@north-light/crouter 0.3.249 → 0.3.251

package/dist/core/__tests__/seam/broker-provider-retry.test.js

@@ -7,12 +7,12 @@
 // its helpers in isolation.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHeadlessHarness } from '../helpers/harness.js';
 import { createAttachKit } from '../helpers/broker-clients.js';
 import { defaultModelLaddersConfig } from '../../../types.js';
-import { readFault } from '../../runtime/fault.js';
+import { admitProviderRetryEpisode, readFault, readProviderRetryEpisode } from '../../runtime/fault.js';
 import { buildPiArgv, normalizeModel } from '../../runtime/launch.js';
 import { encodeFrame } from '../../runtime/broker-protocol.js';
 const MODEL_LADDERS = defaultModelLaddersConfig();
@@ -79,6 +79,18 @@ function agentStartCount(id) {
         return 0;
     }
 }
+async function crashAndRespawn(id, boots) {
+    const pid = h.node(id)?.pi_pid;
+    assert.ok(pid != null, 'the broker has a live pid before its physical death');
+    process.kill(pid, 'SIGKILL');
+    await h.awaitFleetExit(id);
+    await h.tick();
+    const deferred = h.node(id);
+    assert.ok(deferred.respawn_not_before != null, 'the daemon records respawn backoff after the broker exit');
+    await h.tick(Date.parse(deferred.respawn_not_before) + 1);
+    await h.awaitBoot(id, { minCount: boots + 1 });
+    await h.waitFor(() => existsSync(h.brokerSock(id)), { label: 'replacement broker listener bound' });
+}
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-provider-retry' });
 });
@@ -130,6 +142,73 @@ test('a managed-cooling terminal authors a rate-limit auto fault whose deadline
     await new Promise((resolve) => setTimeout(resolve, 2500));
     assert.equal(agentStartCount(child), baselineStarts + 1, 'the fault-retry timer re-drives the turn exactly once');
 });
