@north-light/crouter 0.3.154

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

@@ -0,0 +1,240 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/cascade-close.test.ts
+//
+// CASCADE CLOSE + exclusive-subtree ownership — a FAITHFUL integration test of
+// `crtr node lifecycle close` on a MIDDLE node, driven through the REAL CLI against a REAL
+// isolated tmux session with REAL fake-pi vehicles in REAL panes, asserting off
+// the canvas data layer and checked against the state-model ORACLE
+// (state-model.md §4 `node lifecycle close`, §5 cascade-close ownership, invariant 3,
+// ambiguity A5).
+//
+// WHY this exists alongside the unit `close.test.ts`: that test exercises
+// `closeNode()` in-process against the data layer with FABRICATED pane strings
+// (`pane:'%x'`) — it proves the closing-set fixpoint and the status flip, but it
+// never kills a real tmux pane, never boots a real vehicle, and never closes a
+// MIDDLE node with a live sideways-sibling subtree. This test fills exactly that
+// gap: it builds a real tree, closes the middle, and proves the reap is EXACTLY
+// the closed node's own subtree — nothing above (the ancestor) or sideways (a
+// sibling subtree) is touched, and the real broker engines actually die.
+//
+// VIEWER MODEL (a09b71f): a managed child boots as a detached headless BROKER
+// with NO viewer pane on spawn (a viewer is opened on demand via `surface node focus`).
+// So "the node is up" is broker-engine liveness — its recorded `pi_pid` is alive
+// — NOT pane presence. close tears that broker engine down (headlessBrokerHost
+// .teardown over view.sock), so we assert pid liveness, not panes.
+//
+// The tree (covers BOTH required shapes in one topology):
+//
+//     A (resident root, in-process)
+//     ├── B   ◄── CLOSE TARGET (the middle node)
+//     │   ├── C
+//     │   │   └── E        depth  : A→B→C→E  (deep chain)
+//     │   └── D            breadth: B has two children {C, D}
+//     └── S                sideways sibling subtree — MUST survive
+//         └── G
+//
+//   close(B) ⇒ exclusive subtree {B,C,D,E} canceled; A,S,G untouched.
+//
+// CRITICAL DELIVERABLE (ambiguity A5): the EXACT terminal status a cascade-
+// closed descendant receives under `node lifecycle close`. With the fixtures made
+// non-empty below: status === 'canceled', intent === null (cleared) — for the
+// cascade ROOT and EVERY descendant alike (`transition(id,'cancel')`,
+// close.ts → lifecycle.ts cancel row: status='canceled', intent=null, from '*').
+// This differs from the ancestor-RESET path (`reapDescendants` → `reap` → 'done')
+// — same act, different terminal status: A5's open question. We assert the close
+// side and report the confirmed fact; we do NOT change it.
+//
+// FLAG vs the task brief: the brief expected "subscription+parent edges removed"
+// on close. CURRENT behavior + the ORACLE (§4: "Nothing is deleted: pi sessions +
+// edges persist → revivable") + the CLI help ("their pi sessions and canvas edges
+// persist for a later revive") all say edges PERSIST. This test asserts the
+// CURRENT (persist) behavior and the report flags the contradiction; production
+// is NOT changed.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHarness, hasTmux, TMUX_TIMEOUT_MS } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+function sessionExists(session) {
+    return (spawnSync('tmux', ['has-session', '-t', session], {
+        stdio: 'ignore',
+        timeout: TMUX_TIMEOUT_MS,
+    }).status === 0);
+}
+function seedAssistantSession(sessionFile) {
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+}
+test('cascade close: middle-node lifecycle close cancels EXACTLY its subtree, ancestor + sideways untouched, edges persist', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-cascade' });
+    try {
+        // ===================================================================
+        // BUILD — the real tree. A is the in-process resident root (no pane);
+        // B,C,D,E,S,G are real managed children, each a real fake-pi in a real
+        // backstage pane (spawnChild awaits each boot). Every `node new` seeds the
+        // spine edge parent→child (active) + the spawned_by/parent provenance.
+        // ===================================================================
+        const A = h.spawnRoot('cascade-close root');
+        const B = await h.spawnChild(A, 'middle node — the close target', { kind: 'developer' });
+        const C = await h.spawnChild(B, 'B child one');
+        const E = await h.spawnChild(C, 'deep leaf under C'); // depth: A→B→C→E
+        const D = await h.spawnChild(B, 'B child two'); // breadth: B has {C, D}
+        const S = await h.spawnChild(A, 'sideways sibling of B'); // sideways subtree
+        const G = await h.spawnChild(S, 'child of the sideways sibling');
+        const subtree = [B, C, D, E]; // B's exclusive subtree (the expected cancel set)
+        const sideways = [S, G]; // a sibling subtree — must be wholly untouched
+        // Make the close-path fixtures NON-EMPTY so close exercises cancel+notice
+        // semantics instead of the new reap-empty path.
+        for (const id of subtree) {
+            const sessionFile = h.node(id).pi_session_file;
+            assert.ok(sessionFile !== null && sessionFile !== undefined, `${id} has a session file`);
+            seedAssistantSession(sessionFile);
+        }
+        // Pre-close sanity: every node live + present, spine wired as drawn.
+        {
+            for (const id of [B, C, D, E, S, G]) {
+                assert.ok(h.status(id) === 'active' || h.status(id) === 'idle', `${id} live before close`);
+                const pid = h.node(id).pi_pid;
+                assert.ok(pid != null && isPidAlive(pid), `${id} broker engine alive before close`);
+            }
+            assert.ok(h.status(A) === 'active' || h.status(A) === 'idle', 'A (root) live before close');
+            // Spine: A→{B,S}, B→{C,D}, C→{E}, S→{G} (all active spawn-seed edges).
+            const subIds = (n) => h.subscriptions(n).map((s) => s.node_id).sort();
+            assert.deepEqual(subIds(A), [B, S].sort(), 'A subscribes_to B and S');
+            assert.deepEqual(subIds(B), [C, D].sort(), 'B subscribes_to C and D');
+            assert.deepEqual(subIds(C), [E], 'C subscribes_to E');
+            assert.deepEqual(subIds(S), [G], 'S subscribes_to G');
+            // provenance edges (spawned_by / parent)
+            for (const [child, parent] of [[B, A], [C, B], [E, C], [D, B], [S, A], [G, S]]) {
+                assert.equal(h.node(child).parent, parent, `${child}.parent = ${parent}`);
+            }
+        }
+        // Make A's inbox NON-EMPTY before the close so "ancestor inbox intact" is a
+        // non-vacuous assertion: B pushes a routine update up its spine → A (B's
+        // sole active subscriber). A is the in-process root with no live watcher,
+        // so the pointer simply accumulates and must survive the close untouched.
+        {
+            const res = h.cli(B, ['push', 'update', 'progress from B before close']);
+            assert.equal(res.code, 0, `B push update exit 0\n${res.stderr}`);
+        }
+        const aInboxBefore = h.inbox(A);
+        assert.ok(aInboxBefore.some((e) => e.from === B && e.kind === 'update'), "A's inbox holds B's pre-close update (non-vacuous 'intact' baseline)");
+        // ===================================================================
+        // CLOSE the MIDDLE node B, through the REAL CLI (`crtr node lifecycle close --node B`,
+        // run AS the root A). closeNode is synchronous in the subprocess: by the
+        // time it returns, rows are flipped and panes are killed.
+        // ===================================================================
+        const closeRes = h.cli(A, ['node', 'lifecycle', 'close', '--node', B]);
+        assert.equal(closeRes.code, 0, `node lifecycle close exit 0\n${closeRes.stderr}`);
+        // The CLI's own rendered report (plain markdown): cascade root B, exactly
+        // 4 closed, 0 spared (no spared clause is emitted when none were spared).
+        assert.match(closeRes.stdout, new RegExp(`^Closed ${B} and its exclusive subtree — 4 node\\(s\\) closed\\.`), `close report names B as root, count=4, spared=0\n${closeRes.stdout}`);
+        // ===================================================================
+        // ASSERT 1 — the A5 DELIVERABLE: the EXACT terminal status of every
+        // cascade-closed node. With the fixtures now non-empty, close exercises
+        // cancel+notice semantics and the rows remain present as canceled husks.
+        // ===================================================================
+        for (const id of subtree) {
+            const n = h.node(id);
+            assert.equal(n.status, 'canceled', `${id} terminal status === 'canceled' (cancel event)`);
+            assert.strictEqual(n.intent ?? null, null, `${id} intent cleared to null on cancel`);
+        }
+        // Pin the exact field tuple once more, explicitly, for the human decision:
+        // a cascade-closed descendant under `node lifecycle close` reads (canceled, null) —
+        // NOT (done, done) and NOT (done, null). This is the confirmed A5 fact.
+        {
+            const e = h.node(E); // the deepest descendant
+            assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest closed descendant E: (status,intent) === ('canceled', null)");
+        }
+        // ===================================================================
+        // ASSERT 2 — broker ENGINE torn down for the ENTIRE subtree (the real
+        // "node is up" invariant now: a closed node owns no live broker process).
+        // close → headlessBrokerHost.teardown shut each broker down over view.sock.
+        // ===================================================================
+        for (const id of subtree) {
+            await h.waitFor(() => {
+                const pid = h.node(id)?.pi_pid ?? null;
+                return pid === null || !isPidAlive(pid);
+            }, { label: `${id} broker engine torn down by close` });
+            const pid = h.node(id)?.pi_pid ?? null;
+            assert.ok(pid === null || !isPidAlive(pid), `${id} broker engine destroyed by close`);
+        }
+        // ===================================================================
+        // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
+        // SIDEWAYS (S, G) was reaped. close(B) canceled EXACTLY B's own subtree.
+        // ===================================================================
+        // 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');
+            // 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 broker engine alive.
+        for (const id of sideways) {
+            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not canceled`);
+            const pid = h.node(id).pi_pid;
+            assert.ok(pid != null && isPidAlive(pid), `${id} (sideways) broker engine still alive`);
+        }
+        // The strong "EXACTLY its own subtree" closure: every node in the graph is
+        // either in B's subtree (canceled) or untouched (active) — no over-reach.
+        {
+            const reaped = new Set(subtree);
+            for (const id of [A, B, C, D, E, S, G]) {
+                const want = reaped.has(id) ? 'canceled' : 'active';
+                assert.equal(h.status(id), want, `${id} status === '${want}' (no over-/under-reach)`);
+            }
+        }
+        // ===================================================================
+        // ASSERT 4 — EDGES PERSIST (CURRENT behavior + ORACLE §4). close is a pause,
+        // not a delete: a closed node keeps its spine + provenance edges so it can
+        // be revived. (FLAGGED in the report: the task brief expected "edges
+        // removed" — that contradicts current behavior; we assert persistence.)
+        // ===================================================================
+        {
+            const subIds = (n) => h.subscriptions(n).map((s) => s.node_id).sort();
+            // Ancestor's spine edge to the closed middle node survives.
+            assert.ok(h.subscriptions(A).some((s) => s.node_id === B && s.active), 'A→B subscription edge PERSISTS after close (revivable)');
+            // Intra-subtree spine edges survive too.
+            assert.deepEqual(subIds(B), [C, D].sort(), 'B→{C,D} edges persist');
+            assert.deepEqual(subIds(C), [E], 'C→E edge persists');
+            // Provenance (spawned_by / parent) survives.
+            for (const [child, parent] of [[B, A], [C, B], [E, C], [D, B]]) {
+                assert.equal(h.node(child).parent, parent, `${child}.parent = ${parent} persists`);
+            }
+            // Sideways edges obviously untouched.
+            assert.deepEqual(subIds(S), [G], 'S→G edge untouched');
+        }
+        // ===================================================================
+        // ASSERT 5 — each closed node got its cancellation notice (the resume
+        // breadcrumb), appended AFTER its watcher died (close.ts step 3). The root
+        // B reads "CLOSED by the user"; descendants read "CANCELED — an ancestor…".
+        // ===================================================================
+        {
+            const bNotice = h.inbox(B).at(-1);
+            assert.equal(bNotice.from, null, "B's cancel notice is a system message");
+            assert.match(bNotice.label, /CLOSED by the user/, 'B (cascade root) reads the CLOSED notice');
+            assert.equal(bNotice.data?.['cascade_root'], B, "B notice records the cascade root");
+            const eNotice = h.inbox(E).at(-1);
+            assert.match(eNotice.label, /CANCELED/, 'E (descendant) reads the CANCELED notice');
+            assert.equal(eNotice.data?.['cascade_root'], B, "E notice records B as the cascade root");
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/full/consult-startup-failure.test.d.ts

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

package/dist/core/__tests__/full/consult-startup-failure.test.js

@@ -0,0 +1,124 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/consult-startup-failure.test.ts
+//
+// Regression: an exact-model consultation can reject inside runBroker before
+// session_start. Its durable private-fork claim remains active for lifecycle
+// recovery; the daemon sees the fatal model fault, terminalizes the node, and
+// reconciles the armed receipt so the request receives an error.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readFollowUp, registerInboxRoot, requestFollowUp } from '@crouton-kit/humanloop';
+import { closeDb } from '../../canvas/db.js';
+import { armFollowUpWork, getFollowUpWorkRow } from '../../canvas/human-work-outbox.js';
+import { buildLaunchSpec } from '../../runtime/launch.js';
+import { spawnNode } from '../../runtime/nodes.js';
+import { readFault } from '../../runtime/fault.js';
+import { isPidAlive, runStartupRecoverySweep } from '../../../daemon/crtrd.js';
+import { MAX_RESPAWN_ATTEMPTS } from '../../../daemon/fleet.js';
+import { createHarness } from '../helpers/harness.js';
+let h;
+let stateHome;
+let priorStateHome;
+before(async () => {
+    priorStateHome = process.env['XDG_STATE_HOME'];
+    stateHome = mkdtempSync(join(tmpdir(), 'crtr-consult-fatal-state-'));
+    process.env['XDG_STATE_HOME'] = stateHome;
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-consult-fatal' });
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+    rmSync(stateHome, { recursive: true, force: true });
+    if (priorStateHome === undefined)
+        delete process.env['XDG_STATE_HOME'];
+    else
+        process.env['XDG_STATE_HOME'] = priorStateHome;
+});
+test('pre-session exact-consult failure is terminalized and delivered by daemon supervision', async () => {
+    const bridgeId = h.spawnRoot('consult bridge');
+    const interactionRoot = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-consult-fatal-root-')));
+    const ticketDir = join(interactionRoot, 'ticket-1');
+    mkdirSync(ticketDir);
+    // humanloop recognizes registered direct children as tickets only once a
+    // request descriptor exists; its contents are immaterial to this follow-up.
+    writeFileSync(join(ticketDir, 'deck.json'), '{}\n');
+    const benignHandler = { command: process.execPath, args: ['-e', ''] };
+    const registeredRoot = registerInboxRoot({
+        root: interactionRoot,
+        owner: 'crouter',
+        handler: benignHandler,
+        followUpHandler: benignHandler,
+    }).root;
+    const request = requestFollowUp(registeredRoot, ticketDir, { question: 'What should change?' });
+    const branchFile = join(ticketDir, 'branch-point.jsonl');
+    writeFileSync(branchFile, `${JSON.stringify({ type: 'session', id: 'source-session' })}\n`);
+    // The fake registry observes this sentinel live. Exact mode therefore rejects
+    // this captured model during launch rather than substituting or booting
+    // model-less — the production failure that originally stranded the request.
+    writeFileSync(join(h.home, 'fake-pi.no-auth'), '1');
+    const forkId = 'private-fatal-consult';
+    const exactModel = 'openai-codex/unavailable:xhigh';
+    const { launch } = buildLaunchSpec('general', 'base', {
+        lifecycle: 'terminal',
+        hasManager: false,
+        model: exactModel,
+        modelExact: true,
+        cwd: process.cwd(),
+        profileId: null,
+    });
+    armFollowUpWork({ nodeId: forkId, root: registeredRoot, dir: ticketDir, requestId: request.requestId });
+    spawnNode({
+        nodeId: forkId,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        cwd: process.cwd(),
+        parent: null,
+        spawnedBy: bridgeId,
+        forkFrom: branchFile,
+        modelOverride: exactModel,
+        humanWorkTarget: { work_kind: 'follow_up', root: registeredRoot, dir: ticketDir, request_id: request.requestId },
+        privateForkPhase: 'fork_pending',
+        privateForkRecipe: { kickoff: request.question },
+        launch,
+    });
+    assert.equal(h.node(forkId)?.pi_pid ?? null, null, 'the persisted claim starts with no broker');
+    // This row models a fork_pending claim left by the prior daemon epoch. The
+    // explicit startup sweep — not a recurring liveness tick — classifies row 7
+    // and launches its bounded fresh retry through the harness-owned fleet.
+    await runStartupRecoverySweep(h.fleet);
+    await h.waitFor(() => h.node(forkId)?.pi_pid !== null, { label: 'startup sweep launched the durable pending claim' });
+    await h.waitFor(() => readFault(forkId)?.kind === 'model-not-found', { label: 'fatal exact-model fault recorded' });
+    // A broker writes the launch fault immediately before it exits. Its real
+    // ChildProcess exit removes the fleet entry and enqueues a policy job.
+    await h.waitFor(() => {
+        const pid = h.node(forkId)?.pi_pid;
+        return pid !== null && pid !== undefined && !isPidAlive(pid) ? true : null;
+    }, { label: 'fatal consult broker exited after recording its launch fault' });
+    await h.waitFor(() => !h.fleet.has(forkId) ? true : null, { label: 'fatal consult exit left the live fleet' });
+    await h.drainFleet();
+    // Design flow B row 7: a fork_pending death is a bounded fresh retry of the
+    // immutable fork birth — throttled, NOT an immediate boot failure. Every
+    // further short-lived exit increments the same counter, and at
+    // MAX_RESPAWN_ATTEMPTS the respawn loop terminalizes: transition('crash') +
+    // receipt reconcile + surfaceBootFailure + doctrine wake. The real exit above
+    // counted one failure; deliver the remaining short exits synthetically
+    // through the sanctioned seam (§H mode b) so the cap is reached without
+    // minutes of real backoff — each delivery cancels the pending backoff timer,
+    // so no intermediate respawn ever launches.
+    for (let i = 1; i < MAX_RESPAWN_ATTEMPTS; i++) {
+        await h.deliverExit(forkId, { code: 1, signal: null });
+    }
+    await h.waitFor(() => {
+        closeDb();
+        return getFollowUpWorkRow(forkId)?.status === 'errored';
+    }, { timeoutMs: 5_000, label: 'fatal consult receipt settled at throttle exhaustion' });
+    assert.equal(h.status(forkId), 'dead', 'the failed consult fork is terminalized after the fatal launch fault');
+    const followUp = readFollowUp(ticketDir);
+    assert.equal(followUp.request?.state, 'terminal', 'the humanloop request is no longer running');
+    assert.equal(followUp.result?.requestId, request.requestId);
+    assert.equal(followUp.result?.status, 'error');
+    rmSync(interactionRoot, { recursive: true, force: true });
+});

package/dist/core/__tests__/full/detach-focus.test.d.ts

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

package/dist/core/__tests__/full/detach-focus.test.js

@@ -0,0 +1,126 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/detach-focus.test.ts
+//
+// `crtr node demote --detach` on a node with a live viewer (Alt+C → D).
+//
+// BROKER-CUT ADAPTATION (taste/broker-is-the-host, 2026-06-10): every node is a
+// detached headless broker. After a09b71f a managed child opens NO viewer on
+// spawn — a viewer is opened on demand via `surface node focus`, registering
+// its `crtr surface attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
+// pre-cut "relocate the still-running pi pane to the backstage" behavior —
+// detachToBackground's engine break-pane/release path, and its isGenerating()
+// gate that released a non-generating node to dormant — is DELETED. The Bug-1
+// non-generating-release test that locked that gate is deleted with it (the
+// behavior no longer exists; nothing to invent coverage for).
+//
+// What SURVIVES and is locked here: `node demote --detach` flips the node
+// terminal IN PLACE and CLOSES its viewer pane + focus row, leaving the broker
+// ENGINE running untouched (reconnectable by a later `focus`). This drives the
+// REAL verb (subprocess, AS the node) — the actual Alt+C → D menu path — against
+// a live broker node genuinely focused in a viewer pane, and proves:
+//   (a) lifecycle flips terminal in place,
+//   (b) the broker engine keeps running (pi_pid alive, unchanged — NOT killed),
+//   (c) the viewer pane is closed + its focus row dropped (no orphaned/phantom
+//       viewport row — Invariant P / F5).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHarness, hasTmux, TMUX_TIMEOUT_MS } from '../helpers/harness.js';
+import { paneTag, taggedViewerPanes, waitForOneTaggedViewer } from '../helpers/viewer-panes.js';
+import { getNode } from '../../canvas/canvas.js';
+import { closeDb } from '../../canvas/db.js';
+import { isPidAlive } from '../../canvas/pid.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return (spawnSync('tmux', ['has-session', '-t', session], {
+        stdio: 'ignore',
+        timeout: TMUX_TIMEOUT_MS,
+    }).status === 0);
+}
+function paneExistsReal(pane) {
+    return ((spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
+        encoding: 'utf8',
+        timeout: TMUX_TIMEOUT_MS,
+    }).stdout ?? '').trim() === pane);
+}
+// P1 moved the `surface node focus` viewer registry off the `focuses` DB table (the CLI
+// can no longer write canvas.db) onto the tmux `@crtr_node` pane tag a
+// `crtr surface attach` viewer self-sets on connect. These helpers read that
+// pane-tag registry — the ground truth for "which pane is a node's viewer".
+// `paneTag` / `taggedViewerPanes` / `waitForOneTaggedViewer` live in
+// helpers/viewer-panes.ts, shared with the other full-tier viewer tests.
+// Split a throwaway pane in the harness session; return its %id. The caller pane
+// `surface node focus` opens the viewer beside (a09b71f: spawn no longer auto-opens one).
+// Write an assistant message into a node's pi session so it is NOT an empty
+// shell — reapIfEmpty (0515e8d) tears output-less nodes down on detach, which
+// would defeat the "broker survives" contract this test locks.
+function seedAssistantSession(sessionFile) {
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+}
+function makePane(session) {
+    const r = spawnSync('tmux', ['split-window', '-d', '-t', session, '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS });
+    const pane = (r.stdout ?? '').trim();
+    assert.ok(pane.startsWith('%'), `expected a %pane_id, got "${pane}" (stderr: ${r.stderr})`);
+    return pane;
+}
+// ===========================================================================
+// `crtr node demote --detach` on a node with a live viewer (Alt+C → D).
+// ===========================================================================
+test('node demote --detach: flips terminal in place, CLOSES the viewer pane + focus row, broker engine keeps running', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-detach-focus' });
+    try {
+        // A resident root + a live terminal child B. spawnChild launches B's broker
+        // but opens NO viewer (a09b71f) — so B has no focus row yet.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const b0 = h.node(B);
+        assert.equal(b0.lifecycle, 'terminal', 'B born terminal');
+        assert.equal(b0.status, 'active', 'B active after boot');
+        const brokerPid = b0.pi_pid;
+        assert.ok(brokerPid != null && isPidAlive(brokerPid), 'B broker engine alive before detach');
+        // Make B NON-EMPTY (it produced an assistant message) so `--detach`
+        // exercises the "close the viewer, broker survives" contract and NOT the
+        // reap-empty path (0515e8d), which would tear an output-less shell down.
+        assert.ok(b0.pi_session_file != null, 'B has a session file');
+        seedAssistantSession(b0.pi_session_file);
+        // Put B genuinely "on screen": `surface node focus` opens its one `crtr surface attach`
+        // VIEWER pane beside a caller pane in the harness session — the on-demand
+        // viewer the detach then tears down.
+        const caller = makePane(h.session);
+        const focusRes = h.cli(B, ['surface', 'node', 'focus', B, '--pane', caller]);
+        assert.equal(focusRes.code, 0, `surface node focus B exit 0\n${focusRes.stderr}`);
+        // The viewer pane is the node's on-screen presence, registered by the
+        // `@crtr_node` pane tag the attach client self-sets on connect (P1: the CLI
+        // no longer writes the focuses DB table) — NOT a node-row pane (a broker
+        // carries null placement). Wait for the tag so the real registry is live.
+        const viewerPane = await waitForOneTaggedViewer(h.session, B);
+        assert.equal(paneExistsReal(viewerPane), true, 'B viewer pane is live on screen');
+        // --- Drive the REAL verb on the focused node (the Alt+C → D menu path). ---
+        const res = h.cli(B, ['node', 'lifecycle', 'demote', '--node', B, '--pane', viewerPane, '--detach']);
+        assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
+        assert.match(res.stdout, /viewer closed \(broker still running off-screen\)/, `the viewer was closed\n${res.stdout}`);
+        closeDb();
+        const b = getNode(B);
+        // (a) lifecycle flipped to terminal IN PLACE (it was already terminal; the
+        //     demote is idempotent on lifecycle — the point is it does not end B).
+        assert.equal(b.lifecycle, 'terminal', '(a) B lifecycle=terminal after the flip');
+        assert.equal(b.status, 'active', '(a) detach does NOT end the node — B stays active');
+        // (b) the broker ENGINE keeps running — detach closes only the viewer, never
+        //     the engine (the one-host invariant: the engine was never in a pane).
+        assert.equal(b.pi_pid, brokerPid, "(b) B's broker pid is UNCHANGED (engine not killed/respawned)");
+        assert.equal(isPidAlive(brokerPid), true, '(b) B broker engine still alive off-screen');
+        // (c) the viewer pane is CLOSED and its focus row dropped — no orphaned /
+        //     phantom viewport (A3 hazard / Invariant P).
+        await h.waitForPaneGone(B);
+        assert.equal(paneExistsReal(viewerPane), false, '(c) B viewer pane closed');
+        assert.deepEqual(taggedViewerPanes(h.session, B), [], '(c) B no longer occupies any viewer (untagged — Invariant P)');
+        assert.equal(paneTag(viewerPane), '', '(c) NO phantom @crtr_node tag resolves on the closed viewer %id');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/full/idle-release-settlement.test.d.ts

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

package/dist/core/__tests__/full/idle-release-settlement.test.js

@@ -0,0 +1,108 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/idle-release-settlement.test.ts
+//
+// Issue #222: a real idle-release cycle must settle the inbox watcher before the
+// broker exits. The daemon may only revive for a row strictly after that cursor.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
+import { subscribe, updateNode } from '../../canvas/index.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { createHarness } from '../helpers/harness.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-settle' });
+    root = h.spawnRoot('settlement suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+async function awaitReleased(nodeId) {
+    await h.waitFor(() => {
+        const node = h.node(nodeId);
+        return node?.status === 'idle' && node.intent === 'idle-release' && typeof node.pi_pid === 'number' && !isPidAlive(node.pi_pid);
+    }, { label: `idle-release broker exit for ${nodeId}` });
+}
+test('idle-release settles its real watcher before exit; daemon revives exactly once for a later row', { timeout: 30_000 }, async () => {
+    // Reproduce the observed #353/#362 edge: real pi reported
+    // ctx.hasPendingMessages() === true at the sole agent_settled even though the
+    // run had genuinely finished. Persisted on the manager's own launch.env
+    // (never ambient process.env) so BOTH this broker's launch AND its later
+    // daemon-driven revive for the second row see it: a CLI-spawned child's
+    // ambient env never reaches the broker child process (spawn-env.ts's
+    // default-deny allowlist only admits `inv.env`, which `nodeEnv()` derives
+    // from the node's persisted `meta.launch.env`, not the calling process's
+    // env) — so the manager is built by fabricating the row, persisting
+    // launch.env, and calling reviveNode rather than through `spawnHeadlessChild`.
+    //
+    // The same launch.env carries the REAL canvas-inbox-watcher's injectable
+    // cadence seam (CRTR_WATCHER_TICK_MS / CRTR_WATCHER_DEBOUNCE_MS — the same
+    // seam canvas-inbox-watcher.test.ts/canvas-inbox-watcher-hold.test.ts/
+    // deferred-no-wake.test.ts already drive fast, there via ambient env since
+    // they run the watcher in-process). Left at the production 800ms/1000ms
+    // default, this test's two full delivery cycles bake in >=3.6s of pure
+    // wall-clock polling on top of two real broker boots — negligible in
+    // isolation, but on a loaded CI runner deep in the serial `heavy` lane (the
+    // only heavy-tier test that calls h.awaitWake()'s real, non-overridable 15s
+    // cap) that starved interval tick has repeatedly lost the race and timed
+    // out (issue: CI runs 29549096301/29549658681/29550017548, always at the
+    // first h.awaitWake). Driving the cadence fast here removes the wall-clock
+    // dependency entirely without weakening what's under test: the settlement
+    // lifecycle, cursor semantics, and hasPendingMessages veto are all
+    // independent of how fast the watcher polls.
+    const manager = h.fabricateBrokerNode({ id: 'settle-veto-manager', status: 'idle', parent: root });
+    updateNode(manager, {
+        launch: {
+            extensions: [],
+            tools: [],
+            systemPrompt: '',
+            env: {
+                CRTR_FAKE_ENGINE_PENDING_AT_SETTLE: '1',
+                CRTR_WATCHER_TICK_MS: '20',
+                CRTR_WATCHER_DEBOUNCE_MS: '25',
+            },
+        },
+    });
+    reviveNode(manager, { resume: true });
+    await h.awaitBoot(manager);
+    // A live managed child makes this unfocused terminal manager legitimately
+    // awaiting, so its real stophook takes the idle-release branch.
+    const worker = h.fabricateBrokerNode({ parent: manager, status: 'idle', intent: 'idle-release' });
+    subscribe(manager, worker, true);
+    const first = appendInbox(manager, {
+        from: 'worker-a',
+        tier: 'normal',
+        kind: 'final',
+        label: 'first completed',
+        data: { body: 'first completed' },
+    });
+    await h.awaitWake(manager, { match: /first completed/ });
+    // The real watcher injects an idle message, whose fake session now starts and
+    // settles its own prompt lifecycle: watcher → engine → stophook → settle →
+    // broker exit. No test-driven turn or settlement dispatch is involved.
+    await awaitReleased(manager);
+    assert.equal(readCursor(manager), first.entry_id, 'the exact handed-off row commits before clean shutdown');
+    const cyclesAfterRelease = h.node(manager).cycles ?? 0;
+    await h.tick();
+    assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease, 'a second supervision tick does not revive a settled row');
+    const injectedBeforeSecond = h.injected(manager).length;
+    const second = appendInbox(manager, {
+        from: 'worker-b',
+        tier: 'normal',
+        kind: 'final',
+        label: 'second completed',
+        data: { body: 'second completed' },
+    });
+    assert.ok(readInboxSince(manager, first.entry_id).some((entry) => entry.entry_id === second.entry_id), 'the next row is physically after the committed cursor');
+    assert.equal(readInboxSince(manager, second.entry_id).length, 0, 'the physical cursor boundary is exclusive');
+    await h.tick();
+    assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease + 1, 'one later row revives once');
+    await h.awaitBoot(manager, { minCount: 2 });
+    await h.awaitWake(manager, { sinceCount: injectedBeforeSecond, match: /second completed/ });
+    await awaitReleased(manager);
+    assert.equal(readCursor(manager), second.entry_id, 'the later row commits at its own natural idle release');
+    await h.tick();
+    assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease + 1, 'the settled later row does not cause a duplicate revival');
+});

package/dist/core/__tests__/full/issue-146-yield-spawn-focus.test.d.ts

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