@north-light/crouter 0.3.250 → 0.3.252

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

@@ -13,6 +13,9 @@ import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher
 import { appendInbox, readCursor } from '../feed/inbox.js';
 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 { 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';
@@ -44,7 +47,7 @@ function makeFakePi() {
     const handlers = {};
     let resolveFirstInjection;
     const firstInjection = new Promise((resolve) => { resolveFirstInjection = resolve; });
-    return {
+    const pi = {
         injected: [],
         firstInjection,
         sentMessages: [],
@@ -56,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
@@ -275,6 +280,98 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         assert.equal(pi.injected.length, 1);
         assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
     });
+    test('the broker prompt boundary prepends held deferred mail before the human body', async () => {
+        freshNode('node-deferred-engine-prompt');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        await wait(TICK_MS + 100);
+        const entry = appendInbox('node-deferred-engine-prompt', {
+            from: 'child-4',
+            tier: 'deferred',
+            kind: 'update',
+            label: 'held update',
+        });
+        await wait(SETTLE_MS);
+        const order = [];
+        const session = {
+            isStreaming: false,
+            sendCustomMessage: async ({ content }) => { order.push(content); },
+            prompt: async (text, options) => {
+                order.push(text);
+                options.preflightResult?.(true);
+            },
+        };
+        const drive = createEngineDriver({
+            registry: { sendFrame: () => undefined },
+            replies: {},
+            session: () => session,
+            dispatches: { track: (promise) => promise },
+            memoryRefs: { guidanceFor: () => null },
+            authReloadGate: { inFlight: () => undefined },
+            rebind: { installedGeneration: () => 0 },
+            projection: {},
+            toolGroups: {},
+            turnAdmission: createTurnAdmissionGate(),
+        });
+        await drive({}, { type: 'prompt', text: 'where are we?' });
+        assert.equal(order.length, 2, 'one held card and the one human prompt share the admitted operation');
+        assert.match(order[0], /held update/, 'the held inbox card is first');
+        assert.equal(order[1], 'where are we?', 'the human body follows the held card');
+        assert.equal(readCursor('node-deferred-engine-prompt'), undefined, 'the joined handoff waits for settlement');
+        await pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await settle(pi);
+        assert.equal(readCursor('node-deferred-engine-prompt'), entry.entry_id, 'agent_settled commits the broker-joined handoff');
+        const staleFollowUpEntry = appendInbox('node-deferred-engine-prompt', {
+            from: 'child-4',
+            tier: 'deferred',
+            kind: 'update',
+            label: 'held after a stale client snapshot',
+        });
+        await wait(SETTLE_MS);
+        const beforeFollowUp = order.length;
+        await drive({}, { type: 'follow_up', text: 'continue from there' });
+        assert.equal(order.length, beforeFollowUp + 2, 'an idle-routed follow_up shares the same prompt boundary');
+        assert.match(order.at(-2), /held after a stale client snapshot/, 'the held card still precedes the stale follow_up body');
+        assert.equal(order.at(-1), 'continue from there');
+        await pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await settle(pi);
+        assert.equal(readCursor('node-deferred-engine-prompt'), staleFollowUpEntry.entry_id, 'the m-C prompt settles its joined handoff too');
+    });
+    test('a held deferred batch is prepended to an admitted human prompt and replays if that prompt reloads before settlement', async () => {
+        freshNode('node-deferred-human-prompt');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        await wait(TICK_MS + 100);
+        const entry = appendInbox('node-deferred-human-prompt', {
+            from: 'child-4',
+            tier: 'deferred',
+            kind: 'update',
+            label: 'held update',
+        });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 0, 'deferred-only mail remains held while no turn starts');
+        const firstPromptPrefix = [];
+        await heldDeferredInboxPromptJoin()?.({
+            sendCustomMessage: async ({ content }) => { firstPromptPrefix.push(content); },
+        });
+        assert.equal(firstPromptPrefix.length, 1, 'the held card is sent before the human prompt starts');
+        assert.match(firstPromptPrefix[0], /held update/);
+        assert.equal(readCursor('node-deferred-human-prompt'), undefined, 'the pre-prompt handoff is not committed');
+        await shutdown(pi);
+        assert.equal(readCursor('node-deferred-human-prompt'), undefined, 'a reload before agent_settled leaves the held entry replayable');
+        const replacement = makeFakePi();
+        disposers.push(registerWatcher(replacement));
+        await wait(SETTLE_MS);
+        const replayedPrefix = [];
+        await heldDeferredInboxPromptJoin()?.({
+            sendCustomMessage: async ({ content }) => { replayedPrefix.push(content); },
+        });
+        assert.equal(replayedPrefix.length, 1, 'the replacement prompt receives the uncommitted held card again');
+        assert.match(replayedPrefix[0], /held update/);
+        await replacement.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await settle(replacement);
+        assert.equal(readCursor('node-deferred-human-prompt'), entry.entry_id, 'only agent_settled commits the prompt-joined handoff');
+    });
     // Pause makes the profile inert while its broker is still alive: the entry
     // must be RETAINED, not consumed. A critical entry is the sharpest case —
     // its route aborts the live turn, exactly the punch-through pause forbids.

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
@@ -494,12 +500,19 @@ class FakeSession {
      *  a resolvable `/name` token must not crash on a missing method. */
     customMessages = [];
     sendCustomMessage(message, options) {
-        this.customMessages.push({
+        const customMessage = {
             customType: message.customType,
             content: message.content,
             display: message.display,
             deliverAs: options?.deliverAs,
-        });
+        };
+        this.customMessages.push(customMessage);
+        try {
+            appendFileSync(join(this.dir, 'fake-pi.custom-messages.jsonl'), JSON.stringify(customMessage) + '\n');
+        }
+        catch {
+            /* best effort test proof */
+        }
         return Promise.resolve();
     }
     abort() {

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