@north-light/crouter 0.3.251 → 0.3.252

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -15,7 +15,7 @@ import { drainBearings } from '../runtime/kickoff.js';
 import { appendSituationalContext } from '../runtime/situational-context.js';
 import { createEngineDriver } from '../runtime/broker/engine-drive.js';
 import { createTurnAdmissionGate } from '../runtime/broker/turn-admission.js';
-import { heldDeferredInboxPromptJoin } from '../runtime/broker/held-deferred-inbox.js';
+import { BROKER_IDLE_TURN_START, heldDeferredInboxPromptJoin, } from '../runtime/broker/held-deferred-inbox.js';
 import { createNode, getNode, recordPid, setIntent } from '../canvas/canvas.js';
 import { createProfile, pauseProfile, resumeProfile } from '../profiles/manifest.js';
 import { closeDb } from '../canvas/db.js';
@@ -47,7 +47,7 @@ function makeFakePi() {
     const handlers = {};
     let resolveFirstInjection;
     const firstInjection = new Promise((resolve) => { resolveFirstInjection = resolve; });
-    return {
+    const pi = {
         injected: [],
         firstInjection,
         sentMessages: [],
@@ -59,6 +59,8 @@ function makeFakePi() {
         sendMessage(message) { this.sentMessages.push(message); },
         async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
     };
+    globalThis[BROKER_IDLE_TURN_START] = (content) => pi.sendUserMessage(content);
+    return pi;
 }
 // Fire agent_settled — the authoritative durable-commit boundary in the
 // at-least-once model. `pending` maps to pi's `hasPendingMessages()` and is

package/dist/core/__tests__/canvas-inbox-watcher-naming.test.js

@@ -30,6 +30,7 @@ import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { appendInbox } from '../feed/inbox.js';
+import { BROKER_IDLE_TURN_START } from '../runtime/broker/held-deferred-inbox.js';
 const TICK_MS = 20;
 const DEBOUNCE_MS = 25;
 let home;
@@ -76,7 +77,7 @@ function getRequestCount(nodeId) {
 }
 function makeFakePi() {
     const handlers = {};
-    return {
+    const pi = {
         injected: [],
         sentMessages: [],
         on(e, h) { handlers[e] = h; },
@@ -84,6 +85,8 @@ function makeFakePi() {
         sendMessage(message) { this.sentMessages.push(message); },
         fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
     };
+    globalThis[BROKER_IDLE_TURN_START] = (content) => pi.sendUserMessage(content);
+    return pi;
 }
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 async function waitFor(predicate, timeoutMs = 3000, stepMs = 10) {

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -18,6 +18,7 @@ import { closeDb } from '../canvas/db.js';
 import { appendInbox, coalesce, finalizeInboxEntry } from '../feed/inbox.js';
 import { appendSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../runtime/situational-context.js';
 import { parseCard } from '../../shared/generated-context.js';
+import { BROKER_IDLE_TURN_START } from '../runtime/broker/held-deferred-inbox.js';
 // Drive the watcher's injectable cadence seam (CRTR_WATCHER_TICK_MS /
 // CRTR_WATCHER_DEBOUNCE_MS) at a fast tempo so the watcher delivers in tens of
 // milliseconds, not seconds — exactly the resolve+seed tick, read tick, and
@@ -40,7 +41,7 @@ function freshNode(nodeId) {
 }
 function makeFakePi() {
     const handlers = {};
-    return {
+    const pi = {
         injected: [],
         sentMessages: [],
         on(e, h) { handlers[e] = h; },
@@ -48,6 +49,8 @@ function makeFakePi() {
         sendMessage(message) { this.sentMessages.push(message); },
         fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
     };
+    globalThis[BROKER_IDLE_TURN_START] = (content) => pi.sendUserMessage(content);
+    return pi;
 }
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 /** The text of a batch that must coalesce into exactly one delivery. */

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -193,7 +193,9 @@ declare class FakeSession {
     getSessionStats(): Record<string, unknown>;
     private syncTreeSnapshot;
     setSessionName(_name: string): void;
-    prompt(text: string, _options?: unknown): Promise<void>;
+    prompt(text: string, options?: {
+        preflightResult?: (success: boolean) => void;
+    }): Promise<void>;
     /** The unrun queues the welcome snapshot reports (`snapshot.queued`). Real
      *  pi holds a steer + followUp queue and drains it when the next turn runs;
      *  the fake records the same texts and clears them in emitTurn, so a client

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -448,12 +448,18 @@ class FakeSession {
         /* no-op recording stub */
     }
     // controller-drive stubs (no controller connects in these tests)
-    prompt(text, _options) {
+    prompt(text, options) {
         // Rejection seam: the engine refuses the call itself (pi's no-provider-
         // credential shape) — the promise rejects and NO lifecycle event fires.
         if (text.includes(REJECT_PROMPT_CALL)) {
             return Promise.reject(new Error('No API key found for anthropic'));
         }
+        options?.preflightResult?.(true);
+        // The inbox watcher now enters through the broker-owned prompt bridge, not
+        // the Pi extension runtime. Keep its existing observable wake record for
+        // the compiled dormancy seam while the prompt drives the real lifecycle.
+        if (text.startsWith('<runtime kind="inbox"'))
+            this.recordInjected({ content: text });
         // The broker calls this for the controller-less retry path. Emit the turn
         // on the broker's subscribe channel and also run the real extension hooks so
         // the canvas stophook records the fault marker and the broker can schedule

package/dist/core/__tests__/integration/deferred-no-wake.test.js

@@ -50,6 +50,7 @@ import { canvasDbPath, nodeDir, apiSocketPath } from '../../canvas/paths.js';
 import { closeDb } from '../../canvas/db.js';
 import { createApiServer } from '../../../daemon/api/server.js';
 import { CrtrClient } from '../../../api/index.js';
+import { BROKER_IDLE_TURN_START } from '../../runtime/broker/held-deferred-inbox.js';
 import { registerNode } from '../../../commands/node.js';
 import { pushFinal } from '../../feed/feed.js';
 import { InputError } from '../../io.js';
@@ -500,13 +501,15 @@ test('the lifecycle tick parks a resident holding deferred-only mail — mail th
 });
 function makeFakePi() {
     const handlers = {};
-    return {
+    const pi = {
         injected: [],
         on(e, h) { handlers[e] = h; },
         sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
         sendMessage() { },
         async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
     };
+    globalThis[BROKER_IDLE_TURN_START] = (content) => pi.sendUserMessage(content);
+    return pi;
 }
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 test('the real inbox watcher holds a deferred entry alone, then delivers it TOGETHER with a later normal entry with no duplicate/loss, and the durable cursor settles past both (gh #341 review: genuine delivery, not just the daemon decision)', { timeout: 30_000 }, async () => {

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

@@ -215,36 +215,82 @@ test('a fresh db has the four additive runtime columns', () => {
     assert.equal(rt['window'], null);
     assert.equal(rt['tmux_session'], null);
 });
-test('session-file ownership migration deterministically clears duplicate claimants before creating its UNIQUE index', () => {
+test('session-file ownership migration reconciles authoritative metas before clearing duplicate claimants', () => {
     ensureHome();
     const raw = new DatabaseSync(canvasDbPath());
     migrateToVersion(raw, 35);
     const sessionFile = '/tmp/preexisting-duplicate.jsonl';
     const aliasedSessionFile = '/tmp/./preexisting-duplicate.jsonl';
-    for (const id of ['first-owner', 'later-claimant']) {
+    const recoveredSessionFile = '/tmp/recovered-session.jsonl';
+    const metas = [
+        ['first-owner', '2026-01-01T00:00:00.000Z', sessionFile],
+        ['later-claimant', '2026-01-02T00:00:00.000Z', aliasedSessionFile],
+        // The durable meta write survived, but the derived row below is stale.
+        ['recovered-claimant', '2026-01-03T00:00:00.000Z', recoveredSessionFile],
+    ];
+    for (const [id, created, pi_session_file] of metas) {
         const nodeDir = join(home, 'nodes', id);
         mkdirSync(nodeDir, { recursive: true });
         writeFileSync(join(nodeDir, 'meta.json'), JSON.stringify({
-            node_id: id, name: id, created: id === 'first-owner' ? '2026-01-01T00:00:00.000Z' : '2026-01-02T00:00:00.000Z',
-            cwd: '/tmp', kind: 'developer', mode: 'base', lifecycle: 'terminal', pi_session_id: `${id}-session`, pi_session_file: id === 'first-owner' ? sessionFile : aliasedSessionFile,
+            node_id: id, name: id, created, cwd: '/tmp', kind: 'developer', mode: 'base', lifecycle: 'terminal', pi_session_id: `${id}-session`, pi_session_file,
         }));
     }
-    raw.prepare('INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, pi_session_file) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
-        .run('first-owner', 'first-owner', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-01T00:00:00.000Z', sessionFile);
-    raw.prepare('INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, pi_session_file) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
-        .run('later-claimant', 'later-claimant', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-02T00:00:00.000Z', aliasedSessionFile);
+    const insert = raw.prepare('INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, pi_session_file) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    insert.run('first-owner', 'first-owner', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-01T00:00:00.000Z', sessionFile);
+    insert.run('later-claimant', 'later-claimant', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-02T00:00:00.000Z', aliasedSessionFile);
+    insert.run('recovered-claimant', 'recovered-claimant', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-03T00:00:00.000Z', sessionFile);
     assert.doesNotThrow(() => migrate(raw), 'a real canvas with pre-existing duplicates must migrate');
     const rows = raw.prepare('SELECT node_id, pi_session_file FROM nodes ORDER BY created, node_id').all();
     assert.deepEqual(rows.map((row) => [row.node_id, row.pi_session_file]), [
         ['first-owner', sessionFile],
         ['later-claimant', null],
-    ], 'the oldest created row wins after aliases are canonicalized; later claimants are cleared');
+        ['recovered-claimant', recoveredSessionFile],
+    ], 'the oldest duplicate is retained while a stale row is reconciled from its authoritative meta');
     const loser = JSON.parse(readFileSync(join(home, 'nodes', 'later-claimant', 'meta.json'), 'utf8'));
-    assert.equal(loser.pi_session_id, null, 'the loser meta cannot reindex its stale session id');
-    assert.equal(loser.pi_session_file, null, 'the loser meta cannot restore the duplicate projection');
+    assert.equal(loser.pi_session_id, null, 'the duplicate loser meta cannot reindex its stale session id');
+    assert.equal(loser.pi_session_file, null, 'the duplicate loser meta cannot restore the duplicate projection');
+    const recovered = JSON.parse(readFileSync(join(home, 'nodes', 'recovered-claimant', 'meta.json'), 'utf8'));
+    assert.equal(recovered.pi_session_id, 'recovered-claimant-session', 'a stale row cannot clear the authoritative session id');
+    assert.equal(recovered.pi_session_file, recoveredSessionFile, 'a stale row cannot clear the authoritative session file');
     assert.throws(() => raw.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?').run(sessionFile, 'later-claimant'), /UNIQUE/, 'the schema enforces the repaired invariant');
     raw.close();
 });
+test('forward session-file repair reprojects a surviving v36 meta coordinate before restoring its UNIQUE index', () => {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 35);
+    const recoveredSessionFile = '/tmp/surviving-meta-coordinate.jsonl';
+    const staleSessionFile = '/tmp/stale-v36-coordinate.jsonl';
+    for (const [id, pi_session_id, pi_session_file] of [
+        ['surviving-owner', 'surviving-session', recoveredSessionFile],
+        ['stale-row', null, null],
+    ]) {
+        const nodeDir = join(home, 'nodes', id);
+        mkdirSync(nodeDir, { recursive: true });
+        writeFileSync(join(nodeDir, 'meta.json'), JSON.stringify({
+            node_id: id, name: id, created: id === 'surviving-owner' ? '2026-01-01T00:00:00.000Z' : '2026-01-02T00:00:00.000Z',
+            cwd: '/tmp', kind: 'developer', mode: 'base', lifecycle: 'terminal', pi_session_id, pi_session_file,
+        }));
+    }
+    const insert = raw.prepare('INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, created, pi_session_file) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    // This is the v0.3.250 shape after v36: the owner’s surviving meta coordinate
+    // disagrees with its indexed row, while the row carrying it has no meta claim.
+    insert.run('surviving-owner', 'surviving-owner', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-01T00:00:00.000Z', staleSessionFile);
+    insert.run('stale-row', 'stale-row', 'developer', 'base', 'terminal', 'active', '/tmp', '2026-01-02T00:00:00.000Z', recoveredSessionFile);
+    raw.exec('DROP INDEX IF EXISTS idx_nodes_pi_session_file; CREATE UNIQUE INDEX idx_nodes_pi_session_file ON nodes(pi_session_file); PRAGMA user_version = 36;');
+    assert.doesNotThrow(() => migrate(raw));
+    assert.equal(userVersion(raw), MIGRATIONS.length);
+    const rows = raw.prepare('SELECT node_id, pi_session_file FROM nodes ORDER BY created, node_id').all();
+    assert.deepEqual(rows.map((row) => [row.node_id, row.pi_session_file]), [
+        ['surviving-owner', recoveredSessionFile],
+        ['stale-row', null],
+    ]);
+    const survivor = JSON.parse(readFileSync(join(home, 'nodes', 'surviving-owner', 'meta.json'), 'utf8'));
+    assert.equal(survivor.pi_session_id, 'surviving-session');
+    assert.equal(survivor.pi_session_file, recoveredSessionFile);
+    assert.throws(() => raw.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?').run(recoveredSessionFile, 'stale-row'), /UNIQUE/);
+    raw.close();
+});
 test('node lifecycle substrate migration adds six columns and backfills terminal reasons', () => {
     ensureHome();
     const raw = new DatabaseSync(canvasDbPath());

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

@@ -148,6 +148,8 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     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 pendingKickoffObserver = await attachUntil(pendingNode, 'observer', 'pending-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'pending provider episode kickoff settled');
+    pendingKickoffObserver.close();
     const pendingStarts = agentStartCount(pendingNode);
     h.fakeCmd(pendingNode, {
         cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 2_000,
@@ -160,6 +162,8 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     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 admittedKickoffObserver = await attachUntil(admittedNode, 'observer', 'admitted-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'admitted provider episode kickoff settled');
+    admittedKickoffObserver.close();
     const admittedStarts = agentStartCount(admittedNode);
     h.fakeCmd(admittedNode, {
         cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
@@ -174,6 +178,8 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     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 invalidatedKickoffObserver = await attachUntil(invalidatedNode, 'observer', 'invalidated-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'invalidated provider episode kickoff settled');
+    invalidatedKickoffObserver.close();
     const invalidatedStarts = agentStartCount(invalidatedNode);
     h.fakeCmd(invalidatedNode, {
         cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
@@ -190,10 +196,13 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     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' });
+    const cyclingKickoffObserver = await attachUntil(cyclingNode, 'observer', 'fresh-cycle-provider-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'fresh-cycle provider episode kickoff settled');
+    cyclingKickoffObserver.close();
     h.fakeCmd(cyclingNode, {
-        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 60_000,
+        cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 2_000,
     });
     await h.waitFor(() => readProviderRetryEpisode(cyclingNode)?.state === 'pending' ? true : null, { label: 'fresh-cycle episode pending record persisted' });
+    const cyclingStarts = agentStartCount(cyclingNode);
     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}`);
@@ -207,7 +216,13 @@ test('a crashed broker re-drives only its pending provider episode, never admitt
     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');
+    await h.waitFor(() => readProviderRetryEpisode(cyclingNode) === null, { label: 'fresh-cycle kickoff settled successfully' });
+    assert.equal(readProviderRetryEpisode(cyclingNode), null, 'the settled fresh-cycle kickoff clears the old provider episode');
+    assert.equal(agentStartCount(cyclingNode), cyclingStarts + 1, 'the fresh-cycle kickoff starts exactly once');
+    // A retained episode would re-arm immediately once its deadline becomes due.
+    // Wait past that poll interval to prove the completed kickoff cannot replay.
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+    assert.equal(agentStartCount(cyclingNode), cyclingStarts + 1, 'the cleared fresh-cycle episode never replays');
 });
 test('reload_auth re-drives a parked fatal provider-auth turn exactly once', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('auth reload parent');

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

@@ -72,6 +72,7 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
             tools: [],
             systemPrompt: '',
             env: {
+                CRTR_RUNTIME_HOME: process.env['CRTR_RUNTIME_HOME'],
                 CRTR_FAKE_ENGINE_PENDING_AT_SETTLE: '1',
                 CRTR_WATCHER_TICK_MS: '20',
                 CRTR_WATCHER_DEBOUNCE_MS: '25',

package/dist/core/__tests__/watchdog-abort-arms-retry.test.js

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { FaultRetry } from '../runtime/broker/fault-retry.js';
-import { readFault, recordFault } from '../runtime/fault.js';
+import { admitProviderRetryEpisode, clearFault, readFault, readProviderRetryEpisode, recordPendingProviderRetryFault, } from '../runtime/fault.js';
 let home;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-watchdog-abort-retry-'));
@@ -70,12 +70,18 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
 test('a failed retry settlement carries the episode forward instead of restarting it', () => {
     // The episode marker a daemon retry records before re-prompting: original
     // anchor, start time, and the attempt just consumed.
-    recordFault('retry-episode-node', {
+    const sessionFile = 'retry-episode-session';
+    const admittedFault = recordPendingProviderRetryFault('retry-episode-node', sessionFile, {
         link: 'pi→provider', op: 'generation turn', kind: 'connection',
         retry: { disposition: 'auto', by: 'daemon', attempt: 2, max: 8 },
         message: 'connection reset', since: '2026-01-01T00:00:00.000Z', anchorEntryId: 'original-anchor',
     });
+    assert.ok(admittedFault, 'the pre-prompt retry fault persists');
+    assert.equal(admitProviderRetryEpisode('retry-episode-node', sessionFile, admittedFault), true, 'the retry is durably admitted before prompt');
+    clearFault('retry-episode-node', { link: 'pi→provider' }); // error turn_end clears its ordinary marker
+    assert.equal(readProviderRetryEpisode('retry-episode-node')?.state, 'admitted', 'error turn_end preserves the admitted retry for settlement');
     const session = {
+        sessionFile,
         sessionManager: { getLeafId: () => 'leaf-after-failed-retry' },
         model: undefined,
     };
@@ -100,4 +106,5 @@ test('a failed retry settlement carries the episode forward instead of restartin
     assert.equal(fault?.anchorEntryId, 'original-anchor', 'each retry must rewind to the original fork point, not stack prompts');
     assert.equal(fault?.since, '2026-01-01T00:00:00.000Z', 'the episode start survives a failed retry');
     assert.equal(fault?.retry.attempt, 2, 'the attempt count accumulates toward exhaustion');
+    assert.equal(readProviderRetryEpisode('retry-episode-node')?.state, 'pending', 'the failed admitted retry becomes the next durable pending attempt');
 });

package/dist/core/canvas/migrations.js

@@ -26,14 +26,19 @@ import { basename, join, resolve } from 'node:path';
 import { crtrHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
 import { STATE_MIGRATIONS } from '../../migrations/registry.js';
 import { customExtensionPaths } from './extensions.js';
-import { updateJsonFileDurably } from './meta-file.js';
+import { readMetaObject, updateJsonFileDurably, withMetaLock, writeMetaObjectLocked } from './meta-file.js';
 // Schema as a forward-only migration list
 //
 // The schema is the migration list: one place a schema change is expressed,
 // one gate (`PRAGMA user_version`) that applies it. `migrate()` runs every
 // pending step in order and bumps `user_version` after each, so a fresh db and
 // the live fleet (all at `user_version 0`) converge on the same final shape.
-// Migrations are append-only and forward-only — never edit a shipped step.
+// Migrations are append-only and forward-only — never edit a shipped step. The
+// v36 body below is the sole corrective exception: v0.3.250 shipped a destructive
+// stale-row decision, so v36 is narrowed for databases still below its gate while
+// appended v37 repairs databases that already crossed it. Do not repeat this
+// exception; an appended migration is required unless it would run too late to
+// prevent destruction at an existing version boundary.
 /** v1 — the baseline tables + indexes. `IF NOT EXISTS` makes this a no-op on
  *  any existing db (the live fleet already has these tables). */
 function baselineSchema(db) {
@@ -1215,32 +1220,43 @@ function addNodeSessionFileIndex(db) {
     }
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
 }
-/** v36 — one Pi transcript may have exactly one node owner. Normalize every
- * stored path first (including meta), then retain the earliest created row
- * (node_id breaks equal timestamps) and clear both durable session coordinates
- * from every later claimant before creating the UNIQUE index. */
-function makeNodeSessionFileUnique(db) {
+/** Reproject the derived session-file index from authoritative node metadata.
+ * v36 may resolve duplicate authoritative claimants because it runs before the
+ * first UNIQUE index exists. v37 must retain every surviving meta claim: a
+ * conflict at that later boundary is irreconcilable and fails instead. */
+function reconcileNodeSessionFileOwners(db, clearDuplicateMetaClaimants) {
     const canonical = (sessionFile) => {
         const absolute = resolve(sessionFile);
         return existsSync(absolute) ? realpathSync(absolute) : absolute;
     };
-    const rows = db.prepare(`
-SELECT node_id, pi_session_file
-FROM nodes
-WHERE pi_session_file IS NOT NULL
-ORDER BY created ASC, node_id ASC
-`).all();
     const setFile = db.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?');
-    for (const row of rows) {
-        const sessionFile = canonical(row.pi_session_file);
-        if (sessionFile === row.pi_session_file)
+    db.exec('DROP INDEX IF EXISTS idx_nodes_pi_session_file;');
+    const rows = db.prepare('SELECT node_id FROM nodes ORDER BY created ASC, node_id ASC').all();
+    for (const { node_id } of rows) {
+        const metaPath = nodeMetaPath(node_id);
+        // Missing or unreadable metadata has no authoritative coordinate. Avoid
+        // taking a file lock there: old rows can outlive a removed node directory.
+        if (readMetaObject(metaPath) === null) {
+            setFile.run(null, node_id);
             continue;
-        // Identity is authoritative, so normalize both stores before grouping.
-        updateJsonFileDurably(nodeMetaPath(row.node_id), (meta) => {
-            meta['pi_session_file'] = sessionFile;
-            return true;
+        }
+        const sessionFile = withMetaLock(metaPath, () => {
+            const meta = readMetaObject(metaPath);
+            if (meta === null)
+                throw new Error(`node ${node_id} session metadata changed during ownership migration`);
+            if (typeof meta['pi_session_file'] !== 'string')
+                return null;
+            const storedSessionFile = meta['pi_session_file'];
+            const normalizedSessionFile = canonical(storedSessionFile);
+            if (normalizedSessionFile !== storedSessionFile) {
+                meta['pi_session_file'] = normalizedSessionFile;
+                writeMetaObjectLocked(metaPath, meta);
+            }
+            return normalizedSessionFile;
         });
-        setFile.run(sessionFile, row.node_id);
+        // meta.json is authoritative: a crash after its write can leave this row
+        // claiming another node's old session coordinate.
+        setFile.run(sessionFile, node_id);
     }
     const duplicates = db.prepare(`
 SELECT pi_session_file
@@ -1249,6 +1265,10 @@ WHERE pi_session_file IS NOT NULL
 GROUP BY pi_session_file
 HAVING COUNT(*) > 1
 `).all();
+    if (!clearDuplicateMetaClaimants && duplicates.length > 0) {
+        const coordinates = duplicates.map(({ pi_session_file }) => pi_session_file).join(', ');
+        throw new Error(`cannot restore unique Pi session ownership: authoritative metadata has concurrent claimants for ${coordinates}`);
+    }
     const clearRow = db.prepare('UPDATE nodes SET pi_session_file = NULL WHERE node_id = ?');
     for (const { pi_session_file } of duplicates) {
         const owners = db.prepare(`
@@ -1259,18 +1279,36 @@ ORDER BY created ASC, node_id ASC
 `).all(pi_session_file);
         for (const { node_id } of owners.slice(1)) {
             // Clear both durable coordinates so a later reindex cannot restore the
-            // duplicate projection.
-            updateJsonFileDurably(nodeMetaPath(node_id), (meta) => {
+            // duplicate projection. The checked write fails rather than erasing a
+            // concurrent metadata change.
+            const cleared = updateJsonFileDurably(nodeMetaPath(node_id), (meta) => {
+                const currentSessionFile = meta['pi_session_file'];
+                if (typeof currentSessionFile !== 'string' || canonical(currentSessionFile) !== pi_session_file) {
+                    throw new Error(`node ${node_id} session metadata changed during ownership migration`);
+                }
                 meta['pi_session_id'] = null;
                 meta['pi_session_file'] = null;
                 return true;
             });
+            if (!cleared)
+                throw new Error(`node ${node_id} session metadata changed during ownership migration`);
             clearRow.run(node_id);
         }
     }
-    db.exec('DROP INDEX IF EXISTS idx_nodes_pi_session_file;');
     db.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
 }
+/** v36 — one Pi transcript may have exactly one node owner. This is the narrow
+ * corrective body for clients below v36; it reprojects metadata before choosing
+ * the earliest created duplicate claimant (node_id breaks equal timestamps). */
+function makeNodeSessionFileUnique(db) {
+    reconcileNodeSessionFileOwners(db, true);
+}
+/** v37 — repair v0.3.250's already-applied v36 projection without inventing
+ * coordinates v36 already cleared. Surviving authoritative metadata wins over
+ * stale rows; concurrent surviving claims fail loudly rather than clearing one. */
+function repairNodeSessionFileUniqueIndex(db) {
+    reconcileNodeSessionFileOwners(db, false);
+}
 /** v35 — durable node lifecycle execution state and terminal cause. */
 function addNodeLifecycleColumns(db) {
     const columns = nodeColumns(db);
@@ -1340,6 +1378,7 @@ export const MIGRATIONS = [
     /* v34 */ addNodeSessionFileIndex,
     /* v35 */ addNodeLifecycleColumns,
     /* v36 */ makeNodeSessionFileUnique,
+    /* v37 */ repairNodeSessionFileUniqueIndex,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/runtime/broker/engine-drive.js

@@ -52,7 +52,13 @@ export function createEngineDriver(deps) {
                 // claims held deferred mail before the prompt body, but its cursor stays
                 // uncommitted until the resulting turn's agent_settled event.
                 if (route.call === 'prompt' && !session().isStreaming) {
-                    await heldDeferredInboxPromptJoin()?.(session());
+                    try {
+                        await heldDeferredInboxPromptJoin()?.(session());
+                    }
+                    catch {
+                        // The watcher emitted the failed durable delivery and retains it for
+                        // replay. A person's live prompt is not replayable, so it must run.
+                    }
                 }
                 await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
             };

package/dist/core/runtime/broker/fault-retry.js

@@ -58,19 +58,26 @@ export class FaultRetry {
         generation.stagedRefreshAbort = false;
         generation.stagedOverflowFailure = null;
         const settledSession = generation.session;
-        // A failed daemon retry settles here with the episode's fault marker still
-        // present (a successful provider round-trip would have cleared it). Carry
-        // the episode forward — original anchor, start time, and attempt count — so
-        // each retry rewinds to the same fork point instead of stacking recovery
-        // prompts, and so backoff/exhaustion actually accumulate.
+        // turn_end clears the ordinary marker before this settlement. A failed
+        // admitted retry therefore carries from its durable episode, while an
+        // initial provider failure still reads from the ordinary marker.
         const prior = readFault(this.deps.nodeId);
-        const episode = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
-            ? { since: prior.since, anchorEntryId: prior.anchorEntryId, attempt: prior.retry.attempt }
-            : null;
+        const durableEpisode = readProviderRetryEpisode(this.deps.nodeId);
+        const episodeFault = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
+            ? prior
+            : durableEpisode?.state === 'admitted' &&
+                durableEpisode.sessionFile === this.sessionFile(settledSession) &&
+                this.isActiveAutoFault(durableEpisode.fault)
+                ? durableEpisode.fault
+                : null;
+        const episode = episodeFault === null
+            ? null
+            : { since: episodeFault.since, anchorEntryId: episodeFault.anchorEntryId, attempt: episodeFault.retry.attempt };
         const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
         const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
         if (overflowFailure !== null) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
+            clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, {
                 link: 'pi→provider', op: 'context overflow recovery', kind: 'context-overflow', retry: { disposition: 'fatal' },
                 message: overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
@@ -87,21 +94,30 @@ export class FaultRetry {
             });
             return;
         }
-        if (last?.stopReason !== 'error')
+        if (last?.stopReason !== 'error') {
+            if (last !== undefined)
+                clearProviderRetryEpisode(this.deps.nodeId);
             return;
-        if (refreshAbort)
+        }
+        if (refreshAbort) {
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
+        }
         const raw = typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)';
         // An abort landing between requests reaches pi's catch as a bare AbortError
         // and settles as an error rather than `aborted`. Something asked that turn
         // to stop, so there is no provider fault to record.
-        if (endedByAbort({ stopReason: 'error', errorMessage: raw }))
+        if (endedByAbort({ stopReason: 'error', errorMessage: raw })) {
+            clearProviderRetryEpisode(this.deps.nodeId);
             return;
+        }
         const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
         const classified = classify('pi→provider', last);
         const coolingDeadline = extractCoolingDeadline(last);
-        if (uncompactedOverflow)
+        if (uncompactedOverflow) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
+            clearProviderRetryEpisode(this.deps.nodeId);
+        }
         const faultInput = {
             link: 'pi→provider', op: 'generation turn', kind: uncompactedOverflow ? 'context-overflow' : classified.kind,
             retry: uncompactedOverflow
@@ -121,8 +137,10 @@ export class FaultRetry {
         };
         if (faultInput.retry.disposition === 'auto')
             this.recordPendingProviderFault(settledSession, faultInput);
-        else
+        else {
+            clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, faultInput);
+        }
     }
     /** Startup re-drive reads only a durable pending episode. Revive deliberately
      * clears the ordinary fault marker before this boundary, so the episode is

package/dist/core/runtime/broker/held-deferred-inbox.d.ts

@@ -1,4 +1,5 @@
 export declare const HELD_DEFERRED_INBOX_PROMPT_JOIN: unique symbol;
+export declare const BROKER_IDLE_TURN_START: unique symbol;
 export type HeldDeferredInboxPromptJoin = (session: {
     sendCustomMessage: (message: {
         customType: string;
@@ -7,3 +8,6 @@ export type HeldDeferredInboxPromptJoin = (session: {
     }) => Promise<void>;
 }) => Promise<void>;
 export declare function heldDeferredInboxPromptJoin(): HeldDeferredInboxPromptJoin | undefined;
+/** Starts an inbox-delivered idle turn through the broker's admission gate. */
+export type BrokerIdleTurnStart = (text: string) => void;
+export declare function brokerIdleTurnStart(): BrokerIdleTurnStart | undefined;

package/dist/core/runtime/broker/held-deferred-inbox.js

@@ -1,8 +1,13 @@
 // The inbox watcher is a Pi extension loaded through Jiti, while the broker is
-// native ESM. They therefore cannot share a module singleton. This process-global
-// symbol names the watcher-owned join function across that loader boundary.
+// native ESM. They therefore cannot share a module singleton. Process-global
+// symbols carry their narrow bridge functions across that loader boundary.
 export const HELD_DEFERRED_INBOX_PROMPT_JOIN = Symbol.for('@crouton-kit/crtr:held-deferred-inbox-prompt-join');
+export const BROKER_IDLE_TURN_START = Symbol.for('@crouton-kit/crtr:broker-idle-turn-start');
 export function heldDeferredInboxPromptJoin() {
     const join = globalThis[HELD_DEFERRED_INBOX_PROMPT_JOIN];
     return typeof join === 'function' ? join : undefined;
 }
+export function brokerIdleTurnStart() {
+    const start = globalThis[BROKER_IDLE_TURN_START];
+    return typeof start === 'function' ? start : undefined;
+}