Edit

    fn subscribe_with(
        &mut self,
        session_id: u64,
        from_seq: u64,
        intent: AttachIntent,
        by: Option<String>,
    ) -> io::Result<()> {
        self.send(
            KIND_SUBSCRIBE,
            serde_json::to_value(SubscribeReq {
                session_id,
                from_seq,
                intent,
                by,
            })
            .expect("SubscribeReq serializes"),
        )
    }

    fn subscribe_with(
        &mut self,
        session_id: u64,
        from_seq: u64,
        intent: AttachIntent,
        by: Option<String>,
    ) -> io::Result<()> {
        // P1c (operator-stream boundary, kitsubito RACEDIAG): a resume-mode brain
        // (seeded map) that subscribes from `from_seq` must RESET this session's
        // dedup cursor to `from_seq` — the broker's replay from `from_seq` is then
        // re-delivered (and the operator's render cursor dedups the overlap),
        // never lost. WHY THIS, NOT just `read_event`'s `or_insert`: on a re-serve,
        // `serve_attach` may CONSUME a handoff-replay frame at the K boundary
        // BEFORE it is `attached` (the frame is dropped by the `if attached` gate
        // but the snap-above cursor still advanced past K); `attach_as(sid, 0)`
        // then re-subscribes from 0, and without this reset the broker's re-send of
        // seq K arrives below the advanced cursor and is deduped → seq K never
        // reaches the operator viewport → a forward gap. Resetting to `from_seq`
        // makes the re-subscribe re-deliver everything from its floor. A cold-start
        // brain (empty map — e.g. the production dispatch serve brain) keeps the
        // legacy `next_seq` path; this only arms in resume mode.
        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]
        if !self.session_cursors.is_empty() {
            self.session_cursors.insert(session_id, from_seq);
        }
        self.send(
            KIND_SUBSCRIBE,
            serde_json::to_value(SubscribeReq {
                session_id,
                from_seq,
                intent,
                by,
            })
            .expect("SubscribeReq serializes"),
        )
    }


The file C:\Users\decid\Documents\projects\spt-core\crates\spt-daemon\src\brain.rs has been updated successfully. (file state is current in your context — no need to Read it back)

    fn subscribe_with(
        &mut self,
        session_id: u64,
        from_seq: u64,
        intent: AttachIntent,
        by: Option<String>,
    ) -> io::Result<()> {
        self.send(
            KIND_SUBSCRIBE,
            serde_json::to_value(SubscribeReq {
                session_id,
                from_seq,
                intent,
                by,
            })
            .expect("SubscribeReq serializes"),
        )
    }

    fn subscribe_with(
        &mut self,
        session_id: u64,
        from_seq: u64,
        intent: AttachIntent,
        by: Option<String>,
    ) -> io::Result<()> {
        // P1c (operator-stream boundary, kitsubito RACEDIAG): a resume-mode brain
        // (seeded map) that subscribes from `from_seq` must RESET this session's
        // dedup cursor to `from_seq` — the broker's replay from `from_seq` is then
        // re-delivered (and the operator's render cursor dedups the overlap),
        // never lost. WHY THIS, NOT just `read_event`'s `or_insert`: on a re-serve,
        // `serve_attach` may CONSUME a handoff-replay frame at the K boundary
        // BEFORE it is `attached` (the frame is dropped by the `if attached` gate
        // but the snap-above cursor still advanced past K); `attach_as(sid, 0)`
        // then re-subscribes from 0, and without this reset the broker's re-send of
        // seq K arrives below the advanced cursor and is deduped → seq K never
        // reaches the operator viewport → a forward gap. Resetting to `from_seq`
        // makes the re-subscribe re-deliver everything from its floor. A cold-start
        // brain (empty map — e.g. the production dispatch serve brain) keeps the
        // legacy `next_seq` path; this only arms in resume mode.
        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]
        if !self.session_cursors.is_empty() {
            self.session_cursors.insert(session_id, from_seq);
        }
        self.send(
            KIND_SUBSCRIBE,
            serde_json::to_value(SubscribeReq {
                session_id,
                from_seq,
                intent,
                by,
            })
            .expect("SubscribeReq serializes"),
        )
    }

+        // P1c (operator-stream boundary, kitsubito RACEDIAG): a resume-mode brain

+        // (seeded map) that subscribes from `from_seq` must RESET this session's

+        // dedup cursor to `from_seq` — the broker's replay from `from_seq` is then

+        // re-delivered (and the operator's render cursor dedups the overlap),

+        // never lost. WHY THIS, NOT just `read_event`'s `or_insert`: on a re-serve,

+        // `serve_attach` may CONSUME a handoff-replay frame at the K boundary

+        // BEFORE it is `attached` (the frame is dropped by the `if attached` gate

+        // but the snap-above cursor still advanced past K); `attach_as(sid, 0)`

+        // then re-subscribes from 0, and without this reset the broker's re-send of

+        // seq K arrives below the advanced cursor and is deduped → seq K never

+        // reaches the operator viewport → a forward gap. Resetting to `from_seq`

+        // makes the re-subscribe re-deliver everything from its floor. A cold-start

+        // brain (empty map — e.g. the production dispatch serve brain) keeps the

+        // legacy `next_seq` path; this only arms in resume mode.

+        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]

+        if !self.session_cursors.is_empty() {

+            self.session_cursors.insert(session_id, from_seq);


Now remove the now-redundant reset from `attach()` (subscribe_with handles it):


    pub fn attach(&mut self, session_id: u64, from_seq: u64) -> io::Result<()> {
        self.session_id = Some(session_id);
        self.next_seq = from_seq;
        // A resume-mode brain (non-empty map) routes this session's output through
        // the per-session map via `read_event`'s first-sight `or_insert` seed
        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above.
        //
        // P1c: `or_insert` only seeds a FIRST-sight session. An EXPLICIT re-attach
        // of an already-tracked session (e.g. a from-0 ground-truth re-read after
        // a resume, or any deliberate re-subscribe from a different floor) must
        // RESET this session's dedup cursor to `from_seq` — otherwise a prior
        // seed/advance dedup-drops the very replay the caller asked for. Only in
        // resume mode (the seeded map); a legacy brain keeps the `next_seq` path.
        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]
        if !self.session_cursors.is_empty() {
            self.session_cursors.insert(session_id, from_seq);
        }
        self.subscribe(session_id, from_seq)
    }

    pub fn attach(&mut self, session_id: u64, from_seq: u64) -> io::Result<()> {
        self.session_id = Some(session_id);
        self.next_seq = from_seq;
        // A resume-mode brain (non-empty map) routes this session's output through
        // the per-session map via `read_event`'s first-sight `or_insert` seed
        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above. The
        // resume-mode dedup-cursor reset for an explicit re-subscribe lives in
        // `subscribe_with` (P1c, shared by `attach`/`attach_as`).
        self.subscribe(session_id, from_seq)
    }


    pub fn attach(&mut self, session_id: u64, from_seq: u64) -> io::Result<()> {
        self.session_id = Some(session_id);
        self.next_seq = from_seq;
        // A resume-mode brain (non-empty map) routes this session's output through
        // the per-session map via `read_event`'s first-sight `or_insert` seed
        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above.
        //
        // P1c: `or_insert` only seeds a FIRST-sight session. An EXPLICIT re-attach
        // of an already-tracked session (e.g. a from-0 ground-truth re-read after
        // a resume, or any deliberate re-subscribe from a different floor) must
        // RESET this session's dedup cursor to `from_seq` — otherwise a prior
        // seed/advance dedup-drops the very replay the caller asked for. Only in
        // resume mode (the seeded map); a legacy brain keeps the `next_seq` path.
        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]
        if !self.session_cursors.is_empty() {
            self.session_cursors.insert(session_id, from_seq);
        }
        self.subscribe(session_id, from_seq)
    }

    pub fn attach(&mut self, session_id: u64, from_seq: u64) -> io::Result<()> {
        self.session_id = Some(session_id);
        self.next_seq = from_seq;
        // A resume-mode brain (non-empty map) routes this session's output through
        // the per-session map via `read_event`'s first-sight `or_insert` seed
        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above. The
        // resume-mode dedup-cursor reset for an explicit re-subscribe lives in
        // `subscribe_with` (P1c, shared by `attach`/`attach_as`).
        self.subscribe(session_id, from_seq)
    }

