@north-light/crouter 0.3.154

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

@@ -0,0 +1,123 @@
+// 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, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, realpathSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createApiServer } from '../../daemon/api/server.js';
+import { apiSocketPath } from '../canvas/paths.js';
+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';
+import { resolveRef } from '../canvas/history.js';
+let home;
+let stateHome;
+let root;
+let priorHome;
+let server;
+// createApiServer binds its socket asynchronously (file created in the listen
+// callback); poll for it before the subprocess handler tries to connect.
+async function waitForSocket(path) {
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path))
+            return;
+        await new Promise((r) => setTimeout(r, 25));
+    }
+    throw new Error(`api socket never bound at ${path}`);
+}
+before(() => {
+    priorHome = process.env['HOME'];
+});
+beforeEach(async () => {
+    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'];
+    // POST-P1 the `crtr human _deliver` subprocess humanloop spawns pushFinals
+    // through cliClient() over crtrd's socket. Bind an in-process createApiServer()
+    // on this temp home's socket (apiSocketPath() resolves under CRTR_HOME=home)
+    // so the subprocess's client resolves against the same tmp canvas DB. Closed
+    // in afterEach.
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+    // 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;
+});
+afterEach(async () => {
+    await server?.close();
+    server = undefined;
+    closeDb();
+});
+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 resolved = resolveRef(ref);
+    if (resolved === null || resolved.source !== 'report')
+        throw new Error(`push report ref did not resolve to a report: ${ref}`);
+    return resolved.body;
+}
+test('a real completeDeck dispatches the registered crouter CLI subprocess, which pushFinals the readable answer 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?', subtitle: 'Decide whether to ship now so the release can proceed.', 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 answer.
+    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 body = reportBody(finals[0].ref);
+    assert.ok(body.includes('yes, ship'), "the human's answer is inline");
+    assert.ok(body.includes(join(dir, 'response.json')), 'the canonical response path is one path away');
+    assert.ok(!body.includes('humanloop.response/v2'), 'no serialized envelope is inlined');
+});
+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.d.ts

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

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

