@north-light/crouter 0.3.241 → 0.3.243

package/dist/commands/sys/context/admin/list-view.js

@@ -4,78 +4,137 @@
 import { fuzzyMatch } from '../../../../core/tui/fuzzy.js';
 import { deliveredCost, rungCostsOf } from './model.js';
 export const NO_FILTERS = { rung: 'any', origin: 'any', kind: 'any', state: 'any', query: '' };
-/** Documents whose canonical name carries no `/` share one leading section
- *  rather than becoming a crowd of one-member groups. */
+/** Documents whose canonical name carries no `/` and owns no directory share
+ *  one leading section rather than becoming a crowd of one-member groups. */
 const LEADING_KEY = '';
 const LEADING_LABEL = 'top level';
-export function groupKeyOf(name) {
-    const cut = name.indexOf('/');
-    return cut < 0 ? LEADING_KEY : name.slice(0, cut);
-}
-/** Every group key the rows can produce, so collapse state can drop the keys a
- *  re-plan removed instead of accumulating them. */
+/** Every group key the rows can produce — one per proper name prefix, since a
+ *  prefix exists only because something sits under it — so collapse state can
+ *  drop the keys a re-plan removed instead of accumulating them. The leading
+ *  section is a key only when a name with no `/` owns no directory, which is
+ *  exactly when it is not itself one of those prefixes. */
 export function groupKeysOf(rows) {
-    return new Set(rows.map((row) => groupKeyOf(row.name)));
+    const keys = new Set();
+    const unslashed = [];
+    for (const row of rows) {
+        if (row.name.includes('/')) {
+            for (let cut = row.name.indexOf('/'); cut >= 0; cut = row.name.indexOf('/', cut + 1)) {
+                keys.add(row.name.slice(0, cut));
+            }
+        }
+        else
+            unslashed.push(row.name);
+    }
+    if (unslashed.some((name) => !keys.has(name)))
+        keys.add(LEADING_KEY);
+    return keys;
 }
