@north-light/crouter 0.3.235 → 0.3.237

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

@@ -22,7 +22,7 @@ import assert from 'node:assert/strict';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
-import { registerWarmSpare, subscribe, updateNode } from '../../canvas/index.js';
+import { registerWarmSpare, subscribe, subscriptionsOf, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { createHarness } from '../helpers/harness.js';
@@ -78,7 +78,7 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
             },
         },
     });
-    reviveNode(manager, { resume: true });
+    reviveNode(manager, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(manager);
     // A live managed child makes this unfocused terminal manager legitimately
     // awaiting, so its real stophook takes the idle-release branch.
@@ -171,7 +171,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
             },
         });
         subscribe(root, nodeId, true);
-        reviveNode(nodeId, { resume: true });
+        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
         const seenAt = 10_000;
@@ -223,7 +223,7 @@ test('a non-attending observer does not prevent unattended resident parking', {
         intent: 'idle-release',
     });
     updateNode(nodeId, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-    reviveNode(nodeId, { resume: true });
+    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
     assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
@@ -268,7 +268,7 @@ test('a connected broker viewer keeps an obligation-free resident live', { timeo
             env: {},
         },
     });
-    reviveNode(nodeId, { resume: true });
+    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     const boot = await h.awaitBoot(nodeId);
     // awaitBoot returns on the boot proof, which is written BEFORE the broker's
     // own `persistAttachState()` lays down the truthful zero state. Writing our
@@ -311,7 +311,7 @@ test('the unattended park clock cancels an obligation-free terminal node and spa
     try {
         const boot = async (id) => {
             updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
-            reviveNode(id, { resume: true });
+            reviveNode(id, { resume: true, capacity: 'freeze' });
             return (await h.awaitBoot(id)).pid;
         };
         const settled = h.fabricateBrokerNode({ id: 'terminal-no-work', parent: root, status: 'idle', intent: 'idle-release' });
@@ -349,6 +349,75 @@ test('the unattended park clock cancels an obligation-free terminal node and spa
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
     }
 });
