Repository navigation
Conversation
…etired A paired client that wakes replays connect() for every mirrored pane whose host PTY is gone: terminal.resolvePane answers terminal_not_found, and the fall-through legacy terminal.create carries the pane's original tabId/leafId as a hint with no command. canAdoptPaneIdentity only checked the hint's *format*, so the host adopted the id and spawned a fresh shell under a tab its own user had closed — 12 tabs came back with identical ids on every wake, 9x in a day (stablyai#21341). terminal.create now resolves its pane identity through resolveHintedTerminalPaneIdentity, which refuses a hint naming a pane this host retired. Refusal rather than a fresh id: a fresh id still spawns the shell, which is the user-visible bug. The host had no pane-keyed retirement record to consult. `terminalSurfaceTombstonesByPaneKey` is legacy — `recordTerminalSurfaceRetirement` only ever deletes from it and `sanitizeWorkspaceSessionTerminalRetirements` clears the map on every full session write — `terminalTopologyRevisionByRepoId` is per-repo, and `closedTerminalTabTombstonesByTabId` is a client breadcrumb written only for direct-SSH worktrees. The session-tab snapshot's retirement proofs are pane-keyed but carry a terminal handle, so a pane the host user created in the desktop renderer and no client addressed by handle publishes none — which is exactly the reported topology. So `retireMobileSessionSurfacesForPty`, the single funnel a permanent PTY exit reaches, now also records the pane in a bounded in-memory RetiredTerminalPaneLedger. No published content changes. Both halves of the evidence are required to refuse. The ledger alone also covers a shell that exited under a tab the user kept open, and that pane must still restart in place once the host republishes it; absence alone cannot tell a retired pane from a client-minted id the host has never seen, which is the normal shape of a paired client's first create. The error is `tab_not_found`, which the client already treats as definitive surface absence: mapRuntimeError sends it as {code: runtime_error, message: tab_not_found}, isRecoverableRemoteRuntimeConnectionError rejects that, so createWithUnknownOutcomeRecovery rethrows on the first attempt and connect()'s catch surfaces it without arming a retry. No client change needed.
…showing the raw token Review follow-up to the retired-pane create gate. connect()'s catch only settled for isRemoteTerminalGoneMessage, so the host's own `tab_not_found` — positive evidence that the pane it is being asked to recreate is retired — fell into the generic else and surfaced the token as a pane error. It now retires the remote terminal id, the same settle the gone branch reaches through handleRemoteTerminalError. isRemoteTerminalGoneMessage is deliberately left alone: handleRemoteTerminalError also classifies the subscribe/resubscribe path, where the same token must stay re-resolvable rather than fatal. The gate's doc comment claimed every client settles; corrected to say what holds on both sides of the skew — no client retries, an updated one settles the pane as absent, an older one surfaces the token. Also drops publishesLiveSurface, which duplicated the inherited mobileSessionSnapshotHasSurface. The gate takes an isSurfacePublished predicate now, so it no longer restates how a published terminal surface is recognised.
…pane id Review follow-up. Six findings from the independent review of this branch. The ledger recorded every permanent PTY exit, so a shell the user ended with `exit` under a tab they kept open was recorded too. On a desktop host the renderer republishes that surface and the liveness half lets the pane restart in place, but on a headless host nothing republishes it — the pane's Restart, which is a terminal.create carrying the same tabId/leafId, was refused. The ledger now records only when onPtyExit resolved the exit as an operator close. That cause is already computed there from stopRequestedPtyIds, and the bug case still records: `pty:kill`, which renderer-kill.ts documents as "the route the renderer takes when the user closes a terminal tab", marks the stop before the exit lands. Also: - a pane adopted from its hint forgets its retirement, so a later transient snapshot absence cannot refuse a pane the host is publishing; - the ledger is an insertion-ordered set — its timestamp was never read — and its bound goes to 4096, which is a host-wide figure now that natural churn no longer reaches it and operator closes and worker releases are all it has to outlive; - the client settles the pane visibly. On a fresh connect there is no pty id for retireRemoteTerminalId to notify, so the refusal left the pane blank with no overlay; it now publishes the same onExit/onDisconnect pair the stream's own end handler does. The test asserts the settle rather than only the absence of a toast; - the new catch branch reuses isMissingHostSessionSurfaceError, the classifier this file already has for exactly this pair of tokens. Not done, deliberately: capability-gating the refusal. A host-only fix exists to protect a host whose paired client has not updated, and gating it to capable clients would re-enable the resurrection for precisely the clients that cause it. An old client gets the existing non-recoverable error path, on a pane that was already closed, with no retry.
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (16)
🚧 Files skipped from review as they are similar to previous changes (5)
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review. 📝 WalkthroughWalkthroughThe runtime now tracks deliberately retired terminal pane identities in a bounded in-memory ledger. Terminal creation validates hinted identities against retirement state and published surfaces. PTY stop handling distinguishes reversible stops from permanent exits. The renderer settles Priority: ➖ Normal Merge Risk: ⚪ Minimal · up to Closed panes are rejected on replay while sleeping or hibernated panes remain recoverable; the current change has no evidenced merge-blocking risk. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: 96a77a0f-fe12-4d48-9649-8c2cd2fd7a4e
📒 Files selected for processing (11)
src/main/runtime/orca-runtime-create-terminal.tssrc/main/runtime/orca-runtime-on-pty-exit.tssrc/main/runtime/orca-runtime-persist-terminal-surface-retirements.tssrc/main/runtime/orca-runtime-runtime-id.tssrc/main/runtime/orca-runtime-tests/terminal-create-retired-pane-hint.spec.tssrc/main/runtime/orca-runtime.test.tssrc/main/runtime/retired-terminal-pane-hint-gate.test.tssrc/main/runtime/retired-terminal-pane-hint-gate.tssrc/main/runtime/retired-terminal-pane-ledger.tssrc/renderer/src/components/terminal-pane/remote-runtime-pty-transport-host-absence-evidence.test.tssrc/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.
There was a problem hiding this comment.
Important
The retirement ledger keys on every operator_close exit, which includes reversible parks — worktree sleep (terminal.sleep) and the pty:kill+keepHistory hibernation fallback. Their retirement already drops the surface from the mobile session snapshot, so a paired client replaying terminal.create with the pane's own ids after a wake is now refused instead of resumed. Inline comment with the mechanism and an open question.
Reviewed changes
- Retirement ledger (
retired-terminal-pane-ledger.ts): in-memory, insertion-ordered, pane-keyed set bounded at 4096, written at the single permanent-exit funnel. - Hint gate (
retired-terminal-pane-hint-gate.ts):resolveHintedTerminalPaneIdentityreplaces the old format-only adoption inorca-runtime-create-terminal.ts, refusing a retired-and-unpublished hint withtab_not_foundand forgetting the retirement on adoption. - Ledger write site (
orca-runtime-persist-terminal-surface-retirements.ts): records onlyisDeliberateTerminalExitexits, before the handle-keyed proofs, withonPtyExitthreading the cause through. - Client settle (
remote-runtime-pty-transport.ts):connect()'s catch first-matchesisMissingHostSessionSurfaceErrorand settles the pane (retireRemoteTerminalId+onExit(0)/onDisconnect) instead of surfacing the raw token. - Tests: integration spec through the real retirement path, gate unit tests, and a transport settle test.
The server-side gate itself reads cleanly, the red-check tests can fail when the gate is disabled, and the client reconciliation was verified safe: no reachable terminal_not_found occurs inside connect()'s try-block, and the only tab_not_found source is the new gate.
ℹ️ Nitpicks
- The PR body's Notes section says "Bound: 512 ledger records per host process", but
MAX_RETIRED_TERMINAL_PANE_RECORDSis4096. Worth correcting so the description doesn't mislead. - The new first-match on
isMissingHostSessionSurfaceErrordepends onwaitForHostSessionHandleswallowing the sametab_not_foundfromsession.tabs.activate; a one-line note in the catch that this ordering is load-bearing would protect it against a refactor.
DeepSeek Flash (free via Pullfrog for OSS) | 𝕏
… ledger Worktree sleep and pane hibernation stop the PTY through the same calls an ordinary close takes, so their exits were recorded as retirements and the wake that replays the pane's own tabId/leafId was refused — the terminal the user slept came back as an error instead. A stop is now marked reversible at the two callers that mean to undo it, and only an irreversible one records. The exit cause is unchanged; only the ledger write is narrowed. The create's hint gate also cleared a retirement before the shell was spawned, so a spawn that then failed left the pane unprotected and the next replay of the same hint was adopted. Clearing now happens in registerPty, where a PTY is actually bound to the pane.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed commit 2835d0b (delta against the prior pullfrog review at d597bec), which makes the retirement ledger ignore stops the caller means to undo. No new critical or must-address findings; the prior thread is resolved.
- Reversible stop intent (
orca-runtime-mark-pty-liveness-unverifiable.ts):markPtyStopRequestednow takes{ reversible }, tracked inreversibleStopRequestedPtyIds; a later irreversible request over the same PTY clears the marker, so the caller giving the pane up for good wins. - Park paths mark reversible (
kill.ts,renderer-kill.ts):stopAndWaitPtyFromRuntimeControllerandpty:killpassreversible: opts.keepHistory === true, covering worktree sleep (stopAndWait+keepHistory) and pane hibernation (pty:kill+keepHistory,terminal.stopExact). - Ledger write gate (
orca-runtime-persist-terminal-surface-retirements.ts):onPtyExitcaptures the flag before clearing the sets and threads it through; only an irreversible deliberate close records. - Forget moves to registration (
orca-runtime-register-pty.ts): the gate no longer clears the ledger on adoption, so a spawn that fails after the gate leaves the retirement in place; only a bound PTY forgets it. - Tests: reversible-stop adoption, irreversible-after-reversible refusal, late spawn-failure retention,
registerPtyforget, andpty:killkeepHistorymarking reversible.
The prior review's reversible-park concern is fully addressed, and both earlier nitpicks are handled (PR body now says 4096; the load-bearing-order comment was added to the connect() catch).
ℹ️ SSH synthetic-then-real exit re-marks the stop irreversible
The author flagged this as a deliberately-open door: on an SSH-owned PTY, bind-listeners.ts:96 re-marks markPtyStopRequested(payload.id) without reversible when a duplicate real provider exit follows a synthetic one. Since the ledger gate now keys off that flag, a park can still record a retirement in the narrow window where the first (reversible) retirement was not accepted by persistence and a real exit then arrives. Closing it means carrying reversible through rememberSyntheticKillExit/consumeSyntheticKillExit, which is a reasonable follow-up rather than a change required here — the preconditions (SSH host, missed provider exit, transient store-write failure, in-window duplicate) are narrow and no e2e exercises the park-then-recreate path either way.
DeepSeek Flash (free via Pullfrog for OSS) | 𝕏
|
Closing this PR. No replacement PR is open yet; this closes the proposal, not the underlying issue (#21341). Since this PR was opened, main has gained durable closed-tab records for terminals: they are written by the close transaction, kept per host partition, and stored in SQLite. An alternative that refuses a replayed What that local draft changes compared with this PR:
Natural exits and stops without a tab close still adopt the hint; what should happen there stays an open question. |

ELI5
When a paired desktop client goes to sleep and wakes up, it tries to reconnect every terminal pane it remembers. If the host user had already closed some of those terminals, the host still let the client recreate them under the very same tab ids, so a dozen closed terminals could reappear on every wake. The host now remembers which panes it retired and says "that tab is gone" instead of spawning a new shell under it.
What Changed
Before: Host on Mac A hosts a worktree; Mac B is paired to it and holds 12 terminal tabs mirrored from A. The host user closes the 12 tabs (PTYs are killed). Mac B wakes from sleep and replays
connect()for each remembered pane; the host answersterminal_not_found, and the client falls through to the legacyterminal.createcall carrying the pane's originaltabId/leafIdas a hint and no command. The host adopted the hint on id format alone and spawned a fresh shell under each closed tab. Observed 9 times in one day on a live host; the tab ids were identical each time.After: the host keeps a bounded, in-memory, pane-keyed ledger of terminal surfaces it retired, written at the single funnel every permanent PTY exit reaches (
retireMobileSessionSurfacesForPty).terminal.createresolves its pane identity throughresolveHintedTerminalPaneIdentity, which refuses a hint that (a) names a pane in that ledger and (b) the host does not currently publish as a live terminal surface. The refusal istab_not_found, which the client already treats as definitive absence. An updated client settles the pane quietly; an older client shows the token as a pane error and does not retry. Neither spawns a shell.The ledger records only exits the host resolved as an operator close (
stopRequestedPtyIds→OPERATOR_CLOSE_EXIT_CAUSE, which the renderer'spty:killtab-close route marks). A shell the user ended withexitunder a tab they kept open is not recorded, so its Restart in place still works on a headless host where nothing republishes the surface. A pane adopted from its hint forgets its retirement.Review follow-ups folded in (commits 2 and 3): the client's
connect()catch settles the pane on the host's surface-absence tokens (reusingisMissingHostSessionSurfaceError) and publishes the sameonExit/onDisconnectpair the stream's end handler does, so a refused recreate shows the exit overlay instead of a blank pane or a raw error; the gate reuses the inheritedmobileSessionSnapshotHasSurfacepredicate; the ledger is an insertion-ordered set bounded at 4096.Commit 4: a stop the caller means to undo (worktree sleep, pane hibernation, both already passing
keepHistory) is marked reversible, and only an irreversible stop records into the ledger, so a slept pane's wake replay is still adopted. The exit cause is unchanged. The ledger entry is now cleared inregisterPty, where a PTY actually binds to the pane, instead of at the create's hint gate, so a spawn that fails after the gate leaves the retirement in place.Why
Both halves of the evidence are required. The ledger alone would also refuse a shell that exited under a tab the user kept open, and that pane must still restart in place once the host republishes it. Absence alone cannot tell a retired pane from a client-minted id the host has never seen, which is the normal shape of a paired client's first create.
Refusing rather than minting a fresh id: a fresh id still spawns the shell, which is the user-visible bug.
Why a new ledger instead of existing state:
terminalSurfaceTombstonesByPaneKeyis legacy (only ever deleted from, and cleared on every full session write);terminalTopologyRevisionByRepoIdis per-repo with no pane identity; the session-tab snapshot's retirement proofs are keyed by a terminal handle, and a pane the host user created in the desktop renderer that no client ever addressed by handle publishes none, which is exactly the reported topology. The ledger changes nothing the host publishes, so there is no wire change; it is the host-only half of the fix and protects a host whose paired client has not updated.This complements the client-hydration fix being worked on for #21341; it does not replace it. Known gaps, on purpose: a host restart empties the ledger, so a client that re-injects after a host restart is not covered here (persisting it needs a
WorkspaceSessionStateschema field and is a follow-up). A close whose kill was never confirmed (stop_unverified, SSH-owned PTYs) does not record either; that branch keeps the surface addressable rather than retiring it, perdocs/reference/ssh-execution-boundary.md, so there is nothing for the ledger to refuse against. Not capability-gated: a host-only fix exists to protect a host whose paired client has not updated, and gating it to capable clients would re-enable the resurrection for precisely the clients that cause it.Linked Issue
Addresses the host side of #21341 (see my comment there for the Mac ↔ Mac trace). Not marked as closing it, since the client-side hydration fix is in progress separately.
Visual Proof
N/A. No UI change; the observable change is that closed terminals stop reappearing on a paired client's wake, and a refused recreate no longer shows a raw error toast on an updated client.
Testing
Automated:
src/main/runtime/orca-runtime-tests/terminal-create-retired-pane-hint.spec.ts(integration through the real retirement path): retired pane hint →tab_not_found, no spawn; renderer-created pane (the reported topology, viasyncWindowGraph) → same; no-hint create unchanged; hint without retirement adopts; split leaf under a live tab adopts.src/main/runtime/retired-terminal-pane-hint-gate.test.ts: gate composition (republished surface is not refused), pane-key scoping, malformed hints, ledger bound.remote-runtime-pty-transport-host-absence-evidence.test.ts:terminal.createrejecting withtab_not_foundsettles the pane with exactly one create, no retry, no error surfaced.Runs:
pnpm tc:node,pnpm tc:web,pnpm test src/main/runtime,pnpm test src/renderer/src/components/terminal-pane,pnpm test src/renderer/src/runtime,pnpm run check:code-quality:changed,tests/e2e/cross-version-wire— all green. One pre-existing failure inagent-session-process-identity-probe.test.tsreproduces on a clean main checkout and is unrelated.Platforms: developed and unit/integration tested on macOS. The originating repro was a macOS ↔ macOS pairing over Tailscale; I have not yet re-run the live sleep/wake repro against this branch, so the live confirmation is still pending.
AI Disclosure
Investigated and implemented with Claude Code (Claude Fable 5.1 orchestrating, Claude Opus 5 for the implementation pass). Log analysis, root-cause trace and the review of every commit were done by me with the model; all tests were run locally.
Review
Independent review points already addressed in the second commit: client settle on
tab_not_found(scoped to the create path's catch, not the subscribe classifier), and reuse of the existing published-surface predicate.Agent skill upstream boundary
docs/reference/agent-skill-sharing-upstream-boundary.mdand copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.Notes
preservesAbnormalSshSurfacebranch that keeps a HUB-owned pane addressable through reconnect grace does not write it, so an SSH relay drop is not treated as retirement.terminal.createwhose hint names a retired pane; the current client classifies that as non-recoverable and does not retry (verified inremote-runtime-client-error-classification.tsandcreateWithUnknownOutcomeRecovery).Checklist
N/Awith reasonpnpm lint,pnpm typecheck,pnpm test, andpnpm buildpass (or CI will cover; local preferred)