@crouton-kit/crouter 0.3.81 → 0.3.83

package/dist/commands/sys/setup-core.js

@@ -8,6 +8,9 @@ import { BINDING_CATALOG, normalizeGesture, resolveKeybindings, } from '../../co
 import { builtinPiPackageDir } from '../../core/scope.js';
 import { readJsonIfExists } from '../../core/fs-utils.js';
 import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
+import { installInboxBinding } from '@crouton-kit/humanloop';
+import { listNodes } from '../../core/canvas/index.js';
+import { registerCrouterRoot } from '../human/shared.js';
 function isKeybindingsObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -422,6 +425,8 @@ export function renderSetupStaticInstructions(state) {
         '',
         instructions.exaLine,
         instructions.composioLine,
+        '',
+        'Inbox popup: running `crtr sys setup` installs the collision-safe ⌥I humanloop inbox popup binding and registers known nodes\' interaction roots (best-effort; the binding needs a running tmux server). On a key collision, re-bind with `hl inbox bind --key <tmux-key>`.',
         instructions.footer,
     ].join('\n') + '\n';
 }
@@ -447,6 +452,42 @@ export async function writeComposioKey(composioKeyPath, composioKey) {
     await writeFile(composioKeyPath, `${composioKey}\n`, 'utf8');
     await chmod(composioKeyPath, 0o600).catch(() => undefined);
 }
+/** Reconcile humanloop's collision-safe ⌥I inbox popup binding on the current
+ *  tmux server, and register each known node's interaction root to owner
+ *  `crouter` so a resolved ticket can call back into `human _deliver`. Both are
+ *  best-effort: setup must never fail because tmux is absent or the canvas is
+ *  unreadable. Crouter calls humanloop's installer — it never authors its own
+ *  tmux command. */
+export function reconcileInboxFrontDoor() {
+    let binding = { state: 'unavailable', key: '', isDefault: false };
+    try {
+        const state = installInboxBinding();
+        binding = { state: state.state, key: state.key, isDefault: state.isDefault };
+    }
+    catch {
+        /* best-effort: no tmux server / installer unavailable */
+    }
+    let interactionRootsRegistered = 0;
+    try {
+        const seen = new Set();
+        for (const node of listNodes()) {
+            if (seen.has(node.cwd))
+                continue;
+            seen.add(node.cwd);
+            try {
+                registerCrouterRoot(node.cwd);
+                interactionRootsRegistered += 1;
+            }
+            catch {
+                /* skip a cwd humanloop can't canonicalize/create */
+            }
+        }
+    }
+    catch {
+        /* best-effort: canvas unavailable */
+    }
+    return { binding, interactionRootsRegistered };
+}
 export function summarizeSetupExecution(result) {
     return {
         installed: [...result.installedPackages, ...result.installedSystemDeps],
@@ -455,8 +496,22 @@ export function summarizeSetupExecution(result) {
         exaKeyPath: result.exaKeyPath,
         composioKeyWritten: result.composioKeyWritten,
         composioKeyPath: result.composioKeyPath,
+        inboxBinding: result.inboxBinding,
+        interactionRootsRegistered: result.interactionRootsRegistered,
     };
 }
+export function formatInboxBindingLine(binding) {
+    switch (binding.state) {
+        case 'installed':
+            return `inbox popup binding: ⌥I (${binding.key})${binding.isDefault ? '' : ' — custom key'} installed`;
+        case 'collision':
+            return `inbox popup binding: NOT installed — ${binding.key} is already bound by another action. Re-bind explicitly with \`hl inbox bind --key <tmux-key>\`.`;
+        case 'unbound':
+            return 'inbox popup binding: not bound';
+        default:
+            return 'inbox popup binding: unavailable (no tmux server)';
+    }
+}
 export function formatSetupExecutionSummary(summary) {
     return [
         'crtr sys setup complete',
@@ -464,6 +519,8 @@ export function formatSetupExecutionSummary(summary) {
         summary.skipped.length > 0 ? `skipped: ${summary.skipped.join(', ')}` : 'skipped: none',
         summary.exaKeyWritten ? `exa key written: ${summary.exaKeyPath}` : 'exa key written: no',
         summary.composioKeyWritten ? `composio key written: ${summary.composioKeyPath}` : 'composio key written: no',
+        formatInboxBindingLine(summary.inboxBinding),
+        `interaction roots registered: ${summary.interactionRootsRegistered}`,
     ].join('\n') + '\n';
 }
 export async function executeSetupSubmission(submission) {
@@ -499,6 +556,9 @@ export async function executeSetupSubmission(submission) {
     if (composioKeyWritten) {
         await writeComposioKey(submission.composioKeyPath, submission.composioKey);
     }
+    // Front-door reconciliation: install the ⌥I inbox popup binding and register
+    // known nodes' interaction roots for `human _deliver` callback. Best-effort.
+    const { binding, interactionRootsRegistered } = reconcileInboxFrontDoor();
     return summarizeSetupExecution({
         installedPackages,
         skippedPackages,
@@ -508,5 +568,7 @@ export async function executeSetupSubmission(submission) {
         exaKeyPath: submission.exaKeyPath,
         composioKeyWritten,
         composioKeyPath: submission.composioKeyPath,
+        inboxBinding: binding,
+        interactionRootsRegistered,
     });
 }

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,12 @@ export class SetupWizard {
 }
 async function runSetup() {
     const state = buildSetupInitialState();
+    // Front-door reconciliation: invoking `crtr sys setup` — TTY or not —
+    // installs the collision-safe ⌥I inbox popup binding and registers known
+    // nodes' interaction roots. 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).
+    reconcileInboxFrontDoor();
     if (!process.stdout.isTTY) {
         process.stdout.write(renderSetupStaticInstructions(state));
         return;
@@ -1397,6 +1403,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), installs the collision-safe ⌥I humanloop inbox popup binding on the current tmux server (leaving any pre-existing binding untouched and reporting the collision remedy) and registers known nodes\' interaction roots so resolved tickets can call back into the asking node.',
         ],
     },
     run: async () => {

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');
+    });
+});

package/dist/core/__tests__/human-node-not-supervised.test.js

@@ -5,10 +5,11 @@
 // at boot with "pi vehicle exited before the session came up".
 //
 // ROOT CAUSE: a kind:'human' row is NOT a broker-hosted agent node — it is a
-// bookkeeping row for the `crtr human` bridge. Its decision/review TUI runs in a
-// detached `crtr human _run` pane (NOT a pi engine), and the row's lifecycle is
-// driven entirely by that worker's `pushFinal` (or `human cancel`). So it never
-// records a `pi_pid` or `pi_session_id`. After the headless hard-cut made the
+// bookkeeping row for the `crtr human` bridge. Nothing runs in it: the human
+// answers from humanloop's inbox, and the row's lifecycle is driven entirely by
+// humanloop's completion handler (`crtr human _deliver`) calling `pushFinal` (or
+// `human cancel`). So it never records a `pi_pid` or `pi_session_id`. After the
+// headless hard-cut made the
 // broker the universal node host, superviseTick supervised EVERY active|idle row
 // as a broker engine: it read the human row (pid==null, session==null) as a
 // never-booted broker, waited out the boot grace, then crash'd it and fired