@north-light/crouter 0.3.241 → 0.3.243

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

package/dist/core/review/realize.js

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

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

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

package/dist/core/runtime/host.js

@@ -206,121 +206,132 @@ export const headlessBrokerHost = {
         if (!fleet.reserveSlot(nodeId)) {
             throw brokerCapReached(brokerThresholdsForDaemon().automaticReviveCap, fleet.size());
         }
-        // Redirect the detached broker's stdout+stderr to a per-node log under the
-        // node's existing job/ dir. It retains arbitrary engine/process residue and
-        // failed-canonical fatal fallback output. Append-mode preserves crash-revive history.
-        const logDir = jobDir(nodeId);
-        mkdirSync(logDir, { recursive: true });
-        const logFd = openSync(join(logDir, 'broker.log'), 'a');
-        // Launch from the crouter-branded host binary (a copy of node) so the
-        // broker shows "crouter" in macOS Full Disk Access, not "node". On
-        // non-darwin / dev / tests this is just process.execPath (see branded-host).
-        // buildBrokerEnv's default-deny allowlist has no `CRTR_` prefix, so a bare
-        // `CRTR_BROKER_ENGINE` set only in the LAUNCHING process's ambient env (the
-        // T11 test seam — see broker-sdk.ts) would never reach the child, which
-        // would silently fall back to booting the real SDK. Inject the SAME value
-        // preflightBrokerLaunch already resolved+validated above: it is
-        // parent-resolved, crtr-trusted data (the same trust category as
-        // `inv.env`), not a blanket `CRTR_*` passthrough, so this does not weaken
-        // the allowlist's hardening. In production `engineSpec` is always the real
-        // SDK default, so this is a no-op there.
-        const engineSpec = resolveEngineSpec(inv);
-        const childEnv = { ...buildBrokerEnv(inv), CRTR_BROKER_ENGINE: engineSpec };
-        // NODE_OPTIONS is deliberately absent from the operational allowlist (it is
-        // a code-execution vector — `--require`/`--import` — and DAEMON_ENV_STRIP_KEYS
-        // strips it from the daemon's own env for the identical reason: a poisoned
-        // NODE_OPTIONS in an inheriting shell must never reach a process that then
-        // handles model credentials). It is genuinely needed ONLY for the T11 test
-        // seam above: the fake engine is a `.ts` fixture, and the broker CLI entry
-        // itself is only a `.js` file under the compiled `dist/`, so the harness
-        // relies on `NODE_OPTIONS=--import tsx/esm` (set on its own ambient env, same
-        // seam as CRTR_BROKER_ENGINE) to make the spawned child resolve both under
-        // tsx. Gating this carry on `engineSpec !== DEFAULT_BROKER_ENGINE` — i.e. only
-        // when the trusted test seam above already fired — keeps production (where
-        // the engine is never overridden) byte-identical to today: NODE_OPTIONS is
-        // never forwarded there, so an ambient poisoned value stays contained.
-        if (engineSpec !== DEFAULT_BROKER_ENGINE) {
-            const nodeOptions = inv.env['NODE_OPTIONS'] ?? process.env['NODE_OPTIONS'];
-            if (nodeOptions !== undefined)
-                childEnv['NODE_OPTIONS'] = nodeOptions;
-        }
-        if (eventSource() === undefined)
-            bindBrokerEventSource(nodeId);
-        // `--canvas-home` declares broker ownership in argv so the daemon's
-        // startup epoch census can match its own canvas' brokers exactly (crtrd's
-        // brokerCommandDeclaresCanvasHome) instead of inferring from install
-        // paths; `--epoch` stamps WHICH daemon epoch launched it, so the next
-        // daemon's census reaps every prior-epoch broker without adoption (D-8).
-        // Both precede the node id: the node id is by contract the FINAL argv
-        // token (both broker-cli and the ps census parse it that way).
+        let logFd = null;
         let child;
+        let registered = false;
         try {
-            child = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
+            // Redirect the detached broker's stdout+stderr to a per-node log under the
+            // node's existing job/ dir. It retains arbitrary engine/process residue and
+            // failed-canonical fatal fallback output. Append-mode preserves crash-revive history.
+            const logDir = jobDir(nodeId);
+            mkdirSync(logDir, { recursive: true });
+            logFd = openSync(join(logDir, 'broker.log'), 'a');
+            // Launch from the crouter-branded host binary (a copy of node) so the
+            // broker shows "crouter" in macOS Full Disk Access, not "node". On
+            // non-darwin / dev / tests this is just process.execPath (see branded-host).
+            // buildBrokerEnv's default-deny allowlist has no `CRTR_` prefix, so a bare
+            // `CRTR_BROKER_ENGINE` set only in the LAUNCHING process's ambient env (the
+            // T11 test seam — see broker-sdk.ts) would never reach the child, which
+            // would silently fall back to booting the real SDK. Inject the SAME value
+            // preflightBrokerLaunch already resolved+validated above: it is
+            // parent-resolved, crtr-trusted data (the same trust category as
+            // `inv.env`), not a blanket `CRTR_*` passthrough, so this does not weaken
+            // the allowlist's hardening. In production `engineSpec` is always the real
+            // SDK default, so this is a no-op there.
+            const engineSpec = resolveEngineSpec(inv);
+            const childEnv = { ...buildBrokerEnv(inv), CRTR_BROKER_ENGINE: engineSpec };
+            // NODE_OPTIONS is deliberately absent from the operational allowlist (it is
+            // a code-execution vector — `--require`/`--import` — and DAEMON_ENV_STRIP_KEYS
+            // strips it from the daemon's own env for the identical reason: a poisoned
+            // NODE_OPTIONS in an inheriting shell must never reach a process that then
+            // handles model credentials). It is genuinely needed ONLY for the T11 test
+            // seam above: the fake engine is a `.ts` fixture, and the broker CLI entry
+            // itself is only a `.js` file under the compiled `dist/`, so the harness
+            // relies on `NODE_OPTIONS=--import tsx/esm` (set on its own ambient env, same
+            // seam as CRTR_BROKER_ENGINE) to make the spawned child resolve both under
+            // tsx. Gating this carry on `engineSpec !== DEFAULT_BROKER_ENGINE` — i.e. only
+            // when the trusted test seam above already fired — keeps production (where
+            // the engine is never overridden) byte-identical to today: NODE_OPTIONS is
+            // never forwarded there, so an ambient poisoned value stays contained.
+            if (engineSpec !== DEFAULT_BROKER_ENGINE) {
+                const nodeOptions = inv.env['NODE_OPTIONS'] ?? process.env['NODE_OPTIONS'];
+                if (nodeOptions !== undefined)
+                    childEnv['NODE_OPTIONS'] = nodeOptions;
+            }
+            if (eventSource() === undefined)
+                bindBrokerEventSource(nodeId);
+            // `--canvas-home` declares broker ownership in argv so the daemon's
+            // startup epoch census can match its own canvas' brokers exactly (crtrd's
+            // brokerCommandDeclaresCanvasHome) instead of inferring from install
+            // paths; `--epoch` stamps WHICH daemon epoch launched it, so the next
+            // daemon's census reaps every prior-epoch broker without adoption (D-8).
+            // Both precede the node id: the node id is by contract the FINAL argv
+            // token (both broker-cli and the ps census parse it that way).
+            const spawned = spawn(hostExecPath(), [resolveBrokerEntry(), '--canvas-home', crtrHome(), '--epoch', fleet.epoch(), nodeId], {
                 cwd: opts.cwd,
                 detached: true,
                 stdio: ['ignore', logFd, logFd],
                 env: childEnv,
             });
-        }
-        catch (error) {
-            fleet.releaseReservation(nodeId);
+            child = spawned;
+            // The child holds its own dup of the fd; release the parent's copy so the
+            // launching process (CLI or daemon) never leaks it.
             closeSync(logFd);
-            throw error;
-        }
-        // The child holds its own dup of the fd; release the parent's copy so the
-        // launching process (CLI or daemon) never leaks it.
-        closeSync(logFd);
-        // ONE seam for every launch path (revive/spawn/recycle/reset): record the
-        // child's real exit status as a canonical event. Readiness waits consume
-        // `exited` for fail-fast and then discard it, so before this a broker that
-        // was SIGKILLed out from under crouter left NO trace anywhere — an external
-        // kill was indistinguishable from a silent early return, and post-mortems
-        // were unprovable (see the 2026-07-27 "brokers die at startup" RCA).
-        // Emitted through the ordinary bound source: in the daemon (the process
-        // that actually launches brokers) that is the daemon stream carrying
-        // `node_id`, which is how every other daemon-observed broker event
-        // (broker.wedge.detected, broker.yield_stall.*) is recorded and how a
-        // node-scoped log query finds it. The node's own job/log.jsonl is the
-        // BROKER's stream — the reader rejects any non-broker-component line there
-        // (events/read.ts descriptorMatches) — so the daemon must not write into
-        // it. A process already bound to this node's broker source (in-process
-        // revive) naturally lands there instead.
-        const launchedAt = Date.now();
-        const exited = new Promise((resolve) => {
-            let settled = false;
-            const finish = (state) => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve(state);
-            };
-            child.once('exit', (code, signal) => {
-                emitEvent({
-                    level: code === 0 ? 'info' : 'warn',
-                    event: 'broker.exited',
-                    node_id: nodeId,
-                    fields: { code, signal, uptime_ms: Date.now() - launchedAt },
+            logFd = null;
+            // ONE seam for every launch path (revive/spawn/recycle/reset): record the
+            // child's real exit status as a canonical event. Readiness waits consume
+            // `exited` for fail-fast and then discard it, so before this a broker that
+            // was SIGKILLed out from under crouter left NO trace anywhere — an external
+            // kill was indistinguishable from a silent early return, and post-mortems
+            // were unprovable (see the 2026-07-27 "brokers die at startup" RCA).
+            // Emitted through the ordinary bound source: in the daemon (the process
+            // that actually launches brokers) that is the daemon stream carrying
+            // `node_id`, which is how every other daemon-observed broker event
+            // (broker.wedge.detected, broker.yield_stall.*) is recorded and how a
+            // node-scoped log query finds it. The node's own job/log.jsonl is the
+            // BROKER's stream — the reader rejects any non-broker-component line there
+            // (events/read.ts descriptorMatches) — so the daemon must not write into
+            // it. A process already bound to this node's broker source (in-process
+            // revive) naturally lands there instead.
+            const launchedAt = Date.now();
+            const exited = new Promise((resolve) => {
+                let settled = false;
+                const finish = (state) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(state);
+                };
+                spawned.once('exit', (code, signal) => {
+                    emitEvent({
+                        level: code === 0 ? 'info' : 'warn',
+                        event: 'broker.exited',
+                        node_id: nodeId,
+                        fields: { code, signal, uptime_ms: Date.now() - launchedAt },
+                    });
+                    finish({ code, signal });
                 });
-                finish({ code, signal });
+                spawned.once('error', () => finish({ code: null, signal: null }));
             });
-            child.once('error', () => finish({ code: null, signal: null }));
-        });
-        child.unref();
-        const handle = { pid: child.pid ?? null, exited };
-        // Register the live handle synchronously — the fleet entry IS the node's
-        // liveness from here on, and its real `exit` event (never a pid probe)
-        // drives dead-node policy. A null pid (spawn itself failed) registers
-        // nothing: the `exited` promise resolves via the 'error' event and the
-        // caller's own null-pid check surfaces the failure.
-        if (handle.pid !== null) {
-            fleet.register(nodeId, handle);
-            void exited.then((status) => fleet.onChildExit(nodeId, status));
+            spawned.unref();
+            const handle = { pid: spawned.pid ?? null, exited };
+            // Register the live handle synchronously — the fleet entry IS the node's
+            // liveness from here on, and its real `exit` event (never a pid probe)
+            // drives dead-node policy. A null pid (spawn itself failed) registers
+            // nothing: the `exited` promise resolves via the 'error' event and the
+            // caller's own null-pid check surfaces the failure.
+            if (handle.pid !== null) {
+                fleet.register(nodeId, handle);
+                registered = true;
+                void exited.then((status) => fleet.onChildExit(nodeId, status));
+            }
+            return handle;
+        }
+        catch (error) {
+            if (!registered && child?.pid != null) {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* no fleet handle exists to tear down */ }
+            }
+            throw error;
         }
-        else {
-            // Nothing was registered, so nothing will ever free this slot at exit.
-            fleet.releaseReservation(nodeId);
+        finally {
+            if (!registered)
+                fleet.releaseReservation(nodeId);
+            if (logFd !== null)
+                closeSync(logFd);
         }
-        return handle;
     },
     isAlive(node) {
         return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);

package/dist/core/runtime/lifecycle.js

@@ -63,8 +63,9 @@ const TRANSITIONS = {
     crash: { status: 'dead', from: LIVE },
     // requestYield · relaunchRoot new-node safety net. Status KEPT (already active).
     yield: { intent: 'refresh', from: LIVE },
-    // stophook idle-release: free the host, stay woken by the inbox.
-    release: { status: 'idle', intent: 'idle-release', from: LIVE },
+    // Free the host, stay woken by the inbox. A parked resident can also drain
+    // here after a capacity freeze without spending a slot.
+    release: { status: 'idle', intent: 'idle-release', from: [...LIVE, 'done'] },
     // reviveNode provisional refresh launch: activate without committing the
     // refresh until session_start proves the engine booted.
     'refresh-launch': { status: 'active', intent: 'refresh', from: ANY },

package/dist/core/runtime/naming.d.ts

@@ -2,8 +2,18 @@
  *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
  *  single hyphen, and clamps to the first 8 words. */
 export declare function sanitizeSessionName(raw: string): string;
-/** Local fallback: derive a name straight from the prompt (no pi call). Drops
- *  stop-words, takes the first few content words. */
+/** Coerce arbitrary text into a one-line prose title, or '' if nothing usable
+ *  survives. Takes the first non-empty line, collapses runs of whitespace, drops
+ *  wrapping quotes, clamps at a word boundary, and capitalizes the opening
+ *  letter. Punctuation INSIDE the line survives — carrying it is what `title`
+ *  is for. */
+export declare function sanitizeSessionTitle(raw: string): string;
+/** Local fallback: the opening of the prompt as a title (no pi call), with its
+ *  punctuation. Whitespace collapses first so a multi-line message contributes
+ *  its actual opening words rather than whatever its first line happened to be. */
+export declare function titleFromPrompt(prompt: string): string;
+/** Local fallback: derive a kebab handle straight from the prompt (no pi call),
+ *  from the same opening words the fallback title keeps. */
 export declare function slugFromPrompt(prompt: string): string;
 /** The namer's model: the `light` rung of the DEFAULT provider's ladder, with
  *  any thinking suffix stripped because the one-shot session uses thinking off.
@@ -11,11 +21,14 @@ export declare function slugFromPrompt(prompt: string): string;
  *  user who never configured Anthropic: an OpenAI default provider resolves to
  *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
 export declare function lightModel(overrideEnv?: string): string;
-/** A generated session name: the kebab-case handle plus the Nerd Font glyph the
- *  namer chose for it. `icon` is '' when the model returned nothing usable —
- *  every surface renders the name alone in that case. */
+/** A generated session label: the kebab-case handle, the prose title, and the
+ *  Nerd Font glyph the namer chose. `title` is '' when the model gave nothing
+ *  usable, leaving the caller to fall back to the prompt's own opening words;
+ *  `icon` is '' on the same terms, and every surface renders the name alone in
+ *  that case. */
 export interface SessionName {
     name: string;
+    title: string;
     icon: string;
 }
 /** Normalize a model-supplied icon to a single renderable glyph, or '' when
@@ -30,9 +43,14 @@ export interface SessionName {
  *  `nf-fa-bug`, a bare ASCII letter, and anything multi-glyph, all of which
  *  would render as noise or tofu in a label. */
 export declare function sanitizeIcon(raw: string): string;
-/** Ask Pi headlessly for a structured {name, icon} for `body`, async. Resolves
- *  to a sanitized SessionName, or `{name:'',icon:''}` on timeout, a missing tool
- *  call, or a malformed emission so the caller can fall back to a local slug.
+/** Ask Pi headlessly for a structured {name, title, icon} for `body`, async.
+ *  Resolves to a sanitized SessionName, or `{name:'',title:'',icon:''}` on
+ *  timeout, a missing tool call, or a malformed emission so the caller can fall
+ *  back to the prompt's own words.
+ *
+ *  Nothing FORCES the tool call — constrained sampling shapes the arguments once
+ *  the model decides to call it — so a model that answers in prose instead gets
+ *  one more attempt before the caller falls back.
  *
  *  This module stays canvas-free so CLI leaves can reach it. The canvas-coupled
  *  commit path lives in pi-extensions/broker-local.ts, which imports this pure