@crouton-kit/crouter 0.3.21 → 0.3.22

package/dist/core/__tests__/{broker-attach-limits.test.js → full/broker-attach-limits.test.js}

@@ -1,30 +1,61 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-limits.test.ts
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-attach-limits.test.ts
+//
+// FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
+// (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
 //
 // T8 — the `crtr attach` acceptance gate, gates G4/G7/G8/G9 (controller
 // arbitration, decoder overflow caps, backpressure shedding, and the load-bearing
-// ONE-WRITER proof). Split out of broker-lifecycle.test.ts (see its header for
-// the full file map); the tests are the original acceptance gate, unchanged, on
-// their own isolated harness. Each test drives the REAL detached broker process +
-// REAL view.sock with the enriched fake engine, using the PRODUCTION
-// ViewSocketClient (helpers/broker-clients.ts) as the controller/observer — raw
-// node:net only where the client lifecycle is awkward (G7 oversized line, G8
-// stalled viewer). The engine is hosted IN-PROCESS by the broker, so engine pid
-// == broker pid == node.pi_pid == boot.pid.
+// ONE-WRITER proof). Split out of broker-lifecycle.test.ts; the gates are the
+// original acceptance gate, unchanged.
+//
+// 3-PART HEADER (headless-retarget):
+//  (1) BUG IT LOCKS — the broker's client arbitration + resource caps + one-writer
+//      invariant: a 2nd client is an admitted read-only observer and an observer
+//      prompt is rejected not_controller while BOTH clients still receive the relay
+//      (G4); an oversized client line is cap-and-dropped (frame_overflow) without
+//      OOMing the broker (G7); a stalled non-reading viewer is shed at the 32 MiB
+//      backpressure HWM while the broker + fast viewers are unaffected (G8); and
+//      across attach→detach→reattach the broker/engine pid is STABLE with no second
+//      engine ever spawned and the viewer holding ONLY the socket, never the
+//      session .jsonl (G9). Regression = two controllers / an observer driving the
+//      engine / an unbounded decoder or per-viewer queue (broker OOM) / a viewer
+//      that forks a second writer onto the same .jsonl — the corruption headless
+//      one-writer exists to prevent.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — arbitration, the bounded decoder,
+//      the backpressure HWM, and one-writer all live in the broker PROCESS and its
+//      view.sock codec. They are exercised over a pure unix socket (the production
+//      ViewSocketClient + raw node:net peers), with the engine hosted IN-PROCESS by
+//      the broker, so engine pid == broker pid == node.pi_pid == boot.pid. No tmux
+//      pane/window is involved, so the lock holds headlessly (createHeadlessHarness,
+//      no tmux). It needs a REAL broker process (not model state), so this file
+//      keeps ONE real boot, shared across all four gates.
+//  (3) HOW THE HEADLESS DRIVE STILL FAILS ON REGRESSION — each gate drives the real
+//      broker over the real socket and asserts on its observable response: the
+//      welcome role + relay frames (G4), the broker's frame-overflow drop + pid
+//      survival (G7), the broker's HWM-shed log line + pid survival (G8), and pid /
+//      bootCount stability + the .jsonl holder set (G9). A regressed guard fails
+//      these exactly as it would under tmux; nothing here depended on a pane.
+//
+// ONE shared broker is booted in before() and reused across all four gates — 1 real
+// boot total, not 4. Gates whose first attach must hold control use
+// attachUntil(controller) so a prior gate's controller-detach handoff settles
+// deterministically before they drive.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { join } from 'node:path';
-import { createHarness, hasTmux } from './helpers/harness.js';
-import { isPidAlive } from '../canvas/pid.js';
-import { createAttachKit, delay, tok, frameHas, brokerLogText, lsofHolders, } from './helpers/broker-clients.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas, brokerLogText, lsofHolders, } from '../helpers/broker-clients.js';
 let h;
-let root;
+let id; // ONE shared broker, reused across G4/G7/G8/G9 (1 real boot, not 4)
 const kit = createAttachKit(() => h);
 const { attach, attachUntil, connectRaw } = kit;
