@crouton-kit/crouter 0.3.82 → 0.3.84

package/dist/commands/sys/setup.js

@@ -41,7 +41,7 @@ const theme = {
         return getMarkdownTheme().bold(text);
     },
 };
-import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, renderSetupStaticInstructions, resolveExaKeyPath, resolveComposioKeyPath, detectExaKey, detectComposioKey, SetupKeybindingsDraft, } from './setup-core.js';
+import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, reconcileInboxFrontDoor, renderSetupStaticInstructions, resolveExaKeyPath, resolveComposioKeyPath, detectExaKey, detectComposioKey, SetupKeybindingsDraft, } from './setup-core.js';
 function wrapText(text, width) {
     const clean = text.trim();
     if (clean === '')
@@ -1299,6 +1299,14 @@ export class SetupWizard {
 }
 async function runSetup() {
     const state = buildSetupInitialState();
+    // Front-door reconciliation: invoking `crtr sys setup` — TTY or not —
+    // registers known nodes' interaction roots so resolved tickets can call back
+    // into the asking node. Best-effort + idempotent, so it is safe to run on
+    // every invocation regardless of whether the wizard is opened, canceled, or
+    // submitted (the post-submission call re-runs it harmlessly). The inbox-toggle
+    // tmux key is a crouter keybinding, installed by the catalog/save path through
+    // installTmuxBindings() like every other binding — not reconciled here.
+    reconcileInboxFrontDoor();
     if (!process.stdout.isTTY) {
         process.stdout.write(renderSetupStaticInstructions(state));
         return;
@@ -1397,6 +1405,7 @@ export const sysSetupLeaf = defineLeaf({
             'Collects companion package installs, system dependency installs, API keys, and sparse user overrides for crouter-owned keybindings across the remaining tabs.',
             'Saves validated keybinding changes atomically in the user config and refreshes crouter-owned tmux bindings without overwriting occupied user keys.',
             'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key and COMPOSIO_API_KEY to ~/.crouter/composio.key when provided, and prints a summary.',
+            'On every invocation (best-effort, idempotent), registers known nodes\' interaction roots so resolved tickets can call back into the asking node. The inbox popup toggle is a crouter-owned keybinding, edited on the keybindings tab and installed through the catalog/save path alongside every other tmux binding.',
         ],
     },
     run: async () => {

package/dist/core/__tests__/boot.test.js

@@ -17,15 +17,22 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createNode, getRow, recordPid } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
-import { bootChanged, reconcileBootLiveness } from '../canvas/boot.js';
+import { createNode, getRow, recordPid, migrateLegacyPidIdentities } from '../canvas/canvas.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { bootChanged, bootProvenSame, reconcileBootLiveness, reconcileAndMigrateBoot, } from '../canvas/boot.js';
 let home;
 /** Build a BootIdentity for injection. `bootId` null models the non-Linux
  *  fallback (wall-clock window); a string models the exact kernel boot_id. */
 function ident(bootId, bootEpochMs) {
     return { bootId, bootEpochMs };
 }
+const BOOT_A = '4b0c1d2e-3f40-4152-8637-a1b2c3d4e5f6';
+/** Force a row's recorded pid + identity baseline directly (recordPid derives
+ *  the identity from the real `ps`, which can't produce a controlled legacy
+ *  `lstart#ticks` value on a non-Linux test host). */
+function setPidIdentity(id, pid, identity) {
+    openDb().prepare('UPDATE nodes SET pi_pid = ?, pi_pid_identity = ? WHERE node_id = ?').run(pid, identity, id);
+}
 function node(id, over = {}) {
     return {
         node_id: id,
@@ -80,12 +87,60 @@ test('bootChanged: wall-clock fallback (no boot_id) — epochs far apart are a D
 // ---------------------------------------------------------------------------
 // reconcileBootLiveness — the impure sweep against a real canvas.db
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// migrateLegacyPidIdentities — one-time in-place format migration at startup
+// ---------------------------------------------------------------------------
+test('migrateLegacyPidIdentities: a live legacy lstart#ticks broker is re-recorded to <bootId>#<ticks>', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459'); // legacy baseline
+    // The pid still names the same live process; its CURRENT identity on this
+    // (now boot_id-capable) platform reads bootId#ticks with the SAME ticks.
+    const result = migrateLegacyPidIdentities((pid) => (pid === 111 ? `${BOOT_A}#53459` : undefined));
+    assert.deepEqual(result.migrated, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#53459`, 'legacy row completed to boot-scoped format');
+    assert.equal(getRow('n1')?.pi_pid, 111, 'the pid itself is untouched');
+});
+test('migrateLegacyPidIdentities: a legacy row whose pid is GONE is left to normal liveness handling', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    const result = migrateLegacyPidIdentities(() => undefined); // pid gone / probe failed
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'untouched — liveness handles it');
+});
+test('migrateLegacyPidIdentities: a REUSED pid (different ticks) is NOT re-recorded', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    // The pid now names a DIFFERENT process (different jiffies) — no match.
+    const result = migrateLegacyPidIdentities(() => `${BOOT_A}#99999`);
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'reused pid left for liveness to clear');
+});
+test('migrateLegacyPidIdentities: an already boot-scoped row is skipped (not legacy)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, `${BOOT_A}#53459`); // already new-format
+    let captured = false;
+    const result = migrateLegacyPidIdentities(() => {
+        captured = true;
+        return `${BOOT_A}#53459`;
+    });
+    assert.deepEqual(result.migrated, []);
+    assert.equal(captured, false, 'a non-legacy row is filtered out before any ps probe');
+});
+test('migrateLegacyPidIdentities: no readable boot_id (current identity still legacy) leaves the row untouched', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, 'Sat Jul 11 17:51:45 2026#53459');
+    // Platform still composes legacy-shaped identities (no boot_id) — nothing to
+    // upgrade to; the legacy compare lane legitimately stays in play.
+    const result = migrateLegacyPidIdentities(() => 'Sun Jul 12 09:00:00 2026#53459');
+    assert.deepEqual(result.migrated, []);
+    assert.equal(getRow('n1')?.pi_pid_identity, 'Sat Jul 11 17:51:45 2026#53459', 'no boot_id → not migrated');
+});
 test('reconcileBootLiveness: first-ever call seeds the marker and clears nothing', () => {
     const m = node('n1');
     createNode(m);
     recordPid('n1', 12345);
     const result = reconcileBootLiveness(ident('boot-A', 1_000_000));
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: false });
     assert.equal(getRow('n1')?.pi_pid, 12345, 'a first-ever run never clears an existing pid');
 });
 test('reconcileBootLiveness: same boot (same boot_id) leaves pids untouched — MUST NOT weaken the normal daemon-restart case', () => {
@@ -94,7 +149,7 @@ test('reconcileBootLiveness: same boot (same boot_id) leaves pids untouched —
     recordPid('n1', 12345);
     reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed
     const result = reconcileBootLiveness(ident('boot-A', 1_000_000 + 3_000)); // 3s later, same boot
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: true });
     assert.equal(getRow('n1')?.pi_pid, 12345, 'a live pid on the same boot is never cleared');
 });
 test('reconcileBootLiveness: a boot change clears every recorded pid, regardless of status', () => {
@@ -135,6 +190,86 @@ test('reconcileBootLiveness: after reconciling, the SAME boot no longer re-trigg
     reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000)); // boot change → clears + persists boot B
     recordPid('n1', 999); // a fresh broker re-records its pid post-revive
     const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000 + 2_000)); // still boot B, 2s later
