Skip to content

refactor(runtime): name the four answers a host probe can give - #21207

Merged
nwparker merged 1 commit into
mainfrom
np/runtime-host-contact-p0
Sep 18, 2026
Merged

nwparker merged 1 commit into
mainfrom
np/runtime-host-contact-p0

Conversation

@nwparker

@nwparker nwparker commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 1 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​239 0 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​239
Prod 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​162 $\color{#cf222e}{\Huge{\mathbf{−}}}$​13 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​149

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.status is still RuntimeStatus | 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 that null on 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:

export type RuntimeHostContact =
  | { verdict: 'live'; status: RuntimeStatus }
  | { verdict: 'unverifiable'; reason: RuntimeHostContactUnverifiableReason; lastAnswer: RuntimeStatus | null }
  | { verdict: 'refused'; lastAnswer: RuntimeStatus | null }
  | { verdict: 'retired'; lastAnswer: RuntimeStatus | null }

with reason distinguishing never-asked / checking / probe-failed / transport-connecting / transport-down, and two accessors that make the split explicit at the call site: lastRuntimeHostAnswer for facts that do not expire (capabilities, platform, runtime id) and liveRuntimeHostStatus for decisions that must not act on a stale fact.

runtimeHostConnectionStateForEntry is 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

refused is 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. retired is the pairing ended by explicit user action. Neither is a synonym for unverifiable, 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 neither refused nor retired may 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.ts carries 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 new refused/retired verdicts 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, or probe-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).
  • Broad regression over src/renderer/src/runtime, src/renderer/src/store/slices, src/renderer/src/components/settings — 706 passed (706) / 6016 passed (6016).
  • pnpm tc exit 0, zero error TS. check:code-quality:changed against main exit 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).

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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

  • New RuntimeHostContact vocabulary — src/shared/runtime-host-contact.ts names the four probe answers (live / unverifiable with a reason / refused / retired) plus two accessors that split "what the host said" (lastRuntimeHostAnswer) from "what it is worth now" (liveRuntimeHostStatus).
  • Connection-state derivation rebased — runtimeHostConnectionStateForEntry now delegates its early branches to runtimeHostContactFromSnapshot. 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 unchanged runtimeHostConnectionState call.
  • Parity suite — the frozen baseline inlines isRuntimeHostContactRevoked as retired || verification === 'blocked', matching the current definition on main, 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 / exited process triple and forbids mapping refused/retired onto 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.

Pullfrog  | View workflow run | Using DeepSeek Flash (free via Pullfrog for OSS) | 𝕏

@coderabbitai

coderabbitai Bot commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: d9ad3945-f375-4bcb-b7df-631bae6aba63

📥 Commits

Reviewing files that changed from the base of the PR and between 96eb97a and b30a3e6.

📒 Files selected for processing (4)
  • docs/reference/ssh-execution-boundary.md
  • src/renderer/src/runtime/runtime-host-connection-state.ts
  • src/renderer/src/runtime/runtime-host-contact-parity.test.ts
  • src/shared/runtime-host-contact.ts

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


📝 Walkthrough

Walkthrough

Adds RuntimeHostContact with live, unverifiable, refused, and retired verdicts. Adds derivation helpers for snapshots and entries. Updates renderer connection-state mapping to use the shared model. Adds exhaustive parity tests and documents that host contact does not determine process liveness.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to b30a3

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)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description explains the problem, implementation, rationale, compatibility goal, tests, and verification results. However, it omits several required template sections or required entries, includin… Add the missing required template sections. Include an explicit Fixes #<issue> entry, state N/A with a reason under Visual Proof if there is no UI or interaction change, complete AI Disclosure as applicable, address Review and Agent ski…
Docstring Coverage ⚠️ Warning 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: … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: naming the four host-probe contact outcomes.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

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 Fixes # linked issue, Visual Proof with N/A and a reason, AI Disclosure, Review, Agent skill upstream boundary, Notes, and the checklist confirmations.

Resolution

Add the missing required template sections. Include an explicit Fixes #&lt;issue&gt; entry, state N/A with a reason under Visual Proof if there is no UI or interaction change, complete AI Disclosure as applicable, address Review and Agent skill upstream boundary, document the requested Notes considerations, and complete the Checklist items.

Full details: Docstring Coverage

Explanation

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.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch

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.

@nwparker
nwparker merged commit a61119c into main Sep 18, 2026
29 checks passed
ivanvykopal pushed a commit to ivanvykopal/orca that referenced this pull request Sep 20, 2026
…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.
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.

1 participant