@north-light/crouter 0.3.251 → 0.3.253

package/dist/commands/node/lifecycle.js

@@ -109,15 +109,15 @@ const nodeClose = defineLeaf({
         return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
     },
 });
-// node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name)
+// node config — reconfigure a node's settings headlessly (model/lifecycle/kind/mode/name/cwd repair)
 const NODE_CONFIG_MODEL_EFFECT = 'Model change first: a live broker switches immediately over its socket; a dormant node persists the durable model override and launch recipe for its next revive.';
 export const nodeConfig = defineLeaf({
     name: 'config',
-    description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name',
-    whenToUse: 'you want to reconfigure a node\'s settings headlessly after spawn — swap its model/provider, flip it terminal↔resident (interactable), respecialize its kind, switch base↔orchestrator mode, or rename it — without opening its viewer. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).',
+    description: 'reconfigure a node\'s settings headlessly — model, lifecycle (terminal/resident), kind, mode, name; repair a missing cwd',
+    whenToUse: 'you want to reconfigure a node\'s settings headlessly after spawn — swap its model/provider, flip it terminal↔resident (interactable), respecialize its kind, switch base↔orchestrator mode, or rename it — without opening its viewer. It also repairs a dormant node whose recorded cwd is gone, starting its next revive in a fresh conversation. The durable attribute setter; reuses the same recipes a revive reads. Use `node promote` for the opinionated self-promotion path, and `node lifecycle` for teardown actions (recycle/close/demote).',
     help: {
         name: 'node config',
-        summary: 'reconfigure a node\'s settings headlessly — model, lifecycle, kind, mode, name',
+        summary: 'reconfigure a node\'s settings headlessly — model, lifecycle, kind, mode, name; repair a missing cwd',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Target node id. Defaults to the node in --pane, else CRTR_NODE_ID.' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to resolve the node from. Defaults to $TMUX_PANE.' },
@@ -140,20 +140,23 @@ export const nodeConfig = defineLeaf({
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here.' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, constraint: 'Set persona mode headlessly. base is hands-on; orchestrator holds a roadmap and delegates. orchestrator seeds a roadmap scaffold if absent.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Rename the node; if the node has a live window, also rename that viewer window.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Repair-only replacement launch directory. Must be a non-empty absolute existing directory and used alone; the daemon accepts it only for a dormant, non-forked node with no open managed worktree whose recorded cwd is gone. Clears the saved Pi session, so the next revive starts fresh while durable node work remains.' },
         ],
         output: [
-            { name: 'node_id', type: 'string', required: true, constraint: 'The reconfigured node.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The reconfigured node, present for ordinary config changes.' },
             { name: 'model', type: 'string', required: false, constraint: 'The resolved model, present only when --model changed it.' },
             { name: 'lifecycle', type: 'string', required: false, constraint: 'The new lifecycle, present only when --lifecycle changed it.' },
             { name: 'kind', type: 'string', required: false, constraint: 'The new kind, present only when --kind changed it.' },
             { name: 'mode', type: 'string', required: false, constraint: 'The new mode, present only when --mode changed it.' },
             { name: 'name', type: 'string', required: false, constraint: 'The new name, present only when --name changed it.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'The lexically resolved replacement directory, present only after a cwd repair.' },
         ],
         outputKind: 'object',
         effects: [
             NODE_CONFIG_MODEL_EFFECT,
             'Kind, mode, and lifecycle changes rebuild the launch spec from the fresh node meta; setting mode to orchestrator seeds a roadmap scaffold if absent.',
             'Name changes update the row and, when the node already has a live window, rename that viewer window to the new full name.',
+            'A cwd repair writes only the lexically resolved cwd and clears saved Pi session pointers; the old transcript and durable node work remain untouched.',
         ],
         dynamicState: () => kindsStateBlock(),
     },
@@ -165,6 +168,10 @@ export const nodeConfig = defineLeaf({
         // kind is validated against the caller's installed personas here for the
         // clean listing error, and re-validated server-side against the TARGET
         // node's scope as a backstop.
+        const cwdSpec = input['cwd'];
+        if (cwdSpec !== undefined && ['model', 'kind', 'lifecycle', 'mode', 'name'].some((flag) => input[flag] !== undefined)) {
+            throw new InputError({ error: 'cwd_not_exclusive', message: 'cwd repair cannot be combined with another config flag', field: 'cwd', next: 'Pass --cwd alone.' });
+        }
         const modelSpec = input['model']?.trim();
         if (modelSpec === '') {
             throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: 'Run `crtr node config --model -h` and read the focused contract before retrying.' });
@@ -203,12 +210,18 @@ export const nodeConfig = defineLeaf({
             patch.name = nameSpec;
             applied.push('name');
         }
+        if (cwdSpec !== undefined) {
+            patch.cwd = cwdSpec;
+            applied.push('cwd');
+        }
         if (applied.length === 0) {
-            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name.' });
+            throw new InputError({ error: 'no_change', message: 'no config changes requested', next: 'Pass at least one of --model, --lifecycle, --kind, --mode, --name, --cwd.' });
         }
         const detail = await cliClient()
             .patchConfig(nodeId, patch)
             .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        if (cwdSpec !== undefined)
+            return { cwd: detail.cwd };
         const result = { node_id: nodeId };
         if (applied.includes('model'))
             result.model = detail.model_override ?? modelSpec;
@@ -223,6 +236,8 @@ export const nodeConfig = defineLeaf({
         return result;
     },
     render: (r) => {
+        if (r['cwd'] !== undefined)
+            return `Repaired cwd: ${r['cwd']}.`;
         const bits = [];
         if (r['model'] !== undefined)
             bits.push(`model=${r['model']}`);

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