@north-light/crouter 0.3.236 → 0.3.237

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

package/dist/core/__tests__/seam/dormancy-release.test.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' });
@@ -378,7 +378,7 @@ test('a resident managed child parks without finalizing while a terminal child i
         subscribe(terminalManager, terminal, true);
         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 residentPid = await boot(resident);
@@ -439,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;