Repository navigation
fix(ssh): suppress resume after relay replacement - #16839
brennanb2025 wants to merge 2 commits into
Conversation
📝 WalkthroughWalkthroughThe change tracks SSH relay process identities through relay status, PTY spawn and attach responses, PTY results, and persisted leases. Stable-pane adoption compares persisted and current relay identities to produce exited or unverifiable liveness verdicts. Unverifiable absence suppresses agent launch inputs, session claims, launch bookkeeping, telemetry, and launch configuration. Spawn responses report suppressed startup or unavailable resume status. Tests cover identity validation, relay replacement fallback, liveness callbacks, lease persistence, and startup suppression. Merge Risk: 🟡 Moderate · up to The change can suppress normal agent startup for older SSH leases and can carry a stale relay identity across retries, leading to incorrect recovery behavior; the relay ownership check also needs explicit boundary validation. Merge should wait for the two actionable fixes, with security-contract hardening tracked by the owner. 🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
Full details: Description checkExplanation The description provides a detailed summary, user impact, root cause, linked issue, compatibility notes, and verification results. However, it omits the required Visual Proof section and most template checklist sections, including explicit platform coverage and completion status. Resolution Add the required template sections and complete the checklist. Include
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
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: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 2a5a1da5-6822-4b99-8d5c-d9c859c1293e
📒 Files selected for processing (25)
src/main/ipc/pty-pane-reservation-settlement.test.tssrc/main/ipc/pty-relay-age-fallback.test.tssrc/main/ipc/pty/ipc/spawn-commit-persist.tssrc/main/ipc/pty/pane/ssh-relay-absence-verdict.tssrc/main/ipc/pty/pane/stable-owner.tssrc/main/ipc/pty/pane/stable-pane-relay-age-fallback.test.tssrc/main/ipc/pty/pane/stable-pane-types.tssrc/main/ipc/pty/runtime/spawn-commit.tssrc/main/persistence/leasing-ssh-ptys/ssh-normalization.tssrc/main/persistence/leasing-ssh-ptys/ssh-relay-process-id-normalization.test.tssrc/main/providers/pty-spawn-result.tssrc/main/providers/ssh-agent-session-create-operation.tssrc/main/providers/ssh-pty-provider-agent-session-create-operation.test.tssrc/main/providers/ssh-pty-provider-reattach-incarnation.test.tssrc/main/providers/ssh-pty-provider-spawn.test.tssrc/main/providers/ssh-pty-session-reattach.tssrc/main/providers/ssh-pty-spawn-request.tssrc/main/providers/ssh-relay-process-id.tssrc/relay/pty-handler-spawn-admission.test.tssrc/relay/pty-handler-test-harness.tssrc/relay/pty-handler.tssrc/relay/relay-daemon.tssrc/relay/relay-runtime-services.tssrc/relay/subprocess.test.tssrc/shared/ssh-types.ts
Included review availability: Your plan provides up to 10 included reviews per hour; 1 remains after this review.
Exact-head review verification —
|
QA evidence —
|
Decision record: what this PR actually does, and what should outlive itWritten after reading the full diff at 1. The mechanism is a per-relay nonce, not an age comparisonThis is the one place where the "it's a duplicate of #16989" summary is wrong, and it deserves to be on the record.
return status?.relayProcessId === args.bindingRelayProcessId
? { status: 'exited' }
: { status: 'unverifiable', reason: UNPROVEN_RELAY_OWNER_REASON }
That is an identity check. #16989 ( But that does not rescue the approach, because the objection in #16843 was never that the age evidence was imprecise. It was that the predicate itself convicts the safe case:
After a host reboot the relay mints a new UUID. Mismatch → 2. Its failure policy is stricter than #16989's, not looserThis is the part that decides it. The two guards differ in what they do when the evidence is missing:
Two consequences worth naming:
If #16989 is being closed for convicting too much, #16839 convicts a strict superset. Verdict vocabulary: this PR handles it correctly — 3. About a quarter of the diff already shipped on mainThe first bullet of this PR's summary — "treat a reachable relay's that terminal isn't here as typed evidence instead of flattening it into a generic session-expired error" — landed on main in #16763 (
Four of the six merge conflicts are exactly those files ( So "+1151 / −140 across 40 files" overstates the unique surface. Netting out the #16763 overlap, the genuinely new content is: the nonce transport and persistence (~11 files), the verdict + suppression plumbing (~15 files), and 10 test files (+743). Nothing in it is off-topic for STA-5698 — there is no incidental fix in here worth keeping for its own sake, and the 4. What is genuinely worth salvaging#16843's close said the renderer half "is not lost work; it is the correct outcome if a guard is ever justified." That is right, and this PR's version of it is materially better than #16989's — that is the real asset here, and it is independent of which guard (if any) ever ships. #16989 strips intent at the provider spawn-options layer only (
Two of those gaps in #16989 are substantive, not cosmetic. Under #16989 the pane still gets a published launch config, so it is still an agent pane holding resume intent; and #16989 leaves if (absenceVerdict.status === 'unverifiable') {
runtime?.markPtyLivenessUnverifiable(owner.ptyId, absenceVerdict.reason)
runtime?.onPtyExit(owner.ptyId, -1, owner.incarnationId)
} else {
runtime?.onPtyExit(owner.ptyId, 0, owner.incarnationId)
}
clearProviderPtyState(owner.ptyId, {
preserveAgentSessionOwners: absenceVerdict.status === 'unverifiable'
})One thing to carry the other way: The second salvage is the scaffolding, not the nonce. #16843 said that if prevention proves insufficient, "the mechanism to build is a pid + start-time probe, which Orca already implements for its local daemon." The plumbing this PR builds — an optional per-relay stamp on Nothing here helps #16894 / #16895; the host-side prevention work shares no surface with this PR. 5. Recommendation: salvage, then close as supersededSuperseded by #16901 (mint PTY ids carrying the relay incarnation, so a stale id can never resolve to a different live process) plus the host-side prevention pair #16894 / #16895 — prevent the orphan and remove the ambiguity, rather than detect the collision on the client. This PR does not clear the bar #16843 was closed against, and its failure policy is stricter than #16989's, which is itself recommended for closure. One thing that argues the other way, on the recordThe "three PRs remove both ingredients" framing is not quite complete, and it should be visible to whoever revisits this:
So the residual risk is real but narrow: a relay on a Windows SSH host killed by something other than an uncaught exception. On POSIX, the live repro showed the pty master closing and SIGHUP reaping the shell and agent in 0.3s — no orphan to collide with. That residual is an argument for revisiting a guard later, on the pid + start-time mechanism #16843 named, using the scaffolding above. It is not an argument for merging a fail-closed nonce guard that would cost every SSH user their agent resume after any host reboot, any un-upgraded relay, and any 5-second network hiccup on reconnect — to cover a case that only arises on Windows hosts once #16895 is made to actually work. |
|
SSH still works: Orca connects to the host over SSH and routes workspace operations through the managed remote Orca server (orcad). These merges remove the legacy SSH relay, not SSH support. Closing as obsolete after the merged SSH relay retirement in #27214 and #27215. This PR concerns the SSH relay PTY attach, recovery, replay, or lease lifecycle. #27214 removed the desktop relay connection/fallback path; #27215 deleted the SSH relay server, deployment assets, and relay-only tests. SSH hosts now use the managed Orca server (orcad), and unsupported hosts fail explicitly, so this relay-specific work is no longer planned. This closes the proposed relay implementation; it does not claim that any independent local, WSL, or managed-server behavior was fixed. |
|
Thanks @brennanb2025 — the relay itself is gone, but the idea behind this (don't auto-resume an agent when the host's "terminal not found" was never observed as a real exit) still applies to managed hosts and paired runtimes. I've captured it on #13716 with credit to this PR; this one stays closed since its mechanism was relay-specific. |

