@crouton-kit/crouter 0.3.18 → 0.3.20

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

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

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

@@ -0,0 +1,126 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-dialogs.test.ts
+//
+// 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 (see its header for the
+// full file map); the tests are the original acceptance gate, unchanged, on their
+// own isolated harness. The attach-client helpers live in
+// helpers/broker-clients.ts (the PRODUCTION ViewSocketClient, §0 one-writer: a
+// viewer holds ONLY a socket).
+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 } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brkdlg' });
+    root = h.spawnRoot('broker-dialogs suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => 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. (Supports
+// acceptance item 7: the existing suite stays green; this only ADDS coverage.)
+// ===========================================================================
+test('C2 — unattended dialog resolves to its default IMMEDIATELY (noOp), never waits on a timeout', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — dialog');
+    const pid = h.node(id).pi_pid;
+    // 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 h.waitFor(() => {
+        const r = h.dialogResults(id);
+        return r.length > 0 ? r : null;
+    }, { timeoutMs: 15_000, label: 'unattended dialog resolved' });
+    assert.equal(results[0].resolved, false, 'unattended confirm resolves to its default (false / deny)');
+    assert.ok(results[0].ms < 2000, `C2: resolved IMMEDIATELY (noOp), not after the 5000ms timeout — got ${results[0].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', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G5a');
+    const c = await attach(id, 'controller', '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 h.waitFor(() => {
+        const r = h.dialogResults(id);
+        return r.length > 0 ? r : null;
+    }, { label: 'G5 dialog resolved by the controller', timeoutMs: 15_000 });
+    assert.equal(results[0].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', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G5b');
+    const a = await attach(id, 'controller', '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 h.waitFor(() => {
+        const r = h.dialogResults(id);
+        return r.length > 0 ? r : null;
+    }, { label: 'G5b dialog resolved by controller B', timeoutMs: 15_000 });
+    assert.equal(results[0].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', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G6');
+    const pid = brokerPid(id);
+    // (a) zero viewers → immediate noOp default (NOT the 5000ms timeout).
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 5000 });
+    const r1 = await h.waitFor(() => (h.dialogResults(id).length >= 1 ? h.dialogResults(id) : null), { label: 'G6a zero-viewer dialog resolved', timeoutMs: 15_000 });
+    assert.equal(r1[0].resolved, false, 'G6a: zero-viewer dialog resolves to the default (deny)');
+    assert.ok(r1[0].ms < 2000, `G6a: resolved immediately (noOp), not after the 5000ms timeout — got ${r1[0].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 attach(id, 'controller', '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 h.waitFor(() => (h.dialogResults(id).length >= 2 ? h.dialogResults(id) : null), { label: 'G6b attended dialog resolved on timeout', timeoutMs: 15_000 });
+    assert.equal(r2[1].resolved, false, 'G6b: an unanswered attended dialog resolves to the default (deny)');
+    assert.ok(r2[1].ms >= 600 && r2[1].ms < 5000, `G6b: resolved on the ~800ms per-dialog timeout, not instantly and not the 120s default — got ${r2[1].ms}ms`);
+    assert.equal(isPidAlive(pid), true, 'G6: the engine made forward progress on both dialogs (still alive)');
+});

package/dist/core/__tests__/broker-dormant-wake.test.d.ts

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

package/dist/core/__tests__/broker-dormant-wake.test.js

@@ -0,0 +1,51 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-dormant-wake.test.ts
+//
+// Acceptance item 3 (DORMANT) of the headless-broker migration. Split out of
+// broker-lifecycle.test.ts (see its header for the full file map); the test is
+// the original acceptance gate, unchanged, on its own isolated harness.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { subscribe } from '../canvas/canvas.js';
+import { appendInbox } from '../feed/inbox.js';
+import { isPidAlive } from '../canvas/pid.js';
+let h;
+let root;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brkdorm' });
+    // An active resident root: the spawn parent AND the live node a child can hold
+    // an active subscription to (so its natural stop classifies 'awaiting').
+    root = h.spawnRoot('broker-dormant suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// ===========================================================================
+// Item 3 (DORMANT) — a natural stop while awaiting a live subscription idle-
+// RELEASES the broker (it exits); the daemon's second pass revives it (RESUME)
+// on the next unseen inbox entry.
+// ===========================================================================
+test('DORMANT wake — idle-release → broker exits → daemon pass-2 reviveNode(resume) on inbox', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — dormant wake');
+    const pid = h.node(id).pi_pid;
+    // Give the (terminal) child an ACTIVE subscription to the LIVE root, so the
+    // stop-guard classifies its natural stop as 'awaiting' (a dormant orchestrator
+    // awaiting a worker) → the stophook idle-releases it (paneless → no focus).
+    subscribe(id, root, true);
+    await h.stop(id, 'stop');
+    await h.waitForStatus(id, 'idle');
+    assert.equal(h.node(id).intent, 'idle-release', 'awaiting + unfocused → idle-release');
+    await h.waitFor(() => !isPidAlive(pid), { label: 'released broker process exited' });
+    // Daemon owns wake-on-message for a dormant (pi-dead) broker: an unseen inbox
+    // entry + a tick → pass 2 → reviveNode(resume:true) → a fresh broker boots.
+    appendInbox(id, { from: 'tester', tier: 'normal', kind: 'message', label: 'resume-me', data: { body: 'work after release' } });
+    await h.tick();
+    const boot2 = await h.awaitBoot(id, { minCount: 2 });
+    assert.equal(boot2.resuming, true, 'the dormant revive RESUMES the saved session');
+    const newPid = h.node(id).pi_pid;
+    assert.ok(newPid != null && isPidAlive(newPid), 'the revived broker pid is alive');
+    assert.notEqual(newPid, pid, 'the revived broker is a fresh process');
+});

package/dist/core/__tests__/broker-lifecycle.test.d.ts

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

package/dist/core/__tests__/broker-lifecycle.test.js

@@ -0,0 +1,87 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-lifecycle.test.ts
+//
+// The broker-backed lifecycle suite — the acceptance-gate proof of the headless-
+// broker migration (plan T11). It drives the REAL `crtr` CLI into an isolated
+// REAL tmux session and spawns `--headless` nodes onto the REAL headless broker
+// host (host.ts), which boots a REAL detached broker PROCESS (broker.ts) per
+// node. The broker hosts a fake SDK engine (fixtures/fake-engine.ts) loaded via
+// the CRTR_BROKER_ENGINE seam — NOTHING in the broker, the host, the stophook,
+// the inbox-watcher, the stop-guard, or the daemon (superviseTick) is mocked.
+// Every assertion reads straight off the canvas data layer.
+//
+// The suite is SPLIT across sibling files (one isolated harness each) so
+// node:test's file-level parallelism applies — the tests themselves are the
+// original acceptance gate, unchanged:
+//   THIS FILE                        — items 1–2 + 3 (LIVE): spawn, LIVE wake
+//   broker-dormant-wake.test.ts      — item 3 (DORMANT): idle-release → daemon revive
+//   broker-crash-teardown.test.ts    — items 4–6 + M-1/M-2: crash, teardown, boot failure
+//   broker-dialogs.test.ts           — §5.4 C2 + gates G5/G5b/G6 (dialogs)
+//   broker-attach-stream.test.ts     — gates G1/G1b/G2/G3 (drive + relay + snapshot)
+//   broker-attach-limits.test.ts     — gates G4/G7/G8/G9 (arbitration + caps + one-writer)
+//
+// Acceptance items (plan §4) → the asserting test:
+//   1 spawn --headless → host_kind='broker', null placement, live broker pid     → "spawn"
+//   2 supervised by broker-pid signal-0 (stophook recordPid = broker pid)         → "spawn"
+//   3 inbox wakes LIVE (in-broker watcher) AND DORMANT (idle-release → daemon)    → "live wake" here + "dormant wake" (broker-dormant-wake.test.ts)
+//   7 tmux stays default — the existing suite passes UNMODIFIED (this split only
+//     MOVES tests between files + extracts harness wiring; nothing is rewritten).
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { appendInbox } from '../feed/inbox.js';
+import { isPidAlive } from '../canvas/pid.js';
+let h;
+let root;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-broker' });
+    root = h.spawnRoot('broker-suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// ===========================================================================
+// Item 1 + 2 — spawn --headless: broker host, NULL placement, a live broker pid
+// that IS the daemon's supervision signal (stophook recordPid(process.pid)).
+// ===========================================================================
+test('spawn --headless → broker host_kind, null placement, live broker pid; daemon leaves a healthy broker', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — spawn');
+    const node = h.node(id);
+    // Item 1: the broker host + a paneless placement.
+    assert.equal(node.host_kind, 'broker', "host_kind === 'broker'");
+    assert.equal(node.window ?? null, null, 'window is NULL (paneless broker)');
+    assert.equal(node.pane ?? null, null, 'pane is NULL (paneless broker)');
+    assert.equal(node.tmux_session ?? null, null, 'tmux_session is NULL (paneless broker)');
+    assert.ok(node.pi_pid != null, 'a broker pid was recorded as pi_pid');
+    assert.equal(isPidAlive(node.pi_pid), true, 'the broker pid is alive');
+    // Item 2: the supervision signal IS the broker pid — the stophook recorded
+    // process.pid (the broker's own pid) on session_start, == the boot proof pid.
+    const boot = await h.awaitBoot(id);
+    assert.equal(boot.pid, node.pi_pid, 'boot-proof pid (broker process.pid) === supervised pi_pid');
+    // The daemon supervises it by that pid alone: a healthy broker is left untouched.
+    const before = h.bootCount(id);
+    await h.tick();
+    assert.equal(h.status(id), 'active', 'a healthy broker stays active across a daemon tick');
+    assert.equal(h.node(id).pi_pid, node.pi_pid, 'pid unchanged — not revived');
+    assert.equal(h.bootCount(id), before, 'no reboot');
+    assert.equal(isPidAlive(node.pi_pid), true, 'broker still alive');
+});
+// ===========================================================================
+// Item 3 (LIVE) — the in-broker inbox-watcher delivers an inbox push WITHOUT an
+// exit or revive (the broker stays alive; pi.sendUserMessage → injected).
+// ===========================================================================
+test('LIVE wake — in-broker watcher injects an inbox push with no exit/revive', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — live wake');
+    const pid = h.node(id).pi_pid;
+    const boots = h.bootCount(id);
+    appendInbox(id, { from: 'tester', tier: 'normal', kind: 'message', label: 'live-wake', data: { body: 'do this live' } });
+    // The REAL in-broker watcher (800ms poll + 1000ms debounce) delivers via
+    // pi.sendUserMessage → fake-pi.injected.jsonl.
+    await h.awaitWake(id, { match: /do this live/, timeoutMs: 15_000 });
+    // No exit, no revive: same broker pid, still alive, no new boot.
+    assert.equal(h.bootCount(id), boots, 'no new boot — the live broker was not revived');
+    assert.equal(h.node(id).pi_pid, pid, 'pi_pid unchanged — the broker never exited');
+    assert.equal(isPidAlive(pid), true, 'the broker is still alive after the live wake');
+});

