@north-light/crouter 0.3.240 → 0.3.242

package/dist/core/__tests__/daemon-boot.test.js

@@ -93,12 +93,6 @@ test('never-booted broker exit is marked dead and surfaced to the parent as urge
     assert.ok(wake, 'the doctrine wake rides beside the urgent push');
     assert.match(wake.label, /crashed/i);
 });
-// surfaceChildDeath was DELETED, and the node-lifecycle tick recovers a crashed
-// booted child through the SAME policy table its exit event would have used
-// (design D-12), so tick recovery and exit recovery can never diverge. A row
-// whose recorded pid is provably dead and whose session was recorded is a
-// resumable crash: it is relaunched on that saved session, never reaped to
-// `dead` and never announced as a boot failure or a child death.
 test('a crashed booted child is relaunched on its saved session, not reaped, and raises no false boot-failure alarm', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const launches = [];
@@ -123,8 +117,6 @@ test('a crashed booted child is relaunched on its saved session, not reaped, and
         await superviseTick();
         assert.deepEqual(launches, ['C2'], 'the tick recovers the crash through the policy table, exactly as the exit event would');
         assert.equal(getNode('C2').status, 'active', 'crashed booted child is relaunched, NOT marked dead');
-        // surfaceChildDeath is gone and this is not a never-booted node, so the daemon
-        // fans NO push here — no false boot-failure / child-death alarm on a crash.
         assert.equal(readInboxSince('P2').length, 0, 'no false boot-failure / child-death push on a crash (wake relocated to push/close)');
         clearBusy('C2');
     }

package/dist/core/__tests__/dead-node-policy-table.test.js

@@ -2,8 +2,7 @@
 //
 // The invariant-5 policy table (design flow B): `classifyDeadNode` is the ONE
 // pure function mapping a known-dead node's durable row state to its recovery
-// action, used at exactly two call sites — the exit-policy job and the startup
-// recovery sweep — so exit recovery and startup recovery can never diverge.
+// action, used by the exit-policy job and the row-driven supervision tick.
 // This file pins every table row directly.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';

package/dist/core/__tests__/integration/deferred-no-wake.test.js

@@ -44,7 +44,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
-import { createNode, deleteNode, getNode, setStatus, withFreshTerminalGuard } from '../../canvas/canvas.js';
+import { createNode, deleteNode, getNode, setFrozen, setStatus, withFreshTerminalGuard } from '../../canvas/canvas.js';
 import { hasNoNaturalCycle } from '../../runtime/revive-all.js';
 import { canvasDbPath, nodeDir, apiSocketPath } from '../../canvas/paths.js';
 import { closeDb } from '../../canvas/db.js';
@@ -170,7 +170,7 @@ test('node message send --tier deferred to an ordinary dormant (idle-released) t
     assert.equal(after.status, 'idle', 'target left exactly where it was');
     assert.equal(after.intent, 'idle-release', 'target left exactly where it was');
 });