-/** The lines to draw, in corpus order: the leading section, then each group in
- *  order of first appearance. A live query force-expands every group holding a
- *  match without touching `expanded`, so clearing it restores what the user
- *  collapsed. */
+/** The lines to draw, in corpus order: the leading section, then each directory
+ *  in order of first appearance, each recursing into its own members only when
+ *  it is open. A live query force-expands every directory, which is exactly the
+ *  ancestor chain of every surviving match, without touching `expanded` — so
+ *  clearing the query restores what the user collapsed. */
 export function buildListView(rows, filters, expanded, event) {
-    const groups = new Map();
-    const order = [];
+    const root = { key: '', segment: '', depth: -1, children: new Map(), selves: [] };
     for (const row of rows) {
         if (!passes(row, row.records.get(event), filters))
             continue;
-        const key = groupKeyOf(row.name);
-        const held = groups.get(key);
-        if (held === undefined) {
-            groups.set(key, [row]);
-            order.push(key);
+        let dir = root;
+        for (const segment of row.name.split('/')) {
+            let child = dir.children.get(segment);
+            if (child === undefined) {
+                child = {
+                    key: dir.depth < 0 ? segment : `${dir.key}/${segment}`,
+                    segment,
+                    depth: dir.depth + 1,
+                    children: new Map(),
+                    selves: [],
+                };
+                dir.children.set(segment, child);
+            }
+            dir = child;
         }
-        else
-            held.push(row);
+        dir.selves.push(row);
     }
-    if (groups.has(LEADING_KEY)) {
-        order.splice(order.indexOf(LEADING_KEY), 1);
-        order.unshift(LEADING_KEY);
+    const leading = [];
+    const dirs = [];
+    for (const child of root.children.values()) {
+        if (child.children.size === 0)
+            leading.push(...child.selves);
+        else
+            dirs.push(child);
     }
     const lines = [];
-    for (const key of order) {
-        const members = groups.get(key);
-        const rungs = { name: 0, preview: 0, content: 0 };
-        let cost = 0;
-        for (const row of members) {
-            const record = row.records.get(event);
-            if (record !== undefined && record.finalRung !== 'none')
-                rungs[record.finalRung] += 1;
-            cost += deliveredCost(record);
-        }
-        const open = filters.query !== '' || expanded.has(key);
+    if (leading.length > 0) {
+        const open = filters.query !== '' || expanded.has(LEADING_KEY);
         lines.push({
             kind: 'group',
-            key,
-            label: key === LEADING_KEY ? LEADING_LABEL : `${key}/`,
-            docs: members.length,
-            rungs,
-            cost,
+            key: LEADING_KEY,
+            label: LEADING_LABEL,
+            depth: 0,
+            ...rollup(leading, event),
             expanded: open,
-            first: members[0],
+            first: leading[0],
+            isDoc: false,
         });
-        if (!open)
-            continue;
-        for (const row of members) {
-            lines.push({
-                kind: 'doc',
-                key: row.key,
-                row,
-                label: key === LEADING_KEY ? row.name : row.name.slice(key.length + 1),
-                cost: deliveredCost(row.records.get(event)),
-            });
-        }
+        if (open)
+            for (const row of leading)
+                lines.push(docLine(row, row.name, 1, event));
     }
+    for (const dir of dirs)
+        emit(dir, filters, expanded, event, lines);
     return lines;
 }
+/** A directory's rows in drawn order: its own document first, then each child
+ *  segment's subtree — so the head of the list is also the document the header
+ *  hands the dossier. */
+function subtree(dir, out = []) {
+    out.push(...dir.selves);
+    for (const child of dir.children.values())
+        subtree(child, out);
+    return out;
+}
+function emit(dir, filters, expanded, event, lines) {
+    if (dir.children.size === 0) {
+        for (const row of dir.selves)
+            lines.push(docLine(row, dir.segment, dir.depth, event));
+        return;
+    }
+    const members = subtree(dir);
+    const open = filters.query !== '' || expanded.has(dir.key);
+    lines.push({
+        kind: 'group',
+        key: dir.key,
+        label: `${dir.segment}/`,
+        depth: dir.depth,
+        ...rollup(members, event),
+        expanded: open,
+        first: members[0],
+        isDoc: dir.selves.length > 0,
+    });
+    if (!open)
+        return;
+    // The header already stands for the first document named exactly this path;
+    // a second store answering the same name still needs its own row.
+    for (const shadowed of dir.selves.slice(1))
+        lines.push(docLine(shadowed, dir.segment, dir.depth + 1, event));
+    for (const child of dir.children.values())
+        emit(child, filters, expanded, event, lines);
+}
+function docLine(row, label, depth, event) {
+    return { kind: 'doc', key: row.key, row, label, depth, cost: deliveredCost(row.records.get(event)) };
+}
+function rollup(members, event) {
+    const rungs = { name: 0, preview: 0, content: 0 };
+    let cost = 0;
+    for (const row of members) {
+        const record = row.records.get(event);
+        if (record !== undefined && record.finalRung !== 'none')
+            rungs[record.finalRung] += 1;
+        cost += deliveredCost(record);
+    }
+    return { docs: members.length, rungs, cost };
+}
 /** What the whole filtered set costs, split by the rung it arrives at. */
 export function costTotals(rows, event) {
     const byRung = { name: 0, preview: 0, content: 0 };

package/dist/commands/sys/context/admin/shell.d.ts

@@ -90,6 +90,9 @@ export declare class ContextAdminShell implements Component, Focusable {
     private handleModal;
     private renderModal;
     private footer;
+    /** What the focused row does when opened. A directory answers to space, a
+     *  document to enter, and a directory that is also a document to both. */
+    private docsGesture;
     render(width: number): string[];
     /** What the delivering documents spend on this event. An estimate, and a
      *  floor on the rendered prompt: boot wraps these documents in its own intro

package/dist/commands/sys/context/admin/shell.js

@@ -228,7 +228,9 @@ export class ContextAdminShell {
             this.syncDetail();
         }
         else if (this.isDescend(data)) {
-            if (this.docs.onGroup) {
+            // A directory that is also a document keeps both gestures: space opens it,
+            // and descending goes to its dossier like any other document.
+            if (this.docs.onGroup && !this.docs.onDocument) {
                 this.docs.toggleGroup();
                 this.syncDetail();
             }
@@ -648,7 +650,7 @@ export class ContextAdminShell {
         const left = this.zone === 'rail'
             ? `${move} row · space change · enter documents`
             : this.zone === 'docs'
-                ? `${move} row · space ${this.docs.onGroup ? 'open group' : 'group'} · / search · enter dossier`
+                ? `${move} row · ${this.docsGesture()} · / search`
                 : `${move} field · enter edit · e add · x remove · g gate · b body · u unlisted · s slash · m cap · r rename`;
         const right = `${this.label('crtr.setup.tab-next', 'tab')} event · ${this.label('crtr.setup.cancel', 'q')} close`;
         const gap = width - visibleWidth(left) - visibleWidth(right);
@@ -656,6 +658,13 @@ export class ContextAdminShell {
             ? `${theme.fg('dim', left)}${' '.repeat(gap)}${theme.fg('dim', right)}`
             : theme.fg('dim', truncateToWidth(`${left} · ${this.label('crtr.setup.cancel', 'q')} close`, width));
     }
+    /** What the focused row does when opened. A directory answers to space, a
+     *  document to enter, and a directory that is also a document to both. */
+    docsGesture() {
+        if (!this.docs.onGroup)
+            return 'enter dossier';
+        return this.docs.onDocument ? 'space open · enter dossier' : 'space/enter open';
+    }
     render(width) {
         const height = this.terminalRows();
         const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);

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' });