@north-light/crouter 0.3.311 → 0.3.313

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

@@ -7,16 +7,19 @@
 // its helpers in isolation.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHeadlessHarness, readLines } from '../helpers/harness.js';
 import { createAttachKit } from '../helpers/broker-clients.js';
+import { openDb } from '../../canvas/db.js';
 import { defaultModelLaddersConfig } from '../../../types.js';
-import { admitProviderRetryEpisode, readFault, readProviderRetryEpisode } from '../../runtime/fault.js';
+import { admitEpisode, readEpisode as readProviderRetryEpisode, readFault, recordPendingEpisode } from '../../canvas/recovery.js';
 import { buildPiArgv, normalizeModel } from '../../runtime/launch.js';
+import { writeRawConfig } from '../../config.js';
 import { encodeFrame } from '../../runtime/broker-protocol.js';
 import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, generatedContextText, parseCard } from '../../../shared/generated-context.js';
 import { RUNTIME_RESTART_CONTINUATION } from '../../runtime/kickoff.js';
+import { writeSubscriptionPool } from '../../subscription-state.js';
 const MODEL_LADDERS = defaultModelLaddersConfig();
 function resolvedModel(spec) {
     const normalized = normalizeModel(spec, MODEL_LADDERS);
@@ -31,26 +34,46 @@ const OPENAI_STRONG = resolvedModel('openai/strong');
 let h;
 const kit = createAttachKit(() => h);
 const { attachUntil } = kit;
-function poolPath(provider) {
-    const name = provider === 'anthropic' ? 'anthropic-subscriptions.json' : 'openai-codex-subscriptions.json';
-    return join(h.agentHome, '.pi', 'agent', name);
+function episodeSessionId(episode) {
+    assert.ok(episode.sessionId !== null, 'a provider retry episode is bound to a session');
+    return episode.sessionId;
 }
-function seedPool(provider, cooling) {
-    const path = poolPath(provider);
-    mkdirSync(join(h.agentHome, '.pi', 'agent'), { recursive: true });
-    writeFileSync(path, JSON.stringify([{
+function admitProviderRetryEpisode(nodeId, episode, fault) {
+    return admitEpisode(nodeId, { sessionId: episodeSessionId(episode), faultId: fault.faultId, retry: fault.retry });
+}
+function setActiveFaultAnchor(nodeId, anchorEntryId) {
+    const result = openDb().prepare('UPDATE node_faults SET anchor_entry_id = ? WHERE node_id = ? AND active = 1').run(anchorEntryId, nodeId);
+    assert.equal(result.changes, 1, 'the fixture changes exactly one active fault');
+}
+function restoreAdmittedProviderRetryEpisode(nodeId, episode, fault) {
+    const stored = recordPendingEpisode(nodeId, {
+        sessionId: episodeSessionId(episode),
+        input: {
+            link: fault.link,
+            op: fault.op,
+            kind: fault.kind,
+            retry: fault.retry,
+            message: fault.message,
+            since: fault.since,
+            operation_id: fault.operation_id,
+            ...(fault.anchorEntryId === undefined ? {} : { anchorEntryId: fault.anchorEntryId }),
+            ...(fault.providerError === undefined ? {} : { providerError: fault.providerError }),
+        },
+    });
+    assert.ok(stored !== null, 'the bound session accepts a pending recovery episode');
+    assert.equal(admitProviderRetryEpisode(nodeId, episode, stored), true, 'the pending recovery episode becomes admitted');
+}
+async function seedPool(provider, cooling) {
+    await writeSubscriptionPool(provider, [{
             label: 'test-account', refresh: 'refresh', access: 'access', expires: Date.now() + 60_000,
             rateLimitedUntil: cooling ? Date.now() + 60_000 : 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
-        }]));
+        }]);
 }
 function modelRoute(spec) {
     return { ultra: spec, strong: spec, medium: spec, light: spec };
 }
 function seedCapacityFallbackRoutes() {
-    const userConfigDir = join(h.agentHome, '.crouter');
-    const userConfigPath = join(userConfigDir, 'config.json');
-    mkdirSync(userConfigDir, { recursive: true });
-    writeFileSync(userConfigPath, JSON.stringify({
+    writeRawConfig('user', {
         kinds: { 'test/capacity-fallback': { whenToUse: 'Capacity fallback regression.', model: 'anthropic/medium' } },
         modelRoutes: {
             primary: { family: 'anthropic', credentialSource: 'user', providerId: 'fake-primary', models: modelRoute('fake-primary/primary') },
@@ -58,8 +81,7 @@ function seedCapacityFallbackRoutes() {
             largerFallback: { family: 'anthropic', credentialSource: 'third', providerId: 'fake-large', models: modelRoute('fake-large/large') },
         },
         modelRouting: { credentialSourceOrder: ['user', 'northlight', 'third'], familyOrder: ['anthropic'], strengthFallback: ['medium'] },
-    }));
-    return userConfigPath;
+    });
 }
 function seedCapacityFixture(id, largeContextWindow = 999) {
     const dir = join(h.home, 'nodes', id);
@@ -119,10 +141,12 @@ afterEach(() => {
 });
 test('a normalized 503 survives into a durable provider fault and re-drives the turn', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('structured provider failure parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'structured provider failure', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial structured-failure fixture turn started' });
+    const kickoffObserver = await attachUntil(child, 'observer', 'structured-503-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'structured 503 kickoff settled');
+    kickoffObserver.close();
     const baselineStarts = agentStartCount(child);
     h.fakeCmd(child, {
         cmd: 'stop',
@@ -146,8 +170,8 @@ test('a managed-cooling terminal authors a rate-limit auto fault whose deadline
     const parent = h.spawnRoot('cooling terminal parent');
     // The terminal fault path is pool-independent — the stophook classifies purely
     // off the errorMessage text + the cooling diagnostic, so pool state is inert.
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'cooling terminal', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial cooling fixture turn started' });
     const kickoffObserver = await attachUntil(child, 'observer', 'cooling-terminal-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'cooling terminal kickoff settled');
@@ -187,8 +211,8 @@ test('a managed-cooling terminal authors a rate-limit auto fault whose deadline
 });
 test('a crashed broker re-drives a pending episode and a no-progress admitted one, never a progressed or invalidated episode', { timeout: 90_000 }, async () => {
     const parent = h.spawnRoot('durable provider episode parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await 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');
@@ -198,7 +222,7 @@ test('a crashed broker re-drives a pending episode and a no-progress admitted on
         cmd: 'stop', reason: 'error', errorMessage: 'Managed provider pools are temporarily unavailable.', deadline: Date.now() + 2_000,
     });
     const pending = await h.waitFor(() => readProviderRetryEpisode(pendingNode)?.state === 'pending' ? readProviderRetryEpisode(pendingNode) : null, { label: 'pending provider episode persisted before crash' });
-    assert.equal(pending.sessionFile, realpathSync(h.node(pendingNode).pi_session_file), 'the pending episode is tied to its transcript path');
+    assert.equal(pending.sessionId, h.node(pendingNode).pi_session_id, 'the pending episode is tied to its bound session');
     await crashAndRespawn(pendingNode, h.bootCount(pendingNode));
     await h.waitFor(() => agentStartCount(pendingNode) >= pendingStarts + 1, { label: 'replacement re-drove the pending episode' });
     await new Promise((resolve) => setTimeout(resolve, 300));
@@ -227,7 +251,7 @@ test('a crashed broker re-drives a pending episode and a no-progress admitted on
     // already elapsed (see the design's "effectively zero delay" note), so this
     // proves the re-drive without a real ~60s wait.
     const admittedFaultForEpisode = { ...admittedFault, retry: { ...admittedFault.retry, nextAt: new Date(Date.now() - 1_000).toISOString() } };
-    assert.equal(admitProviderRetryEpisode(admittedNode, admittedPending.sessionFile, admittedFaultForEpisode), true, 'the dispatch boundary durably admits the matching episode');
+    assert.equal(admitProviderRetryEpisode(admittedNode, admittedPending, admittedFaultForEpisode), true, 'the dispatch boundary durably admits the matching episode');
     assert.equal(readProviderRetryEpisode(admittedNode)?.state, 'admitted');
     await crashAndRespawn(admittedNode, h.bootCount(admittedNode));
     await h.waitFor(() => agentStartCount(admittedNode) >= admittedStarts + 1, { label: 'replacement re-drove the no-progress admitted episode' });
@@ -269,7 +293,7 @@ test('a crashed broker re-drives a pending episode and a no-progress admitted on
     const progressPending = await h.waitFor(() => readProviderRetryEpisode(progressNode)?.state === 'pending' ? readProviderRetryEpisode(progressNode) : null, { label: 'progress episode pending record persisted' });
     const progressFault = readFault(progressNode);
     assert.ok(progressFault !== null, 'the pending episode retains its retry fault before admission');
-    assert.equal(admitProviderRetryEpisode(progressNode, progressPending.sessionFile, progressFault), true, 'the dispatch boundary durably admits the matching episode');
+    assert.equal(admitProviderRetryEpisode(progressNode, progressPending, progressFault), true, 'the dispatch boundary durably admits the matching episode');
     assert.equal(readProviderRetryEpisode(progressNode)?.state, 'admitted');
     // A real successful turn past the anchor: proves the dead attempt's slot is
     // no longer the branch tail, so recoverOnStartup's no-progress proof must
@@ -278,16 +302,12 @@ test('a crashed broker re-drives a pending episode and a no-progress admitted on
     progressController.send({ type: 'prompt', text: `progress past anchor ${Date.now()}` });
     await progressController.waitFrame((f) => f.type === 'agent_end', 'the progress turn settles');
     progressController.close();
-    // The natural settle above already clears the episode (any non-error settle
-    // clears it unconditionally) — expected, and orthogonal to what this half
-    // proves. Restore `admitted` with the SAME original anchor/fault by writing
-    // the job-dir file directly, bypassing the guarded API (mirrors the
-    // `reload_auth leaves a parked auth fault` precedent above in this file), so
-    // the crash below tests the no-progress proof against a genuine post-anchor
-    // assistant turn instead of an unreliable real-crash race.
+    // The natural settle above clears the episode. Restore the same admitted SQL
+    // record so the crash below tests the no-progress proof against a genuine
+    // post-anchor assistant turn rather than an unreliable real-crash race.
     await h.waitFor(() => readProviderRetryEpisode(progressNode) === null, { label: 'the settled turn cleared the episode' });
-    writeFileSync(join(h.home, 'nodes', progressNode, 'job', 'provider-retry'), JSON.stringify({ state: 'admitted', sessionFile: progressPending.sessionFile, anchorEntryId: progressPending.anchorEntryId, fault: progressFault }));
-    assert.equal(readProviderRetryEpisode(progressNode)?.state, 'admitted', 'the direct write restores the admitted episode for the crash below');
+    restoreAdmittedProviderRetryEpisode(progressNode, progressPending, progressFault);
+    assert.equal(readProviderRetryEpisode(progressNode)?.state, 'admitted', 'the SQL fixture restores the admitted episode for the crash below');
     const progressStartsBeforeCrash = agentStartCount(progressNode);
     await crashAndRespawn(progressNode, h.bootCount(progressNode));
     await new Promise((resolve) => setTimeout(resolve, 300));
@@ -343,8 +363,8 @@ test('a crashed broker re-drives a pending episode and a no-progress admitted on
 });
 test('reload_auth re-drives a parked fatal provider-auth turn exactly once', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('auth reload parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'auth reload child', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial auth fixture turn started' });
     const baselineStarts = agentStartCount(child);
@@ -373,8 +393,8 @@ test('reload_auth re-drives a parked fatal provider-auth turn exactly once', { t
 });
 test('reload_auth leaves a parked auth fault with its original session when navigation is overtaken by replacement', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('auth replacement parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'auth replacement child', { model: OPENAI_STRONG.spec });
     await h.waitFor(() => agentStartCount(child) >= 1, { label: 'initial replacement fixture turn started' });
     h.fakeCmd(child, {
@@ -391,10 +411,7 @@ test('reload_auth leaves a parked auth fault with its original session when navi
     // Force the redrive's leaf/anchor comparison to diverge so it actually enters
     // navigateTree (a matching leaf/anchor legitimately skips the rewind) — the
     // fixture's fault otherwise anchors to the leaf already current.
-    const faultFilePath = join(nodeDir, 'job', 'fault');
-    const rawFault = JSON.parse(readFileSync(faultFilePath, 'utf8'));
-    rawFault['anchorEntryId'] = 'auth-replacement-anchor-mismatch';
-    writeFileSync(faultFilePath, JSON.stringify(rawFault));
+    setActiveFaultAnchor(child, 'auth-replacement-anchor-mismatch');
     writeFileSync(join(nodeDir, 'fake-pi.navigate-hold'), '');
     const controller = await kit.attach(child, 'controller', 'auth-replacement-test');
     controller.send({ type: 'reload_auth' });
@@ -412,8 +429,8 @@ test('reload_auth leaves a parked auth fault with its original session when navi
 // definitive failure make the episode terminal.
 test('a recovered compact-and-retry commits nothing, while a definitive failure publishes one structured overflow fault and terminal notice', { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('overflow parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
     const child = await h.spawnHeadlessChild(parent, 'overflow child', { model: OPENAI_STRONG.spec });
     h.fakeCmd(child, { cmd: 'overflow', outcome: 'recover' });
     await h.waitFor(() => overflowOutcome(child) === 'recover' ? true : null, { label: 'recovered overflow reached agent_settled' });
@@ -437,18 +454,21 @@ test('a recovered compact-and-retry commits nothing, while a definitive failure
     assert.equal(autoFault.kind, 'rate-limit', 'ordinary settled provider failures retain broker-owned retry behavior');
     h.fakeCmd(child, { cmd: 'overflow', outcome: 'fail' });
     await h.waitFor(() => overflowOutcome(child) === 'fail' ? true : null, { label: 'failed overflow reached agent_settled' });
-    const fault = readFault(child);
-    assert.equal(fault?.kind, 'context-overflow');
-    assert.equal(fault?.op, 'context overflow recovery');
-    assert.equal(fault?.retry.disposition, 'fatal');
-    assert.match(fault?.message ?? '', /failed after one compact-and-retry attempt/i);
+    const fault = await h.waitFor(() => {
+        const current = readFault(child);
+        return current?.kind === 'context-overflow' ? current : null;
+    }, { label: 'failed overflow publishes its definitive context-overflow fault' });
+    assert.equal(fault.kind, 'context-overflow');
+    assert.equal(fault.op, 'context overflow recovery');
+    assert.equal(fault.retry.disposition, 'fatal');
+    assert.match(fault.message, /failed after one compact-and-retry attempt/i);
     await h.tick();
     assert.equal(h.status(child), 'dead', 'the daemon applies one terminal child transition');
     const notices = h.inbox(parent).filter((entry) => /exceeded its model context window/i.test(entry.label));
     assert.equal(notices.length, 1, 'the parent receives exactly one structured overflow notice');
 });
 test('provider-retry and model-not-found fallback both terminate when every available target has a smaller known context window', { timeout: 30_000 }, async () => {
-    const userConfigPath = seedCapacityFallbackRoutes();
+    seedCapacityFallbackRoutes();
     try {
         const parent = h.spawnRoot('capacity fallback parent');
         const providerRetry = await h.spawnHeadlessChild(parent, 'provider retry capacity fallback', { kind: 'test/capacity-fallback' });
@@ -474,7 +494,7 @@ test('provider-retry and model-not-found fallback both terminate when every avai
         assert.match(modelNotFoundFault.message, /1000 tokens/, 'the terminal fault survives ordinary settlement staging');
     }
     finally {
-        rmSync(userConfigPath, { force: true });
+        writeRawConfig('user', {});
     }
 });
 // Two real logical launches keep both user paths non-vacuous: the picker first
@@ -482,14 +502,11 @@ test('provider-retry and model-not-found fallback both terminate when every avai
 // directly against still-present logical intent before Shift+Tab and replay.
 test("picker and Alt+M choices each clear logical routing, and Alt+M / Shift+Tab become the durable restart recipe", { timeout: 30_000 }, async () => {
     const parent = h.spawnRoot('model durability parent');
-    seedPool('anthropic', false);
-    seedPool('openai-codex', false);
-    const userConfigDir = join(h.agentHome, '.crouter');
-    const userConfigPath = join(userConfigDir, 'config.json');
-    mkdirSync(userConfigDir, { recursive: true });
-    writeFileSync(userConfigPath, JSON.stringify({
+    await seedPool('anthropic', false);
+    await seedPool('openai-codex', false);
+    writeRawConfig('user', {
         kinds: { 'test/logical-openai': { whenToUse: 'Logical OpenAI routing test.', model: 'openai/strong' } },
-    }));
+    });
     const pickerNode = await h.spawnHeadlessChild(parent, 'picker durability child', { kind: 'test/logical-openai' });
     const pickerBefore = h.node(pickerNode);
     assert.deepEqual(pickerBefore.launch?.modelIntent, { family: 'openai', strength: 'strong' }, 'picker fixture starts from a logical launch preference');
@@ -541,17 +558,14 @@ test("picker and Alt+M choices each clear logical routing, and Alt+M / Shift+Tab
     assert.equal(replay.argv[modelArg + 1], expected, 'the replayed model argument carries both choices');
     assert.equal(replay.env.CRTR_MODEL_INTENT, undefined, 'the stale logical intent is absent from the restarted broker environment');
     ladderCtrl.close();
-    rmSync(userConfigPath, { force: true });
+    writeRawConfig('user', {});
 });
 test('reload_auth restores a newly authenticated personal route before the next idle prompt', { timeout: 30_000 }, async () => {
     const personal = { provider: 'personal-anthropic', id: 'claude-personal' };
     const funded = { provider: 'northlight-openai', id: 'gpt-funded' };
     const personalSpec = `${personal.provider}/${personal.id}:xhigh`;
-    const userConfigDir = join(h.agentHome, '.crouter');
-    const userConfigPath = join(userConfigDir, 'config.json');
     const unauthenticatedProvider = join(h.home, 'fake-pi.unauthenticated-provider');
-    mkdirSync(userConfigDir, { recursive: true });
-    writeFileSync(userConfigPath, JSON.stringify({
+    writeRawConfig('user', {
         // A fixture-private kind, never `general`: the child launches with the
         // package root as cwd, so an ambient project-scope config above the repo
         // (`~/.crouter/config.json`) overrides this user-scope `general` and the
@@ -562,7 +576,7 @@ test('reload_auth restores a newly authenticated personal route before the next
             funded: { family: 'anthropic', credentialSource: 'northlight', providerId: funded.provider, models: { ultra: `${funded.provider}/${funded.id}:medium`, strong: `${funded.provider}/${funded.id}:medium`, medium: `${funded.provider}/${funded.id}:medium`, light: `${funded.provider}/${funded.id}:medium` } },
         },
         modelRouting: { credentialSourceOrder: ['user', 'northlight'], familyOrder: ['anthropic'], strengthFallback: ['medium'] },
-    }));
+    });
     writeFileSync(unauthenticatedProvider, personal.provider);
     try {
         const parent = h.spawnRoot('auth route reconciliation parent');
@@ -571,6 +585,9 @@ test('reload_auth restores a newly authenticated personal route before the next
         const controller = await kit.connectRaw(child, { read: true });
         controller.send({ type: 'hello', role: 'controller', client_id: 'auth-route-reconciliation' });
         await h.waitFor(() => controller.frames.some((frame) => frame.type === 'welcome') ? true : null, { label: 'route reconciliation controller welcomed' });
+        await h.waitFor(() => agentStartCount(child) >= 1, { label: 'route reconciliation kickoff started' });
+        const kickoffObserver = await attachUntil(child, 'observer', 'route-reconciliation-kickoff-settled', (a) => a.welcome.snapshot.state.isStreaming === false, 'route reconciliation kickoff settled');
+        kickoffObserver.close();
         rmSync(unauthenticatedProvider, { force: true });
         const frameStart = controller.frames.length;
         controller.writeRaw(encodeFrame({ type: 'reload_auth' })
@@ -595,7 +612,7 @@ test('reload_auth restores a newly authenticated personal route before the next
     }
     finally {
         rmSync(unauthenticatedProvider, { force: true });
-        rmSync(userConfigPath, { force: true });
+        writeRawConfig('user', {});
     }
 });
 // MODEL-LESS LAUNCH RE-DRIVE — MUST REMAIN THE LAST TEST IN THIS FILE. Its
@@ -629,12 +646,9 @@ test('reload_auth restores a newly authenticated personal route before the next
 // subscription-pool occupancy (broker-sdk-wiring's scope).
 test('login re-drive → list_models self-heals (0a) and reload_auth resolves a model + fires the deferred kickoff', { timeout: 30_000 }, async () => {
     const noAuthSentinel = join(h.home, 'fake-pi.no-auth');
-    const userConfigDir = join(h.agentHome, '.crouter');
-    const userConfigPath = join(userConfigDir, 'config.json');
-    mkdirSync(userConfigDir, { recursive: true });
-    writeFileSync(userConfigPath, JSON.stringify({
+    writeRawConfig('user', {
         kinds: { general: { whenToUse: 'General work.', model: 'anthropic/medium' } },
-    }));
+    });
     writeFileSync(noAuthSentinel, '1');
     try {
         const parent = h.spawnRoot('login re-drive parent');
@@ -663,6 +677,6 @@ test('login re-drive → list_models self-heals (0a) and reload_auth resolves a
     }
     finally {
         rmSync(noAuthSentinel, { force: true });
-        rmSync(userConfigPath, { force: true });
+        writeRawConfig('user', {});
     }
 });

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

@@ -4,8 +4,8 @@
 // acting root:
 //
 //  (1) Issue #222/#353 — a real idle-release cycle must settle the inbox watcher
-//      before the broker exits, and the daemon may only revive for a row strictly
-//      after the committed cursor.
+//      before the broker exits, and the daemon may only revive for a later
+//      pending SQL delivery.
 //  (2) The observed 57-broker / ~5.4GB leak — DAEMON SUPERVISION, not an agent
 //      event, owns the unattended clock. A node with no live obligation is
 //      terminalized into prunable history (a resident completed its
@@ -21,7 +21,8 @@ import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
+import { enqueueNodeMail } from '../../feed/messages.js';
+import { openDb } from '../../canvas/db.js';
 import { acquireCronRunLease, armCron, setCronState } from '../../canvas/crons.js';
 import { registerWarmSpare, subscribe, subscriptionsOf, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
@@ -31,6 +32,17 @@ import { createAttachKit } from '../helpers/broker-clients.js';
 let h;
 let root;
 const attach = createAttachKit(() => h);
+function deliveryState(deliveryId) {
+    return openDb().prepare('SELECT state FROM deliveries WHERE delivery_id = ?').get(deliveryId)?.state;
+}
+function mailTo(nodeId) {
+    return openDb().prepare(`SELECT m.sender_node_id, m.body_json, m.label FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? ORDER BY m.seq`).all(nodeId).map((row) => ({
+        sender: row.sender_node_id,
+        body: row.body_json === null ? null : JSON.parse(row.body_json),
+        label: row.label,
+    }));
+}
 before(async () => {
     h = await createHarness({ headless: true, sessionPrefix: 'crtr-dormancy' });
     root = h.spawnRoot('dormancy-release suite root');
@@ -105,8 +117,8 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
     // run in-process. Keeping this compiled seam at production cadence would add
     // multiple seconds of polling around two real broker boots, so it uses the
     // same fast cadence without weakening what it proves: the settlement
-    // lifecycle, cursor semantics, and hasPendingMessages veto are all
-    // independent of how fast the watcher polls.
+    // lifecycle, delivery acknowledgement semantics, and hasPendingMessages veto
+    // are all independent of how fast the watcher polls.
     const manager = h.fabricateBrokerNode({ id: 'settle-veto-manager', status: 'idle', parent: root });
     updateNode(manager, {
         launch: {
@@ -127,12 +139,13 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
     // awaiting, so its real stophook takes the idle-release branch.
     const worker = h.fabricateBrokerNode({ parent: manager, status: 'idle', intent: 'idle-release' });
     subscribe(manager, worker, true);
-    const first = appendInbox(manager, {
-        from: 'worker-a',
-        tier: 'normal',
+    const first = enqueueNodeMail(manager, {
+        senderNodeId: 'worker-a',
         kind: 'final',
         label: 'first completed',
-        data: { body: 'first completed' },
+        bodyJson: { body: 'first completed' },
+        urgency: 'normal',
+        wake: 1,
     });
     await h.awaitWake(manager, { match: /first completed/ });
     // The real watcher injects an idle message, whose fake session now starts and
@@ -140,27 +153,28 @@ test('idle-release settles its real watcher before exit; daemon revives exactly
     // broker exit. No test-driven turn or settlement dispatch is involved.
     await awaitReleased(manager);
     await h.awaitFleetExit(manager);
-    assert.equal(readCursor(manager), first.entry_id, 'the exact handed-off row commits before clean shutdown');
+    assert.equal(deliveryState(first.deliveryId), 'acknowledged', 'the exact handed-off SQL delivery is acknowledged before clean shutdown');
     const cyclesAfterRelease = h.node(manager).cycles ?? 0;
     await h.tick();
     assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease, 'a second supervision tick does not revive a settled row');
     const injectedBeforeSecond = h.injected(manager).length;
-    const second = appendInbox(manager, {
-        from: 'worker-b',
-        tier: 'normal',
+    const second = enqueueNodeMail(manager, {
+        senderNodeId: 'worker-b',
         kind: 'final',
         label: 'second completed',
-        data: { body: 'second completed' },
+        bodyJson: { body: 'second completed' },
+        urgency: 'normal',
+        wake: 1,
     });
-    assert.ok(readInboxSince(manager, first.entry_id).some((entry) => entry.entry_id === second.entry_id), 'the next row is physically after the committed cursor');
-    assert.equal(readInboxSince(manager, second.entry_id).length, 0, 'the physical cursor boundary is exclusive');
+    assert.equal(deliveryState(first.deliveryId), 'acknowledged', 'the first receipt remains terminal');
+    assert.equal(deliveryState(second.deliveryId), 'pending', 'the later delivery is independently pending');
     await h.tick();
     assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease + 1, 'one later row revives once');
     await h.awaitBoot(manager, { minCount: 2 });
     await h.awaitWake(manager, { sinceCount: injectedBeforeSecond, match: /second completed/ });
     await awaitReleased(manager);
     await h.awaitFleetExit(manager);
-    assert.equal(readCursor(manager), second.entry_id, 'the later row commits at its own natural idle release');
+    assert.equal(deliveryState(second.deliveryId), 'acknowledged', 'the later delivery is acknowledged at its own natural idle release');
     await h.tick();
     assert.equal(h.node(manager).cycles ?? 0, cyclesAfterRelease + 1, 'the settled later row does not cause a duplicate revival');
 });
@@ -177,7 +191,7 @@ test('an already idle resident with no live obligation reconciles into completed
     await h.tick();
     assert.equal(h.node(nodeId)?.status, 'done', 'an older idle row becomes pruning-eligible without needing a broker revive');
     assert.equal(h.node(nodeId)?.intent, 'parked', 'the reconciled row carries the durable park marker (isParked)');
-    const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
+    const wake = mailTo(root).find((entry) => entry.sender === nodeId && entry.body?.['reason'] === 'child-auto-done');
     assert.ok(wake, 'the subscribing root learns that the parked resident completed without a final report');
 });
 test('an unattended resident with no live obligation completes on the daemon clock', { timeout: 30_000 }, async () => {
@@ -235,7 +249,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
         await h.awaitFleetExit(nodeId);
         assert.equal(h.fleet.has(nodeId), false, 'exit policy forgets the parked broker');
         assert.equal(h.node(nodeId)?.status, 'done', 'the row is terminal and eligible for history pruning');
-        const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
+        const wake = mailTo(root).find((entry) => entry.sender === nodeId && entry.body?.['reason'] === 'child-auto-done');
         assert.ok(wake, 'the subscribing root is woken when the unattended clock completes the resident');
         assert.match(wake.label, /submitted no final report/, 'the wake distinguishes automatic completion from a final report');
         await h.tick();

package/dist/core/__tests__/seam/held-deferred-human-prompt.test.js

@@ -7,7 +7,8 @@ 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 { enqueueNodeMail } from '../../feed/messages.js';
+import { acknowledgedNodeMailCount } from '../../canvas/deliveries.js';
 import { updateNode } from '../../canvas/index.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { createHeadlessHarness } from '../helpers/harness.js';
@@ -44,11 +45,12 @@ test('a Jiti-loaded watcher prepends its held deferred batch to a native broker
     });
     await reviveNode(nodeId, { resume: true, capacity: 'freeze' });
     await h.awaitBoot(nodeId);
-    const entry = appendInbox(nodeId, {
-        from: 'child',
-        tier: 'deferred',
+    enqueueNodeMail(nodeId, {
+        senderNodeId: 'child',
         kind: 'update',
         label: 'held Jiti deferred update',
+        urgency: 'deferred',
+        wake: 1,
     });
     await delay(150);
     const customPath = join(h.home, 'nodes', nodeId, 'fake-pi.custom-messages.jsonl');
@@ -59,5 +61,5 @@ test('a Jiti-loaded watcher prepends its held deferred batch to a native broker
     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');
+    assert.equal(acknowledgedNodeMailCount(nodeId), 1, 'agent_settled acknowledges the joined SQL delivery');
 });

package/dist/core/__tests__/seam/inbox-reference-guidance.test.js

@@ -7,8 +7,11 @@ import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { subscribe } from '../../canvas/index.js';
+import { claimNodeMail } from '../../canvas/deliveries.js';
+import { beginExecution } from '../../canvas/executions.js';
 import { resolveRef } from '../../canvas/history.js';
-import { appendInbox, coalesce, readInboxSince } from '../../feed/inbox.js';
+import { coalesce, nodeMailEntry } from '../../feed/inbox.js';
+import { enqueueNodeMail } from '../../feed/messages.js';
 import { pushUpdate } from '../../feed/feed.js';
 import { contextDirNote } from '../../runtime/bearings-render.js';
 import { coalesceBrokerInbox } from '../../runtime/broker/inbox.js';
@@ -16,15 +19,24 @@ import { createHeadlessHarness } from '../helpers/harness.js';
 let h;
 let root;
 let recipient;
+let recipientExecution;
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-inbox-reference-guidance' });
     root = h.spawnRoot('inbox reference guidance seam root');
     recipient = h.fabricateBrokerNode({ id: 'inbox-reference-recipient', parent: root, status: 'idle' });
+    recipientExecution = beginExecution(recipient, { daemonEpoch: h.fleet.epoch() });
 });
 after(async () => {
     if (h !== undefined)
         await h.dispose();
 });
+function latestEntry() {
+    const claim = claimNodeMail(recipient, recipientExecution, 'wake');
+    assert.equal(claim.action, 'claimed');
+    const delivery = claim.deliveries.at(-1);
+    assert.ok(delivery, 'the newly enqueued delivery is handed to the recipient execution');
+    return nodeMailEntry(delivery);
+}
 function onlyCard(entries) {
     const deliveries = coalesce(entries);
     assert.equal(deliveries.length, 1, 'one non-human inbox entry produces one card');
@@ -36,7 +48,7 @@ test('delivered report and message refs name the exact way to read their bodies'
     subscribe(recipient, publisher, true);
     const reportBody = 'published report body';
     await pushUpdate(publisher, reportBody);
-    const reportEntry = readInboxSince(recipient).at(-1);
+    const reportEntry = latestEntry();
     assert.equal(reportEntry.ref?.startsWith(`${publisher}:reports/`), true, 'delivery carries the canonical report handle');
     const reportRef = reportEntry.ref;
     const reportCard = onlyCard([reportEntry]);
@@ -49,13 +61,15 @@ test('delivered report and message refs name the exact way to read their bodies'
         'a'.repeat(1001),
         Array.from({ length: 13 }, (_, i) => `line ${i + 1}`).join('\n'),
     ]) {
-        const message = appendInbox(recipient, {
-            from: publisher,
-            tier: 'normal',
+        enqueueNodeMail(recipient, {
+            senderNodeId: publisher,
+            urgency: 'normal',
+            wake: 1,
             kind: 'message',
             label: 'long message',
-            data: { body },
+            bodyJson: { body },
         });
+        const message = latestEntry();
         assert.ok(message.ref?.startsWith('/'), 'a clipped message stores its full body at an absolute recipient path');
         const messageCard = onlyCard([message]);
         const brokerMessageCard = coalesceBrokerInbox([message], new Map())[0].text;

package/dist/core/__tests__/seam/node-outcome-delivery.test.js

@@ -8,11 +8,35 @@ import assert from 'node:assert/strict';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { closeDb } from '../../canvas/db.js';
-import { readOutcomeDelivery } from '../../canvas/node-outcome-deliveries.js';
+import { messageBodyForDelivery, readExternalActionDelivery } from '../../canvas/deliveries.js';
 import { createHeadlessHarness } from '../helpers/harness.js';
 let h;
 let root;
 let project;
+function outcomeDelivery(nodeId) {
+    const row = readExternalActionDelivery(`node-outcome:${nodeId}`);
+    if (row === null)
+        return null;
+    const adapter = row.adapter;
+    if (adapter?.adapter !== 'subprocess' || !Array.isArray(adapter.argv) || !adapter.argv.every((entry) => typeof entry === 'string') || typeof adapter.cwd !== 'string')
+        throw new Error(`outcome delivery ${row.deliveryId} has an invalid subprocess adapter`);
+    if (row.state !== 'armed' && row.state !== 'pending' && row.state !== 'handed_off' && row.state !== 'acknowledged' && row.state !== 'permanent_failed')
+        throw new Error(`outcome delivery ${row.deliveryId} has an invalid state`);
+    return {
+        state: row.state === 'handed_off' ? 'running' : row.state === 'acknowledged' ? 'accepted' : row.state,
+        actionName: row.destinationId,
+        argv: adapter.argv,
+        cwd: adapter.cwd,
+        configOrigin: typeof adapter.config_origin === 'string' ? adapter.config_origin : '',
+        payload: adapter.payload ?? null,
+        document: row.messageId === null ? null : messageBodyForDelivery(row.deliveryId),
+        attempt: row.attempts,
+        nextAttemptAt: row.nextAttemptAt ?? 0,
+        acceptedAt: row.acknowledgedAt,
+        permanentFailedAt: row.failedAt,
+        lastFailure: row.lastFailure,
+    };
+}
 function assertKeys(value, expected, label) {
     assert.deepEqual(Object.keys(value).sort(), [...expected].sort(), `${label} has the pinned document fields`);
 }
@@ -54,7 +78,7 @@ function assertResultDocument(document, nodeId, action, payloadJson, attempt) {
 function deliveryWhen(nodeId, predicate, label) {
     return h.waitFor(() => {
         closeDb();
-        const delivery = readOutcomeDelivery(nodeId);
+        const delivery = outcomeDelivery(nodeId);
         return delivery !== null && predicate(delivery) ? delivery : null;
     }, { label, timeoutMs: 20_000 });
 }
@@ -71,7 +95,7 @@ async function createAndFinalize(action, payload) {
     const nodeId = createdBody.node_id;
     await h.awaitBoot(nodeId);
     closeDb();
-    const armed = readOutcomeDelivery(nodeId);
+    const armed = outcomeDelivery(nodeId);
     assert.notEqual(armed, null, `node birth arms ${action} delivery`);
     assert.equal(armed.state, 'armed');
     assert.equal(armed.actionName, action);