# Known Hazards Hard-won edge cases harvested from the sister project (`claude_skill_owl`, ~80 commits / 12+ phases / multiple production incidents). Per ADR-0001, this is a **test checklist for the spt-core rebuild** — the clean-room rebuild must re-satisfy each invariant rather than re-discover the bug. **Architecture-translation note.** The sister project runs poll listeners and Psyche wrappers as *separate processes*. spt-core consolidates both into the one `spt-daemon` (brain), with a stable broker beneath it (ADR-0004). Many hazards below were inter-process races in the sister project; in spt-core some become intra-daemon concerns (potentially easier) while others move to the daemon↔broker IPC boundary or the network boundary (potentially new failure surface). Each entry notes the mapping where it differs. Citations point at sister-project paths for reference, not at spt-core. --- ## 1. Race conditions & ordering ### 1.1 Phantom INIT_SIGNOFF after grace period - **Failure:** orphan teardown enqueues INIT_SIGNOFF before the grace-period recheck; a transient Self recovery (binary handoff, brief stale poll) makes the recheck pass-as-alive, but the signoff was already spooled and drains on the next iteration → teardown despite a live Self. - **Invariant:** grace-period wait MUST complete *before* composing/delivering INIT_SIGNOFF; the recheck must bind `still_gone` before any envelope write. - **spt-core mapping:** in-daemon now (no separate wrapper), but the ordering invariant is identical — orphan/teardown logic must re-evaluate liveness after the grace wait, not before enqueue. - **Sister cite:** `src/live/wrapper/orphan.rs:201-259` (sleep@209 precedes compose@231-251); tests T-grace-recovery:576, T-still-gone-recheck:618. ### 1.2 Poll-rewrite race & info.json mid-write reads - **Failure:** `info.json` written by the wrapper mid-iteration while a list/classify command reads it → torn read, misclassification. - **Invariant:** consult liveness via the supervisor (`is_wrapper_alive`-equivalent) before any grace gate; reads of state files must tolerate concurrent writes (atomic write + rename, or read-retry). - **spt-core mapping:** the daemon owns both writer and reader → use in-process locking/snapshotting instead of racing on disk. Cross-node registry reads remain eventually-consistent and must tolerate staleness. - **Sister cite:** `src/common/list_filter.rs:100-150`; `src/owl/poll.rs:141`. ### 1.3 Stale `index.lock` wedge from prior git crash - **Failure:** crashed git leaves a 0-byte `index.lock` in a psyche tracked worktree; every later commit blocks forever. - **Invariant:** on daemon boot, sweep seed + all agent/project worktrees for stale locks (0 bytes, mtime > 60s) and remove; leave live locks alone. - **spt-core mapping:** cross-node Psyche sync (ADR-0002/0003) replaces git-repo sync, so the *git* lock may disappear — but any equivalent lockfile in the new sync mechanism needs the same stale-sweep on boot. - **Sister cite:** CHANGELOG v1.11.20 "Stale `index.lock`"; `src/common/git.rs`. ### 1.4 Deferred spool rows must not leak to the event stream - **Failure:** a hook spools a deferred (spool-only, no TCP wake) notice; startup `drain_all` flushes ALL rows including deferred → event emitted at wrong time/priority. - **Invariant:** startup drain (and idle/timeout TCP-wake sites) use `drain_non_deferred` only; deferred rows are picked up by their intended consumer via `peek`. All drain sites must agree on which rows they flush. - **spt-core mapping:** carries directly — the daemon's spool-drain has the same deferred-vs-immediate distinction. - **Sister cite:** `src/owl/poll.rs:276-316`; `spool::drain_non_deferred_with_metadata`. ### 1.5 Worker (working-perch) lifecycle path consistency - **Failure:** subagent-start creates the perch at one path layout; later hooks read it at another → not found; stop-hook scan misses nested perches. - **Invariant:** all Worker/Psyche child-perch path composition routes through one central resolver; no divergent path construction across hooks. - **spt-core mapping:** `Worker` is a day-one endpoint type; the daemon owns the registry, so perch location is a registry lookup, not ad-hoc path math. Single source of truth for instance→location. - **Sister cite:** `src/owl/hook_subagent_start.rs:122-168`; `hook_subagent_stop.rs:15-55`. --- ## 2. Identity & session-binding ### 2.1 Parent PID over ephemeral poll PID - **Failure:** orphan check polls an ephemeral listener PID; it dies and is recycled (esp. Windows); a foreign process with the recycled PID reads as alive → false-positive teardown (or false-negative). - **Invariant:** prefer the stable harness-session PID (`parent_pid`) over any ephemeral process PID for liveness; minimal `info.json` for supervisor-owned perches to avoid stale leaks. - **spt-core mapping:** session binding (parent-process-tree anchor) still applies for harness-hosted topology. For spt-hosted sessions the broker holds the child directly → liveness is the broker's held-handle state, more reliable than PID polling. - **Sister cite:** `src/live/wrapper/orphan.rs:141-161`; CHANGELOG v1.11.20. ### 2.2 Stdin session_id precedence over env - **Failure:** subagent inherits a stale `OWL_SESSION_ID` env across `/clear`; hook gets two session_ids (fresh stdin, stale env) → wrong-agent binding. - **Invariant:** stdin-provided session_id wins; env is fallback only. - **spt-core mapping:** the harness-contract subcommand surface must define the same precedence for whatever identity fields hooks pass in. - **Sister cite:** CHANGELOG v1.35.1 "IN-05"; `hook_subagent_start.rs:40-51`. ### 2.3 Binary-handoff argv schema must stay backward-compatible - **Failure:** old binary spawns new binary with old argv arity; clap rejects before state rehydration → wrapper dies unlogged. - **Invariant:** every newly-added handoff positional has a default; state-file rehydration happens *after* argv parse; defaults survive intermediate versions. - **spt-core mapping:** CRITICAL — self-update (ADR-0004) makes handoff routine. The broker↔brain IPC and any brain-relaunch argv must be versioned and forward/backward tolerant (a newer brain talks to an older broker). This is the single most update-frequency-sensitive invariant. - **Sister cite:** `src/live/wrapper/lifecycle.rs:17-106`; `src/cli.rs` defaults; CHANGELOG v1.11.10. ### 2.4 Generation `gen_start` always = now() on cold-start AND handoff - **Failure:** stale gen_start from a rehydrated state file fires time-based discriminators on the new process. - **Invariant:** wall-clock `gen_start` is set to `now()` on both cold-start and handoff; generation counter increments on every start/revive; session UUID captured fresh and carried so the resumed mind distinguishes "same gen continuing" vs "new gen born". - **spt-core mapping:** carries to the daemon's per-instance generation tracking. - **Restoration D3/D4 (ADR-0018):** the generation *counter* custody moved to the broker (D3-2 — it observes every brain spawn, planned or crash, and hands `{generation, start-reason}` at spawn; `gen_start` stays `now()`-fresh, never rehydrated). The brain→brain **`BrainState` *message*** (`{session_id, generation, next_seq, gen_start_ms}`) that previously carried continuity across a handoff is **retired from the production path in D4-2**: a brain the supervisor respawns cold-starts and reconstructs all session continuity by **querying the broker** (`Brain::resume_sessions` over the broker's cursor-of-record), never a frame. `BrainState` / `Brain::handoff` / `Brain::snapshot` remain `pub` and compiled **only for the integration tests** (handoff/idempotent/daemon_e2e/attach/brain_swap + `update.rs::apply_brain_only`, itself test-only-reached) — no non-test caller (grep-clean close-out). The falsifiable proof the production path needs no frame is the D4-2 hard-kill harness (`tests/resume.rs`): a brain dropped with no `snapshot()` taken still resumes gaplessly. - **Sister cite:** `src/live/wrapper/lifecycle.rs:70`; `src/common/wrapper_state.rs`. ### 2.5 Daemon-hosted endpoints have no dedicated liveness PID - **Failure:** the sister evaluates Psyche/perch liveness via a dedicated process PID — the wrapper's own pid in `info.json`, checked with `is_process_alive`. Under ADR-0004 the Psyche (and any spt-hosted Self) is a **loop inside the daemon**, not a separate process: it holds no dedicated pid, and its `claude`/summarizer subprocess is ephemeral (spawned per pulse/commune, then exits). If a daemon-hosted perch's `info.json` carries the **daemon's** pid, then *every* hosted endpoint shares one pid, and `is_process_alive(pid)` reads "alive" for a torn-down endpoint as long as the daemon runs — while `clean_stale_entries` (dead-pid deletion) can no longer distinguish a dead endpoint from a live one. The 2.1/5.1 liveness models do **not** cover this third category: the Psyche is neither harness-hosted (no `parent_pid` anchor) nor a broker-held PTY child. - **Invariant:** for **daemon-hosted** perches (Psyche; spt-hosted Self), liveness is the **daemon's authoritative in-memory endpoint table + a `status` field** on `info.json` (`online|offline|…`), **never** `is_process_alive(info.pid)`. `info.pid` for a daemon-hosted perch is at most a *hosted-by-daemon* marker (the daemon pid), not a liveness signal; registry stale-clean for these rows keys on the daemon's endpoint table, not per-row pid. This reuses the pattern already specified for **Shells** (`info.json` carries daemon-managed `status`, capability resolved by `adapter_name` — CONTEXT "Shell… Not in the subnet registry") and extends it to daemon-hosted *agent* perches. - **spt-core mapping:** the **M1/M2a interim** model keeps the Psyche/listener a real per-process owner (the `api listen` process), so its per-pid liveness (`deliver::is_online` → `info.read_pid` → `proc::is_process_alive`; `registry::clean_stale_entries`) is correct *interim*. **M3 daemon consolidation replaces it** with daemon-authoritative liveness for hosted perches. Keep the liveness check behind one resolver (mirrors `resolve_address` stale-clean) so the M3 swap is localized — do **not** let the per-pid assumption leak into new call sites. - **Sister cite:** `src/live/wrapper/orphan.rs` (wrapper-pid liveness); `src/common/list_filter.rs:168-175` (pid-classify); spt-core `crates/spt-store/src/{proc.rs,registry.rs}` + `crates/spt-msg/src/deliver.rs::is_online`. ### 2.6 A shell instance's `online` is a recorded field with no death edge - **Failure:** a shell perch's `status` has exactly two writers — the bind handshake (→`online`) and `close_shell` (→`offline`) — and `close_shell` runs on the **link-break** path alone. A binary that dies **abruptly** (force-kill, crash, OOM) breaks no link, so nothing ever writes the flip: the record says `online` forever while the pid it names is gone. Every consumer of the recorded field then inherits the lie — `shell list` reports online indefinitely; `relink` (the one command that recovers the instance) refuses `SHELL_ALREADY_ONLINE`, gated on the very state that is wrong; and `shell cmd`'s wake-if-offline arm reads "not offline", skips the wake, and spools the command to a corpse — accepted happily, drained by nobody, **indistinguishable from a busy shell**. The only exit was `teardown` + `spawn`, which destroys the perch (losing the instance's persisted state) and frees the mint slot, so the instance returns under a **different canonical id** and every reference to the old name — docs, other agents' notes, tag addressing — silently points at nothing. The rename is the *visible* cost; the expensive one is **silent**: a consumer's perch-persisted cursor re-baselines on the fresh perch, so work arriving between the death and the re-bind is never scanned — not failed-and-retried, just never seen (alchemy's tag scanner, 2026-07-25). Recovery must therefore preserve the perch, not merely restore a running binary. - **Invariant:** ONLINE-ness is **derived**, never the recorded field alone: `status == online` **AND** the recorded `shell.pid` is not *provably* dead. Provably dead is narrow — pid parked, non-zero, `!is_process_alive`; pid absent, unparseable, or `0` (a broker-hosted spawn whose backend exposed no pid) reads **alive**, the same fail-toward-alive parity 2.5 holds, so a backend the resolver cannot see is never declared dead. A recycled pid reads alive, so the heal can be *missed* but never *mis-fired*. Derivation NEVER promotes: a recorded-`offline` instance stays offline whatever its pid file says. Site class is part of the invariant: **derive** at the gates and renders (relink, the cmd wake arm, drive's drop-if-offline, `shelldisc::discover` = the single source of both `shell list` surfaces, the activity fan-out); keep the **recorded** field at the two writers and at the owner-suspend cascade, whose `close_shell` **is** the cleanup that would be skipped; and keep it at the wake reconciler's eligibility read, so nothing relaunches spontaneously. - **No spontaneous relaunch (operator-ratified, flynn 2026-07-25):** the reconciler deliberately does NOT adopt a dead-pid instance. Every reason an operator stops a shell is a reason not to want it back a tick later: mid-deploy (a shared install dir makes "kill the process" routine on Windows, since a running exe cannot be overwritten) an auto-relaunch would run the **old** binary out of the file being replaced — worse than a failed install — and it turns quarantining a misbehaving shell into a restart loop. Recovery is demand-driven instead: `relink`, or a `shell cmd` that wakes. `relink` probes **locally** rather than trusting a daemon sweep, so recovery holds with the daemon down. - **spt-core mapping:** `spt_store::shellinfo::{shell_pid_provably_dead, effective_status, is_shell_online}` (the resolver — the shell-side twin of 2.5's `liveness.rs`, which gave *agent* perches exactly this and which shells never got); consumers in `linkhost::{relink_shell, prepare_drive, run_action}`, `shelldisc::discover`, `activity::observe_links`. - **Source:** spt-core, flynn's spt-alchemy field report (2026-07-25) — a deterministic recipe, not a race. --- ## 3. Lifecycle ### 3.1 Ephemeral perch cleanup on every `ring` exit path - **Failure:** `ring` creates an ephemeral perch; early-exit paths (no-perch, empty-msg, timeout) skip cleanup → stale dirs accumulate. - **Invariant:** every code path that creates an ephemeral perch cleans it before exit; exception: if the caller already had an active perch, do not treat as ephemeral and do not clean up. - **spt-core mapping:** `ring` semantics carry; the daemon owns ephemeral-perch lifecycle, so a single guaranteed-cleanup (drop guard / RAII) is achievable in-process. - **Sister cite:** `src/owl/ring.rs:58-294`. ### 3.2 Stale signoff sentinel must not kill a fresh start - **Failure:** a leftover `.claude/-signoff.md` from a prior session is read by a fresh listener as a live signoff → immediate teardown. - **Invariant:** on every listener/daemon spawn, sweep stale signoff sentinels; signoff files are write-once per generation. - **spt-core mapping:** same sweep on daemon (re)start per hosted instance. - **Sister cite:** CHANGELOG v1.11.20; `src/owl/cleanup.rs:97`. ### 3.3 Orphan teardown fires echo-commune BEFORE INIT_SIGNOFF - **Failure:** teardown delivers INIT_SIGNOFF without first saving the final context delta → Psyche signoff lacks the context-save summary. - **Invariant:** on orphan path, synchronously run the echo-commune (final delta) before composing INIT_SIGNOFF; skip only if the session_id is missing. - **spt-core mapping:** the daemon runs psyche/pulse loops in-process; ordering invariant identical. - **Sister cite:** `src/live/wrapper/orphan.rs:175-199`; tests A-H:333-565. ### 3.4 A `ring` never adopts — so never deletes — a perch it did not create - **Failure:** 3.1 guards the LEAK direction (cleanup on every exit path). It says nothing about *whose* perch is being cleaned, and the two compose into a data-loss bug: `ring` decides "the caller has no perch" **ready-marker-first**, so an existing perch whose marker is momentarily down — busy turn, soft session-end, stale re-bind — reads *perchless*, `setup_ephemeral` clobbers the caller's real `info.json`, and 3.1's guaranteed cleanup then runs on the way out and **deletes** the ready marker, `info.json`, `spool.db` and the directory. Silent CLI-side fs ops, no daemon log, no console trace (field 2026-07-27 — emphasys lost a live endpoint and its spool to one timed-out ring). - **The mail half is a CONFIDENTIALITY failure, not only a durability one:** deletion is what happens on the way out, but while the ring *holds* the adopted perch its reply-wait `drain_one_at` consumes whatever is in the victim's spool and **renders it to the ringer as the reply**. Ringer == victim (the field case) is the degenerate, mild shape — anything drained reaches its intended recipient. Ringer != victim is the severe one: a third party rings a live agent and the **victim's inbox is drained into the ringer's output**, leaving no trace on either side once the dir is removed. Across a multi-machine subnet that is one agent reading another's mail. Bounded honestly for the record: in the field instance theft did **not** fire — emphasys's 66-second window returned `TIMEOUT` with zero `Replied{…}` — it was available and did not happen. - **Self-camouflaging**, which is why it went unattributed for hours: the damage — perch gone, roster row ghosted — *mimics the stale-liveness condition people reach for `ring` to diagnose*. The field caller was probing a ghost-roster symptom and the probe manufactured a fresh one, so debuggers of stale liveness are disproportionately its victims and read the wreckage as more of the symptom they were chasing. - **Marker-down is not an edge case:** on hosted OMP endpoints the extension owns the listener and publishes busy/idle through `api state`, so marker-down is the **normal steady state during work** — marker-first misjudges healthy endpoints routinely. - **Invariant:** probe the perch **directory**, not the marker. A dir carrying a **record or a spool** is OCCUPIED — refuse to adopt it. Ambiguity resolves toward refusal, always: an **unreadable** record (corrupt/truncated `info.json`) or an unreadable dir counts as occupied, never as residue, because deletion is irreversible while refusal is recoverable. A pre-existing **empty** dir is refused too — it is not provably ring's own residue (`endpoint run` mid-create owns an empty perch dir for a window, and deleting it is the same race in a different hat). Refusal never blocks and is never silent: the message is delivered, the call declines to block-wait (the reply lands on the caller's own listener), and the caller gets a **distinct** loud report — `RING_PERCH_EXISTS` (record/spool) or `RING_STALE_DIR` (empty; names the path and the manual remedy). Loudness — not a self-heal — is what keeps a permanent refusal from being a silent one. Structural, not advisory: the leaf dir is created with `create_dir` (fails `AlreadyExists`), so a perch appearing between probe and create still cannot be adopted, and the refusal path never calls cleanup. - **spt-core mapping:** `spt_msg::ring::{probe_perch, setup_ephemeral, ring}`; `RingOutcome::{PerchExists, StaleDir}` rendered by `cmd_ring`. - **Source:** spt-core field incident 2026-07-27 (emphasys endpoint + spool loss); ruled by doyle, with emphasys's mid-create-race amendment revoking the empty-dir self-heal. --- ## 4. Wire / transport ### 4.1 Envelope HTML-entity codec ordering — `&` decoded LAST - **Failure:** decoding `&`-entity before the others double-decodes nested entities (`<` → wrong result). - **Invariant:** ENCODE order amp→first … `
`→last; DECODE order `
`→first … amp→**last** (`<`,`>`,`"`, then `&`). One sole decode site (at the LLM/stdin boundary); the parser never decodes. - **spt-core mapping:** `spt-proto` owns the envelope grammar (public SDK, semver + wire-version). This codec contract is a copy-verbatim commodity item (ADR-0001) and a public-API conformance test. - **Sister cite:** `src/owl/poll.rs:1-73`; `src/common/envelope.rs`. - **CR-linesafety `[REQ-HAZARD-ENVELOPE-CR-LINESAFE]`:** the EVENT is LINE-FRAMED, so the codec must neutralize raw `\r` too — `event_body_escape` folds CRLF/lone-CR to `\n` (→`
`) **before** framing. **Failure (field, 2026-06-08):** a cross-node `spt send` from Windows (`echo` → CRLF) carried a raw `\r` into the single-line envelope; the receiver terminal did a CR→column-0 overwrite (`` clobbered `REQ-HAZARD-ID-CHARSET] --> - **Failure:** a bare endpoint id that contains `:` or `@` (or a path separator / whitespace / control char) makes the canonical qualified address `[subnet:]id[@node]` (ADR-0006 / REQ-INST-10) ambiguous to parse, and lets a name smuggle into a perch directory path. Once permissive ids exist in the wild, tightening later needs a migration. - **Invariant:** every addressable id/name is validated to `[A-Za-z0-9_-]` + Hiragana/Katakana/CJK only, length `1..=64`, **at every creation seam** (`ready` start, `api bind`, `api listen`, `api worker-start`). `:` and `@` are permanently reserved as address delimiters; reads of existing perches are never re-validated. Enforce now (pre-M3/M4) so no permissive id-data accumulates. - **spt-core mapping:** `spt_proto::id::validate_endpoint_id`; called at the four creation seams. The existing Psyche (`-psyche`) / Worker (`-w`) suffix scheme uses only `-` + alphanumerics, so composite ids validate. ### 4.7 Concurrent SQLite openers must not fail with "database is locked" - **Failure:** two endpoints on one machine open the same SQLite store at once (e.g. two `ReadyAgent::start` calls registering simultaneously) and one fails outright with `SQLITE_BUSY` / "database is locked" → spurious registration/spool failure. Surfaced as a parallel-test flake in `two_agents_exchange_message_tcp_and_spool`, but the bug is real concurrency, not test-only. - **Invariant:** `busy_timeout` is set **before** any lock-taking statement on every connection. Switching `journal_mode=WAL` takes a brief exclusive lock; with the default 0ms timeout it fails immediately under contention, so the pragma order is load-bearing: `Connection::open` → `busy_timeout` → `journal_mode=WAL` → `CREATE TABLE …`. WAL alone is insufficient (concurrent *writers* still serialize; they must *wait*, not error). - **spt-core mapping:** `spt_store::registry::open_registry` + `spt_store::spool::open_spool_at`; both set `busy_timeout=5000` first. Any future SQLite store (history Path B, instance registry) must follow the same ordering. ### 4.8 Registry merge ordered by epoch, never wall-clock (red-team #8) - **Failure:** the per-subnet registry replicates `endpoint_id → [instances]` eventually-consistently across nodes. Under a partition or clock skew, a lagging node re-announces a stale `Active` for an endpoint that has actually gone `Offline`. If the merge ordered updates by wall-clock (or "last write wins"), the stale `Active` overwrites the newer `Offline` and resolution routes a message to a dead/wrong instance. - **Invariant:** the merge precedence key is a **per-node monotonic epoch counter** (`spt_store::epoch::EpochSource`, persisted, strictly increasing, NEVER wall-clock), compared version-vector style per `(endpoint_id, node)`: an incoming update wins **iff its epoch is strictly greater** than the stored one for that node; equal or lower is dropped as stale. So a newer `Offline` (higher epoch) can never be clobbered by a lagging `Active` (lower epoch), and an idempotent equal-epoch replay is a no-op. Wall-clock is at most a human tiebreaker hint inside a flagged conflict, never the ordering authority. The same epoch source unifies with the D6 sync-precedence concurrent-write detection (#7). - **spt-core mapping:** `spt_net::net::registry::SubnetRegistry::merge_instance` (the lease) + `spt_store::epoch::EpochSource` (the counter). Cross-node replication of the merge wires at D4; the merge seam is identical for local and wire-delivered updates. Chaos/two-host verification = D9. ### 4.9 SQLite stores must create their parent dir — SQLite won't - **Failure:** `Connection::open` creates the database FILE but never its parent DIRECTORY. On a fresh home (first boot, fresh CI `_work` dir) a registry op that runs before any perch-creating op (`create_dir_all` side effects) fails `SQLITE_CANTOPEN` — "unable to open database file …owlery\.registry". Timing-dependent: whichever code path touches the home first decides the outcome, so it surfaces as a parallel-test flake (bind-first tests losing the dir-creation race to perch-first tests). Bit the hfenduleam CI leg twice (2026-06-03/04, four spt-msg unit tests at once on the second strike) before being run to ground; a slow runner filesystem (AV scanning fresh dirs) widens the window but is not the cause. - **Invariant:** every SQLite store's open path `create_dir_all`s its parent dir itself, best-effort, before `Connection::open` — never relying on another subsystem having materialized the home first. (Mirrors the spool, which always did this; the registry didn't.) - **spt-core mapping:** `spt_store::registry::open_registry` (`create_dir_all(owlery)` before open). `spt_store::spool::open_spool_at` already creates its perch dir. Any future SQLite store must do the same — pair this with the 4.7 pragma ordering on every new store. ### 4.10 Dead node identities leave immortal registry rows `[REQ-HAZARD-REGISTRY-GHOST-ROWS]` - **Failure:** the registry's only superseding mechanism is the per-`(endpoint_id, node)` epoch lease (4.8) — a row is replaced only by a newer row *from the same node*. When a node identity dies permanently (machine retired, or `node.key` regenerated so the "node" never speaks again), its rows are never superseded and never expire: they sit in the in-memory registries and the `identity/registry/.json` snapshots forever. A bare-id send then resolves the same endpoint id on both the live and the dead identity and refuses with a **phantom `AcrossNodes` ambiguity** — unfixable by the user, because no qualifier reaches a node that no longer exists. Hit live in the M7 acceptance run (2026-06-06): gravity paired under two identities (09ef…, then 03854a… after its key universe flipped during the sudo experiments); the dead identity's `sergey` row made bare `spt send sergey` refuse on HFENDULEAM. - **Invariant:** registry rows authored by a **silent** peer node decay: a node not *heard* (admitted inbound feed — the M7 D2 heard-map, REQ-SUBNET-1) within the eviction window (`registry_evict_after_ms`, default 300s ≈ 10 default pump cadences) has its rows **evicted** from every subnet registry, snapshots rewritten. Own rows never decay (the node always hears itself implicitly — it authors them each pump tick). Eviction is safe under the lease: v1 has **no transitive gossip**, so any future update for a node comes from that node itself, alive, re-inserting from its durable `EpochSource` within one cadence — there is no lagging third-party replay to mis-order against. A merely-offline node loses its rows after the window and reconverges on return; meanwhile resolution honestly reports it absent instead of poisoning bare-id sends. - **spt-core mapping:** `spt_net::net::registry::SubnetRegistry::evict_nodes` (model) + `spt_daemon::registryhost::RegistryHost::evict_silent_peers` (heard-map TTL) driven from the registry pump tick (`peerloop`). Trust rows are NOT auto-evicted (trust is a user decision; a stale trust row only costs dead dials) — pruning those is a separate verb. - **Source:** M7 acceptance run 2026-06-06 (DEFERRED.md "Ghost registry row eviction"); the AMBIGUOUS render fix rode along. - **Mesh note (ADR-0017, 2026-06-08):** the subnet mesh **preserves** this invariant rather than superseding it. "No transitive gossip" sharpens to **no transitive *row* gossip** — the mesh relays only the member *roster* (discovery), while registry **rows stay own-authored and are fetched directly** from each member over a handshake. So "any future update for a node comes from that node itself, alive" still holds and the eviction lease is untouched. (The plan's rejected alternative — signed transitive *row* relay — would have broken this; roster-only relay was chosen precisely to keep it.) ### 4.11 Advertisement-epoch reset strands a node `[REQ-HAZARD-EPOCH-RESET]` - **Failure:** a node whose advertisement-epoch counter resets (the durable `EpochSource` file lost/recreated) re-advertises with LOW epochs; peers hold a higher last-seen epoch for that `(endpoint, node)` lease and drop every fresh row as **stale** — the node advertises into a void until its counter outruns its own history. Nothing renders the cause: the node looks healthy locally, peers simply never update. - **Invariant (mitigation by construction, common case):** the common trigger — a full reinstall / identity regeneration — is covered by the **re-pair trust overwrite** (M8 decision 13, REQ-SUBNET-7): a completed ceremony presenting the same label + machine id evicts the superseded identity's trust AND registry rows on the seed-holder, and the peer-side epoch memory **dies with the deleted row** — the re-paired node's fresh epochs land on a clean lease. M8 acceptance 7 verifies this explicitly (the epoch sub-check). - **Residual (documented, guard deferred):** the narrow slice — epoch file lost while the node *identity* is kept (manual state surgery, partial restore from backup) — has no guard; it waits for a field hit before one is designed (M8 decision 24). `REQ-HAZARD-EPOCH-RESET` is minted inactive (TRACEABILITY rule 5) as the tracking hook. If hit: symptoms are one node's endpoints frozen-stale on every peer while its own views are fresh; recovery today is re-pairing the node (rides the common-case eviction above). - **spt-core mapping:** epoch mint = `spt_store::epoch::EpochSource` (`identity/epoch.json`); the lease = the per-`(endpoint, node)` epoch compare in `spt_net::net::registry`; the eviction that clears peer-side epoch memory = `registryhost::repair_evict_superseded` + `RegistryHost::consume_repair_evictions`. - **Source:** minted at M8 ratification (decision 24), recognized as a class during the 2026-06-07 pump diagnosis / re-pair overwrite design — not yet field-hit in its residual form. --- ## 5. Platform-specific ### 5.1 Windows PID recycling false positives - **Failure:** recycled PID reads alive for the wrong process → orphan misclassification. - **Invariant:** anchor liveness on the stable parent/harness PID; minimal info.json for supervisor-owned perches; mtime grace window (≥60s) masks transient mismatches. - **spt-core mapping:** broker-held handles supersede PID polling for spt-hosted sessions; keep the grace window for harness-hosted. - **Sister cite:** `src/live/wrapper/orphan.rs:141-161`; `src/common/list_filter.rs:168-175`. ### 5.2 Windows EBUSY on atomic rename - **Failure:** `fs::rename` fails while a handle is (recently) held → registry/marketplace update fails. - **Invariant:** tmp-write + atomic-rename with retry/backoff; best-effort side-fail; tolerate transient EBUSY. - **spt-core mapping:** all on-disk state writes (registry, trust store, spool checkpoints) use this pattern. Self-update binary swap on Windows especially. - **Sister cite:** CHANGELOG "EBUSY"; `src/common/owlery.rs` atomic_write. ### 5.3 Git/subprocess timeout stamping - **Failure:** a hung subprocess (git on slow net) blocks the supervisor indefinitely. - **Invariant:** every metadata-producing subprocess has a timeout; timeout yields `None` + rate-limited stderr, never a hang. - **spt-core mapping:** generalize to all manifest-declared harness invocations (delegated commands, adapter updates) — timeouts mandatory. - **Sister cite:** `src/common/git.rs`. ### 5.4 Windows UNC prefix in serialized paths - **Failure:** canonicalized `\\?\C:\...` serializes to `//?/C:/...` and fails `read_to_string`. - **Invariant:** strip the `\\?\` UNC prefix after backslash→forward-slash conversion; serialized path attrs must be directly consumable. - **spt-core mapping:** any path crossing the wire (file-drop EVENTs, off-node file transfer per ADR-0003) needs canonical normalization at the `spt-proto` boundary. - **Sister cite:** `src/common/owlery.rs:377-384`. ### 5.5 ConPTY withholds output until DSR is answered `[REQ-HAZARD-CONPTY-DSR]` - **Failure:** a broker reading a ConPTY master sees only the 4-byte startup query `ESC [ 6 n` and then nothing — the child looks hung/silent but is producing output normally. ConPTY blocks all child stdout until the terminal answers the cursor-position query. - **Invariant:** every ConPTY reader auto-answers DSR (`ESC [ 6 n` → write `ESC [ 1;1 R`, or a real cursor position) on the PTY writer. Secondary: a ConPTY master does not EOF while the writer is held, so read loops drain on a thread and never gate exit on a blocking `read()`. - **spt-core mapping:** `spt-term` broker PTY reader (ADR-0004). Brand-new to spt-core — not in the sister project (it never hosted ConPTY directly). - **Source:** Spike #1 (`docs/spikes/SPIKE-01-broker-handoff.md`); reproduced with both a Rust child and `cmd.exe`. ### 5.6 Windows detached children inherit a captured caller's pipe `[REQ-HAZARD-DETACHED-PIPE-INHERIT]` - **Failure:** a caller captures an `spt` invocation's output through a pipe (`Command::output()`, a harness hook reading the command). That `spt` process detach-spawns a **long-lived** child (the daemon via `ensure_running`; a shell binary via `spt shell spawn`). On Windows `CreateProcess` runs with `bInheritHandles = TRUE`, and the spt process's std handles — the caller's pipe write-ends — are inheritable by construction, so the immortal child inherits them even when its *own* stdio is `Stdio::null()`. The caller's pipe read never sees EOF: the capturing caller **hangs forever** (unix is immune — pipe fds are `CLOEXEC`). Paid twice: daemon spawn (guarded at D4a-era `spawn_detached`), then again at M5-D3e when the mock-shell E2E hung `spt shell spawn` for hours. - **Invariant:** every detach-spawn of a long-lived child inherits only handles it **enumerates**. The default and overwhelmingly common form of that is `bInheritHandles = FALSE` (`spt-daemon::daemon::detached_no_inherit`) — zero handles flow, whatever the pipe's depth in the ancestry. Stripping `HANDLE_FLAG_INHERIT` from the spawner's *std* handles is NOT sufficient: a grandparent capture's pipe sits in the handle table as a stray inheritable handle and still flows through every **bare** `bInheritHandles = TRUE` hop (the first guard shipped that way and was wedged by exactly this — a daemon spawned three layers deep held the pwsh-level pipe of the CI/test harness). - **The one permitted TRUE (amended 2026-07-26, RESIDENT-SERVICE W1):** a spawn that must capture the child's output may pass `bInheritHandles = TRUE` **only** paired with an explicit `STARTUPINFOEX` + `PROC_THREAD_ATTRIBUTE_HANDLE_LIST` allowlist — the Win32 contract honors the list only under TRUE, so the earlier phrasing ("flipping TRUE is refused") forbade its own mechanism and was unimplementable. The hazard was always *unenumerated* inheritance, and the list **is** the enumeration: only the named handles flow, so a grandparent's pipe cannot reach the child at any depth — strictly stronger than what FALSE achieves incidentally. A **bare** TRUE, with no attribute list, remains REFUSED. Today the only such path is a supervised `[service]` spawn with startup capture (one-entry list, one file handle), and it is pinned behaviorally, not by flag-reading: `a_captured_spawn_inherits_only_the_handle_in_its_allowlist` plants a deliberately inheritable handle that is NOT in the list and fails if the child receives it. - **spt-core mapping:** `spt-daemon::daemon::spawn_detached` (the daemon) and `spt-daemon::shellhost::launch_shell` (the relay-receipt shell binary). Any future long-lived detached spawn (manifest-template children included) must use the same no-inherit spawn, or the enumerated form above where it genuinely must capture output. - **Source:** spt-core, M5-D3e (`shell_e2e.rs` hang, 2026-06-04, twice — once per guard generation); Rust `Command` restricts *its own* created stdio handles but a parent's inheritable handle table still flows. ### 5.7 Elevated commands spawn the daemon with the wrong token `[REQ-HAZARD-ELEVATED-DAEMON-SPAWN]` - **Failure:** membership-implies-reachability made *every* `spt` invocation a potential daemon spawner (`ensure_running`), including the elevation-gated ones (`subnet create`/`join`, REQ-SUBNET-4). The spawned daemon inherits the spawner's token. **Windows:** an elevated `subnet create` auto-starts an ELEVATED daemon whose named pipes deny unelevated clients — every subsequent unelevated `spt` reads "not running", tries to spawn its own daemon, and dies on bind Access-denied; the user had to taskkill (hit live, M7 acceptance 2026-06-06). **Linux:** a sudo'd command spawns a root daemon and/or root-owned state — and because sudo flips `$HOME`, the daemon can mint a *different node identity* in root's universe (the very key-flip that produced the 4.10 ghost rows). - **Invariant:** the daemon **always runs unelevated in the invoking user's universe**, regardless of which command spawns it. Two enforcement points sharing one seam: (a) `spawn_detached` de-elevates the child — Windows: the UAC **linked token** (`TokenLinkedToken` → `DuplicateTokenEx` → `CreateProcessWithTokenW`; inherits no handles, so 5.6 holds by construction); Linux: drop to `SUDO_UID`/`SUDO_GID` with `$HOME`/`$USER`/`$LOGNAME` reset to the invoking user's (passwd lookup); (b) a `Daemon::run` entry guard catches a *directly* elevated `spt daemon` — Linux drops privileges in-process before touching any state; Windows respawns de-elevated and exits. When no unelevated identity exists to drop to (UAC disabled, genuine root login, SYSTEM), the daemon runs as-is with a loud warning — a consistent universe, never a torn one. Elevated one-shot *clients* talking to an unelevated daemon are fine (downward connects work); the daemon side is the invariant. - **spt-core mapping:** `spt-daemon::deelevate` (the OS-split seam) consumed by `daemon::spawn_detached` + the `Daemon::run` entry guard. The fuller Linux elevation model (install symlink + default-account election) is deferred (DEFERRED.md, M8). - **Source:** M7 acceptance run 2026-06-06 (DEFERRED.md "Non-admin daemon spawn"); interim field rule was "bring the daemon up unelevated FIRST". ### 5.8 Console children of the console-less daemon flash visible windows `[REQ-HAZARD-CHILD-CONSOLE-FLASH]` - **Failure:** the daemon runs DETACHED (no console, 5.6/`detached_no_inherit`). Any console-subsystem child it spawns (`git`, `taskkill`, manifest hook commands) gets a **fresh conhost with a visible window** — piped/null stdio does NOT prevent it. Field shape: the 60s sync pump's two git calls (`for-each-ref` + `rev-parse`) flashed two blank windows per minute on the user's desktop (2026-06-06). - **Invariant:** every short-lived console child spawned from daemon-reachable code sets `creation_flags(0x0800_0000)` (`CREATE_NO_WINDOW`). Long-lived detached children use `detached_no_inherit` (already `DETACHED_PROCESS | CREATE_NO_WINDOW`); de-elevated spawns use `CREATE_NEW_CONSOLE + SW_HIDE` (5.7 — `CreateProcessWithTokenW` rejects `CREATE_NO_WINDOW`, error 87). - **Test seam caveat:** window-absence is unobservable from a consoled test runner — the child inherits the runner's console and never creates a window, flag or no flag. Unit coverage asserts the flagged spawn still works (the error-87 "flag combo breaks spawn" regression class); window-absence was verified live by process-watch capture. - **spt-core mapping:** `spt-store::gitrun::run_git` (every BranchStore/ContextStore git call), `spt-daemon::shellhost::kill_shell_pid` (taskkill), `spt-runtime::run_bounded_command` (manifest hook commands), `spt-runtime::ManifestRuntime::command_for` (the one shared builder behind `spawn_session` + `run_bounded_stdin` — the notif pump's `spawn_notif_command` and the live agent's psyche/echo/turn spawns), `spt-daemon::shellwake` (already guarded). The flag lives in each shared builder, not per call site, so the invariant holds for every ManifestRuntime spawn by construction. - **Source:** spt-core field bug, 2026-06-06 — two blank windows flashing every 60 seconds on a desktop workstation, caught by process-spawn watcher (git.exe parent=spt daemon, conhost.exe child each). ### 5.9 `Instant - Duration` underflow-panics on a freshly-booted host `[REQ-HAZARD-INSTANT-UNDERFLOW]` - **Failure:** `Instant::now() - Duration::from_secs(N)` panics `overflow when subtracting duration from instant` when the process's monotonic clock is younger than `N` — i.e. the host booted less than `N` ago. The peer pump primed its cadence legs with `Instant::now() - 86_400s` to mean "everything due now"; on a Windows runner with sub-24h uptime the pump thread panicked at startup, so the subnet never converged (CI `pump_and_dispatch_self_drive_the_subnet` failed, run 27082417706). It is *environment-conditional* — green on any host up longer than the offset, red below it — so it slips local dev and only bites a fresh CI box or a just-rebooted machine. - **Invariant:** NEVER compute an instant in the past by subtracting from `Instant::now()`. Represent "never run / due now" as `Option = None` and gate on forward `now.duration_since(past)` only (`peerloop::due`). No backward instant arithmetic anywhere in scheduling. - **Test seam caveat:** the convergence E2E only reproduces on a sub-offset-uptime host (it passed everywhere with >24h uptime). The deterministic guard is the `due(None, ..)`/`due(Some(now), ..)` unit on the extracted gate — it asserts first-tick-due with zero instant subtraction, independent of host uptime. - **spt-core mapping:** `spt-daemon::peerloop::due` (the sole cadence gate behind `due_reg`/`due_notif`/`due_sync`/`due_upd`); cadence legs are `Option` seeded `None`. - **Source:** spt-core CI failure, 2026-06-07 — Windows runner `hfenduleam` (just booted) panicked the peer pump at the v0.1.1 release gate. ### 5.10 `sudo spt` dead-ends on a user-local install (secure_path) `[REQ-HAZARD-SUDO-SECURE-PATH]` - **Failure:** the elevation-gated commands (`subnet create` / `subnet join` / `show-code`) refuse when unelevated and tell the user to "run as administrator / root". The user types the obvious `sudo spt subnet create FOO` → `sudo: spt: command not found`. `spt` is a user-local install (`~/.local/bin`, `~/.cargo/bin`), and sudo's `secure_path` (a `/etc/sudoers` default) does NOT include those dirs, so a bare command name doesn't resolve under sudo. The guidance is a trap: it names an action that cannot work for the common install shape. Field-hit on KITSUBITO at the v0.1.1 ship. - **Invariant:** elevation guidance on Unix emits the binary's **absolute path** under sudo — `sudo /home/u/.local/bin/spt subnet create FOO` — reconstructed from `current_exe()` + the real argv and shell-quoted. An absolute program path is executed directly; `secure_path` only governs bare-name PATH lookup, so the absolute form always resolves. On an interactive Unix TTY the command auto-elevates (re-execs itself under sudo, the elevated child does the work and `main` de-elevates back); non-interactive or sudo-absent falls back to printing the runnable hint. Never emit a bare-name elevation instruction. - **Companion UX:** the post-de-elevation `DEELEVATED: running as uid N` line is internal state-safety noise — omit it from the user-facing CLI path (it confused the same field user). The detached daemon's own de-elevation log line is fine (it lands in the daemon log, not the terminal). - **Test seam caveat:** the sudo re-exec needs a real `sudo` + TTY (not hermetic). The deterministic guard is the pure `elevation::sudo_argv` / `print_hint_command` (assert an absolute exe path, never a bare name, + shell-quoting on the printed line) and the `decide_elevation_path` matrix (which picks inline-sudo only on an interactive Unix TTY); the exec leg is manual/kitsubito-verified. - **spt-core mapping:** `spt::elevation::{sudo_argv, print_hint_command, decide_elevation_path}` (pure — generalized from the M12-W4 self-elevation seam, 5.11), `spt::cli::{try_auto_elevate, with_elevation_hint}` wired into `cmd_subnet_create` / `cmd_subnet_join` / `cmd_subnet_show_code`; `spt::main` de-elevation drop silenced. - **Source:** spt-core field report, 2026-06-07 — `reavus@KITSUBITO`, `spt` in `~/.local/bin`; the absolute-path `sudo` invocation was confirmed working before the fix landed. ### 5.11 Self-elevating re-launch must re-run verbatim, never widen / inject / loop `[REQ-HAZARD-SELF-ELEVATE]` - **Failure class:** a privilege-gated command (`subnet create` / `join` / `show-code`) self-elevates by re-launching itself with privilege (Windows UAC `runas`, Linux `pkexec` / a terminal-emulator `sudo`, or inline `sudo`). A careless re-launch is a security hole: widening the privilege scope (adding args), resolving the binary by a bare name (a PATH/`secure_path` hijack runs an attacker's `spt`), interpolating a crafted arg into a shell string (`sh -c "… $id …"` injects a second command), or re-elevating the already-elevated child (an infinite UAC/polkit loop). The user's UAC/polkit/sudo prompt is the ONLY consent gate — the mechanism must never bypass or widen it. - **Invariant:** self-elevation re-runs the **EXACT** original invocation with the binary's **ABSOLUTE** exe path — never adding/altering args, never a PATH-resolved bare name, never a shell-interpolated string. Every launcher passes an **argv array** (`Command::new(prog).args([...])`, never `sh -c`); the Windows `ShellExecuteW` params string (which is inherently one string) MSVC-quotes each verbatim arg so `CommandLineToArgvW` round-trips it as a single token. The elevated child drops state back to the user (composes with the 5.7 de-elevation) and **never re-elevates**: `decide_elevation_path` returns `AlreadyElevated` whenever the process is `Elevated`, on every OS (loop-safety). The unprivileged parent never pipes/captures the elevated child's stdout across the privilege boundary — the child is self-contained (on Windows it self-pauses a fresh console via `GetConsoleProcessList` so its output stays legible). The print-hint floor prints the absolute-path command too. - **Test seam caveat:** the real launch needs a UAC/polkit/sudo prompt (not hermetic) — manual-verify. The deterministic guards are the pure `decide_elevation_path` matrix (loop-safety: `AlreadyElevated` on every os; the os×env path order) and the argv builders (`sudo_argv` / `pkexec_argv` / `terminal_argv` assert absolute-exe + verbatim args + array; `windows_runas_params` asserts MSVC-quoting with no `cmd /c` interpolation; the crafted-arg test asserts a shell-metachar arg stays one element / one quoted token). - **spt-core mapping:** `spt::elevation::{decide_elevation_path, sudo_argv, pkexec_argv, terminal_argv, windows_runas_params, print_hint_command, ElevatePath}` (pure), `spt::cli::{try_auto_elevate, launch_uac_window, pause_elevated_console_if_fresh, program_on_path, first_terminal_emulator}` (impure launchers) wired into `cmd_subnet_create` / `cmd_subnet_join` / `cmd_subnet_show_code`. Companions: 5.10 (the Unix abs-path-under-sudo facet) and 5.7 (the elevated child's de-elevation drop, which this composes with). - **Source:** M12-W4 design (subnet QR + self-elevating window), doyle ruling `M12-W4-RULING.md` Q6 — a privilege-escalation feature carries a mandatory hazard REQ. ### 5.12 Native-PTY spawn of a bare program runs the wrong (non-PE) file on Windows `[REQ-HAZARD-WIN-PTY-PROGRAM-RESOLVE]` - **Failure:** `portable-pty`'s ConPTY spawn resolves a bare program name with a `which` that takes the FIRST `PATH` match. A node/npm CLI installs as BOTH an extensionless shebang shim (`ccs`, for Git Bash) and a Windows launcher (`ccs.cmd`) in the same dir; portable-pty picks the extensionless `ccs`, and `CreateProcessW` then tries to execute that non-PE file and fails with **os error 193** ("%1 is not a valid Win32 application"). Live failure: `spt endpoint run claude-spt:ccs` → `CreateProcessW C:\nvm4w\nodejs\ccs` 193 (operator, 2026-06-16). The same bites any harness/shell whose `[session.self]`/`[shell].spawn` names a `.cmd`/`.bat`/`.ps1`-backed command — `CreateProcessW` cannot execute a batch or PowerShell script directly. - **Invariant:** spt-term resolves the program ITSELF before handing it to `CommandBuilder`, bypassing portable-pty's `which`. A bare name is searched over `PATH` × `PATHEXT` (whose default order already prefers `.EXE`/`.COM` over `.BAT`/`.CMD`), then an extensionless fallback. A non-PE target is wrapped in its interpreter: `.cmd`/`.bat` → `cmd.exe /d /c `, `.ps1` → `powershell -NoProfile -File ` (the wrap args precede the caller's args); a real executable spawns directly; an unresolvable name passes through unchanged (never makes a working case worse). Unix is a passthrough — `execve` honours a shebang on an extensionless script. Applied at the ONE `CommandBuilder` chokepoint (`PtySession::spawn_program_in`), so every broker harness + shell spawn is covered. *Caveat:* the `cmd.exe /d /c` wrap inherits cmd's argument-quoting rules for paths/args containing spaces or cmd metacharacters — adequate for the common install-path case; a fully robust cmd-quoting pass is a follow-on if it bites. - **spt-core mapping:** `spt_term::winprog::{resolve_for_pty, resolve_in}` (the pure PATHEXT-precedence kernel + the Windows env wiring), wired into `spt_term::pty::PtySession::spawn_program_in`. Unit: `resolve_in` precedence (`.cmd`-over-shim, `.exe`-direct, explicit-extension, path-order, passthrough) [`winprog.rs`]. - **Source:** field diagnosis 2026-06-16 (operator dogfood, `claude-spt:ccs` bringup) — doyle. ### 5.13 Atomic write leaves data un-synced before the rename → NUL zero-fill on power loss `[REQ-HAZARD-PERCH-RECORD-POWER-LOSS]` - **Failure:** `atomic_write_bytes` was `fs::write(tmp)` + `rename(tmp, path)` with no `fsync`. The rename's directory **metadata** is journaled durable, but the tmp file's **data blocks** are still in the page cache. A hard reset (power loss, forced reboot) between the two flushes lands the rename but loses the data → the file reappears at its **full length filled with NUL**. Field incident: after a machine restart `owlery/hall-a/info.json` was 360 bytes of all-NUL (the nested psyche record 125 bytes all-NUL); `Get-Content` renders blank, `Format-Hex` shows the zero-fill. A wiped-but-present record then read as a live ONLINE endpoint for days (compounded by 5.14). - **Invariant:** for records whose loss is **unrecoverable**, flush data to stable storage **before** the rename publishes the name — `File::create(tmp)` → `write_all` → `sync_all()` → `rename_with_retry`. Then a crash yields the complete old file OR the complete new file, never a NUL husk. (A file of correct length that is ALL-NUL is the diagnostic tell of this class — a non-fsync'd write caught by a hard reset.) **Durability is SCOPED, not blanket.** `fsync`ing *every* atomic write serializes a durable flush behind each of the ~26 `atomic_write` callers — and for `info.json` the flush lands under the per-perch `.info.lock` (the **W1b lock-across-fsync wedge shape**, §6-era) — which stalls daemon bringup 4–6× so the endpoint misses its ONLINE window. Scope the fsync to the record, not the writer: only authoritative per-perch records and one-shot identity material are durable; reconstructible state (registry snapshots, epoch counters, peer caches, the release cache) stays non-durable — a post-crash NUL husk parse-fails to *absent* and is regenerated / re-gossiped, and the 5.14 read-side already makes a corrupt record harmless at every seam. - **spt-core mapping:** `spt_store::atomic::atomic_write_bytes_durable` / `atomic_write_string_durable` are the opt-in durable siblings; the default `atomic_write_bytes` / `atomic_write_string` stay non-durable. Durable callers are exactly `spt_store::info::write_info` (the perch record — the hall-a surface), `spt_store::nodeid` (the node seed — corrupt is node-bricking, never regenerated), and `spt_daemon::machineid` (minted-once machine id — a NUL husk would silently re-mint a different id). Reader-side handling of an already-corrupt record is the sibling 5.14. **Canary:** `attach_wedge_e2e` is the regression guard — a blanket fsync fails it (bringup misses the 20s ONLINE budget); keep durability scoped so it stays green. - **Source:** field diagnosis 2026-07-01 (operator, post-v0.19.0 restart) — counter-39 bug #2; blanket-fsync perf regression pinned + scoped by the gate rig (doyle), same date. ### 5.14 Corrupt info.json read as ABSENT → fail-open readers gossip a wiped perch ONLINE `[REQ-HAZARD-CORRUPT-PERCH-COHERENCE]` - **Failure:** three readers each collapsed a **corrupt** (present-but-unparseable) `info.json` into their fail-open ABSENT default, so a NUL-wiped perch (5.13) read as permanently live: `is_perch_alive` returned `true` (unreadable ⇒ interim-alive), `advertised_status` then saw alive + no resting record ⇒ `Active`, and the daemon self-gossiped that Active row every round (epoch 173k+). Result: `hall-a`, dead since a machine restart, showed ONLINE in `spt whoami` and on every remote picker. - **Invariant:** CORRUPT ≠ ABSENT. A record that EXISTS but stays unparseable across the retry budget is a **destroyed** record — never a live endpoint. `is_perch_alive` reads corrupt ⇒ **not alive** (ABSENT keeps interim-alive parity — the ONE case that stays true); `advertised_status` then lands corrupt in the cold arm ⇒ **Suspended**, never Active/Dormant. Readers that decide liveness/status must branch on the tri-state (present / absent / corrupt), not an `Option` that fuses the last two. - **spt-core mapping:** `spt_store::liveness::{read_raw_state, is_perch_alive}` (the tri-state kernel) and `spt_daemon::registryhost::advertised_status` (cascades to Suspended off the alive fix). `list_self_perch_ids` deliberately still lists a corrupt dir by existence — that is the *visibility* the local-roster fix (counter-39 #3) relies on, not a liveness claim. Candidate sibling seam `is_registry_entry_alive` (corrupt hosted row falls to a daemon-pid probe) is parked — it does not produce the ONLINE gossip. - **Source:** field diagnosis 2026-07-01 (operator, post-v0.19.0 restart) — counter-39 bug #2; sequel to the v0.17.0 W4 presence-truth fix (cold ⇒ Suspended) which a corrupt perch bypassed via false-alive. ### 5.15 Fixed atomic-write tmp name → concurrent writers collide (loser renames a consumed file) `[REQ-HAZARD-ATOMIC-TMP-COLLISION]` - **Failure:** `atomic_write_bytes` staged every write under a **fixed** sibling `{name}.tmp`. Two processes writing the SAME target concurrently — traced at bind ~700µs apart: the daemon's `mutate_info` RMW and `spt api bind`'s `establish_perch` — both create the same `info.json.tmp`; whichever renames first CONSUMES it, and the loser's `fs::rename` hits `NotFound` (os error 2). `NotFound` is non-transient in `rename_with_retry`, so it surfaces as a hard write error: `establish_perch` returns `BindError::Io` *after* having written the record, mock-session's bind-is-fatal check `exit(1)`s, the harness dies, and the endpoint never reaches ONLINE. A microsecond window that existed forever (bare `fs::write` + rename back-to-back) — the 5.13 `sync_all` widened create→rename ~50× (to ~4ms) and made the collision near-certain *exactly at bind*, which is why the durable-perch-record change unmasked it (deterministic wedge, not a perf regression). - **Invariant:** concurrent atomic writers to the same target must never share a tmp name. Stage a **unique** tmp per write — `{name}.tmp.{pid}-{seq}`, `seq` from a process-local static `AtomicU64` (no clock, no rand → resume/replay-safe) — on BOTH the durable and non-durable paths (the collision is generic to `atomic_write`, not the fsync). Keep `rename_with_retry` + best-effort tmp cleanup on rename error. The new names still lack a `.json` extension, so exact-name / `*.json` loaders stay blind to them. - **spt-core mapping:** `spt_store::atomic::write_then_rename` (the shared core behind `atomic_write_bytes`/`_string` and the `_durable` siblings). Regression guard: a ≥4-thread `Barrier`-aligned hammer on one target (`concurrent_writers_never_collide_on_tmp`) — reds on the fixed-tmp code, greens on unique-tmp; a hammer that can't red is decorative. Cross-ref 5.13: the fsync widened the window, the fixed tmp name was the defect. - **Source:** RCA 2026-07-01 (doyle gate rig) — write-trace side-channel + `cmd_bind` step probes pinned `PROBE cmd_bind establish ERR: Io(os error 2)`; explains the counter-39 gate-1 blanket failure, the dummy_harness ONLINE-race DIAGs, and the nondeterminism. Lesson: a widened timing window doesn't create a race, it reveals one. ### 5.16 Unlocked whole-record info.json write races a locked RMW → silent lost update `[REQ-HAZARD-INFO-RMW-LOST-UPDATE]` - **Failure:** `mutate_info` serializes its read→mutate→write under the per-perch `.info.lock` sentinel, but `establish_perch` (`spt::api::startup`) did read→conflict-check→`write_info` with **no lock**. At bind the two writers race (~700µs apart): the daemon RMW reads the PRE-BIND record, bind's `write_info` renames the full record in (`state=live_agent`, `controllable=Some(true)`, `session_id`), then the RMW writes its STALE pre-bind snapshot back plus a `status=online` stamp. The surviving `info.json` is a **pre-bind shape carrying `status=online`** — bringup passes (it sees ONLINE), the broker serves the session, then on child death `reconcile_hosted_liveness` reads `state != "live_agent"` (or `controllable != Some(true)`) and *silently `continue`s* — the dead endpoint is latched ONLINE forever. This resurrects counter-39 #2's dead-but-ONLINE field surface through a brand-new path. Once-loud, now-silent: 5.15's unique tmp turned the previously-`os-error-2` collision into a clean last-writer-wins, and the 5.13 durable fsync (inside the RMW read→write window) made the interleave near-certain on a normal-speed disk. The race predates all of this (v0.19.0-era) — the old fixed tmp made it fail LOUD and non-durable kept the window µs-narrow. - **Invariant:** every `info.json` writer serializes under the one per-perch `.info.lock`. A whole-record write (`write_info`) takes the lock exactly as the RMW (`mutate_info`) does — a unique tmp only makes concurrent writes *last-writer-wins*, which is safe ONLY if the writers are serialized (cross-ref 5.15). A multi-step read→check→write (bind's establish) must hold ONE lock acquisition across all three (a true compare-and-set) — check-then-write with the lock dropped in between still interleaves a stamp. Readers stay lock-free (the atomic rename already gives a complete old-or-new record). Holding `.info.lock` across the durable fsync is ms-scale on these infrequent record writes (the same thing every `mutate_info` already does), NOT the per-keystroke W1b lock-across-fsync shape. - **spt-core mapping:** `spt_store::info` — `write_info` now acquires the sentinel then calls a private `write_info_unlocked` (and `mutate_info` — the public RMW primitive — calls the unlocked writer while holding its own lock, so no double-lock deadlock); `info::establish_locked(perch, build)` runs the bind's read→check→build→write as one locked CAS, called by `spt::api::startup::establish_perch`. The other read-modify-write callers were audited and the two that mutate a load-bearing field were converted to the `mutate_info` CAS: `spt::api::reporting::cmd_boundary` (rc-rebind session-id rotation) and `spt_store::home::adopt_for_unset` (home-subnet adoption; the `is_none()` re-check runs inside the closure). **Deliberately parked (known unlocked-RMW residue, honest coverage):** `spt_msg::listener::write_busy` (BUSY-pid stamp — self-healing: re-marked next delivery, recency next tick) and `spt_store::rename::rewrite_id` (rare operator rename ripple) still do a raw read→write; a lost update there self-heals or is operationally rare, so they are left as follow-ups. `spt_msg::ready::start_homed` (harness-hosted `ready`/`listen` bind) is the same read→build→write *shape* as `establish_perch` but is a single-writer context (the daemon does not host/stamp a harness-hosted ready agent concurrently at its own bind), so it is left as-is — revisit if a daemon-hosted path ever stamps it. Regression guard: `write_info_racing_mutate_info_never_lost_update` — a `Barrier`-aligned RMW-stamp vs full-bind-record write hammer on one perch asserting the full record's fields never vanish under a racing stamp (reds on the unlocked-write code, greens after the lock). - **Source:** RCA 2026-07-01 (doyle gate rig) — differential (baseline PASS / 77beeac+baseline-atomic PASS / fe385f5 2/3 FAIL) isolated the atomic rework as the delta; `reconcile_hosted_liveness` emitting ZERO `LIVENESS_RECONCILE_OFFLINE` lines for the dead victim over 20s pinned the silent-skip. The unique-tmp fix worked (bringup + serve fine) but exposed this deeper pairing. ### 5.17 `powershell` never executes under our detached spawn — a silent no-op that costs every spawn-rig builder the same three runs - **Failure:** a test rig that spawns `powershell -Command …` through `daemon::detached_no_inherit*` (`DETACHED_PROCESS`, no console, no inherited handles) gets a process that **starts and exits having run nothing** — not even a bare `Set-Content`. No error, no output, exit status unremarkable: the rig reads as "my code did not do the thing" when in fact the *fixture* never ran. Measured 2026-07-26 while building the `[service]` supervision gates: three consecutive runs burned on a fixture that could not have worked, each one re-diagnosed as a supervisor bug. `cmd /c` and `sh -c` run fine under the identical spawn, so the no-op is specific to the shell, not to the detachment. - **Invariant (rig discipline, not product code):** spawn-based fixtures use `cmd` on Windows and `sh` on unix — never `powershell`. And find a spawned process's descendants **by parentage** via `spt_store::proc::process_table()` (which returns `(pid, ppid)`), never by asking the child to report them: a grandchild that must cooperate to be found is a rig that cannot observe an *uncooperative* one, which is the case the gate exists for. - **spt-core mapping:** every spawn rig under `crates/spt-daemon` — `servicehost.rs` (`long_running`/`instant_exit`/`noisy_instant_exit` fixtures, the tree-teardown gate) and any future rig over `daemon::detached_no_inherit_env`. No `REQ-HAZARD-*` id and no regression test **deliberately**: the invariant constrains how tests are written, and the only assertion available would be "the OS still refuses to run powershell this way" — an instrument test, which is never requirement evidence. It is numbered here because the cost is paid by whoever writes the *next* rig, and a fact that reads as a bug in your own code is exactly what this document exists to intercept. - **Source:** RESIDENT-SERVICE W1 leg D (todlando, 2026-07-26); ruled into this document by doyle the same day. --- ## 6. Documented regressions (non-obvious invariants) ### 6.1 No flat/nested perch siblings; resolver-routed paths - **Failure:** mixed flat + nested perch layouts confuse which perch is live; cascade-wipe risk. - **Invariant:** one path resolver; never create divergent siblings. - **spt-core mapping:** clean greenfield layout from day one (no migration window) — pick one structure, route everything through the registry. Storage layout deferred to design phase but this single-source-of-truth rule is binding. - **Sister cite:** `src/common/perch_path.rs`; CHANGELOG Phase 25.4. ### 6.2 Soft-cleanup preserves state, removes `ready` - **Failure:** hard-deleting a perch on cleanup loses spool (incl. stored signoff) needed for offline recovery. - **Invariant:** soft-stop removes only the `ready`/online marker; preserves info + spool + dir. Hard-delete only on explicit operator action. - **spt-core mapping:** instance offline-state recovery depends on this; carries to the daemon's stop path. - **Sister cite:** `src/owl/stop.rs`. ### 6.3 Cascade-wipe guard: never delete a parent hosting non-empty children - **Failure:** `doctor --fix` deletes a top-level perch that still hosts in-flight nested Worker/Psyche perches. - **Invariant:** before hard-delete, check for non-empty nested children; if present, soft-clean only and surface the path. - **spt-core mapping:** any destructive maintenance command must check for live child instances first. - **Sister cite:** CHANGELOG v1.11.20 Phase 35.1. ### 6.4 Drop files are single-writer (supervisor-owned), read-only for the mind - **Failure:** the Psyche LLM deletes a commune drop file the wrapper is concurrently reading → race, lost commune. - **Invariant:** drop files (`-commune.md`) are supervisor-owned single-writer; the LLM is read-only; only the supervisor (or explicit operator) deletes them. - **spt-core mapping:** the daemon is the single writer; the harness-invoked mind never mutates drop files. Bake the ownership into the runtime contract. - **Sister cite:** CHANGELOG v1.11.7; `src/live/context.rs:615` (removed delete). ### 6.5 Direct-write precedence guard against stale LLM overwrites - **Failure:** the LLM emits an older snapshot that clobbers a fresher direct write to a context file. - **Invariant:** every context write carries a source+timestamp precedence marker; LLM writes within a protection window after a recent direct write are suppressed (logged); direct writes always proceed. - **spt-core mapping:** cross-node Psyche sync (ADR-0003) makes this multi-writer across machines — the precedence marker must include node identity **plus a per-node version vector** (entries from each node's monotonic `EpochSource`; wall-clock never orders). Distributed rule (ADR-0013, M4-D6): dominate→accept, dominated→drop, **concurrent→surface as durable replicated conflict artifacts + Psyche-reconcile on the active instance's node — never silent newest-wins, never lose either version**. The freshness rule (newest-and-newer-than-mine, per the cross-instance context-freshness feature) is the same guard read as vector dominance. Highest-value carryover for the sync design. - **Sister cite:** CHANGELOG v1.11.6; `src/owl/echo_commune.rs`. ### 6.6 Surfaced context conflicts preserve both versions until dominated - **Failure:** a cross-node concurrent context write (version vectors, neither dominates) gets auto-picked or partially dropped — half a mind silently lost. - **Invariant:** a surfaced concurrent pair is durably preserved (both versions) until a strictly dominating write clears it; no merge/reconcile failure path may discard an unmerged version. Resolution is the Psyche reconcile turn (ADR-0013), whose merged write `join(vA,vB)+bump` dominates both parents — only that dominance clears the artifacts. - **spt-core mapping:** `ContextStore::record_conflict` (tracked `.conflicts/` artifacts, content-hash named, idempotent, replicate like context) / `list_conflicts` / `clear_conflicts` (dominating-write-only). Local working file stays untouched while a conflict is pending. - **Origin:** ADR-0013 design invariant (red-team #7's "wall-clock loses concurrent writes" closed M4-D6), not a sister bug — registered ahead of the wire path so D6c is born conformant. ### 6.7 Broker and brain MUST be separate processes (in-process collapse silently breaks no-endpoint-drop update) `[REQ-HAZARD-BROKER-PROCESS-ISOLATION]` - **Failure:** the daemon hosts the broker as a background *thread* in the single `spt daemon` process (`daemon.rs:165-170`, `Arc` + `thread::spawn(serve)`) instead of a separate process. A brain restart onto a swapped binary then cannot happen without killing the broker thread — closing every PTY, orphaning every harness child, dropping every socket. So `spt update apply` degrades to an in-process `Brain::handoff` no-op: the binary swaps on disk but the running daemon keeps executing the old code until an unrelated restart/logon. The no-endpoint-drop self-update pillar (REQ-UPD-3, ADR-0004) is silently unrealized. Observed live 2026-06-09: `enlyzeam` ran 0.3.0 with 0.3.2 on disk for ~a day, still reproducing the bug the update fixed. - **Invariant:** the broker runs as its own long-lived process that survives every brain restart; the brain restarts onto the new binary and re-attaches via the versioned IPC. A routine (brain-only) update must leave every hosted endpoint untouched at the *process* level — not merely re-subscribe a brain within the same process. The evidence for REQ-UPD-3 / REQ-DAEMON-2 must prove process-level survival (a PTY child + a live QUIC conn survive a brain-process restart onto a swapped binary — SPIKE-01/03 productionized as `int`), NOT the in-process handoff shape that masks this regression. - **spt-core mapping:** restoration is ADR-0018 (next milestone). The current `int` tags on REQ-DAEMON-2 / REQ-UPD-3 are regression-masked and re-point at restoration; the broker becomes the always-up per-machine anchor (seed-lock + liveness + brain supervisor). Two-process supervision, generation custody, durable-deadline loop timing, broker-cursor-of-record, and readiness-gated auto-rollback all hang off this. - **Origin:** unintended spec/impl drift from ADR-0004 (the broker *process* was specced + spiked but built in-process), discovered during the v0.3.2 fleet update verify. Full audit + decisions: `docs/BROKER-BRAIN-SPLIT-RESTORATION.md` (verified) + ADR-0018. - **D1 (restoration skeleton, ADR-0018 Q2/Q3):** the process boundary is restored — `spt daemon run` is the broker process and spawns a supervised `spt daemon brain` child (`brainproc.rs`); the broker survives the brain dying and respawns it (proven in production topology by `crates/spt/tests/brain_split.rs`). The logic loops still run broker-side (D2 migrates them); the `int` process-level survival E2E + the in-process re-point land at D7. - **Closed out (2026-06-11, v0.4.0–v0.4.2):** the two-process model shipped (v0.4.0); the D7 `int` E2E (`brain_survive.rs`) + the N-1 gate prove process-level survival onto swapped bytes and re-pointed REQ-DAEMON-2 / REQ-UPD-3. The v0.4.1 fleet-verify proved this Windows-seamless (hfenduleam: brain pid rolls, broker held, `exe_hash` flips, no manual bounce) but exposed a **Linux** respawn-path gap — the resident broker respawned the brain via per-spawn `current_exe()`, which on Linux follows the `apply` rename to `.old-N` and ran OLD bytes under an `applied` record (`[REQ-HAZARD-BRAIN-RESPAWN-PATH]`, 6.11), fixed in v0.4.2 (respawn from the canonical path captured at broker start + a promotion bytes-gate). Seamless update is now proven on **both OSes** — Windows live (hfenduleam ×2: 0.4.0→0.4.1→0.4.2, broker pid held) and Linux via the CI-gated in-place-rename E2E (`brain_respawn_rename.rs`, kitsubito runner). The fleet runs v0.4.2 on fixed brokers after the project's final two manual bounces. The process-isolation invariant holds; 6.11 is its Linux-respawn-path corollary. ### 6.8 No irreversible durable-state migration before update ready-promotion `[REQ-HAZARD-ROLLBACK-STATE-COMPAT]` - **Failure:** the readiness-gated auto-rollback (ADR-0018 Q7) spawns the *previous* binary against durable state the *new* brain already wrote. The first release that migrates a durable-state schema in place would make the old binary unable to read it — silently bricking rollback exactly when it is needed (a logic-bricking update that can no longer fall back). - **Invariant:** a brain must not irreversibly migrate durable state before it is ready-promoted; equivalently, every pre-ready write must remain readable by the N-1 brain. Schema migrations are gated behind ready-promotion (or written in an N-1-tolerant additive form). - **spt-core mapping:** lands with ADR-0018's auto-rollback. Free to assert now (a 2026-06-09 source audit confirmed zero state-migration code exists); unmintable retroactively once a migration ships. - **D5 conformance (2026-06-10):** the new durable timing state `/deadline-.json` (restoration D5-1) is **additive** — a rolled-back pre-D5 binary does not know the file and simply ignores it (re-phasing on its own flat-sleep cadence, the pre-D5 behavior). No existing-file schema migration, no irreversible pre-ready write → the new file is rollback-N-1-safe by construction. The thing for a future D6 guard to gate is a *migration* of this file's shape, not its introduction. - **D6 guard (2026-06-10, restoration D6-3):** the invariant is now **asserted**, not just noted. The pre-ready durable writes are **enumerated in one place** — `spt-daemon::PRE_READY_DURABLE_FILES` (`rollback_compat.rs`): `deadline-.json` (D5, `DeadlineAnchor`), `applied-state.json` (D6-1, the two-phase `AppliedRecord`), and the generation-stamped `brain.ready` breadcrumb (D6-1b, `{pid, generation}`). A **tripwire unit test** pins each one's additive / N-1-readable contract (load-bearing field names present; an unknown extra field still deserializes), so a *non-additive* pre-ready change (renamed/removed field, or a `deny_unknown_fields`/non-tolerant shape) trips the test and forces the migration **behind ready-promotion** (or into an additive form). **Both new D6 durable files are additive → N-1-safe by construction:** the two-phase `applied-state.json` is a *new* file a rolled-back pre-D6 binary does not know — it ignores it and falls back to the legacy `applied.json`/`last-outcome.json` (which D6 keeps writing alongside for the convergence query); `brain.ready` only gained a `generation` field its sole reader tolerates. It is a tripwire, **not** a migration framework (activate-don't-pre-fail) — the day a real migration is needed, this guard is the wire it trips. - **Origin:** verification amendment `[V1]` (agent `doyle`) on `docs/BROKER-BRAIN-SPLIT-RESTORATION.md`. - **Closed out (2026-06-11):** the readiness-gated auto-rollback shipped (v0.4.0) and the pre-ready durable-file registry + tripwire guard (D6-3) hold. v0.4.2 added a promotion **bytes-gate** that turns a wrong-bytes respawn into an auto-rollback rather than a false `applied` record — strengthening the rollback path the same release exercised across the fleet. No in-place schema migration has shipped, so the invariant remains **asserted, not yet exercised by a real migration** (correct — activate-don't-pre-fail); the tripwire is the wire it trips the day one is needed. ### 6.9 Resume-mode brain: a blocking spawn/command wait silently discards OTHER sessions' output - **Failure:** a resume-mode brain (per-session `session_cursors` populated by `resume_sessions`) drives `Brain` over **blocking** `read_event` calls. Any command that loops `read_event` until its own reply — `spawn_session_pid` waiting for `Spawned`, `net_status`, `sessions`, etc. — calls `read_event` on *every* interleaved frame, so an OUTPUT frame for a **different** session is **cursor-processed** (its `session_cursors` entry snaps forward; the broker already counted it delivered via `delivered_through` on the live-send) and then **discarded** by the waiting loop's `_ => continue`. Cursor advanced + content dropped = that chunk is gone for the downstream consumer and the broker will **not** re-send it (resume reads from the delivered cursor, ADR-0018 D4). One session's spawn/command starves another session's output. - **Invariant:** the daemon-hosted multi-session event loop must not consume a session's OUTPUT inside another session's blocking wait. The **live-agent adapter milestone must restructure the brain event pump** so command/`spawn` is non-blocking (a single demux loop owns `read_event` and routes every frame to its session's consumer), OR a blocking wait must re-queue/route the frames it reads for other sessions rather than dropping them. - **spt-core mapping:** **unreachable today** — the supervised daemon brain hosts no PTY sessions and spawns none; a single-session seat (legacy, empty map) has no "other session" to starve. Surfaces the moment daemon-hosted sessions land (the live-agent adapter), which must rebuild the blocking `read_event` loop regardless (N interactive sessions cannot share one blocking reader). Recorded so that redesign inherits the constraint rather than rediscovering it. No machinery now (would be untested dead code, activate-don't-pre-fail). - **Origin:** surfaced by the D4-2b resume-harness CI flake root-cause (agents `todlando` + `doyle`, 2026-06-10); sibling of `[REQ-HAZARD-BROKER-PROCESS-ISOLATION]` 6.7. ### 6.10 Phase-significant loop timing must be a durable absolute-deadline grid, not phase-relative sleep `[REQ-HAZARD-BROKER-PROCESS-ISOLATION]` - **Failure:** a periodic loop that sleeps a flat `period` each iteration (`pulse_tick` then `sleep(pulse_period)`) is **phase-relative** — every brain restart silently re-phases the grid to the restart instant. Under the seamless-update model (the supervisor respawns the brain onto a swapped binary, ADR-0018 D3-3), a routine update would shift the cadence of every phase-significant loop, and continuity cannot ride a brain→brain frame (the outgoing brain is gone before the new one starts — the same constraint that moved session continuity to the broker in D4). - **Invariant:** phase-significant periodic timing lives as durable absolute-deadline state on disk (`(anchor, interval)`), rehydrated on every brain start, with fires **derived functionally** (`next_fire = anchor + interval·⌈max(0,now−anchor)/interval⌉`) and **no per-fire write**. An **Update** restart re-reads the anchor and keeps deriving (phase preserved, lands mid-grid); a **Crash**/**Cold** restart re-bases the anchor to `now` (phase reset acceptable — the loop is idempotent catch-up). The update-vs-crash decision is the D3 spawn-time `StartReason`. **One-shot** (alarm) deadlines persist their absolute `target-time` at creation and **never reset** on any restart ("remind me at 3pm" is a commitment) — the asymmetry vs the periodic crash-reset is the rule. **[V4]** Only phase-significant loops convert; idempotent pump cadences (stagger-from-due-now) need none — converting them would re-add the per-loop writes Q4 minimizes. - **spt-core mapping:** ADR-0018 Q4/V3/V4, restoration D5. Mechanism in `spt-daemon::deadline` (`DeadlineAnchor` periodic + `OneShotDeadline` rule-only pure helper); the pulse loop (`lifecycle::run_pulse_loop`) consumes it. The one-shot **machinery** (a durable in-daemon alarm scheduler) is the deferred alarm port (`docs/DEFERRED.md`) — the daemon has no one-shot consumer today, so building the timer now would ship untested dead code (activate-don't-pre-fail); D5 fixes the *rule* as a tested-unwired helper, the port builds the *scheduler*. - **Origin:** ADR-0018 Q4 + verification amendments `[V3]`/`[V4]` (agent `doyle`); D5 plan vet (agents `todlando` + `doyle`, 2026-06-10). ### 6.11 Brain respawn must exec the APPLIED bytes, not the renamed old binary (Linux `current_exe` follows the apply-rename; readiness ≠ new-bytes) `[REQ-HAZARD-BRAIN-RESPAWN-PATH]` - **Failure:** the broker respawns the brain candidate from `std::env::current_exe()` resolved **per spawn** (`brainproc.rs:817`). `spt update apply` swaps the binary by renaming the running file `spt` → `spt.old-N` and writing the new bytes at `spt`. On **Linux**, `current_exe()` = `readlink(/proc/self/exe)` is **inode-tracking** and follows the rename to `.old-N`, so the resident broker respawns the brain onto the **OLD** bytes — the brain comes up ready (readiness passes), the trial **promotes**, and the daemon records `applied:N` while still running the previous version. New code does not run; the record is optimistically wrong (the enlyzeam-class record/reality divergence, now provable via `exe_hash`). **Windows** dodged it — `GetModuleFileName` returns the path string captured at process start, so the swap lands new bytes — which is why v0.4.1 went green on hfenduleam and red on kitsubito. Observed live 2026-06-11 (kitsubito ran v0.4.0 bytes under an `applied:8` record after a brain-only `apply`). - **Invariant:** the candidate-binary default is the canonical exe path **captured once at broker start** (before any `apply` can rename under the process), never a per-spawn `current_exe()` — giving Linux the path-at-start semantics Windows already had. AND promotion is **bytes-gated**: a trial promotes only if the candidate's stamped `brain.ready` `exe_hash` equals the staged artifact's hash for this platform; a mismatch is a failed trial → auto-rollback + loud notif (readiness alone is not proof the new bytes run). If either hash is absent the gate degrades to readiness-only (N-1-safe for pre-metadata releases / a missing breadcrumb) but emits `PROMOTE_BYTES_UNVERIFIED` so a disarmed gate stays field-diagnosable. - **spt-core mapping:** v0.4.2 fix (`V042-PLAN.md`). Half 1 = `spawn_brain_supervisor` canonical-exe capture threaded into `spawn_brain_child`'s `None` default; Half 2 = the promotion bytes-gate in `supervise_brain`'s `Promoted` arm (`TrialEnv::ready_exe_hash` + `staged_artifact_hash`). The rollback path (`Some(.old-N)` selection) is unchanged. Sibling of 6.7 — the broker *process* is correct; the bytes it respawned the brain ONTO were not. - **Origin:** ADR-0018 Q3 silently assumed `current_exe()` path-string semantics; surfaced by the v0.4.1 fleet-roll `exe_hash` bytes assert (agents `todlando` + `doyle` + `deployah`, 2026-06-11). ADR-0018 Q3 amended. --- ## 7. Boundary & delivery integrity (added 2026-05-31 — Stage A red-team) These were absent from the sister-project harvest; codex surfaced them as load-bearing gaps for spt-core's new daemon/network surface. ### 7.1 Local `api` mutation auth `[REQ-HAZARD-LOCAL-API-AUTH]` - **Failure:** any local process calls `spt api bind|state|session-end|history-log|poll` and binds, ends, injects, or spoofs the state of an endpoint it does not own. Local untrusted processes are explicitly in scope (shells, third-party adapters). - **Invariant:** every `api` *mutation* is authenticated to an endpoint/session — per-endpoint link token or OS-credential binding. An unrelated local process cannot bind, inject, end, or spoof state. - **spt-core mapping:** the `api` subcommand surface (PRD R-API-*) + broker IPC. - **Source:** codex Stage A #13 (`docs/reviews/STAGE-A-codex-redteam.md`). ### 7.2 Idempotent delivery across brain restart `[REQ-HAZARD-RESTART-IDEMPOTENT]` - **Failure:** broker queues, spool rows, PTY injection, remote streams, and file transfers cross the broker↔brain boundary; a brain restart duplicates or drops a side effect. - **Invariant:** every side effect crossing the boundary carries a durable ID + replay rule; replay after restart is exactly-once / idempotent. Crash the brain before/after spool write, before/after PTY write, mid-transfer, mid-registry update — no dup, no drop. - **spt-core mapping:** broker↔brain IPC (ADR-0004), self-update handoff. - **Source:** codex Stage A #14. ### 7.3 Psyche outbound capture + sanitization `[REQ-HAZARD-PSYCHE-OUTBOUND-PROXY]` - **Failure:** the Psyche's sole outbound channel is its **stdout** (`` intents — ADR-0012). Two ways to break it: (a) a **null-stdout / detached** live-Psyche driver silently **discards every reply and notify**; (b) the daemon relays a Psyche-supplied `from=`/target **unchanged**, letting a sandboxed Psyche **spoof identity** or address arbitrary endpoints. - **Invariant:** the live-Psyche turn driver **MUST capture stdout** (a bounded, stdin-fed, stdout-captured invocation — **never** `Stdio::null()`); the daemon **MUST strip** every Psyche-supplied `from=`/target/routing attribute, **re-stamp `from=`**, and **constrain routing** — `reply` → the inbound message's structural sender (its `from`) only, `notify` → the agent's own user/subnet only. Body validated per 4.1. - **spt-core mapping:** the live-Psyche turn driver + daemon outbound relay (ADR-0012); `spt-proto::event` type taxonomy (`+reply`/`+notify`). The interim `runtime::spawn_session` `Stdio::null()` path is **not** the live-Psyche driver. - **Source:** grill-with-docs 2026-06-03 (uncovered by prior design passes); sister `src/live/wrapper/claude.rs` (sandbox `["Read","Write","Edit"]` + `parse_markers`). ### 7.4 Per-agent pulse/psyche/echo scheduling must not serialize across agents `[REQ-HAZARD-DAEMON-SCHED-NONBLOCKING]` - **Failure:** echo-commune (`run_bounded_stdin`) and the live-Psyche turn driver (D7.5) are **bounded LLM calls that block their calling thread** until the child answers or the timeout fires. Today each agent drives its own pulse from its **own process** (`spt/src/api/{live,startup}.rs`), so blocking is isolated. When the daemon hosts **N per-agent loops** (ADR-0004 target; the `run_pulse_loop` fan-out is currently def+test only), a **single serial driver** that calls these invocations inline lets one agent's slow/hung LLM call **stall every other agent's heartbeat, commune, and reply** — the per-call timeout bounds the worst case *only* when the work is isolated; serial makes the stalls additive. - **Invariant:** each agent's bounded LLM-bearing work (echo-commune summarizer, Psyche turn) runs on its **own thread / off the shared scheduler** — no single-threaded driver iterating all agents may call a blocking invocation inline. One agent's slow/timed-out call must not delay another agent's next tick beyond tolerance. - **spt-core mapping:** the daemon's multi-agent pulse/psyche hosting (ADR-0004, "all Psyche/pulse loops" consolidated); `run_pulse_loop` fan-out; echo-commune + the D7.5 Psyche driver. - **Source:** grill-with-docs 2026-06-03 (forward invariant — the multi-agent fan-out is not yet wired). Distinct from ADR-0002 SERIOUS #6 (crash blast-radius, not scheduling latency). ### 7.5 WAN-inbound origin is transport truth, never payload `[REQ-HAZARD-WAN-ORIGIN-AUTH]` - **Failure:** the ADR-0009 access whitelist gates **unsolicited wire inbound by origin node**. If the gate's subject is read from record bytes (an `origin_node`/`from`/`node` field a sender wrote), any sender forges any origin and the whitelist is decoration — same spoof class as 7.3's Psyche-supplied `from=`, now on the cross-node surface. - **Invariant:** the origin the gate (and detection/UX — "node X is driving") consumes is the **QUIC handshake-proven remote node id** (iroh `EndpointId` == Ed25519 node pubkey, the REQ-NET-1 identity binding) read from the **broker's conn/stream table** (`NetStreamInfo::remote_id_hex`), never from payload. Wire records carry **no origin field by design**; a forged one decodes as an ignored unknown field and influences nothing. `from` inside a record is reply-routing metadata only — never an authorization subject. - **spt-core mapping:** `spt_net::net::wanmsg::WanMessage` (no origin field) + `spt_daemon::wan::receive_wan` (origin parameter sourced from the stream table) + every future wire-inbound consumer (D5b attach, D5c transfer, D8 notifs). - **Source:** M4-D5a design (ADR-0009 consequence: the gate must bind to the transport identity). - **Mesh note (ADR-0017, 2026-06-08):** preserved verbatim. The mesh never relays third-party rows, so a record's author is **always** the QUIC-handshake-proven connection origin. The new **membership proof** (seed-proof) is itself channel-bound to both handshake-proven pubkeys — the authorization subject stays transport truth, never payload. - **Sender-stamp note (W2b, `REQ-MSG-SENDER-STAMP`, 2026-07-29):** the invariant above is preserved for the **origin node** and for **`from`**, and both sentences stand verbatim — the gate's node subject is still transport truth, and `from` is still never an authorization subject. One field is now carved out of "a forged one decodes as an ignored unknown field and influences nothing": `WanMessage.sender_proven` IS decoded and **acted on** as the access chain's tier-1 sender subject. It does not weaken this hazard, because it is **daemon-stamped from the sending session** (never `--from`, which a caller controls) and it can only ever name a *sender endpoint* — never the node. Forging it therefore requires a malicious member node, which `REQ-MSG-6`'s ratified boundary places out of scope, while the in-scope adversary (an **agent** passing `--from`) is defeated. Absence abstains, so the tier's activation changed no N-1 decision. See `docs/FAULT-MATRIX.md` row 11b. ### 7.6 Pump brain-IPC reads must be deadline-bounded (a blocked read wedges the whole pump) `[REQ-HAZARD-PUMP-IPC-DEADLINE]` - **Failure:** the peer pump is a SINGLE thread driving every leg (registry/notif/sync/update) against every peer over ONE brain-IPC client. Its reply reads (`net_open_stream`, `net_stream_send`, `net_dial`, and the sync/update pull `read_event` loops) were `loop { read_event() }` with no deadline. When a peer's QUIC path black-holes, the broker's stream-open/send awaits the dead peer and never sends the reply, so the brain's `read_frame` blocks FOREVER and the pump freezes mid-round. The heartbeat (loop-top) stops and the stall warning fires honestly, but `supervise_pump` cannot rescue it: the supervisor catches a panic / error / clean return, and a BLOCKED thread never returns. Observed twice — 2026-06-07, then a **2.2h wedge on hfenduleam (2026-06-11)** where the broker stayed responsive to `daemon status` while the pump thread sat dead. - **Invariant:** in PUMP mode the brain carrier is **SPLIT at construction** — a dedicated `pump-ipc-reader` thread does blocking `read_frame` on the `RecvHalf` and forwards each framed result down a channel; the main thread writes on the `SendHalf` and reads with `Receiver::recv_timeout`. Every IPC reply read is bounded by a per-call **total-wait** deadline (`PUMP_PEER_IO_TIMEOUT` = 30s, > any legitimate round-trip, < the 60s QUIC idle; re-armed on stream progress for the streaming pull legs so a healthy long sync is never killed — only a ≥30s silence). **Mechanism note (Windows):** the carrier is a reader-thread + channel, NOT a non-blocking socket + poll — interprocess 2.4.2 on Windows named pipes has no portable read timeout (`set_recv_timeout` → `no_timeouts()`) and its `set_nonblocking` uses deprecated `PIPE_NOWAIT`, which corrupts mid-stream (proven by the mesh E2E). Blocking reads work on both OSes; the channel supplies the deadline. A read that exceeds the deadline returns `io::ErrorKind::TimedOut`, treated as a **POISONED client** (a late reply could bind the wrong stream id in a later call — gotcha-#1-adjacent): it BUBBLES out of the round → `run_peer_pump` returns Err → `supervise_pump` restarts the pump with a fresh brain client + conn cache + reset WorkerLasts (the §V4 stagger re-primes every leg). NEVER a per-peer retry. An ordinary error (the broker REPLIED with one) stays a per-peer abort + conn drop + redial. **Leak watch (accepted, not fixed):** a restart abandons the old reader thread parked in `read_frame` (split halves share one OS handle → on a named pipe the broker may never signal the disconnect); bounded to ONE thread per actual wedge (the post-restart conn cache is fresh — the dead peer is re-dialed, not re-wedged), diagnosable by the reader's spawn/exit log lines, and fully cured by the broker-side B-half (§7.8, `REQ-HAZARD-BROKER-QUIC-DEADLINE`), shipped in v0.8.3 — with the broker bounding its QUIC await, the brain's read returns promptly (an ordinary error) so the reader thread is never left parked. - **spt-core mapping:** `Brain::cold_start_pump` (splits the carrier + arms the deadline) / `BrainConn::Split` (the `SendHalf` + reader-thread channel) / `call_deadline` / `read_event_until` / `read_frame_until` (the `recv_timeout` dispatch), `pump::run_peer_pump` (connects in pump mode) + `pump::peer_outcome` (the tier-split), the `request_sync`/`request_update` pull loops (deadline re-armed on progress). The broker-side half — the broker must never make a brain wait unbounded on a QUIC op (bound the `net_dial`/`open_stream`/`send_stream` handlers) — shipped in v0.8.3 as §7.8 (`REQ-HAZARD-BROKER-QUIC-DEADLINE`). - **Source:** field diagnosis 2026-06-11 (the 2.2h hfenduleam wedge); doyle ruling A-now / B-deferred. The stall warning (M8 decision 23) was the band-aid; this is the fix. The B-half landed v0.8.3 (§7.8) after the 2026-06-16 recurrence. ### 7.7 A slow/dead/hostile remote VIEWER must never stall the controller, child, or drain `[REQ-HAZARD-VIEWER-ISOLATION]` - **Failure:** the W2.5 controller/viewer model lets ANY number of read-only `--view` attachers ride one session's broker `OutputLog`. The single drain thread fans each output chunk to every attacher. If a viewer's socket is fanned out with a **blocking** write under the log lock (the controller's authoritative path), one wedged viewer (a slow terminal, a black-holed WAN peer, a hostile non-reader) stalls the drain — freezing the controller's stream and backing up the PTY child. A single watcher must never be able to degrade or hang the driver. - **Invariant:** the drain writes the **controller** on the authoritative blocking bounded path (it alone advances `delivered_through`), but each **viewer** gets an **isolated bounded SPSC queue + a dedicated writer thread**; the drain `try_send`s under the log lock and **evicts** any viewer whose queue is `Full` (fell behind the live stream) or `Disconnected` (its writer died on a dead socket) — the drain thread **never touches a viewer socket**, so no viewer write can backpressure it. A **soft cap** (`MAX_VIEWERS`) bounds the writer-thread count (a viewer attach beyond it is refused). Viewer eviction never perturbs the controller stream, the `delivered_through` cursor, or the child. Ring **replay-at-attach** is owned by the writer thread (not the bounded live queue), so a viewer attaching to a busy session is not spuriously evicted. - **spt-core mapping:** `OutputLog::append` (controller blocking + `viewer_send_evicts` `try_send` fan-out), `OutputLog::add_viewer` (bounded `sync_channel(VIEWER_CHANNEL_DEPTH)` + `viewer_writer` thread), `MAX_VIEWERS` soft cap, `ViewerSink`. Unit: `viewer_overflow_or_disconnect_evicts_never_blocks`. Int: `wedged_viewer_does_not_stall_controller` (a non-reading viewer is evicted while the controller keeps receiving past a 200KB burst). - **Source:** M12 W2.5 controller/viewer model (doyle ruling 2026-06-14, Q1). ### 7.8 The broker must never make a brain wait UNBOUNDED on a QUIC op (the pump-IPC-deadline B-half) `[REQ-HAZARD-BROKER-QUIC-DEADLINE]` - **Failure:** the broker's brain-facing QUIC handlers (`dispatch_net_dial` / `dispatch_net_stream_open` / `dispatch_net_stream_send`) call into `NetHost::dial` / `open_stream` / `send_stream`, whose iroh awaits (`endpoint.connect` + `prove_membership`; `open_bi`; `write_all`/`finish`) had NO bound of their own. A dead/black-holed roster peer (its process gone, or a mixed-pair that accepts the conn but never answers the seed-proof) makes the broker await its QUIC path FOREVER, so the brain escapes only via its OWN 30s read-deadline (the 7.6 A-half) — a 30s stall + a full pump restart EACH round, and the supervised restart re-dials the SAME dead peer and re-wedges. Root cause of the 2.2h hfenduleam wedge (2026-06-11) and its recurrence (2026-06-16). - **Invariant:** every brain-waiting QUIC op is wrapped in a broker-side deadline (`NetHost::bounded_block_on` → `tokio::time::timeout`, `BROKER_QUIC_OP_TIMEOUT_MS` = 10s). On elapse the future is DROPPED (cancelling the in-flight connect/stream op, so nothing is half-registered) and a non-`TimedOut` `io::Error` is returned, which the broker REPLIES as an ordinary error frame. The bound (10s) sits comfortably above any legitimate LAN/relay round-trip and 20s below the brain's 30s `PUMP_PEER_IO_TIMEOUT`, so the BROKER fires FIRST — the brain reconstructs `ErrorKind::Other` (its `net_dial`/`net_open_stream`/`net_stream_send` map a broker error reply to `io::Error::other`), NOT its own read-deadline `TimedOut`, so `pump::peer_outcome` takes the ordinary per-peer arm (drop conn + redial next tick), the round CONTINUES and the heartbeat keeps advancing. **Never the brain's read-deadline:** that `TimedOut` is the 7.6 poison → supervised-restart path this fix exists precisely to AVOID. **Exactly-once preserved:** a timed-out journaled op fails INSIDE its `apply_once` closure (the QUIC call is made there), so no phantom `conn_id`/`stream_id` is recorded (`effect()?` propagates before `applied.insert`) and a fresh tick re-dials cleanly — no dedupe into a dead conn. **Happy path unchanged:** a live peer completes with zero added latency; the bound only bites a non-responsive peer. - **spt-core mapping:** `NetHost::bounded_block_on` (the timeout wrapper) wrapping `NetHost::dial` / `open_stream` (QUIC branch) / `send_stream`; `BROKER_QUIC_OP_TIMEOUT_MS` + `set_quic_op_timeout` (test override, off `NetConfig` — mirrors `set_roster_exchange`). Unit: `bounded_block_on_cuts_a_never_completing_op_with_an_ordinary_error` (a never-completing op → prompt non-`TimedOut` error; a ready op untouched). Int: `dial_to_a_black_holing_peer_fails_with_a_bounded_ordinary_error` (the broker REPLIES an ordinary error within the bound + exactly-once-on-timeout: journal un-applied, conn table empty, clean redial) and `pump_survives_a_black_holing_peer_heartbeat_advances_no_restart` (the production pump against a dead peer — heartbeat monotonic-advances, `run_peer_pump` exits Ok, no supervised restart). The `peer_outcome` ordinary-vs-`TimedOut` tier-split itself is unit-covered at 7.6. - **Source:** the 7.6 B-half — deferred 2026-06-11 (doyle ruling A-now / B-deferred, DEFERRED.md) and shipped in v0.8.3 after the 2026-06-16 hfenduleam recurrence. ### 7.9 A daemon-state wire change needs a deliberate BROKER restart (the broker is resident across a brain self-update) `[REQ-HAZARD-BROKER-SEED-WIRE-SKEW]` - **Failure:** the broker serves the seed-control channel and is RESIDENT across a brain-only self-update (ADR-0004's no-terminate-during-update pillar forbids auto-killing it — 6.7). A self-update that changes a daemon-state WIRE FORMAT — e.g. the v0.9.0 adapter-agnostic `Seed` (the `adapter` field dropped) — therefore lands a NEW-version CLI talking to the STILL-RESIDENT OLD broker. The old broker cannot deserialize the new `Seed` (its formerly-required `adapter` is absent), so it drops the seed-control conn without acking; the CLI's `put_seed` ack-read hits EOF and surfaces a raw `UnexpectedEof` "failed to fill whole buffer" — a cryptic footgun that hides the real cause (perri PREP-4 FINDING 1: v0.9.0 CLI ↔ stale 0.8.x broker). - **Invariant:** (a) spt-core surfaces an ACTIONABLE diagnostic on the seed-ack EOF — naming the stale-broker cause + the fix (`spt daemon stop`; the broker restarts on the next `spt api` call) — never the bare io error (scoped to `UnexpectedEof` on the seed-ack path, so it never mis-fires on an unrelated error like a refused connect). (b) A daemon-state wire change requires a DELIBERATE full broker restart; this is NOT automatic — ADR-0004 forbids auto-killing the resident broker, and a brain-only update keeps the old broker. (c) FORWARD discipline: daemon-state / `Seed` schema changes stay ADDITIVE + serde-default, so a resident OLD broker tolerates a NEW CLI across a brain-only update. (This would NOT have rescued 0.9.0 itself — the old broker's `adapter` was a REQUIRED field, so no additive tolerance could read the new bytes; for a wire change that removes/renames a required field, the operative rule is the broker restart.) - **spt-core mapping:** `startup::seed_fail_message` (the `UnexpectedEof` → actionable-hint branch) fired from `cmd_seed`'s `put_seed` error arm; the broker's seed-control residency (`seedmap::serve_seed_control`, held across brain restarts — 6.7). Unit: `seed_fail_eof_gives_actionable_stale_broker_hint` (EOF → the `spt daemon stop` hint naming the stale broker; a non-EOF kind → the plain message, no mis-fire). - **Source:** perri PREP-4 FINDING 1 (v0.9.0 dogfood) → v0.9.1. ### 7.10 A VIEW is independent from the endpoint — closing the launching tab must NOT reap the daemon-hosted harness `[REQ-HAZARD-VIEWER-CLOSE-DETACH]` - **Failure (Windows):** `spt endpoint run` autostarts the daemon (`ensure_running` → `detached_no_inherit`), which INHERITS the launching terminal's Windows Job Object. Windows Terminal / VS Code place the shell AND every descendant in a Job with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`; closing the tab drops the job's last handle → the OS reaps the daemon + its broker-spawned ConPTY harness subtree. The `rc` pump detaching should end ONLY the viewport; the harness must keep running + stay re-attachable. (ConPTY isolation itself is already correct — portable-pty builds the pseudoconsole in the daemon; the leaking lifetime binding is the Job Object, not the console.) - **Invariant:** both daemon spawn paths request `CREATE_BREAKAWAY_FROM_JOB` (0x0100_0000), best-effort with an in-job FALLBACK on `ERROR_ACCESS_DENIED`(5) / `ERROR_INVALID_PARAMETER`(87) so a breakaway-denying job NEVER regresses the spawn. **A real job CAN deny breakaway** (proven: the cargo/CI runner's own ancestor job ACCESS_DENIES it), so efficacy against the real terminal is UNKNOWN until measured. **int stage = OPERATOR MANUAL ACCEPTANCE, not CI** (doyle ruling 2026-06-18): the runner sits inside a breakaway-denying job and every test-created job nests inside it → a faithful "harness survives tab-close" test is a guaranteed FALSE-RED; the two units (escape-where-permitted self-skip + fallback-where-denied) are the CI evidence; `required_stages` stays `[doc,impl,unit]`. The daemon-OWNED harness Job is the **L4 daemon-stop reap** backstop ONLY — NOT tab-close survival (a job nested in the terminal's kill-on-close job dies with it). **Backstop candidate (design-only, build ONLY if the operator measures breakaway DENIED + daemon dies):** re-parent the cold-start daemon spawn OUT of the terminal job via a job-neutral creator — WMI `Win32_Process.Create` (owned by WmiPrvSE, outside the terminal job; synchronous, returns pid) preferred over a `schtasks` one-shot. - **spt-core mapping:** `daemon.rs::detached_no_inherit` + `deelevate.rs::create_with_token` (the breakaway flag + fallback). Units: `detached_no_inherit_falls_back_under_a_breakaway_denying_job` (no-regression — the shared runner exercises the fallback directly), `breakaway_spawn_escapes_a_kill_on_close_job` (the OS escape mechanism — self-SKIPS where the ancestor job forbids breakaway). Unix: the daemon's `setsid` session-detach already keeps a closing terminal's SIGHUP off its children (guard test, no code). - **Source:** v0.12.0 real-harness defect (operator) → v0.12.1 L1 @5ae68f8; doyle design+int ruling 2026-06-18. ### 7.11 A dead PTY child + a dropped operator pump must NOT wedge the broker for other clients `[REQ-HAZARD-ATTACH-WEDGE]` - **Failure (hypothesized, v0.12.0):** a legitimately dead PTY child (crash/kill) plus an `rc` pump dropped without a clean detach (closed tab) was thought to make the broker's loopback forward `write_all` block forever on a full 64 KB duplex, park a worker in the 2-worker net runtime, saturate both, and stall every new attach / `endpoint run` (with `daemon stop` unable to join). - **Invariant — DISPOSITION = PROVE-DON'T-CHANGE** (doyle GATE-PASS @e883f45, 2026-06-18): the post-L0 code ALREADY prevents the wedge; NO fail-fast / worker-count code was added. (1) `serve_attach` forwards fire-and-forget (`net_stream_send` `op_id=None`) and the broker-side `send_stream` is already deadline-bounded (`bounded_block_on`, `BROKER_QUIC_OP_TIMEOUT_MS` = 10s — hazard 7.8), not forever. (2) the loopback duplex is drained broker-INTERNALLY by the operator row's OWN read pump (`nethost.rs` `RecvHalf::Loopback`), which for an ordinary attach stream (`retentive_cap == 0`) NEVER parks → `peer_w` never backs up on a dead `rc` (a dead `rc` is just a dropped IPC subscriber against a bounded, EVICTING ring). (3) `bounded_block_on` = `runtime.handle().block_on` → parks the BROKER DISPATCH thread, not a net worker, so worker-pool exhaustion cannot occur. A dead spt-hosted endpoint is OFFLINED within one reconcile tick on abrupt child death (the broker exit-waiter `wait()` reaps the session even on `taskkill /F` → `reconcile_hosted_liveness` clears the `status=online` latch). - **spt-core mapping:** int `crates/spt/tests/attach_wedge_e2e.rs` (REAL detached daemon + dummy-harness fixture): serve the victim (rc sees its tick), abruptly kill rc (dropped pump) + kill the PTY child → a NEW endpoint still comes online + is served (no wedge), the dead endpoint is offlined within a tick (`LIVENESS_RECONCILE_OFFLINE`), `daemon stop` bounded. Leans on 7.8 (the QUIC-op deadline) + 7.7 (viewer isolation). - **Source:** v0.12.0 real-harness finding (operator) → v0.12.1 L2 @e883f45; doyle GATE-PASS 2026-06-18. ### 7.12 Controller output must NOT be written inline on the drain thread — a backed-up controller wedges the session `[REQ-HAZARD-INJECT-CONTROL-COEXIST]` - **Failure (v0.12.x, operator dogfooding + doyle /diagnose 2026-06-19):** `OutputLog::append` fanned each live chunk to the CONTROLLER via a SYNCHRONOUS, blocking `write_frame` held INLINE on the session's single drain thread while `Mutex` was locked (viewers already had a dedicated writer thread + bounded evicting channel). A backed-up controller socket — a slow operator, or the full 64 KB `rc` loopback duplex under heavy TUI redraw — parked the drain thread WITH THE LOG LOCK HELD: output + keystroke-echo stalled and every attach / resize / `KIND_SESSIONS` that needs the log lock blocked FOREVER, while the broker process stayed alive. Fires on NORMAL interactive `rc` use under heavy output (not only message injection); REOPENED the wedge facet of 7.11 (dead-child backpressure only). - **Invariant:** controller delivery runs OFF the drain thread — a dedicated controller writer thread + bounded channel (the 7.7 viewer_writer pattern) does the blocking socket write; the drain hands each chunk off with a BOUNDED, OFF-LOCK send (deadline → detach + `clear_controller`, never park forever, never silently evict a LIVE operator's authoritative view). The controller is AUTHORITATIVE (unlike a viewer): its writer advances the `delivered_through` resume cursor (atomic, only-on-success, monotonic). `clear_controller` is the ONE unlatch path (clears `driven_by`, drops the sink) — W5's reconcile self-heal reuses it. - **spt-core mapping:** impl `broker.rs` `OutputLog::append`/`controller_writer`/`become_controller`/`ControllerJob::deliver`/`clear_controller`; int `crates/spt-daemon/tests/inject_control_wedge.rs` (a fully-backed-up controller keeps `KIND_SESSIONS` answering = no wedge); unit the bounded-deliver + monotonic-cursor kernels. The input-side parks (write_input `write_all` on a full buffer; DSR-answer writer-mutex contention) are BENIGN on Windows ConPTY (absorbs a large inject), real only on Unix forkpty → bounded by W2's atomic-write substrate. - **Source:** v0.12.x operator wedge → v0.13.0 W1 (doyle GATE-PASS 2026-06-19). ### 7.13 `spt rc` must SWAP Windows legacy-console Backspace/Ctrl+Backspace (`^H`↔DEL); do NOT enable VT console input `[REQ-HAZARD-RC-INPUT-KEY-ENCODING]` - **Failure (operator dogfooding):** `spt rc` is a raw verbatim stdin byte pump; the legacy Windows console delivers Backspace as `^H` (0x08), and Claude Code maps `^H` → backward-kill-word, so every Backspace deletes a whole word. Confirmed bytes (operator HITL capture, real Windows Terminal): Backspace=0x08, Ctrl+Backspace=0x7f. - **REJECTED fix (dc07c39, reverted):** enabling `ENABLE_VIRTUAL_TERMINAL_INPUT` on the stdin console BACKFIRED — on Windows Terminal that flag yields **win32-input-mode**, not legacy xterm VT. Every key then arrives as a 6-field `ESC[Vk;Sc;Uc;Kd;Cs;Rc_` key-down/up record: (1) the ctrl-b detach broke (0x02 is wrapped, so `parse_stdin_chunk` never sees the raw `DETACH_PREFIX`), and (2) win32-input-mode was forwarded into Claude Code's own ConPTY input negotiation (garbage). The VT lever is wrong for Windows Terminal. (Lesson: verify a terminal-input fix on the REAL terminal via the operator re-capture — unit/clippy never exercise the live key path.) - **Invariant:** stay a raw byte pump and NARROW-normalize in the forward path — **SWAP** the two delete bytes: `0x08` → `0x7f` (VT DEL, char-delete) AND `0x7f` → `0x08` (^H, kill-word), AFTER the detach state machine consumes any `0x02`, leaving `0x02` and every other byte untouched. Because CC reads `^H`=word-delete and DEL=char-delete, swapping the *input* bytes gives Backspace=char-delete and Ctrl+Backspace=word-delete — the native Win11 convention (the operator rejected losing word-delete; the earlier one-way `0x08`→`0x7f` map dropped it). cfg(windows) only (Unix is already VT; a real `ctrl+h`/`ctrl+?` there must pass through). Accepted minor loss: a real `ctrl+h` (0x08) and a real DEL (0x7f) are swapped on Windows — both are delete keys, so the practical effect is the Backspace/Ctrl+Backspace native mapping. - **spt-core mapping:** the Backspace/Ctrl+Backspace SWAP intent persists; the `normalize_key_byte` byte-swap was SUPERSEDED on Windows by **7.16** (`REQ-RC-KEY-VT-TRANSLATE`, v0.13.0 bug 2) — the agnostic key-event→xterm-VT `translate_key_event` now emits Backspace → `0x7f` and Ctrl+Backspace → `0x08` natively (carrying the relocated `[impl]`/`[unit]` evidence), so `normalize_key_byte` + its unit were removed. The live keypress is HITL operator re-capture. - **Source:** v0.13.0 W7 (operator dogfooding; doyle /diagnose + byte confirm + VT-backfire re-capture 2026-06-19; one-way→swap upgrade 2026-06-19; superseded-on-Windows by the bug-2 translator 2026-06-19). ### 7.14 The effect journal must NOT hold its lock across the PTY write (or fsync every keystroke) — interactive input stutters then wedges `[REQ-HAZARD-EFFECT-JOURNAL-PTY-WEDGE]` - **Failure (operator dogfooding + doyle /diagnose, MEASURED on the real Windows box, 2026-06-19, post-W1 escape):** `EffectJournal::apply_once` held its global `inner` mutex ACROSS `write_line(PENDING)` → `effect()` → `write_line(DONE)`, and `write_line` does `flush()+sync_all()` (a full fsync). Every operator keystroke is a `PtyWrite` effect (via `send_effect` → `dispatch_input` op_id branch), so each paid TWO fsyncs serialized under a GLOBAL lock with the blocking PTY write INSIDE the lock. Two facets, one root: **(A) stutter** — measured fsync on `%LOCALAPPDATA%\spt-core` median 6.5 ms / spikes 198 ms, ×2 per keystroke → choppy, worsens with volume; **(B) HARD WEDGE** — a blocking `PtyWrite` (ConPTY/forkpty input buffer not draining) held the lock indefinitely, so the single-threaded dispatch could open NO attaches → every `spt rc --view/--take` died with `brain IPC read deadline elapsed` (broker control-plane KIND queries still answered = a different thread). DISTINCT from 7.12 (the OUTPUT drain); this is the INPUT/effect-journal path 7.12 never touched. **Refutes** 7.12's "input parks are Windows-benign (ConPTY absorbs)" deferral — on the real box the input path wedges regardless, because the wedge is the LOCK HOLD, not the PTY write blocking per se. - **Invariant:** `apply_once` RELEASES the inner lock across `effect()` — reserve the key (fsync `PENDING` for DURABLE kinds) under the lock, RELEASE, run the effect OFF the lock, then re-acquire to finalize (fsync `DONE` for durable, mark applied). Crash-idempotency comes from the per-key reservation + the applied-set, not from holding the lock across the effect (the brain-crash guarantee is unchanged: the broker survives the brain, so reserve→effect→finalize runs uninterrupted on the broker thread; a replay hits the applied-set and dedups). `EffectKind::PtyWrite` is **EPHEMERAL** — NO journal lines, NO fsync, in-memory dedup only (a keystroke lost to a broker crash is retyped; PTY state is never rebuilt from keystroke replay) — while durable kinds (spool/registry/net) keep their fsync'd markers. The PtyWrite itself must additionally be bounded/fail-fast and must not hold the writer mutex across a blocking write (the Unix-forkpty park bound; ConPTY absorbs = benign). - **spt-core mapping:** impl `effect.rs` `apply_once` (reserve/release/finalize) + `EffectKind::is_durable`; unit (`effect.rs`) a barrier proving the lock is NOT held across `effect()` (a different key's `apply_once` completes while one effect blocks) + `PtyWrite` writes no journal line while a durable kind (`NetSend`) does (the no-fsync proxy); int `crates/spt-daemon/tests/inject_control_wedge.rs` (real broker+PTY, a stalled consumer + sustained blocking input effect: a concurrent `spt rc` attach stays serviceable AND actually receives PTY bytes — the assertion W1's gate lacked). Unix park-(b) folded here, gated on gravity-linux. doyle GATE-GUARD: assert structurally, NEVER on fsync wall-clock (env-dependent, flaky); the stutter is fixed as a consequence of the no-fsync path, proven by the structural unit. - **Source:** v0.13.0 W1b (operator dogfooding post-W1 escape; doyle /diagnose + measurement 2026-06-19). ### 7.15 An OFFLINE spt-hosted endpoint must NOT render phantom `ONLINE+CONTROLLED` — clear `driven_by` when its session is gone `[REQ-HAZARD-DRIVEN-BY-SELFHEAL]` - **Failure:** `driven_by` (the `info.json` `ONLINE+CONTROLLED` latch) is single-written by the broker via `clear_controller`/`stamp_driven_by`, which only fire on a controller change. When an spt-hosted endpoint's broker session is GONE (harness dead — the B2 case, 7-series sibling `REQ-HAZARD-HOSTED-LIVENESS-RECONCILE`), no controller event ever fires, so a stale `driven_by=Some(node)` persists: the picker renders a phantom "controlled by X" on an endpoint that is actually OFFLINE. The B2 reconcile already clears the `status=online` latch here but left `driven_by` untouched. - **Invariant:** `reconcile_hosted_liveness`, when it offlines a sessionless controllable perch (the B2 keystone — no live broker session ⇒ dead harness), ALSO clears `driven_by` (`set_driven_by(perch, None)`). RACE-FREE and single-writer-safe: with NO live broker session there is no controller to re-stamp `driven_by` concurrently, so the brain may write it here without contending the broker. (The LIVE-session leg — a controller gone while its session survives — is NOT this hazard: a clean disconnect already self-heals via `detach_if`→`clear_controller`, W1 (7.12) bounds the active-output wedge, and the residual idle-wedged-REMOTE case is the deferred `REQ-HAZARD-DRIVEN-BY-IDLE-REMOTE-EVICT`, which needs BROKER-SIDE liveness eviction — a brain reconcile can NOT detect it, since the broker still reports `controller_by==Some` on an idle wedged controller. Repro-proven: `inject_control_wedge.rs` w5_a2.) - **MEASURED 2026-07-22 (DAEMON-LIFECYCLE W2 Leg B, `transport_death_eof.rs`) — the residual SPLITS in two, and only one half is still open.** On REAL QUIC (two brokers, `BindScope::Loopback` + a real `net_dial` — NOT the in-process duplex, which has no idle timeout at all), a remote controller whose QUIC STACK DIES WITHOUT A FIN (peer frozen: endpoint alive, UDP port still bound, keepalives unanswered — the sleeping-laptop shape) DOES self-heal: the transport's own idle timeout tears the conn, the read pump's `Err(_) => finish()` leaf surfaces `NetStreamEof` to the ALREADY-SERVING `serve_attach` worker, and the seat releases. **The numbers: clean FIN 120ms · torn no-FIN 65057ms** (`MESH_MAX_IDLE` = 60s plus quinn's PTO slack — a number materially UNDER 60s would mean the staging leaked a signal). **The latch is NOT a lockout — read that sentence before this one:** a different-conn attach during the window is an ADR-0038 fix-6 successor and takes the seat IMMEDIATELY, so the returning operator (or a second one) is never blocked by the dead seat. The residual harm is stale STATUS TRUTH (`CONTROLLED`/`driven_by`/viewer count) for ~65s, self-healing on a bound. **DECIDED 2026-07-22 (doyle, ON the number): ACCEPT AS DOCUMENTED** — no presence-FIN synthesis (a second teardown mechanism on this seam to shave ~60s off a case that already converges) and no keepalive tune (a global QUIC tradeoff: chatter, battery, mobile paths). The revisit lever is NAMED, not built: if the window ever reads as bad product feel, the keepalive interval is the knob, and it is a product-feel call with a false-evict bound to design. Grounds in full: ADR-0040 Amendment 1. **Scope of the measurement:** local real QUIC (two brokers, one box); LAN confirmation over a real two-host path is outstanding and rides the next box-occupancy window — insurance on a decision that builds nothing, not a dependency. **The still-open half is the ALIVE-but-WEDGED controller (A2): its QUIC stack keeps answering keepalives while only the app writer is parked, so the transport NEVER dies and no idle timeout ever fires** — nothing in the transport-death class reaches it, and the measurement above must not be read as covering it. - **Watch-out (repro-proven, real broker):** `SessionInfo.controller_by==None` is AMBIGUOUS — `dispatch_spawn` pre-attaches the spawner as the LOCAL controller with `by=None`, so a live LOCALLY-driven session also reads `None`. It is therefore NOT a usable standalone `driven_by` clear trigger (would false-clear a live local session). The shipped Gap-B self-heal needs no controller signal at all (it keys on session ABSENCE). - **spt-core mapping:** impl `livehost.rs` `reconcile_hosted_liveness` Gap-B clear + the additive `SessionInfo.controller_by` observability field (`msg.rs`, populated in `broker.rs` `KIND_SESSIONS`); unit `livehost.rs` `pull_liveness…` extended (offlined sessionless perch clears `driven_by`; live/relay perches untouched); int `crates/spt-daemon/tests/driven_by_selfheal.rs` `gap_b` (real broker: reconcile offlines AND clears `driven_by`) + the A1/A2 characterization (`inject_control_wedge.rs` w5_a1/w5_a2). - **Cross-ref 7.29 (who MAY clear vs who MUST NOT):** the BRAIN reconcile here MUST NOT clear `driven_by` off `controller_by==None` (ambiguous with a live LOCAL controller). The BROKER stamp-convergence (7.29) MAY — it reads `has_controller()` DEFINITIVELY (its own controller slot), so it authoritatively clears a stale `driven_by` against a live session with no controller (the `has_controller()==false` leg). The invariant's owner for that leg moved to the broker; this brain-side ambiguity-safety is unchanged. The wedged-open-remote A2 residual (`has_controller()==true`) is NOT covered by either — still `REQ-HAZARD-DRIVEN-BY-IDLE-REMOTE-EVICT`. - **Source:** v0.13.0 W5 (repro-first, todlando; doyle-assigned 2026-06-19). A2 (idle wedged-remote leg) deferred to `REQ-HAZARD-DRIVEN-BY-IDLE-REMOTE-EVICT`. ### 7.16 `spt rc` translates Windows console KEY EVENTS to standard xterm VT (arrows/Home/End/F-keys reach the harness); supersedes the W7 byte-swap `[REQ-RC-KEY-VT-TRANSLATE]` - **Failure (operator dogfooding):** `spt rc` read raw stdin BYTES, but the Windows legacy console (no `ENABLE_VIRTUAL_TERMINAL_INPUT`) delivers arrows / Home / End / PgUp / PgDn / Insert / Delete / F-keys as console KEY_EVENTs, NOT stdin bytes — so the byte-pump saw nothing and those keys were DEAD (only byte-emitting keys like Backspace worked, via the 7.13 swap). - **Invariant:** on Windows, read crossterm KEY EVENTS (the picker already does) and translate each to STANDARD xterm VT via the pure `translate_key_event` (copy a known-correct xterm table verbatim: arrows `ESC[A..D`, Home `ESC[H` / End `ESC[F`, `~` keys `ESC[~`, modified `ESC[1;` / `ESC[;~` with `m = 1 + Shift + 2·Alt + 4·Ctrl`, F1–F4 `ESC OP..S` / F5–F12 `ESC[~`), forwarded through the SAME rc pump — the harness receives ordinary xterm VT (AGNOSTIC; NOT win32-input-mode, the 7.13 rejected lever). Press-only (drop Repeat/Release). Detach stays the `ctrl-b d` PREFIX, event-sourced (Ctrl+B arms; armed + plain `d` ⇒ Detach; armed + Ctrl+B ⇒ literal `0x02`; armed + other ⇒ `0x02` + translated). NON-tty stdin (piped / tests) falls back to the byte path (keeps the e2e byte-injection working). UNIX UNCHANGED (cfg-split; its raw-mode stream already delivers VT). SUPERSEDES 7.13's `normalize_key_byte` swap on Windows — Backspace → `0x7f` and Ctrl+Backspace → `0x08` are emitted NATIVELY by the translator. - **spt-core mapping:** impl `rc.rs` `translate_key_event` + `csi_final`/`csi_tilde`/`f_key` + `key_event_step` (event detach SM) + `spawn_stdin_reader` cfg-split (`spawn_stdin_reader_events` on a tty / `spawn_stdin_reader_bytes` non-tty + Unix); unit the EXHAUSTIVE `translate_key_event` mapping + the event-detach SM (the Backspace/Ctrl+Backspace arm carries the relocated `REQ-HAZARD-RC-INPUT-KEY-ENCODING` evidence); NO int (live console = HITL, operator re-capture — REQ-RUN-PICKER/RC-1 precedent). - **Source:** v0.13.0 bug 2 (operator ruling: proper agnostic translator, ship-blocker; doyle design + Option-B detach ruling 2026-06-19). ### 7.18 `spt rc` paste is client-originated on Windows — read the LOCAL clipboard, inject a BRACKETED paste `[REQ-RC-WIN-PASTE]` - **Failure (operator dogfooding):** in an `spt rc` session neither ctrl+V nor right-click pasted (CC explicitly supports ctrl+V). `RawGuard` did only `enable_raw_mode` (no bracketed paste, no mouse capture, no clipboard interception); the Windows console delivers a paste as synthetic per-char KEY EVENTs (no crossterm `Event::Paste`), and ctrl+V translated to a bare `^V` forwarded to CC — but **CC runs daemon-side with NO access to the operator's LOCAL clipboard**, so remote paste is fundamentally CLIENT-ORIGINATED. A multi-line paste-as-keys also became a `\r` submit-storm. - **Invariant:** on Windows (cfg-split; folds into the 7.16 event path), on a RIGHT-CLICK rc reads the LOCAL clipboard itself and forwards a BRACKETED paste — `wrap_bracketed_paste` = `ESC[200~` + content + `ESC[201~`. CC has bracketed-paste mode on (its TUI sets `ESC[?2004h`), so it treats the synthesized markers as a PASTE: content lands intact, NO submit-storm, harness-AGNOSTIC (standard xterm contract). `RawGuard` also `EnableMouseCapture` (disables console QuickEdit + enables `ENABLE_MOUSE_INPUT` so a right-click surfaces as `Event::Mouse`) on an interactive console only, restored on drop → right-button-down → `read_clipboard` → bracketed paste. `read_clipboard` = the `clipboard-win` crate; empty/failed read ⇒ a clean no-op (never inject garbage, never panic). Content forwarded VERBATIM (literal pasted text, no per-char translation). UNIX UNCHANGED (its terminal pastes natively through the byte pump). **ctrl+V is NOT intercepted** (P1b amendment, HITL re-open): Windows Terminal CONSUMES ctrl+V as its own paste accelerator — it delivers only a Key `kind=RELEASE` (never a Press, so a Press-guarded arm could never fire) AND injects the clipboard as a char-by-char KEY FLOOD spt-core cannot intercept. ctrl+V now rides WT's native paste as keystrokes (multi-line may submit-storm — acceptable; bracketed fidelity = right-click). The flood landing as keystrokes no longer wedges the broker (7.19). - **spt-core mapping:** impl `rc.rs` `wrap_bracketed_paste` + `mouse_is_paste` + `clipboard_paste` + `read_clipboard` + `windows_mouse_wanted` + `RawGuard` (mouse capture/restore) + the `spawn_stdin_reader_events` right-mouse arm; unit the exact bracketed framing + content-verbatim + mouse classify (right-down ⇒ paste, all else ⇒ drop) + the injected-reader paste decision (non-empty ⇒ wrapped, empty/fail ⇒ no-op); NO int (live clipboard + console mouse = HITL, REQ-RUN-PICKER/RC-1 precedent). - **Source:** v0.13.0 P1 (operator HITL; doyle design 2026-06-19). Depends on P0 (7.17). AMENDED v0.13.0 P1b: scope narrowed to right-click-only (the dead ctrl+V interception removed); scroll-forward is 7.20; the input-flood non-wedge is 7.19. ### 7.19 An operator input FLOOD must not deadlock the broker via the applied-ack on the same conn `[REQ-HAZARD-INPUT-ACK-BACKPRESSURE]` - **Failure (operator HITL, the ctrl+V re-open):** a flood of operator input on one brain↔broker conn wedged the WHOLE broker PERMANENTLY (no new/existing attach; the controller stayed latched — the per-conn handler couldn't process the detach). `serve_attach` processes a whole `NetStreamData` batch of N `Input` records in its inner loop, calling `send_effect` N times WITHOUT returning to `read_event()`; the broker answers each with `send_frame(applied_envelope)` on the SAME conn. Brain not reading → the broker→brain return direction fills (~10 frames = the IPC pipe buffer) → `send_frame` BLOCKS → the handler stops reading → the brain's writes block → mutual full-duplex DEADLOCK. (Capture: 11 frames, `write_input` 11/11 — P0 holds; `ack send` START=11/END=10 — frame #11's ack never returns.) WT's ctrl+V paste-accelerator key-flood was the trigger; the deadlock is generic to ANY input flood. - **Invariant:** the applied-ack is OPT-IN. `InputReq` carries `ack: bool` (serde `default = true`, N-1-safe). The fire-and-forward operator/rc path (`serve_attach`) sends `ack=false` via `Brain::send_effect_no_ack`; `dispatch_input` writes NO applied frame when `ack=false`, so the per-conn handler never writes back while servicing the flood → it always drains → no deadlock (cures ANY input flood). `shellchan` (one-at-a-time spool delivery, WAITS on `BrokerEvent::Applied`) keeps `send_effect` (`ack=true`). EXACTLY-ONCE preserved: the broker dedups by `(session, op_id)` at the applied-set regardless of the ack. **N-1 caveat:** an OLD resident broker (the self-update window) ignores `ack=false` → still acks → the deadlock persists until a broker restart (inherent broker-resident-wire-change class, see 7.9). - **spt-core mapping:** impl `msg.rs` `InputReq.ack` (`default_true`) + `brain.rs` `send_effect_no_ack`/`send_effect_inner` + `attach.rs` `serve_attach` operator path → `send_effect_no_ack` + `broker.rs` `dispatch_input` gates `send_frame(applied)` on `req.ack`; unit the serde default + the ack-emitted-iff-true + the no-ack-path exactly-once dedup; int (keystone, repro-first) a flood of N>pipe-buffer input frames through `serve_attach` on one conn — PRE-FIX deadlocks, POST-FIX drains all N + the session stays live + a concurrent attach opens (real broker+brain, no mocks). - **Source:** v0.13.0 P1b (operator HITL re-open; doyle /diagnose on the enhanced rc+broker capture 2026-06-19). The real ship-blocker behind the ctrl+V wedge. ### 7.20 `spt rc` must forward the scroll wheel to the harness (our mouse capture steals WT's native scroll) `[REQ-RC-MOUSE-FORWARD]` - **Failure (operator HITL):** scroll stopped working in `spt rc`. P1's `EnableMouseCapture` (for right-click paste, 7.18) makes Windows Terminal forward ALL mouse — including the wheel — to rc instead of scrolling its own buffer, but the rc mouse handler dropped everything except right-button-down → scroll DIED (and WT's native scrollback is stolen under the capture). - **Invariant:** on Windows, TRACK the harness's mouse-reporting mode from its OUTPUT — scan for DECSET `ESC[?1000h/1002h/1003h` (mouse on) + `ESC[?1006h` (SGR ext) and their `…l` (off) into a shared `MouseMode{enabled,sgr}` (the pump writes from the output render path, the stdin reader reads); the scan survives a sequence SPLIT across output chunks (a bounded carry buffer). The mouse handler: right-button-DOWN → bracketed clipboard paste (7.18, unchanged); `ScrollUp/Down` → an xterm SGR mouse report (`ESC[<64;col+1;row+1M` up / `ESC[<65;…M` down; 0-based crossterm → 1-based xterm), forwarded ONLY when `enabled && sgr` (else DROP — a legacy report the harness may misread is garbage); Moved/drag/left/middle DROP (scroll is the need; click-forward risks garbage, no click-to-position). UNIX UNCHANGED (no capture; the terminal scrolls natively). - **spt-core mapping:** impl `rc.rs` `MouseMode` + `MouseModeScanner`/`parse_decset_private`/`apply_mouse_mode` (carry-buffer scan, fed from the pump's output path) + `scroll_dir` + `scroll_sgr` + the `spawn_stdin_reader_events` scroll arm (threaded via `Arc`); unit `scroll_dir` classify + `scroll_sgr` exact bytes + the DECSET scan (set/reset, combined, mixed, and split-across-chunks); NO int (live console mouse = HITL). - **Source:** v0.13.0 P1b (operator HITL; doyle design 2026-06-19). Bundled with 7.19. ### 7.21 Exactly ONE `controller_writer` per brain↔broker connection — a superseded writer must write nothing further `[REQ-HAZARD-CONTROLLER-WRITER-REORDER]` - **Failure (doyle instrumented RACEDIAG repro, kitsubito):** on a brain-restart re-serve the handoff brain registered as controller on the SAME session TWICE over the SAME socket — `Brain::handoff` eagerly `subscribe(prior.next_seq=1)` → `become_controller(from_seq=1)`, spawning writer-A (writes seq 1); then `serve_attach` re-handled the replayed `Request{from_seq:0}` → `attach_as(sid,0)` → `become_controller(from_seq=0)`, spawning writer-B (writes 0,1). `become_controller` dropped the prior `ControllerSink` (its `tx`) but did NOT stop the prior writer — writer-A kept flushing its OWNED `initial` batch, and both writers held clones of one `SharedSend` (`Arc>`) with no inter-thread ordering. When writer-A's seq 1 beat writer-B's seq 0, the strict consumer saw `output gap: got seq 1 want 0` → `attach_survives_target_brain_restart_exactly_once` panicked at `.expect("re-serve")` OR HUNG in `render_until` (serve thread died on the gap → `MARKER_TWO` never reached the wire). `prior.next_seq` is life1's CONSUMPTION cursor (life1 forwards each frame to the operator immediately on consume, so at crash it has forwarded exactly `[0, K)`); life2 resumes from that same `K`, so the boundary aligns and `[0, K)` need never be re-sent. The crash was NOT byte loss — it was the consumer running the strict **reject-gap legacy path** (handoff left `session_cursors` empty) which treats any out-of-order seq as fatal. PRE-EXISTING, surfaced by the v0.13.0 green-both-runners gate; P1b is innocent. Sibling flaky cluster: `inject_control_wedge::g2`, `broker::spawn_env_reaches_child`. - **Invariant:** on a single brain↔broker connection exactly ONE `controller_writer` is ever the LIVE writer; a SUPERSEDED writer writes no further frames after the epoch bump it observes; and **every `controller_writer` emits a strictly ASCENDING seq stream** (sorted initial batch + ascending live frames). The CORRECTNESS guarantee that falls out: a snap-above consumer over any interleaving of ascending writers — where the surviving writer (`serve_attach`'s `attach_as(sid,0)`) offers the COMPLETE range `[0, end]` — delivers `[K, end]` with **no skip and no dup** (the first sighting of any seq `>M` is always preceded by a sighting of `M` on that same ascending writer, so `M` is delivered before the cursor can pass it). Enforced/relied-on three ways (NB: fix #1 — "drop handoff's eager subscribe" — was REVERTED: that subscribe is the standalone-resume mechanism the brain-only update engine + `handoff`/`idempotent`/`daemon_e2e` replay through with no `serve_attach`): (1) CORRECTNESS — `Brain::handoff` seeds `session_cursors` at `prior.next_seq` so the consumer runs dedup-below + snap-above (resume mode), never the reject-gap legacy trap; the ascending-merge property above makes this complete, not merely tolerant; (2) INVARIANT — `controller_writer`'s INITIAL-BATCH replay is EPOCH-GATED: `controller_epoch` is a shared `Arc`, the writer re-reads it UNDER `send.lock()` (atomically with `write_frame`) and returns the instant it is superseded, so a superseded writer can never flush its stale replay past the bump (W1-safe: never blocks the drain under `Mutex`). The LIVE loop is deliberately NOT gated — new output only ever flows to the CURRENT controller's channel, so a superseded writer's channel holds only its pre-supersede backlog (deduped by snap-above) plus its TERMINAL `Displaced` kick, which the displaced controller MUST still receive; that loop ends naturally on `tx`-drop (gating it suppressed the loud-take `Displaced` — the cv-matrix hang); (3) EXPLICIT-RESUME / OPERATOR-STREAM BOUNDARY (the load-bearing fix — kitsubito RACEDIAG ~33% repro that the keystones missed) — `Brain::subscribe_with` (shared by `attach` AND `attach_as`) RESETS that session's dedup cursor to `from_seq` in resume mode. WHY it's load-bearing, not just the ground-truth re-read: the handoff's eager `subscribe(K)` makes `serve_attach`'s `brain` receive the replay frame at seq=K BEFORE the operator's `Request` is processed (`attached` still false); that early frame is dropped by the `if attached` forward gate but the snap-above cursor has already advanced past K, and `attach_as(sid,0)`'s re-subscribe used to leave the cursor advanced — so the broker's re-send of seq K arrived below it and was deduped → seq K never reached the operator viewport → a `no forward gap` panic at the operator render cursor (`render_until`), and SILENT content loss in the real `rc` consumer (dedup-below + snap-above). Resetting to `from_seq` on the `attach_as(0)` re-subscribe makes the broker's full re-send re-deliver from 0 (the operator dedups the overlap), so seq K is forwarded. The epoch gate (2) is sound (RACEDIAG: zero socket interleaving above K); the residual was purely this consumer-side boundary. Cold-start brains (empty map — e.g. the production dispatch serve brain) keep the legacy `next_seq` path untouched, so production is unaffected. - **spt-core mapping:** impl `brain.rs` `Brain::handoff` (KEEP the eager `subscribe`; seed `session_cursors`) + `Brain::subscribe_with` (resume-mode dedup-cursor reset to `from_seq`, shared by `attach`/`attach_as` — the operator-stream boundary fix) + `broker.rs` `OutputLog.controller_epoch: Arc` / `become_controller` (atomic `fetch_add`, passes the new epoch + `Arc::clone` into the writer) / `controller_writer` (epoch gate read UNDER the lock on both loops) / `mark_controller_gone` + the `ControllerJob` epoch read; unit (white-box, `src/broker.rs`) the epoch-gated writer (a superseded writer flushes nothing — only the latest writer's monotonic stream reaches the wire) + `handoff` seeds `session_cursors`/resubscribes; int (keystone, `tests/broker.rs` + `tests/attach.rs`) deterministically force two `become_controller`-on-one-connection on a real broker+brain (no mocks) — PRE-FIX reorders/gaps, POST-FIX monotonic + byte-exact + session live, PLUS `attach_survives_target_brain_restart_exactly_once` green (doyle: 20× isolated single-threaded timeout-wrapped on Linux/kitsubito — the deterministic RED-on-revert carrier). - **Source:** v0.13.0 P1c (operator-ruled root-fix before ship; doyle root-cause via instrumented repro 2026-06-20; design corrected across two gate rounds — fix #1 reverted, then the kitsubito RACEDIAG pinned the residual to the consumer-side operator-stream boundary, fixed by the `subscribe_with` cursor reset on `attach_as` re-subscribe). The last v0.13.0 ship-blocker. ### 7.22 An idle delivery with no working translation binary must SPOOL, never raw-inject a pseudo-delivery reported as delivered `[REQ-HAZARD-IDLE-SILENT-NONDELIVERY]` - **Failure (F-019 post-mortem):** the v0.11.0 path raw-injected `payload+\r` into the spt-hosted PTY whenever no working translation binary handled an inbound message — none declared, spawn-failed, FAULTED (commit-deadline miss / binary death), or its inject-worker channel dropped — AND acked `delivered=true`. But a bare `payload+\r` does NOT submit on a modern TUI (Claude Code): the message was TYPED into the harness but never sent, a silent pseudo-delivery reported as success. That silent degrade-to-raw-inject is precisely what MASKED F-019 (`[REQ-INSTALL-11]`, above) through a multi-hour black-box hunt — every behavioral hypothesis was moot because the "delivery" never delivered. - **Invariant:** spt-hosted idle delivery is translation-binary-ONLY (ADR-0022 amendment). `dispatch_endpoint_input` with no working binary replies `endpoint_injected_envelope(ep, delivered=false)` and writes NOTHING to the PTY; the caller (`try_broker_inject` → `cmd_send`) reads `delivered=false` and falls through to `deliver::send` = SPOOL (poll-fed, never lost), reporting an honest `QUEUED`, never a confident-but-false `SENT`. The failure is LOUD (`ENDPOINT_INJECT:: no working translation binary … -> SPOOLED, not injected`). The raw-inject fallback (`input.enqueue`) is removed from the no-binary, worker-dropped, AND post-fault paths; the operator-keystroke floor-flush on FAULT is UNCHANGED (operator input is never stranded). Out of scope (follow-up): broker-side auto-redrive of already-spooled inbound when a live-update binary spawns (ordering/exactly-once hazards; the poll substrate + subsequent sends cover re-delivery). - **Boundary — what this does NOT cover (the STATE-vs-transient precision):** the guarantee is the steady FAILED STATE — once a binary IS faulted/absent/worker-gone, subsequent deliveries spool (`faulted` is MONOTONIC: set once, never respawns, so the state is reached deterministically). It does NOT cover the FAULT-TRANSIENT: a delivery that lands in the worker's commit window — BEFORE `event_rx` is dropped / `faulted` is set — can be optimistically enqueue-acked (`delivered=true` the instant `event_tx.send` succeeds) then DROPPED when the worker faults+returns. This is a SEPARATE, PRE-EXISTING hazard (raw-inject removal did not touch it — the old code dropped that queued event too; v0.14.3 makes nothing worse) and is tracked for **v0.15.0 under `[REQ-MSG-DELIVERY-AXES]`** (the spool-centric delivery redesign: ack-on-SPOOL replaces ack-on-enqueue, which closes the optimistic-ack drop naturally). The g2 int gate asserts the steady state via **bounded-retry-until-spool** (faulted-monotonic → converges) rather than a single-shot ack, so it is load-robust under the parallel CI suite. - **spt-core mapping:** impl `broker.rs` `dispatch_endpoint_input` (no-working-binary → `delivered=false` + loud log, no `input.enqueue`; the `input` writer is no longer resolved from the sessions table) + `build_translation`/`fault_translation` (`None`/fault now MEAN spool); unit `msg.rs` `endpoint_injected_envelope_carries_delivered_both_ways` (the `delivered=false` spool signal round-trips); int (real broker+PTY) `tests/broker.rs` `endpoint_keyed_inject_without_binary_spools_not_pty` + `tests/inject_control_wedge.rs` `large_endpoint_inject_to_a_no_binary_session_spools_promptly_without_wedging` + `g2_no_commit_deadline_faults_binary_and_does_not_wedge_controller_input` (post-FAULT inbound EVENTUALLY spools via bounded-retry-until-spool, marker NEVER on PTY across attempts — load-robust; the in-window fault-transient is the carve-out above). - **Source:** v0.14.3 (ADR-0022 amendment @1eaeef1, operator-ruled; doyle-scoped, the F-019 follow-up). CHANGE-5 (`cli.rs` honest report) verified a NO-OP — the spool fall-through already reported `QUEUED`, never `SENT`. --- ### 7.23 A message that has REACHED a node's spool must NEVER depend on an adapter hook-poll cadence to reach an spt-hosted (relay-less) endpoint — the daemon drives delivery on the events it owns `[REQ-HAZARD-DELIVERY-STARVATION]` - **Failure (F-023, RCA @ `f023-f024-wan-idle-starvation`):** a message that has already landed in a node's spool — WAN-arrived, or locally spooled-while-active — stranded INDEFINITELY on an spt-hosted, relay-LESS endpoint whenever the adapter's hooks went quiet (an idle session with no user turns). An spt-hosted perch has no `api listen` relay to wake it, and NOTHING in the daemon re-offered a spooled message once the arrival moment passed — delivery silently depended on the adapter happening to call `api poll`. Presented as "sent but never lands" with a HEALTHY translation binary and a visibly-idle perch (F-023: verified 7 min idle, binary alive, zero injection). TWO gaps: (1) the WAN-ingress path (`receive_wan`) tried the harness-hosted TCP relay then fell straight to spool — it had NO spt-hosted broker-inject leg (that leg existed ONLY in local `cmd_send`); (2) NO idle-edge drain existed anywhere, so a spooled-while-active (deferred) row was never re-offered when the endpoint next went idle. - **Invariant:** the daemon DRIVES delivery of an already-spooled message on the events IT owns — never on hook cadence — for a relay-less spt-hosted endpoint. TWO daemon triggers feed ONE shared spt-hosted inject leg (`spt_daemon::inject::try_spt_hosted_inject`, translation-binary-ONLY): (1) **WAN ingress** — `receive_wan` injects via the live binary BEFORE the spool fallback (`[REQ-WAN-SPT-HOSTED-DELIVERY]`, leg 1); (2) **the ACTIVE→IDLE edge** — `drain_idle_window` (fired by `api state idle`) claims the pending spool (NON-DEFERRED only — see SCOPE below) and injects each via the same leg, reusing the hook-poll take/ack so a concurrent `api poll` cannot double-deliver (`[REQ-MSG-IDLE-EDGE-DRAIN]`, leg 2). The v0.14.3 LAW holds on BOTH triggers (7.22): no working binary ⇒ SPOOL LOUD (the row is released back intact), NEVER a raw PTY write. Hook-poll remains a valid third delivery trigger; it is simply no longer the ONLY one. - **spt-core mapping:** impl `spt-daemon/src/inject.rs` `try_spt_hosted_inject`/`is_spt_hosted_no_relay` (the shared leg) called by `wan.rs` `receive_wan` (leg 1) AND `spt/src/api/delivery.rs` `drain_idle_window` (leg 2, via `spool::claim_idle_edge_at`/`release_at`); int (real broker+PTY+binary) `tests/inject_control_wedge.rs` `wan_arrival_to_idle_spt_hosted_injects_with_no_hook_poll` (leg 1) + `spt/tests/idle_edge_drain_e2e.rs` `spool_while_active_then_idle_fires_injection` (leg 2) — both prove delivery with NO hook poll. - **SCOPE (amended 2026-07-27, FIELD-TRUTH W1 roll-in, operator ruling):** this no-starvation guarantee binds the **`default` and `idle_only` classes ONLY**. The **`active_only` (deferred) class is explicitly OUTSIDE it** — per ADR-0028 it is hook-carried background context whose contract is "active hook window only; never wakes an idle agent", so with no hook cadence it WAITS. That is starvation *by design*, not a defect, and it is the one case where "reached the spool" does not imply "will be delivered without a hook". Leg 2 originally rescued the deferred class too; that rescue was REVOKED, because the rescue WAS the defect: doyle's spool take-audit on a live perch showed every boundary-spooled spt-shells shell-context row (`window=active_only`, `deferred=1`) taken with `taken_leg=idle-inject` ~200ms after spooling — each injection STARTING A TURN on an idle agent, the precise thing "never wakes" forbids. The idle-edge and parked-re-offer claims now exclude `deferred=1` unconditionally (no caller flag widens it — guard 4 of `[REQ-SEND-WINDOW-DRAIN-HONOR]`). **Diagnosis rule that follows:** an `active_only` row sitting pending on a hook-quiet endpoint is CORRECT behaviour — do not read it as this hazard recurring. - **Source:** F-023 (BUILD-F023-WANIDLE; doyle RCA + gate, todlando build 2026-07-02). Delivered in two legs: WAN-ingress inject (leg 1) + idle-edge drain (leg 2). Scope narrowed 2026-07-27 (FIELD-TRUTH W1 roll-in) — see SCOPE above. --- ### 7.24 A delegated live adapter apply must NEVER report success without swapping, and the live-update seam must use ONE parent-aware adapter matcher `[REQ-HAZARD-ADAPTER-APPLY-SILENT-NOOP]` - **Failure (F015B / BUILD-F015B-APPLYMATCH):** a live adapter update to a PROFILE-COMPOSITE endpoint (`--adapter cc:ccs`) silently no-oped — `LIVE` then `DONE` printed, but the version-of-truth stayed OLD. TWO defects on one seam. **(D1, matcher skew):** the broker's `dispatch_adapter_apply` filtered sessions by EXACT `s.adapter == req.adapter`, but a `--adapter :` endpoint stores the COMPOSITE `cc:ccs` (set at `cmd_endpoint_run` → `launch_harness_brokered_in` → `SpawnReq.adapter`) while the apply carries the PARENT record name `cc` — so every `:profile` endpoint fell out to `affected=[]`; `select_endpoints_running_adapter` had the same `adp == adapter` skew, while the CLI live-gate `adapter_has_live_endpoint` already parent-matched via `split(':')` — TWO divergent matchers on ONE seam. **(D2, silent success):** the `affected.is_empty()` branch replied `KIND_APPLIED` and RETURNED WITHOUT SWAPPING. Once the CLI routes the apply to the daemon it has fully delegated — there is NO CLI-side fallback swap — so success-without-swap = the update never lands (re-register re-reads the OLD manifest; version-of-truth honestly reports old). `crc_swap` / the exe-lock / the terminate race were all EXONERATED (never reached — the swap was never attempted). Why `stop → update → relaunch` worked: a stopped endpoint fails the CLI live-gate → the direct `apply_release_crc_swap` path → a real swap. - **Invariant:** (1) ONE shared parent-aware matcher `spt_runtime::profile::adapter_parent_matches(session_adapter, parent)` (`split_option(session_adapter).0 == parent`) is used at EVERY live-update comparator — the CLI live-gate, the broker apply-filter, AND `select_endpoints_running_adapter`; NO exact `==` against a record name at any live-update seam (a profile-composite endpoint always resolves to its parent). (2) Once the apply is delegated the daemon owns the WHOLE apply: the CRC swap runs UNCONDITIONALLY (the terminate/restart loops simply no-op when nothing is resident), and `KIND_APPLIED` is reported ONLY after a real swap — there is no empty-affected early-return. A genuinely-exited endpoint therefore still swaps (correct: the on-disk install dir must reach the new bytes), and a `:profile` endpoint is coordinated exactly like a bare-name one. - **spt-core mapping:** impl `spt-runtime/src/profile.rs` `adapter_parent_matches` wired at `cli.rs` `adapter_has_live_endpoint` + `broker.rs` `dispatch_adapter_apply` session filter + `broker.rs` `select_endpoints_running_adapter`; `broker.rs` `dispatch_adapter_apply` swaps unconditionally (empty-affected early-return removed). unit `profile.rs` `adapter_parent_matches_on_parent_not_composite` (matcher truth table) + `broker.rs` `select_endpoints_running_adapter_filters_dedups_sorts` (extended with a `:profile` composite row — RED under exact-match). int (folds this wave) e2e a/b/c: composite-session swap-LANDS + no-matching-session swap-STILL-runs + a different-adapter session UNTOUCHED. - **Source:** F015B (operator escalation, doyle RCA code-verified end-to-end 2026-07-02; todlando build). ADR-0025 amendment records both invariants. --- ### F-019 diagnosis lesson — confirm an adapter binary actually SPAWNED before behavioral diagnosis `[REQ-INSTALL-11]` - **Failure:** a bare/relative adapter-shipped program path — `[message-idle-translation-binary].path = "cc-spt-idle-translate"` — passed VERBATIM to the broker spawns via `Command::new` against the daemon's cwd/PATH, FAILS (not on PATH), and the spt-hosted session FAILS CLOSED to raw inject. The binary's `{text}{delay}{key:enter}{commit}` choreography never runs → idle messages are typed into the harness but **never submitted**. `build_translation` DOES log `TRANSLATION_SPAWN_FAILED::` (broker.rs) — but it lands on the **DETACHED daemon's stderr, which nobody reads**, so it is "silent" in practice. This cost a multi-hour black-box hunt (byte encoding, win32-input-mode `?9001h`, bracketed-paste, focus, pacing — all moot; the binary simply never ran). - **Invariant:** every adapter-manifest program path resolves against the adapter install dir BEFORE PATH (REQ-INSTALL-11, `resolve_program_in_dir`) — at the harness session spawn (`harnesshost::launch_harness_brokered_in`: the idle-translation binary AND the session program), the W3d live-update RESPAWN (`broker::read_translation_path`), and the notif command (`with_install_dir`, both the daemon `notif.rs` and the api `reporting.rs` render paths). **Diagnosis rule:** before any deep behavioral analysis of a translation/adapter binary, CONFIRM it actually spawned — a resident process exists, and a deployed path edit changes behavior. `TRANSLATION_SPAWN_FAILED` on daemon stderr is the signal today, but its visibility is poor (surfacing it on the perch / a louder channel is a candidate follow-up). - **Source:** F-019 (v0.14.2); root confirmed on real claude-spt (perri + doyle). The raw-inject FALLBACK itself (degenerate no-binary floor) is unchanged by F-019 — its removal (message stays SPOOLED + poll-fed, never raw PTY inject) rides a separate ADR-0022 amendment. --- ### 7.25 A perch PINNED to a DEAD session self-heals (dead-owner re-pin) instead of wedging forever; a LIVE-owner rotation still refuses `[REQ-HAZARD-SESSION-PIN-WEDGE]` - **Failure (F-024C/F-024D, ENLYZEAM field + clean-room repro 2026-07-02):** `authenticate()` (auth.rs) gates `api poll`/`state`/`boundary` on `proof.session_id == info.json.session_id`. If ONE boundary rotation is LOST — the departing session dies (crash / tab-close) or its `/clear`-era `boundary` call never lands — the perch stays PINNED to the dead sid, and every id-scoped hook call thereafter AUTH_REFUSES *including `boundary` itself* (the very call that would re-pin presents the NEW sid). A permanent, self-inflicted strand: `ready:false`, stale `.idle`, drains no-op, WAN/idle spool sleeps forever — and `AUTH_REFUSED` is stderr-only, so INSIDE a hook it is invisible. No self-heal existed. - **Invariant:** `authenticate()` gains a DEAD-OWNER fallback — when the caller's sid MISMATCHES the pin **AND** the perch's recorded owner pid is DEAD (`proc::is_process_alive == false`), ACCEPT the caller's sid and RE-PIN (rotate `info.json.session_id` via the locked `mutate_info` RMW + a LOUD `SESSION_REPIN` stderr line). Same trust model as `establish_perch`'s conflict gate, which already allows a rebind exactly when `owner_alive == false` (an orphaned perch accepts a new LOCAL owner). This is **ADR-0032 LAYER 2 of 3**. A LIVE-owner mismatch (a `/clear`/`/compact` live-pid rotation — SAME process, new sid) STILL REFUSES: squat protection, deliberately NOT widened to live owners. The live-rotation contract is the adapter's (**layer 1**: persist + present the departed session's prior sid as `boundary` proof — `[REQ-BOUNDARY-ROTATION-CREDENTIAL]`, perri's `.sid` state-file pattern is the reference); a self-proving `parent_pid`-ancestry rotation is the design-true **layer 3** (parked: needs an ADR + Windows parent-spoof caveats). ADDITIVE to token auth — the existing token-auth recovery path is UNTOUCHED (the branch fires only on no/failed token AND sid mismatch AND owner dead). - **spt-core mapping:** impl `spt/src/api/auth.rs` `authenticate` dead-owner-mismatch branch (`read_pid` → `proc::is_process_alive` → `mutate_info` rotate + `SESSION_REPIN` log); unit `auth.rs` `pinned_to_dead_sid_mismatched_poll_repins` (AUTH_REFUSED → drains+re-pins, RED pre-fix) + `live_owner_mismatch_still_refuses` (the `/clear` live-rotation squat guard, unwidened) + `token_auth_path_unchanged` (correct token wins first, no rotation). - **Source:** F-024C/F-024D (perri field RCA on ENLYZEAM + doyle code-confirm 2026-07-02; the wedge latches on `/clear` even in a CLEAN env — the env-corruption domino was sufficient but not necessary). COVERAGE: dead-owner re-pin rescues CRASHED/DEAD owners ONLY; live-pid rotation is correctly refused without departed-session proof. Cross-refs ADR-0032 (the 3-layer rotation-credential model) + `[REQ-BOUNDARY-ROTATION-CREDENTIAL]` (layer 1, the adapter/harness-contract half). ### 7.26 Concurrent first-touch of ONE fresh BranchStore must ALL succeed — a non-atomic `git init` race must never strand a first-toucher `[REQ-HAZARD-STORE-INIT-RACE]` - **Failure (G3-gate pump.rs:442 flake, doyle-ledgered; clean-room repro 2026-07-02):** `BranchStore::open_or_init` (branchstore.rs:47) is a TOCTOU — it gates on `HEAD.exists()` then runs a NON-ATOMIC init (`git init --bare` + `git config core.autocrlf false` + best-effort `worktree.useRelativePaths`). N processes that all observe `!HEAD.exists()` on ONE fresh store race the init: concurrent `git init --bare` collide copying template hooks (`fatal: cannot copy … File exists`, exit 128), AND the `git config` step collides on git's per-repo `config.lock` (`could not lock config file …: File exists`) — either failure returns a hard `io::Error` that strands the losing caller. - **Invariant:** N concurrent `open_or_init` on ONE fresh dir ALL return `Ok`. The init is race-tolerant: `git init --bare` retries a transient collision with a growing backoff that desynchronizes racers (a lone re-init on a partially-copied dir completes cleanly — verified), treating a now-present `HEAD` as success (open-after-lose); the required `core.autocrlf=false` pin retries a transient `config.lock` collision (the value is idempotent, so the winner writes the same bytes). Convergence is guaranteed — once any racer creates `HEAD`, every other either sees it or re-inits alone. Non-lock / non-copy failures still fail fast. - **spt-core mapping:** impl `spt-store/src/branchstore.rs` `open_or_init` → `init_bare_tolerant` (bounded init-collision backoff-retry + open-after-lose) + `config_set_locked_retry` (bounded `config.lock`-aware retry). unit `branchstore.rs` `concurrent_open_or_init_on_one_fresh_store_all_ok` (N=8 threads race one fresh dir → every result Ok, HEAD present, `core.autocrlf=false`; RED-FIRST: the pre-fix path failed the `git init` template-copy loser). - **Source:** doyle F-025 wave Item 2 (the G3-gate pump.rs:442 flake root-caused as this TOCTOU). The red-first repro surfaced the race is BROADER than the ledgered `config.lock` — concurrent `git init --bare` itself collides on template-hook copy. --- ### 7.27 A control/viewer stamp must NEVER outlive its session — every teardown path clears what attach stamped `[REQ-HAZARD-CONTROL-STAMP-LIFETIME]` - **Failure (F-026 #2, live evidence HFENDULEAM):** an spt-hosted endpoint stayed `ONLINE+CONTROLLED` after the operator's RC `/exit` — hours later hall-a's `info.json` still read `controlled:true` (status offline, dormant) and hfenduleam still GOSSIPED `controller_node=self` cross-node (SPT_DEV.json snapshot). ROOT: `/exit` kills the CHILD, not the controller connection, so the endpoint suspends via child termination and the teardown runs the REAP path (`broker.rs` exit-waiter → `sessions.remove(&id)`), NEVER the controller-detach path (`detach_if`→`clear_controller`→`stamp_driven_by`, the ONLY stamp-clear). The exit-waiter had no stamp clear, so the OutputLog dropped with the controller slot occupied and `controlled` / `viewer_count` / (`driven_by` for a remote controller) latched in `info.json` forever — the picker + cross-node gossip then lie about control state indefinitely. Distinct from 7.15 (that heals a SESSIONLESS perch via the reconcile; this is a session that DIED with its stamps still set, cleared at the reap itself). - **Invariant:** on session reap the broker clears the perch's control/viewer stamps — `OutputLog::stamp_reaped()` = `set_driven_by(None)` + `set_controlled(false)` + `set_viewer_count(0)` via the known endpoint id — so no teardown path leaves a stamp behind. The broker stays the SINGLE writer; the clear is unconditional (idempotent when already clear) and RACE-FREE — the session is dead, so there is no live controller to re-stamp concurrently (the same argument as 7.15's no-session leg). Best-effort like the sibling stampers (empty endpoint ⇒ nowhere to record). The residual ~1 min `ONLINE` tail after child death is the roster liveness-decay window (separate, lower priority) — but `CONTROLLED` no longer lies. - **spt-core mapping:** impl `broker.rs` `OutputLog::stamp_reaped` + the exit-waiter reap call (before `sessions.remove`); int (real broker+PTY, no mocks) `crates/spt-daemon/tests/control_stamp_lifetime.rs` `reap_clears_control_and_viewer_stamps` (spawn hosted session → the live controller stamps `controlled=true` → latch `driven_by`+`viewer_count` on disk → KILL the child → the reap clears all three; RED-first verified: fix disabled leaves `driven_by=Some`, `controlled=true`, `viewer_count=Some(2)` past reap). Killing the child (not dropping the conn) isolates the reap leg — the detach path never runs. - **Source:** F-026 W1 #2 (BUILD-F026-PICKERTRUTH; doyle triage + gate, todlando build 2026-07-03). --- ### 7.28 A relative manifest path resolves against the ENDPOINT, never the daemon `[REQ-STORE-CONTEXT-BRANCH-FILL]` - **Class rule:** a relative manifest path naming a filesystem location the ENDPOINT reads or writes MUST resolve against the endpoint's own cwd (its `info.json.cwd`, read at USE time), never the daemon's process cwd. A single daemon hosts many endpoints with different cwds, so a relative path frozen or read against the daemon cwd points at a directory no endpoint uses. Keys that resolve via `{cwd}` template substitution (`[digest].source`, `[history].locate_template` — `{cwd}` filled from `info.cwd`) or that the daemon fills with a computed ABSOLUTE path (`[message-idle-translation-binary].path` ← install-dir/PATH program resolution) are already endpoint-anchored and out of scope; the verbatim-`PathBuf::from` keys are the risk. - **Failure (F-026 SI-1, box-wide, evidence-complete):** the two-tier context BranchStore (`tracked/.seed.git`) held ZERO `a-*`/`p-*` branches on HFENDULEAM despite months of live-agent use — 0 objects, unborn HEAD, no `projects/` worktree checkouts, no commune drop files anywhere (psyche context flowed via the SEPARATE spt-agent-storage sync, masking it). ROOT: `BrainLifecycle::with_config_in` used `manifest.session.commune_dir` / `signoff_dir` VERBATIM (`PathBuf::from`). claude-spt declares `commune_dir = ".claude"` (RELATIVE, documented "resolved per-endpoint against its cwd"), so `drop_dirs()` yielded a bare `.claude` that `ingest_drops` joined against the DAEMON's cwd (`drop_path.exists()==false` every pulse → `continue` → zero ingest → zero commit). Compounded: the frozen `project_id = project_id_for_dir(commune_dir.parent())` = `project_id_for_dir("")` = garbage. Every daemon test injected an ABSOLUTE tempdir `commune_dir`, so the relative leg was NEVER exercised (the use-it-like-a-human gap). - **Invariant:** drop-dir resolution + project-id derivation happen AT INGEST TIME against the endpoint's fresh `info.cwd` (`pulse_tick`, not frozen at construction): absolute → as-is; relative + a recorded cwd → joined under it; relative + NO cwd → SKIPPED with a LOUD-once `DROP_INGEST_SKIP` diagnostic (never guessed, never the daemon cwd). Project-tier routing is owlery-gated — an owlery-internal anchor (psyche-host session) resolves its drops verbatim but routes NO `p-` branch (empty project_id → `route_slices` skips `commit_project`; mirrors the picker's owlery exclusion); a non-owlery anchor derives `project_id` via the SAME `project_id_for_dir` the picker uses (category-key parity). Pure back-compat: absolute manifests unchanged, no wire change, no adapter republish (the manifest already documented the contract). SECONDARY (perri consumable, release-ping): `p-*` fills only if the commune body carries a `` slice — claude-spt's authoring must emit one. - **spt-core mapping:** impl `spt-daemon/src/lifecycle.rs` `resolve_endpoint_drop_dir` + `is_owlery_internal` + `warn_no_cwd_once` + `pulse_tick` (reads `info.cwd`, resolves each drop dir, derives owlery-gated `project_id`) + `spt-live/src/ingest.rs` `route_slices` (empty-project_id skips the project tier); unit `resolve_endpoint_drop_dir_cases` + `is_owlery_internal_cases` (lifecycle.rs) + `empty_project_id_skips_project_tier` (ingest.rs); int (real pulse + real store) `relative_commune_dir_resolves_against_endpoint_cwd_and_fills_project_branch` — a RELATIVE `.claude` + a real endpoint cwd → the drop is found and `a-` + `p-` commit (RED-first: verbatim-relative resolution → 0 ingested, store pristine). - **Source:** F-026 SI-1 (BUILD-F026-PICKERTRUTH; doyle RCA-gate + design ruling, todlando build 2026-07-03). Hazard-class sweep confirmed commune_dir+signoff_dir the ONLY verbatim instances. --- ### 7.29 Control/viewer stamps CONVERGE to broker session-table truth, not merely edge-trigger `[REQ-HAZARD-CONTROL-STAMP-CONVERGENCE]` - **Failure (F-026 stamp-gap, hall-b + the original ball-b):** a picker-created endpoint (`endpoint run` → new) read plain `ONLINE` in the list + picker while genuinely driven — `info.json` `controlled:false` throughout. ROOT (the UPWARD companion to 7.27's downward edge-clear): the broker spawn path's `become_controller` → `stamp_driven_by` → `set_controlled(true)` fires at SPAWN time, but a FRESH endpoint has NO PERCH yet (the adapter binds it after claude boots), so `mutate_info` returns `NotFound` and every stamper swallows it (`let _`). The adapter's bind then writes `InfoJson::new` with `controlled:false` DEFAULT, and since the operator never re-attaches, no later EDGE ever re-stamps → the endpoint reads uncontrolled FOREVER while driven. The 7.15/7.27 edge model (stamp on become-controller / clear on detach/reap) has no re-assert for a stamp LOST to a not-yet-existing perch. (The #3 display fix reads `controlled` correctly — it was simply datum-starved on this creation path.) - **Invariant:** the broker (SINGLE writer) re-asserts each live session's control/viewer stamps to session-table TRUTH, DIVERGENCE-GATED — read the perch's recorded `(driven_by, controlled, viewer_count)`, compare to the live truth (`controller_by()` / `has_controller()` / live `viewer_count`), and write ONLY on a real difference (no per-poll fsync storm). The re-assert rides the `KIND_SESSIONS` handler (the daemon reconcile + picker poll it on cadence), so a fresh perch CONVERGES within one reconcile-poll window after bind — a BOUNDED window, no new timer. Truth is SNAPSHOTTED under each log lock; the convergence writes run OFF the lock (the lock-across-effect discipline, 7.12/5.16). Event-on-input is INSUFFICIENT (an idle controlled session — the operator attached, not typing — never converges); the poll-driven re-assert covers it. Complements 7.27: 7.27 clears a stamp when its session dies (downward), 7.29 asserts a stamp while its session lives (upward) — together the stamp always equals broker truth. - **Coverage boundary (who MAY clear vs who MUST NOT — cross-ref 7.15):** the convergence's `driven_by`-clear leg fires ONLY when `has_controller()==false` — the DEFINITIVE broker signal (it reads its OWN controller slot, not the ambiguous `controller_by`). That is why the broker MAY clear a stale `driven_by` where the BRAIN reconcile (7.15) MUST NOT: the brain only sees `controller_by==None`, which a live LOCAL controller also reads, so a brain clear would false-heal a genuinely-driven session. This leg is belt-and-suspenders over the clean-disconnect `detach_if`→`clear_controller` (which already zeroes `driven_by` on a clean drop). The convergence does NOT close the HALF-OPEN wedged-remote residual — an abandoned REMOTE controller whose conn stays OPEN (no FIN) keeps the broker's controller slot, so `has_controller()==true` and convergence correctly KEEPS the stamp (it cannot tell a wedged-open conn from a live one). That leg stays deferred to `REQ-HAZARD-DRIVEN-BY-IDLE-REMOTE-EVICT` (oracle = the D4c NetPresence disconnect → `clear_controller`, per the 2026-06-19 ruling) — **narrowed 2026-07-22 by the Leg B measurement recorded in 7.15: the DEAD-transport-no-FIN half heals on QUIC's own idle timeout (120ms clean / 65s torn, measured), so what is still deferred here is the ALIVE-but-WEDGED conn, where the transport never dies and convergence genuinely has no signal to read.** - **spt-core mapping:** impl `broker.rs` `stamp_divergence` (pure gate) + `converge_perch_stamps` (off-lock, single-writer, skips a perch-less/corrupt endpoint) + `OutputLog::has_controller`/`live_viewer_count` (snapshot accessors) + the `KIND_SESSIONS` handler (snapshot-under-lock → converge-off-lock); unit `broker.rs` `stamp_divergence_gates_writes` (no-diff → no write; `controlled false→true` = the stamp-before-bind case; driven_by / viewer / both); int (real broker+PTY) `control_stamp_lifetime.rs` `converge_stamps_on_sessions_poll_after_late_bind` (spawn with NO perch → spawn stamp swallowed → LATE bind writes `controlled:false` → a `KIND_SESSIONS` poll converges `controlled=true`; RED-first: hook disabled leaves `controlled:false` forever). - **Source:** F-026 W1-addendum (BUILD-F026-PICKERTRUTH; doyle stamp-gap dispatch + convergence ruling + KIND_SESSIONS-hook approval, todlando build 2026-07-03). ### 7.30 A Psyche failure of ANY shape must NEVER remove or alter the parent endpoint's ready/hosted state `[REQ-HAZARD-PSYCHE-RESIDENCY-EXPECTATION]` - **Failure (paid-for, field brick 2026-07-04, adapter v0.13.2):** the pre-F-030 model kept a **resident** Psyche process the daemon supervised, with residency machinery (`confirm_residency_or_unhost`) that **un-hosted the parent endpoint** when the resident child went missing. A bad adapter ship (v0.13.2) made the psyche shim exit on every turn; the residency machinery read that as a lost resident and **tore down the parent's hosted state — the ready marker was removed and never re-stamped**, so every `--force-native` delivery then gated `cli-gate-not-hosted` PERMANENTLY. A Psyche problem silently bricked the parent LiveAgent. (Companion churn class: 7.31.) - **Invariant:** a Psyche is a **bounded per-event turn**, not a resident process — its liveness is that turns succeed, so there is no "resident is gone" signal to react to. A psyche turn failure of ANY shape (spawn fail, non-zero exit, timeout, wedge) stamps **psyche fields only** (`psyche_host_error` on the Self perch) and **NEVER** touches the parent endpoint's `status` / ready marker / hosted state; the endpoint stays online and deliverable while its Psyche is unwell. The teardown-on-psyche-trouble path is **deleted** with the residency machinery. `REQ-HAZARD-LIVEHOST-NONRESIDENT`'s spirit (a psyche that cannot work must be visible on the perch, hosting must not churn) transfers to the per-event failure budget (7.31); its traceable entry carries a SUPERSEDED pointer here (the LIVENESS-DECAY→SUPERSEDED pattern). - **spt-core mapping:** the residency/reap DELETIONS in `spt_daemon::livehost` (`reconcile_once`'s stop-side no longer un-hosts on psyche trouble; `host_one` holds no resident child) + `spt_daemon::lifecycle::run_psyche_event_turn` (a turn failure stamps `psyche_host_error` only) + the `first_turn_psyche_context` non-empty guarantee (a zero-context fresh turn can't masquerade as continue → reseed churn). Conformance int = the hall-bf shape: multi-subnet home, live endpoint, a psyche turn that fails every fire → parent ready marker PRESENT + deliverable stays TRUE, endpoint NOT un-hosted, no rehost churn, `psyche_host_error` stamped (the wave's heart). - **Source:** F-030 (psyche-ephemeral) — paid-for by the hall-bf churn (ordinal 6491+) and the adapter v0.13.2 bad-ship brick, 2026-07-04. ### 7.31 The Psyche failure budget must count REAL per-event attempts — a resident rate-guard is blind to per-event churn `[REQ-HAZARD-THRASH-GUARD-BLIND]` - **Failure (paid-for, field evidence 2026-07-04):** the pre-F-030 resident-hosting thrash guard keyed on ledger-rate boundaries that were NOT the real re-host attempts. On hall-bf a **~12/min** re-host churn ran completely **invisibly** — the guard never tripped, never stamped, never cooled down, because the boot records it looked at were not ledger boundaries the guard counted. A runaway failure loop looked healthy. - **Invariant:** the failure budget counts **REAL per-event attempts** — every bounded per-event psyche turn feeds a consecutive-failure budget (default 3): N consecutive turn failures → `psyche_host_error` stamp + cooldown, reset on the next clean turn. Because each real attempt is one counted turn, the churn the resident rate-guard was blind to now counts **by construction** (no separate rate belt). A synthetic per-minute failure loop MUST trip the budget. - **spt-core mapping:** the per-event turn-failure budget IS the guard — `spt_daemon::lifecycle` `note_turn_outcome` / `psyche_turn_strikes_exhausted` (every real turn attempt feeds it; stamps `psyche_host_error` on exhaustion WITHOUT de-stamping `status`/ready — see 7.30). unit = a synthetic consecutive-failure loop trips the budget + stamps, pure/no-sleep, with a budget→never-exhaust guard-revert as the RED-first control. - **Source:** F-030 (psyche-ephemeral) — paid-for by hall-bf's ~12/min invisible re-host churn (evidence #6), 2026-07-04. ### 7.32 The effective resting state MUST be derived through ONE shared liveness-aware function — a stored-intent-alone read lies about cold perches `[REQ-EFFECTIVE-INSTANCE-STATE]` - **Failure (paid-for, field evidence):** two rest-state readers derived the effective instance state independently. `registryhost::advertised_status` read it liveness-aware (cold ⇒ Suspended); `resting::apply_event` derived its `from` off the stored `rest_state` intent field ALONE (`unwrap_or(RestState::Active)`). A cold (offline) perch with no resting intent therefore looked **Active** to `apply_event` — so a `Wake` event found it "already in the target state", the pure table returned `None`, and the endpoint reported **NO_EDGE on a definitely-suspended endpoint** and could never be woken. The mirror defect: a `Suspend` on that same cold void perch faked an Active→Suspended edge and fired a spurious transition echo (a bounded LLM call) on a driver that was never active. - **Invariant:** the effective resting state of a perch is derived through the ONE shared `resting::effective_rest_state(alive, unbound, intent)` — liveness discriminates warm from cold, stored intent refines only *within* warm, and absent intent NEVER defaults active. Both `advertised_status` (via a RestState→Status map) and `apply_event`'s `from` route through it, so the two readers can never drift. Any new rest-state reader MUST use the same derivation — two independent derivations WILL disagree, and that disagreement IS this bug. - **spt-core mapping:** `spt_daemon::resting::effective_rest_state` is the single derivation; `advertised_status` and `apply_event` both delegate. unit = a pure 3×4 liveness×intent table + two `apply_event` wire tests (a cold void perch Wakes as a real Suspended→Active edge; a cold void Suspend is a no-edge that fires no echo), each RED-first against the old `unwrap_or(Active)`. - **Source:** REMOTE-TRUTH A-1 (effective-instance-state shared derivation), ADR-0033 §Decision (Q1 ruling: one shared derivation). ### 7.33 NO bare `.lock().unwrap()` on a broker-resident lock reachable from serve/dispatch — a poison permanently wedges every attach `[REQ-HAZARD-BROKER-FLOOR-LOCK-POISON]` - **Failure (paid-for class):** a brain-only self-update restarts the BRAIN but keeps the BROKER process — and every one of its `Mutex`es — ALIVE by design (REQ-UPD-3). So a single panic while another thread held a broker-resident lock POISONS it permanently: the next `.lock().unwrap()` panics too, kills its per-conn reply thread, and EVERY subsequent attach silently deadlines (`spt rc` → "brain IPC read deadline elapsed") while non-locked ops keep working. The effect journal (bug #16, `[REQ-HAZARD-EFFECT-JOURNAL-PTY-WEDGE]`) and the inject floor (`[REQ-HAZARD-INJECT-WORKER-POISON]`) were fixed one lock at a time; the SURVIVING class was the attach-path locks — the session map (`sessions` ×18 + its `sessions_exit` alias), the per-session `OutputLog` ring (×11), and `pair_holds` (×4) — all bare `.lock().unwrap()`. - **Invariant:** NO broker-resident lock reachable from serve/dispatch may use a bare `.lock().unwrap()`. Recover via the shared `recover` (`into_inner` — safe for the short, coherent-on-recovery map ops of `sessions`/`pair_holds`) or, for the `OutputLog` ring, `recover_log` — which adds a COHERENCE CLAMP on the recovery path: a panic mid-`append` can leave the ring torn (over-cap, a last seq not below `next_seq`, non-monotonic), and serving those bytes risks garbage, so `clamp_or_reset` cheap-checks the invariants and RESETS the ring empty (`next_seq` preserved — cursors never rewind) + loud-logs on violation. Fail-fast on the log would REINTRODUCE the wedge; blind recover would serve torn bytes; clamp-or-reset costs only scrollback that self-heals on the next PTY output + repaint. Any NEW broker-resident lock must use `recover`/`recover_log` or carry a documented fail-fast justification. - **spt-core mapping:** `broker::recover` / `broker::recover_log` / `OutputLog::clamp_or_reset`. unit = a poisoned session-map recovers to a usable guard (the next attach still opens), a torn ring clamps/resets-empty only when torn (coherent untouched, `next_seq` preserved), and `recover_log` wires the clamp onto the poison branch — each RED-first against a bare `.lock().unwrap()` / an un-clamped `into_inner`. int (scripted panic-under-lock during concurrent attach → next attach opens) deferred to the two-host rig. - **Source:** REMOTE-TRUTH B-1 (pivoted — the triage's named floor sites were already closed by `[REQ-HAZARD-INJECT-WORKER-POISON]`; the surviving attach-path lock class is the real root), doyle B-1 ruling (recover all three via one helper + the OutputLog ring coherence clamp). ### 7.34 A dead `rec.pid` on an spt-hosted perch is EXPECTED — no reader may alive-gate on `rec.pid` alone `[REQ-HAZARD-DEAD-REC-PID]` - **Failure (paid-for, field evidence — the F-026 #11 dead-pid class):** an spt-hosted endpoint's `rec.pid` records the ephemeral bind-CLI pid, which dies IMMEDIATELY after bind (the broker holds the PTY; there is no resident harness process at that pid). Readers that alive-gated on `rec.pid` alone treated the perch as stale: self-detect leg (c) could NEVER resolve an spt-hosted sender (its from-stamp degraded to `cli@NODE`, operator #7, and replies bounced `NO_PERCH` — sighted on hall-bf/ball-b, v0.24.0). - **Invariant:** a dead `rec.pid` on an spt-hosted perch is an EXPECTED state, not staleness. NO reader may alive-gate on `rec.pid` alone: spt-hosted LIVENESS comes from the daemon-managed `status` field (KH 2.5 — status present ⇒ authoritative, never a per-pid probe); IDENTITY comes from session/ancestry resolution, where `rec.parent_pid` (the harness pid, the stable session-binding anchor) is the ancestry candidate (ADR-0021 seed-hint discipline: pid is a bind-time SEED, not a truth anchor — re-anchoring truth in `rec.pid` is overruled by design). Any newly sighted `rec.pid`-alive-gating reader gets the same scoped fix and extends THIS requirement's evidence — no new REQ per reader. - **spt-core mapping:** `roster.rs` `detect_self_by_ancestry` (the first sighted reader, fixed by `[REQ-SELF-DETECT-PARENT-PID]`: `parent_pid` candidates alongside `rec.pid`). int = the E-1 red-first (`detect_self_resolves_spt_hosted_perch_via_parent_pid`: dead `rec.pid` + live-ancestor `parent_pid` resolves), dual-tagged as this class's test. - **Source:** REMOTE-TRUTH E-1 rider (doyle ruling 2026-07-05: scoped reader-side (b) over re-stamping `rec.pid` (a) — ADR-0021 ground truth, migration hole, blast radius). ### 7.35 The cached ceremony-clock NTP offset must NOT survive an OS clock STEP — an offset measured against the pre-step clock strands every pairing for the TTL `[REQ-HAZARD-CEREMONY-CLOCK-STEP]` - **Failure (paid-for, field evidence — the enlyzeam BIGNET-join RCA 2026-07-06):** enlyzeam's `w32time` was STOPPED, so its system clock drifted +3m30s; the pairing ceremony offset (REQ-PAIR-8, `ntp.rs`) correctly corrected the TOTP clock — until an operator `w32tm /resync` STEPPED the OS clock back −210s under the LIVE daemon. The cached offset had been measured against the OLD (drifted) clock and its snapshot was monotonic-only (`when: Option`), so the step was invisible to the cache: for up to the 15-min TTL the ceremony clock stayed ~7 TOTP steps in the past, every `subnet join` returned NO_SEED_HOLDER while fresh-process probes met in <500ms, and only a daemon bounce (which forced a fresh query) healed it. Timeline-proven: refresh cadence 15:08/15:23/15:38/15:53; resync-step 15:45:46; joins failed 15:46–15:52; bounce healed instantly. - **Invariant:** the offset cache MUST detect an OS clock step and re-query, never apply a stale offset across it. The snapshot stores an `(Instant, SystemTime)` PAIR; on every read, if the wall clock diverged from the monotonic clock since the snapshot beyond a small tolerance (`|wall_elapsed − mono_elapsed| > ~2s`) the OS clock STEPPED ⇒ force an immediate re-query (offset recomputed against the new clock) regardless of TTL. Belt-and-braces at the join edge: `meet_seed_holder`, on search-deadline exhaustion, forces ONE fresh NTP query and runs one final sweep at the corrected step before the NO_SEED_HOLDER verdict — so a stepped-clock join self-heals WITHOUT a daemon bounce. The step tolerance sits far below one TOTP step (30 s) and well above scheduling jitter. Contract of REQ-PAIR-8 (lazy TTL cache, system-clock fallback, never sets the OS clock) is otherwise unchanged. - **spt-core mapping:** `spt_net::net::pairing::ntp` — `CachedOffset{when, wall_at}` pair + `refresh_needed`/`clock_stepped`/`signed_secs` (step-detect) + `force_refresh`/`invalidate` (the meet-exhaustion re-query seam); `spt_daemon::pairhost::meet_seed_holder` via `sweep_then_final_retry` (force-refresh + one final sweep on exhaustion). unit = `clock_step_forces_refresh_via_injected_reads` (injected mono/wall reads: a wall step forward OR back with mono barely moved re-queries; agreeing clocks within TTL do not; TTL-expiry and never-queried also refresh — no 15-min sleep) + `invalidate_clears_the_snapshot` + `meet_retries_once_after_refresh_on_exhaustion`/`meet_final_retry_failing_surrenders_once` (exactly one post-refresh retry, then surrender with the richer error). - **Source:** JOIN-TRUTH W1/D3 (doyle /diagnose enlyzeam RCA; the offset defeated by a live clock step is the D3 of four defects, D1 multihome + D2 loud-fail + D4 verbose-clock the siblings). ### 7.36 The broker control plane and PTY fan-out must NEVER block on a single subscriber connection — a suspended brain conn must not wedge control `[REQ-HAZARD-BROKER-VIEWER-BRAIN-DECOUPLE]` - **Failure (paid-for, rig-CONFIRMED 2026-07-06/07 — `NtSuspendProcess` on the brain, no update involved):** a controller's writer thread does a BLOCKING socket write to its brain subscriber conn. When that brain is suspended (or black-holed) the write never returns. The output-driven eviction path (`append` → `mark_controller_gone`, bounded by 7.12's `CONTROLLER_WRITE_DEADLINE`) only fires on NEW output, and `reap_dead_controller` (7.29 companion) only caught a writer that had EXITED — so a controller BLOCKED (not exited) on an IDLE session was evicted by NEITHER. Within seconds: attached output froze, `detach` did not release the control stamp (release routed through the wedged conn), reattach was REFUSED (`controlled-by` latched), `rc --take` hung, and `daemon status` still read healthy. Every brain cycle — including every `update apply` — has such a freeze window; a stalled or slow-draining NEW brain (6 sessions + psyches + WAN on the incident night) makes it a PERMANENT wedge until a bounce. `brain.ready ≠ subscribers drained` — why the 22:47 apply "promoted" while frozen. - **Invariant:** no broker client ever observes a wedge because the BRAIN stalled. (1) The controller's writer publishes its IN-FLIGHT-write window (`write_blocked_since`: `Some(Instant)` set immediately before the blocking `write_frame`, `None` after — the mutex never held ACROSS the write); a reader sees a `Some` older than `BRAIN_WRITE_DEADLINE` (15 s = 3× the 7.12 controller bound, measured full-with-**zero writer progress**, so a slow-but-DRAINING brain never trips it) as a WEDGED writer and stall-evicts it. Eviction is triggered TIME-based, not output-driven: at the take/reattach path (`resolve_subscribe`, so control self-heals against broker truth even on an idle session) AND at the `KIND_SESSIONS` reap. (2) The stamp release is BROKER-side — `clear_controller` re-stamps `driven_by`/`controlled` with no brain round-trip, so `controlled-by` can never latch behind a dead transit; `rc --take` and reattach-refuse consult live `has_controller()` truth. (3) The evict is OBSERVABLE, never a silent absence — a per-evict broker-log line plus a broker-global tally (`count` + `last_ms`) surfaced on `daemon status` (a brain that never returns is then a diagnosable fact). Idle ≠ wedged: an idle controller (writer parked on `rx.recv()`, `write_blocked_since` `None`) is NEVER evicted; only a genuinely-blocked writer is. Complements 7.12 (which bounds a merely SLOW controller's Full channel) and 7.29 (which converges stamps to broker truth) — this covers the BLOCKED-conn case both leave open. Deferred (Q2, minimal-plus): the WHOLESALE take/release verb-set migration off the brain stays out; the suspend-brain int rig is the arbiter — if it passes with the stall-evict shape, the wholesale move is scope creep. **Residual — BOUNDED by W2, CLOSED by W3 (`REQ-UPDATE-PROMOTE-DRAINED`):** the stall-evict shrank the update-apply FALSE-PROMOTE window from unbounded to `BRAIN_WRITE_DEADLINE` (15 s) — `brain.ready` could still arrive inside that window while blocked writes pended on the OLD-generation subscriber conn (`brain.ready ≠ subscribers drained`, the 22:47 apply). W3 CLOSES it: the ADR-0018 brain-trial promotion gate (`brainproc::run_trial`) now LATCHES ready-seen and promotes only on ready **AND** `TrialEnv::old_gen_drained()` — a broker-truth read (`Broker::any_local_controller_wedged`, the brain's own `by:None` conn wedged past the deadline; a remote conn is excluded, it is the W2 concern not an old-gen brain conn), no brain round-trip. Ready-but-never-drained elapses the trial window → kill + rollback (conservative; never a false-promote onto a wedge). The false-promote int rig (`tests/false_promote.rs`) exercises the promotion path itself, RED-first. - **spt-core mapping:** `broker.rs` — `ControllerSink::write_blocked_since` + `controller_writer` (marks the in-flight window around both the initial-batch and live-loop writes) + `controller_write_stalled` (pure predicate over injected `now`/`deadline`) + `stall_evict_controller` (Inline stamp at `resolve_subscribe`, Deferred stamp at `reap_dead_controller` so the reap closure does no I/O under the shared sessions lock) + `record_stall_evict`/`stall_evict_stats` (the tally) + `dispatch_stall_evicts` (`KIND_STALL_EVICTS` IPC); `brain.rs` `Brain::stall_evicts`; `cli.rs` `render_stall_evict_line` (daemon-status surface, public wording). unit = `controller_write_stall_predicate_distinguishes_wedged_from_idle` + `stalled_incumbent_is_evicted_on_reattach_and_control_released` + `reap_evicts_a_blocked_writer_not_only_an_exited_one` + `stall_evict_line_surfaces_only_a_real_tally`. int = `brain_decouple.rs` `suspended_brain_controller_is_stall_evicted_take_completes_viewer_ticks` — the deterministic in-process ANALOG of a suspended brain (a REMOTE controller that stops reading parks the broker writer in `write_frame`, the same primitive `NtSuspendProcess` produces), asserting EXACTLY four things: (1) an attached viewer keeps ticking during the wedge, (2) a second operator's `Control` subscribe COMPLETES via stall-evict (RED-first: remove the `resolve_subscribe` evict → `BusyControlled` + `evicts=0`), (3) it resolves promptly (well under the watchdog), (4) the evict is tallied (observability); Linux leg on kitsubito. It does NOT re-assert resume + cursor-replay byte-identity — W2's delta does not touch the replay path, so output integrity stays covered by the pre-existing ring/cursor units (effect-journal replay dedup, the `delivered_through` no-rewind CAS `advanced_cursor`, clean-repaint cold-attach). The live `NtSuspendProcess`/`SIGSTOP` run on a real brain child remains the MANUAL field rig from the incident night, not a CI test. - **Source:** LIFECYCLE-TRUTH W2 (doyle rig `NtSuspendProcess` root + design ruling `docs/W2-DESIGN-RULING.md` @60ec0ed — minimal-plus scope, `BRAIN_WRITE_DEADLINE` 15 s, passive resubscribe + observability rider; todlando build 2026-07-07). The v0.27→v0.28 update-wedge night's flagship defect. ### 7.37 The Layer-1 settle-gate must RE-ARM per delivery on an observable PTY — a mid-session reader reattach (`/clear`) re-creates the head-swallow race `[REQ-HAZARD-INJECT-SETTLE-REARM]` - **Failure (paid-for, field-CONFIRMED on 0.29.0 — doyle diagnosis + perri screenshot `WindowsTerminal_6iSjya8pMt.png`):** the shipped W5-A settle-gate (7-of-W5, `REQ-INJECT-MULTILINE-INTEGRITY`) gated Layer 1 behind a worker-local ONE-SHOT (`settled_once`) on the premise that the head-swallow race is a STARTUP condition (the input reader not yet attached after spawn). That premise is FALSE: a mid-session `/clear` re-enters the harness's raw-mode input reader, re-attaching it and RE-CREATING the pre-settle window — but the one-shot had already fired at spawn, so `settle_before_inject` was SKIPPED and the head was eaten again. A checkpoint-wake payload injected right after `/clear` arrived head-truncated (mid-path `spt/Cargo.toml)`); echo-verify (Layer 2) is a default-OFF declared capability (`SPT_INJECT_VERIFY_ECHO`) for that session, so the loss was silent AND unrecoverable (a live-SENT inject leaves no spool copy). - **Invariant:** the settle-gate re-arms before EVERY delivery on an OBSERVABLE (echoing/interactive) PTY — the bug-prone class, where re-settling is cheap (a tick or two once the reader answers) and necessary (a mid-session reader reattach must be re-confirmed). The steady-state settle is latch-skipped ONLY where the probe is known UNOBSERVABLE on this PTY (a non-echoing ConPTY whose DSR answer never surfaces): there is no reader-reattach race to guard, and each settle would burn the full `INJECT_SETTLE` deadline. The class is discriminated by the settle's OWN return value — `settle_before_inject` returns `true` iff the session ring advanced (probe observed) — latched on the FIRST attempt only; a RE-DRIVE (`attempt > 1`, reached only on a swallowed head) ALWAYS settles regardless of the latch. This preserves the old one-shot's sole legitimate purpose (sparing a non-echoing ConPTY the deadline on every delivery) while closing the mid-session recurrence for echoing PTYs. - **spt-core mapping:** `broker.rs` `run_inject_worker` — the `settled_once: bool` one-shot is replaced by a `probe_unobservable: bool` latch (init `false` = assume observable → settle first delivery); the gate is the pure `should_settle(attempt, probe_unobservable) = attempt > 1 || !probe_unobservable`, and the first-attempt settle's `observed` return sets `probe_unobservable = !observed`. `settle_before_inject` gains a `bool` return (observed vs timed-out). unit = `should_settle_rearms_on_observable_pty` (observable PTY re-settles each delivery; unobservable-probe PTY skips the steady-state settle; a re-drive settles in both classes — RED-first: restore the one-shot and the observable-PTY assert flips). No int edit: the `inject_control_wedge.rs` mocks (`findstr`/`cat`) never answer the DSR probe → the settle times out → `probe_unobservable` latches true after delivery 1 → behaviour is IDENTICAL to the old one-shot for those non-echoing mocks; only a genuinely echoing PTY changes (it re-settles), which is the fix. Rides `REQ-INJECT-MULTILINE-INTEGRITY`'s existing int coverage. - **Source:** post-0.29.0 field fix (doyle diagnosis + design ruling `BUILD-SPEC-inject-settle-rearm`; todlando build 2026-07-08). An impl bug in the shipped W5-A Layer-1 fix, not a new invariant class — the settle-gate was correct but under-armed. ### 7.38 EVERY write on a physical broker connection is bounded + cancelable + poison-on-failure — no writer holds the send gate across an UNBOUNDED OS write `[REQ-HAZARD-SHAREDSEND-NO-BLOCKING-WRITE-UNDER-LOCK]` - **Failure (paid-for, field capture + deterministic Windows repro 2026-07-09 — hertz RCA, UPDATE-WEDGE round-4):** `controller_writer` held the `SharedSend = Arc>` guard ACROSS a blocking `write_frame`. On Windows, `interprocess 2.4.2` routes the send to `WriteFileEx` + `SleepEx(INFINITE, alertable)` — this local-socket send path exposes **no supported write timeout** (`set_timeout` → `Unsupported`). An `rc --take` controller consumer that stopped reading blocked the write **indefinitely** (~127.95 s in the capture, released only when a brain restart tore the connections down). The 7.36 logical `stall_evict_controller` removed the controller ROLE but neither canceled the in-flight pipe write, closed the physical connection, nor called `CancelIoEx` — the detached writer kept its `SharedSend` clone and live stack-owned mutex guard, and every other write queued at that gate wedged behind it. Load-gated: needs a real `seq>0` frame plus a non-draining consumer (seq-0 boot conns and a quiescent update are clean — why v0.30.5's controlled apply passed). `CTRL_WRITE_LOCKED wait_us=0` on all four capture writers exonerates the mutex convoy: the block is INSIDE the OS write, after lock acquisition. Neither existing deadline bounds it: `CONTROLLER_WRITE_DEADLINE` is output-driven channel-full handling (a writer blocked on its first owned frame never fills the channel); `BRAIN_WRITE_DEADLINE` is an age predicate sampled opportunistically, not an I/O timer. - **Invariant:** every write on a physical broker connection rides ONE broker-owned bounded/cancelable framed-write primitive with an **independent out-of-band aborter**. The `SendHalf` never leaves the conn object (a bypass cannot compile). An ABSOLUTE deadline stamped at write entry covers BOTH the serialized gate-wait AND OS write completion; a per-conn watchdog fires at that deadline and aborts the in-flight op — never relying on the write returning or on opportunistic stall-evict sampling. On deadline / partial write / cancellation / unknown completion: (1) poison the whole physical conn idempotently, (2) abort read+write so `handle_conn` reaches existing EOF cleanup, (3) wait for the canceled op to report completion before releasing its buffer, (4) NEVER reuse the conn (a timed-out length-prefixed frame may be partially written — reuse would corrupt framing), (5) finish/join the retired writer before reporting physical cleanup. Controller (replay + live), viewer, dispatch-reply, and nethost stream/presence writes ALL route through the primitive — any raw unbounded write left behind the gate preserves the failure class. NO additional output queue (the bounded queue + isolated writer already exist; the block is BELOW them); NO `PIPE_NOWAIT` (recorded mid-frame corruption risk). The logical stall-evict (7.36) stays as the ROLE-release trigger; physical retirement authority is the bounded write itself. Unix keeps its existing semantics under the same poison/retire invariant. - **spt-core mapping:** `spt-daemon/src/conn.rs` `BrokerConn` (Condvar-gated serialized write gate + poisoned state + per-in-flight op id + watchdog + `abort_physical()`: cfg(windows) `CancelIoEx` → completion handshake → `DisconnectNamedPipe` raw kernel32 externs; cfg(unix) `UnixStream::shutdown(Both)`); `broker.rs` `SharedSend = Arc` + `controller_writer`/`viewer_writer`/`send_frame`/`send_error` routed; `nethost.rs` stream-log/presence sends routed. int = `brain_decouple.rs` `non_draining_controller_stall_evict_releases_writer_and_connection` (`#[cfg(windows)]`, the hertz 9-step: real PTY burst, black-holed remote controller, exactly one logical stall-evict via an independent draining conn, the black-holed conn's `handle_conn` finishes ≤2 s of logical release WITHOUT dropping the client, a write on the old client conn fails, a fresh controller resumes from the frozen cursor) — RED-first pre-fix; the cross-platform companion `suspended_brain_controller_is_stall_evicted_take_completes_viewer_ticks` stays green on both OSes. - **Source:** UPDATE-WEDGE round-4 (hertz root doc `docs/UPDATE-WEDGE-ROOT-CAUSE.md` @f8596ca; doyle gate ruling `docs/UPDATE-WEDGE-RCA-DISPATCH-todlando.md`; todlando build 2026-07-09). The residual 7.36 left open: logical eviction without physical retirement. --- ### 7.39 Per-session identity env (`SPT_ENDPOINT_ID`/`OWL_SESSION_ID`/`SPT_AGENT_ID`) is NEVER inherited — the daemon scrubs it at startup AND on every role spawn, regardless of any role's declared `env_remove` `[REQ-HAZARD-DAEMON-IDENTITY-ENV-SANITIZE]` - **Failure (paid-for, perri field RCA 2026-07-09/10 — F-036 psyche seat-theft):** a daemon restarted from inside an agent session (routine during core dev / `spt update apply`) carried the session's `SPT_ENDPOINT_ID=doyle` and passed it verbatim into every `[session.psyche_resume]` spawn — core stripped only each role's DECLARED `env_remove` list (runtime.rs `command_for`), so ONE adapter `env_remove` miss infected the whole node. Every psyche claude turn fired SessionStart, the adapter hook saw the leaked endpoint id, took the bind path, and ROTATED the victim's perch onto the psyche's own custody sid with a valid prior-sid proof — every pulse. Field blast radius: lia/deployah/doyle psyches ALL briefed as ``; 37 peer msgs drained into lia's psyche transcript; victim deliveries eaten, communes dark, sends downgraded to `from:cli@node`. - **Invariant:** the identity set (`spt_runtime::IDENTITY_ENV_VARS`) is per-session state and NEVER correct inherited state for a daemon or any child it spawns. The daemon (broker AND brain entries) scrubs its own process env first thing (`scrub_identity_env`); the shared role-spawn command builder scrubs the set unconditionally and LAST (after `env_remove`, read-env stamps, and the recursion guard), so no adapter declaration — missing or pathological — can leak identity into a role child. A spawn that NEEDS an identity var (a hosted harness) receives it by explicit per-spawn injection (manifest `[env] direction = "inject"`), never by inheritance. The same startup scrub also clears the inject-echo knobs (`spt_runtime::INJECT_ECHO_ENV_VARS`: `SPT_INJECT_VERIFY_ECHO`/`SPT_INJECT_FORCE_ECHO_MISS`) — same inheritance class, different payload: an inherited dev-shell export force-enabled the default-OFF Layer-2 echo-verify host-wide, and a false verify-miss RETYPED whole sequences into a live session's input field (the F-033 typed-garbage symptom). These knobs are startup-scrub ONLY (not in the role-spawn builder scrub): explicit per-spawn declaration stays the production on-switch. Companion guard (F-036 leg c, `REQ-BIND-PSYCHE-CUSTODY-SQUAT-GUARD`): a bind whose sid equals a nested psyche's OWN custody sid is refused loud (`PSYCHE_CUSTODY_SQUAT`) — the seat-theft class stays unreachable even under an unknown future leak vector. Related docs fix (leg b): `recursion_guard_env` is honored for ANY role declaring the field — the schema description is role-agnostic, not "summarizer children". - **spt-core mapping:** `spt-runtime/src/runtime.rs` `IDENTITY_ENV_VARS` + `scrub_identity_env` + the `command_for` unconditional scrub; `spt-daemon/src/daemon.rs` `Daemon::run` / `Daemon::run_brain` startup scrub; `spt/src/api/startup.rs` `establish_perch` custody-squat refusal over `spt-store/src/psyche_custody.rs` `custody_squatter`. - **Source:** MSG-IDENTITY W1 (perri F-036 RCA; doyle dispatch `docs/MSG-IDENTITY-DISPATCH.md`; adapter half shipped claude-spt v0.18.8 — this is the core-layer defense so no adapter miss can ever leak identity again). --- ### 7.40 A commune/signoff drop is deleted ONLY after every applicable tier is durably committed — an un-committable slice preserves the drop, never delete-then-lose `[REQ-HAZARD-COMMUNE-INGEST-BLACKHOLE]` - **Failure (paid-for, perri field finding 2026-07-08 — F-032, data-loss):** `ingest_drops` unconditionally deleted the drop after `route_slices`, but the project tier is GATED on a non-empty `project_id` — when the endpoint's anchor cwd was unresolved/owlery-internal at ingest time, the `` slice was parsed but never committed, yet the source drop was still deleted → the project-context content permanently lost. perri's two-sliced echo-commune INGESTED (file deleted) yet never surfaced at her next SessionStart resume-pull; adapter exonerated. Legacy spt held commit-first-then-delete parity; the modern two-slice ingest broke it. - **Invariant:** delete-after-commit, per slice. Distinguish a write **SUPPRESSED by precedence** (incoming older than durable → already superseded → safe to delete) from a slice **un-committable now** (empty `project_id`, or any write error → the `?` retry path). An un-committable non-empty project slice is preserved as a **project-only pending slice under the COMMUNE suffix, whatever the source drop's kind** — a signoff-suffix pending would be reaped by `sweep_stale_signoff` on the next listener start (the signoff sentinel is write-once-per-generation), recreating the black-hole on the signoff path; the commune-named pending is a pure project-slice carrier both suffixes ingest identically and the sweep never sees. The already-committed live slice is dropped from the pending so retries never re-commit it (no per-tick branch-commit churn; `write_context` has no LLM-after-LLM suppression), the rewrite is idempotent (the pending form re-parses to itself), and the next ingest with a resolvable `project_id` commits + deletes. A newer commune from the mind overwriting the pending file is a supersede (fresher LLM snapshot), not a loss. An endpoint whose project id NEVER resolves (psyche-host anchor cwd) retains its pending indefinitely — an intentional bounded no-op per pass, preferred over any deletion heuristic. Loud `COMMUNE_PROJECT_DEFERRED` on the preserve transition only. - **spt-core mapping:** `spt-live/src/ingest.rs` `ingest_drops` (deferred-project preserve + `Ingested.preserved`); `route_slices` project gate unchanged (`REQ-STORE-CONTEXT-BRANCH-FILL`); kin `REQ-HAZARD-DROP-FILE-SINGLE-WRITER` (core stays the single writer — the preserve rewrite is core's own write). - **Source:** MSG-IDENTITY W3 (doyle triage, code-grounded ingest.rs:156 gate vs :200 delete; repro fixture F-032-commune-2026-07-08T222721Z.md). --- ### 7.41 A fresh dispatcher must NEVER re-serve a terminal stream — historical replay must not steal or clear a live controller `[REQ-HAZARD-REDISPATCH-CONTROL-STEAL]` - **Failure (paid-for, hertz field RCA 2026-07-16 — 4/5 endpoints frozen, twice in one day):** every brain cycle (`spt daemon refresh`, `spt update` apply — same `applyhost.rs` path) launches a fresh `dispatch::run_dispatch_loop` whose EMPTY per-process `claimed` set enumerates every broker-held peer stream. `NetShared.streams` has NO removal path (`StreamLog::finish` only marks) and the claim condition has no finished filter → the fresh dispatcher replays FINISHED historical attach streams. A replayed historical Attach calls `attach_as(Control, same origin)` → same-identity silent `become_controller` (no `Displaced`) steals the CURRENT controller; the replayed EOF then `detach_session` CLEARS it. The live serve loop still believes it is Controller but its sink is deselected — the operator sees a FROZEN remote PTY (detach + fresh `spt rc` recovers, no PTY restart needed). Adjacent leg: classification peeks ring seq 0, but the data ring is bounded (4096 chunks) — an active stream whose opener evicted classifies Unknown/Failed with the claim burned pre-spawn, never retried → active stream permanently abandoned. - **Invariant:** redispatch eligibility is LIFECYCLE-gated: a finished/terminal stream row is retired from the dispatcher's enumeration (a fresh dispatcher never re-serves a terminal Attach); classification identity is restart-durable and independent of the evictable data ring (immutable opener fact pinned per stream until close); claims are retryable on transient worker-setup failure and terminal on terminal outcomes (no hot-loop). The legitimate same-`by` successor re-take after a brain restart still silently re-takes — the discriminator is lifecycle, never origin identity. Regressions ride the PRODUCTION rediscovery path (no manual re-serve — the pre-fix e2e bypassed exactly the broken seam). - **spt-core mapping:** `spt-daemon/src/dispatch.rs` `run_dispatch_loop` claim condition + `peek_first_line` classification + worker spawn; `spt-daemon/src/nethost.rs` `NetShared.streams` insert/finish + `DEFAULT_STREAM_RING_CHUNKS`; `spt-daemon/src/applyhost.rs` (the brain-cycle trigger). - **Source:** REDISPATCH-TRUTH W1 (hertz source-level RCA `.claude/reports/2026-07-16-redispatch-truth/hertz-refresh-rca.txt`, doyle seam-verified; ADR-0038; distinct from the CLOSED 0.30.x session-cursor resume-steal saga). --- ### 7.42 A node holding a valid roster address for a peer is NEVER route-less — a failed dial must not delete the only bootstrap route `[REQ-HAZARD-MESH-BOOTSTRAP-TRAP]` - **Failure (paid-for, hertz field RCA 2026-07-10 — HFENDULEAM + ENLYZEAM fully sequestered from every subnet member, symmetric, green-status):** the pump resolved dial addresses from the exact `peer-addrs.json` entry else id-only discovery — never the valid `RosterEntry.address` — and every `PRESENCE_DIAL_FAILED` unconditionally `drop_seed`'d the cached entry, while the cache refilled only after a future successful seed-proof connection. One transient failure converted a warm route into id-only-or-nothing; with id-only discovery stalled, isolation prevented its own repair. Both rosters held correct direct addresses (Tailscale ping ~12ms) the entire time; `net_up: true`, fresh heartbeat, normal durable counts — every status surface answered a different question than "can I reach anyone?". Compounding: `PeerAddrStore::put` validated nothing, so persisted poison rows (outer key ≠ nested `address.id`) survived roster correction on both nodes. - **Invariant:** dial-address resolution is the ROUTE CHAIN — exact cache → validated `RosterEntry.address` (id-match required) → id-only discovery — always fully consulted in order. A failed dial demotes a cached route (suspect), never deletes a sole route; removal happens only via validated-fresher replacement or roster tombstone. Validated roster addresses reconcile into the cache at startup and on roster merge — recovery never requires an already-successful connection or operator state surgery. `outer key == address.id` is enforced on load and write (repair-from-roster or reject, loudly; migration never bare-deletes the file). Peer-failure telemetry is stage-split and stamped; health reports live peer count + last real progress, and the incident's exact fingerprint renders DEGRADED. - **spt-core mapping:** `spt-daemon/src/pump/mod.rs` `resolve_submit_addr` + `presence_state_effect` (`PRESENCE_DIAL_FAILED` arm); `spt-store/src/peeraddrs.rs` `PeerAddrStore::put`/`drop_seed`; `spt-daemon/src/seedproofx.rs` `gapfill_peeraddrs`; status renders (`daemon status` / `subnet status`). - **Source:** MESH-RECOVERY W1 (hertz RCA `.claude/reports/2026-07-10-hertz-session/02-mesh-isolation-rca.md`, doyle seam-verified 2026-07-16; ADR-0039 — amends REQ-CONV-1's falsified "a stale addr never strands a peer" drop-on-fail mechanism). --- ### 7.43 One wedged stream subscriber must NEVER stall stream serving — replay halts at the first failed write, a poisoned subscriber is removed, and recovery machinery must not manufacture new replay victims `[REQ-HAZARD-REDISPATCH-STALL]` - **Failure (paid-for, hertz field RCA 2026-07-16 — live v0.34 boxes, recurrent 20–30s PTY/RC freezes, DISPATCH tails 17–62s):** a COMPOSITION, not one new timer. The dispatcher's retryable claims (500ms/1s ×3) re-drove the opener fallback whose guard arm is a broad `Err(_)` (`dispatch.rs:414` — comment intends old-broker-only; catches transport timeout/EOF/poison), each pass installing a throwaway peek subscriber. `StreamLog::attach` synchronously replays the ENTIRE retained ring under the per-stream mutex, `let _ = sub.write(&frame)` discards errors, iteration continues past failure, and the poisoned subscriber STAYS INSTALLED — one wedged subscriber conn = serial 15s bounded-write poison windows (33 observed, all 15,000–15,154 ms — the round-4 SharedSend deadline firing back-to-back), composing with unbounded Whole-brain reads + a distinct unbounded wire conn + the NetHost 10s send into the observed tails. 4361 stream-sub-attach records per brain generation. Per-stream, not broker-wide (unrelated conns progressed mid-poison). - **Invariant:** subscriber I/O never holds the `StreamLog` mutex (enqueue-under-lock, I/O outside, bounded per-subscriber queue; overflow = detach + resume-from-cursor); replay and fan-out halt at the FIRST failed subscriber write and the failed subscriber is REMOVED (attach + append + finish, all sites, `PresenceLog` mirrors included); the ring-peek fallback fires ONLY on the explicit unsupported-verb/old-broker answer; a deadline-poisoned replay is circuit-broken (global backoff, no reinstall until the prior subscriber is fully gone — an upgrade of bounded retry, never a revert to burn-the-claim abandonment); attach/detach validate ownership/generation so a stale worker never detaches a replacement controller (covers the unfinished-stale steal shape that finished-row retirement cannot see). - **spt-core mapping:** `spt-daemon/src/nethost.rs` `StreamLog::attach`/`push`/`finish` + `PresenceLog` mirrors + serve/wire worker pairing; `spt-daemon/src/dispatch.rs` `first_line` fallback arm + claim retry/backoff + worker spawn; SharedSend bounded-write deadline (round-4, KH 7.7 kin). - **Source:** REDISPATCH-STALL W1 (hertz v0.34 field RCA 2026-07-16, doyle seam-verified same day; ADR-0038 Amendment 2026-07-16; `.claude/reports/2026-07-16-redispatch-stall/rca-summary.md`; distinct from `update --restart`'s bounded 30s rc reconnect loop). ### 7.44 Streams and seats on a long-lived connection must have bounded lifetime — one-way rows terminal at FIN, seats released at serve completion, no per-chunk full-state rewrites in a drain loop `[REQ-HAZARD-REGISTRY-STALL]` - **Failure (paid-for, hertz post-close v0.36 field RCA 2026-07-17 — live prod box):** FOUR compounding consequences of "physical teardown waits for conn close" on connections that never close. The registry pump opens one fresh stream per feed (~30s) on the persistent pump conn; nothing retires the rows (the dispatcher — sole `retire_stream` caller — skips `initiated_locally`) → sender history unbounded. `stream_infos` filters `retired` only → every dispatcher poll serializes O(history) rows over IPC. `serve_registry_feed` ran `write_snapshots` (full rewrite of every subnet registry + heard.meta) up to TWICE PER 64KiB CHUNK, synchronously in the brain's event loop → brain stops draining IPC → broker seat writer blocks → 15s SharedSend bound → CONN_WRITE_POISONED (12→15 observed, family=Registry, fresh carrier each) → replay from seq 0 repeats the amplification. And seats retain FAMILY-AGNOSTICALLY: the conn loop accretes `my_stream_subs`, releases only at conn-loop exit, NO unsubscribe verb existed → ~546 of 589 broker threads were unnamed parked SubscriberSeat writers on completed Registry/sync/update seats. Independently: the brain re-hashed its 30.64 MiB exe every 500ms heartbeat (`write_ready` → `current_exe_hash`, a dropped W4 rider) = 15.5%/core + a breadcrumb that lies post-swap (path-read ≠ resident bytes). - **Invariant:** a one-way (fire-and-forget) family's row is TERMINAL at successful FIN — the sender retires it; eligibility filtering happens server-side before IPC serialization; feed application is transactional per feed (snapshot writes O(feeds), never O(chunks × record-kinds) — no synchronous full-state rewrite inside a per-chunk drain iteration); a deadline-poisoned one-way replay retires terminal at a per-stream strike budget (safe: the next pump round re-advertises); every completed serve releases its SubscriberSeat (unsubscribe verb — thread joined, cursor dropped), all families; the exe self-hash is captured once per brain process (that IS the resident-bytes truthfulness contract). - **spt-core mapping:** `spt-daemon/src/pump/mod.rs` `push_feed` (sender retire); `spt-daemon/src/nethost.rs` `stream_infos` (server filter) + SubscriberSeat teardown + thread naming; `spt-daemon/src/dispatch.rs` `serve_registry_feed` (transactional apply) + worker completion unsubscribe + strike budget; `spt-daemon/src/registryhost.rs` `write_snapshots` call sites; `spt-daemon/src/brainproc.rs` `write_ready`/`current_exe_hash`. - **Source:** REGISTRY-LIFECYCLE W1 (hertz RCA `.claude/reports/2026-07-17-registry-stall-rca/README.md`, doyle-verified all legs 2026-07-17; ADR-0040; supersedes the v0.36 clean-window general-health ruling — the Attach-family fix stands, the class recurred for Registry). ### 7.45 Endpoint lifecycle state converges to truth from every death path — no optimistic online without authority, no surviving control stamps, no immortal wake intent, no untruthful create `[REQ-HAZARD-ENDPOINT-LIFECYCLE]` - **Failure (paid-for, three hertz reports + operator field 2026-07-16):** four families, one root shape — lifecycle state written by multiple non-converging paths, optimistic stamps never verified. (a) `cmd_listen` stamped `status=online` from manifest capability alone → dead-PID hybrid rows survived EVERY restart (reconcile skipped them by state, cleanup gated on `controllable=true`, readers trusted `status=online` past dead-PID rejection). (b) Definitive session death stamped `status=offline` only, never `rest_state` → preserved `Active` intent = outstanding wake order → zombie WAKE_RESUME loops across generations (perri field). (c) `KIND_SESSIONS` poll snapshot raced the exit-waiter reap → stale poll relatched `controlled=true` on a dead session. (d) `--create` silently discarded; broker deduped every labeled SpawnReq into `Spawned(existing)` with no disposition → CLI printed success for a spawn that never happened; dup-guard and shutdown state machine consulted DIFFERENT liveness sources and contradicted on the same zombie (ALREADY_LIVE / OFFLINE / NO_EDGE three-way). - **Invariant:** online is stamped only from persisted state + hosting authority; legacy rows self-heal after a SUCCESSFUL broker query (broker failure ≠ empty set); control-stamp cleanup runs for every endpoint absent from session truth regardless of state/controllability, split from offline classification; definitive death = ONE atomic store mutation (offline + rest_state=suspended + clear dormant_since_ms, same info.json write) — never a rest-event edge, never reader-side inference; stamp writes are session/generation-validated so a pre-reap snapshot can't overwrite post-reap truth; fresh-create is a broker-atomic policy with a TYPED conflict (distinct wire kind, loud on N-1), never `Spawned(existing)`; cycle verbs share one liveness authority. - **spt-core mapping:** `spt/src/api/startup.rs` `cmd_listen` creator gate; `spt-daemon/src/livehost.rs` reconcile split + decide_resume; `spt-daemon/src/lifecycle.rs` `mark_offline` → terminal-normalize; `spt/src/cli.rs` `cmd_stop`/create dispatch; `spt-daemon/src/broker.rs` SpawnReq policy split + KIND_SPAWN_FRESH + dup-guard probe; KH 7.12/7.27/7.29 kin. - **Source:** REGISTRY-LIFECYCLE W2/W3 (hertz emphasys triple + rest-normalize + spawn-fresh reports 2026-07-16, doyle seam-verified same day; ADR-0041; operator deployah-wedge field evidence). ### 7.46 An rc surface answers from live session authority, never a stale persisted projection — and a resuming perch is UNBOUND, not offline `[REQ-HAZARD-RC-ATTACH-TRUTH]` - **Failure (paid-for, hertz perri contradiction RCA 2026-07-17/18 + operator field recovery):** the broker hosted an honest live session (client tree alive, `SessionProbe::has_live_session_honest` = true) while the persisted perch row said `offline` — the resumed harness sat wedged at a failed native resume, SessionStart never fired, the perch never bound, inbound messages black-holed. `spt rc` trusted the offline row and refused pre-IPC while `endpoint run --resume` reattached to the very same session (authority split, decisive A/B). The offline fast-fail's own doc-comment invariant ("`offline` never co-occurs with a live session") was falsified in the field; the "resume gets no UNBOUND stamp — accepted" boundary note assumed the pre-bind window is transient when it can be permanent. Separately: rc mapped a harness-only refusal to stale-row guess copy, and leaked the user's qualified target string onto the wire as the endpoint id (false refusal after a correct dial). - **Invariant:** every rc-family reader consults the single honest-session authority (ADR-0041 `SessionProbe`) before any persisted-status fast-fail — honest session ⇒ attach; no session ⇒ refuse; dead client tree ⇒ refuse/reap, never attach. UNBOUND = broker session exists + harness not bound, fresh/resume-invariant: resume stamps an existing offline perch UNBOUND (generation-safe rollback on spawn-fail/session death), bind owns UNBOUND→ONLINE. Refusal copy states known facts (harness-hosted ≠ stale row). The wire always carries the canonical bare endpoint id. - **spt-core mapping:** `spt/src/rc.rs` `run_attach` offline fast-fail + `establish_attach` target carry; `spt/src/rc.rs` `SessionProbe`; the resume-launch spawn path (UNBOUND stamp + rollback); `spt/src/cli.rs` `cmd_endpoint_run` reattach arm (the already-correct reader, parity source). - **Source:** RC-RENDER-TRUTH W1 (hertz RCAs 2026-07-16..18, doyle seam-verified; ADR-0042; organic pre-edit evidence preserved at hertz's `perri-info.pre-unbound-manual.json`). ### 7.47 The physical terminal is never mutated or terminated outside its renderer's ordered state model — output before exit, owned baselines, unconditional teardown `[REQ-HAZARD-RENDER-LIFECYCLE]` - **Failure (paid-for, hertz stale-glyphs RCA 2026-07-18, all legs doyle seam-verified):** four render-lifecycle defects presenting as "missing whitespace"/stale glyphs. (a) The broker exit waiter direct-writes `KIND_EXIT` via `all_sinks()` while PTY output queues through `controller_writer` — the per-conn gate serializes bytes but not producer order, so Exit overtakes the child's final erase/SGR-reset/`?1049l` and rc returns immediately (the broker test suite already documented Exit-before-Output and compensated by draining; production rc did not). (b) `RawGuard::drop` restores raw mode/mouse/console mode but no VT display state — every exit path can leave alt-screen/cursor/SGR/scroll-region dirty. (c) The picker ran purge inline under the live ratatui alternate screen while the purge core wrote stderr — mutating the physical screen behind ratatui's previous-Buffer diff baseline, so later draws skip "already blank" cells and stderr fragments persist. (d) `render_repaint` omitted tracked DECSTBM margins, so client and server grids scrolled against different regions after a cold repaint. - **Invariant:** one FIFO sequencer per attach sink — Exit is enqueued behind all prior Output (drain completion first); rc display teardown is a separate RAII guard from input teardown, unconditional and idempotent on every exit path including unwind (SGR reset, scroll-region reset, cursor show, leave alt screen, clear+home — while VT processing is enabled, before mode restore, before prose); a TUI surface has exactly one renderer — core verbs invoked from a live TUI return structured outcomes and write nothing to the terminal; cold repaint replays every tracked render-affecting mode (DECSTBM minimum). Blanks are real cells; a baseline is invalidated by any out-of-band mutation, reconnect, or resize. - **spt-core mapping:** `spt-daemon/src/broker.rs` exit waiter + `controller_writer`; `spt/src/rc.rs` `RawGuard` (split guard) + reconnect give-up path; `spt/src/picker/mod.rs` purge arm + `spt/src/cli.rs` `cmd_endpoint_purge` output; `spt-term/src/screen.rs` `render_repaint` + DECSTBM tracking. - **Source:** RC-RENDER-TRUTH W3 (hertz RCA 2026-07-18; ADR-0043; herdr v0.7.4 surveyed as prior art, ideas only — AGPL). ### 7.48 At most one input-capable controller lease per PTY session — takeover revokes atomically and loudly, input is fenced to the active lease, node identity is never a lease `[REQ-HAZARD-CONTROLLER-LEASE]` - **Failure (paid-for, hertz same-machine `--take` RCA, field repro 2026-07-16):** terminal A controlled an endpoint; terminal B on the SAME machine ran `spt rc --take`. Local loopback attaches carry only NODE identity, so `resolve_subscribe` computed `same_identity=true` and took the silent successor path for a distinct `--take` — intent never consulted; sink replaced with no `Displaced`, no stream close (the only loud branch is different-remote+Take). `dispatch_input` is session-addressed with no controller validation, so A kept typing into the PTY while B exclusively received output — a split-brain: input-capable-but-blind incumbent, rendering-but-shared-control taker. `brain.rs` had already documented the `None==None` shape of the defect. - **Invariant:** each rc invocation/attach mints a unique controller LEASE id carried through subscribe, the controller slot, and Input/Resize; the only silent successor is same-lease + equal-or-newer generation (dispatcher recovery, ADR-0038 fix-6 preserved); explicit Take on a DISTINCT lease always revokes ATOMICALLY and authoritatively (old lease fenced + old attach stream FORCE-closed; the Displaced notice via the old writer is best-effort — a Full-queue notice drop must never leave the incumbent installed or interactive) regardless of node match; the broker fences Input/Resize to the active lease — stale-lease commands are dropped after replacement (the invariant holds even if notification is lost); node identity = attribution/access only, never a lease. N-1: lease field additive, absent lease degrades to connection-identity fencing. - **spt-core mapping:** `spt-daemon/src/broker.rs` `OutputLog::resolve_subscribe` (same-identity branch) + `become_controller` slot + `dispatch_input` fence; `spt-daemon/src/brain.rs` documented `None==None` note; `spt/src/rc.rs` loopback attach origin + `PumpEnd::Displaced` (client side already correct). - **Source:** RC-RENDER-TRUTH W2 (hertz RCA filed 2026-07-18, doyle seam-verified same day; ADR-0044). ### 7.49 A teardown verb never stamps a terminal or resting state it has not caused — and two individually-correct verbs must not compose into a lifecycle dead end `[REQ-HAZARD-TEARDOWN-DEADEND]` - **Failure (paid-for, two hertz field RCAs 2026-07-19, both doyle code-verified the same day; the second hit doyle's OWN live production endpoint):** `endpoint shutdown` reported `Active -> Suspended` and `endpoint stop` reported `STOPPED` while the broker session, its harness child, and a descendant `spt api listen` all kept running — the verbs only removed the ready marker, ran the Suspend rest edge / unregistered the address, and stamped the record. Three consequences, all observed: (a) the whole subtree was orphaned, and because the survivor was a GRANDCHILD of the PTY child, even a direct-child kill would have missed it; (b) the stamp was not durable — post-stop `info.json` read `status=offline` beside `rest_state=active` + `controlled=true`, because the surviving host RE-BOUND over the CAS-less `terminal_normalize(path, None)`; (c) it composed with `endpoint run`'s CORRECT `ENDPOINT_CREATE_CONFLICT` refusal (the deliberate no-silent-reattach rule) into a lifecycle DEAD END — the survivor was simultaneously what `stop` claimed to have killed and what `run` refused to work around, so with a wedged harness every in-band verb was exhausted (stop lies, run refuses, `rc` replays a dead PTY, `rc --take` controls a process that never answers) and exit required out-of-band `taskkill`. NEITHER behavior was individually wrong; the COMPOSITION was the hazard. - **Invariant:** a teardown verb never stamps a terminal or resting state it has not caused. Where the session is broker-hosted (`controllable == Some(true)` — the ONE hosting authority, ADR-0041), "stopped" and "suspended" both mean the broker session row is GONE and its whole DESCENDANT subtree is reaped, via one shared primitive behind both verbs: resolve → dedicated sid/endpoint-keyed kill claiming NO controller (never `attach` + `kill_session`, which is a controller theft with a lease-generation bump behind it) → descendant tree-kill → bounded await of row removal → only THEN stamp + unregister + advertise. The kill never depends on harness cooperation — a wedged host is the design case. On an unconfirmed reap: exit non-zero, stamp NOTHING (a cold row over a live process is the worse lie), and name the surviving root pid plus the scoped-kill remedy, because `stop` is the last rung with no in-band escalation behind it. Where core holds no process (harness-hosted / external) a teardown verb claims nothing about processes. Regression must assert the COMPOSITION: after a `stop`, `endpoint run --id ` SUCCEEDS and never answers `ENDPOINT_CREATE_CONFLICT`. **The refusal is gated on a LIVE process, never on row presence alone** — "the row is still there" is only a proxy for "a host survived". A lingering row whose root pid is provably gone is the ZOMBIE row (`zombie_verdict`'s primary class: a dead root with a surviving record), it can never clear itself because the exit waiter already failed to remove it, and refusing it would strand the record in band while naming a remedy against a pid that no longer exists — the same dead end on a different class of row. **A stamp requires POSITIVE proof the root is gone; no snapshot is not proof** — absence of evidence read as proof of death is the same error class one layer down, so an unavailable or empty process oracle must never authorize a stamp (the illustration: `process_table` yields empty where the platform has no snapshot). Prove that liveness from the OS process table, never from `is_process_alive` — on Windows the latter probes `OpenProcess`, which keeps succeeding for a terminated process while a parent holds its handle, and the broker always holds one for a PTY child (filed separately as a backlog audit). A stale row is stamped LOUDLY, never silently as a clean reap: two stamps that reached the same end state by different truths are not the same event, and collapsing them makes this bug undiagnosable in the field next time. **And a named survivor propagates:** `purge --force` refuses rather than wiping records out from under a live subtree, because the records are the only in-band handle left to it; the ordinary slow-to-quiesce case keeps its clean-anyway posture, since that is not a named survivor. - **spt-core mapping:** `spt/src/teardown.rs` (the shared primitive + topology gate + timeout copy); `spt/src/cli.rs` `cmd_shutdown` / `cmd_stop`; `spt-daemon/src/broker.rs` `dispatch_teardown` (over `spt_store::proc::kill_pid_tree`); `spt-daemon/src/brain.rs` `teardown_session`; `spt-daemon/src/livehost.rs` `reconcile_hosted_liveness` stays the partial-failure catch-up net. Precedent one scope up: `REQ-HAZARD-DAEMON-STOP-REAP`. - **Source:** TEARDOWN-AUTHORITY W1 (ADR-0045; hertz RCAs 2026-07-19). ### 7.50 The liveness oracle answers from the process table, never from a handle a caller still holds `[REQ-LIVENESS-ORACLE-SOUND]` - **Failure (paid-for, found by todlando during TEARDOWN-AUTHORITY W1 gate round 0, 2026-07-19; latent in `session_is_zombie` since the cycle verbs were built):** `spt_store::proc::is_process_alive` probes `OpenProcess` on Windows, which keeps SUCCEEDING for a TERMINATED process while any parent still holds an open handle to it — and the broker holds `Arc`, hence such a handle, for every PTY child it spawned. So a correctly-reaped harness reads ALIVE. `broker.rs::session_is_zombie` feeds exactly that call into `zombie_verdict`'s `wrapper_alive`, which flips the verdict off its PRIMARY class (`Some(false)` — "dead root, surviving record — always a zombie") onto the conditional arm, where classification then additionally requires `adapter_labeled && past_grace && !has_live_descendants`. **Consequence: a dead-root session that is not adapter-labeled is claimed LIVE indefinitely** — `endpoint run`'s dup-guard refuses `ENDPOINT_ALREADY_LIVE` over a tree that is already dead, and `cmd_rest`'s Suspend `alive_hint` forces `from=alive` on the same false claim (both via `has_live_session_honest`). `REQ-ENDPOINT-CYCLE-HONEST` exists to give the cycle verbs ONE liveness authority; after W1 there were TWO, disagreeing by construction. - **Invariant:** **`is_process_alive` is unsound exactly when the ASKER — or a live ancestor of it — still holds an open HANDLE to the target.** That is the only condition under which `OpenProcess` outlives termination; dropping a `Child` closes the handle, so a spawner that DROPS is honest and a spawner that RETAINS is not. Therefore the dangerous shape is asking **"is it GONE" about a process you OWN**, and **the same call is sound in the CLI and unsound in the daemon for the very same pid** — soundness is a property of the ASKER, not of the call. "Does this pid still exist" is answered from the OS process table, which lists only processes that still exist, so absence from a NON-EMPTY snapshot is proof of death. An EMPTY table is **NO KNOWLEDGE, never proof** (`process_table()` yields empty where the platform has no snapshot): it must resolve to "unproven" — at the zombie site, to `None`, which already means "never guess" — and must NEVER manufacture `Some(false)`, which would mass-classify every live session a zombie. `zombie_verdict` stays PURE and unchanged: it was fed a lie, it is not wrong. Audit call sites with the discriminator rather than mass-migrating; the sound probe is a NAMED SIBLING whose name is the question (`process_exists`), and `is_process_alive`'s doc names the question it does NOT answer. - **Second instance — the table's OTHER half (paid-for, found by doyle at the RESIDENT-SERVICE W1 PR gate, Linux leg, 2026-07-26):** absence from a non-empty snapshot is proof of death, but **PRESENCE in it is proof of LIFE on Windows only.** On unix a killed-but-unreaped child of a still-running spawner (in-process daemon hosting, tests) stays in `/proc` in `Z` state with a readable `stat`, so `process_table` keeps it and `process_exists` answers `Some(true)` for a process that runs nothing. `provably_gone`'s present arm returned `!exists` unconditionally, so table-presence beat the `Z`-state demotion `is_process_alive` already performs: a completed force-kill polled `awaits_death` to its full deadline and reported `OrphanSweep::KillFailed`, and a tree-teardown assertion read its own direct child as a survivor. Windows was structurally green (Toolhelp snapshots exclude terminated processes; no zombie concept) — a Windows-only gate would have shipped it. **Invariant:** the present arm asks `is_process_alive` on unix (`kill(pid, 0)` + the `/proc` `Z` read — both handle-independent, so this does NOT reopen the `OpenProcess` hazard above, which is Windows-only) and answers "alive" from the table alone on Windows. A zombie is GONE to every consumer of "is a process I own gone?". - **spt-core mapping:** `spt-store/src/proc.rs` (`is_process_alive` caveat + `process_exists` sibling over `process_table` + `provably_gone`'s per-platform present arm); `spt-daemon/src/servicehost.rs` `awaits_death` / `kill_orphan_service_at`; `spt-daemon/src/broker.rs` `session_is_zombie` (`wrapper_alive`) with `zombie_verdict` unchanged; consumers `spt/src/rc.rs` `has_live_session_honest`, `spt/src/cli.rs` `endpoint run` dup-guard + `cmd_rest` Suspend `alive_hint`; `spt/src/teardown.rs` `root_provably_gone` (handle-half correct since W1, zombie-half fixed 2026-07-26 — the mapping vouches only for what was audited). Precedent one scope down: `REQ-HAZARD-TEARDOWN-DEADEND` (row-presence-as-proxy). - **Source:** TEARDOWN-AUTHORITY W2 (ADR-0045 Amendment 1; todlando W1 gate finding 2026-07-19). Knowledge note: this Windows behavior was documented VERBATIM in `spt-daemon/tests/legacy_resident_sweep_e2e.rs` (which drops handles deliberately to get an honest probe) and never reached `proc.rs` or `zombie_verdict` — written where DISCOVERED, not where CONSUMED. ### 7.51 Process custody is an identity, never a bare PID — a recycled pid must read NOT OURS `[REQ-HAZARD-RESUME-CUSTODY-ABA]` - **Failure (paid-for, hertz v0.39.4 field RCA 2026-07-22, doyle code-verified same day):** `resume.pid` custody is a bare PID consumed as `read_resume_pid(..).is_some_and(is_process_alive)` at BOTH the livehost restart gate and the liveness-reconcile DEFER. A dead wake-resume spawn's pid, recycled by the OS onto an unrelated process (field proof: `resume.pid=29456` resolved to a random `cmd.exe`), reads as "a resume is in flight" indefinitely: reconcile defers every tick, the row stays online-authoritative, and the endpoint is FALSE-ONLINE with no self-repair — every reader faithfully resurrects the lie. The ABA problem, in process custody. - **Invariant:** a custody record that gates lifecycle decisions stores an **identity pair (pid + process creation time)**, written atomically at spawn-mint; consumers test the PAIR, and a mismatch means NOT OURS — the discovering reader DELETES the record and proceeds as if no custody existed (self-heal, not error). Bind and reap clear custody atomically with their own outcome. Creation time comes from the process snapshot, never a retained handle (7.50); no snapshot ⇒ "unproven" ⇒ defer ONE tick, never a manufactured verdict. - **spt-core mapping:** `spt-daemon/src/livehost.rs` (restart gate + reconcile DEFER custody reads); `spt-store` resume-custody record + `proc.rs` snapshot identity; regression = the recycled-pid rig (custody pair mismatching a live impostor pid → record deleted, reconcile proceeds, row goes honest). - **Source:** DAEMON-LIFECYCLE W1 (ADR-0047 decision 1; hertz field RCA bug 1). ### 7.52 An operator stop outranks every implicit ensure — no convenience path resurrects what the operator just killed `[REQ-HAZARD-STOP-RESPAWN-CONVOY]` - **Failure (paid-for, hertz v0.39.4 field RCA 2026-07-22, doyle code-verified same day):** `spt daemon stop --force` is non-terminal on a box hosting live adapter sessions: every `spt api` invocation runs an unconditional `ensure_daemon()` (REQ-DAEMON-3's anchor), hook-driven api calls arrive continuously, so the stop is a race the operator loses — 5–10 ephemeral spawner windows flash and the daemon is back; several force-stops to stay down. The rc-side twins were fixed earlier (rc.rs); the api anchor stayed armed. Two defects compose: resurrect-after-stop, and N racing spawners with no serialization. - **Invariant:** `daemon stop` records a durable machine-scoped **stop inhibit** BEFORE teardown begins; every implicit autostart path consults it and DECLINES with one honest line naming the remedy (`spt daemon start`). Cleared by intent verbs only (explicit start; update paths that restart by design) — **no TTL** (a timeout is the surprise respawn again, later). Implicit autostart additionally takes a machine-wide lock around probe-and-spawn so concurrent callers can never launch competing daemons. Regression must assert the COMPOSITION: stop under a live api-call storm → daemon stays down, zero respawns, callers print the refusal; explicit start clears; concurrent-ensure race spawns exactly one daemon post-clear. - **spt-core mapping:** `spt/src/api/mod.rs` `ensure_daemon` + `spt-daemon` `ensure_running` (the two implicit anchors); `spt/src/cli.rs` `cmd_stop` (inhibit mint) + `daemon start` (clear); machine-lock alongside the existing daemon single-instance machinery. Kin: `REQ-HAZARD-DAEMON-STOP-REAP` (stop reaps its tree — this hazard keeps the tree DOWN afterwards). - **Source:** DAEMON-LIFECYCLE W1 (ADR-0047 decision 2; hertz field RCA bug 2). ### 7.53 A durable copy of revocable content is validated against its source of truth at DELIVERY time — a spooled notice outliving its row must not deliver `[REQ-NOTIF-DRAIN-ROW-VALIDITY]` - **Failure (paid-for, operator field report from perri's node 2026-07-22 — the day after the v0.40.0 notif redesign shipped; doyle root-caused same day, own session corroborating with stale v0.39.x drains):** a node already ON v0.40.0 received the v0.40.0 "update available" notice twice. ADR-0046's quiet delivery makes every notif surface an `active_only` SPOOL write per endpoint; every lifecycle mechanism (apply-seam dismissal, coalesce supersession, TTL, migration) operates on notif-store ROWS only. A copy spooled while the endpoint was busy/offline — the normal state of a working agent — is a detached snapshot no dismissal can recall; it delivers at the endpoint's next drain, after the fact it advertises has been resolved, once per qualifying surface event. The row-layer claim "notices self-clear" was true; the delivery layer the operator sees lied. - **Invariant:** content that is REVOCABLE at its source (a dismissible notif row) is re-validated against that source at the moment of DELIVERY, not only at the moment of surfacing. The safe-point drain delivers a notify envelope only if its `notif_id` resolves to a live undismissed row; dismissed/superseded/expired/unknown copies drop silently, and N spooled copies of one notif dedupe to one delivery. Ordinary (non-revocable) messages are exempt and MUST deliver. Recall-on-dismiss sweeps are the rejected shape (race the drain, span every perch, miss copies in flight) — validity lives at the choke point every copy must pass, not at N producers. - **spt-core mapping:** `spt/src/api/delivery.rs` `cmd_poll` deferred presentation (the one drain choke point); notify envelope attrs (`from`/`notif_id`/`subnet`, notif.rs `notify_envelope`); `spt-store/src/notif.rs` row-liveness read. Kin: 7.49/7.50 (a stamp/verdict needs positive proof at the moment it is asserted — same principle, delivery-shaped). - **Source:** DAEMON-LIFECYCLE W1 rider (ADR-0046 Amendment 1; operator field report 2026-07-22). ### 7.54 A geometry change invalidates the client's painted cells by itself — every resize entry emits the authoritative repaint, and an attach's old-geometry repaint is never the final word `[REQ-ATTACH-RESIZE-REPAINT]` - **Failure (paid-for THREE TIMES — v0.39.3 geometry-epoch, v0.39.4 presentation barrier, and still red in the field; pinned by hertz's ENLYZEAM production byte capture 2026-07-22, doyle seam-verified same day):** the codebase has TWO resize entries. The IPC `ResizeReq` path is sound post-0.39.4 (arm barrier → settle → issue → commit pushes the authoritative repaint at the landed geometry). But rc's INITIAL viewport resize rides the attach-stream verb (`send_attach_resize`, once per establish) which never arms the barrier — the no-transition branch of `commit_resize` resizes the grid and pushes NOTHING, on the claim "no suppression, so no sync frame owed". So a controller attach to a session hosted at different geometry (80x24 hosted, 131x60 client — no window resize anywhere, which is why the operator's "not resize-related" was true as observed and the seam hid for three iterations) paints the OLD-geometry synthesized repaint, lands the new geometry silently, and every subsequent differential assumes the reflowed model against a client screen still holding pre-resize cells — keystroke-paint `/c` scraps and SGR misalignment. Proof both directions: independent-emulator replay WITH the stale repaint reproduces; from the first post-resize full frame is clean; fresh viewer clean; transport byte-identical (A/B taps). - **Invariant:** a geometry change invalidates every attached sink's painted cells BY ITSELF — bytes-in-flight or none. Geometry change is ONE transaction with ONE exit shape regardless of entry point: resize → grid lands → authoritative full repaint at the new geometry to every attached sink → only then subsequent output. Any resize entry (IPC, attach-stream, future) rides the SAME barrier machinery; a "no repaint owed" branch survives only for genuinely sink-less sessions. At attach specifically: when viewport geometry differs from hosted geometry, the initial resize's committed repaint supersedes the attach's synthesized old-geometry repaint — the old-geometry paint is never the client's final word. ORACLE: regression replays the captured shape (content-bearing 80x24 hosted → 131x60 controller attach → menu/keystroke differentials) into an INDEPENDENT VT emulator and asserts final cells/colors — a ScreenGrid-only oracle shares the model under test and misses this class by construction (the REQ-SCREENGRID-WIDTH precedent). - **spt-core mapping:** `spt-daemon/src/broker.rs` `commit_resize` no-transition branch + the attach-stream resize handler (`send_attach_resize` server side) vs the barriered `ResizeReq` dispatch; `spt/src/rc.rs` initial `send_attach_resize` at establish; kin REQ-RC-RESIZE-GEOMETRY-EPOCH / REQ-RC-RESIZE-PRESENTATION-BARRIER (the machinery exists — this hazard is the second entry that must ride it). - **Source:** DAEMON-LIFECYCLE W3 (ADR-0047 Amendment 1; hertz ENLYZEAM byte-capture RCA 2026-07-22, v0.39.4 field bug 3). ### 7.55 A surface resize never alters the hosted terminal's input discipline — input bytes must never come back as output `[REQ-RESIZE-INPUT-MODE-INTEGRITY]` - **Failure (paid-for, second ENLYZEAM production capture 2026-07-22 — operator resized a LIVE established rc viewport; hertz froze the taps):** after the resize, the raw ConPTY drain emits the operator's keystrokes as isolated OUTPUT records — literal one-byte `c`/`o`/`n`/`f`/`i` frames interleaved with the TUI's cursor-addressed menu diffs, raw and broker taps byte-identical. The hosted Claude TUI runs raw/no-echo, so the hosted console echoed input that nothing asked it to echo. That evidence is REAL and is SERVER-SIDE: it sits in the child→broker drain, upstream of any client console, so it is independent of the 7.56 presentation defect that explains the `/c/config` line's other half. Non-spt sessions bypass the nested ConPTY path, which is why the operator only ever saw it spt-hosted. spt-core touches console input modes NOWHERE in-tree (zero `ENABLE_*` handling). - **MEASURED 2026-07-22 (todlando, doyle-ratified), and it changes the shape of this hazard:** the resize seam does NOT alter the input mode. A probe child under a real ConPTY, clamped raw at startup, resized 24x80→60x131 live, reports an IDENTICAL input mode word at four sample points — `boot` / `before-resize` / `after-resize` / `before-write`, all `in=0x000001f0 echo=0 line=0` — and typed bytes do not come back as output. A seeded capability probe (cooked input deliberately re-enabled mid-run) moves BOTH observables, so the absence is earned rather than vacuous. ADR-0047 Amendment 1's addendum supposed "something across the resize path re-enables console echo"; on this box and this `portable_pty`/ConPTY version, that is NOT what happens. Trigger UNPINNED. - **The open candidate (field question with hertz, NOT built against):** the pseudoconsole BOOTS with `ENABLE_ECHO_INPUT`/`ENABLE_LINE_INPUT` ON (`in=0x000001f7` measured) and it is the CHILD that clamps them off. Any window in which the hosted TUI has not yet clamped — startup, or a re-clamp after a TUI-internal state transition — is a window in which the console echoes BY DEFAULT, with no seam having "re-enabled" anything. That reframes the question from *who turns echo back on* to *is there a window where nobody has turned it off yet*. It is a candidate, not a root — but it is now FIELD-GROUNDED (hertz via doyle, same day): in capture 2 the echo onset is **6003 ms after** the first resize-associated repaint burst and lands immediately after a 3225-byte TUI-reinit-shaped absolute repaint, then ceases mid-input (`c`/`o`/`n`/`f`/`i`, no `g`) right after a 535-byte diff — a late clamp landing, invisible to a byte tap, and NOT resize-instant. Carried forward as seed `REQ-TERM-ECHO-CLAMP-WINDOW` (minted inactive); note that spt may not be able to mitigate it at all, since the daemon cannot touch the child console's modes, so the honest outcome may be an upstream finding. - **Invariant:** input bytes must never come back as output — that stands, and it is the observable any regression asserts, because it survives being wrong about the mechanism. Two structural facts constrain every fix and every rig for this class: (1) **the daemon cannot observe or set the hosted child's console modes at all** — those handles belong to the pseudoconsole the child is attached to, and the daemon holds only the master end, so "instrument the mode at the `spt-term` resize seam" names a probe point that physically cannot see the console in question, and a server-side clamp is equally impossible; the only vantage point is a process attached to that console; (2) consequently the RIG is the instrument, and no production instrumentation ships for this hazard (measuring the wrong console is manufactured confidence) — if the field ever needs live diagnosis, the probe-child pattern ships as a debug tool then. - **spt-core mapping:** no production code owed today. Instrument = `adapters/mock/src/console_mode_probe.rs` (probe child; verdict travels in the stdout PROTOCOL LINE, never stderr — under a ConPTY the child's stderr is interleaved into the same re-rendered stream and arrives shredded, so a refused `SetConsoleMode` could otherwise read as a measurement). Rig = `crates/spt-term/tests/resize_console_mode_integrity.rs` (the four-sample measurement, the typed-bytes-do-not-echo symptom leg, and the seeded capability probe). Rig-craft pinned there and transferable: a probe that never clamps raw is already sitting at the default the seam is suspected of restoring and cannot distinguish "reset" from "never changed"; and ConPTY's post-resize REPAINT re-emits earlier output, which impersonates a fresh reply to any rig that matches loosely. - **Source:** DAEMON-LIFECYCLE W3 (ADR-0047 Amendment 1 addendum; hertz second production capture 2026-07-22; measurement + rescope todlando 2026-07-22, doyle-ratified same day). ### 7.56 The rc client presents relayed bytes exactly as the emitter addressed them — console output modes are part of presentation truth `[REQ-RC-NEWLINE-PRESENTATION-TRUTH]` - **Failure (paid-for — v0.39.4 field bug 3, the `/c/config` scraps, pinned 2026-07-22 via the W3 bisect):** rc's Windows viewport enables VT output as `prior | ENABLE_VIRTUAL_TERMINAL_PROCESSING | ENABLE_PROCESSED_OUTPUT` (`rc.rs` `with_vt_output`) and `DISABLE_NEWLINE_AUTO_RETURN` appears NOWHERE in the tree — so with processed output on, the operator's console translates every relayed bare LF into CR+LF. A hosted TUI that emits bare LF as a plain index at a non-zero column (capture record t=1784714152501: `CUP 51;3` + `EL` + SGR + `0x0a` + `"/cd…"`) is presented with a column reset the emitter never asked for; later absolutely-addressed writes never erase cols 1-2, so the `/c` residue survives to the final screen. The relay is BYTE-CLEAN end to end — which is exactly why two independent isolated rigs read NOT-REPRODUCED (they compared bytes or rendered via spec VTs; nobody presented through a really-configured Windows console), why a fresh viewer read clean (the synthesized attach repaint is CUP-absolute, no bare LFs), and why the debris appears at a FIXED window size (no resize required). The W3 replay rig's "vehicle artifact" (a second ConPTY manufacturing the exact field string) was this same asymmetry — the rig was a faithful model of the CLIENT while being consulted about the broker. - **Invariant:** the rc presentation path configures the console so relayed bytes render as the emitter addressed them: whenever processed/VT output is enabled, `DISABLE_NEWLINE_AUTO_RETURN` is set with it (the Windows half of the symmetry Unix rc already has — raw mode clears OPOST/ONLCR); the prior mode is captured and restored on exit as today. A bare LF in the relayed stream is an INDEX (row down, column preserved), never a newline. Console-mode seam kin: 7.55 (input echo across resize) and the W3 vehicle finding — three manifestations of one uninstrumented seam in one day; any rig placing a non-spt vehicle (ConPTY or otherwise) between fixture and code-under-test must prove the vehicle transparent per cell before its verdict counts (the vehicle-fidelity clause), or declare itself a client-model rig in its header. - **spt-core mapping:** `spt/src/rc.rs` `with_vt_output`/`enable_vt_output`/`restore_out_mode`; regression = the W3 captured-bytes rig PAIR (vehicle console without DNAR = field client model, RED pre-fix; with DNAR = fixed client, GREEN) + the minimal LF probe (`ESC[2J ESC[5;3H "XX" LF "AB"` — column preserved vs reset) through an rc-mode console. - **Source:** DAEMON-LIFECYCLE W3 bisect (todlando three-probe isolation + doyle static grep + byte-verify, 2026-07-22); hertz ENLYZEAM captures (anchor + fresh-viewer-clean contrast). ### 7.57 Resolve a process-global once per operation and thread the value inward `[REQ-HAZARD-PROCESS-GLOBAL-ONE-RESOLUTION]` - **Latent failure:** a public operation resolves a process-global and then calls a callee that resolves it again. The two reads can disagree inside one operation. Two production instances existed unnoticed: `daemon_inhibit::set_stop_inhibit -> inhibit_path` and `servicehost::service_env -> env assembly`. Both were invisible until a test happened to be the victim; nobody was hunting the production forms. - **Invariant:** resolve the process-global exactly once at each public boundary and thread that value inward. An `_at(home)` helper is not proof if any inner callee can still read the global. - **Eventual gate:** count `spt_home()` occurrences and require exactly one per public boundary, inside the thin wrapper. The repaired files currently expose the intended count directly: `servicehost.rs` has one occurrence in its wrapper; `daemon_inhibit.rs` has five, one per public function. A shape-only test for a threaded parameter is insufficient because it can pass while a callee re-reads the global. - **Posture:** recorded as inactive `REQ-HAZARD-PROCESS-GLOBAL-ONE-RESOLUTION`; activate only with the milestone that adds the counting regression. No changelog entry: disagreement requires an in-process `SPT_HOME` mutation and is not user-observable in ordinary CLI use. ### 7.58 A pid breadcrumb is not kill authority — authenticate the live image before any kill `[REQ-HAZARD-TEST-PID-TREE-KILL-IDENTITY]` - **Failure (golden run `30501468421`, Windows job `90742055246`):** `worker_lifecycle_e2e` ran all child calls, then read `daemon.pid` and invoked `taskkill /PID /F /T` before its first assertion or observability point. A hard-killed harness cannot unwind, producing the observed bare exit 1 with no panic or assertion. More seriously, a stale or wrong recycled pid lets `/T` terminate an arbitrary foreign process tree on a shared runner. - **Invariant:** identity precedes termination. First distinguish a gone process from a live one: an already-exited pid is benign, logged, and skipped. For a live pid, re-resolve its executable path immediately before killing and require it to sit under the test job's own target directory. Refuse the current test process and every ancestor even when its path matches. **A live but unidentifiable process is never a legitimate kill target:** unreadable or denied identity fails closed, leaves the process alive, and fails the test loudly. A helper that collapses “gone” and “unreadable” is not adequate for a kill path. - **Measured breadth, predicates stated separately:** on the wider non-recursive root `crates/*/tests/*.rs`, 42 files contain `taskkill` plus the literal argument `"/T"` (the original `crates/spt/tests/*.rs` root accounts for 31). Of those 42, 30 also join a literal `*.pid` or `*.ready` breadcrumb filename: 26 reference `brain.ready`, 6 reference `daemon.pid`, with overlap; manual source tracing confirms breadcrumb-to-tree-kill flow in 23 and leaves 7 explicitly unconfirmed. An independent wider-root predicate reproduced exactly the original 6 `daemon.pid` tree-kill flows. A graded second tier adds 12 more files that manually pass `daemon.pid` to `taskkill /F` without `/T`: smaller blast radius, identical reused-pid identity violation. Excluded populations remain source unit modules, nested `tests/common/`, scripts, and any non-literal or differently named breadcrumb until separately enumerated. - **`brain.ready` inversion:** a live brain refreshes `brain.ready` every heartbeat, so **a stale `brain.ready` means the brain is already dead — and killing a dead pid is precisely when reuse bites.** A heartbeat-refreshed breadcrumb feels safer than a write-once one, but staleness correlates with the original target being gone; the dangerous reuse case is therefore the common stale-file case. - **Narrow repair posture:** the release-path repair instruments and path-authenticates only `worker_lifecycle_e2e`. The inactive requirement seed owns the separately reviewed fleet-wide audit; breadth is a finding, not permission for silent scope expansion. --- ## Conformance checklist (condensed) | # | Invariant | spt-core surface | |---|---|---| | 1.1 | Grace wait precedes INIT_SIGNOFF | daemon teardown | | 1.4/4.4 | Deferred rows excluded from event-stream drain | daemon spool drain | | 2.1/5.1 | Stable PID/broker-handle over ephemeral PID | liveness detection | | 2.3 | Handoff argv/IPC version-tolerant (newer brain ↔ older broker) | broker↔brain IPC, self-update | | 2.4 | gen_start = now() on cold-start + handoff | per-instance generation | | 2.6 | A shell's ONLINE-ness is DERIVED (recorded status AND a not-provably-dead `shell.pid`) — an abruptly-killed binary breaks no link, so `close_shell`'s offline flip never runs and the record lies forever; derive at the gates/renders, keep the recorded field at the writers, the suspend-cascade close, and the wake reconciler (no spontaneous relaunch — deploys and quarantine own that decision). Not only a crash edge: the GRACEFUL daemon-stop path kills bound shells at stop-begin with `close_shell` unrun (field 2026-07-25 — shells died abruptly, `info.json` still `online`, while the broker drained on 2m10s), so every daemon restart manufactures these stale records routinely; the derivation heals them at the gates | `spt_store::shellinfo::{shell_pid_provably_dead,effective_status,is_shell_online}`, `linkhost` relink/drive/cmd-wake, `shelldisc::discover`, `activity::observe_links` | | 3.1 | Ephemeral perch cleanup on all exit paths | `ring` (RAII guard) | | 3.4 | A ring never adopts (so never deletes) a perch it did not create — probe the DIR, not the ready marker; record/spool/unreadable = occupied, empty = refused too; deliver + loud `RING_PERCH_EXISTS`/`RING_STALE_DIR` instead of block-waiting | `spt_msg::ring` probe + `create_dir` leaf | | 3.3 | Echo-commune before INIT_SIGNOFF | daemon psyche loop | | 4.1 | Envelope decode order, `&` last | spt-proto (public, wire-versioned) | | 4.2 | Parser panic-free + tolerant | spt-proto | | 4.3 | Stale registry entries → fallback, never hard-fail | subnet registry resolution | | 4.10 | Silent-node registry rows evicted (heard-map TTL); own rows never decay | registry pump eviction | | 4.6 | Addressable-id charset reserves `:`/`@` delimiters | `spt_proto::id` at creation seams | | 5.2 | tmp-write + atomic-rename + retry (EBUSY) | all state writes, binary swap | | 5.3 | Timeout every harness subprocess | manifest invocations | | 5.4 | Strip UNC prefix on serialized paths | spt-proto path normalization | | 5.5 | ConPTY reader answers DSR (`ESC[6n`) | spt-term broker PTY reader | | 7.7 | A wedged viewer is evicted, never stalls the controller/child/drain | broker `OutputLog` fan-out (controller/viewer) | | 5.6 | Detached long-lived children inherit only ENUMERATED handles — `bInheritHandles=FALSE`, or TRUE solely beside a `PROC_THREAD_ATTRIBUTE_HANDLE_LIST` allowlist (never bare) | daemon + shell spawn + `[service]` startup capture | | 5.7 | Daemon always unelevated in the invoker's universe (de-elevated spawn + entry guard) | `deelevate` seam, `spawn_detached`, `Daemon::run` | | 5.8 | `CREATE_NO_WINDOW` on every console child of the console-less daemon | `gitrun::run_git`, `kill_shell_pid`, `run_bounded_command`, `shellwake` | | 5.17 | Spawn-based test rigs use `cmd`/`sh`, never `powershell` (silent no-op under `DETACHED_PROCESS`); descendants found by parentage via `proc::process_table()` | every rig over `daemon::detached_no_inherit*` | | 5.12 | Native-PTY spawn PATHEXT-resolves a bare program + wraps non-PE targets (.cmd/.bat→`cmd /c`, .ps1→powershell), bypassing portable-pty's shim-first `which` (CreateProcessW os error 193) | `spt_term::winprog` → `PtySession::spawn_program_in` | | 6.1 | Single path/registry source of truth | storage layout | | 6.4 | Drop files supervisor-owned single-writer | runtime contract | | 6.5 | Direct-write precedence marker (+ node id) | cross-node Psyche sync | | 6.6 | Surfaced conflicts preserve both versions until dominated | context conflict artifacts (ADR-0013) | | 6.7 | Broker + brain are separate processes (brain restart never drops a hosted endpoint at the process level) | daemon process topology, self-update (ADR-0018) | | 6.8 | No irreversible durable-state migration before update ready-promotion (pre-ready writes stay N-1-readable) | auto-rollback / durable-state schema (ADR-0018) | | 6.10 | Phase-significant loop timing is a durable absolute-deadline grid (no per-fire write; update preserves phase, crash resets, one-shot never resets) | durable loop timing / self-update (ADR-0018 Q4) | | 6.11 | Brain respawn execs the applied bytes (canonical exe captured at broker start, not per-spawn current_exe) + promotion bytes-gate (exe_hash == artifact, else rollback) | daemon respawn path / self-update (ADR-0018 Q3) | | 7.1 | Local `api` mutation authenticated to endpoint | api surface / broker IPC | | 7.2 | Idempotent delivery across brain restart | broker↔brain IPC | | 7.3 | Psyche outbound captured + `from=`/target stripped + reply-to-sender / notify-to-own-user | live-Psyche driver / daemon relay (ADR-0012) | | 7.4 | Per-agent pulse/psyche/echo runs off the shared scheduler (no serial blocking across agents) | daemon multi-agent hosting (ADR-0004) | | 7.5 | WAN-inbound origin = QUIC handshake identity from the broker's stream table, never payload bytes | wan receive funnel + every wire-inbound consumer (ADR-0009) | | 7.6 | Pump brain-IPC reads deadline-bounded (30s total-wait); TimedOut → supervised restart, never per-peer retry | `Brain::cold_start_pump` / `BrainConn::Split` (reader-thread + `recv_timeout`), `pump::peer_outcome` | | 7.8 | Broker bounds every brain-waiting QUIC op (10s < the brain's 30s); a dead peer fails as an ORDINARY error the broker replies → per-peer redial, round continues, no pump restart (the 7.6 B-half) | `NetHost::bounded_block_on` wrapping `dial`/`open_stream`/`send_stream` | | 7.9 | A daemon-state wire change (e.g. the v0.9.0 agnostic Seed) needs a deliberate broker restart — the resident old broker can't read new bytes; the seed-skew EOF surfaces an actionable `spt daemon stop` hint, not "failed to fill whole buffer"; forward: additive + serde-default daemon-state | `cmd_seed`/`seed_fail_message`, broker seed-control residency | | 7.10 | A view is independent from the endpoint: the cold-started daemon is launched JOB-NEUTRAL (WMI `Win32_Process.Create` PRIMARY → WmiPrvSE child, outside any terminal job from birth; breakaway DEMOTED to a fallback rung because a job CAN deny it). A WMI/scheduler child does NOT inherit transient shell env, so `SPT_*` (esp. `SPT_HOME`) is forwarded via a `cmd /c set … & start /b` wrapper. Ladder (first-success-wins, both cold-start + `spt daemon start`): WMI → schtasks → breakaway → in-job. int IS CI-testable via the WMI rung (no nesting false-red — WMI escapes regardless of job policy); operator WT/VSCode tab-close = final non-gating confirmation. `detached_no_inherit` unchanged for `launch_shell`; elevated `deelevate` keeps L1 breakaway (WMI-reparent = follow-up) | `daemon.rs::launch_daemon_job_neutral` (ladder), `spawn_daemon_via_wmi`/`wrapped_daemon_command`, int `job_escape_e2e.rs` | | 7.11 | A dead PTY child + a dropped operator pump does NOT wedge the broker — PROVE-DON'T-CHANGE: send_stream already QUIC-deadline-bounded (7.8), the loopback duplex is drained broker-internally (evict-not-park), block_on parks the dispatch thread not a net worker; dead endpoint offlined within a reconcile tick | int `attach_wedge_e2e.rs` | | 7.12 | Controller output delivered OFF the drain thread (dedicated writer + bounded deadline-detach), never inline under the log lock — a backed-up controller can't wedge the session | broker `OutputLog::append`/`controller_writer`, int `inject_control_wedge.rs` | | 7.13 | `spt rc` maps Windows legacy-console delete keys so Backspace→char-delete / Ctrl+Backspace→word-delete; does NOT enable VT console input (= win32-input-mode on WT, broke detach). SUPERSEDED on Windows by 7.16 (the byte-swap `normalize_key_byte` removed; behavior native in `translate_key_event`) | `rc.rs` → 7.16 `translate_key_event` | | 7.14 | `EffectJournal::apply_once` releases its lock ACROSS `effect()` (reserve→release→run→finalize), never holding it across the blocking PTY write; `EffectKind::PtyWrite` is ephemeral (no per-keystroke fsync, in-memory dedup), durable kinds keep fsync — fixes interactive stutter + the hard input wedge (`brain IPC read deadline`) | `effect.rs` `apply_once`/`is_durable`, int `inject_control_wedge.rs` | | 7.15 | `reconcile_hosted_liveness` clears stale `driven_by` when it offlines a sessionless controllable perch (no live broker session) — an OFFLINE endpoint never renders phantom `ONLINE+CONTROLLED`; race-free (no session ⇒ no concurrent broker re-stamp). `controller_by==None` is ambiguous (local controller reads None) so it is NOT a clear trigger; the idle wedged-remote leg is deferred (`REQ-HAZARD-DRIVEN-BY-IDLE-REMOTE-EVICT`) | `livehost.rs` `reconcile_hosted_liveness`, int `driven_by_selfheal.rs`/`inject_control_wedge.rs` | | 7.16 | `spt rc` on Windows reads crossterm KEY EVENTS and translates to standard xterm VT (arrows/Home/End/PgUp/Dn/Ins/Del/F-keys + modifiers reach the harness; agnostic, NOT win32-input-mode); `ctrl-b d` detach preserved event-sourced; non-tty + Unix keep the byte path; supersedes the 7.13 byte-swap | `rc.rs` `translate_key_event`/`key_event_step`/`spawn_stdin_reader_events`, unit-only (live = HITL) | | 7.17 | PTY **input** is single-writer: each session spawns ONE dedicated input-writer thread = the SOLE caller of the blocking `write_input`, fed by a bounded FIFO (`sync_channel`). Every caller (`dispatch_input`, `dispatch_endpoint_input`, the inject worker/floor flush) ENQUEUES (`try_send`) + returns at once — a paste burst that fills the harness input buffer parks only that thread, never the broker dispatch thread. Full queue ⇒ DROP excess + stamp the perch `input_backpressure` (heal-on-resume: cleared on the next accepted enqueue); the daemon NEVER wedges on a stuck harness. Completes the W1b-deferred fix (2) of 7.14. The OUTPUT-side single-writer (7.12) mirror, applied to input | broker `InputWriter`/`input_writer`/`flush_inject_floor`/`run_inject_worker`/`dispatch_input`, `spt_store::info::set_input_backpressure`, int `inject_control_wedge.rs` | | 7.18 | `spt rc` paste is **client-originated** on Windows: CC runs daemon-side with no access to the operator's LOCAL clipboard. On a RIGHT-CLICK rc reads the local clipboard itself and injects a BRACKETED paste (`ESC[200~` + content + `ESC[201~`) — CC has bracketed-paste mode on (`ESC[?2004h`), so a multi-line paste lands intact with NO `\r` submit-storm, harness-agnostic, content VERBATIM. RawGuard captures the mouse (disables console QuickEdit so right-click reaches the app) on an interactive console only + restores on drop. **ctrl+V is NOT intercepted** (P1b): WT consumes it (Key RELEASE only, never Press) + injects the clipboard as a key flood — it rides WT's native paste as keystrokes (no wedge, 7.19; bracketed = right-click). cfg(windows) only — Unix pastes natively | `rc.rs` `wrap_bracketed_paste`/`mouse_is_paste`/`clipboard_paste`/`read_clipboard`/`RawGuard`/`spawn_stdin_reader_events`, unit-only (live clipboard+mouse = HITL) | | 7.19 | An operator input FLOOD must not deadlock the broker: `serve_attach` sends N `Input` frames on one conn without reading, the broker acks each on the SAME conn → the return direction fills (~pipe buffer) → `send_frame` blocks the per-conn handler → mutual full-duplex DEADLOCK (permanent broker wedge, controller latched). FIX: opt-in ack — `InputReq.ack` (serde default true); the operator/rc path sends `ack=false` (`send_effect_no_ack`), `dispatch_input` skips the applied frame → the handler never writes back while draining the flood. `shellchan` keeps `ack=true` (its `Applied`-wait). Exactly-once unaffected (dedup at the applied-set). N-1: an old resident broker still acks until restart (7.9 class) | `msg.rs` `InputReq.ack`, `brain.rs` `send_effect_no_ack`, `attach.rs` `serve_attach`, `broker.rs` `dispatch_input`, int (flood repro) | | 7.20 | `spt rc` must forward the SCROLL wheel to the harness — our mouse capture (for right-click paste, 7.18) steals WT's native scroll. Track the harness's mouse-reporting mode from its OUTPUT (DECSET `ESC[?1000/1002/1003h` + `1006h` SGR, and `…l` off; scan survives a split across output chunks) into `MouseMode{enabled,sgr}`; forward `ScrollUp/Down` as an xterm SGR report (`ESC[<64/65;col+1;row+1M`) ONLY when `enabled && sgr`, else drop; Moved/drag/clicks dropped. cfg(windows) only — Unix scrolls natively | `rc.rs` `MouseMode`/`MouseModeScanner`/`scroll_dir`/`scroll_sgr`/`spawn_stdin_reader_events`, unit-only (live mouse = HITL) | | 7.21 | Exactly ONE LIVE `controller_writer` per brain↔broker connection + every writer emits an ASCENDING seq stream ⇒ a snap-above consumer over the surviving writer's COMPLETE `[0,end]` replay delivers `[K,end]` with no skip/dup. A brain-restart re-serve double-registered the controller (handoff's `subscribe(from_seq=K)` + the re-serve's `attach_as(sid,0)`) → two writers raced one socket → the consumer's strict reject-gap legacy path saw `got seq 1 want 0` (flaky `attach_survives_target_brain_restart_exactly_once`). FIX (fix #1 "drop handoff's subscribe" REVERTED — it's the standalone-resume mechanism): (1) `handoff` seeds `session_cursors` → dedup-below + snap-above (correctness, made complete by the ascending-merge property); (2) `controller_writer` epoch-gated via shared `Arc` `controller_epoch`, re-read UNDER `send.lock()` (single live writer); (3) `subscribe_with` resets the resume-mode dedup cursor to `from_seq` (shared by `attach`/`attach_as`) — the LOAD-BEARING fix for the operator-stream boundary: serve_attach consumes the handoff replay's seq K before `attached`, advancing the cursor; the `attach_as(0)` re-subscribe reset re-delivers it so the operator viewport stays gapless. Pre-existing; P1b innocent | `brain.rs` `handoff`/`subscribe_with`, `broker.rs` `become_controller`/`controller_writer`/`controller_epoch`, unit `src/broker.rs`, int `tests/broker.rs`+`attach.rs` (keystone + restart carrier, 20× on kitsubito) | | 7.22 | Endpoint-stop / brain-death reaps a brain-LESS perch's orphan detached Psyche via the cmdline-scoped guard — the handle-reap (`stop_host`, REQ-HAZARD-UNHOST-PSYCHE-REAP) CANNOT (the owning brain is dead, so its `psyche_child` handle died with it) and the brain-START sweep (REQ-HAZARD-BRAIN-RESTART-PSYCHE-DUP) never fires for a perch being STOPPED rather than re-hosted. So the live-host runs the scoped reap after `stop_host` at the reconcile stop-side AND in `confirm_residency_or_unhost`. Fail-safe-decline (pid-alive AND basename==psyche-program AND cmdline contains `-psyche`; any unreadable signal DECLINES — a missed dup is bounded, a wrong-kill catastrophic). The orphan-leak half of perri F-010xF-015 (the psyche own-copy is the other half, ADR-0025 amendment) | `livehost.rs` `reap_orphan_psyche_for`/`reap_stopped_endpoint_orphan_psyche`/`reconcile_once`/`confirm_residency_or_unhost`, unit `livehost.rs`, int W3e (perri step 3) | | 7.23 | An already-spooled message (WAN-arrived or spooled-while-active) NEVER depends on adapter hook-poll cadence to reach a relay-less spt-hosted endpoint — the daemon drives delivery on the events it owns. TWO daemon triggers feed ONE shared translation-binary inject leg (`spt_daemon::inject::try_spt_hosted_inject`): WAN ingress (`receive_wan` injects before spool — leg 1, `[REQ-WAN-SPT-HOSTED-DELIVERY]`) + the ACTIVE→IDLE edge (`drain_idle_window` claims the pending spool — NON-DEFERRED ONLY since the 2026-07-27 scope amendment; `active_only` is hook-carried and outside the guarantee — and injects, reusing the hook-poll take/ack so a concurrent `api poll` can't double-deliver — leg 2, `[REQ-MSG-IDLE-EDGE-DRAIN]`). v0.14.3 LAW holds on both: no binary ⇒ SPOOL LOUD (row released intact), never a raw PTY write. Fixes F-023 "sent but never lands" on an idle relay-less perch with a healthy binary | `inject.rs` `try_spt_hosted_inject`, `wan.rs` `receive_wan`, `delivery.rs` `drain_idle_window` + `spool.rs` `claim_idle_edge_at`/`release_at`, int `inject_control_wedge.rs` `wan_arrival_to_idle_spt_hosted_injects_with_no_hook_poll` + `idle_edge_drain_e2e.rs` `spool_while_active_then_idle_fires_injection` | | 7.24 | A DELEGATED live adapter apply never reports success without swapping, and the live-update seam uses ONE parent-aware matcher. `spt_runtime::profile::adapter_parent_matches(session_adapter, parent)` (`split_option().0 == parent`) at ALL three comparators (CLI `adapter_has_live_endpoint`, broker `dispatch_adapter_apply` filter, `select_endpoints_running_adapter`) — no exact `==` against a record name, so a `--adapter cc:ccs` composite endpoint resolves to parent `cc`. `dispatch_adapter_apply` swaps UNCONDITIONALLY (empty-affected early-return removed); `KIND_APPLIED` only after a real swap. Fixes F015B silent no-op (D1 matcher skew dropped every `:profile` endpoint → affected=[] → D2 success-without-swap) | `profile.rs` `adapter_parent_matches`, `broker.rs` `dispatch_adapter_apply`/`select_endpoints_running_adapter`, `cli.rs` `adapter_has_live_endpoint`, unit `profile.rs`+`broker.rs`, int (e2e a/b/c, this wave) | | 7.25 | A perch pinned to a DEAD session self-heals; a LIVE-owner rotation still refuses. `authenticate()` (auth.rs): sid mismatch AND recorded owner pid DEAD (`proc::is_process_alive`) → accept caller sid + RE-PIN (`mutate_info` rotate `session_id` + LOUD `SESSION_REPIN`) — ADR-0032 layer 2, same trust as `establish_perch`'s dead-owner rebind. LIVE-owner mismatch (a `/clear`/`/compact` live-pid rotation) STILL refuses (squat, unwidened — live-rotation proof is the adapter's layer-1 job, `[REQ-BOUNDARY-ROTATION-CREDENTIAL]`; parent_pid ancestry = parked layer 3). ADDITIVE to token auth (branch fires only on no/failed token AND sid mismatch AND owner dead). Fixes the F-024C/D permanent-strand wedge (one lost boundary rotation → every id-scoped hook incl boundary AUTH_REFUSED forever, stderr-silent in a hook) | `auth.rs` `authenticate` dead-owner branch, unit `auth.rs` `pinned_to_dead_sid_mismatched_poll_repins`+`live_owner_mismatch_still_refuses`+`token_auth_path_unchanged` | | 7.26 | Concurrent first-touch of ONE fresh BranchStore all-Ok — the non-atomic `git init` (template-hook copy) + `config.lock` race must never strand a first-toucher. `open_or_init` → `init_bare_tolerant` (bounded backoff-retry on the init collision that desyncs racers + open-after-lose on a racer-created HEAD) + `config_set_locked_retry` (bounded `config.lock`-aware retry; `core.autocrlf` idempotent). Convergence guaranteed: a lone re-init on a partial dir completes. Fixes the G3-gate pump.rs:442 flake | `branchstore.rs` `open_or_init`/`init_bare_tolerant`/`config_set_locked_retry`, unit `concurrent_open_or_init_on_one_fresh_store_all_ok` (N=8, RED-FIRST) | | 7.27 | A control/viewer stamp never outlives its session — every teardown path clears what attach stamped. `/exit` kills the CHILD (endpoint suspends on child death) so the teardown runs the REAP path (exit-waiter → `sessions.remove`), never the controller-detach path — the only pre-fix stamp-clear. The exit-waiter now calls `OutputLog::stamp_reaped()` = `set_driven_by(None)`+`set_controlled(false)`+`set_viewer_count(0)` on reap (broker single-writer, unconditional/idempotent, race-free — dead session ⇒ no concurrent re-stamp). Fixes F-026 #2 (hall-a latched `controlled:true` + gossiped `controller_node=self` for hours after `/exit`). Distinct from 7.15 (sessionless reconcile heal) | `broker.rs` `OutputLog::stamp_reaped` + exit-waiter reap call, int `control_stamp_lifetime.rs` `reap_clears_control_and_viewer_stamps` (RED-first) | | 7.28 | A relative manifest path naming an endpoint-read/written location resolves against the ENDPOINT's cwd (`info.cwd`, read at USE time), never the daemon's process cwd (one daemon hosts many cwds). commune_dir/signoff_dir resolve at ingest: absolute as-is, relative+cwd joined, relative+no-cwd SKIPPED loud-once. Project routing owlery-gated (owlery-internal anchor → no `p-`, live slice still commits; else `project_id_for_dir` parity). {cwd}-templated (digest/history) + daemon-absolute-filled (session-role/translation) keys already anchored. Fixes F-026 SI-1 (pristine BranchStore box-wide; abs-only test fixtures masked the relative leg) | `lifecycle.rs` `resolve_endpoint_drop_dir`/`is_owlery_internal`/`warn_no_cwd_once`/`pulse_tick`, `ingest.rs` `route_slices` empty-id skip, int `relative_commune_dir_resolves_against_endpoint_cwd_and_fills_project_branch` (RED-first) | | 7.29 | Control/viewer stamps CONVERGE to broker session-table truth (upward), not merely edge-trigger — the companion to 7.27's downward edge-clear. A picker-created endpoint's spawn `set_controlled(true)` fires PRE-bind (no perch → `mutate_info` NotFound swallowed); the adapter binds `controlled:false` and no edge re-stamps → uncontrolled-forever-while-driven (hall-b). Broker (single-writer) re-asserts each live session's stamps DIVERGENCE-GATED (write only on diff, no fsync storm) on the `KIND_SESSIONS` poll (bounded window = reconcile cadence, no new timer); truth snapshotted under the log lock, writes OFF it. Event-on-input insufficient (idle controlled sessions). Fixes F-026 stamp-gap | `broker.rs` `stamp_divergence`/`converge_perch_stamps`/`has_controller`/`live_viewer_count` + KIND_SESSIONS handler, unit `stamp_divergence_gates_writes`, int `converge_stamps_on_sessions_poll_after_late_bind` (RED-first) | | 7.30 | A Psyche failure of ANY shape never removes/alters the parent endpoint's ready/hosted state — a Psyche is a bounded per-event turn, so there is no "resident gone" signal; a turn failure stamps `psyche_host_error` ONLY, never `status`/ready. Residency machinery (`confirm_residency_or_unhost`) + the teardown-on-psyche-trouble deleted. Fixes the adapter v0.13.2 field brick (shim exit → residency teardown → ready removed → permanent `cli-gate-not-hosted`) | `livehost.rs` residency/reap deletions, `lifecycle.rs` `run_psyche_event_turn` psyche-fields-only stamp + `first_turn_psyche_context` non-empty, int (hall-bf shape: failing psyche → parent stays deliverable, no churn) | | 7.38 | Every physical broker-conn write bounded + cancelable + poison-on-failure (independent watchdog aborter; poisoned conn never reused; SendHalf never leaves the conn object) | broker `conn.rs` `BrokerConn`, all write sites (`controller_writer`/`viewer_writer`/`send_frame`/nethost), int `brain_decouple.rs` | | 7.31 | The Psyche failure budget counts REAL per-event attempts — every bounded per-event turn feeds a consecutive-N budget (default 3), so per-event churn a resident rate-guard was blind to now counts by construction. Fixes hall-bf's ~12/min re-host churn that ran invisibly (boot records weren't ledger boundaries to the old guard) | `lifecycle.rs` `note_turn_outcome`/`psyche_turn_strikes_exhausted` (stamps `psyche_host_error` on exhaustion, no `status` de-stamp), unit synthetic failure-loop trips the budget (RED-first control) |