Skip to content

fix(runtime): route a CLI close of a paired host's terminal to that host - #29455

Merged
nwparker merged 3 commits into
mainfrom
nwparker/cli-close-routes-paired-host
Oct 16, 2026
Merged

nwparker merged 3 commits into
mainfrom
nwparker/cli-close-routes-paired-host

Conversation

@nwparker

@nwparker nwparker commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 1 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​256 0 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​256
Prod 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​192 $\color{#cf222e}{\Huge{\mathbf{−}}}$​2 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​190

ELI5

On the desktop, orca terminal list also shows terminals that really run on a paired Orca server. Closing one of those with orca terminal close tried to stop the process on the desktop, where it doesn't exist. So the command failed and the process kept running on the server. Now the desktop asks the server that owns the terminal to close it, and reports what that server says.

What Changed

  • Before: orca terminal close --terminal <handle> on a handle whose terminal runs on a paired runtime (executionHostId: runtime:<env> in terminal list) did three things:

    • asked this machine's PTY controller to stop and kill remote:<env>@@<handle>, which it can't own;
    • closed the desktop tab;
    • answered terminal_stop_unverifiable ("a follow-up stop was issued but its outcome could not be verified").

    The server never got a close from the CLI. Agent and CI cleanup scripts failed, and processes leaked on headless servers.

  • After: the desktop sends terminal.close (or terminal.closeTab for --tab) to the owning runtime first, using the host's own handle, which is encoded in the PTY id. The CLI gets that host's receipt: stopped, live, or unverifiable with its reason and pending-kill flag. Then the desktop retires its local mirror. If the owning host can't be reached, the command fails and the terminal stays visible, so you can retry. If the host says it has no such terminal (terminal_not_found), the local mirror is retired, because nothing runs there.

  • Mechanism: a new src/main/runtime/session-tabs/paired-host-terminal-close.ts reads the owner from the PTY id (parseRemoteRuntimePtyId), sends the call, and parses the receipt. The graph-leaf paths of closeTerminal / closeTerminalTab in explicit-terminal-close-stops.ts use it before any local stop. The call reuses the runtime's existing paired-environment transport (callOrchestrationWorkerServer, which already backs federated workers), so no new connection code is added.

Why

The execution host owns the terminal, so only its answer can say whether the process stopped. The alternatives I considered:

  • Making the CLI pick a --host/--environment itself. --environment routing already exists, and that's the route that works when you start from the server's own listing (fix(runtime): a terminal close commits in the session partition that holds the tab #27119 fixed the server side). It doesn't help with a handle the desktop issued, because that handle means nothing on the server.
  • Keeping the old local stop and adding a best-effort host call. That would still report a fabricated verdict.

Failing when the owner is unreachable follows the SSH boundary rule: losing contact is never evidence the process stopped. So nothing is hidden on a guess.

Wire compatibility: this only calls the existing terminal.close / terminal.closeTab methods on the host. Older hosts already answer both.

Linked Issue

Fixes #21339 (Linear STA-7826). Supersedes #21351. That PR only lets --host runtime:<id> pick the paired server for terminal close, which --environment already does. It doesn't route a desktop-issued handle to its owner.

Visual Proof

N/A — this changes what a CLI/RPC close does. There's no UI change.

Testing

src/main/runtime/paired-host-terminal-close.test.ts builds a desktop runtime whose renderer graph has a leaf on runtime:env-1. All five tests fail on origin/main:

  • The host gets terminal.close with its own handle, the CLI gets the host's ptyKilled: true, and the local PTY controller is never asked to stop the remote id.
  • The host's unverifiable verdict, reason, and pendingKillRecorded pass through unchanged.
  • An unreachable host rejects, the tab stays, and nothing local is stopped.
  • terminal_not_found from the host retires the mirror without a verdict.
  • --tab sends terminal.closeTab to the host.

pnpm tc:node and pnpm run check:code-quality:changed pass.

  • I manually tested these changes locally
  • Automated tests added/updated, or explained why not below

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

SSH/remote: this is the paired-host case. Verdicts stay live/unverifiable/exited, taken from the owner. Local and SSH PTYs on this machine are unchanged, because the new path only runs for remote:<env>@@<handle> ids.

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)

orca terminal list on a desktop lists terminals a paired runtime runs, but
orca terminal close on one of those handles stopped the remote PTY id on this
machine, which cannot own it, and answered terminal_stop_unverifiable while
the process kept running on the host. closeTerminal and closeTerminalTab now
send the close to the owning runtime first and return its receipt; when that
host is unreachable the close fails and the terminal stays visible.
@coderabbitai

coderabbitai Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 12 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 6a34747a-6f5d-4ae8-bdef-b61223ad12a6
📥 Commits

Reviewing files that changed from the base of the PR and between da099c3 and 9c1f57e.

📒 Files selected for processing: 4
  • src/main/runtime/paired-host-terminal-close.test.ts
  • src/main/runtime/session-tabs/explicit-terminal-close-stops.ts
  • src/main/runtime/session-tabs/paired-host-terminal-close.ts
  • src/shared/workspace-session-terminal-tab-close.ts
  • 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

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

… the owner's stale-handle answer

Codex review: a pane rebound while the host call was pending had its new
occupant retired, and an owner that no longer knows the handle answers
terminal_handle_stale, which rejected instead of retiring the mirror.
…to close it

Codex review: the renderer's pin guard runs at the local commit, after the host
had already stopped the process.
@nwparker
nwparker merged commit 9b2adf4 into main Oct 16, 2026
33 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Headless server CLI terminal close fails across remote execution host boundary

1 participant