@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/api/handlers/human.js

@@ -1,741 +1,143 @@
-// Human-bridge handlers — the CANVAS HALF (spec §6.5). The humanloop
-// ticket/deck store is an external package that stays client-side; these cover
-// every canvas mutation the `crtr human` surface used to perform in-process,
-// relocated into crtrd so the CLI's transitive import graph never reaches
-// canvas state (spec §1/§10). Two families live here:
-//
-//   POST /v1/canvas/consults    arm a consult-outbox receipt (idempotent)
-//   GET  /v1/canvas/consults    list active consult-outbox entries
-//
-//   POST /v1/human/bridge       create a kind:'human' bridge node (spawnNode, no broker)
-//   POST /v1/human/deliver      run the registered completion handler (_deliver)
-//   POST /v1/human/consult      run the registered follow-up handler (_consult)
-//   POST /v1/human/visual       run the registered visual handler (_visual)
-//
-// The completion-handler bodies (`_deliver`/`_consult`/`_visual`) were lifted
-// VERBATIM from `src/commands/human/queue.ts`: humanloop still invokes
-// `node dist/cli.js human _deliver|_consult|_visual` with the event on stdin,
-// but that CLI leaf is now a thin forwarder to the endpoints below. crtrd
-// RE-VERIFIES the full trust binding (event schema, realpath containment, root
-// registered to `crouter`, and — for consult/visual — the registered handler
-// identity matching crouter's own argv) before performing any canvas mutation,
-// so relocating the caller preserves the security boundary intact. A Visual
-// request may outlive the immutable runtime generation that registered it, so
-// its handler is accepted when it is either the daemon's exact current argv or
-// a Node invocation of the same `_visual` leaf from a sealed sibling generation
-// under the daemon's runtime root. This keeps live old brokers working across
-// generation rolls without accepting an arbitrary executable or CLI path.
-import { realpathSync, accessSync, constants as fsConstants } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+// Human bridge and ticket-work routes owned by crtrd. Ticket directories are
+// derived from bridge node ids; callers never supply a filesystem path, root,
+// handler, or claim binding.
+import { existsSync } from 'node:fs';
 import { ApiError } from '../../../api/index.js';
-import { armFollowUpWork, cancelFollowUpWork, errorFollowUpWork, getActiveFollowUpWorkByRequest, listActiveFollowUpWorkByDir, listActiveVisualWorkByDir, listArmedFollowUpWork, listPendingFollowUpWork, claimVisualWork, getVisualWorkByRequest, retireVisualWork, reconcileFollowUpWork, reconcileVisualWork, } from '../../../core/canvas/human-work-outbox.js';
-import { getNode, subscribersOf } from '../../../core/canvas/canvas.js';
-import { transition } from '../../../core/runtime/lifecycle.js';
-import { buildLaunchSpec } from '../../../core/runtime/launch.js';
-import { newNodeId, spawnNode } from '../../../core/runtime/nodes.js';
-import { reviveNode } from '../../../core/runtime/revive.js';
-import { headlessBrokerHost } from '../../../core/runtime/host.js';
-import { buildIdentityAssertionFor } from '../../../core/runtime/bearings.js';
-import { appendInbox } from '../../../core/feed/inbox.js';
-import { pushFinal } from '../../../core/feed/feed.js';
-import { parseDeck, deckPath, responsePath, isResolved, readJson, readTicketResult, listInboxRoots, readFollowUp, cancelFollowUp, submitFollowUpResult, cancelVisualRequestsForTicket, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequestForEvent, submitVisualResult, } from '@crouton-kit/humanloop';
-import { crouterConsultHandler, crouterVisualHandler } from '../../../commands/human/shared.js';
-import { toConsultOutboxEntryDTO } from '../map.js';
-/** Canonicalize a completion-event path the same way humanloop's registry does
- *  (realpath-resolved), falling back to a plain `resolve()` when the path no
- *  longer exists on disk, so the `_deliver` containment/registration checks
- *  compare like against like regardless of symlinked path components. */
-function canonicalPath(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return resolve(p);
-    }
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { deckPath, reviewPath } from '../../../core/human/convention.js';
+import { ticketDir } from '../../../core/human/root.js';
+import { readTicketResult, validateDeckTicketResponses } from '../../../core/human/tickets.js';
+import { getReviewByBridge } from '../../../core/review/store.js';
+import { ReviewOperationError } from '../../../core/review/types.js';
+import { spawnNode } from '../../../core/runtime/nodes.js';
+import { cancelHumanTicket, resolveDeckTicket } from '../../human/finish.js';
+import { cancelReview } from '../../review/finish.js';
+function requireTicketNodeId(ctx) {
+    const nodeId = ctx.params['node_id'];
+    if (nodeId === undefined || !isSafeNodeId(nodeId)) {
+        throw new ApiError(400, 'invalid_request', 'invalid ticket node id');
+    }
+    return nodeId;
 }
 // ===========================================================================
-// POST/GET /v1/canvas/consults — consult-outbox arm/list (the canvas primitive)
+// POST /v1/human/bridge — create a terminal bridge without a broker
 // ===========================================================================