Summary
exited) only when the answering relay is the exact instance that owned the binding — any other answer (replacement relay, older relay with no identity, malformed or failed status) degrades tounverifiable, neverexitedunverifiable, retire the unusable binding but start a plain shell with no agent launch authority, launch metadata, claim, or telemetry, and surface the existing resume-unavailable bannerWhat this means for users (ELI5)
Orca keeps a small helper process — the relay — running on your SSH host. It owns the terminal processes for your remote workspace, and Orca reconnects to it whenever you come back.
Before this fix. You reopen an SSH workspace whose relay was replaced while you were away — an Orca update restarted it, the host rebooted, or host-side cleanup swapped it out. The replacement relay truthfully answers "I don't have that terminal", but it isn't the relay that was holding your terminal, so it cannot actually know what happened to the process. Orca took that answer as proof your agent had exited: it marked the pane as a clean exit and automatically re-ran the original agent launch/resume command in a fresh terminal. If the old process was in fact still alive on the host, you now had a second agent silently resuming into the same session — duplicate work, contested session state, and agent-launch claims and telemetry for a launch you never asked for.
After this fix. Orca checks who is answering before believing "it's gone". If the same relay that owned your terminal says the terminal is gone, that is authoritative and nothing changes: normal exit handling, resume works as before. If a replacement relay answers, Orca refuses to guess: the pane opens as a plain shell — no automatic agent relaunch, no session claim, no launch telemetry — with the existing "resume unavailable" banner, so you decide what to run next. Nothing is silently resumed on an answer that could not prove anything.
When you'd hit it: reconnecting to an SSH workspace after its relay restarted — typically after an Orca upgrade, a host reboot, or host-side cleanup — while a persisted terminal binding for that workspace still exists.
Root cause
The stable-pane fallback replayed the original
launchAgent/ resume command after a reachable SSH relay answered that the persisted PTY was absent. It did not distinguish the relay instance that owned the binding — and could authoritatively prove process exit — from a younger replacement relay that could never have observed the bound process.Remote wire compatibility
The relay mints its process identity at startup and reports it in
relay.status, and — only when the client asks via a new optionalrequestRelayProcessIdrequest field — in spawn/attach results; the client persists it on the SSH PTY lease as a new optional field. These are additive optional fields on existing RPCs: no new stream opcode, no removed field. An older host simply omits the identity, so the client classifies its positive absence asunverifiableand takes the conservative plain-shell path instead of the old replay — a deliberate behavior change, since such a host cannot prove ownership. An older client never requests the identity and keeps its prior behavior.Verification
absenceVerdictwas absentpnpm testacross 7 focused/adjacent files: 38 passedpnpm tcandpnpm tc:nodegit diff --checkScope note
This focused PR is based directly on
main. It overlaps the relay-age fallback area in draft PR #16763, but it does not stack on, retarget, close, or modify that PR.Closes STA-5698.