fix: use plain orca CLI shim for Claude Agent Teams on SSH remotes

[nwparker]

🧑‍🤝‍🧑 Impact & ELI5

1) What's broken today (ELI5). If you connect a project to a remote machine over SSH and pick "Claude Agent Teams" as your agent, then add a new worktree, the agent just fails to start. The remote logs spit out Unsupported SSH Orca CLI command: claude-teams and nothing happens. It's a hard blocker — not a glitch you can work around — but only for a specific group: people running Claude Agent Teams on a Linux machine over SSH. Local users, and people using other agents, are unaffected. (Reported in #6500 on v1.4.101.)

2) What this PR does (ELI5). Orca starts agents by typing a command on the target machine. On a local Linux desktop it deliberately uses the name orca-ide instead of orca, because plain orca would collide with the built-in GNOME "Orca" screen-reader program. The bug was that Orca used that same renamed orca-ide command on remote machines too — but a remote machine only ever has the plain orca command installed, so the renamed one points at nothing. Think of it like mailing a letter to someone's nickname when the post office over there only knows their legal name. This PR teaches Orca to notice "this is a remote SSH machine" and send the plain orca claude-teams command in that case, while still using orca-ide on a real local Linux desktop. So it now sends a command the remote actually recognizes, instead of one it rejects.

3) Tradeoffs / regressions — honest answer. No regressions — nothing is disabled, no new setup, and no existing behavior is lost. The change only fires in exactly one situation: an SSH-remote Linux machine running the one agent (Claude Agent Teams) that uses the platform-specific name. Everything else is byte-for-byte identical: local Linux still gets orca-ide (the screen-reader workaround is preserved and explicitly tested), Windows remotes still get orca.cmd, macOS is untouched, WSL stays on the local path, and any user-defined command override still wins. The one thing reviewers should actually check is breadth, not danger: the fix threads a single isRemote boolean through many launch call sites (worktree reopen, quick-launch, background sessions, the composer, source-control actions, etc.), so the real risk is a missed call site that would leave that path still broken — not a path made worse. No performance cost, no extra API calls, no default changed.

---

Summary

Fixes #6500.

Adding a worktree to an SSH-connected project with Claude Agent Teams selected queued the wrong default agent command: orca-ide claude-teams instead of orca claude-teams. On the remote this fails — the relay prints Unsupported SSH Orca CLI command: claude-teams and the agent never starts.

Root cause: for SSH-connected repos, getAgentLaunchPlatformForRepo returns 'linux'. That platform flows into getTuiAgentLaunchCommand, which for claude-agent-teams picks launchCmdByPlatform.linux = "orca-ide claude-teams". The orca-ide name exists only to avoid shadowing the GNOME Orca screen reader (/usr/bin/orca) on a local Linux desktop install. On an SSH remote there is no such binary: the relay deploys the CLI shim solely as orca (Unix) via buildRemoteCliShim, and only orca-prefixed commands are routed to the relay CLI. So orca-ide claude-teams is not on PATH, and claude-teams is not in the relay's supported command switch (ssh-remote-orca-cli.ts), hitting the default branch that throws the reported error. Windows SSH remotes were already fine because the remote shim is orca.cmd, matching the win32 override.

Fix: thread an isRemote (SSH) flag through launch-command resolution. When isRemote && platform === 'linux', getTuiAgentLaunchCommand skips launchCmdByPlatform.linux and returns the plain launchCmd (orca claude-teams). The win32 orca.cmd override is preserved (the remote Windows shim is also orca.cmd). Callers compute isRemote = Boolean(repo.connectionId) via a small shared repoIsRemote helper — SSH = remote; WSL/local stay false — so all non-SSH behavior is byte-for-byte unchanged. claude-agent-teams is the only agent using launchCmdByPlatform, so the behavior change is scoped to it.

Screenshots

This is a launch-command (string) defect with no standalone visual surface; the verifiable artifact is the queued command. Evidence (run against the live nwparker/fix-6500 dev build over CDP, plus unit tests) is posted as a PR comment. A running-app screenshot is attached in that comment.

Testing

• pnpm lint (ran oxlint on all changed files — clean)
• pnpm typecheck (ran tsgo --noEmit for node + web + cli configs — clean)
• pnpm test (ran the affected vitest files — pass)
• pnpm build
• Added or updated high-quality tests that would catch regressions

Scoped commands actually run:

• oxlint <changed files> — clean
• tsgo --noEmit -p config/tsconfig.node.json / config/tsconfig.tc.web.json / config/tsconfig.tc.cli.json — clean
• vitest run src/shared/tui-agent-startup.test.ts — 33 passed (added remote-Linux, remote-Windows, explicit local-Linux cases)

AI Review Report

Reviewed correctness, edge cases, cross-platform, and security adversarially.

• Cross-platform: No hardcoded path separators or metaKey. The orca-ide (Linux) vs orca.cmd (Windows) vs orca distinction is preserved exactly per platform; only the Linux-remote case changes. Verified the remote Windows shim is orca.cmd (so win32 remote stays correct) and that isRemote derives from connectionId (SSH), keeping WSL and native macOS/Linux/Windows untouched.
• SSH/remote: This is the SSH-specific fix; verified against the relay shim naming (buildRemoteCliShim) and the relay CLI command switch.
• Git providers: Not provider-related.
• Scope check: claude-agent-teams is the only agent with launchCmdByPlatform, so no other agent's command changes. cmdOverrides still win over the platform lookup, so user overrides are unaffected. Resume paths (buildAgentResumeStartupPlan) were intentionally left untouched because claude-agent-teams is not a ResumableTuiAgent.
• Flagged + addressed: extracting seedCommandCodeSubmittedPromptStatus into command-code-prompt-status-seed.ts to keep launch-agent-in-new-tab.ts under the 300-line lint limit without a max-lines disable.

