diff --git a/docs/reference/ssh-execution-boundary.md b/docs/reference/ssh-execution-boundary.md index 88a4a3c0a0ee..a113a5e6f29c 100644 --- a/docs/reference/ssh-execution-boundary.md +++ b/docs/reference/ssh-execution-boundary.md @@ -72,6 +72,33 @@ A verdict needs evidence from the host that owns the process. Apply these tests Anything short of positive host evidence is `unverifiable`. Reporting it as `exited` is the error this document exists to prevent: it orphans live work and can cold-start a duplicate over the same worktree. +## Host contact is a different question from process liveness + +The `live` / `unverifiable` / `exited` triple above answers one question: is this PTY running. It has +no synonyms, and nothing below adds any. + +A second, narrower question — can we currently reach the host at all, and what is its last answer +worth — is answered by `RuntimeHostContact` (`src/shared/runtime-host-contact.ts`), whose arms are +`live` / `unverifiable` / `refused` / `retired`. These are **not** extra process verdicts and must +never be mapped onto one: + +- `refused` is the host answering and turning us away — unauthorized, a protocol mismatch, a status + method it does not implement. That is positive evidence about the *connection*, and it says + nothing whatever about whether the host's PTYs are running. They almost certainly still are. +- `retired` is the pairing being ended by explicit user action. Same point: the client stops having + a route, the remote work is unaffected. + +Both are reasons to stop *trusting a cached answer*, never reasons to report a process `exited`. A +reader that needs a process verdict must still get it from the host that owns the process, by the +tests above. + +Why the extra arms exist at all: the renderer previously 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. Folding `refused` and `retired` back into +`unverifiable` to match this document's triple would recreate exactly that collapse. The vocabularies +are deliberately separate because the questions are. + ## Deciding a remote pane is idle The orphan-PTY sweep is the one flow that turns an observation into a SIGKILL, so its idleness evidence has to be measured against the same thing the signal reaches. It is not the terminal. diff --git a/src/renderer/src/runtime/runtime-host-connection-state.ts b/src/renderer/src/runtime/runtime-host-connection-state.ts index 21e386857e95..4e5b99b916a7 100644 --- a/src/renderer/src/runtime/runtime-host-connection-state.ts +++ b/src/renderer/src/runtime/runtime-host-connection-state.ts @@ -1,7 +1,5 @@ -import { - isRuntimeHostContactRevoked, - type RuntimeHostStatusSnapshot -} from '../../../shared/runtime-host-status' +import { runtimeHostContactFromSnapshot } from '../../../shared/runtime-host-contact' +import type { RuntimeHostStatusSnapshot } from '../../../shared/runtime-host-status' import type { RuntimeStatus } from '../../../shared/runtime-types' import { isRuntimeWorkspaceWindowClosed } from '../../../shared/runtime-workspace-window-availability' @@ -123,17 +121,23 @@ export function runtimeHostConnectionStateForEntry( ): RuntimeHostConnectionState { const snapshot = entry?.snapshot if (snapshot) { - if (isRuntimeHostContactRevoked(entry)) { + // Why the contact and not the snapshot fields: these four branches were the only place that + // knew a non-verified probe has kinds, and every other reader had to re-derive them or guess. + // Naming them once means the next reader picks an arm instead of re-reading a null. + const contact = runtimeHostContactFromSnapshot(snapshot, entry?.status ?? null) + if (contact.verdict === 'retired' || contact.verdict === 'refused') { return 'disconnected' } - if (snapshot.transport === 'disconnected') { - return 'reconnecting' - } - if (snapshot.verification === 'checking' && !entry?.status) { - return 'checking' - } - if (snapshot.transport === 'ready' && snapshot.verification !== 'verified') { - return 'runtime-unavailable' + if (contact.verdict === 'unverifiable') { + if (contact.reason === 'transport-down') { + return 'reconnecting' + } + if (contact.reason === 'checking') { + return 'checking' + } + if (contact.reason === 'probe-failed') { + return 'runtime-unavailable' + } } } return runtimeHostConnectionState({ diff --git a/src/renderer/src/runtime/runtime-host-contact-parity.test.ts b/src/renderer/src/runtime/runtime-host-contact-parity.test.ts new file mode 100644 index 000000000000..a24e963a1d97 --- /dev/null +++ b/src/renderer/src/runtime/runtime-host-contact-parity.test.ts @@ -0,0 +1,239 @@ +import { describe, expect, it } from 'vitest' +import { + isRuntimeHostContactRevoked, + type RuntimeHostStatusSnapshot +} from '../../../shared/runtime-host-status' +import { + isRuntimeHostContactRevokedVerdict, + lastRuntimeHostAnswer, + liveRuntimeHostStatus, + runtimeHostContactFromSnapshot +} from '../../../shared/runtime-host-contact' +import type { RuntimeStatus } from '../../../shared/runtime-types' +import { + runtimeHostConnectionState, + runtimeHostConnectionStateForEntry, + type RuntimeHostConnectionState +} from './runtime-host-connection-state' + +// This file exists to prove the contact introduced here changes nothing. It carries a frozen copy +// of the derivation as it stood before, and asserts the shipping one agrees with it on every +// combination of the inputs it reads. A behaviour change would have to survive the whole +// cross-product to go unnoticed, which is a much harder thing to do by accident than to argue. + +type Entry = { + status: RuntimeStatus | null + remoteControl?: RuntimeStatus['remoteControl'] | null + snapshot?: RuntimeHostStatusSnapshot +} + +/** The derivation exactly as it read before `RuntimeHostContact` existed. Do not refactor. */ +function legacyRuntimeHostConnectionStateForEntry( + entry: Entry | null | undefined +): RuntimeHostConnectionState { + const snapshot = entry?.snapshot + if (snapshot) { + if (snapshot.retired || snapshot.verification === 'blocked') { + return 'disconnected' + } + if (snapshot.transport === 'disconnected') { + return 'reconnecting' + } + if (snapshot.verification === 'checking' && !entry?.status) { + return 'checking' + } + if (snapshot.transport === 'ready' && snapshot.verification !== 'verified') { + return 'runtime-unavailable' + } + } + return runtimeHostConnectionState({ + hasStatusEntry: Boolean(entry), + status: entry?.status ?? null, + ...(snapshot?.transport === 'connecting' ? { transportStatus: 'checking' as const } : {}), + remoteControl: entry?.remoteControl ?? entry?.status?.remoteControl ?? null + }) +} + +const VERIFICATIONS = ['checking', 'verified', 'unavailable', 'blocked'] as const +const TRANSPORTS = ['unknown', 'connecting', 'ready', 'disconnected'] as const +const RETIRED = [false, true] as const +const REMOTE_CONTROL_STATES = [ + undefined, + 'ready', + 'awaiting_ready', + 'awaiting_authenticated', + 'reconnecting', + 'closed' +] as const + +function makeStatus(overrides: Partial = {}): RuntimeStatus { + return { + runtimeId: 'rt-1', + rendererGraphEpoch: 0, + graphStatus: 'ready', + authoritativeWindowId: 1, + liveTabCount: 0, + liveLeafCount: 0, + ...overrides + } +} + +function makeRemoteControl( + state: Exclude<(typeof REMOTE_CONTROL_STATES)[number], undefined> +): NonNullable { + return { + state, + pendingRequestCount: 0, + subscriptionCount: 0, + reconnectAttempt: 0, + lastConnectedAt: null, + lastClose: null, + lastError: null + } +} + +function makeSnapshot( + verification: (typeof VERIFICATIONS)[number], + transport: (typeof TRANSPORTS)[number], + retired: boolean, + answered: RuntimeStatus | null +): RuntimeHostStatusSnapshot { + return { + environmentId: 'env-a', + pairingRevision: 1, + sequence: 1, + checkedAt: 1, + status: answered, + verification, + transport, + ...(retired ? { retired: true as const } : {}) + } +} + +/** Every entry shape the derivation can distinguish: 4 x 4 x 2, across each status/diagnostic. */ +function* everySnapshotEntry(): Generator<{ label: string; entry: Entry }> { + for (const verification of VERIFICATIONS) { + for (const transport of TRANSPORTS) { + for (const retired of RETIRED) { + for (const answered of [null, makeStatus()] as const) { + for (const remoteControlState of REMOTE_CONTROL_STATES) { + // The store nulls `status` for anything but a verified, unretired probe, so the two + // reachable pairings are the ones enumerated here rather than a free cross-product. + const entryStatus = verification === 'verified' && !retired ? answered : null + const remoteControl = remoteControlState + ? makeRemoteControl(remoteControlState) + : undefined + yield { + label: `${verification}/${transport}/retired=${retired}/answered=${answered !== null}/rc=${remoteControlState ?? 'none'}`, + entry: { + status: entryStatus, + ...(remoteControl ? { remoteControl } : {}), + snapshot: makeSnapshot(verification, transport, retired, answered) + } + } + } + } + } + } + } +} + +describe('the host contact changes no verdict', () => { + it('agrees with the frozen derivation on every snapshot combination', () => { + const cases = [...everySnapshotEntry()] + // Guard against the enumeration silently collapsing: 4 x 4 x 2 x 2 x 6. + expect(cases).toHaveLength(384) + const disagreements = cases + .map(({ label, entry }) => ({ + label, + now: runtimeHostConnectionStateForEntry(entry), + before: legacyRuntimeHostConnectionStateForEntry(entry) + })) + .filter(({ now, before }) => now !== before) + expect(disagreements).toEqual([]) + }) + + it('agrees for entries that carry no snapshot at all', () => { + const entries: (Entry | null | undefined)[] = [ + null, + undefined, + { status: null }, + { status: makeStatus() }, + { status: null, remoteControl: makeRemoteControl('closed') }, + { status: null, remoteControl: makeRemoteControl('ready') }, + { status: makeStatus({ remoteControl: makeRemoteControl('reconnecting') }) } + ] + for (const entry of entries) { + expect(runtimeHostConnectionStateForEntry(entry)).toBe( + legacyRuntimeHostConnectionStateForEntry(entry) + ) + } + }) + + it('keeps the revoked predicate and the contact verdict in step', () => { + for (const { label, entry } of everySnapshotEntry()) { + expect( + isRuntimeHostContactRevokedVerdict( + runtimeHostContactFromSnapshot(entry.snapshot!, entry.status) + ), + label + ).toBe(isRuntimeHostContactRevoked(entry)) + } + }) +}) + +describe('the contact separates what the host said from what it is worth', () => { + it('retains the host answer through every non-live verdict', () => { + const answered = makeStatus() + for (const [verification, transport, retired] of [ + ['unavailable', 'ready', false], + ['checking', 'connecting', false], + ['unavailable', 'disconnected', false], + ['blocked', 'ready', false], + ['verified', 'ready', true] + ] as const) { + const contact = runtimeHostContactFromSnapshot( + makeSnapshot(verification, transport, retired, answered), + null + ) + expect(contact.verdict, `${verification}/${transport}`).not.toBe('live') + // The fact the host gave us survives; only its currency is in question. + expect(lastRuntimeHostAnswer(contact)).toBe(answered) + expect(liveRuntimeHostStatus(contact)).toBeNull() + } + }) + + it('reports a verified probe as live and nothing else', () => { + const answered = makeStatus() + const contact = runtimeHostContactFromSnapshot( + makeSnapshot('verified', 'ready', false, answered), + answered + ) + expect(contact.verdict).toBe('live') + expect(liveRuntimeHostStatus(contact)).toBe(answered) + expect(lastRuntimeHostAnswer(contact)).toBe(answered) + }) + + it('tells a host that was never reached apart from a handshake in flight', () => { + // These collapsed into one `null` before, and they want opposite affordances: one should + // offer Connect, the other should not. + expect( + runtimeHostContactFromSnapshot(makeSnapshot('unavailable', 'unknown', false, null), null) + ).toEqual({ verdict: 'unverifiable', reason: 'never-asked', lastAnswer: null }) + expect( + runtimeHostContactFromSnapshot(makeSnapshot('unavailable', 'connecting', false, null), null) + ).toEqual({ verdict: 'unverifiable', reason: 'transport-connecting', lastAnswer: null }) + }) + + it('tells a refused host apart from a retired pairing', () => { + const answered = makeStatus() + expect( + runtimeHostContactFromSnapshot(makeSnapshot('blocked', 'ready', false, answered), null) + .verdict + ).toBe('refused') + expect( + runtimeHostContactFromSnapshot(makeSnapshot('verified', 'ready', true, answered), null) + .verdict + ).toBe('retired') + }) +}) diff --git a/src/shared/runtime-host-contact.ts b/src/shared/runtime-host-contact.ts new file mode 100644 index 000000000000..84b3dcd01712 --- /dev/null +++ b/src/shared/runtime-host-contact.ts @@ -0,0 +1,118 @@ +import type { RuntimeHostStatusSnapshot } from './runtime-host-status' +import type { RuntimeStatus } from './runtime-types' + +/** + * What a host's last probe is worth, kept apart from what the host actually said. + * + * The store's `status` field answers both questions with one nullable value, so a probe still in + * flight, a probe that failed, a host that refused us and a pairing that was retired all arrive at + * a reader as the same `null`. Readers then spend that `null` on decisions of very different + * weight. This names the four answers so the decision happens where the evidence is understood. + * + * `unverifiable` is never `exited` (docs/reference/ssh-execution-boundary.md). `refused` and + * `retired` are the only arms carrying positive evidence, and they are separate because they + * differ in kind: one is the host turning us away, the other is the pairing being ended. + */ +export type RuntimeHostContact = + | { verdict: 'live'; status: RuntimeStatus } + | { + verdict: 'unverifiable' + reason: RuntimeHostContactUnverifiableReason + lastAnswer: RuntimeStatus | null + } + | { verdict: 'refused'; lastAnswer: RuntimeStatus | null } + | { verdict: 'retired'; lastAnswer: RuntimeStatus | null } + +/** + * Why the host's current state is unknown. `never-asked` is the absence of any transport attempt, + * which is where an unreachable paired host permanently sits — distinct from a handshake in + * flight, and the reason it must stay actionable rather than spin. + */ +export type RuntimeHostContactUnverifiableReason = + | 'never-asked' + | 'checking' + | 'probe-failed' + | 'transport-connecting' + | 'transport-down' + +/** + * The host's last answer whatever the verdict, for facts that do not expire — its build's + * capabilities, its platform, its runtime id. Returns null only when the host never answered. + */ +export function lastRuntimeHostAnswer(contact: RuntimeHostContact): RuntimeStatus | null { + return contact.verdict === 'live' ? contact.status : contact.lastAnswer +} + +/** The answer only while it is current, for decisions that must not act on a stale fact. */ +export function liveRuntimeHostStatus(contact: RuntimeHostContact): RuntimeStatus | null { + return contact.verdict === 'live' ? contact.status : null +} + +/** True only for the host's own terminal verdicts — the one state that may withdraw a fact. */ +export function isRuntimeHostContactRevokedVerdict(contact: RuntimeHostContact): boolean { + return contact.verdict === 'refused' || contact.verdict === 'retired' +} + +/** + * Why the order matters: it is the order the connection-state derivation already used, and the + * parity suite pins every combination against it. Transport loss outranks a probe in flight + * because a dead socket explains the silence; a ready transport with a failed probe is the host + * being unreachable at the runtime layer, not at the network layer. + */ +export function runtimeHostContactFromSnapshot( + snapshot: RuntimeHostStatusSnapshot, + entryStatus: RuntimeStatus | null = snapshot.status +): RuntimeHostContact { + const lastAnswer = snapshot.status + if (snapshot.retired) { + return { verdict: 'retired', lastAnswer } + } + if (snapshot.verification === 'blocked') { + return { verdict: 'refused', lastAnswer } + } + if (snapshot.transport === 'disconnected') { + return { verdict: 'unverifiable', reason: 'transport-down', lastAnswer } + } + if (snapshot.verification === 'checking' && !entryStatus) { + return { verdict: 'unverifiable', reason: 'checking', lastAnswer } + } + if (snapshot.transport === 'ready' && snapshot.verification !== 'verified') { + return { verdict: 'unverifiable', reason: 'probe-failed', lastAnswer } + } + if (snapshot.verification === 'verified' && entryStatus) { + return { verdict: 'live', status: entryStatus } + } + if (snapshot.transport === 'connecting') { + return { verdict: 'unverifiable', reason: 'transport-connecting', lastAnswer } + } + return { verdict: 'unverifiable', reason: 'never-asked', lastAnswer } +} + +/** + * The contact for a recorded entry. A stored `contact` wins so a writer can state one the + * snapshot cannot express — a probe that threw before any snapshot existed, say — and the + * snapshot derivation is the fallback while writers are still being converted. + */ +export function runtimeHostContactForEntry( + entry: + | { + status: RuntimeStatus | null + contact?: RuntimeHostContact + snapshot?: RuntimeHostStatusSnapshot + } + | null + | undefined +): RuntimeHostContact { + if (!entry) { + return { verdict: 'unverifiable', reason: 'never-asked', lastAnswer: null } + } + if (entry.contact) { + return entry.contact + } + if (entry.snapshot) { + return runtimeHostContactFromSnapshot(entry.snapshot, entry.status) + } + return entry.status + ? { verdict: 'live', status: entry.status } + : { verdict: 'unverifiable', reason: 'probe-failed', lastAnswer: null } +}