package/dist/core/__tests__/broker-sdk-wiring.test.d.ts

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

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -0,0 +1,166 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-sdk-wiring.test.ts
+//
+// REAL-SDK regression tests for the latent broker gaps the viewer-reuse scout
+// (node mq5thyli) found (findings-viewer-reuse.md §Q2). These deliberately drive
+// the ACTUAL `@earendil-works/pi-coding-agent` SDK — NOT the `CRTR_BROKER_ENGINE`
+// fake the lifecycle suite uses — because C3 and C4 slipped past the Phase-3 gate
+// PRECISELY because that gate mocked the SDK out. Each test exercises the exact
+// production wiring (`buildBrokerSession` / `makeBrokerUiContext`) and would FAIL
+// against the pre-fix broker:
+//
+//   C3 — the broker drives the SERVICES path, so an extension-registered custom
+//        model provider is registered into the ModelRegistry and resolves onto
+//        the session. Plain createAgentSession never calls registerProvider, so a
+//        custom-provider node would get NO model.
+//   C4 — a project AGENTS.md is injected into the assembled system prompt (the
+//        services path loads project context; 0.78.1 has no project-trust gate so
+//        context is unconditionally loaded — see buildBrokerSession's C4 note).
+//   C2 — with ZERO viewers attached, the broker UI context resolves confirm() /
+//        select() / input() / editor() to deny/cancel IMMEDIATELY (noOp), instead
+//        of relying on a per-dialog timeout and hanging the agent turn forever.
+//
+// These run offline (no network/auth): registration + system-prompt assembly +
+// dialog routing are all local. No tmux, no broker process — direct unit drives.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { buildBrokerSession, makeBrokerUiContext } from '../runtime/broker.js';
+// The REAL engine, assembled from broker-sdk's static SDK re-exports — bypasses
+// the CRTR_BROKER_ENGINE seam entirely so these tests can never accidentally hit
+// the fake (the whole point: prove the wiring the mock hid).
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+const HERE = dirname(fileURLToPath(import.meta.url));
+const C3_EXT = join(HERE, 'fixtures', 'c3-custom-provider-ext.ts');
+function cfg(cwd, extra = {}) {
+    return { cwd, extensionPaths: [], ...extra };
+}
+// ===========================================================================
+// C3 — the SERVICES path registers an extension's custom model provider, so the
+// broker resolves a model that plain createAgentSession (no registerProvider)
+// would never see.
+// ===========================================================================
+test('C3 — services path registers an extension model provider; the broker session gets it', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3-'));
+    try {
+        const { session, services } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT], model: 'c3prov/c3model' }));
+        try {
+            // The extension's provider was registered into the SERVICES registry (this
+            // is the registerProvider step plain createAgentSession skips).
+            const found = services.modelRegistry.find('c3prov', 'c3model');
+            assert.ok(found, 'C3: extension-registered model is present in the services ModelRegistry');
+            assert.equal(found.provider, 'c3prov', 'C3: provider name round-trips');
+            assert.equal(found.id, 'c3model', 'C3: model id round-trips');
+            // …and the broker resolved it onto the session AGAINST the services registry
+            // (a fresh ModelRegistry would have returned undefined → no model).
+            assert.equal(session.model?.id, 'c3model', 'C3: the broker session got the custom-provider model');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+// ===========================================================================
+// C4 — project context (AGENTS.md) is injected into the system prompt. The
+// services path loads project context files; on the 0.78.1 pin there is no
+// project-trust gate, so they load unconditionally (and buildBrokerSession does
+// NOT re-introduce the CLI's headless trust resolver, which would drop them).
+// ===========================================================================
+test('C4 — a project AGENTS.md is injected into the assembled system prompt', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c4-'));
+    try {
+        const marker = 'C4_AGENTS_MARKER_' + Math.random().toString(36).slice(2);
+        writeFileSync(join(cwd, 'AGENTS.md'), `# Project rules\n\n${marker}\n`);
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd));
+        try {
+            assert.ok(session.systemPrompt.includes(marker), 'C4: project AGENTS.md content is present in the assembled system prompt');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+// ===========================================================================
+// C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
+// hanging the turn and never waiting on a per-dialog timeout. Drives the REAL
+// makeBrokerUiContext (the exact ExtensionUIContext the SDK hands extensions),
+// with a controller() that reports zero viewers.
+// ===========================================================================
+test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
+    const ctx = makeBrokerUiContext({
+        controller: () => null, // ZERO viewers attached
+        forward: () => {
+            throw new Error('C2: must NOT forward a dialog when no controller is attached');
+        },
+        pending: new Map(),
+    });
+    // confirm() WITH a large timeout: the fix must resolve at once (deny), NOT after
+    // the timeout — the old timeout-reliant path would have waited 60s (or, with no
+    // timeout, hung forever). Race against a 2s "HANG" sentinel to make a regression
+    // a hard failure rather than a slow pass.
+    const start = Date.now();
+    const confirmed = await Promise.race([
+        ctx.confirm('proceed?', 'really?', { timeout: 60_000 }),
+        new Promise((r) => setTimeout(() => r('HANG'), 2_000)),
+    ]);
+    assert.equal(confirmed, false, 'C2: confirm() denies (false) with zero viewers');
+    assert.ok(Date.now() - start < 1_000, 'C2: resolved immediately, not after the 60s timeout');
+    // The other blocking dialogs cancel to undefined — including editor(), which
+    // takes NO opts at all (so it could never carry a timeout to lean on).
+    assert.equal(await ctx.select('pick', ['a', 'b']), undefined, 'C2: select() cancels (undefined)');
+    assert.equal(await ctx.input('name'), undefined, 'C2: input() cancels (undefined)');
+    assert.equal(await ctx.editor('edit'), undefined, 'C2: editor() cancels (undefined)');
+});
+// ===========================================================================
+// M2 (review mq5wkqep / T4) — REPLACES the Wave-0 M-1 cancel-on-detach. A dialog
+// forwarded to a controller that then DETACHES must NOT be cancelled: it stays
+// pending so a brief detach/reattach (or a handoff to another controller) does
+// not lose an answerable dialog. The broker-side default timeout is the ONLY
+// non-answer resolution (proven here with a short per-dialog timeout standing in
+// for the 120s default). Guards against regressing to the over-eager cancel.
+// ===========================================================================
+test('M2 — a forwarded dialog stays pending on controller detach, resolving only on the broker-side timeout', async () => {
+    const pending = new Map();
+    let attached = true;
+    const ctx = makeBrokerUiContext({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        controller: () => (attached ? { id: 'c1' } : null),
+        forward: () => {
+            /* a real controller would receive the request over its socket */
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        pending: pending,
+    });
+    // Controller attached → confirm() forwards + registers a pending dialog (with the
+    // request retained for welcome.pending_dialog / re-route, T4) and does NOT
+    // resolve yet. A short per-dialog timeout stands in for the 120s broker default.
+    const p = ctx.confirm('proceed?', 'really?', { timeout: 80 });
+    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a controller is attached');
+    const entry = [...pending.values()][0];
+    assert.ok(entry.request, 'M2: the pending entry retains the request (welcome/re-route need it)');
+    assert.equal(entry.cancel, undefined, 'M2: there is no cancel-on-detach path anymore');
+    // Controller detaches → the dialog STAYS pending (the broker no longer cancels it).
+    attached = false;
+    assert.equal(pending.size, 1, 'M2: detach does NOT cancel the in-flight dialog');
+    // Only the broker-side timeout resolves it, to the SAFE default (deny).
+    const resolved = await Promise.race([
+        p,
+        new Promise((r) => setTimeout(() => r('HANG'), 2_000)),
+    ]);
+    assert.equal(resolved, false, 'M2: resolves to deny on the broker-side timeout, never hangs');
+    assert.equal(pending.size, 0, 'M2: the pending registry is drained after the timeout');
+});

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.d.ts

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

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -0,0 +1,102 @@
+// Tests for the canvas-node inbox watcher pi extension, part 2 — the
+// refresh-yield HOLD path and idle delivery. Split out of
+// canvas-inbox-watcher.test.ts (see its header) so node:test's file-level
+// parallelism applies; the tests and the scaffold are moved here UNCHANGED.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher-hold.test.ts
+import { test, describe, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { appendInbox } from '../feed/inbox.js';
+import { createNode, setIntent } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+// Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
+// resolve+seed tick, a read tick, and the debounce window before asserting.
+const TICK_MS = 800;
+const DEBOUNCE_MS = 1000;
+const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 500;
+let origHome;
+let origNode;
+const homes = [];
+const disposers = [];
+/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+function freshNode(nodeId) {
+    const home = join(tmpdir(), `crtr-canvas-watcher-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(home, { recursive: true });
+    homes.push(home);
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_NODE_ID'] = nodeId;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(() => {
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    for (const h of homes) {
+        try {
+            rmSync(h, { recursive: true, force: true });
+        }
+        catch { /* noop */ }
+    }
+});
+describe('canvas inbox watcher — hold + idle delivery', () => {
+    test('refresh-yield in flight: inbox entries are HELD, then delivered once intent clears (no loss)', async () => {
+        freshNode('node-refresh');
+        closeDb(); // rebind the canvas db to this test's fresh home
+        const meta = {
+            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
+            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
+            status: 'active', intent: 'refresh',
+        };
+        createNode(meta);
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // Streaming (mid-turn) when a child finishes — normally this would steer.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 0, 'entries are held while a refresh-yield is in flight (no steer-hijack)');
+        // The fresh pi clears intent on boot; the held entry must then be delivered
+        // — the cursor was never advanced, so nothing is lost.
+        setIntent('node-refresh', null);
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'the held entry is delivered once the refresh clears');
+    });
+    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
+        freshNode('node-idle');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // No agent_start fired → watcher treats the node as idle.
+        await wait(TICK_MS + 100);
+        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
+    });
+});

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -4,6 +4,8 @@
 //
 // Focus: a finished node (push final → InboxEntry kind 'final') must STEER a
 // mid-stream subscriber, not queue behind its current turn as a follow-up.
+// Part 2 — the refresh-yield HOLD path and idle delivery — lives in
+// canvas-inbox-watcher-hold.test.ts (split for node:test file-level parallelism).
 import { test, describe, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdirSync, rmSync } from 'node:fs';
@@ -11,8 +13,6 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
 import { appendInbox } from '../feed/inbox.js';
-import { createNode, setIntent } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
 // Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
 // resolve+seed tick, a read tick, and the debounce window before asserting.
 const TICK_MS = 800;
@@ -88,38 +88,4 @@ describe('canvas inbox watcher — finished-node delivery', () => {
         assert.equal(pi.injected.length, 1);
         assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
     });
-    test('refresh-yield in flight: inbox entries are HELD, then delivered once intent clears (no loss)', async () => {
-        freshNode('node-refresh');
-        closeDb(); // rebind the canvas db to this test's fresh home
-        const meta = {
-            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active', intent: 'refresh',
-        };
-        createNode(meta);
-        const pi = makeFakePi();
-        disposers.push(registerCanvasInboxWatcher(pi));
-        // Streaming (mid-turn) when a child finishes — normally this would steer.
-        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 0, 'entries are held while a refresh-yield is in flight (no steer-hijack)');
-        // The fresh pi clears intent on boot; the held entry must then be delivered
-        // — the cursor was never advanced, so nothing is lost.
-        setIntent('node-refresh', null);
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 1, 'the held entry is delivered once the refresh clears');
-    });
-    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
-        freshNode('node-idle');
-        const pi = makeFakePi();
-        disposers.push(registerCanvasInboxWatcher(pi));
-        // No agent_start fired → watcher treats the node as idle.
-        await wait(TICK_MS + 100);
-        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 1);
-        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
-    });
 });

package/dist/core/__tests__/cascade-close.test.js

@@ -134,13 +134,23 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
         // SIDEWAYS (S, G) was reaped. close(B) reaped EXACTLY B's own subtree.
         // ===================================================================
-        // Ancestor A — fully untouched: still the live resident root, inbox intact.
+        // Ancestor A — lifecycle untouched (still the live resident root), but A is
+        // the SURVIVING manager of the close-root B, so the wake doctrine fix WAKES
+        // it: a "child closed" notice is fanned to a manager OUTSIDE the closing set
+        // (D-1 — previously A heard nothing and a dormant A could hang forever).
         {
             const a = h.node(A);
             assert.equal(a.status, 'active', 'A (ancestor) still active — untouched by the cascade');
             assert.equal(a.lifecycle, 'resident', 'A still resident');
             assert.equal(a.intent ?? null, null, 'A intent untouched');
-            assert.deepEqual(h.inbox(A), aInboxBefore, "A's inbox is byte-for-byte intact across the close (cascade touches only closed nodes' inboxes)");
+            // A's PRIOR entries are preserved; exactly ONE new child-closed entry
+            // from the closed child B is appended (the doctrine wake).
+            const aInbox = h.inbox(A);
+            assert.deepEqual(aInbox.slice(0, aInboxBefore.length), aInboxBefore, "A's prior inbox entries are preserved across the close");
+            const added = aInbox.slice(aInboxBefore.length);
+            assert.equal(added.length, 1, 'exactly one new entry appended to the surviving manager A');
+            assert.equal(added[0].from, B, 'the new entry is from the closed child B');
+            assert.match(added[0].label, /closed/i, 'the new entry tells A its child B was closed');
         }
         // Sideways subtree S→G — wholly alive: status active AND real panes alive.
         for (const id of sideways) {

package/dist/core/__tests__/child-death-wake.test.d.ts

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