Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/reference/ssh-execution-boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
30 changes: 17 additions & 13 deletions src/renderer/src/runtime/runtime-host-connection-state.ts
Original file line number Diff line number Diff line change
@@ -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'

Expand Down Expand Up @@ -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({
Expand Down
239 changes: 239 additions & 0 deletions src/renderer/src/runtime/runtime-host-contact-parity.test.ts
Original file line number Diff line number Diff line change
@@ -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> = {}): 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<RuntimeStatus['remoteControl']> {
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')
})
})
Loading
Loading