@north-light/crouter 0.3.241 → 0.3.242

package/dist/commands/node/create.js

@@ -75,7 +75,7 @@ function nodeNewParams() {
     return [
         { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message.' },
         { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: "Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind." },
-        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
+        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for one hands-on unit; orchestrator when the unit itself needs decomposition across children. When you hold several parallel units of one kind, spawn ONE orchestrator child of that kind to own the fan-out rather than spawning the units yourself — unless you are already an orchestrator of that kind, whose job is exactly that fan-out.' },
         { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the directory this command runs in for a root.' },
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
@@ -147,6 +147,7 @@ function nodeNewOutput() {
     return [
         { name: 'node_id', type: 'string', required: true, constraint: 'New node id.' },
         { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
+        { name: 'frozen_at', type: 'string', required: false, constraint: 'Present when a managed child exists but capacity deferred its broker start.' },
         ...(inTmux()
             ? [
                 { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
@@ -242,23 +243,27 @@ async function runNodeCreation(input) {
         placement = openSpawnViewer(detail.node_id, detail.cwd, detail.name);
     if (root)
         mark('node_new.viewer_window_opened');
+    const frozen = !root && detail.frozen_at !== null;
     const result = {
         node_id: detail.node_id,
         name: detail.name,
+        ...(frozen ? { frozen_at: detail.frozen_at } : {}),
         window: placement.window,
         session: placement.session,
         follow_up: root
             ? (noKickoff
                 ? 'Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.'
                 : 'Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.')
-            : await childFollowUp(parentId),
+            : (frozen
+                ? 'Child row exists, but no broker started because capacity is full. It is frozen and will launch when a broker slot frees; its final report wakes you then.'
+                : await childFollowUp(parentId)),
     };
     return result;
 }
 export const nodeNew = defineLeaf({
     name: 'new',
     description: 'create and start a node immediately',
-    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel, a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
+    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel (usually via one orchestrator child of the matching kind rather than a flat fan-out from you), a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
     tier: 'important',
     help: {
         name: 'node new',

package/dist/commands/sys/daemon.js

@@ -80,7 +80,7 @@ const daemonRestart = defineLeaf({
         effects: [
             'The daemon acknowledges immediately, then after a short grace tears its whole broker fleet down, releases its claim, spawns a successor on the runtime generation currently selected, and exits.',
             'Each torn-down broker hands its foreground bash commands to the file-backed background job system; they keep running and report completion by urgent inbox message.',
-            'Every node it tore down — including the caller — is resumed by the successor through the ordinary startup recovery sweep.',
+            'Every node it tore down — including the caller — is resolved by the successor through the ordinary row-driven supervision tick.',
             'The calling process is killed as part of that teardown, AFTER this result is returned.',
         ],
     },

package/dist/core/__tests__/child-death-wake.test.js

@@ -1,30 +1,4 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/child-death-wake.test.ts
-//
-// DOCTRINE WAKE — "a parent that delegated and went dormant is still woken when
-// its child reaches a genuine terminal outcome, and is NEVER spuriously woken on
-// healthy dormancy." Drives the REAL daemon decision pass (superviseTick) + the
-// REAL closeNode against canvas rows fabricated DIRECTLY in an isolated home — NO
-// real tmux session, NO broker boot.
-//
-// BROKER CUT (this worktree): the daemon's OLD parent-wake mechanism is GONE.
-// U7 deleted surfaceChildDeath and the entire pane-gone reaping block (the
-// crash/finalize/release routing that used to mark a pane-gone child dead/done/
-// idle and fan a system inbox entry to its subscribers). Under exit-event
-// authority a viewer pane/window closing is NOT a node death, and the tick runs
-// no liveness pass at all — a booted child's death is observed only through its
-// broker's real exit event (fleet exit-policy job), which recovery-revives it
-// on its saved session rather than surfacing it as dead. The doctrine wake
-// therefore RELOCATED off the daemon's tick:
-//   • child finishes → `crtr push final` wakes subscribers via the PUSH itself;
-//   • child crashes → its exit event drives a recovery revive (it comes back
-//     and pushes later);
-//   • child never boots → the exit event terminalizes it and surfaceBootFailure
-//     pushes urgent (daemon-boot.test);
-//   • child `node close`d → close.ts fans the child-closed wake (tested below).
-// So the daemon now fans NO liveness wake at all, which makes the old CRUX
-// (healthy dormancy must not wake the parent) hold by construction. This file
-// locks in (a) the new pid-only non-reaping + no-daemon-wake contract, and (b)
-// the one genuine-terminal wake that still lives in core: close.ts.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -112,15 +86,6 @@ after(() => {
     delete process.env['CRTR_HOME'];
     resetFleetForTests();
 });
-// BROKER CUT — exit-event authority REPLACES daemon pane-gone reaping. A booted
-// child whose engine pid is dead (and whose viewer pane is gone) is RECOVERED,
-// not reaped, and the daemon's tick fans NO wake to the dormant parent. This
-// single case subsumes the four deleted scenarios (crash / quiet-finalize /
-// awaiting a live grandchild / pending self-wake): with pane state ignored and
-// surfaceChildDeath gone, the daemon treats them all identically — no reap, no
-// liveness wake — so the old CRUX (no spurious wake on healthy dormancy) holds
-// by construction. The node-lifecycle tick relaunches the row through the same
-// policy table its exit event would have used (D-12); that recovery is silent.
 test('exit-event authority: a dead-engine booted child is recovered, NOT reaped, and the tick fans NO wake to its dormant parent', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const launches = [];
@@ -139,9 +104,6 @@ test('exit-event authority: a dead-engine booted child is recovered, NOT reaped,
         // its saved session, never reaped to dead/done/idle.
         assert.deepEqual(launches, ['CHILD'], 'the tick recovers the dead engine through the policy table');
         assert.equal(getNode('CHILD').status, 'active', 'CHILD is recovered, NOT reaped');
-        // surfaceChildDeath is deleted: the daemon raises no liveness wake. The
-        // doctrine wake now rides the child's own `push final` (or close.ts), so a
-        // purely-inbox-waiting parent is never spuriously woken on dormancy/crash.
         assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — no daemon liveness wake');
     }
     finally {
@@ -163,13 +125,3 @@ test('node close of a child wakes its SURVIVING manager (the parent outside the
     assert.ok(wake, 'node close fanned a child-closed entry to the surviving manager (D-1: previously none)');
     assert.match(wake.label, /closed/i, 'the entry names the closed child');
 });
-// NOTE (broker cut): the two NEGATIVE "CRUX" tests that used to live here — a
-// child dormant while awaiting a live grandchild, and a child dormant on a
-// pending self-wake — asserted the daemon's pane-gone routing chose idle-release
-// (status 'idle', intent 'idle-release') over finalize, so it would not spuriously
-// wake the parent. U7 DELETED that routing entirely: pane state is ignored, the
-// daemon never finalizes/releases on liveness, and surfaceChildDeath is gone, so
-// the daemon raises no liveness wake at all. The no-spurious-wake invariant they
-// protected now holds by construction and is covered by the pid-only test above
-// (PARENT inbox stays empty). Removed rather than adapted because the
-// idle-release-vs-finalize distinction they asserted no longer exists.

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/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