@north-light/crouter 0.3.154

package/dist/core/__tests__/deferred-no-wake.test.js

@@ -0,0 +1,514 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/deferred-no-wake.test.ts
+//
+// REGRESSION LOCK — gh issue #341. `--tier deferred` is documented as the ONE
+// tier that never wakes an idle node ("read on its next natural cycle"), but
+// the wake block in `node message send`'s immediate-delivery path (src/commands/
+// node.ts) never consulted `tier` at all — it revived ANY dormant target
+// unconditionally. The daemon's idle-release second pass (crtrd.ts) had the
+// same gap one hop later: any unseen inbox entry, deferred or not, revived an
+// idle-released row.
+//
+// Fixed shape:
+//   (1) command layer — deferred to an ORDINARY dormant/revivable target
+//       (idle-released, or anything else with a real natural cycle ahead of
+//       it) appends durably and does NOT call reviveNode.
+//   (2) command layer — deferred to a TERMINAL target (done/canceled/
+//       finalized: no natural cycle ever brings it back) is rejected
+//       fail-loud, BEFORE any side effect (mirrors the existing
+//       output-schema+deferred rejection).
+//   (3) daemon second pass — a deferred-only unseen set is treated as "no
+//       wake-worthy work" (no revive, relaunch-attempt state cleared); a
+//       non-deferred unseen entry still wakes exactly as before, and delivers
+//       the previously-held deferred entry alongside it with no loss (neither
+//       entry is ever dropped or skipped by the cursor).
+//
+// (1) and (2) are exercised through the REAL `node message send` command
+// boundary (mirrors push-final-guard.test.ts's #339/#340 pattern) with
+// `headlessBrokerHost.launch` spied so a rejected/held delivery is proven to
+// never attempt a revive, without spawning a real engine. (3) is exercised by
+// fabricating an idle-released row directly and driving the REAL daemon
+// decision pass (`superviseTick`), mirroring child-death-wake.test.ts's
+// no-harness fabrication style.
+//
+// Phase 3 trigger→cron hard cut: the arm-time (`node trigger send`) and
+// daemon fire-time predicate/clock-trigger suites that used to live in this
+// file were removed along with the trigger subsystem itself. What remains
+// below covers only behavior the cut left fully intact: the immediate
+// `node message send --tier deferred` command path, the shared
+// `withFreshTerminalGuard` primitive, and the daemon/inbox-watcher
+// deferred-hold contract.
+import { test, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+import { createNode, deleteNode, getNode, setStatus, withFreshTerminalGuard } from '../canvas/canvas.js';
+import { hasNoNaturalCycle } from '../runtime/revive-all.js';
+import { canvasDbPath, nodeDir, apiSocketPath } from '../canvas/paths.js';
+import { closeDb } from '../canvas/db.js';
+import { createApiServer } from '../../daemon/api/server.js';
+import { CrtrClient } from '../../api/index.js';
+import { registerNode } from '../../commands/node.js';
+import { pushFinal } from '../feed/feed.js';
+import { InputError } from '../io.js';
+import { headlessBrokerHost } from '../runtime/host.js';
+import { appendInbox, readInboxSince, readCursor } from '../feed/inbox.js';
+import { superviseTick } from '../../daemon/crtrd.js';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { bindTestFleet } from './helpers/fleet.js';
+import { resetFleetForTests } from '../runtime/fleet.js';
+let home;
+let server;
+const prevNodeId = process.env['CRTR_NODE_ID'];
+// createApiServer binds its socket asynchronously (file created in the listen
+// callback), and the socket FILE existing does not yet prove the server answers
+// a full HTTP round-trip — under serial recycle the first request to a
+// freshly-listening in-process server can race the accept path and write-EPIPE.
+// Probe an actual `/healthz` round-trip (autostart OFF so a transient miss never
+// spawns a REAL crtrd against the isolated home) before handing the socket to a
+// cliClient() path.
+async function waitForSocket(path) {
+    const probe = CrtrClient.forLocalSocket({ autostart: false });
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path)) {
+            try {
+                await probe.healthz();
+                return;
+            }
+            catch {
+                /* not answering yet — keep polling */
+            }
+        }
+        await new Promise((r) => setTimeout(r, 25));
+    }
+    throw new Error(`api socket never answered /healthz at ${path}`);
+}
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+/** A pid guaranteed dead by the time spawnSync returns. */
+function deadPid() {
+    const r = spawnSync('true', [], { stdio: 'ignore' });
+    return r.pid ?? 0x7ffffffe;
+}
+function messageSendLeaf() {
+    const branch = registerNode().children.find((child) => child.name === 'message');
+    assert.ok(branch !== undefined && branch.kind === 'branch');
+    const leaf = branch.children.find((child) => child.name === 'send');
+    assert.ok(leaf !== undefined && leaf.kind === 'leaf');
+    return leaf;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-deferred-nowake-'));
+    process.env['CRTR_HOME'] = home;
+    // superviseTick and the in-process API server's launch verbs resolve
+    // boundFleet() (D-2). Empty is the point: no fabricated row here has a live
+    // broker, and every no-wake assertion is that no launch happens.
+    bindTestFleet();
+});
+beforeEach(async () => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    mkdirSync(home, { recursive: true });
+    // POST-P1 the `node message send` leaf forwards its wake/revive canvas ops
+    // through cliClient() over crtrd's socket. This home neutralizes the daemon (no REAL
+    // crtrd) but binds no server, so stand one up in-process on the isolated
+    // home's socket (apiSocketPath() resolves under CRTR_HOME=home). Closed in
+    // afterEach.
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+});
+afterEach(async () => {
+    await server?.close();
+    server = undefined;
+    closeDb();
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (prevNodeId === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = prevNodeId;
+    resetFleetForTests();
+});
+// ---------------------------------------------------------------------------
+// Command layer — the immediate-delivery wake block in node.ts
+// ---------------------------------------------------------------------------
+test('node message send --tier deferred to an ordinary dormant (idle-released) target does not revive it — appended and held for the next natural cycle', { timeout: 30_000 }, async () => {
+    const id = 'idleReleaseTarget';
+    createNode(node(id, { status: 'idle', intent: 'idle-release' }));
+    const inboxBefore = readInboxSince(id, undefined).length;
+    const originalLaunch = headlessBrokerHost.launch;
+    let launchCalls = 0;
+    headlessBrokerHost.launch = ((...args) => {
+        launchCalls++;
+        return originalLaunch(...args);
+    });
+    try {
+        const res = (await messageSendLeaf().run({ to: id, tier: 'deferred', body: 'a held note' }));
+        assert.equal(res['delivered'], true, 'the message is still delivered (appended), just not woken');
+        assert.equal(res['revived'], false, 'deferred never revives a dormant target');
+        assert.equal(res['guidance'], "Delivered — held for the target's next natural cycle; not revived.", 'guidance is truthful about the hold, not a claimed revive');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+    }
+    assert.equal(launchCalls, 0, 'a deferred delivery to a dormant target must never attempt a revive');
+    assert.equal(readInboxSince(id, undefined).length, inboxBefore + 1, 'the message is durably appended despite the hold');
+    const after = getNode(id);
+    assert.equal(after.status, 'idle', 'target left exactly where it was');
+    assert.equal(after.intent, 'idle-release', 'target left exactly where it was');
+});
+test('node message send --tier deferred to a terminal target (done/canceled — no natural next cycle) is rejected before any side effect', { timeout: 30_000 }, async () => {
+    for (const status of ['done', 'canceled']) {
+        const id = `terminal-${status}`;
+        createNode(node(id, { status, intent: null }));
+        const inboxBefore = readInboxSince(id, undefined).length;
+        const originalLaunch = headlessBrokerHost.launch;
+        let launchCalls = 0;
+        headlessBrokerHost.launch = ((...args) => {
+            launchCalls++;
+            return originalLaunch(...args);
+        });
+        try {
+            await assert.rejects(() => messageSendLeaf().run({ to: id, tier: 'deferred', body: 'never delivered' }), (e) => e instanceof InputError && e.payload.error === 'deferred_no_natural_cycle', `${status}: rejected with the terminal-edge error code`);
+        }
+        finally {
+            headlessBrokerHost.launch = originalLaunch;
+        }
+        assert.equal(launchCalls, 0, `${status}: a rejected deferred must never attempt a revive`);
+        assert.equal(readInboxSince(id, undefined).length, inboxBefore, `${status}: a rejected deferred must not append an inbox entry`);
+    }
+});
+// #343 third-fix-cycle review: the IMMEDIATE `--tier deferred` path had its
+// own, separate TOCTOU — a stale-snapshot check (`rejectDeferredWithoutNaturalCycle`)
+// ran well before the real appendInbox call, with several fallible side
+// effects (assertFinalizedForReopen/writeOutputSchema/appendSituationalContext/
+// commitReopen) in between. Fixed shape: the whole remaining sequence is now
+// one `deliverImmediate` closure, guarded end-to-end by `withFreshTerminalGuard`
+// when tier === 'deferred' — so the fresh check and every side effect
+// (appendInbox included) share ONE canvas write-lock transaction. This drives
+// that exact composed shape (the guard wrapping a body that appends an inbox
+// entry identical to what `deliverImmediate` builds) against a REAL rival
+// writer, proving the immediate path linearizes the same way the shared
+// primitive is proven to below.
+test('#343 (immediate path): withFreshTerminalGuard closes the TOCTOU for `node message send --tier deferred` immediate delivery too — a rival terminalization cannot land between the fresh check and the appendInbox it guards', { timeout: 30_000 }, () => {
+    const targetId = 'raceTargetImmediate';
+    createNode(node(targetId, { status: 'active', intent: null }));
+    const rival = new DatabaseSync(canvasDbPath());
+    rival.exec('PRAGMA busy_timeout = 0');
+    let rivalBlocked = false;
+    const outcome = withFreshTerminalGuard(targetId, hasNoNaturalCycle, () => {
+        // Same entry shape `deliverImmediate` builds for a body message — the
+        // guarded write this test's race must prove is atomic with the fresh read.
+        const entry = appendInbox(targetId, {
+            from: 'human',
+            tier: 'deferred',
+            kind: 'message',
+            label: 'raced note',
+            data: { body: 'raced note' },
+        });
+        // Attempted WHILE the guard holds its BEGIN IMMEDIATE write lock — a real
+        // concurrent finish/cancel/finalization racing the immediate delivery.
+        try {
+            rival.exec('BEGIN IMMEDIATE');
+            rival.prepare("UPDATE nodes SET status = 'done' WHERE node_id = ?").run(targetId);
+            rival.exec('COMMIT');
+        }
+        catch (e) {
+            rivalBlocked = /SQLITE_BUSY|database is locked/i.test(e.message);
+        }
+        return entry;
+    });
+    try {
+        assert.equal(rivalBlocked, true, 'the rival terminalization could not acquire the lock mid-guard — the immediate delivery genuinely serializes against it');
+        assert.equal(outcome.kind, 'ran', 'the guard read the pre-terminal state and completed the delivery, uncontested by the rival');
+        assert.equal(readInboxSince(targetId, undefined).length, 1, 'exactly the one guarded append landed');
+    }
+    finally {
+        try {
+            rival.exec('ROLLBACK');
+        }
+        catch { /* rival's own txn already closed above */ }
+        rival.close();
+    }
+});
+test('#343 (immediate path): `node message send --tier deferred --reopen` against an already-finalized target is still rejected with deferred_no_natural_cycle, and does NOT clear final_report (the reopen+deferred combo stays dead, now atomically)', { timeout: 30_000 }, async () => {
+    const id = 'reopenDeferredFinalized';
+    createNode(node(id));
+    // #343 final-review Minor: capture the AMBIENT prior value (not assumed
+    // undefined) and restore exactly in `finally`, deleting only when it was
+    // originally unset — so a focused/reordered run under an ambient managed-
+    // node id stays hermetic instead of losing it for every later test in the
+    // file (the suite-level `after` hook only restores the ORIGINAL module-load
+    // value, too late for tests that run between this one and teardown).
+    const priorNodeId = process.env['CRTR_NODE_ID'];
+    process.env['CRTR_NODE_ID'] = id;
+    let firstFinal;
+    try {
+        await pushFinal(id, 'round 1 verdict');
+        firstFinal = getNode(id)?.final_report;
+        assert.ok(firstFinal, 'the target is genuinely finalized before the raced retask');
+    }
+    finally {
+        if (priorNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = priorNodeId;
+    }
+    const inboxBefore = readInboxSince(id, undefined).length;
+    const originalLaunch = headlessBrokerHost.launch;
+    let launchCalls = 0;
+    headlessBrokerHost.launch = ((...args) => {
+        launchCalls++;
+        return originalLaunch(...args);
+    });
+    try {
+        await assert.rejects(() => messageSendLeaf().run({ to: id, tier: 'deferred', reopen: true, body: 'round 2 attempt' }), (e) => e instanceof InputError && e.payload.error === 'deferred_no_natural_cycle', '--reopen + --tier deferred immediate delivery is a semantically-impossible combo (final_report set => hasNoNaturalCycle true) and stays rejected');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+    }
+    assert.equal(launchCalls, 0, 'a rejected reopen+deferred retask must never attempt a revive');
+    assert.equal(readInboxSince(id, undefined).length, inboxBefore, 'a rejected reopen+deferred retask must not append an inbox entry');
+    assert.equal(getNode(id)?.final_report, firstFinal, 'the canonical final must survive untouched — assertFinalizedForReopen/commitReopen never ran on the rejected path');
+});
+// ---------------------------------------------------------------------------
+// The shared `withFreshTerminalGuard` primitive itself (Major, gh #341/#343
+// review). Every caller that needs a fresh terminal-status check and a
+// dependent write to share one transaction — the immediate deferred path
+// above, and any future arm/schedule doorway — rides this one function.
+// ---------------------------------------------------------------------------
+// #343 review, Major 1: the fresh terminal-status check and a guarded write
+// that depends on it must share ONE transaction, or a concurrent finish/
+// cancel/finalization can land in the gap and silently strand the write. This
+// drives the actual shared primitive (`withFreshTerminalGuard`) against a
+// REAL second connection to the same canvas.db — a genuine rival writer, not
+// a timing sleep or a poll loop — to prove the linearization deterministically:
+// while the guard holds its transaction, the rival's own write is provably
+// locked out (SQLITE_BUSY, immediate — `busy_timeout = 0` never waits), so
+// it cannot land between the guard's read and its write; and once the target
+// is ALREADY terminal before the guard ever opens its transaction, the
+// guarded body never runs at all.
+test('#343: withFreshTerminalGuard closes the check-then-write TOCTOU — a rival writer cannot land inside the guarded transaction, and an already-terminal target never reaches the guarded write', { timeout: 30_000 }, () => {
+    const targetId = 'raceTarget';
+    createNode(node(targetId, { status: 'active', intent: null }));
+    // A second, independent connection to the SAME canvas.db, bypassing the
+    // process-wide openDb() singleton — models a concurrent writer (another
+    // broker's finish/cancel/finalize) racing the guarded operation.
+    const rival = new DatabaseSync(canvasDbPath());
+    rival.exec('PRAGMA busy_timeout = 0'); // fail immediately instead of blocking this single thread
+    let rivalBlocked = false;
+    try {
+        const outcome = withFreshTerminalGuard(targetId, hasNoNaturalCycle, () => {
+            // Attempted WHILE the guard holds its BEGIN IMMEDIATE write lock — a
+            // real concurrent terminalization racing the guarded write.
+            try {
+                rival.exec('BEGIN IMMEDIATE');
+                rival.prepare("UPDATE nodes SET status = 'done' WHERE node_id = ?").run(targetId);
+                rival.exec('COMMIT');
+            }
+            catch (e) {
+                rivalBlocked = /SQLITE_BUSY|database is locked/i.test(e.message);
+            }
+            return 'armed';
+        });
+        assert.equal(rivalBlocked, true, 'the rival terminalization write could not acquire the lock mid-guard — the guard genuinely serializes against it');
+        assert.deepEqual(outcome, { kind: 'ran', result: 'armed' }, 'the guard read the pre-terminal state and completed its write, uncontested by the rival');
+    }
+    finally {
+        try {
+            rival.exec('ROLLBACK');
+        }
+        catch { /* rival's own txn already closed by its own catch above */ }
+        rival.close();
+    }
+    // The reverse linearization: a terminalization that already committed
+    // BEFORE the guard's fresh read runs — the guard must observe it and never
+    // invoke the guarded write at all.
+    setStatus(targetId, 'done');
+    let bodyRan = false;
+    const outcome2 = withFreshTerminalGuard(targetId, hasNoNaturalCycle, () => {
+        bodyRan = true;
+        return 'never';
+    });
+    assert.equal(bodyRan, false, 'a target already terminal when the guard reads must short-circuit — the guarded write must never run');
+    assert.equal(outcome2.kind, 'terminal', 'the guard reports the terminal outcome instead of a written result');
+});
+// #343 final-review Major: the fresh terminal guard must not treat a target
+// deleted between the caller's own selection and the guard's fresh read as
+// safe/body-run — a distinct 'missing' outcome, never conflated with
+// 'terminal' (no status/final_report to report) or a fabricated 'ran'.
+test("withFreshTerminalGuard reports 'missing' — never runs the guarded body — for a target deleted before the guard's fresh read (no orphan node dir/inbox is created)", { timeout: 30_000 }, () => {
+    const targetId = 'deletedBeforeGuard';
+    createNode(node(targetId, { status: 'active', intent: null }));
+    deleteNode(targetId); // row + dir gone — models a concurrent deletion that already committed
+    assert.equal(existsSync(nodeDir(targetId)), false, 'sanity: the target dir is genuinely gone before the guard ever runs');
+    let bodyRan = false;
+    const outcome = withFreshTerminalGuard(targetId, hasNoNaturalCycle, () => {
+        bodyRan = true;
+        return appendInbox(targetId, { from: 'human', tier: 'deferred', kind: 'message', label: 'orphan', data: { body: 'orphan' } });
+    });
+    assert.equal(bodyRan, false, "a missing target must NEVER run the guarded body — 'missing' must not be treated as safe/empty-and-runnable");
+    assert.deepEqual(outcome, { kind: 'missing' }, "the guard reports a distinct 'missing' outcome, not 'terminal' (nothing to report) and not a fabricated 'ran'");
+    assert.equal(existsSync(nodeDir(targetId)), false, 'the guarded appendInbox never ran, so no orphan node dir was recreated for the deleted target');
+});
+// ---------------------------------------------------------------------------
+// Daemon second pass — crtrd.ts's idle-release inbox loop
+// ---------------------------------------------------------------------------
+// Deterministic: `headlessBrokerHost.launch` is fully STUBBED (never delegates
+// to the real launcher) so `reviveNode` cannot spawn a real detached broker/pi
+// process as a side effect of this decision test — the stubbed HostHandle's
+// `exited` promise never settles and its pid is a fixed sentinel, so the only
+// thing under test is the daemon's revive-or-hold DECISION (cycles/status/
+// intent), never a real engine's boot. Genuine post-revive DELIVERY (both
+// entries actually reaching the target, no duplicate/loss, cursor settling) is
+// proven separately below through the real inbox watcher.
+test('daemon second pass: a deferred-only unseen set never wakes an idle-released node; a later non-deferred entry wakes it (decision only — real delivery is proven separately below)', { timeout: 30_000 }, async () => {
+    const id = 'idleReleaseDeferredDaemon';
+    createNode(node(id, { status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: null, cwd: home }));
+    const baseline = readCursor(id); // undefined — the real watcher never ran here
+    const originalLaunch = headlessBrokerHost.launch;
+    let launchCalls = 0;
+    headlessBrokerHost.launch = (() => {
+        launchCalls++;
+        return { pid: 0x7ffffffe, exited: new Promise(() => { }) };
+    });
+    let deferredEntry;
+    let normalEntry;
+    try {
+        deferredEntry = appendInbox(id, {
+            from: 'human',
+            tier: 'deferred',
+            kind: 'message',
+            label: 'deferred note',
+            data: { body: 'deferred note' },
+        });
+        await superviseTick();
+        {
+            const after = getNode(id);
+            assert.equal(after.cycles ?? 0, 0, 'a deferred-only unseen entry never revives an idle-released node');
+            assert.equal(after.status, 'idle', 'target left idle');
+            assert.equal(after.intent, 'idle-release', 'target left idle-release');
+            assert.equal(launchCalls, 0, 'no launch attempt for a deferred-only unseen set');
+        }
+        assert.equal(readCursor(id), baseline, 'the cursor is untouched while the entry is held (nothing consumed it)');
+        normalEntry = appendInbox(id, {
+            from: 'human',
+            tier: 'normal',
+            kind: 'message',
+            label: 'go now',
+            data: { body: 'go now' },
+        });
+        await superviseTick();
+        {
+            const after = getNode(id);
+            assert.equal(after.cycles ?? 0, 1, 'a non-deferred unseen entry still wakes the idle-released node exactly as before');
+            assert.equal(after.status, 'active', 'revived');
+            assert.equal(after.intent ?? null, null, 'intent cleared by the revive');
+            assert.equal(launchCalls, 1, 'exactly one (stubbed) launch attempt for the wake-worthy entry');
+        }
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+    }
+    // No loss: BOTH the previously-held deferred entry and the new one are still
+    // past the (daemon-never-advances) cursor, ready for the real inbox watcher's
+    // normal flush to deliver together on this same revived cycle.
+    const unseen = readInboxSince(id, baseline).map((e) => e.entry_id);
+    assert.deepEqual(unseen, [deferredEntry.entry_id, normalEntry.entry_id], 'neither entry was dropped or skipped by the daemon');
+});
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        sendMessage() { },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+test('the real inbox watcher holds a deferred entry alone, then delivers it TOGETHER with a later normal entry with no duplicate/loss, and the durable cursor settles past both (gh #341 review: genuine delivery, not just the daemon decision)', { timeout: 30_000 }, async () => {
+    const id = 'watcherDeferredThenNormal';
+    createNode(node(id, { status: 'idle', intent: null }));
+    const TICK_MS = 20;
+    const DEBOUNCE_MS = 25;
+    const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 30;
+    const origTick = process.env['CRTR_WATCHER_TICK_MS'];
+    const origDebounce = process.env['CRTR_WATCHER_DEBOUNCE_MS'];
+    const origNodeId = process.env['CRTR_NODE_ID'];
+    process.env['CRTR_WATCHER_TICK_MS'] = String(TICK_MS);
+    process.env['CRTR_WATCHER_DEBOUNCE_MS'] = String(DEBOUNCE_MS);
+    process.env['CRTR_NODE_ID'] = id;
+    const pi = makeFakePi();
+    let dispose;
+    try {
+        dispose = registerCanvasInboxWatcher(pi);
+        // session_start is the real lifecycle gate that arms the watcher's poll
+        // interval and initial tick (see canvas-inbox-watcher.ts) — registration
+        // alone only wires up handlers.
+        pi.fire('session_start', { type: 'session_start' }, undefined);
+        // No agent_start fired — the watcher treats the node as idle, same as the
+        // idle-released daemon scenario above.
+        await wait(TICK_MS + 60);
+        const deferredEntry = appendInbox(id, {
+            from: 'human',
+            tier: 'deferred',
+            kind: 'message',
+            label: 'deferred note',
+            data: { body: 'deferred note' },
+        });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 0, 'a deferred-only idle buffer is held by the real watcher, not delivered alone');
+        assert.equal(readCursor(id), undefined, 'nothing committed while held');
+        const normalEntry = appendInbox(id, {
+            from: 'human',
+            tier: 'normal',
+            kind: 'message',
+            label: 'go now',
+            data: { body: 'go now' },
+        });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'both entries are delivered together in ONE coalesced turn once a non-deferred entry joins the batch');
+        assert.match(pi.injected[0].content, /deferred note/, 'the previously-held deferred entry rides along — not lost');
+        assert.match(pi.injected[0].content, /go now/, 'the new normal entry is in the same digest — not duplicated into a second turn');
+        assert.equal(pi.injected[0].deliverAs, undefined, 'idle delivery triggers a fresh turn, no deliverAs');
+        // Idle-path delivery hands off on the void send but only COMMITS the
+        // durable cursor at agent_settled (never on the fire-and-forget send
+        // itself) — settle the turn and prove the cursor lands past BOTH delivered
+        // entries, not just the earlier (previously-held) one.
+        pi.fire('agent_settled', { type: 'agent_settled' }, { isIdle: () => true, hasPendingMessages: () => false });
+        assert.equal(readCursor(id), normalEntry.entry_id, 'the durable cursor settles past BOTH delivered entries, at the final physical entry');
+        assert.notEqual(readCursor(id), deferredEntry.entry_id, 'not a partial commit stuck at the earlier entry');
+    }
+    finally {
+        dispose?.();
+        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;
+        if (origNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = origNodeId;
+    }
+});

package/dist/core/__tests__/events-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/events-contract.test.js

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { buildEnvelope, serializeEventRecord, validateOperationId } from '../events/index.js';
+import { readLogSnapshot } from '../events/read.js';
+test('event serialization bounds cyclic Unicode fields with truncation metadata', () => {
+    const cyclic = {};
+    cyclic.self = cyclic;
+    const serialized = serializeEventRecord(buildEnvelope({
+        level: 'error',
+        event: 'contract.serialization',
+        component: 'daemon',
+        fields: {
+            cyclic,
+            huge: '🍞'.repeat(40_000),
+            array: Array.from({ length: 100 }, (_, index) => ({ index, value: 'x'.repeat(5_000) })),
+        },
+    }));
+    assert.ok(Buffer.byteLength(serialized, 'utf8') + 1 <= 65_536);
+    assert.ok(!serialized.includes('\n'));
+    const record = JSON.parse(serialized);
+    assert.equal(record.record_truncated, true);
+    assert.ok((record.original_bytes ?? 0) > 0);
+    assert.ok((record.dropped_fields_count ?? 0) > 0);
+});
+test('a value-only truncated record with dropped_fields_count 0 survives readLogSnapshot', () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-events-contract-'));
+    const priorHome = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+    try {
+        const serialized = serializeEventRecord(buildEnvelope({
+            level: 'info',
+            event: 'contract.value_truncation',
+            component: 'daemon',
+            fields: { huge: 'x'.repeat(5_000) },
+        }));
+        const record = JSON.parse(serialized);
+        assert.equal(record.record_truncated, true);
+        assert.equal(record.dropped_fields_count, 0);
+        assert.ok((record.original_bytes ?? 0) > 0);
+        assert.ok(Buffer.byteLength(serialized, 'utf8') + 1 <= 65_536);
+        writeFileSync(join(home, 'crtrd.log'), `${serialized}\n`);
+        const snapshot = readLogSnapshot({}, false);
+        assert.equal(snapshot.invalidCanonicalLines, 0);
+        assert.equal(snapshot.items.length, 1);
+        const [item] = snapshot.items;
+        assert.equal(item?.kind, 'event');
+        if (item?.kind !== 'event')
+            throw new Error('expected canonical event item');
+        assert.equal(item.envelope.record_truncated, true);
+        assert.equal(item.envelope.dropped_fields_count, 0);
+        assert.ok((item.envelope.original_bytes ?? 0) > 0);
+    }
+    finally {
+        if (priorHome === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = priorHome;
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('operation IDs are exactly non-zero lowercase 32-character hexadecimal', () => {
+    assert.equal(validateOperationId('0123456789abcdef0123456789abcdef'), '0123456789abcdef0123456789abcdef');
+    for (const invalid of [
+        '00000000000000000000000000000000',
+        '0123456789ABCDEF0123456789ABCDEF',
+        '0123456789abcdef0123456789abcdeg',
+        '0123456789abcdef0123456789abcde',
+        '0123456789abcdef0123456789abcdef0',
+        '',
+        42,
+    ])
+        assert.throws(() => validateOperationId(invalid));
+});

package/dist/core/__tests__/fault-classifier.test.d.ts

@@ -0,0 +1 @@
+export {};