@@ -0,0 +1,399 @@
+// 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, afterEach } 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 { resolveRef } from '../canvas/history.js';
+import { humanDeliver } from '../../commands/human/queue.js';
+import { createApiServer } from '../../daemon/api/server.js';
+import { trustedCrouterVisualHandler } from '../../daemon/api/handlers/human.js';
+import { apiSocketPath } from '../canvas/paths.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;
+// Since the crtrd-API re-plumb the producer + completion leaves are thin CLI
+// forwarders: `ask`/`review` create their bridge node through
+// `cliClient().createHumanBridge`, and `_deliver` forwards the completion event
+// to crtrd, which owns the pushFinal/finalize delivery. Stand up a real
+// in-process `createApiServer()` bound to the isolated CRTR_HOME's socket so the
+// full leaf → client → server → handler path runs against the genuine seam —
+// never an autostarted subprocess daemon, never a mock client.
+let server;
+async function waitForSocket(path) {
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path))
+            return;
+        await new Promise((r) => setTimeout(r, 25));
+    }
+    throw new Error(`api socket never bound at ${path}`);
+}
+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. */
+function reportBody(ref) {
+    const resolved = resolveRef(ref);
+    if (resolved === null || resolved.source !== 'report')
+        throw new Error(`push report ref did not resolve to a report: ${ref}`);
+    return resolved.body;
+}
+before(() => {
+    priorHome = process.env['HOME'];
+});
+beforeEach(async () => {
+    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));
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+});
+afterEach(async () => {
+    await server?.close();
+});
+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 captures fork provenance
+// ---------------------------------------------------------------------------
+test('Visual handler trusts sealed sibling runtime generations across a daemon roll', () => {
+    const currentGeneration = 'a'.repeat(64);
+    const retainedGeneration = 'b'.repeat(64);
+    const current = {
+        command: '/home/.crouter/host/crouter',
+        args: [`/home/.crouter/runtime/generations/${currentGeneration}/dist/cli.js`, 'human', '_visual'],
+    };
+    const retained = {
+        command: '/opt/bin/node',
+        args: [`/home/.crouter/runtime/generations/${retainedGeneration}/dist/cli.js`, 'human', '_visual'],
+    };
+    assert.equal(trustedCrouterVisualHandler(retained, current), true);
+    assert.equal(trustedCrouterVisualHandler({ ...retained, command: '/tmp/python' }, current), false);
+    assert.equal(trustedCrouterVisualHandler({ ...retained, args: ['/tmp/cli.js', 'human', '_visual'] }, current), false);
+    assert.equal(trustedCrouterVisualHandler({ ...retained, args: [retained.args[0], 'human', '_deliver'] }, current), false);
+});
+describe('enqueue is producer-only', () => {
+    test('ask requires and preserves an explicit title instead of deriving one from the body', async () => {
+        const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
+        process.env['CRTR_NODE_ID'] = parent;
+        await assert.rejects(() => humanAsk.run({ question: 'This first line must never become the title.' }), /require a non-empty --title/);
+        const r = (await humanAsk.run({ title: 'Release decision', subtitle: 'Decide whether to release now so the launch can proceed.', question: 'This first line must never become the title.' }));
+        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 deck = JSON.parse(readFileSync(join(r['dir'], 'deck.json'), 'utf8'));
+        assert.equal(deck.title, 'Release decision');
+        assert.equal(deck.interactions[0]?.title, 'Release decision');
+        assert.equal(deck.interactions[0]?.subtitle, 'Decide whether to release now so the launch can proceed.');
+        assert.equal(deck.interactions[0]?.body, 'This first line must never become the title.');
+        assert.equal(deck.interactions[0]?.kind, 'decision');
+        const structured = (await humanAsk.run({
+            deck: {
+                title: 'Structured decision',
+                interactions: [
+                    { id: 'default', title: 'Default', subtitle: 'Choose the default so the release can proceed.', options: [] },
+                    { id: 'context', kind: 'context', title: 'Context', subtitle: 'Read this context so the decision is informed.', options: [] },
+                ],
+            },
+        }));
+        const structuredDeck = JSON.parse(readFileSync(join(structured['dir'], 'deck.json'), 'utf8'));
+        assert.deepEqual(structuredDeck.interactions.map((interaction) => interaction.kind), ['decision', 'context']);
+        const rc = JSON.parse(readFileSync(join(r['dir'], 'run.json'), 'utf8'));
+        assert.equal(rc['mode'], 'ask');
+        assert.equal(rc['job_id'], r['job_id']);
+        assert.deepEqual(rc['conversation_fork'] && {
+            status: rc['conversation_fork']['status'],
+            reason: rc['conversation_fork']['reason'],
+        }, { status: 'unavailable', reason: 'broker_unavailable' });
+        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, subtitle: 'Review this plan so implementation can begin safely.' }));
+        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 answer
+// ---------------------------------------------------------------------------
+describe('_deliver: deck', () => {
+    test('pushFinals the readable answer 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 human's words —
+        // the summary, not a serialized envelope — plus the metadata path.
+        const finals = readInboxSince(parent).filter((e) => e.from === bridge && e.kind === 'final');
+        assert.equal(finals.length, 1, 'exactly one pushFinal reached the parent');
+        const body = reportBody(finals[0].ref);
+        assert.equal(body.split('\n')[0], deckResult.summary, 'the answer leads the report');
+        assert.ok(body.includes(join(dir, 'response.json')), 'the canonical response path is one path away');
+        assert.ok(!body.includes('humanloop.response/v2'), 'no serialized envelope is inlined');
+    });
+    // (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 == readable anchored comments + record path
+// ---------------------------------------------------------------------------
+describe('_deliver: review', () => {
+    test('pushes readable anchored comments plus the feedback-record path', 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 = reportBody(finals[0].ref);
+        assert.ok(delivered.includes('1 comment on ' + md), 'the comment count and file lead the report');
+        assert.ok(delivered.includes('tighten'), 'the human\'s comment text is inline');
+        assert.ok(delivered.includes(join(dir, 'response.json')), 'the full feedback record is one path away');
+        assert.ok(!delivered.includes('"savedAt"'), 'no serialized FeedbackResult is inlined');
+        assert.deepEqual(JSON.parse(readFileSync(projection, 'utf8')), feedback, 'the output projection file is untouched');
+    });
+});
+// ---------------------------------------------------------------------------
+// (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?', subtitle: 'Decide whether to proceed so the work can continue.', 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', subtitle: 'The build passed, so the change is ready to review.' }));
+        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.d.ts

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

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

@@ -0,0 +1,94 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-node-not-supervised.test.ts
+//
+// BUG REGRESSION (issue #2 — "Headless node can't reach human-ask: human-kind
+// TUI dies at boot"): a headless orchestrator's every `crtr human ask` node died
+// 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. 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, the daemon
+// supervised EVERY active|idle row as a broker engine: it read the human row
+// (pid==null, session==null) as a never-booted broker and boot-failed it —
+// killing the human prompt before the person could ever answer.
+//
+// THE FIX under exit-event authority lives in TWO filters, both driven here:
+// superviseTick drops kind:'human' rows from every row pass, and the startup
+// recovery sweep skips them before classification — the sweep treats every
+// swept row as known-dead, so an unfiltered human row (session null, no fork
+// claim) would land in policy row 8 (boot failure), the modern re-incarnation
+// of the exact bug.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { superviseTick, runStartupRecoverySweep } from '../../daemon/crtrd.js';
+import { bindTestFleet } from './helpers/fleet.js';
+import { resetFleetForTests } from '../runtime/fleet.js';
+let home;
+let tf;
+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,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-not-supervised-'));
+    process.env['CRTR_HOME'] = home;
+    tf = bindTestFleet(); // superviseTick + the sweep require a bound fleet (D-2)
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    tf.fleet.dispose();
+    resetFleetForTests();
+});
+test('a kind:"human" bridge row is NEVER boot-failed by the daemon (it has no broker engine)', async () => {
+    // The exact shape spawnNode({kind:'human'}) mints: active, host_kind broker,
+    // but NO pi engine ever booted — so pi_pid and pi_session_id stay null.
+    createNode(node('HUMAN', {
+        kind: 'human',
+        lifecycle: 'terminal',
+        host_kind: 'broker',
+        pi_pid: null,
+        pi_session_id: null,
+        intent: null,
+    }));
+    // The asking node is auto-subscribed to its human bridge node at spawn, so a
+    // surfaceBootFailure (pushUrgent) would land in ASKER's inbox. Park it as a
+    // dormant idle-release row (policy row 4 / pass-2 no-op) so both the sweep and
+    // the tick leave IT alone — it is only here to catch a push.
+    createNode(node('ASKER', { status: 'idle', intent: 'idle-release', pi_session_id: 'booted' }));
+    subscribe('ASKER', 'HUMAN', true);
+    // Two well-spaced ticks: under exit-event authority the tick runs no liveness
+    // pass at all, and its row passes (controller-wait settle, pass-2 inbox wake)
+    // must drop the human row before reading it.
+    const t0 = Date.now();
+    await superviseTick(t0);
+    await superviseTick(t0 + 10_000_000);
+    // The startup recovery sweep is the sharper threat: it classifies every swept
+    // active|idle row as known-dead, so only its kind:'human' filter keeps the
+    // bridge row out of policy row 8 (boot failure).
+    await runStartupRecoverySweep(tf.fleet);
+    assert.equal(getNode('HUMAN').status, 'active', 'human bridge row stays alive — never crash-reaped as a dead broker');
+    assert.equal(readInboxSince('ASKER').length, 0, 'no surfaceBootFailure urgent push — the asker is never told its human prompt "never started"');
+});

package/dist/core/__tests__/inline-memory-refs.test.d.ts

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