feat(cursor): support cursor-agent binary fallback

[erenaslandev]

---

Review all of them with eye of John Carmack-like simplicity with elegeance approach and apply the one only if required

Greptile Summary

Adds cursor-agent as the preferred binary for Cursor AI with agent as a legacy fallback. The ToolAdapter interface gains an optional binaryFallbacks field, and resume.ts gains resolveToolBinaryName which tries candidates in order and returns the first available one. The fallback logic is clean, well-tested, and fits the registry-driven architecture correctly.

Confidence Score: 5/5

• Safe to merge — the only finding is a cosmetic display mismatch when the legacy fallback binary is in use.
• All remaining findings are P2. Runtime binary resolution is correct; nativeResume, crossToolResume, and getAvailableTools all use the new resolver. Tests cover the primary, fallback, and null cases. The resumeCommandDisplay string mismatch is a minor UX issue that does not affect actual command execution.
• src/parsers/registry.ts — resumeCommandDisplay line 766

Important Files Changed

Filename	Overview
src/utils/resume.ts	Adds getToolBinaryCandidates, resolveToolBinaryName (exported, injectable), and requireToolBinaryName; integrates them into nativeResume, crossToolResume, and getAvailableTools cleanly. Logic is correct and properly uses ToolNotAvailableError.
src/parsers/registry.ts	Adds optional binaryFallbacks field to ToolAdapter interface; changes cursor binaryName from 'agent' to 'cursor-agent' with 'agent' as fallback. resumeCommandDisplay hardcodes 'cursor-agent' regardless of which binary is resolved at runtime.
src/tests/resume-binary.test.ts	New test file covering candidate ordering, primary preference, fallback, and null-return cases for resolveToolBinaryName. Full coverage of the new logic paths.
src/tests/forward-flags.test.ts	Updates existing test to assert binaryName is now 'cursor-agent' and binaryFallbacks is ['agent']. Correct and minimal.

Sequence Diagram

sequenceDiagram
    participant C as CLI (resume/crossToolResume)
    participant R as requireToolBinaryName()
    participant RR as resolveToolBinaryName()
    participant GC as getToolBinaryCandidates()
    participant IA as isBinaryAvailable()

    C->>R: requireToolBinaryName('cursor')
    R->>RR: resolveToolBinaryName('cursor')
    RR->>GC: getToolBinaryCandidates('cursor')
    GC-->>RR: ['cursor-agent', 'agent']
    RR->>IA: isBinaryAvailable('cursor-agent')
    alt cursor-agent found
        IA-->>RR: true
        RR-->>R: 'cursor-agent'
    else cursor-agent missing
        IA-->>RR: false
        RR->>IA: isBinaryAvailable('agent')
        alt agent found
            IA-->>RR: true
            RR-->>R: 'agent'
        else neither found
            IA-->>RR: false
            RR-->>R: null
            R-->>C: throws ToolNotAvailableError
        end
    end
    R-->>C: resolved binaryName
    C->>C: runCommand(binaryName, args, cwd)

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/parsers/registry.ts
Line: 766

Comment:
**`resumeCommandDisplay` out of sync with resolved binary**

This function always returns `cursor-agent --resume ${s.id}`, but at runtime `requireToolBinaryName` may resolve to the `agent` fallback instead. If a user only has the legacy `agent` binary installed, the TUI/help display shows a command they can't actually run. The runtime behavior is correct; the display is not.

```suggestion
  resumeCommandDisplay: (s) => `cursor-agent --resume ${s.id} (or: agent --resume ${s.id})`,
```

Or better: accept that the display reflects the preferred binary and add a note in parentheses, or make `getResumeCommand` in `resume.ts` accept the already-resolved `binaryName` as an argument so it can display what was actually used.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat(cursor): support cursor-agent binar..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}

[devin-ai-integration]

Devin Review found 4 potential issues.

[devin-ai-integration]

📝 Info: getAvailableTools now checks multiple binaries per tool sequentially within parallel checks

The getAvailableTools function at src/utils/resume.ts:317-330 previously called isBinaryAvailable(adapters[name].binaryName) once per tool. Now it calls resolveToolBinaryName(name) which iterates through candidates sequentially (primary + fallbacks). For cursor, this means two which/where spawns instead of one. However, since all tools are wrapped in Promise.allSettled via ALL_TOOLS.map(async ...), cursor's two sequential checks don't block other tools' checks. The performance impact is negligible — at most one extra which call for cursor, running concurrently with all other tool checks.

(Refers to lines 317-322)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

📝 Info: requireToolBinaryName correctly uses typed ToolNotAvailableError

The new requireToolBinaryName function at src/utils/resume.ts:306-312 correctly uses ToolNotAvailableError from src/errors.ts rather than a bare throw new Error(), consistent with the REVIEW.md rule about using typed errors on user-facing paths. This is called from both nativeResume (line 123) and crossToolResume (line 169). Note that the pre-existing throw new Error(...) on lines 122 and 168 (for unknown adapter) remain as bare errors — these are not part of this PR's diff but are worth noting as a pre-existing inconsistency with the project's error conventions.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

📝 Info: Binary resolution adds a latency cost to every resume operation

Before this PR, nativeResume and crossToolResume directly used adapter.binaryName without checking availability. Now they call requireToolBinaryName which spawns which/where subprocess(es) to verify the binary exists before running it. This adds ~50-200ms of latency to every resume operation. For most tools (no fallbacks), it's one which check. For cursor, it could be two. This is a behavioral change — previously the tool would just attempt to spawn and fail with an ENOENT error if unavailable; now it fails early with a friendlier ToolNotAvailableError. The trade-off (slightly slower but better UX) seems intentional.

(Refers to lines 119-124)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

📝 Info: Cursor resumeCommandDisplay always shows both binaries regardless of which is installed

The resumeCommandDisplay at src/parsers/registry.ts:766 always emits cursor-agent --resume ... (or: agent --resume ...) as a static string. Unlike the actual spawn path which dynamically resolves which binary is available via resolveToolBinaryName, the display path doesn't check availability — it's purely informational. This is acceptable for a help/display string, but could be confusing to users who only have one binary installed. The display function is synchronous (resumeCommandDisplay returns string, not Promise<string>), so making it dynamic would require changing the interface signature.

---

Was this helpful? React with 👍 or 👎 to provide feedback.