-test('node message send --tier deferred to a terminal target (done/canceled — no natural next cycle) is rejected before any side effect', { timeout: 30_000 }, async () => {
+test('node message send --tier deferred rejects ordinary terminal targets but accepts a frozen terminal target with a thaw cycle owed', { timeout: 30_000 }, async () => {
     for (const status of ['done', 'canceled']) {
         const id = `terminal-${status}`;
         createNode(node(id, { status, intent: null }));
@@ -190,6 +190,18 @@ test('node message send --tier deferred to a terminal target (done/canceled —
         assert.equal(launchCalls, 0, `${status}: a rejected deferred must never attempt a revive`);
         assert.equal(readInboxSince(id, undefined).length, inboxBefore, `${status}: a rejected deferred must not append an inbox entry`);
     }
+    const frozenId = 'terminal-frozen';
+    createNode(node(frozenId, {
+        lifecycle: 'resident',
+        status: 'done',
+        intent: 'parked',
+    }));
+    setFrozen(frozenId, new Date().toISOString());
+    const inboxBefore = readInboxSince(frozenId, undefined).length;
+    const result = await messageSendLeaf().run({ to: frozenId, tier: 'deferred', body: 'held for thaw' });
+    assert.equal(result['guidance'], "Delivered — held for the target's next natural cycle; not revived.", 'a frozen terminal row still has a thaw cycle');
+    assert.equal(result['revived'], false, 'deferred mail waits for the thaw without launching');
+    assert.equal(readInboxSince(frozenId, undefined).length, inboxBefore + 1, 'the deferred message is durably appended');
 });
 // #343 third-fix-cycle review: the IMMEDIATE `--tier deferred` path had its
 // own, separate TOCTOU — a stale-snapshot check (`rejectDeferredWithoutNaturalCycle`)

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

@@ -133,17 +133,17 @@ test('yield: illegal from done|dead|canceled → throws', () => {
         assert.throws(() => transition(`n_${from}`, 'yield'), /illegal lifecycle transition/);
     }
 });
-// release → idle + intent='idle-release', legal only from active|idle
-test('release: active|idle → idle + intent=idle-release', () => {
-    for (const from of LIVE) {
+// release → idle + intent='idle-release', legal from active|idle|done
+test('release: active|idle|done → idle + intent=idle-release', () => {
+    for (const from of [...LIVE, 'done']) {
         mk(`n_${from}`, from);
         const m = transition(`n_${from}`, 'release');
         assert.equal(m.status, 'idle', `release from ${from}`);
         assert.equal(m.intent, 'idle-release', `release from ${from} sets intent=idle-release`);
     }
 });
-test('release: illegal from done|dead|canceled → throws', () => {
-    for (const from of TERMINAL) {
+test('release: illegal from dead|canceled → throws', () => {
+    for (const from of ['dead', 'canceled']) {
         mk(`n_${from}`, from);
         assert.throws(() => transition(`n_${from}`, 'release'), /illegal lifecycle transition/);
     }

package/dist/core/__tests__/relaunch-root.test.js

@@ -8,12 +8,18 @@
 // behavior via the injectable deps seam, so they run tmux-free and broker-free.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { CrtrClient } from '../../api/client.js';
+import { createApiServer } from '../../daemon/api/server.js';
+import registerCanvasStophook from '../../pi-extensions/canvas-stophook.js';
 import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
+import { apiSocketPath } from '../canvas/paths.js';
+import { brokerCapReached, resetFleetForTests } from '../runtime/fleet.js';
 import { relaunchRoot } from '../runtime/reset.js';
+import { bindTestFleet } from './helpers/fleet.js';
 let home;
 function node(id, over = {}) {
     return {
@@ -31,6 +37,20 @@ function node(id, over = {}) {
 /** A tmux-free / broker-free deps seam. `pid` controls the new broker launch:
  *  a number = success, null = a boot failure. Records the node ids launchBroker
  *  was called with, so the boot-failure test can find the half-born new node. */
+async function waitForApi() {
+    const client = CrtrClient.forLocalSocket({ autostart: false });
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(apiSocketPath())) {
+            try {
+                await client.healthz();
+                return;
+            }
+            catch { /* the socket can appear before it accepts */ }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    throw new Error('API socket did not become ready');
+}
 function makeDeps(pid) {
     const launched = [];
     const deps = {
@@ -102,6 +122,76 @@ test('relaunchRoot on a boot failure leaves the old root + descendants fully int
     assert.equal(launched.length, 1, 'one broker launch was attempted');
     assert.equal(getNode(launched[0])?.status, 'dead', 'the half-born new node is crashed (dead)');
 });
+test('relaunchRoot at capacity refuses visibly and settles the half-born row before preserving the old root', async () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('child', { parent: 'root' }));
+    subscribe('root', 'child', true);
+    const launched = [];
+    const deps = {
+        launchBroker: (nodeId) => {
+            launched.push(nodeId);
+            throw brokerCapReached(2, 2);
+        },
+        waitForViewSocket: () => true,
+        respawnViewer: () => true,
+        teardownBroker: () => { },
+    };
+    await assert.rejects(() => relaunchRoot('root', deps), (error) => {
+        const details = error.details ?? {};
+        assert.equal(details['error'], 'broker_cap_reached');
+        assert.match(String(details['message']), /2 live brokers at the cap of 2/);
+        return true;
+    });
+    assert.equal(getNode('root')?.status, 'active', 'the old root remains live');
+    assert.equal(getNode('child')?.status, 'active', 'its descendants remain live');
+    assert.equal(launched.length, 1);
+    assert.equal(getNode(launched[0])?.status, 'dead', 'the half-born replacement is terminal, not an active pid-less strand');
+});
+test('root /new capacity refusal reaches the attached human through broker UI notify', async () => {
+    process.env['CRTR_MAX_LIVE_BROKERS'] = '2';
+    process.env['CRTR_NODE_ID'] = 'root';
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    const tf = bindTestFleet();
+    const never = new Promise(() => { });
+    tf.fleet.register('filler-a', { pid: 700_001, exited: never });
+    tf.fleet.register('filler-b', { pid: 700_002, exited: never });
+    const server = createApiServer();
+    try {
+        await waitForApi();
+        let sessionStart;
+        registerCanvasStophook({
+            on(event, handler) {
+                if (event === 'session_start')
+                    sessionStart = async (ev, ctx) => { await handler(ev, ctx); };
+            },
+            sendUserMessage() { },
+            sendMessage() { },
+        });
+        let resolveNotice;
+        const notice = new Promise((resolve) => { resolveNotice = resolve; });
+        await sessionStart?.({ reason: 'new' }, {
+            sessionManager: {
+                getSessionId: () => 'root-new-session',
+                getSessionFile: () => null,
+                getEntries: () => [],
+            },
+            ui: { notify: (message) => resolveNotice(message) },
+        });
+        const message = await Promise.race([
+            notice,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('capacity notice was not shown')), 1_000)),
+        ]);
+        assert.match(message, /^\/new refused: no broker slot is free/);
+        assert.match(message, /2 live brokers at the cap of 2/);
+    }
+    finally {
+        await server.close();
+        tf.fleet.dispose();
+        resetFleetForTests();
+        delete process.env['CRTR_MAX_LIVE_BROKERS'];
+        delete process.env['CRTR_NODE_ID'];
+    }
+});
 test('relaunchRoot is a no-op for a non-root child and an already-parked root', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('child', { parent: 'root' }));

package/dist/core/__tests__/revive-capacity.test.js

@@ -10,15 +10,18 @@
 // finally happens retires the mark.
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, getNode } from '../canvas/canvas.js';
+import { jobDir } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
 import { bindDaemonEventSource, resetEventSourceForTests } from '../events/source.js';
 import { resetFleetForTests } from '../runtime/fleet.js';
+import { CANVAS_EXTENSIONS } from '../runtime/canvas-extensions.js';
 import { headlessBrokerHost } from '../runtime/host.js';
 import { reviveNode } from '../runtime/revive.js';
+import { deliverNodeMessage } from '../../daemon/messaging/node-message.js';
 import { bindTestFleet } from './helpers/fleet.js';
 let home;
 let tf;
@@ -89,6 +92,24 @@ test('a refusing caller gets an error naming the cap and the live count, never a
     assert.equal(meta.pi_session_id, 'sess-refused', 'the refusal happens before any mutation of the session identity');
     assert.equal(meta.cycles ?? 0, 0, 'a node turned away never spent a cycle');
 });
+test('a pre-spawn launch failure releases the reservation', () => {
+    const id = node('pre-spawn-failure');
+    mkdirSync(join(jobDir(id), 'broker.log'));
+    headlessBrokerHost.launch = originalLaunch;
+    try {
+        assert.throws(() => headlessBrokerHost.launch(id, {
+            argv: CANVAS_EXTENSIONS.flatMap((path) => ['-e', path]),
+            env: {},
+        }, { cwd: home, name: id, resuming: false }), /EISDIR/);
+        assert.equal(tf.fleet.occupancy(), 0, 'the failed launch leaves no slot reserved');
+        assert.equal(tf.fleet.reserveSlot(id), true, 'the same node can claim the released slot immediately');
+        tf.fleet.releaseReservation(id);
+        assert.equal(tf.fleet.occupancy(), 0);
+    }
+    finally {
+        stubLaunch();
+    }
+});
 test('a freezing caller gets a frozen row, marked once and left otherwise untouched', () => {
     saturate();
     const waiting = node('frozen', { pi_session_id: 'sess-frozen' });
@@ -102,6 +123,20 @@ test('a freezing caller gets a frozen row, marked once and left otherwise untouc
     assert.equal(second.outcome, 'frozen');
     assert.equal(getNode(waiting).frozen_at, marked.frozen_at, 'freezing is once-per-episode: a second saturated tick keeps the original wait timestamp');
 });
+test('a durable daemon message reports capacity_frozen when its wake cannot launch', async () => {
+    saturate();
+    const waiting = node('message-frozen');
+    const delivery = await deliverNodeMessage({
+        node_id: waiting,
+        body: 'capacity-delayed notice',
+        label: 'notice',
+        mode: 'wake',
+    });
+    assert.equal(delivery.via, 'inbox');
+    assert.ok(delivery.entry_id !== null, 'the message stays durable while the broker waits');
+    assert.equal(delivery.revived, false);
+    assert.equal(delivery.reason, 'capacity_frozen');
+});
 test('an already-live node is admitted at the cap — it consumes no new slot', () => {
     const live = node('already-live');
     reviveNode(live, { resume: false, capacity: 'refuse' });

package/dist/core/__tests__/seam/broker-cap-freeze.test.js

@@ -12,9 +12,14 @@
 // by the daemon pass, so it belongs in the compiled seam tier.
 import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
+import { createNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
 import { isPidAlive } from '../../canvas/pid.js';
+import { appendInbox } from '../../feed/inbox.js';
 import { closeNode } from '../../runtime/close.js';
+import { headlessBrokerHost } from '../../runtime/host.js';
+import { transition } from '../../runtime/lifecycle.js';
+import { reviveNode } from '../../runtime/revive.js';
 import { spawnChild } from '../../runtime/spawn.js';
 import { createHarness } from '../helpers/harness.js';
 let h;
@@ -31,6 +36,34 @@ after(async () => {
         await h.dispose();
     delete process.env['CRTR_MAX_LIVE_BROKERS'];
 });
+test('node new reports a frozen delegated birth without claiming its broker started', { timeout: 120_000 }, async () => {
+    const created = [];
+    try {
+        for (const prompt of ['first API child', 'second API child']) {
+            const result = h.cli(root, ['--json', 'node', 'new', '--kind', 'general', prompt]);
+            assert.equal(result.code, 0, `node new should succeed\n${result.stderr}`);
+            const nodeId = result.json.node_id;
+            created.push(nodeId);
+            await h.awaitBoot(nodeId);
+        }
+        const frozen = h.cli(root, ['--json', 'node', 'new', '--kind', 'general', 'frozen API child']);
+        assert.equal(frozen.code, 0, `node new should record the frozen birth\n${frozen.stderr}`);
+        const output = frozen.json;
+        created.push(output.node_id);
+        assert.ok(output.frozen_at !== undefined, 'JSON reports the durable frozen birth detail');
+        assert.match(output.follow_up, /Child row exists, but no broker started because capacity is full/);
+        const prose = h.cli(root, ['node', 'new', '--kind', 'general', 'another frozen API child']);
+        assert.equal(prose.code, 0, `node new should report capacity in prose\n${prose.stderr}`);
+        assert.match(prose.stdout, /Child row exists, but no broker started because capacity is full/);
+        const proseNode = prose.stdout.match(/\(([^)]+)\)/)?.[1];
+        assert.ok(proseNode !== undefined, 'prose names the created frozen row');
+        created.push(proseNode);
+    }
+    finally {
+        for (const nodeId of created)
+            h.cli(root, ['node', 'lifecycle', 'close', '--node', nodeId]);
+    }
+});
 test('a birth at the cap freezes instead of booting, survives saturated ticks, and thaws when a slot frees', { timeout: 120_000 }, async () => {
     const first = await h.spawnHeadlessChild(root, 'first live child');
     const second = await h.spawnHeadlessChild(root, 'second live child');
@@ -78,4 +111,44 @@ test('a birth at the cap freezes instead of booting, survives saturated ticks, a
     assert.equal(h.fleet.has(third), true, 'the freed slot is now the thawed node\u2019s');
     assert.equal(h.fleet.has(second), true, 'the untouched live node kept its slot throughout');
     assert.notEqual(thawed.pi_pid, firstPid, 'the thaw is a real new broker, not the finished node\u2019s pid lingering');
+    transition(second, 'park');
+    headlessBrokerHost.teardown(second);
+    await h.awaitFleetExit(second);
+    const filler = await h.spawnHeadlessChild(root, 'terminal thaw filler');
+    assert.equal(h.fleet.size(), 2, 'the parked target is non-live while the cap remains full');
+    appendInbox(second, { from: root, tier: 'normal', kind: 'message', label: 'durable wake' });
+    assert.equal(reviveNode(second, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    closeDb();
+    const frozenTerminal = h.node(second);
+    assert.equal(frozenTerminal.status, 'done', 'freezing preserves the terminal status');
+    assert.equal(frozenTerminal.intent, 'parked', 'freezing preserves the terminal intent');
+    assert.ok(frozenTerminal.frozen_at != null, 'the durable wake remains in the bounded terminal tick population');
+    headlessBrokerHost.teardown(filler);
+    await h.awaitFleetExit(filler);
+    await h.tick();
+    await h.awaitBoot(second, { minCount: 2 });
+    closeDb();
+    assert.equal(h.node(second).frozen_at ?? null, null, 'a freed slot thaws the frozen terminal wake');
+    assert.equal(h.fleet.has(second), true, 'the terminal wake receives the freed slot');
+    createNode({
+        node_id: 'resident-drain',
+        name: 'resident drain',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        status: 'done',
+        intent: 'parked',
+        cwd: h.node(third).cwd,
+        host_kind: 'broker',
+        parent: root,
+        created: new Date().toISOString(),
+        pi_session_id: 'resident-drain-session',
+    });
+    assert.equal(reviveNode('resident-drain', { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    await h.tick();
+    closeDb();
+    const drained = h.node('resident-drain');
+    assert.equal(drained.status, 'idle', 'an eligible resident drains to Dormant');
+    assert.equal(drained.frozen_at ?? null, null, 'draining retires the frozen mark');
+    assert.equal(h.fleet.size(), 2, 'the drain does not spend a live-broker slot');
 });

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -181,8 +181,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
         // Clock expiry: arms the pending park and requests the summary turn.
         await h.tick(seenAt + 1500);
         // Summary grace expiry: the degraded enactment parks without a report.
-        // (If the summary turn's settlement already released the broker in the
-        // api-server process, the dormant-inbox reconciler applies the same park.)
+        // The lifecycle tick applies the same park after a settled release.
         await h.tick(seenAt + 1500 + 1000);
         await h.waitFor(() => {
             const node = h.node(nodeId);

package/dist/core/canvas/browse/model.d.ts

@@ -55,15 +55,6 @@ export declare function buildTree(rows: DashboardRow[], rootIds: string[], child
  *  reaped node's parent so a non-leaf reap never orphans them out of view. No-op
  *  if the id is absent. */
 export declare function pruneNode(tree: Tree, id: string): void;
-/** Case-insensitive subsequence match: every char of `query` appears in `text`
- *  in order (gaps allowed). Empty query matches everything. Substrings are a
- *  subsequence, so this subsumes substring matching too. */
-export declare function fuzzyMatch(query: string, text: string): boolean;
-/** Indices in `text` consumed by a greedy left-to-right subsequence match of
- *  `query` — the same walk as `fuzzyMatch`, but returning WHICH chars matched so
- *  the renderer can highlight them. Empty set when `query` is empty OR does not
- *  fully match (no partial highlights). */
-export declare function matchIndices(query: string, text: string): Set<number>;
 /** One word-wrapped preview line: its text + the column indices WITHIN that text
  *  to highlight (the query match). */
 export interface SnippetLine {

package/dist/core/canvas/browse/model.js

@@ -5,6 +5,7 @@
 // access (dashboardRowsAll / listNodes / subscriptionsOf) into buildTree, then
 // drives flatten() on each keystroke.
 import { isFinishedWork, isLiveStatus, statusRank } from '../node-order.js';
+import { matchIndices } from '../../tui/fuzzy.js';
 export const TABS = ['All', 'Live', 'Dormant', 'Attention', 'Pinned'];
 export const SORTS = ['tree', 'attention', 'relevance', 'recency'];
 /** Does a node belong to this tab's slice?
@@ -119,43 +120,6 @@ export function pruneNode(tree, id) {
     }
     tree.nodes.delete(id);
 }
-// Fuzzy match
-/** Case-insensitive subsequence match: every char of `query` appears in `text`
- *  in order (gaps allowed). Empty query matches everything. Substrings are a
- *  subsequence, so this subsumes substring matching too. */
-export function fuzzyMatch(query, text) {
-    if (query === '')
-        return true;
-    const q = query.toLowerCase();
-    const t = text.toLowerCase();
-    let qi = 0;
-    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
-        if (t[ti] === q[qi])
-            qi++;
-    }
-    return qi === q.length;
-}
-/** Indices in `text` consumed by a greedy left-to-right subsequence match of
- *  `query` — the same walk as `fuzzyMatch`, but returning WHICH chars matched so
- *  the renderer can highlight them. Empty set when `query` is empty OR does not
- *  fully match (no partial highlights). */
-export function matchIndices(query, text) {
-    const out = new Set();
-    if (query === '')
-        return out;
-    const q = query.toLowerCase();
-    const t = text.toLowerCase();
-    let qi = 0;
-    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
-        if (t[ti] === q[qi]) {
-            out.add(ti);
-            qi++;
-        }
-    }
-    if (qi < q.length)
-        out.clear(); // no full match → no highlight
-    return out;
-}
 /** Chars of leading context kept before the match start when windowing. */
 const SNIPPET_LEAD = 12;
 /** The literal case-insensitive substring span in a conversation preview.

package/dist/core/canvas/browse/render.js

@@ -12,7 +12,8 @@
 // reverse) is allowed always. See detectColorCaps() for the gate, and the
 // canvas-browse color spec for the rationale + palette.
 import { STATUS_GLYPH, STATUS_COLOR, isFrozenRow, resolveNodeVisual, faultSummary } from '../status-glyph.js';
-import { TABS, matchIndices, promptText, previewSnippet } from './model.js';
+import { TABS, promptText, previewSnippet } from './model.js';
+import { matchIndices } from '../../tui/fuzzy.js';
 // Span/color primitives live in core/tui/draw.ts (one copy, shared with the
 // `crtr view` host). Re-export the color caps so browse's importers + tests keep
 // resolving them from this module.

package/dist/core/canvas/canvas.d.ts

@@ -129,11 +129,11 @@ export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: numbe
  *  Unlike `listNodes`, this includes unclaimed warm-pool spares: profile
  *  deletion owns every matching row, whether or not it is user-visible. */
 export declare function listNodesByProfile(profileId: string): NodeMeta[];
-/** All rows, optionally filtered by status and by carrying a recorded pid (the
- *  supervision tick's terminal-row query). Unclaimed warm spares are excluded. */
+/** All rows, optionally filtered by status and terminal execution traces. Unclaimed warm spares are excluded. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];
     withRecordedPid?: boolean;
+    withRecordedPidOrFrozen?: boolean;
 }): NodeRow[];
 /** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
  *  from every listing until it is claimed. */
@@ -170,8 +170,8 @@ export declare function isWarmSpare(nodeId: string): boolean;
  *  pool has none. The select+delete run inside ONE canvas write-lock
  *  transaction, so two concurrent creates can never be handed the same spare.
  *  A spare whose broker is gone is skipped here and reaped by
- *  `reapStaleSpares` — nothing ever resumes a spare (the recovery sweep reads
- *  `listNodes`, which hides them), so a dead spare is garbage, not a parked one.
+ *  `reapStaleSpares` — nothing ever resumes a spare (the daemon's row query
+ *  hides them), so a dead spare is garbage, not a parked one.
  *
  *  The claim also restamps the row's `created` to `created` — birth time is a
  *  spare's MINT time, and consumers sort conversations on it, so an hour-old
@@ -291,7 +291,7 @@ export type TerminalGuardResult<T> = {
 /** Close the TOCTOU between checking a target has a natural cycle ahead
  *  of it and the write that depends on that (for example, a deferred inbox
  *  append). Fresh-reads `nodeId`'s
- *  (status, final_report) and either runs `body` (a write) or short-circuits
+ *  (status, final_report, frozen_at) and either runs `body` (a write) or short-circuits
  *  with a `'terminal'`/`'missing'` outcome — the read and `body`'s write share
  *  ONE canvas write-lock boundary (`withCanvasWrite`'s `BEGIN IMMEDIATE`), so
  *  a concurrent finish/cancel/finalization/deletion either commits entirely
@@ -311,6 +311,7 @@ export type TerminalGuardResult<T> = {
 export declare function withFreshTerminalGuard<T>(nodeId: string, isTerminal: (row: {
     status: NodeStatus;
     final_report: string | null;
+    frozen_at: string | null;
 }) => boolean, body: () => T): TerminalGuardResult<T>;
 /** Rebuild node rows from on-disk metas (the db node table is a derived index).
  *  Only the IDENTITY columns are rebuilt — they are a projection of meta. The

package/dist/core/canvas/canvas.js

@@ -19,7 +19,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, }
 /** The identity keys meta.json persists. Listed explicitly so no runtime field
  *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
 const IDENTITY_KEYS = [
-    'node_id', 'name', 'description', 'icon', 'cycles', 'created', 'cwd', 'host_kind', 'profile_id', 'kind', 'mode',
+    'node_id', 'name', 'description', 'title', 'icon', 'cycles', 'created', 'cwd', 'host_kind', 'profile_id', 'kind', 'mode',
     'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'fork_source_file', 'review_binding', 'passive_default', 'pi_session_id',
     'pi_session_file', 'cycle_pending', 'model_override',
     'launch', 'managed_worktree',
@@ -456,8 +456,7 @@ export function listNodesByProfile(profileId) {
         return meta;
     });
 }
-/** All rows, optionally filtered by status and by carrying a recorded pid (the
- *  supervision tick's terminal-row query). Unclaimed warm spares are excluded. */
+/** All rows, optionally filtered by status and terminal execution traces. Unclaimed warm spares are excluded. */
 export function listNodes(filter) {
     const clauses = [NOT_A_SPARE];
     const params = [];
@@ -468,6 +467,8 @@ export function listNodes(filter) {
     }
     if (filter?.withRecordedPid === true)
         clauses.push('pi_pid IS NOT NULL');
+    if (filter?.withRecordedPidOrFrozen === true)
+        clauses.push('(pi_pid IS NOT NULL OR frozen_at IS NOT NULL)');
     const rows = openDb()
         .prepare(`SELECT * FROM nodes WHERE ${clauses.join(' AND ')} ORDER BY created`)
         .all(...params);
@@ -539,8 +540,8 @@ function spareIsClaimable(row) {
  *  pool has none. The select+delete run inside ONE canvas write-lock
  *  transaction, so two concurrent creates can never be handed the same spare.
  *  A spare whose broker is gone is skipped here and reaped by
- *  `reapStaleSpares` — nothing ever resumes a spare (the recovery sweep reads
- *  `listNodes`, which hides them), so a dead spare is garbage, not a parked one.
+ *  `reapStaleSpares` — nothing ever resumes a spare (the daemon's row query
+ *  hides them), so a dead spare is garbage, not a parked one.
  *
  *  The claim also restamps the row's `created` to `created` — birth time is a
  *  spare's MINT time, and consumers sort conversations on it, so an hour-old
@@ -763,7 +764,7 @@ export function settleDeadMessageWait(nodeId, controller, deliver) {
 /** Close the TOCTOU between checking a target has a natural cycle ahead
  *  of it and the write that depends on that (for example, a deferred inbox
  *  append). Fresh-reads `nodeId`'s
- *  (status, final_report) and either runs `body` (a write) or short-circuits
+ *  (status, final_report, frozen_at) and either runs `body` (a write) or short-circuits
  *  with a `'terminal'`/`'missing'` outcome — the read and `body`'s write share
  *  ONE canvas write-lock boundary (`withCanvasWrite`'s `BEGIN IMMEDIATE`), so
  *  a concurrent finish/cancel/finalization/deletion either commits entirely
@@ -783,7 +784,7 @@ export function settleDeadMessageWait(nodeId, controller, deliver) {
 export function withFreshTerminalGuard(nodeId, isTerminal, body) {
     return withCanvasWrite((db) => {
         const row = db
-            .prepare('SELECT status, final_report FROM nodes WHERE node_id = ?')
+            .prepare('SELECT status, final_report, frozen_at FROM nodes WHERE node_id = ?')
             .get(nodeId);
         if (row === undefined) {
             return { kind: 'missing' };

package/dist/core/canvas/types.d.ts

@@ -90,6 +90,12 @@ export interface NodeIdentity {
     /** A 2-4 word kebab-case handle derived from the node's first prompt (named
      *  headlessly by pi; see runtime/naming.ts). Shown in the editor label. */
     description?: string;
+    /** The same first prompt named as PROSE — a sentence-case phrase with its
+     *  punctuation intact, produced by the same headless namer in the same call as
+     *  `description`. Kebab case is right for a tmux window and an editor label
+     *  and wrong for a conversation list, so a surface reading to a person takes
+     *  this. Absent on a node named before titles existed. */
+    title?: string;
     /** A single Nerd Font glyph depicting the node's work, chosen by the same
    *  headless namer that produced `description` (see runtime/naming.ts). Kept as
    *  its own field rather than baked into the description so each surface decides

package/dist/core/review/realize.js

@@ -177,7 +177,7 @@ export async function realizeReview(reviewId) {
         throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);
     }
     // R5: SQLite visibility commits before the ticket projection. A missing
-    // projection is deliberately under-exposed and recovered by the startup sweep.
+    // projection is deliberately under-exposed and retried by the review lane.
     if (openReviewRow(review.review_id, new Date().toISOString())) {
         signalReviewActivity();
         if (review.origin_kind === 'ticket')

package/dist/core/runtime/broker/node-named.d.ts

@@ -1,6 +1,7 @@
 /** What crtrd stored, as it stored it — the payload of a `node_named` frame. */
 export interface NodeNamedNotice {
     description: string;
+    title: string;
     icon: string;
     editorLabel: string;
 }