* docs(ssh): state the SSH execution boundary and pin the liveness vocabulary
Nothing under docs/ described how work splits between the client and an SSH
host, so agents and humans inferred it from error strings and got it wrong:
loss of contact was repeatedly reported as process death, which orphaned live
remote agents and cold-started duplicates over the same worktree.
Pins the vocabulary to the incumbent live/unverifiable/exited verdict from
unstopped-pty-verification so no synonym is introduced, records the one real
discriminator (all of a host's terminals drop together on link loss; one alone
means process exit), and lists the outstanding gaps with citations.
Tracked via the docs allow-list and linked from AGENTS.md, per the convention
in .gitignore.
* docs(ssh): cite the live restoreRequired site after it moved
The throw now lives in reattachSshPtySessionForSpawn; ssh-pty-provider.ts no
longer contains it. Caught by the worker fixing it, against a newer main than
the audit ran on.
* docs(ssh): require host evidence for liveness verdicts
* docs(ssh): keep boundary references stable
* docs(ssh): fence liveness evidence to its host identity
* docs(ssh): state replay and environment boundaries precisely
* docs(ssh): correct replay and platform boundary claims
* docs(ssh): describe headless runtime continuity accurately
* docs(ssh): distinguish authority from client metadata
* docs(ssh): describe pending fixes accurately
* docs(ssh): date the gap list and name the PR that closes each entry
The Known gaps section was accurate when written and becomes actively
misleading as its fixes land: it told a reader to go fix restoreRequired,
the missing unverifiable verdict, and the absent terminal-list host field,
three things now addressed by #14974, #14977 and #14973.
Mark the section as dated, require verification against current code before
acting on any entry, name the PR per entry, and move landed items out. Also
correct the two body claims that the landed fixes invalidated. The rules
above are durable; only this section rots.
* docs(ssh): make the boundary doc a durable ruleset, not an incident record
The Known gaps section was 18 of 93 lines enumerating specific defects from
one investigation, several already fixed by sibling PRs in the same batch. A
reference doc that needs a 'this section rots' warning is telling you the
section belongs somewhere else; those entries belong in issues.
Replace the six-row table of currently-lying signals with the method that
outlands any particular bug: ask whether the owning host produced the signal,
whether every PTY on the target went quiet together, whether the termination
event matches the current incarnation and generation, and whether a returned
status is actually a claim. Same for artifacts - state what ls-remote and a PR
head each do and do not prove, rather than listing which command is currently
wrong.
Nothing here goes stale when the open fixes land.
