@north-light/crouter 0.3.312 → 0.3.314

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

@@ -10,18 +10,21 @@ 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 { appendInbox, readCursor } from '../feed/inbox.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, recordPid, setIntent } from '../canvas/canvas.js';
+import { createNode, getNode, setIntent } from '../canvas/canvas.js';
 import { createProfile, pauseProfile, resumeProfile } from '../profiles/manifest.js';
-import { closeDb } from '../canvas/db.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';
-import { CrtrClient } from '../../api/client.js';
-import { ApiError } from '../../api/errors.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
@@ -30,17 +33,28 @@ 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;
-/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+/** Bind each case to isolated canvas and user SQL state. */
 function freshNode(nodeId) {
-    const home = join(tmpdir(), `crtr-w-${Math.random().toString(36).slice(2, 8)}`);
+    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 });
-    homes.push(home);
-    process.env['CRTR_HOME'] = home;
+    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() {
@@ -70,7 +84,8 @@ function makeFakePi() {
 // the one boundary where `hasPendingMessages()` still gates a commit.
 async function settle(pi, opts = {}) {
     const pending = opts.pending === true;
-    await pi.fire('agent_settled', { type: 'agent_settled' }, { isIdle: () => true, hasPendingMessages: () => pending });
+    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
@@ -110,27 +125,48 @@ function ensureWatcherNode() {
         cwd: '/tmp',
         kind: 'general',
         mode: 'base',
-        // Resident: these cases are about the watcher's own cursor/handoff/hold
-        // contract at each tier as sent. A terminal node's mail is raised to the
-        // steering tier on append (feed/inbox.ts), which would route every case
-        // here as a steer.
         lifecycle: 'resident',
         status: 'active',
     });
-    recordPid(nodeId, process.pid);
+}
+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();
-    recordPid(process.env['CRTR_NODE_ID'], process.pid);
+    const nodeId = process.env['CRTR_NODE_ID'];
+    startWatcherExecution(nodeId);
     const dispose = registerCanvasInboxWatcher(pi);
-    void pi.fire('session_start', { type: 'session_start' }, undefined);
+    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);
@@ -142,16 +178,26 @@ afterEach(async () => {
     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
@@ -160,6 +206,7 @@ after(() => {
         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 });
@@ -174,7 +221,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         const meta = {
             node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
             cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active', intent: 'refresh',
+            status: 'active',
         };
         createNode(meta);
         const pi = makeFakePi();
@@ -182,69 +229,16 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         // 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);
-        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
+        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 durable cursor boundary');
-        // The cursor operation decides the refresh hold at its durable commit
-        // boundary; clearing intent does not manufacture a second handoff.
+        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('replacement session binding holds a late old-broker cursor commit', async () => {
-        freshNode('node-refresh-replacement');
-        closeDb();
-        const meta = {
-            node_id: 'node-refresh-replacement', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active', intent: 'refresh',
-        };
-        createNode(meta);
-        const entry = appendInbox(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'handoff before replacement' });
-        recordPid(meta.node_id, 101);
-        const client = CrtrClient.forLocalSocket({ autostart: false });
-        // The replacement binds first, consuming refresh and recording its own
-        // process generation. The old broker's delayed request must still hold.
-        await client.bindBrokerSession(meta.node_id, {
-            piSessionId: 'replacement-session', sessionFile: '/tmp/replacement.jsonl',
-            pid: 202, reason: 'startup', reviewBoundaryIds: [],
-        });
-        const oldResult = await client.advanceBrokerInboxCursor(meta.node_id, {
-            throughEntryId: entry.entry_id, brokerPid: 101,
-        });
-        assert.deepEqual(oldResult, { action: 'hold_refresh' });
-        assert.equal(readCursor(meta.node_id), undefined, 'the stale broker cannot consume the replacement replay');
-        const replacementResult = await client.advanceBrokerInboxCursor(meta.node_id, {
-            throughEntryId: entry.entry_id, brokerPid: 202,
-        });
-        assert.deepEqual(replacementResult, { action: 'advanced' });
-        assert.equal(readCursor(meta.node_id), entry.entry_id, 'only the replacement broker advances the durable cursor');
-    });
-    test('cursor rejects a nonexistent or backward physical entry', async () => {
-        freshNode('node-cursor-physical-boundary');
-        closeDb();
-        const meta = {
-            node_id: 'node-cursor-physical-boundary', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident', status: 'active',
-        };
-        createNode(meta);
-        recordPid(meta.node_id, 303);
-        const first = appendInbox(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'first' });
-        const second = appendInbox(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'second' });
-        const client = CrtrClient.forLocalSocket({ autostart: false });
-        const rejected = (request) => client
-            .advanceBrokerInboxCursor(meta.node_id, request)
-            .then(() => assert.fail('cursor request should fail'))
-            .catch((error) => {
-            assert.ok(error instanceof ApiError);
-            assert.equal(error.status, 400);
-        });
-        await rejected({ throughEntryId: 'f'.repeat(32), brokerPid: 303 });
-        assert.equal(readCursor(meta.node_id), undefined, 'a well-shaped unknown id cannot poison the cursor');
-        await client.advanceBrokerInboxCursor(meta.node_id, { throughEntryId: second.entry_id, brokerPid: 303 });
-        await rejected({ throughEntryId: first.entry_id, brokerPid: 303 });
-        assert.equal(readCursor(meta.node_id), second.entry_id, 'a late commit cannot move the durable cursor backward');
-    });
     test('refresh-yield replays a handoff that reached the discarded conversation', async () => {
         freshNode('node-refresh-handoff');
         closeDb();
@@ -258,15 +252,17 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         disposers.push(registerWatcher(pi));
         pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
         await wait(TICK_MS + 100);
-        appendInbox(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'handoff at yield' });
+        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(readCursor(meta.node_id), undefined, 'the discarded conversation cannot commit its inbox handoff');
-        const bearings = drainBearings(getNode(meta.node_id));
+        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 () => {
@@ -275,7 +271,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         disposers.push(registerWatcher(pi));
         // No agent_start fired → watcher treats the node as idle.
         await wait(TICK_MS + 100);
-        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
+        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');
@@ -285,7 +281,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         const pi = makeFakePi();
         disposers.push(registerWatcher(pi));
         await wait(TICK_MS + 100);
-        const entry = appendInbox('node-deferred-engine-prompt', {
+        const entry = publishMail('node-deferred-engine-prompt', {
             from: 'child-4',
             tier: 'deferred',
             kind: 'update',
@@ -317,11 +313,11 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         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');
+        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(readCursor('node-deferred-engine-prompt'), entry.entry_id, 'agent_settled commits the broker-joined handoff');
-        const staleFollowUpEntry = appendInbox('node-deferred-engine-prompt', {
+        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',
@@ -335,14 +331,14 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         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');
+        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 = appendInbox('node-deferred-human-prompt', {
+        const entry = publishMail('node-deferred-human-prompt', {
             from: 'child-4',
             tier: 'deferred',
             kind: 'update',
@@ -356,9 +352,9 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         });
         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');
+        assert.equal(acknowledgedNodeMailCount('node-deferred-human-prompt'), 0, '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');
+        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);
@@ -370,20 +366,14 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         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');
+        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');
-        closeDb();
-        const origUserHome = process.env.HOME;
         const origProfile = process.env['CRTR_PROFILE_ID'];
-        const userHome = join(tmpdir(), `crtr-w-home-${Math.random().toString(36).slice(2, 8)}`);
-        mkdirSync(userHome, { recursive: true });
-        homes.push(userHome);
-        process.env.HOME = userHome;
         try {
             const profile = createProfile('paused watcher', [{ path: '/tmp', memory: 'content' }]);
             pauseProfile(profile.profileId);
@@ -391,20 +381,16 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
             const pi = makeFakePi();
             disposers.push(registerWatcher(pi));
             await wait(TICK_MS + 100);
-            appendInbox('node-paused-profile', { from: 'child-1', tier: 'critical', kind: 'update', label: 'sent while paused' });
+            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(readCursor('node-paused-profile'), undefined, 'the held entry stays unconsumed');
+            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 (origUserHome === undefined)
-                delete process.env.HOME;
-            else
-                process.env.HOME = origUserHome;
             if (origProfile === undefined)
                 delete process.env['CRTR_PROFILE_ID'];
             else
@@ -435,16 +421,17 @@ describe('canvas inbox watcher — action-gated startup (session_start arm)', ()
         };
         // 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 = appendInbox('node-action-gate', { from: 'child-1', tier: 'normal', kind: 'update', label: 'pre-bind entry' });
+        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(readCursor('node-action-gate'), undefined, 'the durable cursor is untouched 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;
@@ -452,9 +439,9 @@ describe('canvas inbox watcher — action-gated startup (session_start arm)', ()
         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(readCursor('node-action-gate'), undefined, 'still uncommitted until agent_settled');
+        assert.equal(acknowledgedNodeMailCount('node-action-gate'), 0, 'still uncommitted until agent_settled');
         await settle(pi);
-        assert.equal(readCursor('node-action-gate'), entry.entry_id, 'cursor committed at agent_settled');
+        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);
@@ -465,14 +452,15 @@ describe('canvas inbox watcher — action-gated startup (session_start arm)', ()
     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();
-        appendInbox('node-dispose-before-start', { from: 'child-1', tier: 'normal', kind: 'update', label: 'never armed' });
+        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(readCursor('node-dispose-before-start'), undefined, 'disposal before start commits nothing');
+        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);
@@ -480,38 +468,26 @@ describe('canvas inbox watcher — action-gated startup (session_start arm)', ()
         assert.equal(pi.injected.length, 0, 'session_start after disposal does not resurrect the discarded generation');
     });
 });
-// Durable-cursor model (at-least-once, one conservative boundary): the in-memory
-// `cursor` advances at buffer time (so a burst is never re-read into the same
-// watcher's buffer), but the on-disk cursor commits at `agent_settled` — never
-// on the fire-and-forget send return, never at `agent_end` (which fires before
-// pi decides on retry/continuation). A send returning normally is a HANDOFF,
-// and the commit clamps below anything still buffered. agent_settled is
-// authoritative and commits unconditionally, with no `hasPendingMessages()`
-// veto: pi's contract guarantees no queued continuation remains once it fires.
-// `session_shutdown` is the graceful-teardown safety net for a settle that
-// never fired before exit; THERE `ctx.hasPendingMessages()` still gates the
-// commit, because an unconsumed queued send dies with the process. A watcher
-// that dies (crash, SIGTERM, daemon kick) before a committing settle leaves the
-// on-disk cursor behind, so a fresh watcher re-reads and re-delivers rather
-// than silently losing the entry. See canvas-inbox-watcher.ts's header/inline
-// comments on `handedOffWatermark`, `commitTarget`, `commitAtSettle`, and
-// `commitAtShutdown` for the full rationale.
-describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
-    test('mid-turn handoff, crash before settle: on-disk cursor NOT advanced, fresh watcher re-delivers', async () => {
-        freshNode('node-cursor-crash');
+// 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);
-        appendInbox('node-cursor-crash', { from: 'child-1', tier: 'normal', kind: 'update', label: 'still working' });
+        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 durability boundary: no settle has fired, so the on-disk cursor must
-        // still be untouched — this is the assertion that proves the fix (a
-        // commit-at-buffer-time / commit-on-send variant would have committed here).
-        assert.equal(readCursor('node-cursor-crash'), undefined, 'on-disk cursor not committed before a settle');
+        // 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
@@ -525,44 +501,43 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         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: cursor committed, fresh watcher does NOT redeliver', async () => {
-        freshNode('node-cursor-committed');
+    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 = appendInbox('node-cursor-committed', { from: 'child-2', tier: 'normal', kind: 'update', label: 'still working' });
+        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(readCursor('node-cursor-committed'), undefined, 'not yet committed before the settle');
+        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 commits the cursor.
+        // THAT acknowledges the delivery.
         await settle(pi1);
-        assert.equal(readCursor('node-cursor-committed'), entry.entry_id, 'cursor committed to disk at agent_settled');
+        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-cursor-idle');
+        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 = appendInbox('node-cursor-idle', { from: 'child-3', tier: 'normal', kind: 'update', label: 'idle update' });
+        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 cursor stays put until the turn settles. (One rule: no
-        // immediate idle-path commit.)
-        assert.equal(readCursor('node-cursor-idle'), undefined, 'idle send does not commit on the fire-and-forget return');
+        // 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(readCursor('node-cursor-idle'), entry.entry_id, 'idle-path delivery commits at the turn it started settling');
+        assert.equal(acknowledgedNodeMailCount('node-receipt-idle'), 1, 'idle-path delivery commits at the turn it started settling');
     });
-    test('synchronous send throw then agent_settled: durable cursor NOT advanced past the re-buffered entry, fresh watcher re-delivers', async () => {
-        freshNode('node-cursor-failsend');
+    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.
@@ -570,12 +545,12 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         disposers.push(registerWatcher(pi1));
         pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
         await wait(TICK_MS + 100);
-        appendInbox('node-cursor-failsend', { from: 'child-1', tier: 'normal', kind: 'update', label: 'never delivered' });
+        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(readCursor('node-cursor-failsend'), undefined, 'durable cursor not advanced past a re-buffered, never-delivered entry');
+        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);
@@ -583,7 +558,7 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         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-cursor-critical');
+        freshNode('node-receipt-critical');
         const pi1 = makeFakePi();
         let aborted = 0;
         disposers.push(registerWatcher(pi1));
@@ -591,15 +566,15 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         // preempts via ctx.abort()).
         pi1.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false, abort: () => { aborted += 1; } });
         await wait(TICK_MS + 100);
-        appendInbox('node-cursor-critical', { from: 'child-1', tier: 'critical', kind: 'update', label: 'critical work' });
+        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: () => true });
-        await settle(pi1);
-        assert.equal(readCursor('node-cursor-critical'), undefined, 'abort-generated settle does not commit the pending critical entry before its retry');
+        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);
@@ -607,7 +582,7 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         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-cursor-batchB');
+        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.
@@ -617,17 +592,16 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         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 = appendInbox('node-cursor-batchB', { from: 'child-a', tier: 'normal', kind: 'update', label: 'batch A' });
+        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 = appendInbox('node-cursor-batchB', { from: 'child-b', tier: 'normal', kind: 'update', label: 'batch B' });
+        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(readCursor('node-cursor-batchB'), a.entry_id, 'commit lands on handed-off batch A');
-        assert.notEqual(readCursor('node-cursor-batchB'), b.entry_id, 'commit does not cross the still-buffered batch B');
+        assert.equal(acknowledgedNodeMailCount('node-receipt-batchB'), 1, 'commit lands on handed-off batch A');
         const pi2 = makeFakePi();
         disposers.push(registerWatcher(pi2));
         await waitForFirstInjection(pi2);
@@ -640,26 +614,25 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
     // — 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 stalls the cursor with no later settle to
-    // clear it.
+    // 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-cursor-failhold');
+        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 = appendInbox('node-cursor-failhold', { from: 'child-1', tier: 'normal', kind: 'update', label: 'queued across a failure' });
+        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(readCursor('node-cursor-failhold'), undefined, 'a failure agent_end does not commit');
+        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(readCursor('node-cursor-failhold'), entry.entry_id, 'agent_settled commits unconditionally, even when hasPendingMessages() reports pending');
+        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);
@@ -671,10 +644,10 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
     // 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-cursor-refresh-shutdown');
+        freshNode('node-receipt-refresh-shutdown');
         closeDb();
         const meta = {
-            node_id: 'node-cursor-refresh-shutdown', name: 'r', created: new Date().toISOString(),
+            node_id: 'node-receipt-refresh-shutdown', name: 'r', created: new Date().toISOString(),
             cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
             status: 'active',
         };
@@ -683,26 +656,26 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         disposers.push(registerWatcher(pi));
         pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
         await wait(TICK_MS + 100);
-        appendInbox(meta.node_id, { from: 'child-x', tier: 'normal', kind: 'update', label: 'handoff at shutdown' });
+        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(readCursor(meta.node_id), undefined, 'a refresh keeps the shutdown handoff uncommitted for replay');
+        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-cursor-shutdownhold');
+        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 = appendInbox('node-cursor-shutdownhold', { from: 'child-1', tier: 'normal', kind: 'update', label: 'still queued at shutdown' });
+        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(readCursor('node-cursor-shutdownhold'), undefined, 'session_shutdown declines to commit while pi reports pending sends');
+        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();
@@ -711,27 +684,27 @@ describe('canvas inbox watcher — durable cursor (at-least-once)', () => {
         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(readCursor('node-cursor-shutdownhold'), entry.entry_id, 'the redelivered entry commits once the fresh watcher settles cleanly');
+        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-cursor-situational');
-        appendSituationalContext('node-cursor-situational', 'ambient checkout state');
+        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 = appendInbox('node-cursor-situational', {
+        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(readCursor('node-cursor-situational'), undefined, 'not committed before the settle');
+        assert.equal(acknowledgedNodeMailCount('node-receipt-situational'), 0, 'not committed before the settle');
         await settle(pi1);
-        assert.equal(readCursor('node-cursor-situational'), entry.entry_id, 'the situational handoff commits at the drained settle');
+        assert.equal(acknowledgedNodeMailCount('node-receipt-situational'), 1, 'the situational handoff commits at the drained settle');
     });
 });