@north-light/crouter 0.3.318 → 0.3.320

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

@@ -1,710 +0,0 @@
-// Tests for the canvas-node inbox watcher pi extension, part 2 — the
-// refresh-yield HOLD path and idle delivery. Split out of
-// canvas-inbox-watcher.test.ts (see its header) so node:test's file-level
-// parallelism applies; the tests and the scaffold are moved here UNCHANGED.
-//
-// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher-hold.test.ts
-import { test, describe, before, after, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdirSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
-import { acknowledgedNodeMailCount, resetStaleExecutionMail } from '../canvas/deliveries.js';
-import { beginExecution } from '../canvas/executions.js';
-import { enqueueNodeMail } from '../feed/messages.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, setIntent } from '../canvas/canvas.js';
-import { createProfile, pauseProfile, resumeProfile } from '../profiles/manifest.js';
-import { closeDb, migrate, openDb } from '../canvas/db.js';
-import { closeScopedStores } from '../scoped-state/db.js';
-import { initializeFreshScopedStore } from '../scoped-state/migrate.js';
-import { resetScopeCache } from '../scope.js';
-import { createApiServer } from '../../daemon/api/server.js';
-// Drive the watcher's injectable cadence seam (CRTR_WATCHER_TICK_MS /
-// CRTR_WATCHER_DEBOUNCE_MS) at a fast tempo so the test sleeps milliseconds, not
-// seconds. SETTLE_MS still allows a resolve+seed tick, a read tick, and the
-// debounce window before asserting, exactly as against the real 800/1000 cadence.
-const TICK_MS = 20;
-const DEBOUNCE_MS = 25;
-const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 200;
-let origHome;
-let origUserHome;
-let origNode;
-let origExecution;
-const homes = [];
-const disposers = [];
-let server;
-/** Bind each case to isolated canvas and user SQL state. */
-function freshNode(nodeId) {
-    closeDb();
-    closeScopedStores();
-    resetScopeCache();
-    const root = join(tmpdir(), `crtr-w-${Math.random().toString(36).slice(2, 8)}`);
-    const home = join(root, 'home');
-    const canvas = join(root, 'canvas');
-    mkdirSync(home, { recursive: true });
-    mkdirSync(canvas, { recursive: true });
-    homes.push(root);
-    process.env['HOME'] = home;
-    process.env['CRTR_HOME'] = canvas;
-    process.env['CRTR_NODE_ID'] = nodeId;
-    initializeFreshScopedStore({ kind: 'user', root: join(home, '.crouter') });
-    migrate(openDb());
-    server = createApiServer();
-}
-function makeFakePi() {
-    const handlers = {};
-    let resolveFirstInjection;
-    const firstInjection = new Promise((resolve) => { resolveFirstInjection = resolve; });
-    const pi = {
-        injected: [],
-        firstInjection,
-        sentMessages: [],
-        on(e, h) { handlers[e] = h; },
-        sendUserMessage(content, options) {
-            this.injected.push({ content, deliverAs: options?.deliverAs });
-            resolveFirstInjection?.();
-        },
-        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
-// passed through unused by the commit path: agent_settled commits
-// unconditionally regardless of queue state, so `pending: true` exercises that
-// the commit still lands rather than being vetoed. See `shutdown()` below for
-// the one boundary where `hasPendingMessages()` still gates a commit.
-async function settle(pi, opts = {}) {
-    const pending = opts.pending === true;
-    const idle = opts.idle ?? true;
-    await pi.fire('agent_settled', { type: 'agent_settled' }, { isIdle: () => idle, hasPendingMessages: () => pending });
-}
-// Fire session_shutdown — pi's graceful-teardown safety net for a settle that
-// never fired before exit. The real handler takes NO event ctx of its own; it
-// reads the module's captured `lastCtx`, last set by whichever named event
-// fired most recently (session_start/turn_end/agent_start/agent_end/
-// agent_settled — see captureCtx call sites). A session_shutdown with no prior
-// settle is naturally preceded by an agent_end (the failure/abort path), so
-// this fires that first to seed `lastCtx` before firing session_shutdown
-// itself. `pending` maps to pi's `hasPendingMessages()`: true exercises the
-// retained HOLD (an unconsumed queued send would die with the process, so the
-// commit is declined); false (default) commits normally.
-async function shutdown(pi, opts = {}) {
-    const pending = opts.pending === true;
-    await pi.fire('agent_end', { type: 'agent_end', messages: [] }, { isIdle: () => false, hasPendingMessages: () => pending });
-    await pi.fire('session_shutdown', {}, undefined);
-}
-const wait = (ms) => new Promise((r) => setTimeout(r, ms));
-async function waitForFirstInjection(pi, timeoutMs = 2_000) {
-    const timeout = new Promise((_, reject) => {
-        const timer = setTimeout(() => reject(new Error('watcher did not inject the inbox handoff')), timeoutMs);
-        timer.unref();
-    });
-    await Promise.race([pi.firstInjection, timeout]);
-}
-// Register the watcher, then fire session_start — the real lifecycle gate
-// that arms its poll interval and initial tick (see canvas-inbox-watcher.ts).
-// registerCanvasInboxWatcher() alone only wires up handlers; without this the
-// watcher never polls or sends anything.
-function ensureWatcherNode() {
-    const nodeId = process.env['CRTR_NODE_ID'];
-    if (nodeId === undefined || getNode(nodeId) !== null)
-        return;
-    createNode({
-        node_id: nodeId,
-        name: nodeId,
-        created: new Date().toISOString(),
-        cwd: '/tmp',
-        kind: 'general',
-        mode: 'base',
-        lifecycle: 'resident',
-        status: 'active',
-    });
-}
-function publishMail(nodeId, input) {
-    const priorNode = process.env['CRTR_NODE_ID'];
-    process.env['CRTR_NODE_ID'] = nodeId;
-    ensureWatcherNode();
-    if (priorNode === undefined)
-        delete process.env['CRTR_NODE_ID'];
-    else
-        process.env['CRTR_NODE_ID'] = priorNode;
-    return enqueueNodeMail(nodeId, {
-        kind: input.kind,
-        label: input.label,
-        senderNodeId: input.from,
-        bodyRef: input.ref,
-        bodyJson: input.data,
-        disposition: input.disposition,
-        urgency: input.tier,
-        wake: 1,
-    });
-}
-function startWatcherExecution(nodeId) {
-    process.env['CRTR_EXECUTION_ID'] = beginExecution(nodeId, { daemonEpoch: 'test' });
-    resetStaleExecutionMail(Date.now());
-}
-function registerWatcher(pi) {
-    ensureWatcherNode();
-    const nodeId = process.env['CRTR_NODE_ID'];
-    startWatcherExecution(nodeId);
-    const dispose = registerCanvasInboxWatcher(pi);
-    void server.ready.then(() => pi.fire('session_start', { type: 'session_start' }, undefined));
-    return dispose;
-}
-let origTick;
-let origDebounce;
-before(() => {
-    origHome = process.env['CRTR_HOME'];
-    origUserHome = process.env['HOME'];
-    origNode = process.env['CRTR_NODE_ID'];
-    origExecution = process.env['CRTR_EXECUTION_ID'];
-    origTick = process.env['CRTR_WATCHER_TICK_MS'];
-    origDebounce = process.env['CRTR_WATCHER_DEBOUNCE_MS'];
-    process.env['CRTR_WATCHER_TICK_MS'] = String(TICK_MS);
-    process.env['CRTR_WATCHER_DEBOUNCE_MS'] = String(DEBOUNCE_MS);
-});
-afterEach(async () => {
-    while (disposers.length > 0)
-        disposers.pop()();
-    await server?.close();
-    server = undefined;
-    closeDb();
-    closeScopedStores();
-    resetScopeCache();
-});
-after(() => {
-    if (origHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = origHome;
-    if (origUserHome === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = origUserHome;
-    if (origNode === undefined)
-        delete process.env['CRTR_NODE_ID'];
-    else
-        process.env['CRTR_NODE_ID'] = origNode;
-    if (origExecution === undefined)
-        delete process.env['CRTR_EXECUTION_ID'];
-    else
-        process.env['CRTR_EXECUTION_ID'] = origExecution;
-    if (origTick === undefined)
-        delete process.env['CRTR_WATCHER_TICK_MS'];
-    else
-        process.env['CRTR_WATCHER_TICK_MS'] = origTick;
-    if (origDebounce === undefined)
-        delete process.env['CRTR_WATCHER_DEBOUNCE_MS'];
-    else
-        process.env['CRTR_WATCHER_DEBOUNCE_MS'] = origDebounce;
-    resetScopeCache();
-    for (const h of homes) {
-        try {
-            rmSync(h, { recursive: true, force: true });
-        }
-        catch { /* noop */ }
-    }
-});
-describe('canvas inbox watcher — hold + idle delivery', () => {
-    test('refresh-yield in flight: a handoff remains uncommitted for the replacement conversation', async () => {
-        freshNode('node-refresh');
-        closeDb(); // rebind the canvas db to this test's fresh home
-        const meta = {
-            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active',
-        };
-        createNode(meta);
-        const pi = makeFakePi();
-        disposers.push(registerWatcher(pi));
-        // Streaming (mid-turn) when a child finishes — normally this would steer.
-        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        publishMail('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
-        await waitForFirstInjection(pi);
-        assert.equal(pi.injected.length, 1, 'the live broker receives the handoff before its delivery receipt');
-        // The delivery receipt decides the refresh hold; clearing intent does not
-        // manufacture a second handoff.
-        setIntent('node-refresh', 'refresh');
-        setIntent('node-refresh', null);
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 1, 'the same handoff is not delivered twice');
-    });
-    test('refresh-yield replays a handoff that reached the discarded conversation', async () => {
-        freshNode('node-refresh-handoff');
-        closeDb();
-        const meta = {
-            node_id: 'node-refresh-handoff', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active',
-        };
-        createNode(meta);
-        const pi = makeFakePi();
-        disposers.push(registerWatcher(pi));
-        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        publishMail(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'handoff at yield' });
-        await waitForFirstInjection(pi);
-        assert.equal(pi.injected.length, 1, 'the active conversation received the handoff before yield');
-        // Yield discards that conversation before it can act on the queued handoff.
-        // Its settle must leave the entry durable for the fresh revive's kickoff.
-        setIntent(meta.node_id, 'refresh');
-        await settle(pi);
-        assert.equal(acknowledgedNodeMailCount(meta.node_id), 0, 'the discarded conversation cannot commit its inbox handoff');
-        const replacementExecution = beginExecution(meta.node_id, { daemonEpoch: 'test' });
-        resetStaleExecutionMail(Date.now());
-        const bearings = drainBearings(getNode(meta.node_id), replacementExecution);
-        assert.match(bearings.unreadDigest ?? '', /handoff at yield/, 'the fresh revive receives the uncommitted handoff');
-    });
-    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
-        freshNode('node-idle');
-        const pi = makeFakePi();
-        disposers.push(registerWatcher(pi));
-        // No agent_start fired → watcher treats the node as idle.
-        await wait(TICK_MS + 100);
-        publishMail('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
-        await waitForFirstInjection(pi);
-        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 = publishMail('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, broadcast: () => 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(acknowledgedNodeMailCount('node-deferred-engine-prompt'), 0, 'the joined handoff waits for settlement');
-        await pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await settle(pi);
-        assert.equal(acknowledgedNodeMailCount('node-deferred-engine-prompt'), 1, 'agent_settled commits the broker-joined handoff');
-        const staleFollowUpEntry = publishMail('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(acknowledgedNodeMailCount('node-deferred-engine-prompt'), 2, 'the follow-up 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 = publishMail('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(acknowledgedNodeMailCount('node-deferred-human-prompt'), 0, 'the pre-prompt handoff is not committed');
-        await shutdown(pi);
-        assert.equal(acknowledgedNodeMailCount('node-deferred-human-prompt'), 0, '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(acknowledgedNodeMailCount('node-deferred-human-prompt'), 1, '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.
-    test('a paused profile holds queued entries in a live broker until resume', async () => {
-        freshNode('node-paused-profile');
-        const origProfile = process.env['CRTR_PROFILE_ID'];
-        try {
-            const profile = createProfile('paused watcher', [{ path: '/tmp', memory: 'content' }]);
-            pauseProfile(profile.profileId);
-            process.env['CRTR_PROFILE_ID'] = profile.profileId;
-            const pi = makeFakePi();
-            disposers.push(registerWatcher(pi));
-            await wait(TICK_MS + 100);
-            publishMail('node-paused-profile', { from: 'child-1', tier: 'critical', kind: 'update', label: 'sent while paused' });
-            await wait(SETTLE_MS);
-            assert.equal(pi.injected.length, 0, 'a paused profile delivers nothing to its live broker');
-            assert.equal(acknowledgedNodeMailCount('node-paused-profile'), 0, 'the held entry stays unconsumed');
-            resumeProfile(profile.profileId);
-            await waitForFirstInjection(pi);
-            assert.equal(pi.injected.length, 1, 'resume delivers the entry that waited');
-            assert.match(pi.injected[0].content, /sent while paused/);
-        }
-        finally {
-            if (origProfile === undefined)
-                delete process.env['CRTR_PROFILE_ID'];
-            else
-                process.env['CRTR_PROFILE_ID'] = origProfile;
-        }
-    });
-});
-// Lifecycle-ordering regression (the live inbox-delivery startup loop): pi
-// deliberately makes action methods (sendUserMessage/sendMessage) throw until
-// the session binds the shared extension runtime, and it only emits
-// session_start once that bind has happened. registerCanvasInboxWatcher()'s
-// factory must therefore make zero action calls on its own — arming the poll
-// interval and the initial tick is deferred to the session_start handler,
-// which must itself be idempotent (a resume/fork/second session_start must not
-// re-arm a second interval or re-deliver).
-describe('canvas inbox watcher — action-gated startup (session_start arm)', () => {
-    test('factory registration makes zero action calls; only session_start arms delivery, and a repeat session_start is harmless', async () => {
-        freshNode('node-action-gate');
-        const pi = makeFakePi();
-        let actionsReady = false;
-        let sendAttempts = 0;
-        const realSendUserMessage = pi.sendUserMessage.bind(pi);
-        pi.sendUserMessage = (content, options) => {
-            sendAttempts += 1;
-            if (!actionsReady)
-                throw new Error('Extension runtime not initialized: session not yet bound');
-            realSendUserMessage(content, options);
-        };
-        // An unread entry already sits in the inbox before the watcher is even
-        // registered — the same shape as a revived broker with pre-existing work.
-        const entry = publishMail('node-action-gate', { from: 'child-1', tier: 'normal', kind: 'update', label: 'pre-bind entry' });
-        // Registration alone (the extension factory, before Pi has bound actions)
-        // must be side-effect-free: no timer armed, no tick run, no action attempted
-        // — even across several tick+debounce windows.
-        ensureWatcherNode();
-        startWatcherExecution('node-action-gate');
-        disposers.push(registerCanvasInboxWatcher(pi));
-        await wait(TICK_MS * 5 + DEBOUNCE_MS + 50);
-        assert.equal(sendAttempts, 0, 'no action call is attempted before session_start arms the watcher');
-        assert.equal(pi.injected.length, 0, 'nothing handed off before session_start');
-        assert.equal(acknowledgedNodeMailCount('node-action-gate'), 0, 'no delivery is acknowledged before session_start');
-        // session_start is pi's real bind signal: actions work from here on. Arming
-        // now must pick up the already-buffered pre-bind entry.
-        actionsReady = true;
-        pi.fire('session_start', { type: 'session_start' }, undefined);
-        await waitForFirstInjection(pi);
-        assert.equal(sendAttempts, 1, 'exactly one action attempt once session_start arms the watcher');
-        assert.equal(pi.injected.length, 1, 'exactly one handoff once actions are bound');
-        assert.equal(acknowledgedNodeMailCount('node-action-gate'), 0, 'still uncommitted until agent_settled');
-        await settle(pi);
-        assert.equal(acknowledgedNodeMailCount('node-action-gate'), 1, 'agent_settled acknowledges the delivery');
-        // A repeated session_start (e.g. a resume) must not re-arm a second
-        // interval or re-run the initial tick — no duplicate delivery.
-        pi.fire('session_start', { type: 'session_start' }, undefined);
-        await wait(SETTLE_MS);
-        assert.equal(sendAttempts, 1, 'a repeated session_start does not re-arm or re-attempt delivery');
-        assert.equal(pi.injected.length, 1, 'a repeated session_start does not re-deliver');
-    });
-    test('disposal before any session_start is safe (no timer to leak, no action ever attempted)', async () => {
-        freshNode('node-dispose-before-start');
-        const pi = makeFakePi();
-        publishMail('node-dispose-before-start', { from: 'child-1', tier: 'normal', kind: 'update', label: 'never armed' });
-        startWatcherExecution('node-dispose-before-start');
-        const dispose = registerCanvasInboxWatcher(pi);
-        // Dispose immediately, before session_start ever fires — models a reload
-        // that discards this generation before Pi finishes binding.
-        dispose();
-        await wait(TICK_MS * 3 + DEBOUNCE_MS + 50);
-        assert.equal(pi.injected.length, 0, 'a watcher disposed before session_start never delivers');
-        assert.equal(acknowledgedNodeMailCount('node-dispose-before-start'), 0, 'disposal before start commits nothing');
-        // A session_start firing after disposal (a stale handler on a discarded
-        // generation) must also be inert.
-        pi.fire('session_start', { type: 'session_start' }, undefined);
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 0, 'session_start after disposal does not resurrect the discarded generation');
-    });
-});
-// SQL delivery receipts preserve at-least-once delivery. A claimed delivery is
-// acknowledged only at agent_settled, never at the fire-and-forget send return
-// or agent_end. A watcher that exits before acknowledgment leaves its claim for
-// the replacement execution to inherit and deliver again. session_shutdown
-// retains a claim when Pi still has pending messages, because that queued send
-// would otherwise die with the process.
-describe('canvas inbox watcher — SQL delivery receipts (at-least-once)', () => {
-    test('mid-turn handoff, crash before settle: delivery remains unacknowledged and a fresh watcher re-delivers', async () => {
-        freshNode('node-receipt-crash');
-        const pi1 = makeFakePi();
-        disposers.push(registerWatcher(pi1));
-        // Streaming (mid-turn) so this delivers via followUp, not the idle path.
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        publishMail('node-receipt-crash', { from: 'child-1', tier: 'normal', kind: 'update', label: 'still working' });
-        await waitForFirstInjection(pi1);
-        assert.equal(pi1.injected.length, 1, 'delivered mid-turn as a followUp');
-        assert.equal(pi1.injected[0].deliverAs, 'followUp');
-        // The delivery remains handed off until settle; a send return alone must not acknowledge it.
-        assert.equal(acknowledgedNodeMailCount('node-receipt-crash'), 0, 'delivery is not acknowledged before a settle');
-        // Simulate the watcher dying without a graceful session_shutdown — never
-        // settle OR fire session_shutdown on pi1. The broker's SIGTERM handler DOES
-        // run a JS handler (disposeAndExit: session.dispose() + process.exit), but
-        // that path never emits this extension's session_shutdown, so its safety-net
-        // commit does not run on a kill. Registering a fresh watcher clears pi1's
-        // timer (the module-level liveTimer guard) without running its teardown,
-        // modeling crash-then-revive rather than a clean stop.
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await waitForFirstInjection(pi2);
-        assert.equal(pi2.injected.length, 1, 'a fresh watcher re-reads and re-delivers the same uncommitted entry');
-        assert.match(pi2.injected[0].content, /still working/);
-    });
-    test('mid-turn handoff + agent_settled: delivery acknowledged, fresh watcher does NOT redeliver', async () => {
-        freshNode('node-receipt-committed');
-        const pi1 = makeFakePi();
-        disposers.push(registerWatcher(pi1));
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        const entry = publishMail('node-receipt-committed', { from: 'child-2', tier: 'normal', kind: 'update', label: 'still working' });
-        await waitForFirstInjection(pi1);
-        assert.equal(pi1.injected.length, 1);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-committed'), 0, 'not yet committed before the settle');
-        // The turn settles with pi's queue drained (the followUp was consumed) —
-        // THAT acknowledges the delivery.
-        await settle(pi1);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-committed'), 1, 'delivery acknowledged at agent_settled');
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await wait(SETTLE_MS);
-        assert.equal(pi2.injected.length, 0, 'a fresh watcher does not redeliver an already-committed entry');
-    });
-    test('idle-path delivery: NOT committed on the void send, committed at agent_settled', async () => {
-        freshNode('node-receipt-idle');
-        const pi = makeFakePi();
-        disposers.push(registerWatcher(pi));
-        // No agent_start fired → watcher treats the node as idle.
-        await wait(TICK_MS + 100);
-        const entry = publishMail('node-receipt-idle', { from: 'child-3', tier: 'normal', kind: 'update', label: 'idle update' });
-        await waitForFirstInjection(pi);
-        assert.equal(pi.injected.length, 1);
-        assert.equal(pi.injected[0].deliverAs, undefined, 'idle delivery has no deliverAs');
-        // The idle send triggers a turn, but its void return is a handoff, not proof
-        // of acceptance — the delivery remains handed off until the turn settles.
-        assert.equal(acknowledgedNodeMailCount('node-receipt-idle'), 0, 'idle send does not commit on the fire-and-forget return');
-        await settle(pi);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-idle'), 1, 'idle-path delivery commits at the turn it started settling');
-    });
-    test('synchronous send throw then agent_settled: re-buffered delivery remains unacknowledged and a fresh watcher re-delivers', async () => {
-        freshNode('node-receipt-failsend');
-        const pi1 = makeFakePi();
-        // Persistent synchronous send failure: the entry is read + buffered, flush
-        // throws, it is re-buffered and never handed off.
-        pi1.sendUserMessage = () => { throw new Error('send always fails'); };
-        disposers.push(registerWatcher(pi1));
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        publishMail('node-receipt-failsend', { from: 'child-1', tier: 'normal', kind: 'update', label: 'never delivered' });
-        await wait(SETTLE_MS);
-        assert.equal(pi1.injected.length, 0, 'the failing send delivered nothing');
-        // agent_settled must NOT commit past the still-re-buffered (never-handed-off) entry.
-        await settle(pi1);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-failsend'), 0, 're-buffered, never-delivered mail is not acknowledged');
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await waitForFirstInjection(pi2);
-        assert.equal(pi2.injected.length, 1, 'a fresh watcher re-reads and re-delivers the never-committed entry');
-        assert.match(pi2.injected[0].content, /never delivered/);
-    });
-    test('critical abort then abort-generated settle: pending critical entry NOT committed, fresh watcher re-delivers', async () => {
-        freshNode('node-receipt-critical');
-        const pi1 = makeFakePi();
-        let aborted = 0;
-        disposers.push(registerWatcher(pi1));
-        // Mid-turn streaming, with an abort() seam on the ctx (a critical entry
-        // preempts via ctx.abort()).
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false, abort: () => { aborted += 1; } });
-        await wait(TICK_MS + 100);
-        publishMail('node-receipt-critical', { from: 'child-1', tier: 'critical', kind: 'update', label: 'critical work' });
-        await wait(SETTLE_MS);
-        assert.ok(aborted >= 1, 'the critical entry aborted the live turn');
-        assert.equal(pi1.injected.length, 0, 'the critical path re-buffers, it does not deliver mid-stream');
-        // The abort-generated agent_end/settle must not commit the pending critical
-        // entry (it is re-buffered, never handed off).
-        pi1.fire('agent_end', { type: 'agent_end', messages: [] }, { isIdle: () => false });
-        await settle(pi1, { idle: false });
-        assert.equal(acknowledgedNodeMailCount('node-receipt-critical'), 0, 'abort-generated settle does not commit the pending critical entry before its retry');
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await waitForFirstInjection(pi2);
-        assert.equal(pi2.injected.length, 1, 'a fresh watcher re-delivers the critical entry');
-        assert.match(pi2.injected[0].content, /critical work/);
-    });
-    test('batch A settles while batch B still debounces: commit stops at A, fresh watcher re-delivers B', async () => {
-        freshNode('node-receipt-batchB');
-        // Wide debounce for THIS watcher so B stays buffered-but-unflushed when we
-        // settle A; the watcher captures the cadence at registration, so restore the
-        // file default immediately after for the fresh (pi2) watcher.
-        process.env['CRTR_WATCHER_DEBOUNCE_MS'] = '200';
-        const pi1 = makeFakePi();
-        disposers.push(registerWatcher(pi1));
-        process.env['CRTR_WATCHER_DEBOUNCE_MS'] = String(DEBOUNCE_MS);
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 60);
-        const a = publishMail('node-receipt-batchB', { from: 'child-a', tier: 'normal', kind: 'update', label: 'batch A' });
-        await waitForFirstInjection(pi1);
-        assert.equal(pi1.injected.length, 1, 'batch A delivered mid-turn');
-        assert.equal(pi1.injected[0].deliverAs, 'followUp');
-        const b = publishMail('node-receipt-batchB', { from: 'child-b', tier: 'normal', kind: 'update', label: 'batch B' });
-        await wait(70); // B read into the buffer but < 200ms debounce → not yet flushed
-        // A's turn settles while B is still debouncing in the buffer. The commit must
-        // clamp below the still-buffered B and land on A only.
-        await settle(pi1);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-batchB'), 1, 'commit lands on handed-off batch A');
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await waitForFirstInjection(pi2);
-        assert.equal(pi2.injected.length, 1, 'a fresh watcher re-reads from A and re-delivers B');
-        assert.match(pi2.injected[0].content, /batch B/);
-        assert.doesNotMatch(pi2.injected[0].content, /batch A/, 'A is already committed, only B is re-delivered');
-    });
-    // agent_settled is authoritative: pi's documented contract guarantees no
-    // queued continuation remains once it fires, so the commit is unconditional
-    // — a context reporting pending sends (hasPendingMessages() = true) no longer
-    // vetoes it. This is the exact real-incident invariant behind #353/#362: a
-    // settle-time veto that declines the sole commit, followed by cooperative
-    // idle-release exit, permanently leaves the mail handed off with no later settle.
-    test('agent_settled commits unconditionally even when hasPendingMessages() reports pending', async () => {
-        freshNode('node-receipt-failhold');
-        const pi1 = makeFakePi();
-        disposers.push(registerWatcher(pi1));
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        const entry = publishMail('node-receipt-failhold', { from: 'child-1', tier: 'normal', kind: 'update', label: 'queued across a failure' });
-        await waitForFirstInjection(pi1);
-        assert.equal(pi1.injected.length, 1, 'delivered mid-turn as a followUp');
-        assert.equal(pi1.injected[0].deliverAs, 'followUp');
-        // A failure/aborted agent_end is never a commit point regardless of queue
-        // state, so it must NOT commit.
-        pi1.fire('agent_end', { type: 'agent_end', messages: [] }, { isIdle: () => false });
-        assert.equal(acknowledgedNodeMailCount('node-receipt-failhold'), 0, 'a failure agent_end does not commit');
-        // The settle commits even though the context reports pending sends —
-        // agent_settled no longer declines on hasPendingMessages().
-        await settle(pi1, { pending: true });
-        assert.equal(acknowledgedNodeMailCount('node-receipt-failhold'), 1, 'agent_settled commits unconditionally, even when hasPendingMessages() reports pending');
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await wait(SETTLE_MS);
-        assert.equal(pi2.injected.length, 0, 'a fresh watcher does not redeliver an already-committed entry');
-    });
-    // session_shutdown retains the conservative hold this test file used to pin
-    // at agent_settled: it is pi's graceful-teardown safety net for a settle that
-    // never fired before exit, so an unconsumed queued send there would die with
-    // the process — committing past it would durably lose a message pi never
-    // delivered.
-    test('session_shutdown keeps a refresh handoff replayable when no messages are pending', async () => {
-        freshNode('node-receipt-refresh-shutdown');
-        closeDb();
-        const meta = {
-            node_id: 'node-receipt-refresh-shutdown', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active',
-        };
-        createNode(meta);
-        const pi = makeFakePi();
-        disposers.push(registerWatcher(pi));
-        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        publishMail(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'handoff at shutdown' });
-        await waitForFirstInjection(pi);
-        assert.equal(pi.injected.length, 1, 'the active conversation received the handoff before refresh');
-        setIntent(meta.node_id, 'refresh');
-        await shutdown(pi, { pending: false });
-        assert.equal(acknowledgedNodeMailCount(meta.node_id), 0, 'a refresh keeps the shutdown handoff uncommitted for replay');
-    });
-    test('session_shutdown still holds while hasPendingMessages() reports pending (no agent_settled fired)', async () => {
-        freshNode('node-receipt-shutdownhold');
-        const pi1 = makeFakePi();
-        const dispose = registerWatcher(pi1);
-        pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        const entry = publishMail('node-receipt-shutdownhold', { from: 'child-1', tier: 'normal', kind: 'update', label: 'still queued at shutdown' });
-        await waitForFirstInjection(pi1);
-        assert.equal(pi1.injected.length, 1, 'delivered mid-turn as a followUp');
-        // session_shutdown fires with no prior agent_settled, and the context
-        // reports an unconsumed queued send — the hold declines the commit.
-        await shutdown(pi1, { pending: true });
-        assert.equal(acknowledgedNodeMailCount('node-receipt-shutdownhold'), 0, 'session_shutdown declines to commit while pi reports pending sends');
-        dispose();
-        // A fresh watcher re-reads and re-delivers, then a drained settle commits.
-        const pi2 = makeFakePi();
-        disposers.push(registerWatcher(pi2));
-        await waitForFirstInjection(pi2);
-        assert.equal(pi2.injected.length, 1, 'a fresh watcher re-reads and re-delivers the never-committed entry');
-        assert.match(pi2.injected[0].content, /still queued at shutdown/);
-        await settle(pi2);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-shutdownhold'), 1, 'the redelivered entry commits once the fresh watcher settles cleanly');
-    });
-    // Situational custom sends do not enter pi's user steer/followUp queue, so
-    // hasPendingMessages() never reflects them: a situational handoff commits at
-    // the next drained settle (a situational send that async-rejected is the
-    // accepted silent-loss window, not held).
-    test('situational custom send: committed at the next drained agent_settled', async () => {
-        freshNode('node-receipt-situational');
-        appendSituationalContext('node-receipt-situational', 'ambient checkout state');
-        const pi1 = makeFakePi();
-        disposers.push(registerWatcher(pi1));
-        // Idle so the situational-only entry delivers as a hidden custom message.
-        await wait(TICK_MS + 100);
-        const entry = publishMail('node-receipt-situational', {
-            from: null, tier: 'normal', kind: 'message', label: '(ambient context updated)',
-            data: { situational: true, situationalOnly: true },
-        });
-        await wait(SETTLE_MS);
-        assert.equal(pi1.sentMessages.length, 1, 'the hidden custom message was sent');
-        assert.equal(acknowledgedNodeMailCount('node-receipt-situational'), 0, 'not committed before the settle');
-        await settle(pi1);
-        assert.equal(acknowledgedNodeMailCount('node-receipt-situational'), 1, 'the situational handoff commits at the drained settle');
-    });
-});