+test('a resident managed child parks without finalizing while a terminal child is settled by the same grace sweep', { timeout: 40_000 }, async () => {
+    const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    const priorGraceMs = process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+    process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = '1000';
+    try {
+        const resident = h.fabricateBrokerNode({
+            id: 'resident-managed-child',
+            parent: root,
+            lifecycle: 'resident',
+            status: 'idle',
+            intent: 'idle-release',
+            pi_session_id: 'resident-managed-session',
+        });
+        subscribe(root, resident, true);
+        // Keep a managed terminal child in the same sweep, but make its parent
+        // historical so no live subscriber remains to hold an unfinished report.
+        const terminalManager = h.fabricateBrokerNode({ id: 'terminal-manager', status: 'done' });
+        const terminal = h.fabricateBrokerNode({
+            id: 'terminal-managed-child',
+            parent: terminalManager,
+            lifecycle: 'terminal',
+            status: 'idle',
+            intent: 'idle-release',
+            pi_session_id: 'terminal-managed-session',
+        });
+        subscribe(terminalManager, terminal, true);
+        const boot = async (id) => {
+            updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
+            reviveNode(id, { resume: true, capacity: 'freeze' });
+            return (await h.awaitBoot(id)).pid;
+        };
+        const residentPid = await boot(resident);
+        const terminalPid = await boot(terminal);
+        const seenAt = 50_000;
+        await h.tick(seenAt);
+        // Clock expiry arms the resident's pending park and requests its summary
+        // turn; the terminal child is cancelled outright by the same pass.
+        await h.tick(seenAt + 1500);
+        // Summary grace expiry: the degraded enactment parks without a report.
+        await h.tick(seenAt + 1500 + 1000);
+        await h.waitFor(() => h.node(resident)?.status === 'done' && h.node(resident)?.intent === 'parked' && !isPidAlive(residentPid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'resident managed child parks and releases its broker',
+        });
+        await h.waitFor(() => h.node(terminal)?.status === 'canceled' && !isPidAlive(terminalPid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'terminal managed child settles and releases its broker',
+        });
+        await h.awaitFleetExit(resident);
+        await h.awaitFleetExit(terminal);
+        assert.equal(h.node(resident)?.intent, 'parked', 'resident child carries the durable park marker, not a final');
+        assert.equal(h.node(resident)?.final_report ?? null, null, 'resident child has no forced final report');
+        assert.ok(subscriptionsOf(root).some((edge) => edge.node_id === resident && edge.active), 'resident child keeps its active parent subscription');
+        assert.equal(h.node(terminal)?.status, 'canceled', 'terminal child is settled by unattended grace without a final');
+    }
+    finally {
+        if (priorParkMs === undefined)
+            delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+        else
+            process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+        if (priorGraceMs === undefined)
+            delete process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+        else
+            process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = priorGraceMs;
+    }
+});
 test('an unattended resident awaiting a live child remains wakeable', { timeout: 30_000 }, async () => {
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
@@ -370,7 +439,7 @@ test('an unattended resident awaiting a live child remains wakeable', { timeout:
                 env: {},
             },
         });
-        reviveNode(nodeId, { resume: true });
+        reviveNode(nodeId, { resume: true, capacity: 'freeze' });
         const boot = await h.awaitBoot(nodeId);
         const seenAt = 20_000;
         await h.tick(seenAt);

package/dist/core/__tests__/seam/yield-refresh-transaction.test.js

@@ -65,7 +65,7 @@ test('yield-message survives one pre-session_start retry and clears on session_s
     // the retry still roots a fresh cycle carrying the note, never reopening the
     // old session. Driving reviveNode directly is exactly what focus's revive path
     // calls, minus a tmux pane this contract does not involve.
-    const focusRevive = reviveNode(id, { resume: true });
+    const focusRevive = reviveNode(id, { resume: true, capacity: 'freeze' });
     const focusPid = focusRevive.launch?.pid;
     assert.ok(focusPid != null, 'the competing focus invocation launches the replacement broker');
     assert.equal(focusRevive.resumed, false, 'refresh intent overrides this invocation\'s strict-resume request');

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

@@ -11,7 +11,7 @@
 // Every hue (fg / bg color) is gated on `caps.color`; structural SGR (bold/dim/
 // reverse) is allowed always. See detectColorCaps() for the gate, and the
 // canvas-browse color spec for the rationale + palette.
-import { STATUS_GLYPH, STATUS_COLOR, resolveNodeVisual, faultSummary } from '../status-glyph.js';
+import { STATUS_GLYPH, STATUS_COLOR, isFrozenRow, resolveNodeVisual, faultSummary } from '../status-glyph.js';
 import { TABS, matchIndices, promptText, previewSnippet } from './model.js';
 // Span/color primitives live in core/tui/draw.ts (one copy, shared with the
 // `crtr view` host). Re-export the color caps so browse's importers + tests keep
@@ -185,7 +185,11 @@ function spansWidth(spans) {
  *  node is genuinely mid-turn; otherwise the lifecycle word. The word is what makes
  *  state legible at a glance and survives NO_COLOR (the glyph is the second cue). */
 function statusRail(r) {
-    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
+    const v = resolveNodeVisual(r.status, {
+        streaming: r.streaming === true,
+        frozen: isFrozenRow(r),
+        hanging: r.hanging ?? null,
+    });
     // Plain status keeps browse's own status WORD; overlays (hanging/⟳)
     // carry their own word from resolveNodeVisual. A hanging kind label can exceed
     // STATUS_W — acceptable: the rare, attention-demanding row gets a slightly
@@ -366,7 +370,11 @@ function previewPanel(r, width, caps, now, query) {
             out.push('');
         return out;
     }
-    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
+    const v = resolveNodeVisual(r.status, {
+        streaming: r.streaming === true,
+        frozen: isFrozenRow(r),
+        hanging: r.hanging ?? null,
+    });
     const glyph = caps.color
         ? `${ESC}${v.color}m${v.glyph}${RESET}`
         : v.glyph;

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

@@ -1,4 +1,4 @@
-import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef, Mode, Lifecycle } from './types.js';
+import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef, Mode, Lifecycle, TerminalReason } from './types.js';
 /** Create a node: scaffold its dirs, persist identity to meta.json, and seed the
  *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
 export declare function createNode(meta: NodeMeta): NodeMeta;
@@ -35,6 +35,7 @@ export declare function setIntent(nodeId: string, intent: ExitIntent): void;
 export declare function transitionStatusIntent(nodeId: string, fields: {
     status?: NodeStatus;
     intent?: ExitIntent;
+    terminal_reason?: TerminalReason | null;
 }, opts?: {
     fromStatuses?: readonly NodeStatus[];
     requireNoFinalReport?: boolean;
@@ -74,7 +75,16 @@ export declare function recordPid(nodeId: string, pid: number): void;
  *  `recordPid` and must be cleared together, or a subsequent relaunch that
  *  reuses the pid namespace could compare its own fresh pid against a STALE
  *  identity left over from the pid this row held before. */
-export declare function clearPid(nodeId: string): void;
+export declare function clearRecordedPid(nodeId: string): void;
+export declare const clearPid: typeof clearRecordedPid;
+export declare function recordLaunch(nodeId: string, at: string): void;
+export declare function recordSettledTurn(nodeId: string, at: string): void;
+export declare function setFrozen(nodeId: string, at: string): void;
+export declare function clearFrozen(nodeId: string): void;
+export declare function recordRespawnAttempt(nodeId: string, attempt: {
+    failures: number;
+    notBefore: string | null;
+}): void;
 /** ONE-TIME completion of the boot-scoped-identity format migration, run once
  *  at daemon startup (the natural boot-reconciliation chokepoint, right after
  *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
@@ -119,9 +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. Unclaimed warm spares are excluded. */
+/** All rows, optionally filtered by status and by carrying a recorded pid (the
+ *  supervision tick's terminal-row query). Unclaimed warm spares are excluded. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];
+    withRecordedPid?: boolean;
 }): NodeRow[];
 /** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
  *  from every listing until it is claimed. */

package/dist/core/canvas/canvas.js

@@ -13,10 +13,9 @@ import { isPidAlive, recordedPidLiveness, capturePidIdentities, identitiesMatch,
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
 // meta.json (durable identity — the source of truth for what PERSISTS)
 //
-// One authoritative store per fact: meta.json holds NodeIdentity only; the six
-// runtime fields (status, intent, pi_pid, window, tmux_session, pane) are
-// authoritative in the WAL'd `nodes` row, each mutated by one atomic setter
-// below. getNode() hydrates the two back into the historical NodeMeta view.
+// One authoritative store per fact: meta.json holds NodeIdentity only; live
+// runtime fields are authoritative in the WAL'd `nodes` row. getNode() hydrates
+// the two back into the historical NodeMeta view.
 /** 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 = [
@@ -129,6 +128,12 @@ function rowFrom(r) {
         created: r['created'],
         intent: r['intent'] ?? null,
         waiting_for: r['waiting_for'] ?? null,
+        frozen_at: r['frozen_at'] ?? null,
+        respawn_failures: r['respawn_failures'] ?? 0,
+        respawn_not_before: r['respawn_not_before'] ?? null,
+        launched_at: r['launched_at'] ?? null,
+        last_settled_at: r['last_settled_at'] ?? null,
+        terminal_reason: r['terminal_reason'] ?? null,
         final_report: r['final_report'] ?? null,
         finalized_at: r['finalized_at'] ?? null,
         pi_pid: r['pi_pid'] ?? null,
@@ -142,7 +147,7 @@ function rowFrom(r) {
  *  no row exists yet (the hydration then falls back to whatever the meta held). */
 function runtimeFromRow(nodeId) {
     const r = openDb()
-        .prepare('SELECT status, intent, waiting_for, final_report, finalized_at, pi_pid, pi_pid_identity, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
+        .prepare('SELECT status, intent, waiting_for, frozen_at, respawn_failures, respawn_not_before, launched_at, last_settled_at, terminal_reason, final_report, finalized_at, pi_pid, pi_pid_identity, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
         .get(nodeId);
     if (r === undefined)
         return null;
@@ -150,6 +155,12 @@ function runtimeFromRow(nodeId) {
         status: r['status'] ?? 'active',
         intent: r['intent'] ?? null,
         waiting_for: r['waiting_for'] ?? null,
+        frozen_at: r['frozen_at'] ?? null,
+        respawn_failures: r['respawn_failures'] ?? 0,
+        respawn_not_before: r['respawn_not_before'] ?? null,
+        launched_at: r['launched_at'] ?? null,
+        last_settled_at: r['last_settled_at'] ?? null,
+        terminal_reason: r['terminal_reason'] ?? null,
         final_report: r['final_report'] ?? null,
         finalized_at: r['finalized_at'] ?? null,
         pi_pid: r['pi_pid'] ?? null,
@@ -273,6 +284,10 @@ export function transitionStatusIntent(nodeId, fields, opts = {}) {
         assignments.push('intent = ?');
         values.push(fields.intent ?? null);
     }
+    if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
+        assignments.push('terminal_reason = ?');
+        values.push(fields.terminal_reason ?? null);
+    }
     const predicates = ['node_id = ?'];
     values.push(nodeId);
     if (opts.fromStatuses !== undefined) {
@@ -334,9 +349,29 @@ export function recordPid(nodeId, pid) {
  *  `recordPid` and must be cleared together, or a subsequent relaunch that
  *  reuses the pid namespace could compare its own fresh pid against a STALE
  *  identity left over from the pid this row held before. */
-export function clearPid(nodeId) {
+export function clearRecordedPid(nodeId) {
     openDb().prepare('UPDATE nodes SET pi_pid = NULL, pi_pid_identity = NULL WHERE node_id = ?').run(nodeId);
 }
+export const clearPid = clearRecordedPid;
+export function recordLaunch(nodeId, at) {
+    openDb()
+        .prepare('UPDATE nodes SET launched_at = ?, frozen_at = NULL, respawn_not_before = NULL WHERE node_id = ?')
+        .run(at, nodeId);
+}
+export function recordSettledTurn(nodeId, at) {
+    openDb().prepare('UPDATE nodes SET last_settled_at = ? WHERE node_id = ?').run(at, nodeId);
+}
+export function setFrozen(nodeId, at) {
+    openDb().prepare('UPDATE nodes SET frozen_at = ? WHERE node_id = ?').run(at, nodeId);
+}
+export function clearFrozen(nodeId) {
+    openDb().prepare('UPDATE nodes SET frozen_at = NULL WHERE node_id = ?').run(nodeId);
+}
+export function recordRespawnAttempt(nodeId, attempt) {
+    openDb()
+        .prepare('UPDATE nodes SET respawn_failures = ?, respawn_not_before = ? WHERE node_id = ?')
+        .run(attempt.failures, attempt.notBefore, nodeId);
+}
 /** ONE-TIME completion of the boot-scoped-identity format migration, run once
  *  at daemon startup (the natural boot-reconciliation chokepoint, right after
  *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
@@ -421,20 +456,21 @@ export function listNodesByProfile(profileId) {
         return meta;
     });
 }
-/** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
+/** All rows, optionally filtered by status and by carrying a recorded pid (the
+ *  supervision tick's terminal-row query). Unclaimed warm spares are excluded. */
 export function listNodes(filter) {
-    const db = openDb();
-    let rows;
+    const clauses = [NOT_A_SPARE];
+    const params = [];
     if (filter?.status !== undefined) {
         const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
-        const placeholders = statuses.map(() => '?').join(',');
-        rows = db
-            .prepare(`SELECT * FROM nodes WHERE status IN (${placeholders}) AND ${NOT_A_SPARE} ORDER BY created`)
-            .all(...statuses);
-    }
-    else {
-        rows = db.prepare(`SELECT * FROM nodes WHERE ${NOT_A_SPARE} ORDER BY created`).all();
+        clauses.push(`status IN (${statuses.map(() => '?').join(',')})`);
+        params.push(...statuses);
     }
+    if (filter?.withRecordedPid === true)
+        clauses.push('pi_pid IS NOT NULL');
+    const rows = openDb()
+        .prepare(`SELECT * FROM nodes WHERE ${clauses.join(' AND ')} ORDER BY created`)
+        .all(...params);
     return rows.map(rowFrom);
 }
 // Warm pool — spare booted roots awaiting a `prefer_warm` claim (see

package/dist/core/canvas/migrations.js

@@ -1215,6 +1215,26 @@ function addNodeSessionFileIndex(db) {
     }
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
 }
+/** v35 — durable node lifecycle execution state and terminal cause. */
+function addNodeLifecycleColumns(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'frozen_at', 'ALTER TABLE nodes ADD COLUMN frozen_at TEXT;');
+    addNodeColumnIfMissing(db, columns, 'respawn_failures', 'ALTER TABLE nodes ADD COLUMN respawn_failures INTEGER NOT NULL DEFAULT 0;');
+    addNodeColumnIfMissing(db, columns, 'respawn_not_before', 'ALTER TABLE nodes ADD COLUMN respawn_not_before TEXT;');
+    addNodeColumnIfMissing(db, columns, 'launched_at', 'ALTER TABLE nodes ADD COLUMN launched_at TEXT;');
+    addNodeColumnIfMissing(db, columns, 'last_settled_at', 'ALTER TABLE nodes ADD COLUMN last_settled_at TEXT;');
+    addNodeColumnIfMissing(db, columns, 'terminal_reason', 'ALTER TABLE nodes ADD COLUMN terminal_reason TEXT;');
+    db.exec(`
+UPDATE nodes SET terminal_reason = CASE
+  WHEN status = 'done' AND final_report IS NOT NULL THEN 'finalized'
+  WHEN status = 'done' AND intent = 'parked'        THEN 'parked'
+  WHEN status = 'done'                              THEN 'finished'
+  WHEN status = 'canceled'                          THEN 'stranded'
+  WHEN status = 'dead'                              THEN 'crashed'
+END
+WHERE status IN ('done','canceled','dead') AND terminal_reason IS NULL;
+`);
+}
 /** The journaled lane of the state-migration registry, adapted to this chain's
  *  step shape. Registry order is preserved, so these versions stay stable as
  *  long as the registry is append-only (same contract as the local list). */
@@ -1262,6 +1282,7 @@ export const MIGRATIONS = [
     /* v32 */ addCronHeldColumns,
     /* v33 */ addHumanActionDeliveries,
     /* v34 */ addNodeSessionFileIndex,
+    /* v35 */ addNodeLifecycleColumns,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/canvas/nav-render.js

@@ -14,7 +14,7 @@ import { isPidAlive } from './pid.js';
 import { isBusy } from '../runtime/busy.js';
 import { readFault } from '../runtime/fault.js';
 import { activeFaultForDisplay } from './render-source.js';
-import { resolveNodeVisual } from './status-glyph.js';
+import { isFrozenRow, resolveNodeVisual } from './status-glyph.js';
 // Tuning constants
 /** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
  *  array widget; anything beyond it pi truncates with its own "... (widget
@@ -62,6 +62,8 @@ export function nodeGlyph(node, remote = false) {
         return '?';
     const v = resolveNodeVisual(node.status, {
         streaming: remote ? false : streamingFor(node),
+        // Durable row state, so it holds for a remote node too.
+        frozen: isFrozenRow(node),
         hanging: remote ? null : hangingFor(node),
     });
     return `${ESC}${v.color}m${v.glyph}${RESET}`;

package/dist/core/canvas/remote-canvas-source.js

@@ -161,6 +161,8 @@ export class RemoteCanvasSource {
             created: n.created,
             intent: n.intent ?? null,
             waiting_for: n.waiting_for ?? null,
+            frozen_at: n.frozen_at ?? null,
+            terminal_reason: n.terminal_reason ?? null,
             pi_pid: n.pi_pid ?? null,
             pi_pid_identity: n.pi_pid_identity ?? null,
             window: n.window ?? null,

package/dist/core/canvas/render-source.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasSource } from './source.js';
 import { type Fault } from '../runtime/fault.js';
-import type { NodeStatus, Lifecycle, NodeMeta, NodeRow } from './types.js';
+import type { NodeStatus, Lifecycle, NodeMeta, NodeRow, TerminalReason } from './types.js';
 export declare function activeFaultForDisplay<T extends {
     status: NodeStatus;
     pi_pid?: number | null;
@@ -24,6 +24,8 @@ export interface DashboardRow {
     /** Generated first-task description. Searchable below user-authored prompts. */
     description?: string;
     status: NodeStatus;
+    frozen_at?: string | null;
+    terminal_reason?: TerminalReason | null;
     kind: string;
     mode: string;
     ctx_tokens: number;

package/dist/core/canvas/render-source.js

@@ -18,7 +18,7 @@ import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
 import { jobDir, contextDir } from './paths.js';
 import { isPidAlive } from './pid.js';
-import { resolveNodeVisual, faultSummary } from './status-glyph.js';
+import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
 import { parseCard } from '../../shared/generated-context.js';
 // Active-fault overlay: stale daemon-owned provider faults are hidden once the
@@ -63,7 +63,7 @@ async function nodeLineFromSource(source, nodeId, indent, connector, remote, tic
     if (node === null)
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
     const hanging = remote ? null : hangingFor(node);
-    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
     const asks = tickets[nodeId] ?? 0;
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
@@ -114,7 +114,7 @@ export async function renderTreeFromSource(source, rootId) {
     const asks = tickets[rootId] ?? 0;
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const hanging = remote ? null : hangingFor(node);
-    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     const out = [];
     out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
@@ -388,6 +388,8 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
         handle: row.name,
         status: row.status,
+        frozen_at: row.frozen_at ?? null,
+        terminal_reason: row.terminal_reason ?? null,
         kind: row.kind,
         mode: row.mode,
         ctx_tokens: 0, // lazy: enrichRow
@@ -423,6 +425,8 @@ export async function dashboardRowsFromSource(source, rootId) {
             handle: node.name,
             description: node.description,
             status: node.status,
+            frozen_at: node.frozen_at ?? null,
+            terminal_reason: node.terminal_reason ?? null,
             kind: node.kind,
             mode: node.mode,
             ctx_tokens: tel.tokens_in ?? 0,

package/dist/core/canvas/status-glyph.d.ts

@@ -15,10 +15,19 @@ export interface NodeVisual {
     word?: string;
     bold?: boolean;
 }
+/** Whether a row is frozen: the broker ledger marked it waiting for a slot and
+ *  no process holds it. Both halves matter — a launch clears `frozen_at`, so a
+ *  mark sitting beside a live pid is stale rather than frozen. A projection
+ *  that carries no pid at all (the dashboard row) reads on the mark alone. */
+export declare function isFrozenRow(row: {
+    frozen_at?: string | null;
+    pi_pid?: number | null;
+}): boolean;
 /** Resolve a node's glyph + hue + overlay word, applying the precedence
- *  hanging > streaming > status. */
+ *  hanging > frozen > streaming > status. */
 export declare function resolveNodeVisual(status: NodeStatus, opts: {
     streaming?: boolean;
+    frozen?: boolean;
     hanging?: Fault | {
         kind: FaultKind;
     } | null;

package/dist/core/canvas/status-glyph.js

@@ -1,8 +1,11 @@
 // status-glyph.ts — the canonical status glyph and color map used by the canvas
 // ASCII forest and interactive browser. The overlay precedence is
-// hanging > streaming > status. `hanging` and `streaming` are
+// hanging > frozen > streaming > status. `hanging` and `streaming` are
 // mutually exclusive in practice (hanging means the turn ended, so `busy` is
-// gone) but the precedence is defined regardless.
+// gone) but the precedence is defined regardless. `frozen` outranks `streaming`
+// because a frozen row has no process at all: any streaming read against it is
+// a stale marker, and showing it as active is the lie the freeze state exists
+// to stop telling.
 import { FAULT_QUIET_MS } from '../runtime/fault.js';
 // ── Status glyphs (the mono, color-free primary encoding) ─────────────────────
 export const STATUS_GLYPH = {
@@ -24,6 +27,9 @@ export const STATUS_COLOR = {
 // ── Streaming overlay (genuinely mid-turn) — browse's existing statusRail visual.
 const STREAMING_GLYPH = '⟳';
 const STREAMING_COLOR = 92; // bright green (brighter than active-status green)
+// ── Frozen overlay (waiting on a broker slot: marked, but no process). ───────
+const FROZEN_GLYPH = '◌';
+const FROZEN_COLOR = 94; // bright blue
 // ── Active-fault overlay (one glyph, kind label carries the detail). ─────────
 export const HANGING_GLYPH = '⚠';
 export const HANGING_COLOR = 33; // yellow
@@ -42,12 +48,22 @@ export function hangingLabel(kind) {
         default: return 'other';
     }
 }
+/** Whether a row is frozen: the broker ledger marked it waiting for a slot and
+ *  no process holds it. Both halves matter — a launch clears `frozen_at`, so a
+ *  mark sitting beside a live pid is stale rather than frozen. A projection
+ *  that carries no pid at all (the dashboard row) reads on the mark alone. */
+export function isFrozenRow(row) {
+    return row.frozen_at != null && row.pi_pid == null;
+}
 /** Resolve a node's glyph + hue + overlay word, applying the precedence
- *  hanging > streaming > status. */
+ *  hanging > frozen > streaming > status. */
 export function resolveNodeVisual(status, opts) {
     if (opts.hanging != null) {
         return { glyph: HANGING_GLYPH, color: HANGING_COLOR, word: hangingLabel(opts.hanging.kind), bold: true };
     }
+    if (opts.frozen === true) {
+        return { glyph: FROZEN_GLYPH, color: FROZEN_COLOR, word: 'frozen' };
+    }
     if (opts.streaming === true) {
         return { glyph: STREAMING_GLYPH, color: STREAMING_COLOR, word: 'live', bold: true };
     }

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

@@ -11,13 +11,14 @@
  *  only `dead` is a fault. */
 export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
- *  resident = interactable while attached or holding a live obligation. An
- *  unattended obligation-free resident completes after the daemon grace. */
+ *  resident = an interactable conversation that parks and remains wakeable
+ *  without being forced to submit a final. */
 export type Lifecycle = 'terminal' | 'resident';
 /** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
 export type Mode = 'base' | 'orchestrator';
 /** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
 export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
+export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded';
 /** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
  *  org chart, views, completion routing). `spawned_by` is audit only. */
 export type EdgeType = 'subscribes_to' | 'spawned_by';
@@ -48,7 +49,7 @@ export interface LaunchSpec {
     env: Record<string, string>;
 }
 export interface ManagedWorktree {
-    state: 'open' | 'closed';
+    state: 'open' | 'closed' | 'abandoned';
     /** A closed worktree remains registered until its owner has exited, so Git
      *  never deletes the caller's live checkout beneath it. */
     cleanup?: 'pending' | 'complete';
@@ -59,6 +60,12 @@ export interface ManagedWorktree {
     base_sha: string;
     created: string;
     closed?: string;
+    abandoned?: {
+        branch: string;
+        tip_sha: string;
+        at: string;
+        by: string;
+    };
 }
 /** Immutable companion provenance. The origin session/leaf/model coordinates
  *  remain canonical in the review row rather than being duplicated into node
@@ -181,6 +188,12 @@ export interface NodeRuntime {
     /** Controller whose next inbox delivery permits this terminal node to sleep.
      * Mutable durable runtime state: ancestry never implies a wait. */
     waiting_for?: string | null;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
     /** Immutable basename of the committed canonical final report, or null. */
     final_report?: string | null;
     /** ISO timestamp carried by the committed canonical final report, or null. */
@@ -244,6 +257,12 @@ export interface NodeRow {
     /** Authoritative runtime columns (see NodeRuntime). */
     intent: ExitIntent;
     waiting_for: string | null;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
     final_report?: string | null;
     finalized_at?: string | null;
     pi_pid: number | null;

package/dist/core/feed/feed.js

@@ -91,7 +91,7 @@ function commitCanonicalFinal(nodeId, staged) {
         const subscribers = db.prepare(`SELECT from_id AS node_id, active, created FROM edges WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`).all(nodeId).map((row) => ({ node_id: row['node_id'], active: row['active'] === 1, created: row['created'] }));
         install(staged);
         installed = true;
-        db.prepare("UPDATE nodes SET status = 'done', intent = 'done', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
+        db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
         db.exec('COMMIT');
         return { subscribers };
     }

package/dist/core/human/feedback-companion.js

@@ -40,7 +40,7 @@ function materializeFeedbackBranch(dir, capture) {
  * the first-comment race to a concurrently recorded companion. */
 export function discardFeedbackCompanion(nodeId) {
     try {
-        transition(nodeId, 'cancel');
+        transition(nodeId, 'cancel', { reason: 'retired' });
         headlessBrokerHost.teardown(nodeId);
     }
     catch { /* the refusal is authoritative; a straggler node is inert */ }
@@ -88,7 +88,10 @@ export async function realizeFeedbackCompanion(args) {
     });
     try {
         initializeForkContextExposure(node.node_id, args.senderNodeId);
-        reviveNode(node.node_id, { resume: false });
+        // The bind deadline below only a live broker can meet, so a capacity
+        // refusal must surface here and discard the companion — freezing would
+        // burn the whole deadline waiting for a launch that is not coming.
+        reviveNode(node.node_id, { resume: false, capacity: 'refuse' });
         if (!await awaitCompanionBind(node.node_id, COMPANION_BIND_DEADLINE_MS)) {
             throw new Error(`feedback companion did not bind within ${COMPANION_BIND_DEADLINE_MS}ms`);
         }