-        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above.

-        // P1c: `or_insert` only seeds a FIRST-sight session. An EXPLICIT re-attach

-        // of an already-tracked session (e.g. a from-0 ground-truth re-read after

-        // a resume, or any deliberate re-subscribe from a different floor) must

-        // RESET this session's dedup cursor to `from_seq` — otherwise a prior

-        // seed/advance dedup-drops the very replay the caller asked for. Only in

-        // resume mode (the seeded map); a legacy brain keeps the `next_seq` path.

-        // [impl->REQ-HAZARD-CONTROLLER-WRITER-REORDER]

-        if !self.session_cursors.is_empty() {

-            self.session_cursors.insert(session_id, from_seq);

+        // (D4-2b); a legacy brain (empty map) uses the `next_seq` set above. The

+        // resume-mode dedup-cursor reset for an explicit re-subscribe lives in

+        // `subscribe_with` (P1c, shared by `attach`/`attach_as`).


Fix applied (reset now in `subscribe_with`, covers `attach_as`). Compile + run the Windows sweep to confirm no regression (the 33% fix is doyle's kitsubito verify):


Bash

cd C:/Users/decid/Documents/projects/spt-core && cargo build -p spt-daemon --tests 2>&1 | grep -E "error|Finished" | tail -3; echo "BUILD=${PIPESTATUS[0]}"
echo "=== carrier + new int + cv-matrix ==="
timeout 120 cargo test -p spt-daemon --test attach -- --test-threads=1 2>&1 | grep -E "test result|FAILED"; echo "[attach EXIT=${PIPESTATUS[0]}]"

Build and run attach suite after the fix


check your ongoing Monitor tool call's output


    Finished `dev` profile [unoptimized + debuginfo] target(s) in 33.74s
BUILD=0
=== carrier + new int + cv-matrix ===
test result: ok. 14 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 3.21s
[attach EXIT=0]


attach 14/14. Now the standalone-resume callers + broker keystone + lib:


cd C:/Users/decid/Documents/projects/spt-core
for suite in brain_swap handoff idempotent broker; do
  echo "=== $suite ==="
  timeout 200 cargo test -p spt-daemon --test $suite -- --test-threads=1 2>&1 | grep -E "test result|FAILED"; echo "[$suite EXIT=${PIPESTATUS[0]}]"
done
echo "=== lib (white-box keystone) ===" && timeout 200 cargo test -p spt-daemon --lib 2>&1 | grep -E "test result|FAILED"; echo "[lib EXIT=${PIPESTATUS[0]}]"

Run standalone callers + broker + lib after the fix


=== brain_swap ===
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s
[brain_swap EXIT=0]
=== handoff ===
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.21s
[handoff EXIT=0]
=== idempotent ===
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s
[idempotent EXIT=0]
=== broker ===
test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.47s
[broker EXIT=0]
=== lib (white-box keystone) ===
test result: ok. 349 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 9.81s
[lib EXIT=0]


No regression — all green (brain_swap/handoff/idempotent standalone resume intact, broker 8/8, lib 349/0). Direction 2 is clean on Windows; the 33% fix needs doyle's kitsubito. Now clippy + traceable + docs-drift:


cd C:/Users/decid/Documents/projects/spt-core && echo "=== clippy ===" && cargo clippy --workspace --all-targets -- -D warnings 2>&1 | tail -3; echo "[clippy=${PIPESTATUS[0]}]"; echo "=== traceable ===" && traceable-reqs check >/dev/null 2>&1; echo "traceable=$?"; echo "=== docs-drift ===" && cargo run -p xtask -- gen >/dev/null 2>&1 && git status --short | grep -E "reference.md|docs-site" || echo "(no docs drift)"

Run clippy, traceable, docs-drift after the fix


=== clippy ===
    Checking spt v0.12.1 (C:\Users\decid\Documents\projects\spt-core\crates\spt)
    Checking xtask v0.12.1 (C:\Users\decid\Documents\projects\spt-core\crates\xtask)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 10.09s
[clippy=0]
=== traceable ===
traceable=0
=== docs-drift ===
(no docs drift)


All gates green. Now updating KH 7.21 + REQ for the operator-stream boundary fix. Reading current 7.21:


cd C:/Users/decid/Documents/projects/spt-core && rg -n "7.21|Brain::attach\` \(resume-mode|attach\` \(resume-mode cursor|EXPLICIT-RESUME" docs/KNOWN-HAZARDS.md | head

Locate 7.21 EXPLICIT-RESUME text to update


469:### 7.21 Exactly ONE `controller_writer` per brain↔broker connection — a superseded writer must write nothing further  `[REQ-HAZARD-CONTROLLER-WRITER-REORDER]`
471:- **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<AtomicU64>`, 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<OutputLog>`). 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 — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.
472:- **spt-core mapping:** impl `brain.rs` `Brain::handoff` (KEEP the eager `subscribe`; seed `session_cursors`) + `Brain::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs` `OutputLog.controller_epoch: Arc<AtomicU64>` / `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).
529:| 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<AtomicU64>` `controller_epoch`, re-read UNDER `send.lock()` (single live writer); (3) explicit `Brain::attach(sid,from_seq)` resets the resume-mode dedup cursor to `from_seq`. Pre-existing; P1b innocent | `brain.rs` `handoff`/`attach`, `broker.rs` `become_controller`/`controller_writer`/`controller_epoch`, unit `src/broker.rs`, int `tests/broker.rs`+`attach.rs` (keystone + restart carrier, 20× on kitsubito) |


Updating bullet (3) — the operator-stream boundary is the load-bearing root (kitsubito), and the reset now lives in `subscribe_with`:


Edit

(3) EXPLICIT-RESUME — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.

(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 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's render cursor (`render_until`), and SILENT content loss in the real `rc` consumer (dedup-below + snap-above). Resetting the cursor 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-level 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.


<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>

Error: File has not been read yet. Read it first before writing to it.


471	- **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<AtomicU64>`, 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<OutputLog>`). 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 — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.
472	- **spt-core mapping:** impl `brain.rs` `Brain::handoff` (KEEP the eager `subscribe`; seed `session_cursors`) + `Brain::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs` `OutputLog.controller_epoch: Arc<AtomicU64>` / `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).
473	- **Source:** v0.13.0 P1c (operator-ruled root-fix before ship; doyle root-cause via instrumented repro 2026-06-20; design corrected at the gate — fix #1 reverted, epoch-gate + snap-above + attach-reset carry it). The last v0.13.0 ship-blocker.

- **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<AtomicU64>`, 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<OutputLog>`). 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 — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.
- **spt-core mapping:** impl `brain.rs` `Brain::handoff` (KEEP the eager `subscribe`; seed `session_cursors`) + `Brain::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs` `OutputLog.controller_epoch: Arc<AtomicU64>` / `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 at the gate — fix #1 reverted, epoch-gate + snap-above + attach-reset carry it). The last v0.13.0 ship-blocker.


(3) EXPLICIT-RESUME — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.

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


The file C:\Users\decid\Documents\projects\spt-core\docs\KNOWN-HAZARDS.md has been updated successfully. (file state is current in your context — no need to Read it back)

### 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<Mutex<socket>>`) 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<AtomicU64>`, 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<OutputLog>`). 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 — an explicit `Brain::attach(sid, from_seq)` in resume mode RESETS that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so without this a from-0 ground-truth re-read after a resume dedup-drops its own replay). Cold-start brains (empty map) keep the legacy `next_seq` path untouched.

+- **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<AtomicU64>`, 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<OutputLog>`). 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::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs` `OutputLog.controller_epoch: Arc<AtomicU64>` / `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 at the gate — fix #1 reverted, epoch-gate + snap-above + attach-reset carry it). The last v0.13.0 ship-blocker.