+test('a crashed broker re-drives only its pending provider episode, never admitted or invalidated episodes', { timeout: 90_000 }, async () => {
+    const parent = h.spawnRoot('durable provider episode parent');
+    seedPool('anthropic', false);
+    seedPool('openai-codex', false);
+    const pendingNode = await h.spawnHeadlessChild(parent, 'pending provider episode', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(pendingNode) >= 1, { label: 'pending episode fixture started' });
+    const pendingStarts = agentStartCount(pendingNode);
+    h.fakeCmd(pendingNode, {
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 2_000,
+    });
+    const pending = await h.waitFor(() => readProviderRetryEpisode(pendingNode)?.state === 'pending' ? readProviderRetryEpisode(pendingNode) : null, { label: 'pending provider episode persisted before crash' });
+    assert.equal(pending.sessionFile, realpathSync(h.node(pendingNode).pi_session_file), 'the pending episode is tied to its transcript path');
+    await crashAndRespawn(pendingNode, h.bootCount(pendingNode));
+    await h.waitFor(() => agentStartCount(pendingNode) >= pendingStarts + 1, { label: 'replacement re-drove the pending episode' });
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    assert.equal(agentStartCount(pendingNode), pendingStarts + 1, 'a pending episode re-drives exactly once after broker death');
+    const admittedNode = await h.spawnHeadlessChild(parent, 'admitted provider episode', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(admittedNode) >= 1, { label: 'admitted episode fixture started' });
+    const admittedStarts = agentStartCount(admittedNode);
+    h.fakeCmd(admittedNode, {
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
+    });
+    const admittedPending = await h.waitFor(() => readProviderRetryEpisode(admittedNode)?.state === 'pending' ? readProviderRetryEpisode(admittedNode) : null, { label: 'admitted episode pending record persisted' });
+    const admittedFault = readFault(admittedNode);
+    assert.ok(admittedFault !== null, 'the pending episode retains its retry fault before admission');
+    assert.equal(admitProviderRetryEpisode(admittedNode, admittedPending.sessionFile, admittedFault), true, 'the dispatch boundary durably admits the matching episode');
+    assert.equal(readProviderRetryEpisode(admittedNode)?.state, 'admitted');
+    await crashAndRespawn(admittedNode, h.bootCount(admittedNode));
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    assert.equal(agentStartCount(admittedNode), admittedStarts, 'an admitted episode is never replayed by replacement startup');
+    const invalidatedNode = await h.spawnHeadlessChild(parent, 'invalidated provider episode', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(invalidatedNode) >= 1, { label: 'invalidated episode fixture started' });
+    const invalidatedStarts = agentStartCount(invalidatedNode);
+    h.fakeCmd(invalidatedNode, {
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
+    });
+    await h.waitFor(() => readProviderRetryEpisode(invalidatedNode)?.state === 'pending' ? true : null, { label: 'invalidated episode pending record persisted' });
+    const controller = await kit.attach(invalidatedNode, 'controller', 'invalidated-provider-episode');
+    controller.send({ type: 'new_session' });
+    await controller.waitFrame((frame) => frame.type === 'ack' && frame.for === 'new_session', 'replacement session acknowledged');
+    assert.equal(readFault(invalidatedNode), null, 'replacement discards the old daemon-owned auto fault instead of inheriting its anchor');
+    await h.waitFor(() => readProviderRetryEpisode(invalidatedNode)?.state === 'invalidated' ? true : null, { label: 'rebind durably invalidated the old episode' });
+    controller.close();
+    await crashAndRespawn(invalidatedNode, h.bootCount(invalidatedNode));
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    assert.equal(agentStartCount(invalidatedNode), invalidatedStarts, 'an invalidated rebound-session episode is never replayed by replacement startup');
+    const cyclingNode = await h.spawnHeadlessChild(parent, 'fresh-cycle provider episode', { model: OPENAI_STRONG.spec });
+    await h.waitFor(() => agentStartCount(cyclingNode) >= 1, { label: 'fresh-cycle episode fixture started' });
+    h.fakeCmd(cyclingNode, {
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
+    });
+    await h.waitFor(() => readProviderRetryEpisode(cyclingNode)?.state === 'pending' ? true : null, { label: 'fresh-cycle episode pending record persisted' });
+    const cyclingBoots = h.bootCount(cyclingNode);
+    const yieldResult = h.cli(cyclingNode, ['node', 'yield', 'begin a fresh cycle']);
+    assert.equal(yieldResult.code, 0, `node yield should succeed\n--stderr--\n${yieldResult.stderr}`);
+    const cyclingPid = h.node(cyclingNode)?.pi_pid;
+    assert.ok(cyclingPid != null, 'the refresh-pending broker remains live until its physical death');
+    process.kill(cyclingPid, 'SIGKILL');
+    await h.awaitFleetExit(cyclingNode);
+    await h.tick();
+    const cyclingBackoff = h.node(cyclingNode);
+    assert.ok(cyclingBackoff.respawn_not_before != null, 'the fresh-cycle relaunch receives daemon backoff');
+    await h.tick(Date.parse(cyclingBackoff.respawn_not_before) + 1);
+    await h.awaitBoot(cyclingNode, { minCount: cyclingBoots + 1 });
+    await h.waitFor(() => existsSync(h.brokerSock(cyclingNode)), { label: 'fresh-cycle replacement broker listener bound' });
+    assert.equal(readProviderRetryEpisode(cyclingNode)?.state, 'invalidated', 'new-cycle startup invalidates the old transcript episode');
+});
 test('reload_auth re-drives a parked fatal provider-auth turn exactly once', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('auth reload parent');
     seedPool('anthropic', false);

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

@@ -194,7 +194,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
         assert.equal(h.node(nodeId)?.status, 'done', 'the row is terminal and eligible for history pruning');
         const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
         assert.ok(wake, 'the subscribing root is woken when the unattended clock completes the resident');
-        assert.match(wake.label, /sent no final report/, 'the wake distinguishes automatic completion from a final report');
+        assert.match(wake.label, /submitted no final report/, 'the wake distinguishes automatic completion from a final report');
         await h.tick();
         assert.equal(h.fleet.has(nodeId), false, 'a supervision tick does not revive completed history');
     }

package/dist/core/__tests__/seam/held-deferred-human-prompt.test.d.ts

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

package/dist/core/__tests__/seam/held-deferred-human-prompt.test.js

