@north-light/crouter 0.3.154

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

@@ -0,0 +1,741 @@
+// 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';
+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);
+    }
+}
+// ===========================================================================
+// POST/GET /v1/canvas/consults — consult-outbox arm/list (the canvas primitive)
+// ===========================================================================
+/** `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') {
+        throw new ApiError(400, 'invalid_request', 'bridge kind must be "human"');
+    }
+    if (typeof cwd !== 'string' || cwd === '') {
+        throw new ApiError(400, 'invalid_request', 'bridge body requires `cwd`');
+    }
+    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');
+    }
+    // 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 } };
+    }
+    // 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).
+// ===========================================================================
+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) {
+    try {
+        accessSync(path, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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');
+    }
+    // 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) });
+}
+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 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 };
+    }
+    const forkId = newNodeId();
+    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 };
+        }
+        // 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 });
+    }
+    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');
+    }
+    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 },
+];