- **spt-core mapping:** impl `brain.rs` `Brain::handoff` (KEEP the eager `subscribe`; seed `session_cursors`) + `Brain::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs`

- **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`


- **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<AtomicU64>`, 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<OutputLog>`). 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::attach` (resume-mode cursor reset to `from_seq`) + `broker.rs` `OutputLog.controller_epoch: Arc<AtomicU64>` / `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).

+- **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<AtomicU64>` / `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 at the gate — fix #1 reverted, epoch-gate + snap-above + attach-reset carry it). The last v0.13.0 ship-blocker.

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


- **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<AtomicU64>` / `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 at the gate — fix #1 reverted, epoch-gate + snap-above + attach-reset carry it). The last v0.13.0 ship-blocker.

+- **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.


(3) explicit `Brain::attach(sid,from_seq)` resets the resume-mode dedup cursor to `from_seq`. Pre-existing; P1b innocent | `brain.rs` `handoff`/`attach`, `broker.rs` `become_controller`/`controller_writer`/`controller_epoch`, unit `src/broker.rs`, int `tests/broker.rs`+`attach.rs` (keystone + restart carrier, 20× on kitsubito) |

(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.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<AtomicU64>` `controller_epoch`, re-read UNDER `send.lock()` (single live writer); (3) explicit `Brain::attach(sid,from_seq)` resets the resume-mode dedup cursor to `from_seq`. Pre-existing; P1b innocent | `brain.rs` `handoff`/`attach`, `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.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<AtomicU64>` `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) |


Now the REQ registry — update the FIX (3) and impl (3) to `subscribe_with` + the operator-stream boundary:


Bash

cd C:/Users/decid/Documents/projects/spt-core && rg -n "EXPLICIT-RESUME — an explicit|Brain::attach resets session_cursors|attach\(\) now resets" traceable-reqs.toml

Locate REQ text mentioning attach reset


1280:title = "Two `controller_writer` threads must never race ONE brain↔broker connection's socket. ROOT (doyle, instrumented RACEDIAG repro on kitsubito): on a brain-restart re-serve the handoff brain registers as controller on the SAME session TWICE over the SAME `Brain::conn` socket — (1) `Brain::handoff` eagerly `subscribe(prior.session_id, prior.next_seq=1)` → `become_controller(from_seq=1)`, initial=[1], spawns writer-A (writes seq 1); (2) `serve_attach` re-handles the replayed `Request{from_seq:0}` → `attach_as(sid,0)` → `become_controller(from_seq=0)`, initial=[0,1], spawns writer-B (writes 0 then 1). `become_controller` (broker.rs) drops the prior `ControllerSink` (its `tx`) but does NOT stop the prior writer thread — writer-A keeps flushing its owned `initial` batch, and both writers hold clones of the same `SharedSend` (`Arc<Mutex<socket>>`) with NO inter-thread ordering. When writer-A's seq 1 wins the socket before writer-B's seq 0, the strict legacy consumer (brain.rs read_event reject-gap path) sees `output gap: got seq 1 want 0` → the test `attach_survives_target_brain_restart_exactly_once` panics at `.expect(\"re-serve\")` OR HANGS in `render_until` (serve thread died on the gap → MARKER_TWO never reaches the wire). `prior.next_seq` is life1's CONSUMPTION cursor, NOT life2's connection state — life2's socket has been sent NOTHING, so a `from_seq=0` full replay on a connection that already streamed seq 1 is contradictory. Snap-above tolerance ALONE can't fix it (it would dedup-drop the late seq 0 → byte loss → the exactly-once byte-identity assert fails). PRE-EXISTING, surfaced by the v0.13.0 green-both-runners release gate; P1b is INNOCENT (its diff touches only input-ack machinery, proven mechanically + the test passes post-P1b in isolation). Sibling flaky cluster: `inject_control_wedge::g2`, `broker::spawn_env_reaches_child`. INVARIANT: on a single brain↔broker connection the controller output-frame stream is monotonic non-decreasing in seq (modulo dedup re-sends); exactly ONE `controller_writer` is ever live per connection; a SUPERSEDED writer writes NO further frames; a re-serve never replays a seq below what the connection already received. FIX (doyle design, corrected at the gate 2026-06-20): fix #1 as designed ('drop handoff's eager subscribe so serve_attach's attach_as is the sole registration') was REVERTED — handoff's `subscribe(prior.next_seq)` IS the standalone-resume mechanism (the brain-only update engine `apply_brain_only` + the `handoff`/`idempotent`/`daemon_e2e` int tests replay output through it with NO `serve_attach`; dropping it hung every resume-via-handoff test). The shipped fix is three parts: (1) CORRECTNESS — `Brain::handoff` seeds `session_cursors` at `prior.next_seq` so the consumer runs the production dedup-below+snap-above path, never the strict reject-gap legacy trap; this is COMPLETE (not merely tolerant) because every `controller_writer` emits an ASCENDING seq stream and the surviving writer (serve_attach's attach_as(sid,0)) offers the complete `[0,end]` range, so a snap-above merge of ascending writers delivers `[K,end]` with no skip/dup (first sighting of any seq>M is preceded by M on that writer). (2) INVARIANT — `controller_writer`'s INITIAL-BATCH replay is epoch-gated: `controller_epoch` is a shared `Arc<AtomicU64>`, the writer re-reads it UNDER `send.lock()` (atomically with `write_frame`) and returns the instant it is superseded — no check-then-block-then-write window, no superseded replay (W1-safe: never blocks the drain under `Mutex<OutputLog>`). The LIVE loop is NOT gated (new output only flows to the current controller; a superseded writer must still deliver its terminal `Displaced` kick — gating it suppressed the loud-take notice; it ends on `tx`-drop). (3) EXPLICIT-RESUME — an explicit `Brain::attach(sid,from_seq)` in resume mode resets that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so a from-0 ground-truth re-read after a resume would otherwise dedup-drop its own replay); cold-start brains (empty map) keep the legacy `next_seq` path. (v0.13.0)"
1281:required_stages = ["doc", "impl", "unit", "int"]  # ACTIVATED v0.13.0 P1c (todlando, the last v0.13.0 ship-blocker — pre-existing flaky resume race that gates green-both-runners; doyle root-caused + designed, doyle gates). doc = KNOWN-HAZARDS entry (the reorder + the single-live-writer-per-connection invariant + the two compounding defects) + CONTEXT note. impl = (1) Brain::handoff KEEPS its eager subscribe(prior.session_id, prior.next_seq) [fix #1 REVERTED — load-bearing resume] AND seeds session_cursors.insert(prior.session_id, prior.next_seq); (2) OutputLog.controller_epoch -> Arc<AtomicU64>, become_controller passes the new epoch + Arc::clone into controller_writer, whose INITIAL-BATCH loop returns when controller_epoch != its snapshot (read UNDER send.lock(), atomically with write_frame) — the live recv loop is NOT gated (delivers a superseded controller's terminal Displaced, ends on tx-drop), become_controller/mark_controller_gone/the ControllerJob epoch read switch to atomic load/fetch_add; (3) Brain::attach resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map) so an explicit re-attach honors its floor. unit = epoch-gated controller_writer: a superseded writer (epoch bumped) writes NOTHING from its initial batch (real broker socket, two become_controller on one connection -> only the latest writer's monotonic stream reaches the wire) + handoff seeds session_cursors (session_cursor(sid) == prior.next_seq) + resubscribes for resume. int = the keystone: deterministically force two become_controller-on-one-connection (handoff-then-reserve ordering) on a real broker+brain, NO mocks -> PRE-FIX the wire reorders (got seq 1 want 0 / gap or byte-drop) -> POST-FIX the wire stays monotonic + byte-exact + the session stays live; PLUS attach_survives_target_brain_restart_exactly_once green (doyle runs it 20x isolated single-threaded timeout-wrapped on Linux/kitsubito — the deterministic RED-on-revert carrier). Full seam sweep (attach/broker/resume/brain_swap/inject_control_wedge — the shared W1 controller-writer model). clippy/traceable/docs-drift."


Edit

(3) EXPLICIT-RESUME — an explicit `Brain::attach(sid,from_seq)` in resume mode resets that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so a from-0 ground-truth re-read after a resume would otherwise dedup-drop its own replay); cold-start brains (empty map) keep the legacy `next_seq` path. (v0.13.0)"