+// Admit a controller, waiting out any prior gate's controller-detach handoff.
+const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
 before(async () => {
-    if (!hasTmux())
-        return;
-    h = await createHarness({ sessionPrefix: 'crtr-brklim' });
-    root = h.spawnRoot('broker-attach-limits suite root');
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brklim' });
+    const root = h.spawnRoot('broker-attach-limits suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — attach-limits gates');
 });
 after(async () => {
     if (h !== undefined)
@@ -33,16 +64,15 @@ after(async () => {
 afterEach(() => {
     kit.closeAll();
 });
-const brokerPid = (id) => h.node(id).pi_pid;
+const brokerPid = () => h.node(id).pi_pid;
 // ---------------------------------------------------------------------------
 // G4 — arbitration + observer read. Guards: 2nd client is admitted observer, an
 // observer prompt is rejected not_controller, BOTH clients receive the relay.
 // Failure mode: two controllers, or an observer driving the engine, or fan-out
 // that misses a viewer.
 // ---------------------------------------------------------------------------
-test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G4');
-    const c1 = await attach(id, 'controller', 'g4-ctrl');
+test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', async () => {
+    const c1 = await ctrl('g4-ctrl');
     assert.equal(c1.welcome.role, 'controller', 'first client holds control');
     const c2 = await attach(id, 'controller', 'g4-second'); // requests control; held → observer
     assert.equal(c2.welcome.role, 'observer', 'second client is admitted read-only observer (first-attach-wins)');
@@ -59,9 +89,8 @@ test('G4 — second client is observer; observer prompt → error{not_controller
 // cap-and-dropped; the broker survives and other clients are unaffected. Failure
 // mode: an unbounded decoder buffer growing the broker to OOM.
 // ---------------------------------------------------------------------------
-test('G7 — an oversized client line is dropped (frame_overflow), the broker survives, other clients unaffected', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G7');
-    const pid = brokerPid(id);
+test('G7 — an oversized client line is dropped (frame_overflow), the broker survives, other clients unaffected', async () => {
+    const pid = brokerPid();
     const boots = h.bootCount(id);
     const survivor = await attach(id, 'observer', 'g7-survivor');
     // 26 MiB with NO newline > BROKER_READ_CAPS.maxLineBytes (24 MiB) → the bounded
@@ -75,7 +104,7 @@ test('G7 — an oversized client line is dropped (frame_overflow), the broker su
     h.fakeCmd(id, { cmd: 'stream', text: token });
     await survivor.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G7 survivor still receives live frames');
     assert.equal(isPidAlive(pid), true, 'G7: the broker survived the overflow');
-    assert.equal(brokerPid(id), pid, 'G7: broker pid unchanged');
+    assert.equal(brokerPid(), pid, 'G7: broker pid unchanged');
     assert.equal(h.bootCount(id), boots, 'G7: no reboot');
 });
 // ---------------------------------------------------------------------------
@@ -84,9 +113,8 @@ test('G7 — an oversized client line is dropped (frame_overflow), the broker su
 // Failure mode: an indefinitely-growing per-viewer queue (broker OOM) or a slow
 // viewer back-pressuring the shared engine.
 // ---------------------------------------------------------------------------
-test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + fast viewers are unaffected', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G8');
-    const pid = brokerPid(id);
+test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + fast viewers are unaffected', async () => {
+    const pid = brokerPid();
     const fast = await attach(id, 'observer', 'g8-fast'); // reads normally
     // A helloed viewer that NEVER reads (paused socket). It must be in the broadcast
     // set before the flood; hello, then a short beat for the broker to process it.
@@ -108,7 +136,7 @@ test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + f
     // proving only the stalled viewer was shed, while the fast one was unaffected.
     await fast.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G8 fast viewer received the whole stream', 30_000);
     assert.equal(isPidAlive(pid), true, 'G8: the broker survived the slow-viewer flood');
-    assert.equal(brokerPid(id), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
+    assert.equal(brokerPid(), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
 });
 // ---------------------------------------------------------------------------
 // G9 — the load-bearing ONE-WRITER assertion. Across attach→detach→reattach the
@@ -117,18 +145,17 @@ test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + f
 // Failure mode: a viewer that spawns/forks a second engine or opens the session
 // .jsonl — the corruption the headless design exists to prevent.
 // ---------------------------------------------------------------------------
-test('G9 — one-writer: broker/engine pid stable across attach→detach→reattach; no second engine; viewer holds only the socket', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G9');
-    const pid0 = brokerPid(id);
+test('G9 — one-writer: broker/engine pid stable across attach→detach→reattach; no second engine; viewer holds only the socket', async () => {
+    const pid0 = brokerPid();
     const boots0 = h.bootCount(id);
-    const c1 = await attach(id, 'controller', 'g9-a');
+    const c1 = await ctrl('g9-a');
     const a = tok('G9-A');
     c1.send({ type: 'prompt', text: a });
     await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, a), 'G9 first turn relayed');
     c1.send({ type: 'bye' });
     c1.close();
     await delay(300);
-    assert.equal(brokerPid(id), pid0, 'G9: broker/engine pid unchanged after detach');
+    assert.equal(brokerPid(), pid0, 'G9: broker/engine pid unchanged after detach');
     assert.equal(isPidAlive(pid0), true, 'G9: the one engine is still alive after detach');
     assert.equal(h.bootCount(id), boots0, 'G9: no second engine spawned across detach');
     // attachUntil (not a fixed sleep) synchronizes on the controller handoff: the
@@ -139,7 +166,7 @@ test('G9 — one-writer: broker/engine pid stable across attach→detach→reatt
     const b = tok('G9-B');
     c2.send({ type: 'prompt', text: b });
     await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, b), 'G9 reattached controller drives the SAME engine');
-    assert.equal(brokerPid(id), pid0, 'G9: STILL the same broker/engine pid after reattach (one writer, never two)');
+    assert.equal(brokerPid(), pid0, 'G9: STILL the same broker/engine pid after reattach (one writer, never two)');
     assert.equal(isPidAlive(pid0), true, 'G9: the single engine is alive across the full cycle');
     assert.equal(h.bootCount(id), boots0, 'G9: exactly one engine boot across attach→detach→reattach');
     // fd-check (best-effort): the viewer host (this test process) must NOT hold the

package/dist/core/__tests__/{broker-attach-stream.test.js → full/broker-attach-stream.test.js}

@@ -1,29 +1,56 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-stream.test.ts
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-attach-stream.test.ts
+//
+// FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
+// (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
 //
 // T8 — the `crtr attach` acceptance gate, gates G1/G1b/G2/G3 (controller drive,
 // relay/coalescing, detach survival, catch-up snapshot). Split out of
-// broker-lifecycle.test.ts (see its header for the full file map); the tests are
-// the original acceptance gate, unchanged, on their own isolated harness. Each
-// test drives the REAL detached broker process + REAL view.sock with the enriched
-// fake engine, using the PRODUCTION ViewSocketClient (helpers/broker-clients.ts)
-// as the controller/observer. The engine is hosted IN-PROCESS by the broker, so
-// engine pid == broker pid == node.pi_pid == boot.pid; "engine pid unchanged" ==
-// broker pid unchanged + no new boot. Each test's lead comment names its gate #
-// and the failure mode it guards.
+// broker-lifecycle.test.ts; the gates are the original acceptance gate, unchanged.
+//
+// 3-PART HEADER (headless-retarget):
+//  (1) BUG IT LOCKS — the broker's client fan-out: a controller `prompt` must run
+//      the engine and the streamed AgentSessionEvents must relay VERBATIM and IN
+//      ORDER to every viewer (G1); message_update coalescing must flush BEFORE any
+//      other event so a stale update can never land after message_end, and the
+//      last coalesced update must not be dropped (G1b, the F2 typing-lag fix);
+//      detach (bye+close) must drop ONE listener, never the engine (G2); and
+//      messages produced with no viewer attached must be in welcome.snapshot on
+//      reattach (G3). Regression = a viewer that sees nothing / sees stale text /
+//      kills the engine on detach / reattaches blind to history.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — the relay is a pure unix-socket
+//      path: ViewSocketClient ⇄ broker view.sock ⇄ in-process fake engine's
+//      subscribe channel. No tmux pane, window, or pi session read is involved, so
+//      the lock holds headlessly (createHeadlessHarness, no tmux). It needs a REAL
+//      broker PROCESS (not just model state) because it proves the cross-process
+//      frame codec + fan-out + coalescer, which is why this file keeps ONE real
+//      boot — shared across all four gates to stay off the fast-tier long pole.
+//  (3) HOW THE HEADLESS DRIVE STILL FAILS ON REGRESSION — each gate attaches the
+//      PRODUCTION ViewSocketClient over the real socket and asserts on the frames
+//      the real broker relays (order, types, snapshot, pid stability). A broken
+//      relay/coalescer/detach path fails the frame assertions exactly as it would
+//      under tmux; nothing here depended on a pane.
+//
+// The engine is hosted IN-PROCESS by the broker, so engine pid == broker pid ==
+// node.pi_pid == boot.pid; "engine pid unchanged" == broker pid unchanged + no new
+// boot. ONE shared broker is booted in before() and reused across all four gates
+// (each just attaches fresh clients) — 1 real boot total, not 4. A gate whose
+// first attach must hold control uses attachUntil(controller) so the prior gate's
+// controller-detach handoff settles deterministically before it drives.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { createHarness, hasTmux } from './helpers/harness.js';
-import { isPidAlive } from '../canvas/pid.js';
-import { createAttachKit, delay, tok, frameHas } from './helpers/broker-clients.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas } from '../helpers/broker-clients.js';
 let h;
-let root;
+let id; // ONE shared broker, reused across G1/G1b/G2/G3 (1 real boot, not 4)
 const kit = createAttachKit(() => h);
 const { attach, attachUntil } = kit;
+// Admit a controller, waiting out any prior gate's controller-detach handoff.
+const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
 before(async () => {
-    if (!hasTmux())
-        return;
-    h = await createHarness({ sessionPrefix: 'crtr-brkstrm' });
-    root = h.spawnRoot('broker-attach-stream suite root');
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkstrm' });
+    const root = h.spawnRoot('broker-attach-stream suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — attach-stream gates');
 });
 after(async () => {
     if (h !== undefined)
@@ -32,15 +59,14 @@ after(async () => {
 afterEach(() => {
     kit.closeAll();
 });
-const brokerPid = (id) => h.node(id).pi_pid;
+const brokerPid = () => h.node(id).pi_pid;
 // ---------------------------------------------------------------------------
 // G1 — controller drive + live relay. Guards: a controller's `prompt` runs the
 // engine AND the streaming AgentSessionEvents are fanned out to the client
 // VERBATIM. Failure mode: a broken relay/fan-out (viewer sees nothing).
 // ---------------------------------------------------------------------------
-test('G1 — controller prompt runs the engine and the streamed AgentSessionEvents relay to the client', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G1');
-    const c = await attach(id, 'controller', 'g1-ctrl');
+test('G1 — controller prompt runs the engine and the streamed AgentSessionEvents relay to the client', async () => {
+    const c = await ctrl('g1-ctrl');
     assert.equal(c.welcome.role, 'controller', 'first controller is admitted as controller');
     const token = tok('G1-PROMPT');
     c.send({ type: 'prompt', text: token });
@@ -62,9 +88,8 @@ test('G1 — controller prompt runs the engine and the streamed AgentSessionEven
 // be silently dropped at end-of-turn. Failure modes: a flush ordered after the
 // non-update event, or a pending update discarded when message_end wins the race.
 // ---------------------------------------------------------------------------
-test('G1b — coalesced message_update never arrives after message_end; updates still relayed', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G1b');
-    const c = await attach(id, 'controller', 'g1b-ctrl');
+test('G1b — coalesced message_update never arrives after message_end; updates still relayed', async () => {
+    const c = await ctrl('g1b-ctrl');
     const token = tok('G1B');
     // 12 updates at the fake engine's setImmediate pace — far faster than the 75ms
     // coalesce window, so coalescing genuinely engages (fewer relayed than emitted).
@@ -86,11 +111,10 @@ test('G1b — coalesced message_update never arrives after message_end; updates
 // G2 — detach leaves the engine running. Guards: `bye`/close drops ONE listener,
 // never the engine. Failure mode: a detach that disposes the broker/engine.
 // ---------------------------------------------------------------------------
-test('G2 — detach (bye+close) leaves the broker alive + the engine still emitting; engine pid unchanged', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G2');
-    const pid = brokerPid(id);
+test('G2 — detach (bye+close) leaves the broker alive + the engine still emitting; engine pid unchanged', async () => {
+    const pid = brokerPid();
     const boots = h.bootCount(id);
-    const c = await attach(id, 'controller', 'g2-ctrl');
+    const c = await ctrl('g2-ctrl');
     const p = tok('G2-PROMPT');
     c.send({ type: 'prompt', text: p });
     await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, p), 'G2 turn relayed before detach');
@@ -98,7 +122,7 @@ test('G2 — detach (bye+close) leaves the broker alive + the engine still emitt
     c.close();
     await delay(300); // let the broker process the 'close'
     assert.equal(isPidAlive(pid), true, 'G2: broker still alive after detach');
-    assert.equal(brokerPid(id), pid, 'G2: engine (== broker) pid UNCHANGED across detach');
+    assert.equal(brokerPid(), pid, 'G2: engine (== broker) pid UNCHANGED across detach');
     assert.equal(h.bootCount(id), boots, 'G2: no reboot — no second engine spawned');
     // Still emitting: drive a turn with no client, then a fresh observer's snapshot
     // carries it (the engine kept running and processing after the detach).
@@ -113,8 +137,7 @@ test('G2 — detach (bye+close) leaves the broker alive + the engine still emitt
 // in welcome.snapshot on reattach, and live events resume. Failure mode: a viewer
 // that reattaches blind to history / gets no further events.
 // ---------------------------------------------------------------------------
-test('G3 — messages produced while detached appear in welcome.snapshot on reattach; live events resume', { skip: !hasTmux() }, async () => {
-    const id = await h.spawnHeadlessChild(root, 'headless worker — G3');
+test('G3 — messages produced while detached appear in welcome.snapshot on reattach; live events resume', async () => {
     const past = tok('G3-DETACHED');
     h.fakeCmd(id, { cmd: 'stream', text: past }); // produced with zero viewers attached
     const o = await attachUntil(id, 'observer', 'g3-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(past), 'G3 detached message in snapshot');

package/dist/core/__tests__/full/broker-crash-teardown.test.js

@@ -0,0 +1,143 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-crash-teardown.test.ts
+//
+// HEADLESS RETARGET (foundation-spec §C.3 + §E). Broker crash / teardown / boot-
+// failure — acceptance items 4–6 of the headless-broker migration plus the
+// M-1/M-2 boot-failure regression — tmux-free (no hasTmux() gate). FULL TIER: the
+// crash + teardown items genuinely exercise a real broker PROCESS so they share
+// ONE spawn + ONE grace-revive (2 boots, ~5s each), which is why the file lives
+// in full/ (CI), not the fast local loop. (The boot-failure lock is PURE daemon
+// logic, fabricated with ZERO boots.)
+//
+// (1) BUG LOCKED — two locks:
+//     • items 4–6: a CRASHED broker (pid killed out from under the daemon) must
+//       grace-revive RESUMING the saved .jsonl, ONE-WRITER (the crashed pid is
+//       dead BEFORE the revive launches and never resurrects; the revived pid is
+//       distinct); and a clean `node close` tears the broker down (shutdown frame
+//       → exit, socket unlinked, status canceled, daemon leaves it).
+//     • M-1/M-2: a broker that DIES before session_start records NO pid and NO
+//       session EVER. Read pid==null unconditionally as "still booting" and the
+//       node strands 'active' with no engine FOREVER and its parent waits on a
+//       dead child. The daemon must instead, after REVIVE_GRACE_MS with still no
+//       pid AND no session, crash it (→ dead) and surface a boot-failure push up
+//       the spine (handleBrokerLiveness, crtrd.ts).
+//
+// (2) WHY MODEL-LEVEL vs A REAL BOOT — the M-1/M-2 grace-surface is pure daemon
+//     logic: pid==null && pi_session_id==null past the boot grace → transition
+//     ('crash') + surfaceBootFailure → pushUrgent fanned to the active parent.
+//     A broker is supervised purely by its row (pi_pid/pi_session_id), so this is
+//     fabricated DIRECTLY — a parent-subscribed broker row with NO pid and NO
+//     session, ticked across the grace boundary — with ZERO real boots and no
+//     crashing subprocess at all. The crash/teardown items, by contrast, ARE the
+//     broker process under test (a real pid to kill, a real socket to unlink), so
+//     they pay one real spawn + the grace-revive boot.
+//
+// (3) HOW THE HEADLESS DRIVE STILL FAILS IF THE BUG REGRESSES — for crash/teardown,
+//     an early revive (no grace) would land a second writer in the respawn gap, or
+//     a broken teardown would leave the socket / pid alive — the one-writer / socket
+//     / canceled asserts go RED. For M-1/M-2, remove the grace-surface branch (read
+//     pid==null as "still booting" forever) and the fabricated node NEVER goes
+//     'dead' and the parent NEVER receives the notice → the boot-failure asserts go
+//     RED. Verified by reverting that branch (see bug-injection report).
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { createHarness } from '../helpers/harness.js';
+import { subscribe } from '../../canvas/canvas.js';
+import { isPidAlive } from '../../canvas/pid.js';
+// crtrd.ts module const (not exported): the fresh-pi-boot grace window the daemon
+// waits before grace-reviving / boot-failing a pi observed dead. Reference:
+// crtrd.ts `REVIVE_GRACE_MS = 20_000`.
+const REVIVE_GRACE_MS = 20_000;
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-brkcrash' });
+    root = h.spawnRoot('broker-crash suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// ===========================================================================
+// Items 4 + 5 + 6 — one real broker lifecycle, ONE spawn + ONE grace-revive:
+//   crash → grace-revive RESUME (one-writer) → close → clean teardown.
+// ===========================================================================
+test('CRASH → grace-revive RESUME (one-writer), then clean teardown on close', async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — crash+teardown');
+    const oldPid = h.node(id).pi_pid;
+    assert.equal(isPidAlive(oldPid), true, 'broker alive before the crash');
+    assert.equal(h.node(id).intent ?? null, null, 'fresh broker has a null intent (not refresh/idle-release)');
+    const boots = h.bootCount(id);
+    // --- Items 4 + 6: kill the broker out from under the daemon (a crash). Drive a
+    //     FIXED clock so the grace window is exercised deterministically. ---
+    process.kill(oldPid, 'SIGKILL');
+    await h.waitFor(() => !isPidAlive(oldPid), { label: 'crashed broker pid is dead' });
+    // ONE-WRITER: the old engine pid is dead BEFORE any revive can launch.
+    assert.equal(isPidAlive(oldPid), false, 'crashed pid dead before the daemon revives');
+    const NOW = 5_000_000;
+    await h.tick(NOW); // pid dead, intent null → handleBrokerLiveness → handleLiveWindow marks pending
+    assert.equal(h.bootCount(id), boots, 'inside the grace window → NOT yet revived');
+    await h.tick(NOW + REVIVE_GRACE_MS + 1); // grace elapsed → reviveNode(resume:true)
+    const boot2 = await h.awaitBoot(id, { minCount: boots + 1 });
+    assert.equal(boot2.resuming, true, 'grace-revive RESUMES the saved .jsonl');
+    const newPid = h.node(id).pi_pid;
+    assert.ok(newPid != null && isPidAlive(newPid), 'the revived broker pid is alive');
+    assert.notEqual(newPid, oldPid, 'the revived pid is distinct from the crashed one');
+    assert.equal(isPidAlive(oldPid), false, 'one-writer: the crashed pid never resurrected');
+    // --- Item 5: clean teardown of the (revived, live) broker. node close marks
+    //     canceled BEFORE teardown (crash-safe order), then hostFor(broker).teardown
+    //     sends the `shutdown` frame → the broker disposes + exits, socket unlinked. ---
+    const sock = h.brokerSock(id);
+    await h.waitFor(() => existsSync(sock), { label: 'revived broker created its view.sock' });
+    const res = h.cli(root, ['node', 'close', '--node', id]);
+    assert.equal(res.code, 0, `node close should exit 0\n--stderr--\n${res.stderr}`);
+    await h.waitFor(() => !isPidAlive(newPid), { label: 'broker process exited on shutdown frame' });
+    await h.waitFor(() => !existsSync(sock), { label: 'broker unlinked its socket on exit' });
+    assert.equal(h.status(id), 'canceled', 'the closed node is canceled');
+    // listNodes only surfaces active|idle, so a canceled broker is never supervised.
+    await h.tick();
+    assert.equal(h.status(id), 'canceled', 'still canceled after a daemon tick');
+    assert.equal(isPidAlive(newPid), false, 'the broker stays dead — never revived');
+});
+// ===========================================================================
+// M-1 / M-2 — a broker that DIES before session_start (NO pid, NO session EVER)
+// must be grace-surfaced as a boot failure, not stranded 'active' forever.
+// PURE MODEL DRIVE: fabricate the exact strand state directly + a parent
+// subscription, tick across the boot grace, assert crash + the up-spine push.
+// ZERO real boots — no crashing subprocess needed.
+// ===========================================================================
+test('boot failure — a broker that never records a pid/session is grace-surfaced, not stranded (review M-1/M-2)', async () => {
+    // The exact "never booted" strand: status=active, NO pid, NO session ever
+    // (pi_session_id null routes the boot-failure branch, NOT relaunch-in-flight).
+    const id = h.fabricateBrokerNode({
+        parent: root,
+        status: 'active',
+        intent: null,
+        pi_pid: null,
+        pi_session_id: null,
+    });
+    // The parent is an ACTIVE subscriber of the child (what spawn auto-wires), so
+    // surfaceBootFailure's pushUrgent reaches it on its inbox.
+    subscribe(root, id, true);
+    {
+        const n0 = h.node(id);
+        assert.equal(n0.host_kind, 'broker', 'broker-hosted (paneless)');
+        assert.equal(n0.pi_pid ?? null, null, 'no broker pid was ever recorded');
+        assert.equal(n0.pi_session_id ?? null, null, 'no session was ever recorded');
+        assert.equal(n0.status, 'active', 'starts stranded active');
+    }
+    // Inside the boot grace the daemon LEAVES it (could be the sub-second boot gap):
+    // tick 1 starts the boot-grace clock, tick 2 still within grace.
+    const NOW = 9_000_000;
+    await h.tick(NOW);
+    assert.equal(h.status(id), 'active', 'first observation → boot-grace clock started, left active');
+    await h.tick(NOW + 10_000);
+    assert.equal(h.status(id), 'active', 'inside the boot grace → daemon leaves it (boot gap)');
+    // Past the boot grace with STILL no pid and no session → crash + boot failure.
+    await h.tick(NOW + REVIVE_GRACE_MS + 1);
+    assert.equal(h.status(id), 'dead', 'a never-booted broker is reaped, not stranded active forever');
+    // …and the parent (an active subscriber of the child) was told up the spine.
+    const note = h.inbox(root).find((e) => /never started/.test(e.label ?? ''));
+    assert.ok(note !== undefined, 'the parent received a boot-failure notice up the spine');
+    assert.equal(note.tier, 'urgent', 'the boot-failure notice is urgent');
+});

package/dist/core/__tests__/full/broker-dialogs.test.js

@@ -0,0 +1,153 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-dialogs.test.ts
+//
+// FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
+// (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
+//
+// Broker dialog handling — the §5.4 C2 forward-progress proof plus the T8 attach
+// gates G5/G5b/G6. Split out of broker-lifecycle.test.ts; the gates are the
+// original acceptance gate, unchanged.
+//
+// 3-PART HEADER (headless-retarget):
+//  (1) BUG IT LOCKS — the broker's blocking-dialog anti-deadlock contract: an
+//      unattended (zero-viewer) confirm() resolves to its default (false)
+//      IMMEDIATELY via noOp, never arming/awaiting a timeout (C2/G6a); a controller
+//      receives the dialog as extension_ui_request and its extension_ui_response
+//      unblocks the engine with ITS answer, not the default (G5); a dialog raised
+//      under a prior controller survives that controller's detach and is delivered
+//      to whoever takes control next via welcome.pending_dialog (G5b); and an
+//      ATTENDED dialog the controller never answers resolves on a SHORT per-dialog
+//      broker timeout, never the 120s default (G6b). Regression = an engine that
+//      hangs forever on a dialog with no answerer, or a pending dialog lost on
+//      controller handoff.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — the dialog round-trip is a pure
+//      async promise inside the broker's makeBrokerUiContext, forwarded/answered
+//      over the view.sock to the production ViewSocketClient. No tmux pane/window
+//      or pi session read is involved, so the lock holds headlessly
+//      (createHeadlessHarness, no tmux). It needs a REAL broker process (the real
+//      uiContext + timeout machinery), so this file keeps ONE real boot, shared
+//      across all four gates.
+//  (3) HOW THE HEADLESS DRIVE STILL FAILS ON REGRESSION — each gate drives the fake
+//      engine to raise a real confirm() through the real broker and asserts on the
+//      resolution recorded in fake-pi.dialog.jsonl (value + latency) and the frames
+//      the real controller receives. A regressed timeout/noOp/handoff path fails
+//      these exactly as it would under tmux; nothing here depended on a pane.
+//
+// ONE shared broker is booted in before() and reused across all four gates — 1 real
+// boot total, not 4. Because fake-pi.dialog.jsonl is APPEND-ONLY across the shared
+// broker, each gate snapshots the count before it drives (`base`) and asserts on
+// the entries IT produced (results[base], results[base+1]); gates whose first
+// attach must hold control use attachUntil(controller) to settle a prior gate's
+// controller-detach handoff.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
+let h;
+let id; // ONE shared broker, reused across C2/G5/G5b/G6 (1 real boot, not 4)
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+// Admit a controller, waiting out any prior gate's controller-detach handoff.
+const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
+// dialog.jsonl is append-only across the shared broker — snapshot the count, then
+// wait for AT LEAST `want` new entries and return the full (cumulative) array.
+const dialogCount = () => h.dialogResults(id).length;
+const awaitDialogs = (atLeast, label) => h.waitFor(() => (h.dialogResults(id).length >= atLeast ? h.dialogResults(id) : null), { label, timeoutMs: 15_000 });
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkdlg' });
+    const root = h.spawnRoot('broker-dialogs suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — dialog gates');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = () => h.node(id).pi_pid;
+// ===========================================================================
+// C2 forward-progress (zero-viewer path) — an unattended blocking dialog
+// resolves to its default (false) IMMEDIATELY: with no controller connected the
+// broker's REAL makeBrokerUiContext falls back to noOp resolution, so the engine
+// never deadlocks AND never waits on a per-dialog timeout (the design §5.4
+// timeout premise is false). Red/green: the OLD broker armed a setTimeout and
+// resolved only after `timeout` ms; the fixed broker resolves in ~0ms.
+// ===========================================================================
+test('C2 — unattended dialog resolves to its default IMMEDIATELY (noOp), never waits on a timeout', async () => {
+    const pid = brokerPid();
+    const base = dialogCount();
+    // Drive the fake engine to call uiContext.confirm(..., { timeout: 5000 }) with
+    // NO controller. C2 fix: makeBrokerUiContext resolves the default (false) AT
+    // ONCE — it does NOT arm/await the timeout. A generous < 2000ms bound is still a
+    // hard fail against the old ~5000ms timeout-wait while staying robust on slow CI.
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 5000 });
+    const results = await awaitDialogs(base + 1, 'unattended dialog resolved');
+    assert.equal(results[base].resolved, false, 'unattended confirm resolves to its default (false / deny)');
+    assert.ok(results[base].ms < 2000, `C2: resolved IMMEDIATELY (noOp), not after the 5000ms timeout — got ${results[base].ms}ms`);
+    assert.equal(isPidAlive(pid), true, 'the broker made forward progress (still alive, did not hang or exit)');
+});
+// ---------------------------------------------------------------------------
+// G5 — dialog forward + answer. Guards: a blocking dialog reaches the controller
+// as extension_ui_request and the controller's extension_ui_response unblocks the
+// engine with ITS answer (not the default). Failure mode: a dialog the controller
+// can't see/answer (silent deadlock).
+// ---------------------------------------------------------------------------
+test('G5 — controller receives an extension_ui_request, answers it, and the engine proceeds with that answer', async () => {
+    const base = dialogCount();
+    const c = await ctrl('g5-ctrl');
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 20_000 }); // generous: the controller answers first
+    const req = await c.waitFrame((f) => f.type === 'extension_ui_request', 'G5 dialog forwarded to controller');
+    assert.equal(req.method, 'confirm', 'G5: the forwarded dialog is the confirm() the engine raised');
+    const reqId = req.id;
+    c.send({ type: 'extension_ui_response', id: reqId, confirmed: true });
+    const results = await awaitDialogs(base + 1, 'G5 dialog resolved by the controller');
+    assert.equal(results[base].resolved, true, 'G5: the engine proceeded with the controller answer (true), not the default (false)');
+});
+// ---------------------------------------------------------------------------
+// G5 (mid-dialog attach) — Guards: a dialog raised under a prior controller stays
+// pending across that controller's detach (M2) and is delivered to whoever takes
+// control next via welcome.pending_dialog. Failure mode: a pending dialog lost on
+// controller handoff.
+// ---------------------------------------------------------------------------
+test('G5 — a controller attaching MID-dialog receives the pending dialog via welcome.pending_dialog', async () => {
+    const base = dialogCount();
+    const a = await ctrl('g5b-A');
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 30_000 }); // stays pending long enough for the handoff
+    const reqA = await a.waitFrame((f) => f.type === 'extension_ui_request', 'G5b dialog forwarded to controller A');
+    const reqId = reqA.id;
+    a.send({ type: 'bye' });
+    a.close(); // M2: detach frees control but does NOT cancel the pending dialog
+    // Controller B takes control (retry covers the close→controllerId=null beat) and
+    // its welcome carries the still-pending dialog.
+    const b = await attachUntil(id, 'controller', 'g5b-B', (x) => x.welcome.role === 'controller' && x.welcome.pending_dialog != null, 'G5b controller B takes control with the pending dialog');
+    assert.equal(b.welcome.pending_dialog.id, reqId, 'G5b: welcome.pending_dialog is the same dialog raised under A');
+    assert.equal(b.welcome.pending_dialog.method, 'confirm', 'G5b: the pending dialog is the confirm()');
+    b.send({ type: 'extension_ui_response', id: reqId, confirmed: true });
+    const results = await awaitDialogs(base + 1, 'G5b dialog resolved by controller B');
+    assert.equal(results[base].resolved, true, 'G5b: controller B answered the handed-off dialog and the engine proceeded');
+});
+// ---------------------------------------------------------------------------
+// G6 — anti-deadlock. (a) a zero-viewer dialog resolves to its default AT ONCE
+// (noOp). (b) an ATTENDED dialog the controller never answers resolves on a SHORT
+// per-dialog broker timeout. Guards: the engine never hangs on a dialog with no
+// answerer. Failure mode: a forever-blocked turn.
+// ---------------------------------------------------------------------------
+test('G6 — zero-viewer dialog resolves immediately; an unanswered attended dialog resolves on the broker timeout', async () => {
+    const pid = brokerPid();
+    const base = dialogCount();
+    // (a) zero viewers → immediate noOp default (NOT the 5000ms timeout).
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 5000 });
+    const r1 = await awaitDialogs(base + 1, 'G6a zero-viewer dialog resolved');
+    assert.equal(r1[base].resolved, false, 'G6a: zero-viewer dialog resolves to the default (deny)');
+    assert.ok(r1[base].ms < 2000, `G6a: resolved immediately (noOp), not after the 5000ms timeout — got ${r1[base].ms}ms`);
+    // (b) controller attached but silent → the broker resolves on the SHORT explicit
+    // per-dialog timeout (800ms), never the 120s default.
+    const c = await ctrl('g6-ctrl');
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 800 });
+    await c.waitFrame((f) => f.type === 'extension_ui_request', 'G6b dialog forwarded to controller'); // received, deliberately NOT answered
+    const r2 = await awaitDialogs(base + 2, 'G6b attended dialog resolved on timeout');
+    assert.equal(r2[base + 1].resolved, false, 'G6b: an unanswered attended dialog resolves to the default (deny)');
+    assert.ok(r2[base + 1].ms >= 600 && r2[base + 1].ms < 5000, `G6b: resolved on the ~800ms per-dialog timeout, not instantly and not the 120s default — got ${r2[base + 1].ms}ms`);
+    assert.equal(isPidAlive(pid), true, 'G6: the engine made forward progress on both dialogs (still alive)');
+});