@north-light/crouter 0.3.154

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

@@ -0,0 +1,147 @@
+// 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 surface attach` acceptance gate for G4/G7/G8: multi-writer
+// admission, decoder overflow isolation, and backpressure shedding.
+//
+// 3-PART HEADER (headless):
+//  (1) CONTRACT — every client that hellos as `controller` is welcomed writable,
+//      simultaneously and independently; each writable client may submit, and
+//      every connected client (both writers plus a read-only observer) receives
+//      the merged stream of both submissions, while a client that hellos as
+//      `observer` is rejected with error{read_only} when it tries to drive (G4).
+//      An oversized client line is capped and dropped with frame_overflow while
+//      the broker and other clients continue operating (G7). A stalled
+//      non-reading viewer is shed at the 32 MiB backpressure HWM while the
+//      broker and fast viewers remain unaffected (G8).
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — role admission, decoder limits,
+//      and the backpressure HWM are broker-process and view.sock contracts. They
+//      are exercised over a pure Unix socket using the production ViewSocketClient
+//      and raw node:net peers, with a real broker process and no tmux pane or
+//      window.
+//  (3) HOW THE HEADLESS DRIVE ASSERTS THE CONTRACT — the real socket responses
+//      provide the G4 welcome roles, per-writer relay frames and the read-only
+//      rejection, the G7 frame-overflow drop and broker survival, and the G8
+//      HWM-shed log line and broker survival.
+//
+// One shared broker is booted in before() and reused across all three gates. There
+// is no writer slot to hand off, so every gate simply attaches at the role it
+// wants.
+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, delay, tok, frameHas, brokerLogText, } from '../helpers/broker-clients.js';
+let h;
+let id; // ONE shared broker, reused across G4/G7/G8 (1 real boot, not 3)
+const kit = createAttachKit(() => h);
+const { attach, connectRaw } = kit;
+before(async () => {
+    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)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = () => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G4 — multi-writer admission + read-only gating. Guards: two simultaneous
+// `controller` hellos are BOTH welcomed writable, each one's own submission
+// reaches the engine, and every connected client sees BOTH turns; an explicit
+// observer that tries to drive is rejected with error{read_only}.
+// Failure mode: a singleton writer slot demoting the second client, a writer
+// whose prompt is silently dropped, fan-out that misses a viewer, or a
+// read-only client that can drive the engine.
+// ---------------------------------------------------------------------------
+test('G4 — two simultaneous clients are both welcomed controller, each submits, and both see both turns; an observer drive → error{read_only}', async () => {
+    const [w1, w2] = await Promise.all([
+        attach(id, 'controller', 'g4-writer-1'),
+        attach(id, 'controller', 'g4-writer-2'),
+    ]);
+    assert.equal(w1.welcome.role, 'controller', 'first client is welcomed writable');
+    assert.equal(w2.welcome.role, 'controller', 'second SIMULTANEOUS client is ALSO welcomed writable (no singleton slot)');
+    const observer = await attach(id, 'observer', 'g4-observer');
+    assert.equal(observer.welcome.role, 'observer', 'an explicit observer hello stays read-only');
+    // A read-only client may not drive the engine — the role is per-client and
+    // fixed by its own hello, so this rejection is independent of who else is
+    // attached.
+    observer.send({ type: 'prompt', text: 'a read-only client must not drive' });
+    const err = await observer.waitFrame((f) => f.type === 'error', 'G4 observer prompt rejected');
+    assert.equal(err.code, 'read_only', 'G4: observer prompt → error{read_only}');
+    // Each writer submits its OWN token. Submissions are sequenced (a prompt sent
+    // mid-stream routes as a steer and produces no second turn), so each turn is
+    // driven to its terminal agent_end before the next writer submits.
+    const tokenA = tok('G4-WRITER-1');
+    w1.send({ type: 'prompt', text: tokenA });
+    await w1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 writer 1 saw its own turn');
+    const tokenB = tok('G4-WRITER-2');
+    w2.send({ type: 'prompt', text: tokenB });
+    await w2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 writer 2 saw its own turn');
+    // The merged stream: EVERY connected client — both writers and the read-only
+    // observer — receives BOTH writers' turns.
+    await w2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 writer 2 ALSO received writer 1 turn');
+    await w1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 writer 1 ALSO received writer 2 turn');
+    await observer.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 observer received writer 1 turn');
+    await observer.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 observer received writer 2 turn');
+});
+// ---------------------------------------------------------------------------
+// G7 — decoder overflow (guards C5 OOM). A client line over BROKER_READ_CAPS is
+// 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', { timeout: 30_000 }, 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
+    // FrameDecoder throws FrameOverflowError; the broker drops the peer.
+    const bad = await connectRaw(id, { read: true });
+    bad.writeRaw(Buffer.alloc(26 * 1024 * 1024, 0x78));
+    await bad.waitClosed('G7 oversized peer dropped by the broker');
+    await h.waitFor(() => /frame overflow/.test(brokerLogText(h, id)) || null, { label: 'G7 broker logged the frame-overflow drop' });
+    // The broker survives and the other client is unaffected: a fresh turn relays.
+    const token = tok('G7-AFTER');
+    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(), pid, 'G7: broker pid unchanged');
+    assert.equal(h.bootCount(id), boots, 'G7: no reboot');
+});
+// ---------------------------------------------------------------------------
+// G8 — backpressure leak (guards M1). A stalled (non-reading) viewer is shed at
+// the HWM (32 MiB byte cap) while the broker + other viewers are unaffected.
+// 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', { timeout: 30_000 }, 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.
+    const stalled = await connectRaw(id, { read: false });
+    stalled.send({ type: 'hello', role: 'observer', client_id: 'g8-stalled' });
+    await delay(400);
+    // A fast event stream: ~60 MiB across 240 message_update frames. The stalled
+    // viewer's per-viewer backlog crosses the 32 MiB byte cap → dropped; the fast
+    // viewer drains between frames (per-update yield) and survives.
+    //
+    // The DROP SIGNAL is the broker's own log line, NOT the stalled socket's 'close':
+    // a PAUSED node socket does not surface the peer FIN/close until it is resumed,
+    // so the broker-side `backpressure high-water mark exceeded` line is the
+    // deterministic, race-free proof that the slow viewer was shed at the HWM.
+    const token = tok('G8-FLOOD');
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 240, padBytes: 256 * 1024, tool: false });
+    await h.waitFor(() => /backpressure high-water mark exceeded/.test(brokerLogText(h, id)) || null, { label: 'G8 broker shed the stalled viewer at the HWM', timeoutMs: 30_000 });
+    // The fast viewer drained the WHOLE stream (agent_end is the terminal frame) —
+    // 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(), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
+});