(3) EXPLICIT-RESUME / OPERATOR-STREAM BOUNDARY (the LOAD-BEARING fix — kitsubito RACEDIAG ~33% repro the keystones missed) — `Brain::subscribe_with` (shared by attach/attach_as) resets the resume-mode dedup cursor to `from_seq`. The handoff eager subscribe makes serve_attach's brain receive the replay's seq K BEFORE the operator Request is processed (`attached`=false); that frame is dropped by the if-attached forward gate but the snap-above cursor already advanced past K, and `attach_as(sid,0)`'s re-subscribe used to leave the cursor advanced → the broker's re-send of seq K arrives below it, deduped, never forwarded → operator viewport forward-gap (silent content loss in the real rc consumer). Resetting to from_seq on the attach_as re-subscribe re-delivers from 0 (operator dedups the overlap) so seq K reaches the viewport. The epoch gate (2) is sound (RACEDIAG: zero socket interleaving above K); cold-start brains (empty map — production dispatch serve) keep the legacy next_seq path, so production is unaffected. (v0.13.0)"


The file C:\Users\decid\Documents\projects\spt-core\traceable-reqs.toml has been updated successfully. (file state is current in your context — no need to Read it back)

# ── P1c (operator-ruled root-fix before v0.13.0 ship; doyle root-cause via instrumented repro on kitsubito, 2026-06-20): controller-writer reorder on brain-restart re-serve ──

-title = "Two `controller_writer` threads must never race ONE brain↔broker connection's socket. ROOT (doyle, instrumented RACEDIAG repro on kitsubito): on a brain-restart re-serve the handoff brain registers as controller on the SAME session TWICE over the SAME `Brain::conn` socket — (1) `Brain::handoff` eagerly `subscribe(prior.session_id, prior.next_seq=1)` → `become_controller(from_seq=1)`, initial=[1], spawns writer-A (writes seq 1); (2) `serve_attach` re-handles the replayed `Request{from_seq:0}` → `attach_as(sid,0)` → `become_controller(from_seq=0)`, initial=[0,1], spawns writer-B (writes 0 then 1). `become_controller` (broker.rs) drops the prior `ControllerSink` (its `tx`) but does NOT stop the prior writer thread — writer-A keeps flushing its owned `initial` batch, and both writers hold clones of the same `SharedSend` (`Arc<Mutex<socket>>`) with NO inter-thread ordering. When writer-A's seq 1 wins the socket before writer-B's seq 0, the strict legacy consumer (brain.rs read_event reject-gap path) sees `output gap: got seq 1 want 0` → the test `attach_survives_target_brain_restart_exactly_once` panics at `.expect(\"re-serve\")` OR HANGS in `render_until` (serve thread died on the gap → MARKER_TWO never reaches the wire). `prior.next_seq` is life1's CONSUMPTION cursor, NOT life2's connection state — life2's socket has been sent NOTHING, so a `from_seq=0` full replay on a connection that already streamed seq 1 is contradictory. Snap-above tolerance ALONE can't fix it (it would dedup-drop the late seq 0 → byte loss → the exactly-once byte-identity assert fails). PRE-EXISTING, surfaced by the v0.13.0 green-both-runners release gate; P1b is INNOCENT (its diff touches only input-ack machinery, proven mechanically + the test passes post-P1b in isolation). Sibling flaky cluster: `inject_control_wedge::g2`, `broker::spawn_env_reaches_child`. INVARIANT: on a single brain↔broker connection the controller output-frame stream is monotonic non-decreasing in seq (modulo dedup re-sends); exactly ONE `controller_writer` is ever live per connection; a SUPERSEDED writer writes NO further frames; a re-serve never replays a seq below what the connection already received. FIX (doyle design, corrected at the gate 2026-06-20): fix #1 as designed ('drop handoff's eager subscribe so serve_attach's attach_as is the sole registration') was REVERTED — handoff's `subscribe(prior.next_seq)` IS the standalone-resume mechanism (the brain-only update engine `apply_brain_only` + the `handoff`/`idempotent`/`daemon_e2e` int tests replay output through it with NO `serve_attach`; dropping it hung every resume-via-handoff test). The shipped fix is three parts: (1) CORRECTNESS — `Brain::handoff` seeds `session_cursors` at `prior.next_seq` so the consumer runs the production dedup-below+snap-above path, never the strict reject-gap legacy trap; this is COMPLETE (not merely tolerant) because every `controller_writer` emits an ASCENDING seq stream and the surviving writer (serve_attach's attach_as(sid,0)) offers the complete `[0,end]` range, so a snap-above merge of ascending writers delivers `[K,end]` with no skip/dup (first sighting of any seq>M is preceded by M on that writer). (2) INVARIANT — `controller_writer`'s INITIAL-BATCH replay is epoch-gated: `controller_epoch` is a shared `Arc<AtomicU64>`, the writer re-reads it UNDER `send.lock()` (atomically with `write_frame`) and returns the instant it is superseded — no check-then-block-then-write window, no superseded replay (W1-safe: never blocks the drain under `Mutex<OutputLog>`). The LIVE loop is NOT gated (new output only flows to the current controller; a superseded writer must still deliver its terminal `Displaced` kick — gating it suppressed the loud-take notice; it ends on `tx`-drop). (3) EXPLICIT-RESUME — an explicit `Brain::attach(sid,from_seq)` in resume mode resets that session's dedup cursor to `from_seq` (a deliberate re-subscribe honors its floor; `read_event`'s `or_insert` only seeds a first-sight session, so a from-0 ground-truth re-read after a resume would otherwise dedup-drop its own replay); cold-start brains (empty map) keep the legacy `next_seq` path. (v0.13.0)"

