@north-light/crouter 0.3.154

package/dist/daemon/api/__tests__/inbox.test.js

@@ -0,0 +1,578 @@
+// Run with: node --import tsx/esm --test src/daemon/api/__tests__/inbox.test.ts
+//
+// Integration coverage for crtrd's `/v1/human/inbox` routes
+// (inbox-contract.md §A, `handlers/inbox.ts`). Exercises the full leaf → typed
+// `CrtrClient` → in-process `createApiServer()` → handler → real
+// `@crouton-kit/humanloop` boundary — never a mock client, never a
+// pre-parsed handler call. Tickets live under a root registered directly
+// with humanloop's `registerInboxRoot`, isolated per test via a fresh
+// `XDG_STATE_HOME` (humanloop's root registry reads it live, so the SAME
+// running server picks up a fresh registry with no restart needed).
+//
+// Fixture policy: an ordinary pending ticket is created through humanloop's
+// public `submitDeck`/`submitReview` — the same surface a real caller uses.
+// A raw hand-written `deck.json`/`review.json` is used ONLY where the test's
+// whole point is a state `submitDeck`/`submitReview` cannot produce: a
+// stored ticket with an unresolved `bodyPath` (submit-time resolution
+// already inlines it), a tampered/malformed stored deck (simulating
+// mutation after enumeration), an adversarial root-replacement fixture, or a
+// deliberately raced foreign claim/resolution. Each such use is commented.
+import { test, describe, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, symlinkSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { registerInboxRoot, submitDeck, submitReview, claimTicket, releaseClaim, deckPath, responsePath, notifyDeck, } from '@crouton-kit/humanloop';
+import { createApiServer } from '../server.js';
+import { apiSocketPath } from '../../../core/canvas/paths.js';
+import { CrtrClient, ApiError } from '../../../api/index.js';
+const TICKET_ID_PATTERN = /^[a-f0-9]{64}$/;
+// ---------------------------------------------------------------------------
+// Harness — one server for the whole file; a fresh humanloop root registry
+// (XDG_STATE_HOME) per test.
+// ---------------------------------------------------------------------------
+let crtrHome;
+let priorCrtrHome;
+let priorXdgStateHome;
+let server;
+let client;
+let stateHome;
+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(async () => {
+    priorCrtrHome = process.env['CRTR_HOME'];
+    priorXdgStateHome = process.env['XDG_STATE_HOME'];
+    crtrHome = mkdtempSync(join(tmpdir(), 'crtr-inbox-home-'));
+    process.env['CRTR_HOME'] = crtrHome;
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+    client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+});
+after(async () => {
+    await server?.close();
+    rmSync(crtrHome, { recursive: true, force: true });
+    if (priorCrtrHome !== undefined)
+        process.env['CRTR_HOME'] = priorCrtrHome;
+    else
+        delete process.env['CRTR_HOME'];
+    if (priorXdgStateHome !== undefined)
+        process.env['XDG_STATE_HOME'] = priorXdgStateHome;
+    else
+        delete process.env['XDG_STATE_HOME'];
+});
+beforeEach(() => {
+    stateHome = mkdtempSync(join(tmpdir(), 'crtr-inbox-state-'));
+    process.env['XDG_STATE_HOME'] = stateHome;
+});
+afterEach(() => {
+    rmSync(stateHome, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+function freshRoot(owner, withHandler = false) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-inbox-root-'));
+    const reg = registerInboxRoot({
+        root: dir,
+        owner,
+        ...(withHandler ? { handler: { command: process.execPath, args: ['-e', ''] } } : {}),
+    });
+    return reg.root; // already canonical (realpathSync'd internally)
+}
+function deckJson(blockedSince, extra = {}) {
+    return {
+        title: 'Ship it?',
+        source: { blockedSince },
+        interactions: [{ id: 'q', title: 'Ship it?', subtitle: 'Approve shipping now so the release can proceed.', options: [{ id: 'yes', label: 'Yes' }, { id: 'no', label: 'No' }] }],
+        ...extra,
+    };
+}
+/** Create a real pending deck ticket through the public submission API — the
+ *  normal fixture path for any test that just needs a valid, answerable
+ *  ticket on disk. */
+function submitTestDeck(root, id, blockedSince, extra = {}) {
+    return submitDeck({ root, id, deck: deckJson(blockedSince, extra) }).dir;
+}
+/** Create a real pending review ticket through the public submission API. */
+function submitTestReview(root, id, blockedSince) {
+    const srcDir = mkdtempSync(join(tmpdir(), 'crtr-inbox-review-src-'));
+    const file = join(srcDir, 'plan.md');
+    writeFileSync(file, '# Plan\n\nDo the thing.\n');
+    return submitReview({ root, id, review: { title: 'Review the plan', subtitle: 'Review the plan now so implementation can begin with confidence.', source: {}, file, blockedSince } }).dir;
+}
+/** RAW fixture writer — bypasses `submitDeck`'s own submit-time validation
+ *  and body-path resolution entirely. Used ONLY to construct on-disk states
+ *  a real submitter cannot produce: an unresolved `bodyPath`, a tampered
+ *  stored deck, or an adversarial root-replacement target. */
+function writeRawDeckTicket(root, id, deck) {
+    const dir = join(root, id);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(deckPath(dir), JSON.stringify(deck));
+    return dir;
+}
+function ticketIdFor(root, basename) {
+    return createHash('sha256').update(`${root}\0${basename}`, 'utf8').digest('hex');
+}
+async function expectApiError(promise, status, code) {
+    try {
+        await promise;
+    }
+    catch (err) {
+        assert.ok(err instanceof ApiError, `expected ApiError, got ${String(err)}`);
+        assert.equal(err.status, status, `status: ${err.message}`);
+        assert.equal(err.code, code, `code: ${err.message}`);
+        return err;
+    }
+    throw new Error('expected the promise to reject');
+}
+// ---------------------------------------------------------------------------
+// Wire-shape assertions — a closed allowlist per DTO plus a recursive
+// forbidden-content walk (host paths, claim/dir/file/output/bodyPath keys).
+// ---------------------------------------------------------------------------
+function assertKeys(obj, allowed, label) {
+    for (const key of Object.keys(obj)) {
+        assert.ok(allowed.includes(key), `unexpected field "${key}" in ${label}: ${JSON.stringify(obj)}`);
+    }
+}
+function assertSourceShape(source) {
+    assert.equal(typeof source, 'object');
+    assertKeys(source, ['sessionName', 'askedBy', 'blockedSince', 'nodeId', 'visual'], 'DeckSourceDTO');
+}
+function assertTicketSummaryShape(ticket) {
+    assert.match(ticket.ticket_id, TICKET_ID_PATTERN);
+    assert.ok(ticket.kind === 'deck' || ticket.kind === 'review');
+    const allowed = ticket.kind === 'deck'
+        ? ['ticket_id', 'kind', 'title', 'subtitle', 'blocked_since', 'source', 'interaction_kind']
+        : ['ticket_id', 'kind', 'title', 'subtitle', 'blocked_since', 'source'];
+    assertKeys(ticket, allowed, `InboxTicketSummaryDTO(${ticket.kind})`);
+    assertSourceShape(ticket.source);
+}
+function assertInboxListShape(body) {
+    assertKeys(body, ['tickets'], 'InboxListDTO');
+    for (const ticket of body.tickets)
+        assertTicketSummaryShape(ticket);
+}
+function assertInteractionShape(interaction) {
+    assertKeys(interaction, ['id', 'title', 'subtitle', 'body', 'options', 'multiSelect', 'allowFreetext', 'freetextLabel', 'kind', 'preAnswered'], 'InteractionDTO');
+    for (const option of interaction.options) {
+        assertKeys(option, ['id', 'label', 'description'], 'InteractionOptionDTO');
+    }
+    if (interaction.preAnswered !== undefined) {
+        assertKeys(interaction.preAnswered, ['selectedOptionId', 'selectedOptionIds', 'freetext', 'label'], 'InteractionPreAnswerDTO');
+    }
+}
+function assertDeckShape(deck) {
+    assertKeys(deck, ['title', 'source', 'interactions'], 'DeckDTO');
+    if (deck.source !== undefined)
+        assertSourceShape(deck.source);
+    for (const interaction of deck.interactions)
+        assertInteractionShape(interaction);
+}
+function assertInboxDeckShape(body) {
+    assertKeys(body, ['ticket_id', 'kind', 'deck'], 'InboxDeckDTO');
+    assert.equal(body.kind, 'deck');
+    assert.match(body.ticket_id, TICKET_ID_PATTERN);
+    assertDeckShape(body.deck);
+}
+function assertDeckResultShape(result) {
+    assertKeys(result, ['schema', 'kind', 'responses', 'summary', 'completedAt'], 'DeckTicketResultDTO');
+    assert.equal(result.schema, 'humanloop.response/v2');
+    assert.equal(result.kind, 'deck');
+    for (const response of result.responses) {
+        assertKeys(response, ['id', 'selectedOptionId', 'selectedOptionIds', 'freetext', 'optionComments'], 'InteractionResponseDTO');
+    }
+}
+function assertCanceledResultShape(result) {
+    assertKeys(result, ['schema', 'kind', 'canceledAt', 'reason', 'actor'], 'CanceledTicketResultDTO');
+    assert.equal(result.schema, 'humanloop.cancel/v1');
+    assert.equal(result.kind, 'canceled');
+}
+const FORBIDDEN_KEYS = new Set(['dir', 'file', 'output', 'claim', 'bodyPath']);
+/** Recursively walk a parsed JSON value, failing on any forbidden key name or
+ *  any string value containing one of the given forbidden substrings (host
+ *  paths, in practice). Used against full success AND error bodies. */
+function assertNoForbiddenContent(value, forbidden, path = '$') {
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => assertNoForbiddenContent(item, forbidden, `${path}[${i}]`));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [key, val] of Object.entries(value)) {
+            assert.ok(!FORBIDDEN_KEYS.has(key), `forbidden key "${key}" present at ${path}.${key}`);
+            assertNoForbiddenContent(val, forbidden, `${path}.${key}`);
+        }
+        return;
+    }
+    if (typeof value === 'string') {
+        for (const needle of forbidden) {
+            assert.ok(!value.includes(needle), `forbidden content "${needle}" leaked at ${path}: ${JSON.stringify(value)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// GET /v1/human/inbox — enumerate
+// ---------------------------------------------------------------------------
+describe('GET /v1/human/inbox — enumerate', () => {
+    test('mixed deck + review tickets sort newest blocked_since first, then ticket_id ascending; closed wire shape, no forbidden content', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'older-deck', '2026-01-01T00:00:00.000Z');
+        submitTestReview(root, 'newer-review', '2026-01-02T00:00:00.000Z');
+        const list = await client.listHumanInbox();
+        assertInboxListShape(list);
+        assertNoForbiddenContent(list, [root, stateHome]);
+        assert.equal(list.tickets.length, 2);
+        assert.equal(list.tickets[0].kind, 'review', 'newer blocked_since sorts first');
+        assert.equal(list.tickets[1].kind, 'deck');
+        assert.equal(list.tickets[0].ticket_id, ticketIdFor(root, 'newer-review'));
+        assert.equal(list.tickets[1].ticket_id, ticketIdFor(root, 'older-deck'));
+    });
+    test('sorts by parsed instant across differing UTC offsets, not lexical string order', async () => {
+        const root = freshRoot('crouter');
+        // '+14:00' is lexically GREATER than 'Z' at the date digit that differs,
+        // but the instant it names is two hours EARLIER than the 'Z' ticket
+        // below (2026-01-01T10:00:00Z vs. 2026-01-01T12:00:00Z). A lexical
+        // descending sort would (wrongly) place this ticket first.
+        submitTestDeck(root, 'lexically-later-but-earlier-instant', '2026-01-02T00:00:00+14:00');
+        submitTestDeck(root, 'lexically-earlier-but-later-instant', '2026-01-01T12:00:00Z');
+        const list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 2);
+        assert.equal(list.tickets[0].blocked_since, '2026-01-01T12:00:00Z', 'the chronologically newer instant sorts first regardless of lexical string order');
+        assert.equal(list.tickets[0].ticket_id, ticketIdFor(root, 'lexically-earlier-but-later-instant'));
+        assert.equal(list.tickets[1].ticket_id, ticketIdFor(root, 'lexically-later-but-earlier-instant'));
+    });
+});
+// ---------------------------------------------------------------------------
+// GET /v1/human/inbox/:ticket_id — read a pending deck
+// ---------------------------------------------------------------------------
+describe('GET /v1/human/inbox/:ticket_id', () => {
+    test('inlines bodyPath at read time; no bodyPath key on the wire', async () => {
+        // RAW fixture: `submitDeck` resolves `bodyPath` to inline `body` at
+        // submit time, so a ticket with a still-unresolved `bodyPath` on disk
+        // (the state crtrd's own `parseDeck` read-time resolution exists to
+        // handle) cannot be produced through the public submission API.
+        const root = freshRoot('crouter');
+        const dir = join(root, 'body-deck');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(dir, 'body.md'), 'Full markdown body.\n');
+        writeFileSync(deckPath(dir), JSON.stringify({
+            title: 'Ship it?',
+            source: { blockedSince: '2026-01-01T00:00:00.000Z' },
+            interactions: [{ id: 'q', title: 'Ship it?', subtitle: 'Approve shipping now so the release can proceed.', bodyPath: 'body.md', options: [{ id: 'yes', label: 'Yes' }] }],
+        }));
+        const id = ticketIdFor(root, 'body-deck');
+        const deckDto = await client.getHumanInboxDeck(id);
+        assertInboxDeckShape(deckDto);
+        assertNoForbiddenContent(deckDto, [root, dir]);
+        assert.equal(deckDto.deck.interactions[0].body, 'Full markdown body.\n');
+    });
+    test('404 ticket_not_found for a syntactically valid but unknown ticket id', async () => {
+        await expectApiError(client.getHumanInboxDeck('a'.repeat(64)), 404, 'ticket_not_found');
+    });
+    test('409 ticket_kind_unsupported for a review ticket', async () => {
+        const root = freshRoot('crouter');
+        submitTestReview(root, 'rev', '2026-01-01T00:00:00.000Z');
+        await expectApiError(client.getHumanInboxDeck(ticketIdFor(root, 'rev')), 409, 'ticket_kind_unsupported');
+    });
+    test('malformed stored deck sanitizes to 500 internal: no bodyPath value or host path in error.message', async () => {
+        // RAW fixture: simulates a ticket mutated on disk after enumeration (or a
+        // corrupted store) — a state `submitDeck` cannot produce, since it
+        // validates and resolves bodyPath before ever writing deck.json. This
+        // reproduces the review's exact repro shape: a bodyPath that escapes the
+        // ticket directory to an existing absolute host file.
+        const root = freshRoot('crouter');
+        const dir = writeRawDeckTicket(root, 'malformed', deckJson('2026-01-01T00:00:00.000Z', {
+            interactions: [{ id: 'q', title: 'Ship it?', subtitle: 'Approve shipping now so the release can proceed.', bodyPath: process.execPath, options: [{ id: 'yes', label: 'Yes' }] }],
+        }));
+        const id = ticketIdFor(root, 'malformed');
+        const err = await expectApiError(client.getHumanInboxDeck(id), 500, 'internal');
+        assert.ok(!err.message.includes(process.execPath), `error.message leaked a host path: ${err.message}`);
+        assert.ok(!err.message.includes(dir), `error.message leaked the ticket directory: ${err.message}`);
+        assert.ok(!err.message.toLowerCase().includes('bodypath'), `error.message named bodyPath: ${err.message}`);
+    });
+});
+// ---------------------------------------------------------------------------
+// POST /v1/human/inbox/:ticket_id/respond
+// ---------------------------------------------------------------------------
+describe('POST /v1/human/inbox/:ticket_id/respond', () => {
+    test('persists the canonical humanloop.response/v2 result unchanged, matches stored response.json exactly, and dispatches completion delivery', async () => {
+        const root = freshRoot('crouter', true);
+        const dir = submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const result = await client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] });
+        assertDeckResultShape(result);
+        assertNoForbiddenContent(result, [root, dir]);
+        assert.deepEqual(result.responses, [{ id: 'q', selectedOptionId: 'yes' }]);
+        const stored = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+        assert.deepEqual(stored, result, 'the wire result is the stored humanloop response exactly, unreconstructed');
+        // Completion dispatch is async (spawns the registered handler); poll for
+        // the delivery marker rather than assuming it lands synchronously.
+        const deliveryFile = join(dir, 'delivery.json');
+        for (let i = 0; i < 100 && !existsSync(deliveryFile); i++)
+            await new Promise((r) => setTimeout(r, 25));
+        assert.ok(existsSync(deliveryFile), 'completion delivery was dispatched to the registered handler');
+    });
+    test('ordinary notify acknowledgement — no special endpoint/shape', async () => {
+        const root = freshRoot('crouter');
+        const id_ = 'notify';
+        submitDeck({ root, id: id_, deck: notifyDeck('Build done', { subtitle: 'The build completed successfully, so the change is ready to review.' }) });
+        const id = ticketIdFor(root, 'notify');
+        const result = await client.respondHumanInboxDeck(id, { responses: [{ id: 'notify', selectedOptionId: 'ok' }] });
+        assert.equal(result.kind, 'deck');
+        assert.deepEqual(result.responses, [{ id: 'notify', selectedOptionId: 'ok' }]);
+    });
+    test('409 ticket_kind_unsupported for a review ticket', async () => {
+        const root = freshRoot('crouter');
+        submitTestReview(root, 'rev', '2026-01-01T00:00:00.000Z');
+        await expectApiError(client.respondHumanInboxDeck(ticketIdFor(root, 'rev'), { responses: [] }), 409, 'ticket_kind_unsupported');
+    });
+    test('409 ticket_already_resolved on a second respond after the first succeeds', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        await client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] });
+        await expectApiError(client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'no' }] }), 409, 'ticket_already_resolved');
+    });
+    test('409 ticket_unavailable when a live foreign claim already holds the ticket', async () => {
+        const root = freshRoot('crouter');
+        const dir = submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        // Raw use of the claim API is the legitimate way to simulate a genuine
+        // live foreign claim.
+        const foreignClaim = claimTicket(dir, { host: 'someone-else' });
+        assert.ok(foreignClaim !== null, 'foreign claim acquired');
+        try {
+            await expectApiError(client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] }), 409, 'ticket_unavailable');
+        }
+        finally {
+            releaseClaim(dir, foreignClaim.token);
+        }
+    });
+    test('external cancel/resolve race: a resolution that lands between the precheck and claimTicket() reports ticket_already_resolved, never ticket_unavailable', async () => {
+        const root = freshRoot('crouter');
+        const dir = submitTestDeck(root, 'race', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'race');
+        // A real separate OS process holds the SAME ticket lock humanloop's
+        // `claimTicket` contends for (`<dir>/.ticket-lock`, matching the marker
+        // scheme in humanloop's `convention.ts`). It signals once it holds the
+        // lock, then after a short real delay writes `response.json` directly
+        // (simulating an external actor's cancel/respond winning the race) and
+        // releases. Because the holder grabs the lock BEFORE this test sends the
+        // respond request, the precheck inside the handler is guaranteed to see
+        // the ticket still pending, and `claimTicket()`'s own lock acquisition is
+        // guaranteed to block until the holder resolves the ticket and releases
+        // — deterministically reproducing the exact interleaving the fix must
+        // handle, without relying on a microsecond-scale timing coincidence.
+        const script = `
+      const { mkdirSync, writeFileSync, rmSync } = require('node:fs');
+      const dir = process.env.RACE_TICKET_DIR;
+      const lockPath = dir + '/.ticket-lock';
+      mkdirSync(lockPath, { mode: 0o700 });
+      writeFileSync(lockPath + '/owner.race-holder', '', { flag: 'wx', mode: 0o600 });
+      process.stdout.write('holding\\n');
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 300);
+      writeFileSync(dir + '/response.json', JSON.stringify({
+        schema: 'humanloop.cancel/v1', kind: 'canceled',
+        canceledAt: new Date().toISOString(), reason: 'external race', actor: 'external',
+      }) + '\\n', { mode: 0o600 });
+      rmSync(lockPath, { recursive: true, force: true });
+      process.stdout.write('resolved\\n');
+    `;
+        const holder = spawn(process.execPath, ['-e', script], {
+            env: { ...process.env, RACE_TICKET_DIR: dir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        holder.stdout.setEncoding('utf8');
+        holder.stderr.setEncoding('utf8');
+        holder.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        holder.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        const exited = new Promise((resolve) => holder.once('close', resolve));
+        try {
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new Error(`race holder never signaled "holding": stdout=${stdout} stderr=${stderr}`)), 5000);
+                const check = () => {
+                    if (stdout.includes('holding')) {
+                        clearTimeout(timer);
+                        resolve();
+                    }
+                };
+                holder.stdout.on('data', check);
+                holder.once('error', (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+                check();
+            });
+            await expectApiError(client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] }), 409, 'ticket_already_resolved');
+        }
+        finally {
+            await exited;
+        }
+        assert.ok(stdout.includes('resolved'), `race holder did not complete its resolve+release: stdout=${stdout} stderr=${stderr}`);
+    });
+    test('500 internal for a finalize failure that is not a response-shape rejection — sanitized, not misclassified as 400', async () => {
+        const root = freshRoot('crouter');
+        const dir = submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        // RAW tamper: rewrite the persisted deck so its own re-read inside
+        // `finalizeDeck` fails deck-schema validation (interactions.min(1)) —
+        // this is a storage-layer failure, not a response-shape rejection, and
+        // `submitDeck` could never have written it in the first place.
+        writeFileSync(deckPath(dir), JSON.stringify({ title: 'Ship it?', interactions: [] }));
+        const err = await expectApiError(client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] }), 500, 'internal');
+        assert.equal(err.message, 'the ticket could not be finalized');
+        assert.ok(!err.message.includes(dir), `error.message leaked the ticket directory: ${err.message}`);
+    });
+    test('400 invalid_ticket_response releases the claim so a following valid respond succeeds', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const err = await expectApiError(client.respondHumanInboxDeck(id, { responses: [{ id: 'nonexistent', freetext: 'x' }] }), 400, 'invalid_ticket_response');
+        assert.match(err.message, /response does not match a unique deck interaction: nonexistent/);
+        const result = await client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] });
+        assert.equal(result.kind, 'deck', 'the claim was released, so a valid respond now succeeds');
+    });
+    test('400 invalid_request for a malformed body', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const path = `/v1/human/inbox/${id}/respond`;
+        await expectApiError(client.request('POST', path, { responses: [], extra: true }), 400, 'invalid_request');
+        await expectApiError(client.request('POST', path, { responses: 'nope' }), 400, 'invalid_request');
+    });
+});
+// ---------------------------------------------------------------------------
+// POST /v1/human/inbox/:ticket_id/cancel
+// ---------------------------------------------------------------------------
+describe('POST /v1/human/inbox/:ticket_id/cancel', () => {
+    test('default reason, actor is hardcoded human, matches stored response.json, dispatches completion delivery', async () => {
+        const root = freshRoot('crouter', true);
+        const dir = submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const result = await client.cancelHumanInboxTicket(id);
+        assertCanceledResultShape(result);
+        assertNoForbiddenContent(result, [root, dir]);
+        assert.equal(result.reason, 'Canceled from the inbox.');
+        assert.equal(result.actor, 'human');
+        const stored = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+        assert.deepEqual(stored, result, 'the wire result is the stored humanloop cancellation exactly, unreconstructed');
+        const deliveryFile = join(dir, 'delivery.json');
+        for (let i = 0; i < 100 && !existsSync(deliveryFile); i++)
+            await new Promise((r) => setTimeout(r, 25));
+        assert.ok(existsSync(deliveryFile), 'completion delivery was dispatched to the registered handler');
+    });
+    test('custom reason is honored; actor is always human regardless of any client-supplied field', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const result = await client.cancelHumanInboxTicket(id, { reason: 'changed my mind' });
+        assert.equal(result.reason, 'changed my mind');
+        assert.equal(result.actor, 'human');
+    });
+    test('409 ticket_kind_unsupported for a review ticket', async () => {
+        const root = freshRoot('crouter');
+        submitTestReview(root, 'rev', '2026-01-01T00:00:00.000Z');
+        await expectApiError(client.cancelHumanInboxTicket(ticketIdFor(root, 'rev')), 409, 'ticket_kind_unsupported');
+    });
+    test('409 ticket_already_resolved after the ticket was already resolved via respond', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        await client.respondHumanInboxDeck(id, { responses: [{ id: 'q', selectedOptionId: 'yes' }] });
+        await expectApiError(client.cancelHumanInboxTicket(id), 409, 'ticket_already_resolved');
+    });
+    test('400 invalid_request for an empty (post-trim) reason and for a >1000-char reason', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        await expectApiError(client.cancelHumanInboxTicket(id, { reason: '   ' }), 400, 'invalid_request');
+        await expectApiError(client.cancelHumanInboxTicket(id, { reason: 'x'.repeat(1001) }), 400, 'invalid_request');
+    });
+});
+// ---------------------------------------------------------------------------
+// Malformed ticket id syntax
+// ---------------------------------------------------------------------------
+describe('malformed ticket id syntax', () => {
+    test('400 invalid_request on GET/respond/cancel for a non-hex or wrong-length id', async () => {
+        for (const bad of ['not-hex-not-64-chars', 'a'.repeat(63), 'g'.repeat(64)]) {
+            await expectApiError(client.request('GET', `/v1/human/inbox/${bad}`), 400, 'invalid_request');
+            await expectApiError(client.request('POST', `/v1/human/inbox/${bad}/respond`, { responses: [] }), 400, 'invalid_request');
+            await expectApiError(client.request('POST', `/v1/human/inbox/${bad}/cancel`, {}), 400, 'invalid_request');
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// Root filtering
+// ---------------------------------------------------------------------------
+describe('root filtering', () => {
+    test('a non-crouter-owned root never appears in enumeration and its ticket 404s on GET', async () => {
+        const root = freshRoot('humanloop');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        const list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 0);
+        await expectApiError(client.getHumanInboxDeck(id), 404, 'ticket_not_found');
+    });
+    test('a root that becomes unavailable disappears from enumeration and resolution', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'ask', '2026-01-01T00:00:00.000Z');
+        const id = ticketIdFor(root, 'ask');
+        let list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 1);
+        rmSync(root, { recursive: true, force: true });
+        list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 0);
+        await expectApiError(client.getHumanInboxDeck(id), 404, 'ticket_not_found');
+    });
+    test('a registered root replaced by a symlink to an unrelated directory confers no authority (enumeration and resolution)', async () => {
+        const root = freshRoot('crouter');
+        submitTestDeck(root, 'legit', '2026-01-01T00:00:00.000Z');
+        // Adversarial fixture: after registration, the registered pathname is
+        // removed and replaced with a symlink to an unrelated directory that
+        // was never registered as a crouter-owned root. Only a raw fixture can
+        // construct this — no submission API models a compromised root.
+        const attackerDir = mkdtempSync(join(tmpdir(), 'crtr-inbox-attacker-'));
+        writeRawDeckTicket(attackerDir, 'attacker', deckJson('2026-01-01T00:00:00.000Z', { title: 'Attacker deck' }));
+        rmSync(root, { recursive: true, force: true });
+        symlinkSync(attackerDir, root);
+        const list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 0, 'the attacker-controlled target must not be exposed through the replaced pathname');
+        const attackerId = ticketIdFor(attackerDir, 'attacker');
+        await expectApiError(client.getHumanInboxDeck(attackerId), 404, 'ticket_not_found');
+    });
+});
+// ---------------------------------------------------------------------------
+// Opaque-id collision safety
+// ---------------------------------------------------------------------------
+describe('opaque-id collision safety', () => {
+    test('two crouter roots with tickets sharing the same basename resolve to distinct ids and correct decks', async () => {
+        const rootA = freshRoot('crouter');
+        const rootB = freshRoot('crouter');
+        submitTestDeck(rootA, 'dup', '2026-01-01T00:00:00.000Z', { title: 'From root A' });
+        submitTestDeck(rootB, 'dup', '2026-01-01T00:00:00.000Z', { title: 'From root B' });
+        const idA = ticketIdFor(rootA, 'dup');
+        const idB = ticketIdFor(rootB, 'dup');
+        assert.notEqual(idA, idB);
+        const list = await client.listHumanInbox();
+        assert.equal(list.tickets.length, 2);
+        const ids = list.tickets.map((t) => t.ticket_id).sort();
+        assert.deepEqual(ids, [idA, idB].sort());
+        const deckA = await client.getHumanInboxDeck(idA);
+        const deckB = await client.getHumanInboxDeck(idB);
+        assert.equal(deckA.deck.title, 'From root A');
+        assert.equal(deckB.deck.title, 'From root B');
+    });
+});

package/dist/daemon/api/bridge.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/** Handle the HTTP upgrade for `GET /v1/nodes/{id}/attach`. A-9 matches the
+ *  route, extracts `{id}`, and calls this with the raw upgrade triplet; this
+ *  owns the WS handshake (its own noServer `wss` above) AND the spec §5.3
+ *  attach-implies-revive semantics. Never throws — every failure path either
+ *  refuses the upgrade (plain HTTP error + socket destroy) or, post-handshake,
+ *  closes the WS with a code. So A-9's upgrade router needs no try/catch around
+ *  this call beyond its own top-level safety net.
+ *
+ *  Flow:
+ *   1. Guard `isSafeNodeId` (→ 400) and existence (→ 404) BEFORE building any
+ *      fs path or reviving — an unsafe id must never reach `viewSocketPath`.
+ *   2. Unless revive is opted out (`?revive=0` / `X-Crtr-Attach-Revive: 0`):
+ *      `reviveNode(id, { resume:true })` then
+ *      `waitForBrokerViewSocket` (bounded). Revive throw OR socket-not-listenable
+ *      → refuse 409, WS never opens.
+ *   3. Revive opted out: a single connect probe. Dormant (socket refuses) →
+ *      refuse 409 (spec §5.3 asymmetry: a dead broker can't stream over WS).
+ *   4. Only then upgrade and hand the live WS to {@link bridgeConnection}. */
+export declare function handleAttachUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, nodeId: string): Promise<void>;