-    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.deepEqual(result, { changed: false, cleared: [], sameBootProven: true });
     assert.equal(getRow('n1')?.pi_pid, 999, 'a pid recorded AFTER reconciliation, within the same boot, is never touched');
 });
+// ---------------------------------------------------------------------------
+// bootProvenSame + the daemon migration gate (Major-1 regression)
+//
+// The legacy identity migration blesses a recorded pid as a current-boot
+// process on a bare ticks match, so it may run ONLY when same-boot provenance
+// is POSITIVELY proven (exact boot_id equal on both sides). `!bootChanged` is
+// NOT that proof — it is also true with no/malformed marker or the wall-clock
+// epoch fallback, where an unrelated cross-boot process can collide on
+// pid+ticks and be permanently baptized.
+// ---------------------------------------------------------------------------
+test('bootProvenSame: exact equal boot_id on both sides is proof', () => {
+    assert.equal(bootProvenSame(ident('boot-A', 2_000), ident('boot-A', 1_000)), true);
+});
+test('bootProvenSame: no history is NOT proof (absent/malformed marker)', () => {
+    assert.equal(bootProvenSame(ident('boot-A', 1_000), null), false);
+});
+test('bootProvenSame: a missing boot_id on EITHER side is NOT proof (epoch fallback)', () => {
+    assert.equal(bootProvenSame(ident(null, 1_000), ident('boot-A', 1_000)), false, 'current lacks boot_id');
+    assert.equal(bootProvenSame(ident('boot-A', 1_000), ident(null, 1_000)), false, 'known lacks boot_id');
+    assert.equal(bootProvenSame(ident(null, 1_000), ident(null, 1_000)), false, 'both lack boot_id');
+});
+test('bootProvenSame: a different boot_id is not proof (it is a change)', () => {
+    assert.equal(bootProvenSame(ident('boot-B', 1_000), ident('boot-A', 1_000)), false);
+});
+// Drive the ACTUAL production startup composition (reconcile, then gate the
+// migration on proven same-boot provenance) rather than a test-side copy, so a
+// revert that inverts/drops the gate or reorders migration ahead of
+// reconciliation is caught here. `runDaemon` calls this same helper.
+function daemonBootStartup(current, captureIdentity) {
+    return reconcileAndMigrateBoot(migrateLegacyPidIdentities, current, captureIdentity);
+}
+const LEGACY = 'Sat Jul 11 17:51:45 2026#53459';
+test('migration gate: a cross-boot equal-ticks legacy row is NOT migrated when the marker is ABSENT (first-ever startup)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    // No marker yet. A current-boot stranger process happens to hold pid 111 with
+    // the same ticks — an equal-ticks collision that would falsely migrate if the
+    // sweep ran. It must NOT: provenance is unproven.
+    const result = daemonBootStartup(ident(BOOT_A, 1_000_000), () => `${BOOT_A}#53459`);
+    assert.deepEqual(result.migrated, [], 'no marker → unproven → migration skipped');
+    assert.equal(getRow('n1')?.pi_pid_identity, LEGACY, 'the stranger is NOT baptized as the recorded process');
+});
+test('migration gate: a cross-boot equal-ticks legacy row is NOT migrated under the epoch fallback (no boot_id)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    reconcileBootLiveness(ident(null, 1_000_000)); // seed a no-boot_id marker
+    // A transient current boot_id read failure: reconcile sees null on both sides,
+    // the epochs are within tolerance so no change is DETECTED, but same-boot is
+    // NOT PROVEN. A cross-boot pid+ticks collision must not be migrated.
+    const result = daemonBootStartup(ident(null, 1_000_000 + 5_000), () => `${BOOT_A}#53459`);
+    assert.deepEqual(result.migrated, [], 'epoch fallback → unproven → migration skipped');
+    assert.equal(getRow('n1')?.pi_pid_identity, LEGACY, 'not migrated on an unproven boot');
+});
+test('migration gate: a legacy row IS migrated when same-boot provenance is PROVEN (exact boot_id match)', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    reconcileBootLiveness(ident(BOOT_A, 1_000_000)); // seed an exact-boot_id marker
+    // Same boot proven (boot_id equal on both sides); pid 111 still names the same
+    // live process (matching ticks) — the in-place upgrade completes.
+    const result = daemonBootStartup(ident(BOOT_A, 1_000_000 + 3_000), (pid) => pid === 111 ? `${BOOT_A}#53459` : undefined);
+    assert.deepEqual(result.migrated, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#53459`, 'proven same boot → migrated in place');
+});
+test('migrateLegacyPidIdentities CAS: a concurrent re-record between probe and update is not clobbered', () => {
+    createNode(node('n1'));
+    setPidIdentity('n1', 111, LEGACY);
+    // The capture models the old broker still probing as its live legacy self,
+    // but a concurrent revive atomically re-records a FRESH (pid, identity) pair
+    // before the sweep's compare-and-swap update lands.
+    const result = migrateLegacyPidIdentities((pid) => {
+        if (pid === 111) {
+            setPidIdentity('n1', 222, `${BOOT_A}#77777`); // concurrent revive wins the row
+            return `${BOOT_A}#53459`; // stale probe result for the OLD pid
+        }
+        return undefined;
+    });
+    assert.deepEqual(result.migrated, [], 'CAS matched zero rows — no migration counted');
+    assert.equal(getRow('n1')?.pi_pid, 222, 'the concurrent revive pid stands');
+    assert.equal(getRow('n1')?.pi_pid_identity, `${BOOT_A}#77777`, 'the fresh identity is NOT overwritten by the stale one');
+});