Security Audit

The change only threads a boolean and selects between two pre-existing static command strings (orca claude-teams vs orca-ide claude-teams). No new shell construction, no user-input interpolation, no eval, no network, no filesystem, no secrets, no new dependencies, no IPC surface. repoIsRemote reads repo.connectionId only. No injection surface introduced.

Notes

• All callers that resolve a real SSH-remote launch platform for claude-agent-teams now pass isRemote: worktree reopen, quick-launch new tab, background sessions, the new-workspace composer (incl. quick-create), GitHub work-item background requests, direct work-item launch, source-control AI action plan/preview, folder-workspace composer, and the main-process runtime startup/draft/mobile-session builders.
• Future suggestion (out of scope): getAgentLaunchPlatformForRepo returning a bare platform loses the local-vs-remote-Linux distinction at the type level; a small { platform, isRemote } result type could remove the need to recompute isRemote alongside it at each call site.

Made with Orca 🐋

[coderabbitai]

Warning

Review limit reached

@nwparker, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 27 minutes and 16 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3c9ba606-bc15-41b0-a41b-ed0c90b76a34

📥 Commits

Reviewing files that changed from the base of the PR and between e51b2df and 466435b.

📒 Files selected for processing (18)

• src/main/runtime/orca-runtime.ts
• src/renderer/src/components/right-sidebar/buildSourceControlAgentDeliveryPlan.ts
• src/renderer/src/components/right-sidebar/useSourceControlAgentActionDialog.ts
• src/renderer/src/components/right-sidebar/useSourceControlAgentActionStart.ts
• src/renderer/src/components/sidebar/folder-workspace-composer-submit.ts
• src/renderer/src/hooks/useComposerState.ts
• src/renderer/src/lib/command-code-prompt-status-seed.ts
• src/renderer/src/lib/github-work-item-background-request.ts
• src/renderer/src/lib/launch-agent-background-session.ts
• src/renderer/src/lib/launch-agent-in-new-tab.ts
• src/renderer/src/lib/launch-work-item-direct-agent.ts
• src/renderer/src/lib/launch-work-item-direct.ts
• src/renderer/src/lib/source-control-agent-action-plan.ts
• src/renderer/src/lib/worktree-activation.ts
• src/shared/agent-launch-remote.ts
• src/shared/tui-agent-config.ts
• src/shared/tui-agent-startup.test.ts
• src/shared/tui-agent-startup.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nwparker]

Evidence

Unit tests (vitest run src/shared/tui-agent-startup.test.ts)

Test Files  1 passed (1)
     Tests  33 passed (33)

✓ uses the Linux Orca CLI command for Claude Agent Teams launches        (orca-ide claude-teams — local Linux, unchanged)
✓ uses the plain orca shim for Claude Agent Teams on Linux SSH remotes    (orca claude-teams — THE FIX)
✓ keeps the Windows orca.cmd shim for Claude Agent Teams on SSH remotes   (orca.cmd claude-teams — unchanged)
✓ keeps the Linux orca-ide wrapper for local (non-remote) Claude Agent Teams (orca-ide claude-teams — explicit isRemote:false)

In-app verification (live nwparker/fix-6500 dev build, over CDP)

Attached to the running app instance (devBranch: nwparker/fix-6500, devRepoRoot: /private/tmp/orca-bb/6500) and exercised the shipped renderer launch-plan code directly (not the test harness):

{
  "localLinux":     "orca-ide claude-teams",   // unchanged — GNOME-screen-reader safe
  "sshLinuxRemote": "orca claude-teams",        // THE FIX (was "orca-ide claude-teams")
  "sshWin32Remote": "orca.cmd claude-teams",    // unchanged — remote Windows shim is orca.cmd
  "repoIsRemote_ssh":   true,
  "repoIsRemote_local": false
}

Before/after at the resolver, from the same running app:

{
  "before_fix_remote_linux": "orca-ide claude-teams",   // getTuiAgentLaunchCommand(config, 'linux')
  "after_fix_remote_linux":  "orca claude-teams"         // getTuiAgentLaunchCommand(config, 'linux', { isRemote: true })
}

This confirms: on a Linux SSH remote, the queued default agent command is now orca claude-teams (matches the relay shim name and the supported relay CLI route), instead of the broken orca-ide claude-teams that produced Unsupported SSH Orca CLI command: claude-teams.

Gate

• oxlint on all changed files — clean (extracted a helper to avoid a max-lines disable).
• tsgo --noEmit for tsconfig.node.json, tsconfig.tc.web.json, tsconfig.tc.cli.json — all clean.

Remaining gap

The decisive end-to-end repro (real SSH Linux remote host: connect project, add worktree, watch the relay no longer reject claude-teams) requires a live remote runtime, which isn't available in this validation environment. The above proves the shipped command-resolution behavior in the running app plus the unit regression coverage; the relay-side acceptance path is unchanged by this PR.