-/** `POST /v1/canvas/consults` — arm a consult-outbox receipt. Idempotent for a
- *  follow-up: an already-armed/pending request for the same dir+request_id is
- *  returned with `created:false` rather than double-armed.
- *
- *  Visual consults carry an immutable correlation binding (interaction /
- *  generation / snapshot / handler / claim token) that `CreateConsultRequest`
- *  does not model, so a `visual` kind is refused (422) rather than half-written
- *  here. Since the `_visual` lift below arms visual work with its full binding
- *  server-side (`handleVisual`), no crouter caller ever reaches this route with
- *  a visual kind — the 422 is retained only as a defensive guard on the bare
- *  consult primitive. */
-function handleCreate(ctx) {
-    const req = ctx.body;
-    if (req === undefined || typeof req !== 'object') {
-        throw new ApiError(400, 'invalid_request', 'consult body is required');
-    }
-    const { node_id, kind, request_id, dir, root } = req;
-    for (const [field, value] of Object.entries({ node_id, kind, request_id, dir, root })) {
-        if (typeof value !== 'string' || value === '') {
-            throw new ApiError(400, 'invalid_request', `consult body requires \`${field}\``);
-        }
-    }
-    if (kind === 'visual') {
-        throw new ApiError(422, 'unprocessable', 'visual consults carry an immutable correlation binding not modeled by this route');
-    }
-    if (kind !== 'follow_up') {
-        throw new ApiError(400, 'invalid_request', `unknown consult kind: ${String(kind)}`);
-    }
-    if (getActiveFollowUpWorkByRequest(dir, request_id) !== null) {
-        return { status: 200, body: { request_id, created: false } };
-    }
-    armFollowUpWork({ nodeId: node_id, dir, root, requestId: request_id });
-    return { status: 200, body: { request_id, created: true } };
-}
-/** `GET /v1/canvas/consults` — active consult-outbox entries. With `?dir=<abs>`
- *  the list is scoped to that interaction dir (both follow-up and visual work);
- *  without it, every active follow-up receipt on the canvas (armed + pending). */
-function handleList(ctx) {
-    const dir = ctx.query.get('dir');
-    const rows = dir !== null && dir !== ''
-        ? [...listActiveFollowUpWorkByDir(dir), ...listActiveVisualWorkByDir(dir)]
-        : [...listArmedFollowUpWork(), ...listPendingFollowUpWork()];
-    return { status: 200, body: { entries: rows.map(toConsultOutboxEntryDTO) } };
-}
-// ===========================================================================
-// POST /v1/human/bridge — create a kind:'human' bridge node (no broker)
-// ===========================================================================
-/** Create the terminal `kind:'human'` bridge node that later receives the
- *  human's answer via `pushFinal`. Uses `spawnNode` (a pure canvas row + meta,
- *  NO broker engine) — NOT `spawnChild`/`POST /nodes`, which always launches a
- *  broker the bridge must never have (spec §6.5's "spawnChild" is corrected to
- *  this dedicated no-broker endpoint). */
 function handleCreateBridge(ctx) {
     const req = ctx.body;
     if (req === undefined || typeof req !== 'object') {
         throw new ApiError(400, 'invalid_request', 'bridge body is required');
     }
     const { kind, cwd, name } = req;
-    if (kind !== 'human') {
+    if (kind !== 'human')
         throw new ApiError(400, 'invalid_request', 'bridge kind must be "human"');
-    }
-    if (typeof cwd !== 'string' || cwd === '') {
+    if (typeof cwd !== 'string' || cwd === '')
         throw new ApiError(400, 'invalid_request', 'bridge body requires `cwd`');
-    }
-    if (typeof name !== 'string' || name === '') {
+    if (typeof name !== 'string' || name === '')
         throw new ApiError(400, 'invalid_request', 'bridge body requires `name`');
-    }
     const parent = req.parent ?? null;
     if (parent !== null && (typeof parent !== 'string' || parent === '')) {
         throw new ApiError(400, 'invalid_request', 'bridge `parent` must be a node id or null');
     }
-    let node;
-    try {
-        node = spawnNode({ kind: 'human', parent, cwd, name, lifecycle: 'terminal' });
-    }
-    catch (e) {
-        // The only expected failure is an unknown parent (spawnNode validates it
-        // before minting) — surface it as a 400, not an internal error.
-        throw new ApiError(400, 'invalid_request', String(e));
-    }
-    return { status: 200, body: { node_id: node.node_id, name: node.name } };
-}
-// ===========================================================================
-// POST /v1/human/deliver — the registered humanloop completion handler
-// ===========================================================================
-/** Build the ResolutionEnvelope crouter delivers back for an answered deck,
- *  from the canonical deck result. */
-function envelopeFromDeckResult(responses, summary, completedAt, respPath) {
-    return { summary, responsePath: respPath, schema: 'humanloop.response/v2', responses, completedAt };
-}
-/** The answer report a subscriber actually reads. The asking agent wants the
- *  human's words, not a serialized envelope: the deterministic per-question
- *  summary IS the answer, and the canonical response.json stays one path away
- *  for the rare case that option ids or timestamps matter. */
-function renderDeckAnswer(env) {
-    const summary = env.summary.trim();
-    const body = summary === '' ? '(the human submitted no answer text)' : summary;
-    return `${body}\n\nResponse metadata (question ids, selected options, timestamp): ${env.responsePath}`;
-}
-/** Same contract for a review ticket: readable anchored comments, with the
- *  full feedback record left as a path rather than inlined JSON. */
-function renderReviewAnswer(feedback, respPath) {
-    const n = feedback.comments.length;
-    const out = [];
-    if (n === 0) {
-        out.push(feedback.approved
-            ? `Review approved — 0 comments on ${feedback.file} (human signalled looks-good; proceed).`
-            : `Review returned with 0 comments on ${feedback.file}.`);
-    }
-    else {
-        out.push(`Review — ${n} comment${n === 1 ? '' : 's'} on ${feedback.file}:`);
-        out.push('');
-        feedback.comments.forEach((c, i) => {
-            const range = c.endLine > c.line ? `L${c.line}-${c.endLine}` : `L${c.line}`;
-            const quoted = c.quote !== undefined && c.quote !== '' ? c.quote : c.lineText;
-            out.push(` ${i + 1}. ${range}`);
-            quoted.split('\n').forEach((ln, k) => out.push(k === 0 ? `    text:    ${ln}` : `             ${ln}`));
-            c.comment.split('\n').forEach((ln, k) => out.push(k === 0 ? `    comment: ${ln}` : `             ${ln}`));
-            out.push('');
-        });
-    }
-    out.push(`Full feedback record (anchors, columns, timestamps): ${respPath}`);
-    return out.join('\n');
-}
-/** Follow-up retirement, invoked before the bridge is retired on ANY
- *  resolution/cancellation outcome (deck, review, canceled) —
- *  design-followup-consult-v2.md §B.5 "Bridge retirement" + §6 "Cancellation
- *  & supersede" (c). Ordering matters (M1): invalidate the current follow-up
- *  request under humanloop's `.followup-lock` FIRST (`cancelFollowUp`), so a
- *  fork that is mid-launch sees a non-running request on its post-launch
- *  recheck (`handleConsultStart`) and self-cancels, THEN cancel any
- *  request-bound fork still armed or pending for this ticket. Best-effort and
- *  idempotent: a follow-up consult must never block or fail the primary
- *  delivery it rides in on — reconcileFollowUpWork is the crash-safety net
- *  for anything this misses. */
-async function retireVisualsForTicket(root, dir) {
-    try {
-        await cancelVisualRequestsForTicket(root, dir);
-    }
-    catch { /* primary delivery remains authoritative */ }
-    for (const row of listActiveVisualWorkByDir(dir)) {
-        try {
-            transition(row.node_id, 'cancel');
-        }
-        catch { /* already terminal */ }
-        try {
-            headlessBrokerHost.teardown(row.node_id);
-        }
-        catch { /* best-effort, mirrors close.ts */ }
-        retireVisualWork(dir, row.request_id);
-    }
-}
-function retireConsultsForTicket(root, dir) {
     try {
-        cancelFollowUp(root, dir);
-    }
-    catch {
-        // No live followUpHandler registration, or no running request to
-        // invalidate — nothing to do.
-    }
-    try {
-        for (const row of listActiveFollowUpWorkByDir(dir)) {
-            transition(row.node_id, 'cancel');
-            cancelFollowUpWork(row.node_id);
-        }
-    }
-    catch {
-        // Best-effort cleanup; reconcileFollowUpWork is the crash-safety net.
-    }
-}
-/** `POST /v1/human/deliver` — turns a resolved/canceled ticket into the
- *  existing pushFinal delivery and bridge finalization. The body is a
- *  `humanloop.completion/v1` event (already JSON-parsed by the router).
- *  Idempotent: replay after a crash is safe. */
-async function handleDeliver(ctx) {
-    const event = ctx.body;
-    if (event?.schema !== 'humanloop.completion/v1') {
-        throw new ApiError(400, 'invalid_request', 'not a humanloop.completion/v1 event');
-    }
-    // Canonicalize both paths through realpathSync before comparing. Humanloop's
-    // registry stores every root REALPATH-resolved, but its dispatchCompletion
-    // only `resolve()`s the dir into the event (not realpath) and crouter's own
-    // `human cancel` hands it a CRTR_HOME-derived dir that is likewise not
-    // realpath'd. So on any host whose interaction path has a symlinked component
-    // (macOS `/tmp`→`/private/tmp`, `/var`→`/private/var`), a plain `resolve()`
-    // comparison mismatches the registry's realpath and the containment/registration
-    // checks below spuriously reject a legitimate completion. Realpath'ing both
-    // sides makes the trust boundary robust to whichever caller produced the event.
-    const root = canonicalPath(event.root);
-    const dir = canonicalPath(event.dir);
-    // Containment: the interaction dir must be a direct child of the event root,
-    // and that root must be registered to crouter.
-    if (resolve(dir, '..') !== root) {
-        throw new ApiError(400, 'invalid_request', 'interaction dir is not a direct child of the event root');
-    }
-    const registered = listInboxRoots().some((r) => r.root === root && r.owner === 'crouter');
-    if (!registered) {
-        throw new ApiError(400, 'invalid_request', `root is not registered to crouter: ${root}`);
-    }
-    // Prove event.responsePath is THIS ticket's canonical response before
-    // trusting anything about it (Major-3): dispatchCompletion always sets it
-    // to `responsePath(dir)`, so a mismatch means a malformed/stale/forged
-    // event whose kind/payload cannot be trusted — reject it here, before any
-    // consult is invalidated and before the (unread) result could downgrade a
-    // live, valid consultation.
-    if (canonicalPath(event.responsePath) !== canonicalPath(responsePath(dir))) {
-        throw new ApiError(400, 'invalid_request', "responsePath is not this ticket's canonical response");
-    }
-    const jobId = basename(dir);
-    const rc = readJson(join(dir, 'run.json'));
-    // A notification has no bridge and no answer delivery.
-    if (rc?.mode === 'notify')
-        return { status: 200, body: { delivered: true } };
-    // Read + validate the canonical primary result BEFORE invalidating or
-    // canceling any live follow-up consult (Major-3): a malformed, stale, or
-    // transiently unreadable event must fail HERE and leave a live consult
-    // untouched, rather than permanently canceling valid consultation work
-    // ahead of a delivery that then turns out not to have a real result.
-    const result = readTicketResult(event.responsePath);
-    if (result === null) {
-        throw new ApiError(404, 'not_found', 'no canonical result to deliver');
+        const node = spawnNode({ kind: 'human', parent, cwd, name, lifecycle: 'terminal' });
+        return { status: 200, body: { node_id: node.node_id, name: node.name } };
     }
-    // The canonical primary result is now proven and read. Only from here is
-    // it safe to retire any live follow-up consult for this ticket, run the
-    // crash-safety-net sweep for every OTHER ticket, and perform bridge
-    // retirement (below) — §B.5 ordering (M1): invalidate the request, then
-    // cancel the fork, THEN the general reconcile pass (Major 6): a pending
-    // consult crash-left for THIS exact ticket must never get a chance to
-    // publish while this ticket's request is still 'running' — retiring this
-    // ticket first (which cancels its own outbox rows) makes the reconcile
-    // that follows a true no-op for it, leaving reconcile to do its
-    // crash-safety-net job for every OTHER ticket only.
-    await retireVisualsForTicket(root, dir);
-    retireConsultsForTicket(root, dir);
-    reconcileFollowUpWork();
-    reconcileVisualWork();
-    const node = getNode(jobId);
-    // Replay-safe: an already-terminal (or reaped) bridge needs no further work.
-    if (node === null || node.status === 'dead' || node.status === 'canceled' || (node.status === 'done' && node.final_report != null)) {
-        return { status: 200, body: { delivered: true } };
-    }
-    if (result.kind === 'canceled') {
-        transition(jobId, 'finish');
-        const note = result.reason !== undefined && result.reason !== '' ? ` — ${result.reason}` : '';
-        const actor = result.actor;
-        for (const sub of subscribersOf(jobId)) {
-            if (actor !== undefined && sub.node_id === actor)
-                continue;
-            appendInbox(sub.node_id, {
-                from: jobId,
-                tier: 'deferred',
-                kind: 'message',
-                label: `human interaction ${jobId} canceled — no answer is coming${note}`,
-                data: { body: `The human interaction ${jobId} was canceled${note}. No response will arrive.` },
-            });
-        }
-        return { status: 200, body: { delivered: true } };
-    }
-    if (result.kind === 'review') {
-        const feedback = result.result;
-        await pushFinal(jobId, renderReviewAnswer(feedback, event.responsePath));
-        return { status: 200, body: { delivered: true } };
+    catch (error) {
+        throw new ApiError(400, 'invalid_request', String(error));
     }
-    // deck
-    const env = envelopeFromDeckResult(result.responses, result.summary, result.completedAt, event.responsePath);
-    await pushFinal(jobId, renderDeckAnswer(env));
-    return { status: 200, body: { delivered: true } };
 }
 // ===========================================================================
-// POST /v1/human/consult — the registered follow-up handler
-//
-// design-followup-consult-v2.md §B.5 — the registered `followUpHandler` for
-// the crouter root (§B.7). Verifies capability + a live running follow-up
-// request (M3), then persists the receipted outbox + lifecycle-owned private
-// fork claim and asks reviveNode to birth it (action:'start'), or cancels the
-// request-bound child (action:'cancel'). Every branch resolves without
-// throwing — `handled` communicates whether an action was actually taken;
-// humanloop's handler contract is a fast kickoff ack, never a blocking wait on
-// the answer (a rejection here just means a cancel/supersede already raced
-// ahead of this event, which is expected, not exceptional).
+// POST /v1/human/tickets/:node_id/resolve and /cancel
 // ===========================================================================
-const FOLLOW_UP_CAPABILITY = 'humanloop.follow-up/v1';
-const PRIVATE_FOLLOW_UP_FRAMING = 'A human overseeing your earlier question asked a private follow-up. Answer it as a ' +
-    'self-contained directive-markdown briefing, then `crtr push final` — your final report ' +
-    'IS the answer. This is private; it returns only to them and does NOT go back to your ' +
-    'original conversation.';
-/** The capability IS the registered handler (§B.5's "real anchor" for M3):
- *  require the root's registered `followUpHandler` to be a crouter `_consult`
- *  invocation, so a stray/forged event naming a registered-but-different owner
- *  can't create private work. Generation-tolerant for the same reason Visual
- *  is (`trustedCrouterHandler`): the registration is written by the asking
- *  broker's sealed generation, while crtrd may already run a newer sibling
- *  generation — an exact argv compare silently declined every follow-up after
- *  a daemon roll and left the ticket stuck on "consulting…" forever. */
-function followUpHandlerMatches(handler) {
-    try {
-        return trustedCrouterHandler(handler, crouterConsultHandler(), '_consult');
-    }
-    catch {
-        return false;
-    }
-}
-/** Look up the fork bound to one ticket dir + requestId via the indexed
- *  request-bound DAO read (Minor 9) rather than scanning every armed/pending
- *  row and filtering in memory. Per-request binding (not a mutable single
- *  current-fork pointer) is what makes the supersede race structurally
- *  impossible (§B.5): an old cancel can only ever find and cancel the fork
- *  actually bound to ITS requestId. */
-function findConsultForkId(dir, requestId) {
-    return getActiveFollowUpWorkByRequest(dir, requestId)?.node_id ?? null;
-}
-/** Full trust binding shared by BOTH start and cancel (Major 5 + M3):
- *  explicit capability constant, `owner==='crouter'`, the dir is a direct
- *  child of the registered root, that registration's `followUpHandler`
- *  identity matches ours, and the ticket is an `ask` run — the only kind with
- *  a branch worth consulting, and the trust anchor a cancel needs just as
- *  much as a start. Returns the canonicalized root/dir plus the parsed
- *  run.json once every check passes; returns null (decline, never act) on the
- *  first failure. */
-function verifyConsultTrust(event) {
-    if (event.capability !== FOLLOW_UP_CAPABILITY || event.owner !== 'crouter')
-        return null;
-    const root = canonicalPath(event.root);
-    const dir = canonicalPath(event.dir);
-    if (resolve(dir, '..') !== root)
-        return null;
-    const registration = listInboxRoots().find((r) => r.root === root && r.owner === 'crouter');
-    if (registration === undefined || !followUpHandlerMatches(registration.followUpHandler))
-        return null;
-    const rc = readJson(join(dir, 'run.json'));
-    if (rc?.mode !== 'ask')
-        return null;
-    return { root, dir, rc };
-}
-/** True when `path` exists and this process can read it. Used to settle
- *  (not silently decline) a consult whose captured branch is missing OR
- *  present-but-unreadable (Major 1) — both are the same terminal outcome for
- *  the human: no conversation context to consult against. */
-function isReadableFile(path) {
+function reviewSubmitGuidance() {
+    return new ApiError(400, 'invalid_request', 'review approvals use POST /v1/human/reviews/:review_id/submit');
+}
+/** The ticket resolve route accepts only a deck response body. */
+function requireResolveRequest(ctx) {
+    const request = ctx.body;
+    if (request === undefined || request === null || typeof request !== 'object' || Array.isArray(request)) {
+        throw new ApiError(400, 'invalid_request', 'ticket resolve body is required');
+    }
+    const body = request;
+    const fields = Object.keys(body);
+    if (fields.length === 1 && fields[0] === 'responses')
+        return { responses: body['responses'] };
+    if ('feedback' in body)
+        throw reviewSubmitGuidance();
+    throw new ApiError(400, 'invalid_request', 'ticket resolve body requires exactly `responses`');
+}
+function requireDeckTicket(dir) {
+    const deck = existsSync(deckPath(dir));
+    const review = existsSync(reviewPath(dir));
+    if (review && !deck)
+        throw reviewSubmitGuidance();
+    if (!deck || review) {
+        throw new ApiError(400, 'invalid_request', 'ticket has no unambiguous deck kind');
+    }
+}
+function invalidResolveRequest(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new ApiError(400, 'invalid_request', `invalid ticket resolve body: ${detail}`);
+}
+function preflightResolve(validate) {
     try {
-        accessSync(path, fsConstants.R_OK);
-        return true;
-    }
-    catch {
-        return false;
+        return validate();
     }
-}
-/** action:'start' — full trust binding (Major 5) plus a live running current
- *  request, THEN arm the receipted outbox and launch, then a post-launch
- *  currency recheck (M1). Once BOTH trust and request currency are
- *  established, every further failure (missing/unreadable branch, no
- *  captured model, a launch fault) settles the request with a published
- *  error result rather than silently declining — nothing else will ever
- *  publish an answer for a ticket stuck on "consulting…" (Major 1). */
-function handleConsultStart(event) {
-    const trust = verifyConsultTrust(event);
-    if (trust === null)
-        return { handled: false };
-    const { root, dir, rc } = trust;
-    const { request } = readFollowUp(dir);
-    if (request === null || request.state !== 'running' || request.requestId !== event.requestId) {
-        // A cancel may have already raced in, or this event is already stale
-        // (superseded by a newer '?'). Nothing to do — no error is owed here,
-        // since this exact request is no longer the one anything is waiting on.
-        return { handled: false };
-    }
-    const jobId = basename(dir);
-    const node = getNode(jobId);
-    if (node === null) {
-        // Trust + request currency are both established, but the bridge node
-        // itself is gone (pruned/reaped) — there is no cwd/profile context left
-        // to fork from. Settle with a published error rather than silently
-        // declining (Major-4): a bare `handled:false` here left Lane A publishing
-        // nothing and the UI stuck on "consulting…" forever, matching the
-        // missing-branch/missing-model error paths below.
-        submitFollowUpResult(root, dir, {
-            requestId: event.requestId,
-            status: 'error',
-            error: 'the asking conversation no longer exists; follow-up unavailable',
-        });
-        return { handled: true };
-    }
-    // Full trust + current-request validation are both established from here.
-    const provenance = rc.conversation_fork;
-    if (provenance?.status !== 'ready') {
-        submitFollowUpResult(root, dir, {
-            requestId: event.requestId,
-            status: 'error',
-            error: 'no captured conversation branch for this ask; follow-up unavailable',
-        });
-        return { handled: true };
-    }
-    const branchFile = join(dir, provenance.branch_point);
-    if (!isReadableFile(branchFile)) {
-        submitFollowUpResult(root, dir, {
-            requestId: event.requestId,
-            status: 'error',
-            error: 'captured conversation branch is unavailable; follow-up unavailable',
-        });
-        return { handled: true };
-    }
-    const exactModel = provenance.model_spec;
-    const originProfileId = getNode(provenance.source_node_id)?.profile_id ?? null;
-    const forkId = newNodeId();
-    try {
-        // Persist the delivery receipt and every immutable birth fact before the
-        // lifecycle is allowed to create an engine. The node is parent-null (no
-        // subscription/viewer), exact-model locked, and explicitly fork_pending;
-        // reviveNode is the only operation below that can turn the claim into a
-        // broker process.
-        armFollowUpWork({ nodeId: forkId, dir, root, requestId: event.requestId });
-        const { launch } = buildLaunchSpec('general', 'base', {
-            lifecycle: 'terminal',
-            hasManager: false,
-            model: exactModel,
-            modelExact: true,
-            cwd: node.cwd,
-            profileId: originProfileId,
-        });
-        const kickoff = `${buildIdentityAssertionFor({ node_id: forkId, kind: 'general', mode: 'base', fork_from: branchFile })}\n\n` +
-            `${PRIVATE_FOLLOW_UP_FRAMING}\n\n${event.question}`;
-        spawnNode({
-            nodeId: forkId,
-            kind: 'general',
-            mode: 'base',
-            lifecycle: 'terminal',
-            cwd: node.cwd,
-            parent: null,
-            spawnedBy: node.node_id,
-            forkFrom: branchFile,
-            modelOverride: exactModel,
-            humanWorkTarget: { work_kind: 'follow_up', dir, request_id: event.requestId, root },
-            privateForkPhase: 'fork_pending',
-            privateForkRecipe: { kickoff },
-            profile_id: originProfileId,
-            launch,
-        });
-        reviveNode(forkId, { resume: false });
-    }
-    catch (e) {
-        // A synchronous claim/birth failure leaves any armed receipt in place so
-        // publication remains retryable. Publish the user-visible error first and
-        // mark the receipt terminal only after Humanloop confirms that publish.
-        submitFollowUpResult(root, dir, {
-            requestId: event.requestId,
-            status: 'error',
-            error: `consultation failed to launch: ${String(e)}`,
-        });
-        const armedForkId = getActiveFollowUpWorkByRequest(dir, event.requestId)?.node_id ?? null;
-        if (armedForkId !== null)
-            errorFollowUpWork(armedForkId);
-        return { handled: true };
-    }
-    // Post-launch currency recheck (M1): a supersede/cancel that raced the
-    // launch means this fork is already wasted work — cancel it early. The
-    // authoritative safety net is submitFollowUpResult's own conditional
-    // publish (A.4); this just avoids burning a turn on a fork nobody will read.
-    const recheck = readFollowUp(dir);
-    if (recheck.request === null || recheck.request.requestId !== event.requestId || recheck.request.state !== 'running') {
-        transition(forkId, 'cancel');
-        cancelFollowUpWork(forkId);
-    }
-    return { handled: true };
-}
-/** action:'cancel' — the SAME full trust binding as start (Major 5), then
- *  declines ONLY the narrow untrusted case: this exact requestId still
- *  `running` at `dir` (humanloop's `cancelFollowUp` always settles it out of
- *  `running` BEFORE invoking `action:'cancel'`, design §A.4, so a legitimate
- *  event never observes that). It does NOT require `dir`'s CURRENT request to
- *  still equal this requestId (Minor-5) — a delayed cancel legitimately
- *  arrives after a newer `?` has already superseded it, and `findConsultForkId`
- *  keys on `(dir, requestId)` directly, so it can only ever find/cancel the
- *  fork bound to THIS requestId, never a newer one's. `transition(...,
- *  'cancel')` refuses to overwrite a committed final, so a fork that already
- *  delivered is left untouched. */
-function handleConsultCancel(event) {
-    const trust = verifyConsultTrust(event);
-    if (trust === null)
-        return { handled: false };
-    const { dir } = trust;
-    // Trust binding only (Minor-5): humanloop's cancelFollowUp settles the
-    // CURRENT request out of 'running' under `.followup-lock` BEFORE ever
-    // invoking action:'cancel' (design §A.4), so a legitimate cancel event's
-    // OWN requestId is never still the live running one — decline only that
-    // exact case (a stray/forged cancel racing ahead of the lock). Do NOT also
-    // require dir's CURRENT request to still equal this event's requestId: a
-    // delayed cancel legitimately arrives after a newer '?' has already
-    // superseded it, and `findConsultForkId` below keys on `(dir, requestId)`
-    // directly, so it can only ever find/cancel the fork actually bound to
-    // THIS requestId — never a newer one's.
-    const { request } = readFollowUp(dir);
-    if (request !== null && request.requestId === event.requestId && request.state === 'running') {
-        return { handled: false };
-    }
-    const forkId = findConsultForkId(dir, event.requestId);
-    if (forkId === null)
-        return { handled: false };
-    transition(forkId, 'cancel');
-    cancelFollowUpWork(forkId);
-    return { handled: true };
-}
-/** `POST /v1/human/consult` — the follow-up handler body. The event is a
- *  `humanloop.followup-request/v1` (already JSON-parsed by the router). */
-function handleConsult(ctx) {
-    const event = ctx.body;
-    if (event?.schema !== 'humanloop.followup-request/v1') {
-        throw new ApiError(400, 'invalid_request', 'not a humanloop.followup-request/v1 event');
+    catch (error) {
+        throw invalidResolveRequest(error);
     }
-    // Crash-safety net (§B.4): reconcile on every touchpoint, never a timer.
-    reconcileFollowUpWork();
-    // Explicit action union (Major 5) — anything other than the literal
-    // 'start'/'cancel' is declined, never silently treated as a start.
-    if (event.action === 'start')
-        return { status: 200, body: handleConsultStart(event) };
-    if (event.action === 'cancel')
-        return { status: 200, body: handleConsultCancel(event) };
-    return { status: 200, body: { handled: false } };
-}
-// ===========================================================================
-// POST /v1/human/visual — the registered visual handler
-// ===========================================================================
-const VISUAL_CAPABILITY = 'humanloop.visual/v1';
-const PRIVATE_VISUAL_FRAMING = 'Create concise, self-contained Markdown visual context for the supplied interaction. Use inherited history only for facts. Return exactly one Markdown result with `crtr push final`; it returns only to Humanloop Visual.';
-function sameHandler(left, right) {
-    return left !== undefined && JSON.stringify(left) === JSON.stringify(right);
-}
-/** A broker retains its sealed runtime generation across installs. Humanloop
- * freezes that generation's `_visual` argv into the request, while crtrd may
- * already run a newer sibling generation when the human opens the ticket.
- * Accept only a Node invocation of the same leaf from an immutable 64-hex
- * generation beneath the current handler's exact generations directory. The
- * command differs legitimately: CLI registrations use the system Node path,
- * while the daemon runs through crouter's stable copied-Node host. */
-export function trustedCrouterHandler(candidate, current, leaf) {
-    if (sameHandler(candidate, current))
-        return true;
-    if (candidate === undefined)
-        return false;
-    if (basename(candidate.command) !== 'node' && basename(candidate.command) !== basename(current.command))
-        return false;
-    if (candidate.args.length !== 3 || current.args.length !== 3)
-        return false;
-    if (candidate.args[1] !== 'human' || candidate.args[2] !== leaf)
-        return false;
-    if (current.args[1] !== 'human' || current.args[2] !== leaf)
-        return false;
-    const currentEntry = resolve(current.args[0]);
-    const candidateEntry = resolve(candidate.args[0]);
-    const generationsDir = resolve(currentEntry, '..', '..', '..');
-    const currentGeneration = basename(resolve(currentEntry, '..', '..'));
-    const candidateGeneration = basename(resolve(candidateEntry, '..', '..'));
-    const generationId = /^[a-f0-9]{64}$/;
-    if (!generationId.test(currentGeneration) || !generationId.test(candidateGeneration))
-        return false;
-    return candidateEntry === join(generationsDir, candidateGeneration, 'dist', 'cli.js');
-}
-export function trustedCrouterVisualHandler(candidate, current = crouterVisualHandler()) {
-    return trustedCrouterHandler(candidate, current, '_visual');
 }
-function submitVisualError(root, dir, request, error) {
-    submitVisualResult(root, dir, { requestId: request.requestId, generationId: request.generationId, interactionId: request.interactionId, interaction: request.interaction, claimToken: request.claim.token, status: 'error', error: error.slice(0, 8_192) });
+async function handleResolve(ctx) {
+    const nodeId = requireTicketNodeId(ctx);
+    const request = requireResolveRequest(ctx);
+    const dir = ticketDir(nodeId);
+    requireDeckTicket(dir);
+    const responses = preflightResolve(() => validateDeckTicketResponses(dir, request.responses));
+    await resolveDeckTicket(nodeId, responses);
+    return { status: 200, body: { delivered: true, kind: 'deck' } };
 }
-function trustedVisual(event) {
-    if (event.capability !== VISUAL_CAPABILITY || event.owner !== 'crouter')
-        return null;
-    const root = canonicalPath(event.root), dir = canonicalPath(event.dir);
-    if (resolve(dir, '..') !== root || event.ticketId !== basename(dir))
-        return null;
-    if (!listInboxRoots().some((entry) => entry.root === root && entry.owner === 'crouter'))
-        return null;
-    const request = readVisualRequestForEvent(event);
-    if (request === null || !trustedCrouterVisualHandler(request.handler))
-        return null;
-    const rc = readJson(join(dir, 'run.json'));
-    return rc?.mode === 'ask' ? { root, dir, rc, request } : null;
+function hasPublishedTicket(dir) {
+    return existsSync(deckPath(dir)) || existsSync(reviewPath(dir)) || readTicketResult(dir) !== null;
 }
-function currentVisualInteraction(dir, request) {
-    try {
-        const deck = parseDeck(deckPath(dir));
-        const current = deck.interactions.find((interaction) => interaction.id === request.interactionId);
-        return deck.source?.visual === VISUAL_CAPABILITY && current !== undefined && canonicalInteractionJson(current) === canonicalInteractionJson(request.interaction);
-    }
-    catch {
-        return false;
-    }
-}
-function handleVisualStart(event) {
-    const trust = trustedVisual(event);
-    if (trust === null)
-        return { handled: false };
-    const { root, dir, rc, request } = trust;
-    if (!currentVisualInteraction(dir, request) || isResolved(dir))
-        return { handled: false };
-    const provenance = rc.conversation_fork;
-    if (provenance?.status !== 'ready') {
-        submitVisualError(root, dir, request, 'Visual context is unavailable for this ask');
-        return { handled: true };
-    }
-    const branchFile = join(dir, provenance.branch_point);
-    if (!isReadableFile(branchFile)) {
-        submitVisualError(root, dir, request, 'Captured Visual context is unavailable');
-        return { handled: true };
-    }
-    const bridge = getNode(basename(dir));
-    if (bridge === null) {
-        submitVisualError(root, dir, request, 'The asking conversation no longer exists; Visual is unavailable');
-        return { handled: true };
+async function handleCancel(ctx) {
+    const nodeId = requireTicketNodeId(ctx);
+    const request = ctx.body;
+    if (request !== undefined && (typeof request !== 'object' || request === null)) {
+        throw new ApiError(400, 'invalid_request', 'ticket cancel body must be an object');
     }
-    const forkId = newNodeId();
+    const dir = ticketDir(nodeId);
+    const review = getReviewByBridge(nodeId);
     try {
-        const claim = claimVisualWork({ nodeId: forkId, dir, root, requestId: request.requestId, interactionId: request.interactionId, generationId: request.generationId, interactionSnapshot: canonicalInteractionJson(request.interaction), handlerCommand: request.handler.command, handlerArgs: request.handler.args, claimToken: request.claim.token });
-        if (!claim.created)
-            return { handled: true };
-        const originProfileId = getNode(provenance.source_node_id)?.profile_id ?? null;
-        const { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'terminal', hasManager: false, model: provenance.model_spec, modelExact: true, cwd: bridge.cwd, profileId: originProfileId });
-        const kickoff = `${buildIdentityAssertionFor({ node_id: forkId, kind: 'general', mode: 'base', fork_from: branchFile })}\n\n${PRIVATE_VISUAL_FRAMING}\n\nInteraction:\n${canonicalInteractionJson(request.interaction)}`;
-        spawnNode({ nodeId: forkId, kind: 'general', mode: 'base', lifecycle: 'terminal', cwd: bridge.cwd, parent: null, spawnedBy: bridge.node_id, forkFrom: branchFile, modelOverride: provenance.model_spec, humanWorkTarget: { work_kind: 'visual', dir, request_id: request.requestId, root }, privateForkPhase: 'fork_pending', privateForkRecipe: { kickoff }, profile_id: originProfileId, launch, initialStatus: 'canceled' });
-        if (isResolved(dir) || readVisualRequestForEvent(event) === null) {
-            retireVisualWork(dir, request.requestId);
-            return { handled: true };
+        if (review !== null) {
+            if (review.state === 'approved') {
+                throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
+            }
+            const finished = await cancelReview(review.review_id, request ?? {});
+            if (finished.outcome === 'already_settled') {
+                throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
+            }
+            return { status: 200, body: { canceled: true } };
         }
-        // The claim is armed and the node is born inert (Major-3): reviveNode's own
-        // locked gate re-reads this exact claim immediately before launch, inside
-        // the same write-lock as a concurrent cancel's retirement. A throw here
-        // means a cancel won that race and already owns settlement for this
-        // ticket — not a genuine launch fault — so only report/retire when the
-        // claim is still armed after the throw.
-        reviveNode(forkId, { resume: false });
+        // A binding row has no published ticket. It is intentionally
+        // indistinguishable from an unknown node id on this ticket surface.
+        if (!hasPublishedTicket(dir)) {
+            throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+        }
+        await cancelHumanTicket(nodeId, request ?? {});
+        return { status: 200, body: { canceled: true } };
     }
     catch (error) {
-        const stillArmed = getVisualWorkByRequest(dir, request.requestId)?.status === 'visual_armed';
-        if (stillArmed)
-            submitVisualError(root, dir, request, `Visual generation failed to launch: ${String(error)}`);
-        retireVisualWork(dir, request.requestId);
-    }
-    return { handled: true };
-}
-function handleVisualCancel(event) {
-    const trust = trustedVisual(event);
-    if (trust === null)
-        return { handled: false };
-    const { dir, request } = trust;
-    const row = getVisualWorkByRequest(dir, request.requestId);
-    if (row === null)
-        return { handled: true };
-    const exact = row.root === request.root && row.generation_id === request.generationId && row.interaction_id === request.interactionId && row.interaction_snapshot === canonicalInteractionJson(request.interaction) && row.handler_command === request.handler.command && row.handler_args_json === JSON.stringify(request.handler.args) && row.claim_token === request.claim.token;
-    if (!exact)
-        return { handled: false };
-    // Retire before canceling the deliberately inert fork so reconciliation
-    // cannot classify this exact cancellation as a pre-launch claim.
-    retireVisualWork(dir, request.requestId);
-    try {
-        transition(row.node_id, 'cancel');
-    }
-    catch { /* absent or terminal is an acknowledgement */ }
-    try {
-        headlessBrokerHost.teardown(row.node_id);
-    }
-    catch { /* best-effort, mirrors close.ts */ }
-    return { handled: true };
-}
-/** `POST /v1/human/visual` — validates and launches or retires one exact
- *  Humanloop Visual fork. The event is a `humanloop.visual-request-event/v1`
- *  (already JSON-parsed by the router). */
-function handleVisual(ctx) {
-    let event;
-    try {
-        event = parseVisualRequestEvent(ctx.body);
-    }
-    catch {
-        throw new ApiError(400, 'invalid_request', 'not a humanloop.visual-request-event/v1 event');
+        if (error instanceof ApiError)
+            throw error;
+        // Review errors are not part of the retained ticket route's vocabulary.
+        if (error instanceof ReviewOperationError) {
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
+        }
+        throw new ApiError(500, 'internal', 'the ticket could not be canceled');
     }
-    reconcileVisualWork();
-    return { status: 200, body: event.action === 'start' ? handleVisualStart(event) : handleVisualCancel(event) };
 }
 export const humanRoutes = [
-    { method: 'POST', pattern: '/v1/canvas/consults', handler: handleCreate },
-    { method: 'GET', pattern: '/v1/canvas/consults', handler: handleList },
     { method: 'POST', pattern: '/v1/human/bridge', handler: handleCreateBridge },
-    { method: 'POST', pattern: '/v1/human/deliver', handler: handleDeliver },
-    { method: 'POST', pattern: '/v1/human/consult', handler: handleConsult },
-    { method: 'POST', pattern: '/v1/human/visual', handler: handleVisual },
+    { method: 'POST', pattern: '/v1/human/tickets/:node_id/resolve', handler: handleResolve },
+    { method: 'POST', pattern: '/v1/human/tickets/:node_id/cancel', handler: handleCancel },
 ];