package/dist/core/__tests__/human-deliver-e2e.test.js

@@ -0,0 +1,95 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-deliver-e2e.test.ts
+//
+// M2 e2e — drive a REAL completion through the REGISTERED crouter handler as a
+// SUBPROCESS, not in-process. This exercises the whole cutover seam that the
+// in-process human-deliver.test.ts stubs out with a benign handler:
+//   registerInboxRoot(crouterDeliverHandler()) → submitDeck → claim →
+//   completeDeck → humanloop spawns `crouterCliEntry human _deliver` on stdin →
+//   that CLI subprocess reads the canvas DB at the temp CRTR_HOME, pushFinals
+//   the envelope to the parent, and exits 0.
+//
+// crouterDeliverHandler() resolves the runnable CLI entry from the loaded
+// shared.ts location. Under `tsx`, that is `src/cli.ts` via the tsx ESM loader
+// (dist/cli.js is not a sibling of src/); either entry is a real subprocess that
+// must resolve the canvas at CRTR_HOME, which humanloop's dispatch inherits from
+// this process's env.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, realpathSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerInboxRoot, submitDeck, validateDeck, claimTicket, completeDeck, atomicWriteJson, } from '@crouton-kit/humanloop';
+import { crouterDeliverHandler } from '../../commands/human/shared.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { getNode, closeDb } from '../canvas/index.js';
+import { readInboxSince } from '../feed/inbox.js';
+let home;
+let stateHome;
+let root;
+let priorHome;
+before(() => {
+    priorHome = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-e2e-home-'));
+    stateHome = mkdtempSync(join(tmpdir(), 'crtr-e2e-state-'));
+    const rootDir = mkdtempSync(join(tmpdir(), 'crtr-e2e-root-'));
+    process.env['CRTR_HOME'] = home;
+    process.env['HOME'] = home;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    delete process.env['CRTR_NODE_ID'];
+    // Register with the REAL crouter completion handler — this is what humanloop
+    // will spawn as a subprocess on resolution.
+    root = registerInboxRoot({ root: realpathSync(rootDir), owner: 'crouter', handler: crouterDeliverHandler() }).root;
+});
+after(() => {
+    closeDb();
+    if (priorHome !== undefined)
+        process.env['HOME'] = priorHome;
+    else
+        delete process.env['HOME'];
+    delete process.env['CRTR_HOME'];
+    delete process.env['XDG_STATE_HOME'];
+    delete process.env['CRTR_NODE_ID'];
+});
+function reportBody(ref) {
+    const raw = readFileSync(ref, 'utf8');
+    const end = raw.indexOf('\n---\n');
+    return end === -1 ? raw : raw.slice(end + 5);
+}
+test('a real completeDeck dispatches the registered crouter CLI subprocess, which pushFinals the envelope to the parent', async () => {
+    const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+    const bridge = spawnNode({ kind: 'human', parent, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+    const dir = join(root, bridge);
+    mkdirSync(dir, { recursive: true });
+    atomicWriteJson(join(dir, 'run.json'), { mode: 'ask', job_id: bridge });
+    const deck = validateDeck({ title: 'Ship it?', interactions: [{ id: 'question', title: 'Ship it?', options: [], allowFreetext: true }] });
+    submitDeck({ root, id: bridge, deck });
+    const claim = claimTicket(dir);
+    assert.ok(claim !== null, 'claimed the fresh ticket');
+    // Release the test process's DB handle so the spawned handler subprocess has
+    // clean access to the temp canvas at CRTR_HOME.
+    closeDb();
+    const { won } = await completeDeck(dir, [{ id: 'question', freetext: 'yes, ship' }], claim.token);
+    assert.equal(won, true, 'completeDeck won');
+    // humanloop writes delivery.json only after the handler exits 0.
+    assert.ok(existsSync(join(dir, 'delivery.json')), 'the handler subprocess acked delivery (exit 0)');
+    assert.ok(!existsSync(join(dir, 'delivery-error.json')), 'no delivery error');
+    // The subprocess pushFinal'd through the real CLI: bridge finalized + parent inbox has the envelope.
+    assert.equal(getNode(bridge)?.status, 'done', 'bridge finalized by the subprocess handler');
+    const finals = readInboxSince(parent).filter((e) => e.from === bridge && e.kind === 'final');
+    assert.equal(finals.length, 1, 'exactly one pushFinal reached the parent via the subprocess');
+    const env = JSON.parse(reportBody(finals[0].ref));
+    assert.equal(env.schema, 'humanloop.response/v2');
+    assert.deepEqual(env.responses, [{ id: 'question', freetext: 'yes, ship' }]);
+});
+test('the registered handler argv is an absolute, cwd-independent runnable CLI entry', () => {
+    const handler = crouterDeliverHandler();
+    assert.equal(handler.command, process.execPath);
+    // Last two args are always the subcommand path.
+    assert.deepEqual(handler.args.slice(-2), ['human', '_deliver']);
+    // The CLI entry is an existing absolute file (dist/cli.js when built, else src/cli.ts under tsx).
+    const entry = handler.args.find((a) => a.endsWith('cli.js') || a.endsWith('cli.ts'));
+    assert.ok(entry !== undefined && entry.startsWith('/') && existsSync(entry), `handler CLI entry must be an existing absolute path: ${entry}`);
+});

package/dist/core/__tests__/human-deliver.test.js

@@ -0,0 +1,332 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-deliver.test.ts
+//
+// Unit C1 — crouter as a humanloop producer + completion bridge. These tests
+// pin the two crouter boundaries the hard cut leaves behind:
+//   1. ask/review ENQUEUE only — they create a bridge node, write a minimal
+//      run.json, submit to humanloop, and return immediately. No pane/pid.
+//   2. `_deliver` is the registered completion handler — it turns a humanloop
+//      completion event into the existing `pushFinal` delivery (deck/review) or
+//      a quiet bridge finalization (canceled), idempotently.
+//
+// Everything crosses the real humanloop package boundary: fixtures are the
+// canonical `response.json` union that humanloop's strict `readTicketResult`
+// decodes. Tickets live under a root REGISTERED to owner 'crouter' (the
+// delivery contract), isolated via a temp XDG_STATE_HOME + HOME + CRTR_HOME.
+import { test, describe, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, realpathSync, readFileSync, existsSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, basename } from 'node:path';
+import { registerInboxRoot, submitDeck, validateDeck, claimTicket, completeDeck, cancelTicket, readTicketResult, atomicWriteJson, } from '@crouton-kit/humanloop';
+import { spawnNode } from '../runtime/nodes.js';
+import { getNode, listNodes, closeDb } from '../canvas/index.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { humanAsk, humanReview, humanNotify } from '../../commands/human/prompts.js';
+import { humanDeliver } from '../../commands/human/queue.js';
+// ---------------------------------------------------------------------------
+// Isolated environment
+// ---------------------------------------------------------------------------
+let home; // CRTR_HOME (canvas db) + HOME (os.homedir → interactionsRoot)
+let stateHome; // XDG_STATE_HOME (humanloop root registry)
+let root; // canonical registered interaction root, owner 'crouter'
+let priorHome;
+const ISO = '2026-07-10T12:00:00.000Z';
+/** A benign direct-exec handler so humanloop's completion dispatch during the
+ *  submit/cancel race is a fast no-op — the crouter delivery is exercised by
+ *  calling `_deliver` in-process, not through this subprocess. */
+function benignHandler() {
+    return { command: process.execPath, args: ['-e', ''] };
+}
+/** Register `dir` (created fresh) as an owner-'crouter' root and return its
+ *  canonical path. */
+function registerRoot(dir) {
+    return registerInboxRoot({ root: dir, owner: 'crouter', handler: benignHandler() }).root;
+}
+/** Create a subscribed parent + a terminal human bridge child; return both ids.
+ *  The parent is auto-subscribed to the bridge at spawn, so a `pushFinal` from
+ *  the bridge fans into the parent's inbox — the sole answer route. */
+function bridgeUnder() {
+    const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+    const bridge = spawnNode({ kind: 'human', parent, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+    return { parent, bridge };
+}
+/** Materialize an interaction dir under the registered root with a run.json. */
+function seedTicket(id, mode, jobId) {
+    const dir = join(root, id);
+    mkdirSync(dir, { recursive: true });
+    atomicWriteJson(join(dir, 'run.json'), { mode, ...(jobId !== undefined ? { job_id: jobId } : {}) });
+    return dir;
+}
+function completionEvent(dir, kind) {
+    return {
+        schema: 'humanloop.completion/v1',
+        root,
+        dir,
+        ticketId: dir.split('/').pop(),
+        kind,
+        outcome: kind === 'canceled' ? 'canceled' : 'resolved',
+        responsePath: join(dir, 'response.json'),
+    };
+}
+/** Read the report body a subscriber inbox pointer references (strips YAML front). */
+function reportBody(ref) {
+    const raw = readFileSync(ref, 'utf8');
+    const end = raw.indexOf('\n---\n');
+    return end === -1 ? raw : raw.slice(end + 5);
+}
+before(() => {
+    priorHome = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-deliver-home-'));
+    stateHome = mkdtempSync(join(tmpdir(), 'crtr-deliver-state-'));
+    const rootDir = mkdtempSync(join(tmpdir(), 'crtr-deliver-root-'));
+    process.env['CRTR_HOME'] = home;
+    process.env['HOME'] = home;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    delete process.env['CRTR_NODE_ID'];
+    root = registerRoot(realpathSync(rootDir));
+});
+after(() => {
+    closeDb();
+    if (priorHome !== undefined)
+        process.env['HOME'] = priorHome;
+    else
+        delete process.env['HOME'];
+    delete process.env['CRTR_HOME'];
+    delete process.env['XDG_STATE_HOME'];
+    delete process.env['CRTR_NODE_ID'];
+});
+// ---------------------------------------------------------------------------
+// (a) ask/review enqueue immediately — no pane/pid; run.json = {mode, job_id}
+// ---------------------------------------------------------------------------
+describe('enqueue is producer-only', () => {
+    test('ask returns a job handle with no pane/pid fields and a minimal run.json', async () => {
+        const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+        process.env['CRTR_NODE_ID'] = parent;
+        const r = (await humanAsk.run({ question: 'Ship it?' }));
+        assert.equal(typeof r['job_id'], 'string');
+        assert.equal(typeof r['dir'], 'string');
+        assert.equal(typeof r['follow_up'], 'string');
+        for (const forbidden of ['pane_id', 'render_pane_id', 'pid', 'worker_pid']) {
+            assert.ok(!(forbidden in r), `ask result must not expose ${forbidden}`);
+        }
+        const rc = JSON.parse(readFileSync(join(r['dir'], 'run.json'), 'utf8'));
+        assert.deepEqual(rc, { mode: 'ask', job_id: r['job_id'] });
+        const bridge = getNode(r['job_id']);
+        assert.equal(bridge?.kind, 'human');
+        assert.equal(bridge?.parent, parent);
+    });
+    test('review returns immediately and writes run.json = {mode:review, job_id}', async () => {
+        const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+        process.env['CRTR_NODE_ID'] = parent;
+        const md = join(home, 'plan.md');
+        writeFileSync(md, '# Plan\n\nline\n');
+        const r = (await humanReview.run({ file: md }));
+        assert.equal(typeof r['job_id'], 'string');
+        assert.ok(!('pane_id' in r) && !('render_pane_id' in r), 'no pane fields');
+        const rc = JSON.parse(readFileSync(join(r['dir'], 'run.json'), 'utf8'));
+        assert.deepEqual(rc, { mode: 'review', job_id: r['job_id'] });
+    });
+});
+// ---------------------------------------------------------------------------
+// (b) deck _deliver: pushFinal exactly once, parent inbox gets the envelope
+// ---------------------------------------------------------------------------
+describe('_deliver: deck', () => {
+    test('pushFinals the ResolutionEnvelope once and wakes the subscribed parent', async () => {
+        const { parent, bridge } = bridgeUnder();
+        const dir = seedTicket(bridge, 'ask', bridge);
+        const deckResult = {
+            schema: 'humanloop.response/v2',
+            kind: 'deck',
+            responses: [{ id: 'question', freetext: 'yes, ship' }],
+            summary: 'Ship it?: yes, ship',
+            completedAt: ISO,
+        };
+        writeFileSync(join(dir, 'response.json'), JSON.stringify(deckResult));
+        const out = (await humanDeliver.run({ body: JSON.stringify(completionEvent(dir, 'deck')) }));
+        assert.equal(out.delivered, true);
+        // Bridge finalized.
+        closeDb();
+        assert.equal(getNode(bridge)?.status, 'done');
+        // Parent inbox has exactly one final pointer carrying the envelope.
+        const finals = readInboxSince(parent).filter((e) => e.from === bridge && e.kind === 'final');
+        assert.equal(finals.length, 1, 'exactly one pushFinal reached the parent');
+        const env = JSON.parse(reportBody(finals[0].ref));
+        assert.equal(env.schema, 'humanloop.response/v2');
+        assert.deepEqual(env.responses, deckResult.responses);
+        assert.equal(env.summary, deckResult.summary);
+        assert.equal(env.completedAt, ISO);
+        assert.equal(env.responsePath, join(dir, 'response.json'));
+    });
+    // (c) replay idempotent
+    test('a second _deliver is idempotent — no second push, still delivered', async () => {
+        const { parent, bridge } = bridgeUnder();
+        const dir = seedTicket(bridge, 'ask', bridge);
+        writeFileSync(join(dir, 'response.json'), JSON.stringify({ schema: 'humanloop.response/v2', kind: 'deck', responses: [{ id: 'q', freetext: 'x' }], summary: 'q: x', completedAt: ISO }));
+        const ev = JSON.stringify(completionEvent(dir, 'deck'));
+        await humanDeliver.run({ body: ev });
+        const replay = (await humanDeliver.run({ body: ev }));
+        assert.equal(replay.delivered, true);
+        closeDb();
+        const finals = readInboxSince(parent).filter((e) => e.from === bridge && e.kind === 'final');
+        assert.equal(finals.length, 1, 'replay after a terminal bridge pushes nothing further');
+    });
+});
+// ---------------------------------------------------------------------------
+// (d) review _deliver: delivered == bare FeedbackResult == output projection
+// ---------------------------------------------------------------------------
+describe('_deliver: review', () => {
+    test('pushes the bare FeedbackResult, matching the output projection content', async () => {
+        const { parent, bridge } = bridgeUnder();
+        const dir = seedTicket(bridge, 'review', bridge);
+        const md = realpathSync(home) + '/spec.md';
+        writeFileSync(md, '# spec\n');
+        const feedback = {
+            file: md,
+            submitted: true,
+            approved: false,
+            comments: [{ id: 'c1', line: 1, endLine: 1, lineText: '# spec', comment: 'tighten', createdAt: ISO }],
+            submittedAt: ISO,
+            savedAt: ISO,
+        };
+        writeFileSync(join(dir, 'response.json'), JSON.stringify({ schema: 'humanloop.review-response/v1', kind: 'review', result: feedback, completedAt: ISO }));
+        // The output projection humanloop writes: the bare FeedbackResult.
+        const projection = join(dir, 'feedback.json');
+        writeFileSync(projection, JSON.stringify(feedback));
+        const out = (await humanDeliver.run({ body: JSON.stringify(completionEvent(dir, 'review')) }));
+        assert.equal(out.delivered, true);
+        closeDb();
+        const finals = readInboxSince(parent).filter((e) => e.from === bridge && e.kind === 'final');
+        assert.equal(finals.length, 1);
+        const delivered = JSON.parse(reportBody(finals[0].ref));
+        assert.deepEqual(delivered, feedback, 'delivered payload is the bare FeedbackResult');
+        assert.deepEqual(delivered, JSON.parse(readFileSync(projection, 'utf8')), 'delivered == output projection file');
+    });
+});
+// ---------------------------------------------------------------------------
+// (e) canceled _deliver: bridge finalized, deferred note skips the actor
+// ---------------------------------------------------------------------------
+describe('_deliver: canceled', () => {
+    test('finalizes the bridge and sends a deferred no-answer note to non-actor subscribers only', async () => {
+        // Two subscribers: the actor (who canceled) and another waiter.
+        const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
+        const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+        const other = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' }).node_id;
+        // `other` also subscribes to the bridge.
+        const { subscribe } = await import('../canvas/canvas.js');
+        subscribe(other, bridge, true);
+        const dir = seedTicket(bridge, 'ask', bridge);
+        writeFileSync(join(dir, 'response.json'), JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: ISO, reason: 'stale', actor }));
+        const out = (await humanDeliver.run({ body: JSON.stringify(completionEvent(dir, 'canceled')) }));
+        assert.equal(out.delivered, true);
+        closeDb();
+        assert.equal(getNode(bridge)?.status, 'done', 'canceled bridge finalized');
+        // Actor (who canceled) gets no note; the other waiter does.
+        assert.equal(readInboxSince(actor).length, 0, 'the cancelling actor is not messaged');
+        const otherNotes = readInboxSince(other);
+        assert.equal(otherNotes.length, 1, 'the other waiter gets one deferred note');
+        assert.equal(otherNotes[0].tier, 'deferred');
+        assert.match(otherNotes[0].label, /canceled/);
+    });
+});
+// ---------------------------------------------------------------------------
+// (e2) REGRESSION (Unit X DEFECT F) — a completion event whose root/dir carry an
+// UNRESOLVED symlinked path component still delivers.
+//
+// Humanloop's registry stores every root realpath-canonicalized, but its
+// `dispatchCompletion` only `resolve()`s the dir into the event (not realpath),
+// and crouter's own `human cancel` hands `cancelTicket` a CRTR_HOME-derived dir
+// that is likewise not realpath'd. On any host whose interaction path has a
+// symlinked component (macOS `/tmp`→`/private/tmp`, `/var`→`/private/var`) the
+// event thus carries `/tmp/…` while the registry holds `/private/tmp/…`. Before
+// the fix, `_deliver` compared those with a plain `resolve()` and spuriously
+// threw `interaction dir is not a direct child of the event root` (exit 2) →
+// humanloop wrote delivery-error.json and NO delivery.json, and the cancel
+// completion was never acknowledged. The deck-SUBMIT path dodged this only
+// because the controller's dir already comes from scanning the realpath'd root.
+// `_deliver` now realpath-canonicalizes both sides, so any caller's event
+// delivers regardless of symlinked components.
+// ---------------------------------------------------------------------------
+describe('_deliver: symlinked event paths (DEFECT F regression)', () => {
+    test('delivers a canceled completion whose root/dir carry an unresolved symlink', async () => {
+        // A symlink whose target is the registered root's PARENT, so `symRoot`
+        // realpath-resolves to the registered (realpath'd) `root` but is a distinct
+        // string with an unresolved symlink component — exactly humanloop's event shape.
+        const linkParent = mkdtempSync(join(tmpdir(), 'crtr-deliver-link-'));
+        const link = join(linkParent, 'lnk');
+        symlinkSync(dirname(root), link);
+        const symRoot = join(link, basename(root));
+        assert.notEqual(symRoot, root, 'symRoot is a distinct string');
+        assert.equal(realpathSync(symRoot), root, 'but realpath-resolves to the registered root');
+        const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
+        const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+        const dir = seedTicket(bridge, 'ask', bridge); // real (realpath'd) dir on disk
+        writeFileSync(join(dir, 'response.json'), JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: ISO, actor }));
+        // The event carries the SYMLINKED root/dir/responsePath (non-realpath), the
+        // way dispatchCompletion + `human cancel` build it on a symlinked host.
+        const symDir = join(symRoot, bridge);
+        const event = {
+            schema: 'humanloop.completion/v1',
+            root: symRoot,
+            dir: symDir,
+            ticketId: bridge,
+            kind: 'canceled',
+            outcome: 'canceled',
+            responsePath: join(symDir, 'response.json'),
+        };
+        const out = (await humanDeliver.run({ body: JSON.stringify(event) }));
+        assert.equal(out.delivered, true, 'the cancel completion delivers (no exit-2 rejection)');
+        closeDb();
+        assert.equal(getNode(bridge)?.status, 'done', 'the bridge is finalized exactly once');
+        assert.equal(readInboxSince(actor).length, 0, 'the cancelling actor is not messaged');
+    });
+});
+// ---------------------------------------------------------------------------
+// (f) submit/cancel race via humanloop primitives → one outcome; crouter converges
+// ---------------------------------------------------------------------------
+describe('submit/cancel race', () => {
+    test('one canonical outcome wins and _deliver converges the bridge to a single terminal state', async () => {
+        const { bridge } = bridgeUnder();
+        const dir = join(root, bridge);
+        mkdirSync(dir, { recursive: true });
+        atomicWriteJson(join(dir, 'run.json'), { mode: 'ask', job_id: bridge });
+        const deck = validateDeck({ title: 'Go?', interactions: [{ id: 'q', title: 'Go?', options: [], allowFreetext: true }] });
+        submitDeck({ root, id: bridge, deck });
+        const claim = claimTicket(dir);
+        assert.ok(claim !== null, 'claimed the fresh ticket');
+        // Race an answer against a cancellation on the same exclusive publish.
+        const [completed, canceled] = await Promise.allSettled([
+            completeDeck(dir, [{ id: 'q', freetext: 'go' }], claim.token),
+            cancelTicket(dir, { reason: 'changed mind', actor: 'someone' }),
+        ]);
+        // Exactly one canonical final marker exists on disk.
+        const result = readTicketResult(dir);
+        assert.ok(result !== null, 'a single canonical response.json won');
+        assert.ok(result.kind === 'deck' || result.kind === 'canceled');
+        // Whatever won, at most one side reports a win.
+        const wonDeck = completed.status === 'fulfilled' && completed.value.won === true;
+        const wonCancel = canceled.status === 'fulfilled' && canceled.value.status === 'canceled';
+        assert.ok(!(wonDeck && wonCancel), 'submit and cancel cannot both win');
+        // Feed the winning outcome to crouter; the bridge reaches exactly one terminal state.
+        const out = (await humanDeliver.run({ body: JSON.stringify(completionEvent(dir, result.kind)) }));
+        assert.equal(out.delivered, true);
+        closeDb();
+        assert.equal(getNode(bridge)?.status, 'done', 'bridge converged to one terminal outcome');
+    });
+});
+// ---------------------------------------------------------------------------
+// (g) notify creates no node
+// ---------------------------------------------------------------------------
+describe('notify', () => {
+    test('enqueues a durable deck and creates no canvas node', async () => {
+        const before = listNodes().length;
+        const r = (await humanNotify.run({ title: 'Build done' }));
+        assert.equal(r['queued'], true);
+        assert.equal(typeof r['dir'], 'string');
+        assert.ok(existsSync(join(r['dir'], 'deck.json')), 'notify wrote a durable deck');
+        closeDb();
+        assert.equal(listNodes().length, before, 'notify created no node');
+    });
+});