Repository navigation
refactor(runtime): name the four answers a host probe can give - #21207
Conversation
The renderer expressed every non-answer as one nullable `status`, so a probe in flight, a probe that failed, a host that refused us and a retired pairing all reached readers as the same `null` -- and readers spent that `null` on decisions of very different weight, including destructive ones. `RuntimeHostContact` names the four. Nothing changes yet: the connection-state derivation is rewritten on top of it and a 384-case parity table asserts the result is identical to a frozen copy of the old one on every combination of verification, transport, retired, answered and remote-control state.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
- New
RuntimeHostContactvocabulary —src/shared/runtime-host-contact.tsnames the four probe answers (live/unverifiablewith areason/refused/retired) plus two accessors that split "what the host said" (lastRuntimeHostAnswer) from "what it is worth now" (liveRuntimeHostStatus). - Connection-state derivation rebased —
runtimeHostConnectionStateForEntrynow delegates its early branches toruntimeHostContactFromSnapshot. I traced the arm mapping against the removed code and it is identical: retired/blocked →disconnected, transport-down →reconnecting, checking →checking, probe-failed →runtime-unavailable, and live / transport-connecting / never-asked fall through to the unchangedruntimeHostConnectionStatecall. - Parity suite — the frozen baseline inlines
isRuntimeHostContactRevokedasretired || verification === 'blocked', matching the current definition onmain, so the comparison is against the real prior behaviour rather than a re-derivation. The 384-case cross-product, the length assertion, and the predicate-parity check all hold. - Boundary-doc section — the added text correctly separates host-contact vocabulary from the
live/unverifiable/exitedprocess triple and forbids mappingrefused/retiredonto a process verdict.
Independently verified this run: 33 tests in the two direct suites, 29 in the dependent reader suites, check:code-quality:changed (0 new findings), and audit:anti-slop all pass.
Two non-blocking notes carried forward, not changes requested: runtimeHostContactForEntry is exported but currently unused and untested, and its no-snapshot fallback maps {status:null} to unverifiable/probe-failed while today's runtimeHostConnectionStateForEntry({status:null}) returns disconnected — P1 will need to decide that mapping rather than assume the two entry points agree. Also, the parity enumeration hardcodes the verification/transport tuples, so a future arm added to either union would silently reduce coverage even though toHaveLength(384) still passes.
DeepSeek Flash (free via Pullfrog for OSS) | 𝕏
|
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 (4)
Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review. 📝 WalkthroughWalkthroughAdds Priority: ⬇️ Low Merge Risk: ⚪ Minimal · up to This change introduces a new internal four-state model for describing whether a runtime host has answered, without altering any currently active behavior; the renderer's connection-state output is proven identical to the prior implementation across an exhaustive set of input combinations. There is no evidence of a behavioral regression or production risk from this change as it stands. 🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
Full details: Description checkExplanation The description explains the problem, implementation, rationale, compatibility goal, tests, and verification results. However, it omits several required template sections or required entries, including an explicit Resolution Add the missing required template sections. Include an explicit Full details: Docstring CoverageExplanation Docstring coverage is 70.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: 1 unsupported.)
✨ 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 |
…yai#21207) The renderer expressed every non-answer as one nullable `status`, so a probe in flight, a probe that failed, a host that refused us and a retired pairing all reached readers as the same `null` -- and readers spent that `null` on decisions of very different weight, including destructive ones. `RuntimeHostContact` names the four. Nothing changes yet: the connection-state derivation is rewritten on top of it and a 384-case parity table asserts the result is identical to a frozen copy of the old one on every combination of verification, transport, retired, answered and remote-control state.

P0 of the enforcing fix for the status-verdict family (#20085, #20095, #20096, #20359, #20262). Flat on
main, no stack. Zero behaviour change, and that is asserted rather than argued.The problem this starts on
Those five PRs converted eight read sites that were treating "the probe did not come back" as "the host is gone". They were the right patches at the right sites, and they did not remove the hazard:
entry.statusis stillRuntimeStatus | null, still populated the same way, with no deprecation and no lint rule. Roughly fifteen read sites of the same bug class remain, and nothing stops the next one.The reason is that one nullable field answers two different questions at once — what did the host say and how much is that worth right now — so a probe in flight, a probe that failed, a host that refused us and a retired pairing all arrive at a reader as the same
null. Readers then spend thatnullon decisions of very different weight. One of them was discarding a terminal's only client-side scrollback (#20096).What this PR does
Adds
src/shared/runtime-host-contact.ts, which names the four answers:with
reasondistinguishingnever-asked/checking/probe-failed/transport-connecting/transport-down, and two accessors that make the split explicit at the call site:lastRuntimeHostAnswerfor facts that do not expire (capabilities, platform, runtime id) andliveRuntimeHostStatusfor decisions that must not act on a stale fact.runtimeHostConnectionStateForEntryis rewritten on top of it. That is the only behavioural surface touched, and it is pinned identical.Why four arms and not the boundary doc's three
refusedis the host answering and turning us away — unauthorized, protocol mismatch, a status method it does not implement. That is positive evidence about the connection, and it says nothing about whether the host's PTYs are running; they almost certainly still are.retiredis the pairing ended by explicit user action. Neither is a synonym forunverifiable, and folding them in would recreate the exact collapse this exists to remove.Because that is easy to misread as violating
docs/reference/ssh-execution-boundary.md's no-synonyms rule, this PR adds a section to that document explaining that host-contact vocabulary is a different question from the process-liveness triple, and that neitherrefusednorretiredmay ever be mapped onto a process verdict. Without the note, someone eventually "fixes" it back.How zero-behaviour-change is proven
runtime-host-contact-parity.test.tscarries a frozen copy of the derivation as it read before this change, and asserts the shipping one agrees with it across the full cross-product:4 verification × 4 transport × 2 retired × 2 answered × 6 remote-control states = 384 cases, plus the entries that carry no snapshot at all. Zero disagreements. The suite also asserts the case count, so the enumeration cannot silently collapse and report a vacuous pass.
A third assertion pins
isRuntimeHostContactRevoked(which #20096's parking gates use) against the newrefused/retiredverdicts over the same 384 cases, so the two definitions cannot drift apart while both exist.Mutation-tested. Changing a single arm's mapping —
transport-down→disconnected, orprobe-failed→checking— fails the cross-product; restoring it returns green. A behaviour change would have to survive all 384 cases to go unnoticed.Verification
runtime-host-contact-parity.test.ts+runtime-host-connection-state.test.ts—33 passed (33).src/renderer/src/runtime,src/renderer/src/store/slices,src/renderer/src/components/settings—706 passed (706)/6016 passed (6016).pnpm tcexit 0, zeroerror TS.check:code-quality:changedagainstmainexit 0.What this does NOT do
No reader is converted and no writer stores a contact yet. The contact is derived, so there is no new field, no fixture churn anywhere, and nothing to migrate. Converting the ~15 remaining read sites is P1 and will land in small per-cluster PRs, each making an explicit decision at the site rather than inheriting one from a
null. The worst of those sites is already handled separately in #21188 (terminal-input-host-platform.ts, where a flap silently re-pointed keystroke and path translation at the client's platform).