+title = "Two `controller_writer` threads must never race ONE brain↔broker connection's socket. ROOT (doyle, instrumented RACEDIAG repro on kitsubito): on a brain-restart re-serve the handoff brain registers as controller on the SAME session TWICE over the SAME `Brain::conn` socket — (1) `Brain::handoff` eagerly `subscribe(prior.session_id, prior.next_seq=1)` → `become_controller(from_seq=1)`, initial=[1], spawns writer-A (writes seq 1); (2) `serve_attach` re-handles the replayed `Request{from_seq:0}` → `attach_as(sid,0)` → `become_controller(from_seq=0)`, initial=[0,1], spawns writer-B (writes 0 then 1). `become_controller` (broker.rs) drops the prior `ControllerSink` (its `tx`) but does NOT stop the prior writer thread — writer-A keeps flushing its owned `initial` batch, and both writers hold clones of the same `SharedSend` (`Arc<Mutex<socket>>`) with NO inter-thread ordering. When writer-A's seq 1 wins the socket before writer-B's seq 0, the strict legacy consumer (brain.rs read_event reject-gap path) sees `output gap: got seq 1 want 0` → the test `attach_survives_target_brain_restart_exactly_once` panics at `.expect(\"re-serve\")` OR HANGS in `render_until` (serve thread died on the gap → MARKER_TWO never reaches the wire). `prior.next_seq` is life1's CONSUMPTION cursor, NOT life2's connection state — life2's socket has been sent NOTHING, so a `from_seq=0` full replay on a connection that already streamed seq 1 is contradictory. Snap-above tolerance ALONE can't fix it (it would dedup-drop the late seq 0 → byte loss → the exactly-once byte-identity assert fails). PRE-EXISTING, surfaced by the v0.13.0 green-both-runners release gate; P1b is INNOCENT (its diff touches only input-ack machinery, proven mechanically + the test passes post-P1b in isolation). Sibling flaky cluster: `inject_control_wedge::g2`, `broker::spawn_env_reaches_child`. INVARIANT: on a single brain↔broker connection the controller output-frame stream is monotonic non-decreasing in seq (modulo dedup re-sends); exactly ONE `controller_writer` is ever live per connection; a SUPERSEDED writer writes NO further frames; a re-serve never replays a seq below what the connection already received. FIX (doyle design, corrected at the gate 2026-06-20): fix #1 as designed ('drop handoff's eager subscribe so serve_attach's attach_as is the sole registration') was REVERTED — handoff's `subscribe(prior.next_seq)` IS the standalone-resume mechanism (the brain-only update engine `apply_brain_only` + the `handoff`/`idempotent`/`daemon_e2e` int tests replay output through it with NO `serve_attach`; dropping it hung every resume-via-handoff test). The shipped fix is three parts: (1) CORRECTNESS — `Brain::handoff` seeds `session_cursors` at `prior.next_seq` so the consumer runs the production dedup-below+snap-above path, never the strict reject-gap legacy trap; this is COMPLETE (not merely tolerant) because every `controller_writer` emits an ASCENDING seq stream and the surviving writer (serve_attach's attach_as(sid,0)) offers the complete `[0,end]` range, so a snap-above merge of ascending writers delivers `[K,end]` with no skip/dup (first sighting of any seq>M is preceded by M on that writer). (2) INVARIANT — `controller_writer`'s INITIAL-BATCH replay is epoch-gated: `controller_epoch` is a shared `Arc<AtomicU64>`, the writer re-reads it UNDER `send.lock()` (atomically with `write_frame`) and returns the instant it is superseded — no check-then-block-then-write window, no superseded replay (W1-safe: never blocks the drain under `Mutex<OutputLog>`). The LIVE loop is NOT gated (new output only flows to the current controller; a superseded writer must still deliver its terminal `Displaced` kick — gating it suppressed the loud-take notice; it ends on `tx`-drop). (3) EXPLICIT-RESUME / OPERATOR-STREAM BOUNDARY (the LOAD-BEARING fix — kitsubito RACEDIAG ~33% repro the keystones missed) — `Brain::subscribe_with` (shared by attach/attach_as) resets the resume-mode dedup cursor to `from_seq`. The handoff eager subscribe makes serve_attach's brain receive the replay's seq K BEFORE the operator Request is processed (`attached`=false); that frame is dropped by the if-attached forward gate but the snap-above cursor already advanced past K, and `attach_as(sid,0)`'s re-subscribe used to leave the cursor advanced → the broker's re-send of seq K arrives below it, deduped, never forwarded → operator viewport forward-gap (silent content loss in the real rc consumer). Resetting to from_seq on the attach_as re-subscribe re-delivers from 0 (operator dedups the overlap) so seq K reaches the viewport. The epoch gate (2) is sound (RACEDIAG: zero socket interleaving above K); cold-start brains (empty map — production dispatch serve) keep the legacy next_seq path, so production is unaffected. (v0.13.0)"

required_stages = ["doc", "impl", "unit", "int"]  # ACTIVATED v0.13.0 P1c (todlando, the last v0.13.0 ship-blocker — pre-existing flaky resume race that gates green-both-runners; doyle root-caused + designed, doyle gates). doc = KNOWN-HAZARDS entry (the reorder + the single-live-writer-per-connection invariant + the two compounding defects) + CONTEXT note. impl = (1) Brain::handoff KEEPS its eager subscribe(prior.session_id, prior.next_seq) [fix #1 REVERTED — load-bearing resume] AND seeds session_cursors.insert(prior.session_id, prior.next_seq); (2) OutputLog.controller_epoch -> Arc<AtomicU64>, become_controller passes the new epoch + Arc::clone into controller_writer, whose INITIAL-BATCH loop returns when controller_epoch != its snapshot (read UNDER send.lock(), atomically with write_frame) — the live recv loop is NOT gated (delivers a superseded controller's terminal Displaced, ends on tx-drop), become_controller/mark_controller_gone/the ControllerJob epoch read switch to atomic load/fetch_add; (3) Brain::attach resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map) so an explicit re-attach honors its floor. unit = epoch-gated controller_writer: a superseded writer (epoch bumped) writes NOTHING from its initial batch (real broker socket, two become_controller on one connection -> only the latest writer's monotonic stream reaches the wire) + handoff seeds session_cursors (session_cursor(sid) == prior.next_seq) + resubscribes for resume. int = the keystone: deterministically force two become_controller-on-one-connection (handoff-then-reserve ordering) on a real broker+brain, NO mocks -> PRE-FIX the wire reorders (got seq 1 want 0 / gap or byte-drop) -> POST-FIX the wire stays monotonic + byte-exact + the session stays live; PLUS attach_survives_target_brain_restart_exactly_once green (doyle runs it 20x isolated single-threaded timeout-wrapped on Linux/kitsubito — the deterministic RED-on-revert carrier). Full seam sweep (attach/broker/resume/brain_swap/inject_control_wedge — the shared W1 controller-writer model). clippy/traceable/docs-drift."

# ── P1c follow-up SEED (doyle proposed, todlando gated, doyle concurred 2026-06-20): the structural per-connection-floor guard — inactive, activate-don't-pre-fail ──


(3) Brain::attach resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map) so an explicit re-attach honors its floor. unit = epoch-gated controller_writer:

(3) Brain::subscribe_with resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map), shared by attach/attach_as — the attach_as(0) re-subscribe re-delivers seq K to the operator viewport (the kitsubito operator-stream boundary fix; reset moved out of attach() into subscribe_with). unit = epoch-gated controller_writer:


