@north-light/crouter 0.3.235 → 0.3.237

package/dist/core/__tests__/integration/revive.test.js

@@ -226,7 +226,7 @@ test('reviveNode no-ops when the node has a live fleet entry — double-revive g
         });
         h.fleet.register(M, { pid: 424242, exited: new Promise(() => { }) });
         const before = h.node(M).cycles ?? 0;
-        const res = reviveNode(M, { resume: true });
+        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'guard path does not re-resume');
         assert.equal(h.node(M).cycles ?? 0, before, 'cycle counter NOT bumped (guard returned early)');
     }
@@ -254,7 +254,7 @@ test('reviveNode PROCEEDS when the node has NO fleet entry — cycle counter bum
             pi_session_file: sessionFile,
         });
         assert.equal(h.node(M).cycles ?? 0, 0, 'fabricated at cycle 0 (no revive yet)');
-        reviveNode(M, { resume: true });
+        reviveNode(M, { resume: true, capacity: 'freeze' });
         const after = h.node(M);
         assert.equal(after.cycles, 1, 'a real (non-guard) revive bumped the cycle counter to 1');
         assert.notEqual(after.pi_pid, stalePid, 'revive records the fresh broker pid immediately, not the stale dead pid');
@@ -298,11 +298,11 @@ test('a recovery relaunch keeps the armed deadline; a wake revive consumes it',
     try {
         const recovered = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-1' });
         armDeadline(recovered, 'cron-recovery');
-        reviveNode(recovered, { resume: true, recovery: true });
+        reviveNode(recovered, { resume: true, recovery: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(recovered), true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
         const woken = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-2' });
         armDeadline(woken, 'cron-wake');
-        reviveNode(woken, { resume: true });
+        reviveNode(woken, { resume: true, capacity: 'freeze' });
         assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
     }
     finally {
@@ -327,7 +327,7 @@ test('reviveNode fresh-fallback clears the stale session identity (Major-3: no p
             pi_session_id: 'uuid-stale',
             pi_session_file: missingFile,
         });
-        const res = reviveNode(M, { resume: true });
+        const res = reviveNode(M, { resume: true, capacity: 'freeze' });
         assert.equal(res.resumed, false, 'a missing .jsonl forces a fresh (non-resuming) launch');
         const after = h.node(M);
         assert.equal(after.pi_session_id, null, 'stale pi_session_id cleared before the fresh launch');
@@ -373,7 +373,7 @@ test('unbound forks replay one durable source file for node-id, path, and UUID o
         deleteNode('ordinary-fork-source');
         for (let index = 0; index < operands.length; index++) {
             const destination = `ordinary-fork-${index}`;
-            reviveNode(destination, { resume: index !== 1 });
+            reviveNode(destination, { resume: index !== 1, capacity: 'freeze' });
             const argv = launches[index];
             const fork = argv.indexOf('--fork');
             assert.equal(argv[fork + 1], forkFile, `${operands[index]} retries from the durable resolved file`);
@@ -406,7 +406,7 @@ test('reviveNode throws a typed cwd_missing error and does NOT crash the node wh
             pi_pid: deadPid(),
         });
         updateNode(M, { cwd: missingCwd });
-        assert.throws(() => reviveNode(M, { resume: true }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
         const after = h.node(M);
         assert.equal(after.status, 'active', 'a cwd-missing preflight refusal must NOT crash the node (fixable in place, not a dead engine)');
     }
@@ -429,7 +429,7 @@ test('reviveNode crashes and clears pid when launch/preflight throws', async ()
             pi_session_file: sessionFile,
         });
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         const after = h.node(M);
         assert.equal(after.status, 'dead', 'failed revive marks the node dead');
         assert.equal(after.pi_pid, null, 'failed revive clears the stale pid');
@@ -462,7 +462,7 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         // was fabricated directly, not spawned through the CLI.
         subscribe(root, M, true);
         headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
-        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        assert.throws(() => reviveNode(M, { resume: true, capacity: 'freeze' }), /refusing to revive/i);
         assert.equal(h.node(M).status, 'dead', 'failed revive marks the node dead');
         const entries = readInboxSince(root, undefined);
         const notice = entries.find((e) => e.data?.['reason'] === 'child-crashed' && e.data?.['child'] === M);
@@ -497,19 +497,19 @@ test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', (
         const missing = join(home, 'sessions', 'never-written.jsonl');
         // (1) Bare interactive node — nothing on disk anywhere: launch promptless.
         createNode(node('bare-unstarted', { cwd: home, pi_session_id: 'uuid-a', pi_session_file: missing }));
-        reviveNode('bare-unstarted', { resume: true });
+        reviveNode('bare-unstarted', { resume: true, capacity: 'freeze' });
         const bare = launches[0];
         assert.equal(bare.some((a) => isReviveKickoff(a)), false, 'an unstarted node is never told it lost context it never had');
         assert.deepEqual(bare, buildPiArgv(getNode('bare-unstarted'), {}).argv, 'a promptless boot — the argv carries no trailing prompt positional at all');
         // (2) Spawned with a mandate whose first turn never persisted: replay it.
         createNode(node('mandate-unstarted', { cwd: home, pi_session_id: 'uuid-b', pi_session_file: missing }));
         writeGoal('mandate-unstarted', 'do the thing');
-        reviveNode('mandate-unstarted', { resume: true });
+        reviveNode('mandate-unstarted', { resume: true, capacity: 'freeze' });
         assert.equal(launches[1].at(-1), 'do the thing', 'a birth replays the spawn mandate');
         // (3) Real durable progress on disk → still a genuine fresh revive.
         createNode(node('progressed', { cwd: home, pi_session_id: 'uuid-c', pi_session_file: missing }));
         seedRoadmap('progressed', { goal: 'ship it' });
-        reviveNode('progressed', { resume: true });
+        reviveNode('progressed', { resume: true, capacity: 'freeze' });
         assert.equal(isReviveKickoff(launches[2].at(-1)), true, 'a node with a roadmap still rebuilds from the kickoff');
     }
     finally {

package/dist/core/__tests__/integration/spawn-root.test.js

@@ -15,6 +15,8 @@ import { spawnNode } from '../../runtime/nodes.js';
 import { readGoal } from '../../runtime/kickoff.js';
 import { spawnChild, resolveSpawner } from '../../runtime/spawn.js';
 import { headlessBrokerHost } from '../../runtime/host.js';
+import { resetFleetForTests } from '../../runtime/fleet.js';
+import { bindTestFleet } from '../helpers/fleet.js';
 import { recordFault } from '../../runtime/fault.js';
 import { piSessionsRoot } from '../../runtime/pi-vendored.js';
 import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../substrate/injected-store.js';
@@ -40,6 +42,9 @@ before(() => {
     process.env['CRTR_HOME'] = home;
     previousPidfile = process.env['CRTR_PIDFILE'];
     process.env['CRTR_PIDFILE'] = join(home, 'crtrd.pid');
+    // Every launcher claims a slot from the ledger before it reaches the host, so
+    // a spawn in-process needs a bound fleet (D-2).
+    bindTestFleet();
 });
 beforeEach(() => {
     closeDb();
@@ -52,6 +57,7 @@ beforeEach(() => {
 });
 after(() => {
     closeDb();
+    resetFleetForTests();
     rmSync(home, { recursive: true, force: true });
     if (previousPidfile === undefined)
         delete process.env['CRTR_PIDFILE'];

package/dist/core/__tests__/integration/worktree-reap.test.js

@@ -9,6 +9,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { gitSync } from '../../git.js';
 import { createManagedWorktree, closeManagedWorktree } from '../../worktree.js';
+import { createApiServer } from '../../../daemon/api/server.js';
+import { apiSocketPath } from '../../canvas/paths.js';
+import { CrtrClient } from '../../../api/index.js';
 import { createNode, getNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
 let home;
@@ -193,6 +196,35 @@ test('autoDropCleanManagedWorktree refuses a worktree with real uncommitted chan
     assert.equal(result, null, 'real uncommitted changes must never be silently dropped');
     assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open');
 });
+test('abandon preserves committed and dirty work, records its retained tip, and releases finalization', async () => {
+    const nodeId = 'wt-abandon';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    writeFileSync(join(wt.path, 'committed.txt'), 'committed work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'real work'], wt.path);
+    writeFileSync(join(wt.path, 'dirty.txt'), 'dirty work\n');
+    createNode(node(nodeId, { cwd: wt.path, status: 'done', managed_worktree: wt }));
+    const server = createApiServer();
+    try {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+        const client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+        const result = await client.abandonWorktree(nodeId, { by: 'test-invoker' });
+        const meta = getNode(nodeId);
+        assert.equal(gitSync(['rev-parse', wt.branch], sourceDir).stdout.trim(), result.tip_sha, 'the retained branch names the recorded tip');
+        assert.equal(gitSync(['show', `${result.tip_sha}:committed.txt`], sourceDir).stdout, 'committed work\n', 'the pre-existing commit remains reachable');
+        assert.equal(gitSync(['show', `${result.tip_sha}:dirty.txt`], sourceDir).stdout, 'dirty work\n', 'the WIP commit preserves dirty work');
+        assert.equal(gitSync(['show', '-s', '--format=%an <%ae>%n%s%n%(trailers:only)', result.tip_sha], sourceDir).stdout, `crtr-abandon <crtr-abandon@localhost>\ncrtr-abandon\nCrtr-Abandon: ${nodeId} ${meta?.managed_worktree?.abandoned?.at}\n\n`, 'the WIP commit has the reserved author, subject sentinel, and durable trailer');
+        assert.equal(existsSync(wt.path), false, 'the checkout is removed');
+        assert.equal(meta?.managed_worktree?.state, 'abandoned', 'the node records the abandoned disposition');
+        assert.deepEqual(meta?.managed_worktree?.abandoned, { branch: wt.branch, tip_sha: result.tip_sha, at: meta?.managed_worktree?.abandoned?.at, by: 'test-invoker' }, 'the metadata names the retained tip and invoker');
+        assert.equal(meta?.cwd, wt.repo_root, 'the node cwd repoints to the repository root');
+        await client.pushReport(nodeId, { tier: 'final', body: 'abandoned work preserved' });
+        assert.ok(getNode(nodeId)?.final_report, 'push final proceeds after abandon releases the worktree gate');
+    }
+    finally {
+        await server.close();
+    }
+});
 // The actual #327 positive case: a branch with REAL commits whose tip is
 // already contained in a base that moved forward past this worktree's
 // original base_sha (a manager landed the same change another way, without

package/dist/core/__tests__/lifecycle-terminal-reasons.test.d.ts

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

package/dist/core/__tests__/lifecycle-terminal-reasons.test.js

@@ -0,0 +1,61 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { transition } from '../runtime/lifecycle.js';
+let home;
+function seed(nodeId) {
+    const node = {
+        node_id: nodeId,
+        name: nodeId,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+    createNode(node);
+}
+function reason(nodeId) {
+    return getNode(nodeId)?.terminal_reason;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-lifecycle-reasons-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('transition records terminal reasons and clears them on terminal-to-live transitions', () => {
+    for (const [event, expected] of [
+        ['finish', 'finished'],
+        ['park', 'parked'],
+        ['cancel', 'stranded'],
+        ['crash', 'crashed'],
+        ['yield', null],
+        ['release', null],
+    ]) {
+        const nodeId = `event-${event}`;
+        seed(nodeId);
+        transition(nodeId, event);
+        assert.equal(reason(nodeId), expected, `${event} records its terminal reason`);
+    }
+    seed('refresh-launch');
+    transition('refresh-launch', 'cancel');
+    transition('refresh-launch', 'refresh-launch');
+    assert.equal(reason('refresh-launch'), null, 'refresh-launch clears a terminal reason');
+    seed('revive');
+    transition('revive', 'finish');
+    transition('revive', 'revive');
+    assert.equal(reason('revive'), null, 'revive clears a terminal reason');
+});

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

@@ -215,6 +215,43 @@ test('a fresh db has the four additive runtime columns', () => {
     assert.equal(rt['window'], null);
     assert.equal(rt['tmux_session'], null);
 });
+test('node lifecycle substrate migration adds six columns and backfills terminal reasons', () => {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 34);
+    const lifecycleColumns = [
+        'frozen_at',
+        'respawn_failures',
+        'respawn_not_before',
+        'launched_at',
+        'last_settled_at',
+        'terminal_reason',
+    ];
+    for (const column of lifecycleColumns)
+        assert.ok(!nodeColumns(raw).includes(column));
+    const insert = raw.prepare('INSERT INTO nodes (node_id, name, kind, status, intent, final_report, cwd, created) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
+    const created = '2020-01-01T00:00:00Z';
+    insert.run('finalized', 'finalized', 'general', 'done', 'done', 'final.md', '/tmp', created);
+    insert.run('parked', 'parked', 'general', 'done', 'parked', null, '/tmp', created);
+    insert.run('finished', 'finished', 'general', 'done', 'done', null, '/tmp', created);
+    insert.run('stranded', 'stranded', 'general', 'canceled', null, null, '/tmp', created);
+    insert.run('crashed', 'crashed', 'general', 'dead', null, null, '/tmp', created);
+    insert.run('active', 'active', 'general', 'active', null, null, '/tmp', created);
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    for (const column of lifecycleColumns)
+        assert.ok(nodeColumns(db).includes(column));
+    const reasons = Object.fromEntries(db.prepare('SELECT node_id, terminal_reason FROM nodes ORDER BY node_id').all().map((row) => [row.node_id, row.terminal_reason]));
+    assert.deepEqual(reasons, {
+        active: null,
+        crashed: 'crashed',
+        finalized: 'finalized',
+        finished: 'finished',
+        parked: 'parked',
+        stranded: 'stranded',
+    });
+});
 // v4: edges FK ON DELETE CASCADE (the one irreversible rebuild)
 /** Build a hand-rolled db at exactly v3 (baseline tables + the four runtime
  *  columns, edges with NO foreign key, `user_version = 3`) — the shape the live
@@ -337,7 +374,7 @@ test('v16 repairs a v15 database missing canonical finalization columns', () =>
     ensureHome();
     const db = new DatabaseSync(join(home, 'finalization.db'));
     try {
-        MIGRATIONS[0](db);
+        migrateToVersion(db, 13);
         db.exec('PRAGMA user_version = 15');
         migrate(db);
         const columns = nodeColumns(db);

package/dist/core/__tests__/push-final-guard.test.js

@@ -179,6 +179,6 @@ test('reviveNode refuses to revive a node that became finalized after the caller
     process.env['CRTR_NODE_ID'] = id;
     await pushFinal(id, 'concurrent final');
     assert.equal(getNode(id)?.status, 'done');
-    assert.throws(() => reviveNode(id, { resume: true }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
+    assert.throws(() => reviveNode(id, { resume: true, capacity: 'freeze' }), /finaliz/i, 'reviveNode\'s own belt-and-suspenders check refuses a now-latched target');
     assert.equal(getNode(id)?.status, 'done', 'the node stays done, never silently revived into an unsatisfiable mandate');
 });

package/dist/core/__tests__/revive-capacity.test.d.ts

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

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

@@ -0,0 +1,127 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/revive-capacity.test.ts
+//
+// The broker cap is a real admission gate, and `reviveNode` is where every
+// launcher meets it. A caller declares what it wants when the ledger is full —
+// `freeze` (its reason to run survives waiting) or `refuse` (it needs an engine
+// now) — and this file pins the whole disposition matrix: the refusal names the
+// cap and the live count instead of failing silently, the freeze marks the row
+// once per episode without touching its session identity, an already-live node
+// is admitted at the cap because it consumes no new slot, and the launch that
+// 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 { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { bindDaemonEventSource, resetEventSourceForTests } from '../events/source.js';
+import { resetFleetForTests } from '../runtime/fleet.js';
+import { headlessBrokerHost } from '../runtime/host.js';
+import { reviveNode } from '../runtime/revive.js';
+import { bindTestFleet } from './helpers/fleet.js';
+let home;
+let tf;
+let seq = 0;
+const originalLaunch = headlessBrokerHost.launch;
+/** The real host contract, minus the process: register at the launch seam, so
+ *  the ledger consumes the reservation exactly as production does. */
+function stubLaunch() {
+    headlessBrokerHost.launch = (nodeId) => {
+        const handle = { pid: 500_000 + seq++, exited: new Promise(() => { }) };
+        tf.fleet.register(nodeId, handle);
+        return handle;
+    };
+}
+function node(id, over = {}) {
+    createNode({
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: home,
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        host_kind: 'broker',
+        ...over,
+    });
+    return id;
+}
+/** Fill the ledger to the cap with live brokers. */
+function saturate() {
+    reviveNode(node(`filler-a-${seq}`), { resume: false, capacity: 'refuse' });
+    reviveNode(node(`filler-b-${seq}`), { resume: false, capacity: 'refuse' });
+    assert.equal(tf.fleet.size(), 2, 'precondition: the ledger is at its cap of 2');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-revive-capacity-'));
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_MAX_LIVE_BROKERS'] = '2';
+    resetEventSourceForTests();
+    bindDaemonEventSource();
+});
+beforeEach(() => {
+    tf = bindTestFleet();
+    stubLaunch();
+});
+after(() => {
+    headlessBrokerHost.launch = originalLaunch;
+    tf.fleet.dispose();
+    resetFleetForTests();
+    resetEventSourceForTests();
+    closeDb();
+    delete process.env['CRTR_MAX_LIVE_BROKERS'];
+    delete process.env['CRTR_HOME'];
+    rmSync(home, { recursive: true, force: true });
+});
+test('a refusing caller gets an error naming the cap and the live count, never a silent no-op', () => {
+    saturate();
+    const turned = node('refused', { pi_session_id: 'sess-refused' });
+    assert.throws(() => reviveNode(turned, { resume: true, capacity: 'refuse' }), (err) => {
+        const details = err.details ?? {};
+        assert.equal(details['error'], 'broker_cap_reached', 'the refusal is a typed InputError, so it survives the /v1 error body');
+        assert.match(String(details['message']), /2 live brokers at the cap of 2/, 'the message names both the live count and the cap');
+        return true;
+    });
+    const meta = getNode(turned);
+    assert.equal(meta.frozen_at ?? null, null, 'a refusal is not a freeze — nothing waits for this row');
+    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 freezing caller gets a frozen row, marked once and left otherwise untouched', () => {
+    saturate();
+    const waiting = node('frozen', { pi_session_id: 'sess-frozen' });
+    const first = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    assert.equal(first.outcome, 'frozen', 'the caller learns it got no engine');
+    const marked = getNode(waiting);
+    assert.ok(marked.frozen_at != null, 'the row carries the durable wait mark the thaw order reads');
+    assert.equal(marked.pi_pid ?? null, null, 'a frozen row holds no pid — every status surface reads it as frozen, not stale-active');
+    assert.equal(marked.cycles ?? 0, 0, 'a frozen node never spent a cycle');
+    const second = reviveNode(waiting, { resume: true, capacity: 'freeze' });
+    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('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' });
+    reviveNode(node('already-live-filler'), { resume: false, capacity: 'refuse' });
+    assert.equal(tf.fleet.size(), 2, 'precondition: this node holds one of the two slots, and the ledger is full');
+    // Both dispositions agree: liveness is answered before capacity ever is.
+    assert.equal(reviveNode(live, { resume: true, capacity: 'refuse' }).outcome, 'already-live');
+    assert.equal(reviveNode(live, { resume: true, capacity: 'freeze' }).outcome, 'already-live');
+    assert.equal(getNode(live).frozen_at ?? null, null, 'a live node is never marked as waiting for a slot');
+});
+test('a freed slot lets the frozen row launch, and the launch retires the mark', async () => {
+    const filler = node('filler-exits');
+    reviveNode(filler, { resume: false, capacity: 'refuse' });
+    reviveNode(node('filler-stays'), { resume: false, capacity: 'refuse' });
+    const waiting = node('thaws', { pi_session_id: 'sess-thaws' });
+    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'frozen');
+    // A real exit frees the slot; its policy job runs on the lane like production.
+    tf.fleet.deliverExit(filler, { code: 0, signal: null });
+    await tf.drain();
+    assert.equal(reviveNode(waiting, { resume: true, capacity: 'freeze' }).outcome, 'launched');
+    assert.equal(getNode(waiting).frozen_at ?? null, null, 'a launch is the definition of not-frozen');
+    assert.equal(tf.fleet.has(waiting), true, 'the thawed node owns the freed slot');
+});

package/dist/core/__tests__/revive-parked-fresh.test.js

@@ -106,7 +106,7 @@ after(() => {
 test('a parked node with mail waiting re-enters fresh even when the caller asked to resume, and the marker clears', () => {
     parkResident('parked', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('parked');
-    const result = reviveNode('parked', { resume: true });
+    const result = reviveNode('parked', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, false, 'the concluded transcript is not replayed');
     assert.deepEqual(placements(), [{ nodeId: 'parked', resuming: false }]);
     assert.equal(kickedOff(launches[0]), true, 'the fresh window is handed its bearings');
@@ -118,12 +118,12 @@ test('a parked node with mail waiting re-enters fresh even when the caller asked
 test('a parked node grounded only by a goal still re-enters fresh when mail rides the revive', () => {
     parkResident('goal-only', { goal: 'Watch the deploy lane.' });
     deliverMail('goal-only');
-    assert.equal(reviveNode('goal-only', { resume: true }).resumed, false);
+    assert.equal(reviveNode('goal-only', { resume: true, capacity: 'freeze' }).resumed, false);
     assert.equal(kickedOff(launches[0]), true);
 });
 test('an input-less revival of a parked node quietly resumes and injects no kickoff', () => {
     parkResident('quiet', { roadmap: '# Roadmap\n\n- one open item\n' });
-    const result = reviveNode('quiet', { resume: true });
+    const result = reviveNode('quiet', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'nothing arrived, so there is nothing a fresh window would answer');
     assert.deepEqual(placements(), [{ nodeId: 'quiet', resuming: true }]);
     assert.equal(kickedOff(launches[0]), false, 'a quiet resume generates nothing');
@@ -135,20 +135,20 @@ test('an input-less revival of a parked node quietly resumes and injects no kick
 test('deferred mail alone is not input, so the revival still resumes quietly', () => {
     parkResident('deferred', { roadmap: '# Roadmap\n\n- one open item\n' });
     deliverMail('deferred', 'deferred');
-    assert.equal(reviveNode('deferred', { resume: true }).resumed, true);
+    assert.equal(reviveNode('deferred', { resume: true, capacity: 'freeze' }).resumed, true);
     assert.equal(kickedOff(launches[0]), false);
     assert.equal(readCursor('deferred'), undefined, 'the deferred entry rides the next natural cycle, unconsumed');
 });
 test('mail already covered by the cursor is not input, so the revival still resumes quietly', () => {
     parkResident('stale', { roadmap: '# Roadmap\n\n- one open item\n' });
     writeCursor('stale', deliverMail('stale'));
-    assert.equal(reviveNode('stale', { resume: true }).resumed, true, 'only the UNSEEN suffix counts as input');
+    assert.equal(reviveNode('stale', { resume: true, capacity: 'freeze' }).resumed, true, 'only the UNSEEN suffix counts as input');
     assert.equal(kickedOff(launches[0]), false);
 });
 test('a parked node with no goal and no roadmap resumes its transcript rather than waking amnesiac', () => {
     parkResident('bare');
     deliverMail('bare');
-    const result = reviveNode('bare', { resume: true });
+    const result = reviveNode('bare', { resume: true, capacity: 'freeze' });
     assert.equal(result.resumed, true, 'the degraded park has nothing on disk to ground a fresh window');
     assert.deepEqual(placements(), [{ nodeId: 'bare', resuming: true }]);
 });
@@ -156,5 +156,5 @@ test('an ordinary done node with a roadmap still resumes — only the park marke
     parkResident('finished', { roadmap: '# Roadmap\n\n- one open item\n' });
     transition('finished', 'revive');
     transition('finished', 'finish');
-    assert.equal(reviveNode('finished', { resume: true }).resumed, true);
+    assert.equal(reviveNode('finished', { resume: true, capacity: 'freeze' }).resumed, true);
 });

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

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

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

@@ -0,0 +1,81 @@
+// Run with: npm run build && node --test dist/core/__tests__/seam/broker-cap-freeze.test.js
+//
+// The cap as the host actually meets it: real broker processes, the real
+// ledger, and the real supervision tick. With CRTR_MAX_LIVE_BROKERS=2 a third
+// birth gets no engine at all — the row exists, carries the durable wait mark,
+// and holds no pid — and it survives repeated saturated ticks rather than being
+// written off as a boot failure. When a live node finishes and gives its slot
+// back, the next tick spends that slot on the waiting row and retires the mark.
+//
+// This is the whole point of P3, and none of it is observable without real
+// processes: the freeze is decided at the launch seam and the thaw is decided
+// 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 { closeDb } from '../../canvas/db.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { closeNode } from '../../runtime/close.js';
+import { spawnChild } from '../../runtime/spawn.js';
+import { createHarness } from '../helpers/harness.js';
+let h;
+let root;
+before(async () => {
+    // Read per launch by brokerThresholdsForDaemon(), so setting it before the
+    // harness boots covers every launch this file drives.
+    process.env['CRTR_MAX_LIVE_BROKERS'] = '2';
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-broker-cap' });
+    root = h.spawnRoot('broker cap suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+    delete process.env['CRTR_MAX_LIVE_BROKERS'];
+});
+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');
+    assert.equal(h.fleet.size(), 2, 'precondition: both slots are held by real brokers');
+    // The third birth meets a full ledger. spawnChild returns rather than
+    // crashing the row: a node that only has to wait is not a failed launch.
+    const born = await spawnChild({
+        kind: 'general',
+        cwd: h.node(first).cwd,
+        prompt: 'third child, born at the cap',
+        parent: root,
+    });
+    closeDb();
+    const third = born.node.node_id;
+    assert.equal(born.frozen, true, 'the birth reports that it got no engine');
+    const frozenRow = h.node(third);
+    assert.ok(frozenRow.frozen_at != null, 'the row carries the durable wait mark');
+    assert.equal(frozenRow.pi_pid ?? null, null, 'no pid was ever recorded — status surfaces read frozen, not stale-active');
+    assert.equal(h.fleet.has(third), false, 'no broker process exists for the frozen row');
+    assert.equal(h.bootCount(third), 0, 'nothing booted');
+    // Six saturated ticks: the cap is not a failure, so nothing is charged
+    // against the row and nothing terminalizes it.
+    for (let i = 0; i < 6; i++)
+        await h.tick();
+    closeDb();
+    const survived = h.node(third);
+    assert.equal(survived.status, 'active', 'six saturated ticks leave the row alive and still owed an engine');
+    assert.equal(survived.respawn_failures ?? 0, 0, 'waiting for a slot is not a respawn failure');
+    assert.equal(survived.frozen_at, frozenRow.frozen_at, 'the original wait timestamp survives — the thaw order reads it');
+    assert.equal(h.fleet.size(), 2, 'the two live brokers were never disturbed');
+    // Finish one node: its broker exits and gives the slot back.
+    const firstPid = h.node(first).pi_pid;
+    closeNode(first, { rootEvent: 'finish' });
+    closeDb();
+    await h.awaitFleetExit(first);
+    assert.equal(h.fleet.size(), 1, 'the finished node released its slot');
+    // The next tick spends the freed slot on the waiting row.
+    await h.tick();
+    closeDb();
+    await h.awaitBoot(third);
+    closeDb();
+    const thawed = h.node(third);
+    assert.equal(thawed.frozen_at ?? null, null, 'the launch retired the wait mark');
+    assert.ok(thawed.pi_pid != null && isPidAlive(thawed.pi_pid), 'the thawed node holds a live broker');
+    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');
+});