@@ -0,0 +1,63 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/held-deferred-human-prompt.test.js
+//
+// Regression: Pi loads canvas extensions through Jiti with moduleCache:false,
+// while broker frame dispatch is native ESM. Deferred mail held by the Jiti
+// watcher must still join the next human prompt driven by native broker code.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendInbox, readCursor } from '../../feed/inbox.js';
+import { updateNode } from '../../canvas/index.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit, delay, frameHas, tok } from '../helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-held-deferred-prompt' });
+    root = h.spawnRoot('held deferred prompt seam root');
+});
+after(async () => {
+    kit.closeAll();
+    if (h !== undefined)
+        await h.dispose();
+});
+test('a Jiti-loaded watcher prepends its held deferred batch to a native broker human prompt', { timeout: 30_000 }, async () => {
+    const nodeId = h.fabricateBrokerNode({
+        id: 'held-deferred-human-prompt',
+        parent: root,
+        lifecycle: 'resident',
+        status: 'idle',
+    });
+    updateNode(nodeId, {
+        launch: {
+            extensions: [],
+            tools: [],
+            systemPrompt: '',
+            env: {
+                CRTR_WATCHER_TICK_MS: '20',
+                CRTR_WATCHER_DEBOUNCE_MS: '25',
+            },
+        },
+    });
+    reviveNode(nodeId, { resume: true, capacity: 'freeze' });
+    await h.awaitBoot(nodeId);
+    const entry = appendInbox(nodeId, {
+        from: 'child',
+        tier: 'deferred',
+        kind: 'update',
+        label: 'held Jiti deferred update',
+    });
+    await delay(150);
+    const customPath = join(h.home, 'nodes', nodeId, 'fake-pi.custom-messages.jsonl');
+    assert.equal(existsSync(customPath), false, 'deferred-only mail stays held and does not wake the broker');
+    const controller = await kit.attach(nodeId, 'controller', 'held-deferred-prompt-controller');
+    const prompt = tok('HELD-DEFERRED-HUMAN-PROMPT');
+    controller.send({ type: 'prompt', text: prompt });
+    await controller.waitFrame((frame) => frame.type === 'agent_end' && frameHas(frame, prompt), 'the human prompt turn');
+    const customMessages = readFileSync(customPath, 'utf8');
+    assert.match(customMessages, /held Jiti deferred update/, 'the Jiti extension instance joined its held batch before the native broker prompt');
+    assert.equal(readCursor(nodeId), entry.entry_id, 'agent_settled commits the joined handoff');
+});

package/dist/core/__tests__/seam/self-close-teardown.test.d.ts

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

package/dist/core/__tests__/seam/self-close-teardown.test.js

@@ -0,0 +1,49 @@
+// Run with: npm run build && node --test dist/core/__tests__/seam/self-close-teardown.test.js
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPidAlive } from '../../canvas/pid.js';
+import { nodeDir } from '../../canvas/paths.js';
+import { createHarness } from '../helpers/harness.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-self-close' });
+    root = h.spawnRoot('self-close teardown root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('a node closes itself without killing its long-lived calling shell', { timeout: 60_000 }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'self-close worker');
+    const brokerPid = h.node(id)?.pi_pid;
+    assert.ok(brokerPid != null && isPidAlive(brokerPid), 'precondition: worker broker is alive');
+    const session = h.node(id)?.pi_session_file;
+    assert.ok(session != null, 'worker has a session file');
+    writeFileSync(session, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'work' }] } }) + '\n');
+    const dir = nodeDir(id);
+    const resultPath = join(dir, 'self-close-result');
+    const shellPidPath = join(dir, 'self-close-shell.pid');
+    let shellPid;
+    try {
+        h.fakeCmd(id, { cmd: 'self_close' });
+        await h.waitFor(() => existsSync(resultPath), { label: 'self-close CLI result' });
+        assert.equal(readFileSync(resultPath, 'utf8').trim(), '0', 'the shell received a successful close result');
+        shellPid = Number(readFileSync(shellPidPath, 'utf8').trim());
+        assert.ok(Number.isInteger(shellPid) && shellPid > 0, 'fixture recorded the long-lived calling shell pid');
+        assert.equal(isPidAlive(shellPid), true, 'the calling shell survives the daemon teardown');
+        await h.waitFor(() => !isPidAlive(brokerPid), { label: 'self-closing broker exits' });
+        assert.equal(isPidAlive(shellPid), true, 'the calling shell remains alive after the broker is gone');
+        assert.equal(h.status(id), 'canceled', 'close writes the terminal transition before teardown');
+    }
+    finally {
+        if (shellPid !== undefined) {
+            try {
+                process.kill(shellPid, 'SIGKILL');
+            }
+            catch { /* shell already exited */ }
+        }
+    }
+});

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

