[Velm14]

ELI5

orca terminal switch --environment <name> should show that terminal in the Orca window on the machine where you ran the command. When the other machine was also running the Orca desktop app, its window jumped to the terminal and yours stayed where it was.

What Changed

• Before: the CLI asked the paired host to navigate first and only tried this machine's desktop when the host answered navigated: false. A headless orca serve always answers false (orca terminal switch --environment <name> does not move the desktop UI to a terminal on a paired remote runtime #24688, fixed by feat(terminal): show a paired server's terminal in this desktop on terminal switch #28023), but a paired desktop app navigates its own window and answers true, so the local reveal never ran ([Bug]: terminal switch --environment doesn't move the local desktop when the paired environment is a desktop app (follow-up to #24688) #31073).
• After: for a paired environment the CLI asks this machine's desktop first (terminal.reveal, same as feat(terminal): show a paired server's terminal in this desktop on terminal switch #28023). If that works, it calls terminal.focus on the host with navigation: 'caller', which resolves the terminal without moving the host's window, and reports navigated: true. Only when no desktop here shows that environment does the host navigate its own window, as before.
• Local terminals are unchanged.

Why

#28023 already said "the desktop on the CLI's own machine is the one to move"; it just decided that from the host's answer, which is the wrong signal once the host has a window. Asking the local desktop first is the direct form of the same rule, and it also stops the other machine's window from jumping for whoever sits at it. caller and host were added together in #9664, so any server that accepts host accepts caller — no mixed-version risk.

Linked Issue

Fixes #31073

Visual Proof

N/A — CLI routing only; the window behaviour is the same reveal #28023 added, now also reached for paired desktops.

Testing

• src/cli/handlers/terminal-switch-paired-reveal.test.ts now covers: the local desktop moves and the host gets navigation: 'caller' for both a windowless server and a paired desktop (both cases fail on main); the host navigates itself when no local desktop shows the environment; local terminals still go straight to the host.

• pnpm test src/cli/handlers src/cli/paired-terminal-desktop-reveal.test.ts — 55 files, 595 tests pass.

• tc:cli, oxlint, oxfmt and check:code-quality:changed pass.

• I couldn't run the two-desktop setup from the issue myself; @luisvae, if you have a minute, a run of the repro from [Bug]: terminal switch --environment doesn't move the local desktop when the paired environment is a desktop app (follow-up to #24688) #31073 on this branch would confirm it.

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

AI Disclosure

Written with Claude Code (Claude Opus 5.5).

Review

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Remote: the host is never asked to move its window when this machine's desktop already showed the terminal, so two people on two machines don't fight over one window.
• Related but separate: e2e: paired-terminal-switch-desktop-reveal intermittently gets navigated:false because the desktop has no repo catalog for the paired host #29817 (the e2e for feat(terminal): show a paired server's terminal in this desktop on terminal switch #28023 sometimes gets navigated: false because the desktop briefly has no repo catalog for the paired host). That is a catalog race, already being looked at, and this PR doesn't change it.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

• Last reviewed commit: e0dcb3b
• Latest commit, not reviewed: f6e696d

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

For remote terminals, the handler attempts to reveal the paired terminal on the local desktop before calling terminal.focus. If the reveal succeeds, it uses caller navigation and marks the result as navigated. Otherwise, it uses host navigation. Local terminals continue to use host navigation. The reveal request now has a 12-second timeout. Tests cover these paths.

Severity of issue fixed: Medium

Merge Risk: Low · previous review e0dcb

Paired terminal switching can be slow when the remote host is resolving a worktree. Bound that preliminary request before merging, or accept the limited navigation delay.

Pre-merge checks: 5

Check name	Status	Explanation
Description check		The description is complete and aligned with the template. It explains the user impact, implementation, rationale, linked issue #31073, testing, visual proof exception, scope, and checklist status.
Title check		The title clearly identifies the CLI terminal-switch change for paired desktops. It is concise and related to the primary change.
Linked Issues check		Issue #31073 requires a paired terminal switch to reveal the terminal in the CLI machine's desktop. terminalFocusHandler calls revealPairedTerminalOnLocalDesktop first for remote clients. When loc…
Out of Scope Changes check		The changes remain within issue #31073. The 12,000 ms timeout bounds the local desktop reveal and supports fallback behavior. The related tests and comments verify the routing. No unrelated change is …
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.

Full details: Linked Issues check

Explanation

Issue #31073 requires a paired terminal switch to reveal the terminal in the CLI machine's desktop. terminalFocusHandler calls revealPairedTerminalOnLocalDesktop first for remote clients. When local reveal succeeds, it calls terminal.focus with navigation: 'caller' and reports navigated: true. When local reveal fails, it uses host navigation. Local terminals still use host navigation. Tests cover both host types, fallback behavior, and local terminals.

Full details: Out of Scope Changes check

Explanation

The changes remain within issue #31073. The 12,000 ms timeout bounds the local desktop reveal and supports fallback behavior. The related tests and comments verify the routing. No unrelated change is shown.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: fa77de59-f886-494a-be23-846bdb218f33

📥 Commits

Reviewing files that changed from the base of the PR and between ad269f4 and 01ef467.

📒 Files selected for processing: 3

• src/cli/handlers/terminal-switch-paired-reveal.test.ts
• src/cli/handlers/terminal.ts
• src/cli/paired-terminal-desktop-reveal.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: a144582c-7535-4842-b44d-28d727b4699f

📥 Commits

Reviewing files that changed from the base of the PR and between 01ef467 and 95f4175.

📒 Files selected for processing: 2

• src/cli/paired-terminal-desktop-reveal.test.ts
• src/cli/paired-terminal-desktop-reveal.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 55366747-e37f-42fc-b409-444e8b4e043a

📥 Commits

Reviewing files that changed from the base of the PR and between 8042bd4 and e0dcb3b.

📒 Files selected for processing: 2

• src/cli/handlers/terminal-switch-paired-reveal.test.ts
• src/cli/handlers/terminal.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[Velm14]

@AmethystLiang ping on this since you're on #31073. Two more people ran into it this week (the comment on #31073 and #38927), so it'd be nice to get it in. The workflows need an approval to run since it's from a fork.

[AmethystLiang]

Thank you @Velm14 . Look into it

[Velm14]

Thanks! Fwiw two more people hit the same thing on #31073 since, and worktree activate and file open --focus have the same root cause, happy to follow up on those after this one.