@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/__tests__/integration/deferred-no-wake.test.d.ts

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

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

@@ -1,610 +0,0 @@
-// Run with: npm run test:integration
-//
-// 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
-//       delivery is ever dropped or acknowledged before settlement).
-//
-// (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, setFrozen, setStatus, subscribe, withFreshTerminalGuard } from '../../canvas/canvas.js';
-import { hasNoNaturalCycle } from '../../runtime/revive-all.js';
-import { canvasDbPath, nodeDir, apiSocketPath } from '../../canvas/paths.js';
-import { closeDb, migrate, openDb } from '../../canvas/db.js';
-import { recordExecutionPid } from '../../canvas/executions.js';
-import { closeScopedStores } from '../../scoped-state/db.js';
-import { initializeFreshScopedStore } from '../../scoped-state/migrate.js';
-import { userScopeRoot } from '../../scope.js';
-import { createApiServer } from '../../../daemon/api/server.js';
-import { CrtrClient } from '../../../api/index.js';
-import { BROKER_IDLE_TURN_START } from '../../runtime/broker/held-deferred-inbox.js';
-import { registerNode } from '../../../commands/node.js';
-import { pushFinal } from '../../feed/feed.js';
-import { InputError } from '../../io.js';
-import { headlessBrokerHost } from '../../runtime/host.js';
-import { enqueueNodeMail } from '../../feed/messages.js';
-import { acknowledgedNodeMailCount } from '../../canvas/deliveries.js';
-import { beginExecution } from '../../canvas/executions.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'];
-const prevHome = process.env['HOME'];
-// 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 inboxRows(nodeId) {
-    return openDb().prepare(`SELECT m.message_id, d.urgency, d.state, d.acknowledged_at FROM deliveries d JOIN messages m ON m.message_id = d.message_id
-      WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND d.canceled_at IS NULL ORDER BY m.seq`).all(nodeId).map((row) => ({
-        messageId: row.message_id,
-        tier: row.urgency,
-        state: row.state,
-        acknowledgedAt: row.acknowledged_at,
-    }));
-}
-function sendMail(nodeId, tier, body, senderNodeId = 'human') {
-    return enqueueNodeMail(nodeId, {
-        ...(senderNodeId === null ? {} : { senderNodeId }),
-        kind: 'message',
-        label: body,
-        bodyJson: { body },
-        urgency: tier,
-        wake: 1,
-    });
-}
-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,
-    };
-}
-function createFixtureNode(meta) {
-    createNode(meta);
-    if (meta.pi_pid == null)
-        return null;
-    const executionId = beginExecution(meta.node_id, { daemonEpoch: 'test-epoch' });
-    recordExecutionPid(executionId, meta.node_id, meta.pi_pid);
-    return executionId;
-}
-/** 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['HOME'] = home;
-    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();
-    closeScopedStores();
-    rmSync(home, { recursive: true, force: true });
-    mkdirSync(home, { recursive: true });
-    migrate(openDb());
-    initializeFreshScopedStore({ kind: 'user', root: userScopeRoot() });
-    // 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();
-    closeScopedStores();
-});
-after(() => {
-    closeDb();
-    closeScopedStores();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-    if (prevHome === undefined)
-        delete process.env['HOME'];
-    else
-        process.env['HOME'] = prevHome;
-    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';
-    // Resident: the hold is what a target with a real later cycle gets. A
-    // terminal target takes no such cycle, so its mail is raised to the steering
-    // tier instead (locked by the next test).
-    createNode(node(id, { lifecycle: 'resident', status: 'idle', intent: 'idle-release' }));
-    const inboxBefore = inboxRows(id).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['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(inboxRows(id).length, inboxBefore + 1, 'the SQL delivery is durable 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-lifecycle target is raised to the steering tier and wakes it', { timeout: 30_000 }, async () => {
-    const id = 'terminalLifecycleTarget';
-    createFixtureNode(node(id, { status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: null, cwd: home }));
-    // Fully stubbed (never delegates): the point is that the raised entry DOES
-    // attempt the wake, so a real detached broker must not be spawned to prove it.
-    const originalLaunch = headlessBrokerHost.launch;
-    let launchCalls = 0;
-    headlessBrokerHost.launch = (() => {
-        launchCalls++;
-        return { pid: 0x7ffffffe, exited: new Promise(() => { }) };
-    });
-    let res;
-    try {
-        res = (await messageSendLeaf().run({ to: id, tier: 'deferred', body: 'not held' }));
-    }
-    finally {
-        headlessBrokerHost.launch = originalLaunch;
-    }
-    const entries = inboxRows(id);
-    assert.equal(entries.length, 1, 'the SQL delivery is durable');
-    assert.equal(entries[0].tier, 'urgent', 'a terminal target takes no later cycle, so the delivery is raised to the steering tier');
-    assert.equal(launchCalls, 1, 'the raised entry wakes the dormant terminal target instead of waiting for a cycle it never takes');
-    assert.equal(res['revived'], true, 'the send reports the wake it actually performed');
-});
-test('node message send --tier deferred rejects ordinary terminal targets but accepts a frozen terminal target with a thaw cycle owed', { timeout: 30_000 }, async () => {
-    for (const status of ['done', 'canceled']) {
-        const id = `terminal-${status}`;
-        createNode(node(id, { status, intent: null }));
-        const inboxBefore = inboxRows(id).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(inboxRows(id).length, inboxBefore, `${status}: a rejected deferred must not create a SQL delivery`);
-    }
-    const frozenId = 'terminal-frozen';
-    createNode(node(frozenId, {
-        lifecycle: 'resident',
-        status: 'done',
-        intent: 'parked',
-    }));
-    setFrozen(frozenId, new Date().toISOString());
-    const inboxBefore = inboxRows(frozenId).length;
-    const result = await messageSendLeaf().run({ to: frozenId, tier: 'deferred', body: 'held for thaw' });
-    assert.equal(result['guidance'], "Delivered — held for the target's next natural cycle; not revived.", 'a frozen terminal row still has a thaw cycle');
-    assert.equal(result['revived'], false, 'deferred mail waits for the thaw without launching');
-    assert.equal(inboxRows(frozenId).length, inboxBefore + 1, 'the deferred SQL delivery is durable');
-});
-// #343 third-fix-cycle review: the IMMEDIATE `--tier deferred` path had its
-// own, separate TOCTOU — a stale-snapshot check (`rejectDeferredWithoutNaturalCycle`)
-// ran before the SQL delivery write, with several fallible side effects
-// (assertFinalizedForReopen/writeOutputSchema/appendSituationalContext/
-// commitReopen) in between. The guarded closure keeps the fresh check and
-// delivery write in one canvas transaction. This drives that shape against a
-// real rival writer.
-test('#343 (immediate path): withFreshTerminalGuard closes the TOCTOU for `node message send --tier deferred` — a rival terminalization cannot land between the fresh check and the SQL delivery 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 = sendMail(targetId, 'deferred', '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(inboxRows(targetId).length, 1, 'exactly the one guarded SQL delivery 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 = inboxRows(id).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(inboxRows(id).length, inboxBefore, 'a rejected reopen+deferred retask must not create a SQL delivery');
-    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 sendMail(targetId, 'deferred', '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 SQL delivery 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, SQL acknowledgement) 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';
-    createFixtureNode(node(id, { lifecycle: 'resident', status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: null, cwd: home }));
-    // A live child is a standing obligation, which is what keeps this row
-    // idle-released across the tick. Without one it would settle into its park
-    // instead (the resident carve-out, locked in the next test) and the wake half
-    // below would be measuring a parked row.
-    createNode(node(`${id}Child`, { status: 'active' }));
-    subscribe(id, `${id}Child`);
-    const baselineAcknowledged = acknowledgedNodeMailCount(id);
-    const originalLaunch = headlessBrokerHost.launch;
-    let launchCalls = 0;
-    headlessBrokerHost.launch = (() => {
-        launchCalls++;
-        return { pid: 0x7ffffffe, exited: new Promise(() => { }) };
-    });
-    let deferredEntry;
-    let normalEntry;
-    try {
-        deferredEntry = sendMail(id, 'deferred', '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(acknowledgedNodeMailCount(id), baselineAcknowledged, 'the held delivery remains unacknowledged');
-        normalEntry = sendMail(id, 'normal', '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 independent SQL obligations remain pending for the revived execution.
-    assert.deepEqual(inboxRows(id).filter((row) => row.state === 'pending').map((row) => row.messageId), [deferredEntry.messageId, normalEntry.messageId], 'neither delivery was dropped or acknowledged by the daemon');
-});
-test('the lifecycle tick parks a resident holding deferred-only mail — mail that never wakes it must not hold it idle forever either', { timeout: 30_000 }, async () => {
-    const id = 'residentDeferredOnly';
-    createFixtureNode(node(id, { lifecycle: 'resident', status: 'idle', intent: 'idle-release', pi_pid: deadPid(), pi_session_id: null, cwd: home }));
-    const originalLaunch = headlessBrokerHost.launch;
-    let launchCalls = 0;
-    headlessBrokerHost.launch = (() => {
-        launchCalls++;
-        return { pid: 0x7ffffffe, exited: new Promise(() => { }) };
-    });
-    try {
-        const held = enqueueNodeMail(id, {
-            kind: 'message',
-            label: 'Child done — auto-done notice',
-            bodyJson: { reason: 'child-auto-done' },
-            urgency: 'deferred',
-            wake: 1,
-        });
-        await superviseTick();
-        const after = getNode(id);
-        assert.equal(after.status, 'done', 'the resident settles into its park instead of sitting idle behind mail that cannot wake it');
-        assert.equal(after.intent, 'parked', 'parked, not released');
-        assert.equal(launchCalls, 0, 'settling quietly never launches an engine');
-        assert.deepEqual(inboxRows(id).filter((row) => row.state === 'pending').map((row) => row.messageId), [held.messageId], 'the held delivery survives the park, ready for the cycle that reopens the conversation');
-    }
-    finally {
-        headlessBrokerHost.launch = originalLaunch;
-    }
-});
-function makeFakePi() {
-    const handlers = {};
-    const pi = {
-        injected: [],
-        on(e, h) { handlers[e] = h; },
-        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
-        sendMessage() { },
-        async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
-    };
-    globalThis[BROKER_IDLE_TURN_START] = (content) => pi.sendUserMessage(content);
-    return pi;
-}
-const wait = (ms) => new Promise((r) => setTimeout(r, ms));
-async function waitUntil(check, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (!check()) {
-        if (Date.now() >= deadline)
-            throw new Error('timed out waiting for watcher deliveries');
-        await wait(5);
-    }
-}
-test('the real inbox watcher holds a deferred delivery alone, then delivers it TOGETHER with a later normal delivery with no duplicate/loss, and acknowledges both at settlement (gh #341 review: genuine delivery, not just the daemon decision)', { timeout: 30_000 }, async () => {
-    const id = 'watcherDeferredThenNormal';
-    // The watcher claims mail only for its current execution. This fake Pi runs
-    // in this test process, so its fabricated node must carry that execution just
-    // like a real launched node does.
-    createNode(node(id, { description: 'deferred inbox watcher fixture', lifecycle: 'resident', status: 'idle', intent: null }));
-    const executionId = beginExecution(id, { daemonEpoch: 'test' });
-    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'];
-    const origExecutionId = process.env['CRTR_EXECUTION_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;
-    process.env['CRTR_EXECUTION_ID'] = executionId;
-    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.
-        await 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 = sendMail(id, 'deferred', '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(acknowledgedNodeMailCount(id), 0, 'nothing is acknowledged while held');
-        const normalEntry = sendMail(id, 'normal', 'go now');
-        await waitUntil(() => pi.injected.length === 2, SETTLE_MS + TICK_MS * 12);
-        // Two direct human entries are two verbatim deliveries — one message per
-        // entry, physical order preserved, one visible send per watcher cycle.
-        assert.equal(pi.injected.length, 2, 'both entries are delivered once a non-deferred entry joins the batch — each human entry as its own verbatim message');
-        assert.match(pi.injected[0].content, /deferred note/, 'the previously-held deferred entry is delivered first — not lost');
-        assert.doesNotMatch(pi.injected[0].content, /go now/, 'the deliveries are separate messages, not one concatenation');
-        assert.match(pi.injected[1].content, /go now/, 'the new normal entry follows in its own message — not duplicated');
-        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 acknowledges the
-        // SQL deliveries at agent_settled (never on the fire-and-forget send
-        // itself) — settle the turn and prove both delivered obligations settle.
-        await pi.fire('agent_settled', { type: 'agent_settled' }, { isIdle: () => true, hasPendingMessages: () => false });
-        assert.equal(acknowledgedNodeMailCount(id), 2, 'agent_settled acknowledges both delivered SQL obligations');
-        assert.ok(inboxRows(id).every((row) => row.acknowledgedAt !== null), 'neither delivery is left in a partial handoff');
-        assert.notEqual(normalEntry.messageId, deferredEntry.messageId, 'the batch retains distinct message identities');
-    }
-    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;
-        if (origExecutionId === undefined)
-            delete process.env['CRTR_EXECUTION_ID'];
-        else
-            process.env['CRTR_EXECUTION_ID'] = origExecutionId;
-    }
-});

package/dist/core/__tests__/integration/flagship-lifecycle.test.d.ts

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