package/dist/core/__tests__/full/broker-attach-stream.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,133 @@
+// 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 surface attach` acceptance gate, gates G1/G1b/G2 (controller drive,
+// relay/coalescing, detach survival). 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 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).
+//      Regression = a viewer that sees nothing / sees stale text / kills the engine
+//      on detach.
+//  (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 three 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 three gates
+// (each just attaches fresh clients) — 1 real boot total, not 3. Each gate attaches
+// a fresh writable client; afterEach closes prior sockets before the next gate begins,
+// and each client's role remains fixed for its socket.
+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, delay, tok, frameHas } from '../helpers/broker-clients.js';
+let h;
+let id; // ONE shared broker, reused across G1/G1b/G2 (1 real boot, not 3)
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+// Attach a writable client for the gate; its role remains fixed for this socket.
+const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
+before(async () => {
+    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)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+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', 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 });
+    // The full streaming turn relays: agent_end carrying the token proves the turn
+    // ran AND its terminal frame reached the client; the intermediate types prove
+    // the stream (not just a final blob) was fanned out.
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1 agent_end carrying the prompt token');
+    for (const t of ['message_start', 'message_update', 'tool_execution_start', 'tool_execution_end', 'message_end', 'turn_end', 'agent_start', 'turn_start']) {
+        assert.ok(c.frames.some((f) => f.type === t), `G1: client received a relayed ${t} frame`);
+    }
+    assert.ok(c.frames.some((f) => f.type === 'message_start' && frameHas(f, token)), 'G1: a relayed message carries the prompt token');
+});
+// ---------------------------------------------------------------------------
+// G1b — message_update coalescing preserves ordering (regression for the F2
+// attach typing-lag fix, 2026-06-09). The broker holds the latest message_update
+// on a ~75ms timer; any OTHER event must flush it FIRST, so a viewer can never
+// observe message_update AFTER its message_end (which would resurrect stale
+// streaming text over the final message), and the LAST coalesced update must not
+// 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', 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).
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 12 });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1b turn relayed');
+    const types = c.frames.map((f) => f.type);
+    const lastUpdate = types.lastIndexOf('message_update');
+    const msgEnd = types.indexOf('message_end');
+    assert.ok(lastUpdate >= 0, 'G1b: at least one message_update relayed (coalescing must not starve updates)');
+    assert.ok(msgEnd >= 0, 'G1b: message_end relayed');
+    assert.ok(lastUpdate < msgEnd, `G1b: a message_update arrived AFTER message_end (update@${lastUpdate} vs end@${msgEnd}) — the coalescer flushed out of order`);
+    // tool/turn/agent frames must also never precede a stale held update.
+    for (const t of ['tool_execution_start', 'turn_end', 'agent_end']) {
+        const i = types.indexOf(t);
+        assert.ok(i < 0 || lastUpdate < i, `G1b: message_update relayed after ${t}`);
+    }
+});
+// ---------------------------------------------------------------------------
+// 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', async () => {
+    const pid = brokerPid();
+    const boots = h.bootCount(id);
+    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');
+    c.send({ type: 'bye' });
+    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(), 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).
+    const after = tok('G2-AFTER-DETACH');
+    h.fakeCmd(id, { cmd: 'stream', text: after });
+    const o = await attachUntil(id, 'observer', 'g2-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(after), 'G2 post-detach message in snapshot');
+    assert.ok(o.welcome.snapshot.messages.length > 0, 'G2: the engine produced a message after the detach');
+    assert.equal(isPidAlive(pid), true, 'G2: broker still alive after the post-detach turn');
+});

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,122 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-crash-teardown.test.ts
+//
+// Daemon-epoch broker ownership, real-process crash and teardown. The broker's
+// exit event is the sole death authority: a SIGTERM of a streaming broker
+// aborts cleanly and resumes the saved session with a continuation (policy row
+// 5); a SIGKILL mid-turn leaves no certificate and starts a fresh cycle (row
+// 6). Each replacement starts only after the
+// prior process has exited, preserving one writer per session. A clean `node
+// lifecycle close` then tears the replacement down (shutdown frame → exit,
+// socket unlinked, status canceled, daemon leaves it).
+//
+// The harness API server is a separate process (so synchronous CLI calls can be
+// served) whose fixture fleet is inert; spawnHeadlessChild retires its fixture
+// broker and reboots the node through THIS process's reviveNode, so every
+// broker below is harness-fleet-owned and every SIGKILL's REAL ChildProcess
+// exit drives policy automatically — no synthetic delivery, no tick, no grace.
+// Short-lived exits pay the real respawn backoff (5s, then 10s), so the one
+// broker lifecycle is split across two serial tests to fit the tier's
+// per-test budget.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { markBusy } from '../../runtime/busy.js';
+import { RUNTIME_RESTART_CONTINUATION } from '../../runtime/kickoff.js';
+import { jobDir } from '../../canvas/paths.js';
+let h;
+let root;
+// One broker lifecycle threaded through the two serial tests below.
+let id;
+let boots;
+let idleRevivedPid;
+let priorHoldTurn;
+before(async () => {
+    priorHoldTurn = process.env['PI_FAKE_ENGINE_HOLD_TURN'];
+    process.env['PI_FAKE_ENGINE_HOLD_TURN'] = '1';
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-brkcrash' });
+    root = h.spawnRoot('broker-crash suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+    if (priorHoldTurn === undefined)
+        delete process.env['PI_FAKE_ENGINE_HOLD_TURN'];
+    else
+        process.env['PI_FAKE_ENGINE_HOLD_TURN'] = priorHoldTurn;
+});
+// ===========================================================================
+// Items 4 + 5 + 6 — one real broker lifecycle:
+//   graceful busy teardown → strict resume + continuation → dirty interrupted-turn
+//   crash → recovery cycle → close.
+// ===========================================================================
+test('SIGTERM of a busy broker aborts cleanly and resumes with a continuation', { timeout: 30_000 }, async () => {
+    id = await h.spawnHeadlessChild(root, 'headless worker — crash+teardown');
+    const boot1 = await h.awaitBoot(id);
+    const oldPid = h.node(id).pi_pid;
+    assert.equal(oldPid, boot1.pid, 'canvas pid identifies the broker that booted the session');
+    assert.equal(isPidAlive(oldPid), true, 'busy broker alive before graceful teardown');
+    await h.waitFor(() => existsSync(h.brokerSock(id)), { label: 'broker socket bound' });
+    await h.waitFor(() => existsSync(join(jobDir(id), 'busy')), { label: 'fixture turn is active before SIGTERM' });
+    assert.equal(h.node(id).intent ?? null, null, 'fresh broker has a null intent (not refresh/idle-release)');
+    boots = h.bootCount(id);
+    // SIGTERM exercises broker.ts's bounded session.abort() path. Its REAL child
+    // exit sees the broker-written clean-abort certificate and resumes only after
+    // the first-failure backoff; no synthetic fleet delivery is involved.
+    process.kill(oldPid, 'SIGTERM');
+    await h.waitFor(() => !isPidAlive(oldPid), { label: 'gracefully torn-down broker pid is dead' });
+    assert.equal(existsSync(join(jobDir(id), 'clean-abort')), true, 'settled abort leaves durable clean-abort evidence before exit policy respawns');
+    // This is the file's SECOND real broker boot (exit-event recovery), behind a
+    // 5s short-lived-exit backoff, on an oversubscribed CI runner sharing the
+    // host with the other full-tier files' own broker spawns. Give it a wide,
+    // still-bounded ceiling.
+    const boot2 = await h.awaitBoot(id, { minCount: boots + 1, timeoutMs: 25_000 });
+    assert.equal(boot2.resuming, true, 'clean-abort exit-event recovery RESUMES the saved .jsonl');
+    assert.equal(boot2.prompt, RUNTIME_RESTART_CONTINUATION, 'the strict resume injects the runtime-restart continuation');
+    assert.ok(!boot2.rawArgv.includes('--crtr-new-cycle'), 'clean abort never starts a recovery cycle');
+    idleRevivedPid = h.node(id).pi_pid;
+    assert.ok(idleRevivedPid != null && isPidAlive(idleRevivedPid), 'the revived broker pid is alive');
+    assert.notEqual(idleRevivedPid, oldPid, 'the revived pid is distinct from the crashed one');
+    assert.equal(isPidAlive(oldPid), false, 'one-writer: the crashed pid never resurrected');
+});
+test('SIGKILL of a busy broker stays a dirty recovery cycle; close tears down the replacement', { timeout: 30_000 }, async () => {
+    // A second crash occurs with only the durable busy marker — SIGKILL cannot run
+    // the abort handler or write clean-abort evidence. Strict resume would only
+    // reopen the transcript at an idle prompt; the policy must select resume:false
+    // and inject the normal fresh-cycle kickoff. This second short-lived exit pays
+    // the 10s backoff before the recovery cycle.
+    markBusy(id);
+    process.kill(idleRevivedPid, 'SIGKILL');
+    await h.waitFor(() => !isPidAlive(idleRevivedPid), { label: 'mid-turn crashed broker pid is dead' });
+    const boot3 = await h.awaitBoot(id, { minCount: boots + 2, timeoutMs: 25_000 });
+    // The fake SessionManager reports `resuming=true` for ANY existing session
+    // path, including a cycle; production distinguishes cycling with the argv
+    // token and non-null kickoff. Assert those load-bearing inputs directly.
+    const recoveryArgv = boot3.rawArgv;
+    assert.ok(recoveryArgv.includes('--crtr-new-cycle'), 'a surviving busy marker selects --crtr-new-cycle');
+    assert.match(boot3.prompt ?? '', /You have been revived fresh after a context refresh/, 'the recovery cycle receives a real roadmap\/feed\/context kickoff');
+    const recoveryPid = h.node(id).pi_pid;
+    assert.ok(recoveryPid != null && isPidAlive(recoveryPid), 'the recovery-cycle broker pid is alive');
+    assert.notEqual(recoveryPid, idleRevivedPid, 'the recovery cycle uses a distinct broker pid');
+    assert.equal(isPidAlive(idleRevivedPid), false, 'one-writer: the interrupted pid never resurrected');
+    // --- Item 5: clean teardown of the (revived, live) broker. node lifecycle close marks
+    //     canceled BEFORE teardown (crash-safe order), then hostFor(broker).teardown
+    //     sends the `shutdown` frame → the broker disposes + exits, socket unlinked. ---
+    const sessionFile = h.node(id).pi_session_file;
+    assert.ok(sessionFile !== null && sessionFile !== undefined, 'revived broker has a session file');
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+    const sock = h.brokerSock(id);
+    await h.waitFor(() => existsSync(sock), { label: 'revived broker created its view.sock' });
+    const res = h.cli(root, ['node', 'lifecycle', 'close', '--node', id]);
+    assert.equal(res.code, 0, `node lifecycle close should exit 0\n--stderr--\n${res.stderr}`);
+    await h.waitFor(() => !isPidAlive(recoveryPid), { 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(recoveryPid), false, 'the broker stays dead — never revived');
+});

package/dist/core/__tests__/full/broker-deliver-ack.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/full/broker-deliver-ack.test.js

@@ -0,0 +1,73 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-deliver-ack.test.ts
+//
+// Regression for the interactive `deliver` ack (broker.ts `case 'deliver'`):
+// the ack must report the ENGINE CALL's real outcome, not the fact that a call
+// was routed. A `session.prompt()` that REJECTS outright — the shape a broker
+// whose model resolved but whose provider has no installed credential produces
+// ("No API key found for anthropic") — used to still ack ok:true, so crtrd
+// returned `delivered:true, delivered_via:engine` for a message the engine had
+// refused, and the one-shot client closed before the error frame arrived: the
+// message vanished with no trace. Now the deliver ack races acceptance (the
+// engine's own agent_start) against rejection, acks ok:false on rejection, and
+// records `broker.prompt.deliver_failed` in the node's job/log.jsonl.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit, brokerLogText } from '../helpers/broker-clients.js';
+import { REJECT_PROMPT_CALL } from '../fixtures/fake-engine.js';
+let h;
+const kit = createAttachKit(() => h);
+// Fired lifecycle hooks land one line each in fake-pi.events.jsonl.
+function eventCount(id, name) {
+    try {
+        return readFileSync(join(h.home, 'nodes', id, 'fake-pi.events.jsonl'), 'utf8')
+            .split('\n')
+            .filter((l) => {
+            try {
+                return JSON.parse(l).event === name;
+            }
+            catch {
+                return false;
+            }
+        }).length;
+    }
+    catch {
+        return 0;
+    }
+}
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-deliver-ack' });
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+test('a deliver whose prompt rejects acks ok:false and records deliver_failed; a succeeding deliver still acks ok:true via prompt', { timeout: 30_000 }, async () => {
+    const parent = h.spawnRoot('deliver ack parent');
+    const child = await h.spawnHeadlessChild(parent, 'deliver ack child');
+    // Let the kickoff turn fully settle so both delivers route as `prompt`
+    // (idle), never `steer` — the steer route legitimately acks at routing time.
+    await h.waitFor(() => (eventCount(child, 'agent_end') >= 1 ? true : null), {
+        label: 'kickoff turn settled',
+    });
+    const ctrl = await kit.attach(child, 'controller', 'deliver-ack-test');
+    // FAILURE: the engine refuses the call itself. Before the fix this acked
+    // ok:true and the rejection left no trace in the node's log.
+    ctrl.send({ type: 'deliver', id: 'd-fail', text: `do a thing ${REJECT_PROMPT_CALL}` });
+    const failAck = await ctrl.waitFrame((f) => f.type === 'ack' && f.for === 'deliver' && f.id === 'd-fail', 'rejected deliver ack');
+    assert.equal(failAck.type === 'ack' && failAck.ok, false, 'a rejected prompt must not ack delivered:true');
+    assert.match((failAck.type === 'ack' ? failAck.detail : undefined) ?? '', /No API key found/, 'the ack detail carries the engine rejection');
+    await h.waitFor(() => (brokerLogText(h, child).includes('broker.prompt.deliver_failed') ? true : null), { label: 'broker.prompt.deliver_failed recorded in job/log.jsonl' });
+    // POSITIVE CONTROL: an ordinary deliver still acks ok:true from acceptance
+    // (the engine's agent_start), detail naming the prompt route.
+    ctrl.send({ type: 'deliver', id: 'd-ok', text: 'an ordinary interactive message' });
+    const okAck = await ctrl.waitFrame((f) => f.type === 'ack' && f.for === 'deliver' && f.id === 'd-ok', 'accepted deliver ack');
+    assert.equal(okAck.type === 'ack' && okAck.ok, true, 'an accepted prompt acks delivered:true');
+    assert.equal(okAck.type === 'ack' ? okAck.detail : undefined, 'prompt');
+    ctrl.close();
+});

package/dist/core/__tests__/full/broker-dialogs.test.d.ts

@@ -0,0 +1 @@
+export {};