title = "Two `controller_writer` threads must never race ONE brain↔broker connection's socket. ROOT (doyle, instrumented RACEDIAG repro on kitsubito): on a brain-restart re-serve the handoff brain registers as controller on the SAME session TWICE over the SAME `Brain::conn` socket — (1) `Brain::handoff` eagerly `subscribe(prior.session_id, prior.next_seq=1)` → `become_controller(from_seq=1)`, initial=[1], spawns writer-A (writes seq 1); (2) `serve_attach` re-handles the replayed `Request{from_seq:0}` → `attach_as(sid,0)` → `become_controller(from_seq=0)`, initial=[0,1], spawns writer-B (writes 0 then 1). `become_controller` (broker.rs) drops the prior `ControllerSink` (its `tx`) but does NOT stop the prior writer thread — writer-A keeps flushing its owned `initial` batch, and both writers hold clones of the same `SharedSend` (`Arc<Mutex<socket>>`) with NO inter-thread ordering. When writer-A's seq 1 wins the socket before writer-B's seq 0, the strict legacy consumer (brain.rs read_event reject-gap path) sees `output gap: got seq 1 want 0` → the test `attach_survives_target_brain_restart_exactly_once` panics at `.expect(\"re-serve\")` OR HANGS in `render_until` (serve thread died on the gap → MARKER_TWO never reaches the wire). `prior.next_seq` is life1's CONSUMPTION cursor, NOT life2's connection state — life2's socket has been sent NOTHING, so a `from_seq=0` full replay on a connection that already streamed seq 1 is contradictory. Snap-above tolerance ALONE can't fix it (it would dedup-drop the late seq 0 → byte loss → the exactly-once byte-identity assert fails). PRE-EXISTING, surfaced by the v0.13.0 green-both-runners release gate; P1b is INNOCENT (its diff touches only input-ack machinery, proven mechanically + the test passes post-P1b in isolation). Sibling flaky cluster: `inject_control_wedge::g2`, `broker::spawn_env_reaches_child`. INVARIANT: on a single brain↔broker connection the controller output-frame stream is monotonic non-decreasing in seq (modulo dedup re-sends); exactly ONE `controller_writer` is ever live per connection; a SUPERSEDED writer writes NO further frames; a re-serve never replays a seq below what the connection already received. FIX (doyle design, corrected at the gate 2026-06-20): fix #1 as designed ('drop handoff's eager subscribe so serve_attach's attach_as is the sole registration') was REVERTED — handoff's `subscribe(prior.next_seq)` IS the standalone-resume mechanism (the brain-only update engine `apply_brain_only` + the `handoff`/`idempotent`/`daemon_e2e` int tests replay output through it with NO `serve_attach`; dropping it hung every resume-via-handoff test). The shipped fix is three parts: (1) CORRECTNESS — `Brain::handoff` seeds `session_cursors` at `prior.next_seq` so the consumer runs the production dedup-below+snap-above path, never the strict reject-gap legacy trap; this is COMPLETE (not merely tolerant) because every `controller_writer` emits an ASCENDING seq stream and the surviving writer (serve_attach's attach_as(sid,0)) offers the complete `[0,end]` range, so a snap-above merge of ascending writers delivers `[K,end]` with no skip/dup (first sighting of any seq>M is preceded by M on that writer). (2) INVARIANT — `controller_writer`'s INITIAL-BATCH replay is epoch-gated: `controller_epoch` is a shared `Arc<AtomicU64>`, the writer re-reads it UNDER `send.lock()` (atomically with `write_frame`) and returns the instant it is superseded — no check-then-block-then-write window, no superseded replay (W1-safe: never blocks the drain under `Mutex<OutputLog>`). The LIVE loop is NOT gated (new output only flows to the current controller; a superseded writer must still deliver its terminal `Displaced` kick — gating it suppressed the loud-take notice; it ends on `tx`-drop). (3) EXPLICIT-RESUME / OPERATOR-STREAM BOUNDARY (the LOAD-BEARING fix — kitsubito RACEDIAG ~33% repro the keystones missed) — `Brain::subscribe_with` (shared by attach/attach_as) resets the resume-mode dedup cursor to `from_seq`. The handoff eager subscribe makes serve_attach's brain receive the replay's seq K BEFORE the operator Request is processed (`attached`=false); that frame is dropped by the if-attached forward gate but the snap-above cursor already advanced past K, and `attach_as(sid,0)`'s re-subscribe used to leave the cursor advanced → the broker's re-send of seq K arrives below it, deduped, never forwarded → operator viewport forward-gap (silent content loss in the real rc consumer). Resetting to from_seq on the attach_as re-subscribe re-delivers from 0 (operator dedups the overlap) so seq K reaches the viewport. The epoch gate (2) is sound (RACEDIAG: zero socket interleaving above K); cold-start brains (empty map — production dispatch serve) keep the legacy next_seq path, so production is unaffected. (v0.13.0)"

-required_stages = ["doc", "impl", "unit", "int"]  # ACTIVATED v0.13.0 P1c (todlando, the last v0.13.0 ship-blocker — pre-existing flaky resume race that gates green-both-runners; doyle root-caused + designed, doyle gates). doc = KNOWN-HAZARDS entry (the reorder + the single-live-writer-per-connection invariant + the two compounding defects) + CONTEXT note. impl = (1) Brain::handoff KEEPS its eager subscribe(prior.session_id, prior.next_seq) [fix #1 REVERTED — load-bearing resume] AND seeds session_cursors.insert(prior.session_id, prior.next_seq); (2) OutputLog.controller_epoch -> Arc<AtomicU64>, become_controller passes the new epoch + Arc::clone into controller_writer, whose INITIAL-BATCH loop returns when controller_epoch != its snapshot (read UNDER send.lock(), atomically with write_frame) — the live recv loop is NOT gated (delivers a superseded controller's terminal Displaced, ends on tx-drop), become_controller/mark_controller_gone/the ControllerJob epoch read switch to atomic load/fetch_add; (3) Brain::attach resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map) so an explicit re-attach honors its floor. unit = epoch-gated controller_writer: a superseded writer (epoch bumped) writes NOTHING from its initial batch (real broker socket, two become_controller on one connection -> only the latest writer's monotonic stream reaches the wire) + handoff seeds session_cursors (session_cursor(sid) == prior.next_seq) + resubscribes for resume. int = the keystone: deterministically force two become_controller-on-one-connection (handoff-then-reserve ordering) on a real broker+brain, NO mocks -> PRE-FIX the wire reorders (got seq 1 want 0 / gap or byte-drop) -> POST-FIX the wire stays monotonic + byte-exact + the session stays live; PLUS attach_survives_target_brain_restart_exactly_once green (doyle runs it 20x isolated single-threaded timeout-wrapped on Linux/kitsubito — the deterministic RED-on-revert carrier). Full seam sweep (attach/broker/resume/brain_swap/inject_control_wedge — the shared W1 controller-writer model). clippy/traceable/docs-drift."

+required_stages = ["doc", "impl", "unit", "int"]  # ACTIVATED v0.13.0 P1c (todlando, the last v0.13.0 ship-blocker — pre-existing flaky resume race that gates green-both-runners; doyle root-caused + designed, doyle gates). doc = KNOWN-HAZARDS entry (the reorder + the single-live-writer-per-connection invariant + the two compounding defects) + CONTEXT note. impl = (1) Brain::handoff KEEPS its eager subscribe(prior.session_id, prior.next_seq) [fix #1 REVERTED — load-bearing resume] AND seeds session_cursors.insert(prior.session_id, prior.next_seq); (2) OutputLog.controller_epoch -> Arc<AtomicU64>, become_controller passes the new epoch + Arc::clone into controller_writer, whose INITIAL-BATCH loop returns when controller_epoch != its snapshot (read UNDER send.lock(), atomically with write_frame) — the live recv loop is NOT gated (delivers a superseded controller's terminal Displaced, ends on tx-drop), become_controller/mark_controller_gone/the ControllerJob epoch read switch to atomic load/fetch_add; (3) Brain::subscribe_with resets session_cursors.insert(session_id, from_seq) when in resume mode (non-empty map), shared by attach/attach_as — the attach_as(0) re-subscribe re-delivers seq K to the operator viewport (the kitsubito operator-stream boundary fix; reset moved out of attach() into subscribe_with). unit = epoch-gated controller_writer: a superseded writer (epoch bumped) writes NOTHING from its initial batch (real broker socket, two become_controller on one connection -> only the latest writer's monotonic stream reaches the wire) + handoff seeds session_cursors (session_cursor(sid) == prior.next_seq) + resubscribes for resume. int = the keystone: deterministically force two become_controller-on-one-connection (handoff-then-reserve ordering) on a real broker+brain, NO mocks -> PRE-FIX the wire reorders (got seq 1 want 0 / gap or byte-drop) -> POST-FIX the wire stays monotonic + byte-exact + the session stays live; PLUS attach_survives_target_brain_restart_exactly_once green (doyle runs it 20x isolated single-threaded timeout-wrapped on Linux/kitsubito — the deterministic RED-on-revert carrier). Full seam sweep (attach/broker/resume/brain_swap/inject_control_wedge — the shared W1 controller-writer model). clippy/traceable/docs-drift."


