@north-light/crouter 0.3.154

package/dist/commands/human/queue.js

@@ -0,0 +1,531 @@
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { ApiError } from '../../api/index.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { nodeDir, nodesRoot } from '../../core/canvas/paths.js';
+import { paginate } from '../../core/pagination.js';
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { scanInbox, parseDeck, deckPath, reviewPath, isResolved, readJson, claimTicket, completeDeck, cancelTicket, listInboxRoots, } from '@crouton-kit/humanloop';
+import { crouterFocusHandler } from './shared.js';
+import { focusViewer } from '../node.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 `_focus` containment/registration checks
+ *  compare like against like regardless of symlinked path components. */
+function canonicalPath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function toRef(n) {
+    return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent };
+}
+/** The canvas roster, fetched ONCE per leaf run through the API and threaded
+ *  into the sync provenance helpers below (they used to call `listNodes()`/
+ *  `getNode()` synchronously; the API surface is async, so the fetch is hoisted
+ *  to the leaf and the helpers read the pre-fetched array/map). */
+async function fetchNodeRefs() {
+    return (await cliClient().listNodes()).map(toRef);
+}
+/** Look up one node by id, mapping the API's 404 to `null`. */
+async function getNodeOrNull(id) {
+    try {
+        return await cliClient().getNode(id);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        rethrowAsCliError(err);
+    }
+}
+function resolveConversation(asking, nodes) {
+    if (asking === undefined)
+        return undefined;
+    const byId = new Map(nodes.map((n) => [n.node_id, n]));
+    let cur = asking;
+    const seen = new Set();
+    while (cur.parent !== null && !seen.has(cur.node_id)) {
+        seen.add(cur.node_id);
+        const parent = byId.get(cur.parent);
+        if (parent === undefined)
+            break;
+        cur = parent;
+    }
+    return cur;
+}
+function readableSourceLabel(source) {
+    const sessionName = source?.sessionName?.trim();
+    if (sessionName !== undefined && sessionName !== '')
+        return sessionName;
+    const askedBy = source?.askedBy?.trim();
+    return askedBy === '' ? undefined : askedBy;
+}
+function askingNodeFor(jobId, byId) {
+    const bridge = byId.get(jobId);
+    if (bridge?.parent !== undefined && bridge.parent !== null)
+        return byId.get(bridge.parent) ?? bridge;
+    return bridge;
+}
+function summarizeTicket(summary, nodes, byId) {
+    const jobId = basename(summary.dir);
+    // Every crouter ticket lives directly in its bridge node directory. A stale
+    // ticket whose node was reaped is intentionally absent from the canvas view.
+    if (!byId.has(jobId))
+        return null;
+    const asking = askingNodeFor(jobId, byId);
+    const conversation = resolveConversation(asking, nodes);
+    const interactionCount = summary.kind === 'deck' ? readJson(deckPath(summary.dir))?.interactions.length : undefined;
+    const sourceLabel = readableSourceLabel(summary.source);
+    return {
+        id: summary.id,
+        job_id: jobId,
+        dir: summary.dir,
+        title: summary.title,
+        subtitle: summary.subtitle,
+        kind: summary.kind === 'deck' ? summary.interactionKind ?? null : 'review',
+        blocked_since: summary.blockedSince,
+        ...(summary.claim !== undefined ? { claim_owner: summary.claim.owner } : {}),
+        ...(sourceLabel !== undefined ? { source_label: sourceLabel } : {}),
+        ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd } : {}),
+        ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
+        ...(interactionCount !== undefined ? { interaction_count: interactionCount } : {}),
+    };
+}
+function interactionDirForJob(jobId, byId) {
+    if (byId.has(jobId))
+        return { dir: nodeDir(jobId) };
+    throw new InputError({ error: 'not_found', message: `no interaction node: ${jobId}`, field: 'job_id', next: 'Pass a job_id from `crtr human list`.' });
+}
+// ---------------------------------------------------------------------------
+// list (read-only, paginated)
+// ---------------------------------------------------------------------------
+export const humanList = defineLeaf({
+    name: 'list',
+    description: 'enumerate pending interactions',
+    whenToUse: 'discovering what is blocked on a human',
+    help: {
+        name: 'human list',
+        summary: 'paginated list of pending interactions, oldest first',
+        params: [
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20, max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: "Opaque token from a previous response's next_cursor. Omit on first call." },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, subtitle, kind, blocked_since}; subtitle is the required authored one-sentence summary. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title, interaction_count. Oldest first.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Pass on the next call to continue. null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Total pending interactions.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const limitRaw = input['limit'];
+        const limit = Math.min(Math.max(1, limitRaw), 100);
+        const cursor = input['cursor'];
+        const nodes = await fetchNodeRefs();
+        const byId = new Map(nodes.map((n) => [n.node_id, n]));
+        const raw = scanInbox([nodesRoot()]);
+        const items = raw
+            .flatMap((s) => {
+            const item = summarizeTicket(s, nodes, byId);
+            return item === null ? [] : [item];
+        })
+            .sort((a, b) => {
+            const ka = `${a.blocked_since}|${a.id}`;
+            const kb = `${b.blocked_since}|${b.id}`;
+            return ka < kb ? -1 : ka > kb ? 1 : 0;
+        });
+        const page = paginate(items, { limit, cursor }, {
+            defaultLimit: 20,
+            maxLimit: 100,
+            keyOf: (i) => `${i.blocked_since}|${i.id}`,
+            total: 'count',
+        });
+        return { items: page.items, next_cursor: page.next_cursor, total: page.total };
+    },
+});
+// ---------------------------------------------------------------------------
+// deck detail (read-only)
+// ---------------------------------------------------------------------------
+export const humanDeck = defineLeaf({
+    name: 'deck',
+    description: 'read one pending humanloop deck',
+    whenToUse: 'you need the full questions/options for a pending human interaction',
+    help: {
+        name: 'human deck',
+        summary: 'read full pending deck detail for one human interaction job',
+        params: [{ kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' }],
+        output: [
+            { name: 'id', type: 'string', required: true, constraint: 'Interaction job id.' },
+            { name: 'interactions', type: 'object[]', required: true, constraint: 'Deck interactions with required authored subtitles, bodies, options, and freetext policy.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads deck.json from the interaction dir resolved through the canvas node cwd.'],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const nodes = await fetchNodeRefs();
+        const byId = new Map(nodes.map((n) => [n.node_id, n]));
+        const { dir } = interactionDirForJob(jobId, byId);
+        if (isResolved(dir)) {
+            throw new InputError({ error: 'already_resolved', message: `interaction already resolved: ${jobId}`, field: 'job_id', next: 'Use `crtr human list` for pending interactions.' });
+        }
+        let deck;
+        try {
+            deck = parseDeck(deckPath(dir));
+        }
+        catch {
+            throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
+        }
+        const asking = askingNodeFor(jobId, byId);
+        const conversation = resolveConversation(asking, nodes);
+        const sourceLabel = readableSourceLabel(deck.source);
+        const first = deck.interactions[0];
+        return {
+            id: jobId,
+            title: deck.title,
+            kind: first.kind ?? null,
+            subtitle: first.subtitle,
+            blocked_since: deck.source?.blockedSince ?? null,
+            ...(sourceLabel !== undefined ? { source_label: sourceLabel } : {}),
+            ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd } : {}),
+            ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
+            interaction_count: deck.interactions.length,
+            interactions: deck.interactions.map((it) => ({
+                id: it.id,
+                kind: it.kind ?? null,
+                title: it.title,
+                subtitle: it.subtitle,
+                ...(it.body !== undefined ? { body: it.body } : {}),
+                options: it.options.map((o) => ({ id: o.id, label: o.label, ...(o.description !== undefined ? { description: o.description } : {}) })),
+                allow_freetext: it.allowFreetext ?? false,
+                ...(it.preAnswered?.selectedOptionId !== undefined ? { default_option_id: it.preAnswered.selectedOptionId } : {}),
+            })),
+        };
+    },
+});
+function parseResolveBody(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Pass {"responses":[{"interaction_id":"..."}]} on stdin.' });
+    }
+    if (!Array.isArray(parsed.responses)) {
+        throw new InputError({ error: 'invalid_field', message: 'responses must be an array', field: 'responses', next: 'Pass {"responses":[{"interaction_id":"...","selected_option_ids":["..."]}]}.' });
+    }
+    return parsed.responses.map((r) => {
+        const id = r.interaction_id ?? r.id;
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'invalid_field', message: 'each response needs interaction_id', field: 'responses', next: 'Include interaction_id for every response.' });
+        }
+        const selectedOptionIds = r.selected_option_ids ?? r.selectedOptionIds;
+        const selectedOptionId = r.selected_option_id ?? r.selectedOptionId;
+        return {
+            id,
+            ...(selectedOptionIds !== undefined ? { selectedOptionIds } : {}),
+            ...(selectedOptionId !== undefined ? { selectedOptionId } : {}),
+            ...(r.freetext !== undefined ? { freetext: r.freetext } : {}),
+            ...(r.optionComments !== undefined ? { optionComments: r.optionComments } : {}),
+        };
+    });
+}
+/**
+ * Translate web-shaped answers into humanloop's response contract. Web clients
+ * always send `selectedOptionIds` (an array) for every option pick, but
+ * humanloop's strict deck validator rejects an array on any non-multiSelect
+ * interaction. For a single-select interaction we faithfully fold a
+ * single-element array down to `selectedOptionId` (deterministic given the
+ * deck's own multiSelect flag — not a lenient guess). Multi-select and freetext
+ * responses pass through untouched; an unreadable deck is left to completeDeck.
+ */
+function coerceSingleSelect(responses, dir) {
+    const deck = readJson(deckPath(dir));
+    if (deck === null || deck === undefined)
+        return responses;
+    return coerceSingleSelectAgainst(responses, deck);
+}
+/** Pure core of {@link coerceSingleSelect}, split out so it is testable without
+ *  a deck.json on disk. */
+export function coerceSingleSelectAgainst(responses, deck) {
+    const isMulti = new Map(deck.interactions.map((it) => [it.id, it.multiSelect === true]));
+    return responses.map((r) => {
+        if (isMulti.get(r.id) === true)
+            return r;
+        if (r.selectedOptionId !== undefined || r.selectedOptionIds === undefined)
+            return r;
+        if (r.selectedOptionIds.length !== 1)
+            return r; // 0 or >1 stays → humanloop rejects
+        const { selectedOptionIds, ...keep } = r;
+        return { ...keep, selectedOptionId: selectedOptionIds[0] };
+    });
+}
+export const humanResolve = defineLeaf({
+    name: 'resolve',
+    description: 'resolve one humanloop deck from stdin answers',
+    whenToUse: 'a browser or local tool is submitting answers for a pending human interaction; this delegates to the humanloop finalize/completion path',
+    tier: 'hidden',
+    help: {
+        name: 'human resolve',
+        summary: 'claim a pending deck through humanloop, finalize it with the given answers, and let the completion boundary deliver back to the asking node',
+        params: [
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:[{interaction_id, selected_option_ids?, freetext?}]}.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call won and finalized the deck. Delivery to the asking node happens asynchronously at humanloop\'s completion boundary and may lag or fail independently of this result.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'Interaction job id.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'already_resolved or claimed when resolved is false.' },
+        ],
+        outputKind: 'object',
+        effects: ['Claims the ticket via humanloop, finalizes response.json through humanloop\'s exclusive publish, and lets humanloop invoke crouter\'s registered completion handler. Never writes response.json itself.'],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const nodes = await fetchNodeRefs();
+        const byId = new Map(nodes.map((n) => [n.node_id, n]));
+        const { dir } = interactionDirForJob(jobId, byId);
+        if (!existsSync(deckPath(dir))) {
+            throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
+        }
+        const responses = coerceSingleSelect(parseResolveBody(input['body']), dir);
+        if (isResolved(dir))
+            return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+        const claim = claimTicket(dir);
+        if (claim === null) {
+            return { resolved: false, job_id: jobId, reason: isResolved(dir) ? 'already_resolved' : 'claimed' };
+        }
+        let won;
+        try {
+            ({ won } = await completeDeck(dir, responses, claim.token));
+        }
+        catch (e) {
+            throw new InputError({ error: 'invalid_field', message: String(e), field: 'responses', next: 'Use interaction/option ids from `crtr human deck <job_id> --json`.' });
+        }
+        if (!won)
+            return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+        // Finalization won. Delivery back to the asking node is humanloop's
+        // completion-boundary responsibility (may lag or fail → delivery-error.json),
+        // so we do NOT claim delivery here — only that the deck was finalized.
+        return { resolved: true, job_id: jobId };
+    },
+});
+// ---------------------------------------------------------------------------
+// cancel — retract a pending ask/review
+// ---------------------------------------------------------------------------
+export const humanCancel = defineLeaf({
+    name: 'cancel',
+    description: 'retract a pending ask/review',
+    whenToUse: 'a question went stale before the human answered',
+    help: {
+        name: 'human cancel',
+        summary: 'retract a pending ask/review you posed — drops it from the human inbox and retires the bridge node. Reach for this the moment a question goes stale (you answered it yourself, the situation changed) so a human is not left resolving a prompt whose answer no longer matters',
+        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit through humanloop\'s exclusive final publish; whichever wins is authoritative. The agent that posed the deck is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
+        params: [
+            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/review.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to subscribers explaining why it was retracted.' },
+        ],
+        output: [
+            { name: 'canceled', type: 'boolean', required: true, constraint: 'True when the interaction was retracted; false when there was nothing live to cancel (already answered/canceled).' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The interaction node id.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'Why nothing was canceled (e.g. "already_resolved"), present when canceled is false.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Races a canceled response.json through humanloop so the interaction drops out of the human inbox.',
+            'On a winning cancellation, humanloop invokes crouter\'s completion handler, which retires the bridge node and drops a deferred no-answer note to waiting subscribers other than the caller.',
+        ],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const reason = input['reason'];
+        const node = await getNodeOrNull(jobId);
+        if (node === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no interaction node: ${jobId}`,
+                field: 'job_id',
+                next: 'Pass the job_id from human ask/review, or list pending with `crtr human list`.',
+            });
+        }
+        const idir = nodeDir(jobId);
+        // Nothing live to cancel: already answered/canceled/retired, or the ticket
+        // never carried a request descriptor humanloop can cancel.
+        const hasDescriptor = existsSync(deckPath(idir)) || existsSync(reviewPath(idir));
+        if (node.status === 'done' || node.status === 'dead' || node.status === 'canceled' || isResolved(idir) || !hasDescriptor) {
+            return { canceled: false, job_id: jobId, reason: 'already_resolved' };
+        }
+        const actor = process.env['CRTR_NODE_ID'] ?? 'human';
+        const { status } = await cancelTicket(idir, { ...(reason !== undefined && reason !== '' ? { reason } : {}), actor });
+        if (status === 'already_resolved') {
+            return { canceled: false, job_id: jobId, reason: 'already_resolved' };
+        }
+        // The winning cancellation dispatched completion → `_deliver` synchronously
+        // retired the bridge and notified subscribers. Nothing to do here.
+        return { canceled: true, job_id: jobId };
+    },
+    render: (r) => r['canceled'] === true
+        ? `Canceled human interaction ${r['job_id']} — it left the human inbox and subscribers were notified no answer is coming.`
+        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
+});
+// ---------------------------------------------------------------------------
+// _deliver / _consult / _visual (hidden completion handlers; not listed in
+// branch help) — thin forwarders to crtrd.
+//
+// humanloop invokes `node dist/cli.js human _deliver|_consult|_visual` with the
+// event JSON on stdin (registered via `registerCrouterRoot`). The handler body
+// — every canvas mutation (spawnNode/reviveNode/transition/pushFinal/arm/claim/
+// retire/reconcile) plus the FULL trust binding re-verification — lives
+// server-side in `src/daemon/api/handlers/human.ts`. These leaves just parse
+// the stdin event and POST it to the daemon, which re-verifies the trust
+// binding before acting. Keeping ZERO canvas imports here is what lets the CLI
+// import graph stay clear of canvas.db (spec §1/§10).
+// ---------------------------------------------------------------------------
+/** Parse a humanloop event off stdin. A malformed body is the caller's error
+ *  (humanloop always sends valid JSON), surfaced as a clean InputError rather
+ *  than a raw SyntaxError. */
+function parseEvent(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (e) {
+        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Only humanloop invokes this handler.' });
+    }
+}
+export const humanDeliver = defineLeaf({
+    name: '_deliver',
+    tier: 'hidden',
+    help: {
+        name: 'human _deliver',
+        summary: 'internal: the registered humanloop completion handler — turns a resolved/canceled ticket into the existing pushFinal delivery and bridge finalization',
+        params: [
+            { kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.completion/v1 event JSON on stdin. Not for manual use.' },
+        ],
+        output: [{ name: 'delivered', type: 'boolean', required: true, constraint: 'True once the bridge is delivered/retired (or already terminal).' }],
+        outputKind: 'object',
+        effects: ['Reads the completion event, forwards it to crtrd, which verifies root registration/containment then pushFinals the answer (ask/review) or retires the bridge (canceled). Idempotent: replay after a crash is safe.'],
+    },
+    run: async (input) => {
+        const event = parseEvent(input['body']);
+        try {
+            return await cliClient().deliverHuman(event);
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+export const humanConsult = defineLeaf({
+    name: '_consult',
+    tier: 'hidden',
+    help: {
+        name: 'human _consult',
+        summary: 'internal: the registered humanloop follow-up handler — verifies capability + a live running request, then launches (or cancels) a private consult fork answering privately back to the ticket',
+        params: [
+            { kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.followup-request/v1 event JSON on stdin. Not for manual use.' },
+        ],
+        output: [
+            {
+                name: 'handled',
+                type: 'boolean',
+                required: true,
+                constraint: 'True when the start/cancel action was actually acted on; false when trust/currency checks rejected it as stale (already superseded/canceled/unregistered/not an ask ticket). Humanloop always gets a fast exit 0 either way — this never throws for a stale event.',
+            },
+        ],
+        outputKind: 'object',
+        effects: [
+            "action:start — crtrd verifies owner+capability+registration identity+run.json(ask)+a live running request, arms a receipted outbox row, launches a detached parent=null consult fork at the exact captured model from the captured branch point, then re-checks the request is still current and cancels the fork if it was superseded/canceled during launch.",
+            'action:cancel — crtrd cancels the request-bound consult fork (if any) and marks its outbox row canceled.',
+            'Once trust and request currency are both established, a missing/unreadable captured branch, a missing captured model, or a synchronous launch fault all publish an error follow-up result immediately instead of declining silently, so the ticket never sticks on "consulting\u2026".',
+        ],
+    },
+    run: async (input) => {
+        const event = parseEvent(input['body']);
+        try {
+            return await cliClient().consultHuman(event);
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+export const humanVisual = defineLeaf({
+    name: '_visual',
+    tier: 'hidden',
+    help: {
+        name: 'human _visual',
+        summary: 'internal: validates and launches or retires one exact Humanloop Visual fork',
+        params: [{ kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.visual-request-event/v1 event JSON. Not for manual use.' }],
+        output: [{ name: 'handled', type: 'boolean', required: true, constraint: 'True when the exact Visual delivery was acknowledged.' }],
+        outputKind: 'object',
+        effects: ['Forwards the event to crtrd, which creates at most one lifecycle-owned exact-model Visual child, or retires only its immutable matching child.'],
+    },
+    run: async (input) => {
+        const event = parseEvent(input['body']);
+        try {
+            return await cliClient().visualHuman(event);
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// _focus (hidden inbox-source handler; not listed in branch help)
+//
+// Unlike _deliver/_consult/_visual, focus is a pure VIEWER/tmux placement — it
+// reveals the originating conversation beside the inbox popup pane. tmux
+// placement is client-side in this architecture (crtrd owns canvas state, not
+// the viewer surface), so this leaf stays in the CLI: the canvas read routes
+// through `getNodeOrNull` (the API) and the revive + view.sock wait happen
+// inside `focusViewer` via `cliClient().ensureAttach()`.
+// ---------------------------------------------------------------------------
+export const humanFocus = defineLeaf({
+    name: '_focus',
+    tier: 'hidden',
+    help: {
+        name: 'human _focus',
+        summary: 'internal: reveal the conversation that created a humanloop ticket',
+        params: [{ kind: 'stdin', name: 'body', required: true, constraint: 'A humanloop.focus/v1 event JSON on stdin. Not for manual use.' }],
+        output: [{ name: 'focused', type: 'boolean', required: true, constraint: 'True once the originating conversation viewer is visible.' }],
+        outputKind: 'object',
+        effects: ['Verifies the registered ticket and focuses its source node beside the tmux pane underneath the inbox popup, opening a viewer when needed.'],
+    },
+    run: async (input) => {
+        const event = JSON.parse(input['body']);
+        if (event.schema !== 'humanloop.focus/v1') {
+            throw new InputError({ error: 'invalid_field', message: 'not a humanloop.focus/v1 event', field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        const root = canonicalPath(event.root);
+        const dir = canonicalPath(event.dir);
+        if (resolve(dir, '..') !== root || basename(dir) !== event.ticketId) {
+            throw new InputError({ error: 'invalid_field', message: 'focus event does not identify a ticket directly beneath its root', field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        const registration = listInboxRoots().find((candidate) => candidate.root === root && candidate.owner === 'crouter');
+        if (registration === undefined || JSON.stringify(registration.focusHandler) !== JSON.stringify(crouterFocusHandler())) {
+            throw new InputError({ error: 'invalid_field', message: `root has no trusted crouter focus handler: ${root}`, field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        if (!/^%\d+$/.test(event.targetPane)) {
+            throw new InputError({ error: 'invalid_field', message: 'focus event has an invalid tmux target pane', field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        const bridge = await getNodeOrNull(event.ticketId);
+        const sourceNodeId = bridge?.parent;
+        if (sourceNodeId === null || sourceNodeId === undefined || sourceNodeId === '') {
+            throw new InputError({ error: 'not_found', message: 'ticket has no originating canvas conversation', field: 'stdin', next: 'Close the inbox normally; this ticket was created outside a canvas conversation.' });
+        }
+        const source = await getNodeOrNull(sourceNodeId);
+        if (source === null || source.kind === 'human' || (source.status !== 'active' && source.status !== 'idle')) {
+            throw new InputError({ error: 'not_focusable', message: `originating conversation ${sourceNodeId} is no longer live`, field: 'stdin', next: 'Close the inbox normally; completed conversations are available through canvas history.' });
+        }
+        const result = await focusViewer(sourceNodeId, { pane: event.targetPane, cwd: source.cwd, name: source.name });
+        if (!result.focused) {
+            throw new InputError({ error: 'focus_failed', message: `could not bring originating conversation ${sourceNodeId} into view`, next: 'Close the inbox and focus the node from the canvas.' });
+        }
+        return { focused: true };
+    },
+});

package/dist/commands/human/shared.d.ts

@@ -0,0 +1,80 @@
+import type { CompletionHandler } from '@crouton-kit/humanloop';
+export declare const DECK_SCHEMA_HINT: string;
+/**
+ * Crouter's private per-interaction record. Reduced to the delivery essentials:
+ * the mode `_deliver` dispatches on and the bridge node id it delivers back to.
+ * Humanloop owns every public request/result/output path (deck.json,
+ * response.json, review.json); crouter never records pane ids or output paths.
+ *
+ * Every ask records an immutable conversation-fork disposition before ticket
+ * publication. A failed capture never suppresses the primary ask: it records an
+ * explicit unavailable reason instead of falling back to live-session reads.
+ */
+export type ConversationFork = {
+    status: 'ready';
+    source_node_id: string;
+    source_file: string;
+    source_session_id: string;
+    leaf_id: string;
+    model_spec: string;
+    branch_point: 'branch-point.jsonl';
+    captured_at: string;
+} | {
+    status: 'unavailable';
+    reason: 'no_origin' | 'broker_unavailable' | 'invalid_coordinates' | 'invalid_model' | 'materialization_failed';
+    detail?: string;
+    captured_at: string;
+};
+export interface RunRecord {
+    mode: 'ask' | 'notify' | 'review';
+    job_id?: string;
+    conversation_fork?: ConversationFork;
+}
+export declare function resolveMaxPanes(): number;
+/**
+ * The direct-exec completion handler humanloop runs when a crouter ticket
+ * resolves, fed the completion event on stdin. The argv is absolute and
+ * PATH/cwd-independent — never a `crtr` shell string — and, critically, must
+ * actually EXECUTE in both crouter contexts:
+ *
+ * - Built (`dist/cli.js` present): `node <abs>/dist/cli.js human _deliver`.
+ * - Dev/tsx (only `src/cli.ts` on disk): plain `node` cannot run the `.ts`
+ *   entry — its mandatory `.js`-extension ESM imports have no `.js` sibling on
+ *   disk, so Node's type-stripping fails at the first relative import. So we
+ *   register tsx's ESM loader first (`node --import <abs tsx/esm> src/cli.ts …`),
+ *   with the tsx entry resolved to an absolute file URL so the handler stays
+ *   cwd-independent when humanloop invokes it. tsx is necessarily present here
+ *   because crouter itself is running under it.
+ *
+ * Throws loudly when neither entry exists rather than registering an argv that
+ * humanloop would retry forever.
+ */
+export declare function crouterDeliverHandler(): CompletionHandler;
+/**
+ * The direct-exec follow-up handler humanloop runs when the human presses `?`
+ * on a pending crouter ticket (design-followup-consult-v2.md §B.5/§B.7) —
+ * mirrors `crouterDeliverHandler()` exactly (same dual dist/tsx entry
+ * resolution) but targets the hidden `human _consult` leaf. Its presence on
+ * the root registration is the ONLY signal humanloop's UI uses to offer `?`,
+ * and `human _consult`'s own trust check (M3) requires the registration's
+ * `followUpHandler` to be this exact argv shape — a `human _consult` entry
+ * inside some sealed runtime generation — so this must stay the same shape as
+ * what `registerCrouterRoot` attaches.
+ */
+export declare function crouterConsultHandler(): CompletionHandler;
+/** The focus handler invoked when the human asks the inbox popup to return to
+ * the conversation that created its selected ticket. */
+export declare function crouterFocusHandler(): CompletionHandler;
+/** The frozen Visual handler. Like the other root handlers, this resolves the
+ * actual installed or tsx CLI entry rather than depending on PATH. */
+export declare function crouterVisualHandler(): CompletionHandler;
+/**
+ * Register the canvas node root with humanloop as owner `crouter`, attaching
+ * the completion, follow-up, Visual, and focus handlers. Every ticket is a
+ * direct child named for its bridge node, so node lifetime is ticket lifetime.
+ * This also completes the hard cut from stale per-cwd registrations — but
+ * never by stranding live tickets: unresolved tickets in an outgoing root are
+ * swept into the current root first, and a root that cannot be fully swept
+ * stays registered so its tickets remain reachable.
+ */
+export declare function registerCrouterRoot(): string;