@@ -24,8 +24,8 @@ after(async () => {
     if (h !== undefined)
         await h.dispose();
 });
-// 30s (approved compiled-seam cap): three real broker boots plus the exit-policy
-// respawn throttle's first ~5s backoff before the successful retry.
+// 30s (approved compiled-seam cap): three real broker boots plus the durable
+// respawn backoff's first ~5s delay before the successful retry.
 test('yield-message survives one pre-session_start retry and clears on session_start', { timeout: 30_000 }, async () => {
     const note = `Issue #146 pre-session_start replay ${FAIL_BEFORE_SESSION_START_ONCE} keeps the wake note`;
     const id = await h.spawnHeadlessChild(root, 'headless worker — yield message transactional retry');
@@ -35,29 +35,37 @@ test('yield-message survives one pre-session_start retry and clears on session_s
     const rc = h.cli(id, ['node', 'yield', note]);
     assert.equal(rc.code, 0, `node yield should succeed\n--stderr--\n${rc.stderr}`);
     // `node yield` arms intent=refresh; the current turn ending is what lets the
-    // stophook release the old broker. Its real ChildProcess exit enqueues policy
-    // row 3 and launches the fresh cycle (after any short-lived-exit backoff), so
-    // there is no liveness tick or grace clock.
+    // stophook release the old broker. The supervision tick classifies that real
+    // ChildProcess exit, persists its backoff, and launches the fresh cycle once
+    // the backoff matures.
     await h.stop(id);
     await h.waitFor(() => !isPidAlive(oldPid), { label: 'yielded broker exited before session_start' });
+    await h.awaitFleetExit(id);
+    await h.tick();
+    const initialRefreshBackoff = h.node(id);
+    assert.equal(initialRefreshBackoff.respawn_failures, 1, 'the old broker death is durably counted');
+    assert.ok(initialRefreshBackoff.respawn_not_before != null, 'the initial refresh retry is durably deferred');
+    assert.equal(initialRefreshBackoff.pi_pid, null, 'classification clears the old broker pid');
+    await h.tick(Date.parse(initialRefreshBackoff.respawn_not_before) + 1);
     // The initial refresh attempt launches and fails before session_start,
     // leaving the note still present in node context.
     const failedCyclePid = await h.waitFor(() => {
         const pid = h.node(id)?.pi_pid;
         return pid != null && pid !== oldPid ? pid : null;
-    }, { label: 'exit-event refresh attempt recorded its broker pid', timeoutMs: 30_000 });
+    }, { label: 'tick-driven refresh attempt recorded its broker pid', timeoutMs: 30_000 });
     await h.waitFor(() => !isPidAlive(failedCyclePid), { label: 'one-shot cycling broker died before session_start' });
     // PID death precedes Node's ChildProcess `exit` delivery. Wait through the
-    // authoritative fleet barrier and its queued exit-policy job so the contender
-    // below reaches refresh arbitration instead of returning on stale liveness.
-    // The policy has only armed its backoff timer at this point; no recovery broker
-    // owns the slot yet.
+    // authoritative fleet barrier, then classify the failure once so the contender
+    // below reaches refresh arbitration while durable backoff is pending.
     await h.awaitFleetExit(id);
+    await h.tick();
     const afterFirstExit = h.node(id);
     assert.equal(h.fleet.has(id), false, 'the failed broker has left the authoritative fleet before focus competes');
     assert.equal(afterFirstExit?.cycles, baseCycles + 1, 'the first refresh attempt advances cycles');
     assert.equal(afterFirstExit?.intent, 'refresh', 'the durable refresh intent still confronts the strict-resume contender');
     assert.equal(afterFirstExit?.cycle_pending, true, 'cycle_pending remains true until session_start confirms');
+    assert.equal(afterFirstExit?.respawn_failures, 2, 'the failed refresh attempt is durably counted');
+    assert.ok(afterFirstExit?.respawn_not_before != null, 'focus competes while the durable refresh backoff is pending');
     assert.equal(readYieldMessage(id), note, 'yield note stays present after pre-session_start failure');
     assert.equal(existsSync(yieldMessagePath(id)), true, 'yield file survives the failed cycle');
     // A real `surface node focus` on the node right now asks the revive arbiter for

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

@@ -334,6 +334,10 @@ export interface PruneResult {
     pruned: PrunedNode[];
     dryRun: boolean;
 }
+/** Whether a row may be removed by an automatic collection sweep. */
+export declare function isCollectible(row: NodeRow, opts?: {
+    pastTtl?: boolean;
+}): boolean;
 /** {@link deleteNode}'s result: whether it actually deleted the node. */
 export interface DeleteNodeResult {
     deleted: boolean;
@@ -396,24 +400,14 @@ export declare function pruneNodes(opts: {
  *  store rather than per-node loss, and reaps nothing. Returns the reaped ids. */
 export declare function reapGhostRows(): string[];
 /** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
- *  nodes plus every protected node, so the real retained floor is
- *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the
- *  TTL sweep can't (a canvas that never crosses the TTL still grows without
+ *  nodes plus every row the collection authority retains, so the real retained
+ *  floor is `max(maxNodes, retainedCount)`. Bounds the otherwise-unbounded growth
+ *  the TTL sweep can't (a canvas that never crosses the TTL still grows without
  *  limit).
  *
- *  Protected (never a prune candidate, regardless of recency rank): any
- *  non-terminal node — status active|idle — REGARDLESS of `pi_pid` liveness,
- *  or a node with an open managed worktree. A crashed-but-non-terminal row
- *  (dead pid, status still active/idle) must survive for daemon crash-recovery
- *  to resume, and an open worktree must retain its node ownership until
- *  `node worktree close`; neither is eligible for count-based pruning. The caller
- *  ($CRTR_NODE_ID) is also always protected.
- *
  *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
- *  to `created`); `target = max(maxNodes, protectedCount)`; delete every node
- *  ranked beyond `target` (0-indexed rank >= target) that is NOT protected and
- *  NOT the caller. Retained = all protected + the newest terminal nodes up to
- *  `target`.
+ *  to `created`); `target = max(maxNodes, retainedCount)`; delete every node
+ *  ranked beyond `target` (0-indexed rank >= target) that is collectible.
  *
  *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
  *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`

package/dist/core/canvas/canvas.js

@@ -20,7 +20,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, }
  *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
 const IDENTITY_KEYS = [
     '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',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'creator', 'fork_from', 'fork_source_file', 'review_binding', 'passive_default', 'pi_session_id',
     'pi_session_file', 'cycle_pending', 'model_override',
     'launch', 'managed_worktree',
 ];
@@ -208,12 +208,13 @@ export function canonicalSessionFile(sessionFile) {
 /** Resolve the crouter node that owns one exact Pi session file. */
 export function findNodeBySessionFile(sessionFile) {
     const canonical = canonicalSessionFile(sessionFile);
-    const matches = openDb()
-        .prepare('SELECT node_id FROM nodes WHERE pi_session_file = ? ORDER BY created')
-        .all(canonical);
-    if (matches.length > 1)
-        throw new Error(`multiple nodes own pi session file: ${canonical}`);
-    return matches[0] === undefined ? null : getNode(matches[0].node_id);
+    // v36 makes this unique. LIMIT 1 also keeps the lookup total for a canvas
+    // opened during repair of an older duplicate projection: the deterministic
+    // oldest row remains the owner instead of turning a lookup into a crash.
+    const match = openDb()
+        .prepare('SELECT node_id FROM nodes WHERE pi_session_file = ? ORDER BY created, node_id LIMIT 1')
+        .get(canonical);
+    return match === undefined ? null : getNode(match.node_id);
 }
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export function getRow(nodeId) {
@@ -839,6 +840,16 @@ export function rebuildIndex() {
 function hasOpenManagedWorktree(nodeId) {
     return getNode(nodeId)?.managed_worktree?.state === 'open';
 }
+/** Whether a row may be removed by an automatic collection sweep. */
+export function isCollectible(row, opts = {}) {
+    if (!['done', 'dead', 'canceled'].includes(row.status)
+        || row.pi_pid !== null
+        || row.frozen_at !== null
+        || hasOpenManagedWorktree(row.node_id)
+        || row.node_id === envNodeId())
+        return false;
+    return opts.pastTtl === true || !['crashed', 'stranded', null].includes(row.terminal_reason ?? null);
+}
 /** Hard-delete ONE node: drop its row (the edges→nodes FK, ON DELETE CASCADE,
  *  GCs its edges) and remove its on-disk `nodes/<id>/` dir. The single-node
  *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
@@ -905,14 +916,13 @@ export function pruneNodes(opts) {
     const selfId = envNodeId() ?? '';
     const db = openDb();
     const terminal = db
-        .prepare(`SELECT node_id, status, created FROM nodes
-         WHERE status IN ('dead', 'done', 'canceled') AND created < ?
-         ORDER BY created`)
-        .all(cutoff).map((r) => ({
-        node_id: r['node_id'],
-        status: r['status'],
-        created: r['created'],
-    }));
+        .prepare(`SELECT * FROM nodes
+       WHERE status IN ('dead', 'done', 'canceled') AND created < ?
+       ORDER BY created`)
+        .all(cutoff)
+        .map(rowFrom)
+        .filter((row) => isCollectible(row, { pastTtl: true }))
+        .map((row) => ({ node_id: row.node_id, status: row.status, created: row.created }));
     // Stale non-terminal sweep (opt-in): active | idle past the TTL whose process
     // is provably gone (pi_pid NULL or not alive). Never the caller itself.
     const stale = !includeStale ? [] : db
@@ -930,8 +940,9 @@ export function pruneNodes(opts) {
         node_id: r['node_id'],
         status: r['status'],
         created: r['created'],
-    }));
-    const candidates = [...terminal, ...stale].filter((node) => !hasOpenManagedWorktree(node.node_id));
+    }))
+        .filter((node) => !hasOpenManagedWorktree(node.node_id));
+    const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     deletePrunedNodes(candidates);
@@ -1015,50 +1026,33 @@ function recencyMs(nodeId, created) {
     return Number.isNaN(t) ? 0 : t;
 }
 /** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
- *  nodes plus every protected node, so the real retained floor is
- *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the
- *  TTL sweep can't (a canvas that never crosses the TTL still grows without
+ *  nodes plus every row the collection authority retains, so the real retained
+ *  floor is `max(maxNodes, retainedCount)`. Bounds the otherwise-unbounded growth
+ *  the TTL sweep can't (a canvas that never crosses the TTL still grows without
  *  limit).
  *
- *  Protected (never a prune candidate, regardless of recency rank): any
- *  non-terminal node — status active|idle — REGARDLESS of `pi_pid` liveness,
- *  or a node with an open managed worktree. A crashed-but-non-terminal row
- *  (dead pid, status still active/idle) must survive for daemon crash-recovery
- *  to resume, and an open worktree must retain its node ownership until
- *  `node worktree close`; neither is eligible for count-based pruning. The caller
- *  ($CRTR_NODE_ID) is also always protected.
- *
  *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
- *  to `created`); `target = max(maxNodes, protectedCount)`; delete every node
- *  ranked beyond `target` (0-indexed rank >= target) that is NOT protected and
- *  NOT the caller. Retained = all protected + the newest terminal nodes up to
- *  `target`.
+ *  to `created`); `target = max(maxNodes, retainedCount)`; delete every node
+ *  ranked beyond `target` (0-indexed rank >= target) that is collectible.
  *
  *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
  *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
  *  reports the candidate set and deletes NOTHING. */
 export function pruneToLimit(opts) {
     const dryRun = opts.dryRun ?? false;
-    const selfId = envNodeId() ?? '';
     const rows = listNodes();
-    // Rank ALL nodes by recency DESC, tagging protection as we go. Protection is
-    // status-only (active|idle) — NOT gated on pi_pid liveness — so a node whose
-    // broker crashed but whose row is still non-terminal stays protected for
-    // crash-recovery instead of being hard-deleted here.
     const ranked = rows
-        .map((r) => ({
-        node_id: r.node_id,
-        status: r.status,
-        created: r.created,
-        recency: recencyMs(r.node_id, r.created),
-        protected: r.status === 'active' || r.status === 'idle' || hasOpenManagedWorktree(r.node_id),
+        .map((row) => ({
+        row,
+        recency: recencyMs(row.node_id, row.created),
+        retained: !isCollectible(row),
     }))
         .sort((a, b) => b.recency - a.recency);
-    const protectedCount = ranked.filter((r) => r.protected).length;
-    const target = Math.max(opts.maxNodes, protectedCount);
+    const retainedCount = ranked.filter((r) => r.retained).length;
+    const target = Math.max(opts.maxNodes, retainedCount);
     const candidates = ranked
-        .filter((r, rank) => rank >= target && !r.protected && r.node_id !== selfId)
-        .map((r) => ({ node_id: r.node_id, status: r.status, created: r.created }));
+        .filter((r, rank) => rank >= target && !r.retained)
+        .map(({ row }) => ({ node_id: row.node_id, status: row.status, created: row.created }));
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     deletePrunedNodes(candidates);

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

@@ -185,14 +185,11 @@ export declare function setCronLastOutputHash(cron_id: string, hash: string): vo
  *  terminal node that stopped without finishing. */
 export declare function hasPendingCancelOnWakeCron(anchor_node: string): boolean;
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
- *  relaunch, which only replaces a dead broker instance and leaves the wait
- *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
- *  with the node, so its deadline must not fire against a finalized or closed
- *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
- *  Kills any in-flight
- *  run process group first (the cancelCron discipline), under one canvas write
- *  boundary. Returns the removed cron ids. */
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement is not a wake. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns removed cron ids. */
 export declare function cancelCronsOnWake(anchor_node: string): string[];
 /** UPDATE the next fire time — recurrence advancement. The daemon settles a
  *  recurring row to its next slot BEFORE enacting the run (crash-safe). */

package/dist/core/canvas/crons.js

@@ -269,14 +269,11 @@ export function hasPendingCancelOnWakeCron(anchor_node) {
         .get(anchor_node) !== undefined);
 }
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
- *  relaunch, which only replaces a dead broker instance and leaves the wait
- *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
- *  with the node, so its deadline must not fire against a finalized or closed
- *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
- *  Kills any in-flight
- *  run process group first (the cancelCron discipline), under one canvas write
- *  boundary. Returns the removed cron ids. */
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement is not a wake. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns removed cron ids. */
 export function cancelCronsOnWake(anchor_node) {
     return withCanvasWrite((db) => {
         const rows = db

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

@@ -53,6 +53,11 @@ export interface CorpusFilter {
  *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
  *  when not run as a node. */
 export declare function callerCwd(): string;
+/** The history ref of a node's newest report, or null when it left none.
+ *  Report filenames lead with a compact timestamp, so the lexicographic maximum
+ *  is the latest one. Callers use this to hand a reader something they can
+ *  actually open (`crtr canvas history read <ref>`) instead of a bare node id. */
+export declare function newestReportRef(nodeId: string): string | null;
 /** Build the searchable artifact set for a scope + corpus filter. Node facets
  *  are applied against the db rows first (cheap); only surviving nodes' files
  *  are read. */

package/dist/core/canvas/history.js

@@ -220,7 +220,7 @@ function metaArtifact(row, desc) {
         loadBody: () => body,
     };
 }
-/** List the markdown reports a node left, newest filename first. */
+/** List the markdown reports a node left, in directory order. */
 function listReportFiles(nodeId) {
     const dir = reportsDir(nodeId);
     if (!pathExists(dir))
@@ -232,6 +232,17 @@ function listReportFiles(nodeId) {
         return [];
     }
 }
+/** The history ref of a node's newest report, or null when it left none.
+ *  Report filenames lead with a compact timestamp, so the lexicographic maximum
+ *  is the latest one. Callers use this to hand a reader something they can
+ *  actually open (`crtr canvas history read <ref>`) instead of a bare node id. */
+export function newestReportRef(nodeId) {
+    let newest = null;
+    for (const f of listReportFiles(nodeId))
+        if (newest === null || f > newest)
+            newest = f;
+    return newest === null ? null : `${nodeId}:reports/${newest}`;
+}
 /** Enumerate every context markdown doc a node left (recursive). */
 function listDocFiles(nodeId) {
     const dir = contextDir(nodeId);