Verify traceable + docs-drift clean after doc edits, then commit:


Bash

cd C:/Users/decid/Documents/projects/spt-core && traceable-reqs check >/dev/null 2>&1; echo "traceable=$?"; cargo run -p xtask -- gen >/dev/null 2>&1 && (git status --short | grep -q "reference.md" && echo "DRIFT" || echo "no docs drift"); echo "=== change set ===" && git status --short

Verify gates and review change set


traceable=0
no docs drift
=== change set ===
 M crates/spt-daemon/src/brain.rs
 M docs/KNOWN-HAZARDS.md
 M traceable-reqs.toml


Clean minimal change set (brain.rs fix + 2 doc files), gates green. Committing the fix on the real branch + pushing for doyle's 20× kitsubito gate:


cd C:/Users/decid/Documents/projects/spt-core && git add crates/spt-daemon/src/brain.rs docs/KNOWN-HAZARDS.md traceable-reqs.toml && git commit -q -F - <<'EOF'
fix(brain): P1c operator-stream boundary — reset resume dedup cursor on re-subscribe (REQ-HAZARD-CONTROLLER-WRITER-REORDER)

Closes the residual the kitsubito RACEDIAG pinned (~33% carrier fail isolated;
the epoch gate was sound — zero socket interleaving above K). ROOT (consumer-
side): handoff's eager subscribe(K) makes serve_attach's brain receive the
replay frame at seq=K BEFORE the operator Request is processed (attached=false);
that frame is dropped by the `if attached` forward gate, but the snap-above
cursor already advanced past K. attach_as(sid,0)'s re-subscribe then left 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 -> `no forward gap` panic
(render_until), and SILENT content loss in the real rc consumer.

FIX: move the resume-mode dedup-cursor reset out of Brain::attach into
Brain::subscribe_with, so BOTH attach AND attach_as reset session_cursors to
from_seq on a re-subscribe. The attach_as(0) re-subscribe now re-delivers from 0
(the operator's render cursor dedups the [0,K) overlap), so seq K is forwarded
and the viewport stays gapless. Gated to resume mode (non-empty map); cold-start
brains (the production dispatch serve brain) keep the legacy next_seq path, so
production is unaffected.

Windows sweep green (carrier+cv-matrix 14/14, brain_swap/handoff/idempotent,
broker 8/8, lib 349/0, clippy/traceable/docs-drift); the carrier is benign on
Windows so the 33% is doyle's 20x kitsubito gate.

Co-authored by: todlando
EOF
git log --oneline -2 && git push 2>&1 | tail -3

Commit and push the operator-stream boundary fix


0dc7018 fix(brain): P1c operator-stream boundary — reset resume dedup cursor on re-subscribe (REQ-HAZARD-CONTROLLER-WRITER-REORDER)
9b0025b fix(broker): controller-writer reorder on brain-restart re-serve (REQ-HAZARD-CONTROLLER-WRITER-REORDER)
To https://github.com/SaberMage/spt-core.git
   9b0025b..0dc7018  v0.13.0-p1b-ack-deadlock -> v0.13.0-p1b-ack-deadlock


Pushed @0dc7018. Let me also put the fix on the diag branch so doyle can run the *instrumented* fix for positive trace confirmation (seq K now forwarded), not just "20× green":


cd C:/Users/decid/Documents/projects/spt-core && git checkout v0.13.0-p1c-reorder-diag 2>&1 | tail -1 && git cherry-pick 0dc7018 2>&1 | tail -4 && git log --oneline -3 && git push 2>&1 | tail -2 && git checkout v0.13.0-p1b-ack-deadlock 2>&1 | tail -1

Cherry-pick the fix onto the diag branch and push


Switched to branch 'v0.13.0-p1c-reorder-diag'
[v0.13.0-p1c-reorder-diag 9efc4e4] fix(brain): P1c operator-stream boundary — reset resume dedup cursor on re-subscribe (REQ-HAZARD-CONTROLLER-WRITER-REORDER)
 Date: Sat Jun 20 18:29:01 2026 -0700
 3 files changed, 27 insertions(+), 18 deletions(-)
9efc4e4 fix(brain): P1c operator-stream boundary — reset resume dedup cursor on re-subscribe (REQ-HAZARD-CONTROLLER-WRITER-REORDER)
f5eef48 diag(broker,attach): env-gated RACEDIAG for the P1c operator-stream reorder (THROWAWAY)
9b0025b fix(broker): controller-writer reorder on brain-restart re-serve (REQ-HAZARD-CONTROLLER-WRITER-REORDER)
To https://github.com/SaberMage/spt-core.git
   f5eef48..9efc4e4  v0.13.0-p1c-reorder-diag -> v0.13.0-p1c-reorder-diag
Switched to branch 'v0.13.0-p1b-ack-deadlock'


Both pushed: clean fix @0dc7018 (real branch), instrumented fix @9efc4e4 (diag branch). Handing the gate to doyle:


"$OWL" send doyle todlando <<'EOF'
FIX PUSHED — root confirmed by your RACEDIAG (consumer-side operator-stream boundary, NOT the socket; epoch gate is sound).

ROOT (your trace, restated): handoff's eager subscribe(K) makes serve_attach's brain CONSUME the replay's seq K BEFORE the operator Request is processed (attached=false). That early frame is dropped by the `if attached` forward gate, but life2's snap-above cursor already advanced past K. Then attach_as(sid,0)'s re-subscribe left the cursor advanced → the broker's re-send of seq K arrives below it → deduped → seq K never forwarded → operator forward-gap (and SILENT rc content loss).

FIX (your direction #2, consolidated): moved the resume-mode dedup-cursor reset OUT of Brain::attach INTO Brain::subscribe_with, so BOTH attach AND attach_as reset session_cursors[sid]=from_seq on a re-subscribe. attach_as(0) now re-delivers from 0 (operator's render cursor dedups the [0,K) overlap) → seq K forwarded → gapless.
PRODUCTION-SAFE: gated `if !session_cursors.is_empty()` (resume mode). I checked the prod serve path — dispatch.rs:299/350 passes a fresh connect()/cold_start brain (empty map) → the reset NEVER fires in production; it only arms for the test's resume-mode life2. Zero prod behavior change. (Kept handoff's subscribe — no fix#1, no 4-caller churn.)

BRANCHES:
- CLEAN FIX: v0.13.0-p1b-ack-deadlock @0dc7018 (on your 9b0025b). Run your 20x carrier here.
- INSTRUMENTED FIX: v0.13.0-p1c-reorder-diag @9efc4e4 (fix + RACEDIAG). Run with SPT_REORDER_DIAG=1 for POSITIVE confirmation — you should now see "serve forward Output seq=1 -> operator" (seq K=1 forwarded) and NO "<<< FORWARD GAP", even in the previously-failing timing.

WINDOWS (benign, can't repro the 33%): full sweep green @0dc7018 — attach 14/14 (carrier+cv-matrix), brain_swap/handoff/idempotent, broker 8/8, lib 349/0, clippy=0, traceable +doc+impl+unit+int EXIT=0, docs-drift clean. Docs/KH 7.21/REQ updated to the operator-stream-boundary root + the subscribe_with fix.

NOTE: the keystones missed this because it's the early-consume TIMING on stream_b, not the socket — the carrier is the load-bearing oracle (your 20x). If you want a deterministic regression guard for the boundary, it needs timing injection (force the pre-attached consume) — I can attempt it if you want it in-scope. Your call: 20x @0dc7018; verdict to follow. Reachable.
Co-authored by: todlando
EOF

Hand the operator-stream boundary fix to doyle for the 20x gate


➜ SENT:doyle


Fix pushed, handed to doyle. Standing by for his 20× kitsubito verdict.

## Status

**P1c — second gate round, root pinned + fixed.**

doyle's kitsubito RACEDIAG proved the epoch gate is **sound** (zero socket interleaving above K) — the residual was a **consumer-side operator-stream boundary** bug: handoff's eager subscribe makes serve_attach consume the replay's seq K *before* `attached=true`; the early frame is dropped by the `if attached` gate but the snap-above cursor advances past K, then `attach_as(0)`'s re-subscribe left the cursor advanced → seq K deduped → operator forward-gap (silent rc content loss).

**Fix (doyle's direction #2, consolidated):** moved the resume-mode dedup-cursor reset from `Brain::attach` into `Brain::subscribe_with`, so `attach_as` also resets to `from_seq` on re-subscribe → re-delivers seq K → gapless. **Production-safe** (verified: prod serve brain is cold_start/empty-map → reset never fires there).

**Pushed:**
- Clean fix @0dc7018 (real branch) — for doyle's 20× gate.
- Instrumented fix @9efc4e4 (diag branch) — for positive trace confirmation (seq K now forwarded, no gap).

**Windows sweep green** @0dc7018 (attach 14/14, standalone callers, broker 8/8, lib 349/0, clippy/traceable/docs-drift); docs/KH/REQ updated. Carrier benign on Windows → the 33%→0 verification is doyle's kitsubito run.

Holding the working tree, reachable for doyle's verdict.


<task-notification>
<task-id>b4cwwiglf</task-id>
Monitor event: "« spt event »"
<event><EVENT-PART seq="1/7" id="001ef904" type="msg" from="doyle">P1c GATE-PASS — the fix is verified end-to-end. Confirmed on kitsubito + locally:
- 20x carrier @0dc7018 (clean fix, no instrumentation): 20 PASS / 0 FAIL / 0 HANG (was 8-11/20). From a 33%-fail baseline, 20/20 is conclusive (~0.0003 fluke odds).
- Instrumented @9efc4e4 positive confirm: the trace now shows &quo</EVENT-PART>
<EVENT-PART seq="2/7" id="001ef904">t;serve forward Output seq=0&quot; + &quot;serve forward Output seq=1&quot; (seq K=1 forwarded), operator recv 0(dedup)/1/2 with NO FORWARD GAP, across 8/8 runs. Mechanism positively proven, not just absence-of-failure.
- Fix delta read + PROD-SAFETY VERIFIED myself: the reset moved into subscribe_with gated `if !session_cursors.is_empty()`</EVENT-PART>
<EVENT-PART seq="3/7" id="001ef904">; dispatch.rs:239 + attach.rs:135 prove the prod serve brain is Brain::cold_start (empty map) → reset NEVER fires in prod serve; resume_sessions (seeded) resets to resume_seq = correct, distinct brain. resume.rs 3/3 green confirms no prod-resume regression. brain_swap/handoff/idempotent 1/1 each (standalone-resume canaries intact). clippy=0,</EVENT-PART>
<EVENT-PART seq="4/7" id="001ef904"> traceable EXIT=0, keystones green.

Clean engineering — 3 rounds of bugs all caught at the gate, none shipped. The subscribe_with consolidation is the right shape.

ONE REQUEST (I'd like it before we fold, but it's TEST-ONLY so it doesn't gate the binary): the deterministic timing-injected regression guard you offered. Reason it</EVENT-PART>
<EVENT-PART seq="5/7" id="001ef904">'s in-scope, not nice-to-have: the carrier catches a revert only ~33% per CI run → carrier-as-guard is FLAKY (reintroduces the exact flaky-cluster we just killed). A REQ-HAZARD wants un-reintroducible = a test that goes DETERMINISTICALLY RED on revert. Please attempt the timing-injection (force the pre-attached consume of seq K, e.g. a test </EVENT-PART>
<EVENT-PART seq="6/7" id="001ef904">seam that delays the serve attach past the handoff replay) so a future revert of the subscribe_with reset flips it red every run. If it proves genuinely fragile/flaky itself, STOP + tell me — we ship on the proven fix + document the carrier as the empirical guard (the int stage is already covered by the carrier + keystones). Send it when you</EVENT-PART>
<EVENT-PART seq="7/7" id="001ef904"> have a read.

I'm folding 0dc7018 to PR #26 + deleting the throwaway diag branch now. Then PR #26 green-both-runners -&gt; deployah cuts v0.13.0.

Co-authored by: doyle</EVENT-PART></event>
</task-notification>


<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging. Fragments OK. Code/commits/security: write normal.


**P1c GATE-PASS!** 🎉 doyle verified: 20/20 carrier on kitsubito (from 33% baseline), positive instrumented confirm (seq K forwarded, no gap, 8/8), prod-safety verified, all sweeps green. 3 rounds of bugs, none shipped. He's folding @0dc7018 to PR #26 + cutting v0.13.0.

His one request (test-only, non-gating): a **deterministic** timing-injected regression guard, because the carrier catches a revert only ~33% (flaky-as-guard reintroduces the cluster we killed). A REQ-HAZARD wants un-reintroducible = RED-every-run on revert.

This is achievable deterministically: force the pre-attached consume *explicitly* (read seq K on the handoff brain before the re-subscribe — no race), then assert re-delivery after `attach_as(0)`. Let me ACK + model it on the simplest existing handoff+read test:


"$OWL" send doyle todlando <<'EOF'
GATE-PASS received — 20/20 from a 33% baseline + the positive instrumented trace (seq K forwarded) is conclusive. Thanks for the rigorous gate; 3 rounds caught clean is the process working. Fold + cut away.

On the deterministic guard: AGREED it's in-scope, not nice-to-have — a flaky carrier-as-guard re-seeds the exact cluster we killed. It IS achievable deterministically: I force the pre-attached consume EXPLICITLY (a focused int that READS seq K on the handoff brain before the attach_as(0) re-subscribe — no timing race), then asserts seq K is RE-DELIVERED after the re-subscribe. Revert of the subscribe_with reset → seq K stays deduped → RED every run.

Attempting now. It's test-only so it rides AFTER your fold — I'll commit it on v0.13.0-p1b-ack-deadlock @0dc7018 as a follow-up and ping you to fold that one commit too (or land it on PR #26 directly, your call). If the timing-injection proves genuinely fragile/flaky itself, I STOP + tell you and we document the carrier+keystones as the empirical int guard. Read incoming.
Co-authored by: todlando
EOF

ACK gate-pass + commit to the deterministic guard