@crouton-kit/crouter 0.3.82 → 0.3.83

package/dist/commands/human/queue.js

@@ -6,166 +6,21 @@ import { paginate } from '../../core/pagination.js';
 import { getNode, listNodes, subscribersOf } from '../../core/canvas/index.js';
 import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
-import { closeSync, existsSync, linkSync, openSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { openInbox, scanInbox, parseDeck, deckPath, responsePath, progressPath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
-import { killPane } from './shared.js';
-// ---------------------------------------------------------------------------
-// stranded-answer healing
-// ---------------------------------------------------------------------------
-/** A deterministic one-line-per-interaction summary, mirroring humanloop's
- *  `<id>: <option>[ — <freetext>]` shape. Used when reconstructing a
- *  ResolutionEnvelope from a bare on-disk response.json (which stores only
- *  `{responses, completedAt}`), so a healed deliver-back reads like the live one. */
-function summarizeResponses(responses, deck) {
-    const interactions = new Map((deck?.interactions ?? []).map((it) => [it.id, it]));
-    return responses
-        .map((r) => {
-        const it = interactions.get(r.id);
-        let picked = '';
-        if (r.selectedOptionIds !== undefined) {
-            picked = r.selectedOptionIds
-                .map((id) => {
-                const label = it?.options.find((o) => o.id === id)?.label ?? id;
-                const note = r.optionComments?.[id];
-                return typeof note === 'string' && note.trim() !== '' ? `${label} ("${note.trim()}")` : label;
-            })
-                .join(', ');
-        }
-        else if (r.selectedOptionId !== undefined) {
-            picked = it?.options.find((o) => o.id === r.selectedOptionId)?.label ?? r.selectedOptionId;
-        }
-        const ft = typeof r.freetext === 'string' && r.freetext.trim() !== '' ? ` — ${r.freetext.trim()}` : '';
-        return `${it?.title ?? r.id}: ${picked}${ft}`;
-    })
-        .join('\n');
-}
-/** Deliver-back + reap an interaction whose answer is on disk but was never
- *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
- *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
- *  a human draining via `crtr human inbox`, which writes response.json directly
- *  and never calls pushFinal), the answer strands and the bridge node leaks.
- *
- *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
- *  (active|idle) AND its interaction is resolved on disk — so it never
- *  double-delivers an interaction the `_run` worker already finalized (pushFinal
- *  flips status=done). Reconstructs the same pushFinal body `_run` would have
- *  emitted, per mode; a canceled-on-disk response reaps the node without
- *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
-export async function finalizeResolvedInteraction(jobId, claim) {
-    const firstNode = getNode(jobId);
-    if (firstNode === null)
-        return false;
-    const idir = interactionDir(jobId, firstNode.cwd);
-    const ownedClaim = claim ?? acquireInteractionClaim(idir, jobId, { allowResolved: true });
-    if (ownedClaim === 'already_resolved' || ownedClaim === 'claimed')
-        return false;
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { scanInbox, parseDeck, deckPath, reviewPath, isResolved, readJson, readTicketResult, claimTicket, completeDeck, cancelTicket, listInboxRoots, } from '@crouton-kit/humanloop';
+/** 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 {
-        const node = getNode(jobId);
-        if (node === null)
-            return false;
-        if (node.status !== 'active' && node.status !== 'idle')
-            return false;
-        if (!isResolved(idir))
-            return false;
-        const rc = readJson(join(idir, 'run.json'));
-        if (rc === null)
-            return false;
-        const resp = readJson(responsePath(idir));
-        if (resp === null)
-            return false;
-        // Canceled out-of-band (a raw canceled response.json, not via `human cancel`):
-        // there is no answer to deliver — just reap the node and tell waiting
-        // subscribers no answer is coming, the same quiet deferred note `human cancel`
-        // emits. (`finalize` is legal from active|idle; the status guard above holds.)
-        if (resp['canceled'] === true) {
-            transition(jobId, 'finalize');
-            const note = typeof resp['reason'] === 'string' && resp['reason'] !== '' ? ` — ${resp['reason']}` : '';
-            for (const sub of subscribersOf(jobId)) {
-                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 true;
-        }
-        const responses = resp['responses'] ?? [];
-        const completedAt = resp['completedAt'] ?? new Date().toISOString();
-        let deck;
-        try {
-            deck = parseDeck(deckPath(idir));
-        }
-        catch {
-            deck = undefined;
-        }
-        const summary = summarizeResponses(responses, deck);
-        // ask (and any other answered deck): the full ResolutionEnvelope shape.
-        const env = {
-            summary,
-            responsePath: responsePath(idir),
-            schema: 'humanloop.response/v2',
-            responses,
-            completedAt,
-        };
-        await pushFinal(jobId, JSON.stringify(env));
-        return true;
+        return realpathSync(p);
     }
-    finally {
-        if (claim === undefined)
-            ownedClaim.release();
+    catch {
+        return resolve(p);
     }
 }
-/** Sweep every interaction under the cwd's interactions root and deliver-back +
- *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
- *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
-export async function healStrandedInteractions(cwd) {
-    const root = interactionsRoot(cwd);
-    if (!existsSync(root))
-        return 0;
-    let healed = 0;
-    for (const ent of readdirSync(root, { withFileTypes: true })) {
-        if (!ent.isDirectory())
-            continue;
-        if (await finalizeResolvedInteraction(ent.name))
-            healed++;
-    }
-    return healed;
-}
-// ---------------------------------------------------------------------------
-// inbox (human-invoked, blocking)
-// ---------------------------------------------------------------------------
-export const humanInbox = defineLeaf({
-    name: 'inbox',
-    description: 'interactively drain pending interactions',
-    whenToUse: 'a human is clearing the queue at their terminal',
-    help: {
-        name: 'human inbox',
-        summary: 'interactively drain pending interactions at your own terminal',
-        params: [],
-        inputNote: 'No input. Run this at a human terminal — it blocks until the backlog is drained or you quit.',
-        output: [
-            { name: 'drained', type: 'boolean', required: true, constraint: 'True once the loop returns.' },
-            { name: 'delivered', type: 'integer', required: true, constraint: 'How many answered-but-undelivered interactions were delivered back to their askers and reaped.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Resolves pending interactions in the per-project interactions root via the TUI.',
-            'Delivers any answered-but-undelivered interaction back to its asking node and reaps the bridge node (the deliver-back the detached _run worker would have done).',
-        ],
-    },
-    run: async () => {
-        await openInbox({ roots: [interactionsRoot(process.cwd())] });
-        // humanloop's openInbox() writes response.json but never calls pushFinal — so a
-        // deck drained here would strand (no answer-back, leaked bridge node). Heal
-        // every resolved-but-live interaction: deliver its answer to the asker + reap.
-        const delivered = await healStrandedInteractions(process.cwd());
-        return { drained: true, delivered };
-    },
-});
 function allInteractionRoots() {
     const roots = new Set();
     roots.add(interactionsRoot(process.cwd()));
@@ -191,8 +46,8 @@ function resolveConversation(asking, nodes) {
     }
     return cur;
 }
-function askingNodeFor(jobId, deck, dir, nodes) {
-    const stamped = deck?.source?.nodeId;
+function askingNodeFor(jobId, dir, source, nodes) {
+    const stamped = source?.nodeId;
     if (stamped !== undefined && stamped !== '') {
         const found = nodes.find((n) => n.node_id === stamped);
         if (found !== undefined)
@@ -211,22 +66,25 @@ function askingNodeFor(jobId, deck, dir, nodes) {
     }
     return bridge !== null ? { node_id: bridge.node_id, name: bridge.name, cwd: bridge.cwd, parent: bridge.parent ?? null } : undefined;
 }
-function summarizeDeckItem(item, deck, nodes) {
-    const jobId = basename(item.dir);
+function summarizeTicket(summary, nodes) {
+    const jobId = basename(summary.dir);
+    // A bare-shell ticket with no canvas node is intentionally omitted from the
+    // canvas-scoped list; the popup still shows it globally.
     if (getNode(jobId) === null)
         return null;
-    const asking = askingNodeFor(jobId, deck, item.dir, nodes);
+    const asking = askingNodeFor(jobId, summary.dir, summary.source, nodes);
     const conversation = resolveConversation(asking, nodes);
+    const interactionCount = summary.kind === 'deck' ? readJson(deckPath(summary.dir))?.interactions.length : undefined;
     return {
-        id: item.id,
+        id: summary.id,
         job_id: jobId,
-        dir: item.dir,
-        title: item.title !== undefined ? item.title : deck?.title ?? null,
-        kind: item.kind !== undefined ? item.kind : deck?.interactions[0]?.kind ?? null,
-        blocked_since: item.blockedSince,
+        dir: summary.dir,
+        title: summary.title,
+        kind: summary.kind === 'deck' ? summary.interactionKind ?? null : 'review',
+        blocked_since: summary.blockedSince,
         ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name } : {}),
         ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
-        ...(deck !== null ? { interaction_count: deck.interactions.length } : {}),
+        ...(interactionCount !== undefined ? { interaction_count: interactionCount } : {}),
     };
 }
 function interactionDirForJob(jobId) {
@@ -245,7 +103,7 @@ export const humanList = defineLeaf({
     whenToUse: 'discovering what is blocked on a human',
     help: {
         name: 'human list',
-        summary: 'paginated list of pending, unclaimed interactions, oldest first',
+        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." },
@@ -265,8 +123,8 @@ export const humanList = defineLeaf({
         const nodes = nodeRefs();
         const raw = scanInbox(allInteractionRoots());
         const items = raw
-            .flatMap((i) => {
-            const item = summarizeDeckItem(i, readJson(deckPath(i.dir)), nodes);
+            .flatMap((s) => {
+            const item = summarizeTicket(s, nodes);
             return item === null ? [] : [item];
         })
             .sort((a, b) => {
@@ -315,7 +173,7 @@ export const humanDeck = defineLeaf({
             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 nodes = nodeRefs();
-        const asking = askingNodeFor(jobId, deck, dir, nodes);
+        const asking = askingNodeFor(jobId, dir, deck.source, nodes);
         const conversation = resolveConversation(asking, nodes);
         const first = deck.interactions[0];
         return {
@@ -337,155 +195,6 @@ export const humanDeck = defineLeaf({
         };
     },
 });
-function isErrno(e, code) {
-    return typeof e === 'object' && e !== null && 'code' in e && e.code === code;
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        if (isErrno(e, 'ESRCH'))
-            return false;
-        return true;
-    }
-}
-function interactionLockPath(dir) {
-    return join(dir, 'resolve.lock');
-}
-function releaseClaim(dir, token) {
-    const lockFile = interactionLockPath(dir);
-    const cur = readJson(lockFile);
-    if (cur?.token === token) {
-        try {
-            unlinkSync(lockFile);
-        }
-        catch (e) {
-            if (!isErrno(e, 'ENOENT'))
-                throw e;
-        }
-    }
-    const progressFile = progressPath(dir);
-    const progress = readJson(progressFile);
-    if (progress?.claimToken !== token)
-        return;
-    try {
-        unlinkSync(progressFile);
-    }
-    catch (e) {
-        if (!isErrno(e, 'ENOENT'))
-            throw e;
-    }
-}
-export function acquireInteractionClaim(dir, jobId, opts = {}) {
-    const allowResolved = opts.allowResolved === true;
-    const markProgress = opts.markProgress === true;
-    const respectProgress = opts.respectProgress === true;
-    const lockFile = interactionLockPath(dir);
-    const progressFile = progressPath(dir);
-    const token = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
-    for (;;) {
-        if (!allowResolved && isResolved(dir))
-            return 'already_resolved';
-        if (!allowResolved && respectProgress && existsSync(progressFile) && !existsSync(lockFile)) {
-            const progress = readJson(progressFile);
-            if (progress?.claim === 'crtr human resolve') {
-                try {
-                    unlinkSync(progressFile);
-                }
-                catch (e) {
-                    if (!isErrno(e, 'ENOENT'))
-                        return 'claimed';
-                }
-            }
-            else {
-                return 'claimed';
-            }
-        }
-        let fd = null;
-        try {
-            fd = openSync(lockFile, 'wx');
-            writeFileSync(fd, JSON.stringify({ pid: process.pid, token, jobId, claimedAt: new Date().toISOString() }, null, 2));
-            closeSync(fd);
-            fd = null;
-            if (markProgress) {
-                atomicWriteJson(progressFile, { partial: true, claim: 'crtr human resolve', claimToken: token, jobId, claimedAt: new Date().toISOString() });
-            }
-            if (!allowResolved && isResolved(dir)) {
-                releaseClaim(dir, token);
-                return 'already_resolved';
-            }
-            return { release: () => releaseClaim(dir, token) };
-        }
-        catch (e) {
-            if (fd !== null)
-                closeSync(fd);
-            if (isErrno(e, 'EEXIST')) {
-                const owner = readJson(lockFile);
-                if (typeof owner?.pid === 'number' && !pidAlive(owner.pid)) {
-                    try {
-                        unlinkSync(lockFile);
-                    }
-                    catch (unlinkErr) {
-                        if (!isErrno(unlinkErr, 'ENOENT'))
-                            return 'claimed';
-                    }
-                    continue;
-                }
-                return 'claimed';
-            }
-            throw e;
-        }
-    }
-}
-function writeResponseOnce(dir, responses, completedAt) {
-    const finalPath = responsePath(dir);
-    const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-    writeFileSync(tmpPath, JSON.stringify({ responses, completedAt }, null, 2), { flag: 'wx' });
-    try {
-        linkSync(tmpPath, finalPath);
-        return 'written';
-    }
-    catch (e) {
-        if (isErrno(e, 'EEXIST'))
-            return 'already_resolved';
-        throw e;
-    }
-    finally {
-        try {
-            unlinkSync(tmpPath);
-        }
-        catch (e) {
-            if (!isErrno(e, 'ENOENT'))
-                throw e;
-        }
-    }
-}
-function validateResolveResponses(deck, responses) {
-    const byId = new Map(deck.interactions.map((it) => [it.id, it]));
-    for (const response of responses) {
-        const interaction = byId.get(response.id);
-        if (interaction === undefined) {
-            throw new InputError({ error: 'invalid_field', message: `unknown interaction_id: ${response.id}`, field: 'responses', next: 'Use interaction ids from `crtr human deck <job_id> --json`.' });
-        }
-        if (interaction.multiSelect === true) {
-            if (response.selectedOptionId !== undefined) {
-                throw new InputError({ error: 'invalid_field', message: `interaction ${response.id} is multi-select; use selected_option_ids`, field: 'responses', next: 'Use selected_option_ids for multi-select interactions.' });
-            }
-        }
-        else if (response.selectedOptionIds !== undefined && response.selectedOptionIds.length > 1) {
-            throw new InputError({ error: 'invalid_field', message: `interaction ${response.id} is single-select`, field: 'responses', next: 'Use selected_option_id or one selected_option_ids value for single-select interactions.' });
-        }
-        const selected = response.selectedOptionIds ?? (response.selectedOptionId !== undefined ? [response.selectedOptionId] : []);
-        const optionIds = new Set(interaction.options.map((o) => o.id));
-        for (const id of selected) {
-            if (!optionIds.has(id)) {
-                throw new InputError({ error: 'invalid_field', message: `unknown option id for ${response.id}: ${id}`, field: 'responses', next: 'Use option ids from `crtr human deck <job_id> --json`.' });
-            }
-        }
-    }
-}
 function parseResolveBody(raw) {
     let parsed;
     try {
@@ -497,81 +206,68 @@ function parseResolveBody(raw) {
     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 {
-        responses: 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 } : {}),
-            };
-        }),
-        completedAt: parsed.completed_at ?? parsed.completedAt ?? new Date().toISOString(),
-    };
+    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 } : {}),
+        };
+    });
 }
 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 writes through the crouter/humanloop finalize path',
+    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: 'write deck answers atomically and deliver them back to the asking node',
+        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?}], completed_at?}.' },
+            { 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 wrote and delivered the answer.' },
+            { 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: 'delivered', type: 'boolean', required: false, constraint: 'True when delivered through crouter push/finalize.' },
             { name: 'reason', type: 'string', required: false, constraint: 'already_resolved or claimed when resolved is false.' },
         ],
         outputKind: 'object',
-        effects: ['Claims the interaction with a local resolve.lock (and progress.json so other humanloop inbox scans skip it), writes response.json with an exclusive no-clobber create, then calls crouter finalize/deliver-back. Does not write response.json from browser/server code.'],
+        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 { dir } = interactionDirForJob(jobId);
-        const { responses, completedAt } = parseResolveBody(input['body']);
-        try {
-            parseDeck(deckPath(dir));
-        }
-        catch {
+        const responses = parseResolveBody(input['body']);
+        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 claim = acquireInteractionClaim(dir, jobId, { markProgress: true, respectProgress: true });
-        if (claim === 'already_resolved')
+        if (isResolved(dir))
             return { resolved: false, job_id: jobId, reason: 'already_resolved' };
-        if (claim === 'claimed')
-            return { resolved: false, job_id: jobId, reason: 'claimed' };
+        const claim = claimTicket(dir);
+        if (claim === null) {
+            return { resolved: false, job_id: jobId, reason: isResolved(dir) ? 'already_resolved' : 'claimed' };
+        }
+        let won;
         try {
-            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`.' });
-            }
-            validateResolveResponses(deck, responses);
-            const writeResult = writeResponseOnce(dir, responses, completedAt);
-            if (writeResult === 'already_resolved')
-                return { resolved: false, job_id: jobId, reason: 'already_resolved' };
-            const delivered = await finalizeResolvedInteraction(jobId, claim);
-            if (!delivered)
-                return { resolved: false, job_id: jobId, reason: 'already_resolved' };
-            return { resolved: true, job_id: jobId, delivered };
+            ({ won } = await completeDeck(dir, responses, claim.token));
         }
-        finally {
-            claim.release();
+        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 };
     },
 });
 // ---------------------------------------------------------------------------
@@ -583,8 +279,8 @@ export const humanCancel = defineLeaf({
     whenToUse: 'a question went stale before the human answered',
     help: {
         name: 'human cancel',
-        summary: 'retract a pending ask/review you posed — kills its TUI pane, drops it from the human queue, and retires the 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. The agent that posed the deck is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers (e.g. the asking node when a human dismisses the prompt) get a quiet deferred note that no answer is coming. Canceling a review kills its live on-screen pane and delivers no comments — the same quiet deferred note covers it.',
+        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.' },
@@ -596,9 +292,8 @@ export const humanCancel = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            "Kills the detached TUI pane (if any) so the prompt leaves the human's screen.",
-            'Writes a canceled response.json so the interaction drops out of `human list`/`inbox`.',
-            'Marks the node done and, only for subscribers other than the caller, drops a deferred note that no answer is coming.',
+            '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) => {
@@ -616,169 +311,110 @@ export const humanCancel = defineLeaf({
         // Resolve the interaction dir from the node's RECORDED cwd: interaction dirs
         // are keyed by the asking process's cwd, which may differ from the caller's.
         const idir = interactionDir(jobId, node.cwd);
-        // Nothing live to cancel: the human already answered, or it was retired.
-        // 'canceled' is in the guard too so transition('finalize') below — legal only
-        // from active|idle — can never throw on an already-canceled (but unresolved)
-        // interaction node.
-        if (node.status === 'done' || node.status === 'dead' || node.status === 'canceled' || isResolved(idir)) {
+        // 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' };
         }
-        // (1) Kill the detached TUI pane so the prompt (or a review's live doc) leaves
-        //     the human's screen. Pass `idir` so killPane only fires when the target
-        //     pane is provably the worker we spawned for THIS job (its launch command
-        //     carries CRTR_HUMAN_DIR=idir) — never the agent's own pane or a shell.
-        const rc = readJson(join(idir, 'run.json'));
-        if (rc?.pane_id !== undefined && rc.pane_id !== '')
-            killPane(rc.pane_id, idir);
-        // A review also opened a live termrender render pane beside the editor —
-        // kill it too or it outlives the canceled job. Verified against the
-        // reviewed file path, which termrender bakes into the pane's start command
-        // (`termrender doc watch ... <file>`), so this can only ever hit our pane.
-        if (rc?.render_pane_id !== undefined && rc.render_pane_id !== '' && typeof rc.file === 'string' && rc.file !== '') {
-            killPane(rc.render_pane_id, rc.file);
-        }
-        // (2) Drop it from the human queue: a response.json marks the dir resolved,
-        //     so scanInbox (human list/inbox) skips it.
-        if (existsSync(idir)) {
-            atomicWriteJson(responsePath(idir), {
-                canceled: true,
-                canceledAt: new Date().toISOString(),
-                ...(reason !== undefined && reason !== '' ? { reason } : {}),
-            });
-        }
-        // (3) Retire the node. We do NOT push a -final.md report: a cancel must not
-        //     masquerade as a human-submitted result. Subscribers get the quiet
-        //     deferred 'no answer is coming' note below instead.
-        transition(jobId, 'finalize');
-        // Almost always the asking agent cancels its OWN deck — it already knows, so
-        // never message the caller. Only a third-party cancel (a human, an
-        // orchestrator) leaves a genuinely-waiting asker uninformed; give them a
-        // quiet deferred note (informational, never nudges) so nobody waits forever.
-        const caller = process.env['CRTR_NODE_ID'] ?? 'human';
-        const note = reason !== undefined && reason !== '' ? ` — ${reason}` : '';
-        for (const sub of subscribersOf(jobId)) {
-            if (sub.node_id === caller)
-                continue; // don't ping whoever issued the cancel
-            appendInbox(sub.node_id, {
-                from: caller,
-                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.` },
-            });
+        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']} — its TUI pane is closed and subscribers were notified no answer is coming.`
+        ? `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'}.`,
 });
 // ---------------------------------------------------------------------------
-// _run (hidden worker; not listed in branch help)
+// _deliver (hidden completion handler; not listed in branch help)
 // ---------------------------------------------------------------------------
-export const humanRun = defineLeaf({
-    name: '_run',
+/** 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 };
+}
+export const humanDeliver = defineLeaf({
+    name: '_deliver',
     tier: 'hidden',
     help: {
-        name: 'human _run',
-        summary: 'internal: the detached worker that runs the blocking humanloop call at the pane TTY',
-        params: [],
-        inputNote: 'Internal; invoked by the spawned pane via CRTR_HUMAN_DIR + run.json. Not for manual use.',
-        output: [{ name: 'none', type: 'void', required: false, constraint: 'No stdout; writes the job result file directly.' }],
+        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: ['Runs the blocking humanloop call; for tracked modes pushes the result as the node\'s final report (fans out to the asking node\'s inbox).'],
+        effects: ['Reads the completion event, verifies root registration/containment, then pushFinals the answer (ask/review) or retires the bridge (canceled). Idempotent: replay after a crash is safe.'],
     },
-    run: async () => {
-        const dir = process.env['CRTR_HUMAN_DIR'];
-        if (dir === undefined || dir === '') {
-            process.exit(1);
-        }
+    run: async (input) => {
+        const event = JSON.parse(input['body']);
+        if (event.schema !== 'humanloop.completion/v1') {
+            throw new InputError({ error: 'invalid_field', message: 'not a humanloop.completion/v1 event', field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        // 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 InputError({ error: 'invalid_field', message: 'interaction dir is not a direct child of the event root', field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        const registered = listInboxRoots().some((r) => r.root === root && r.owner === 'crouter');
+        if (!registered) {
+            throw new InputError({ error: 'invalid_field', message: `root is not registered to crouter: ${root}`, field: 'stdin', next: 'Only humanloop invokes this handler.' });
+        }
+        const jobId = basename(dir);
         const rc = readJson(join(dir, 'run.json'));
-        if (rc === null) {
-            process.exit(1);
+        // notify: a durable deck with no bridge node and no answer delivery.
+        if (rc?.mode === 'notify')
+            return { delivered: true };
+        const result = readTicketResult(event.responsePath);
+        if (result === null) {
+            throw new InputError({ error: 'not_found', message: 'no canonical result to deliver', field: 'stdin', next: 'Only humanloop invokes this handler.' });
         }
-        try {
-            if (rc.mode === 'ask' || rc.mode === 'notify') {
-                const deck = parseDeck(deckPath(dir));
-                if (rc.mode === 'ask') {
-                    const claim = acquireInteractionClaim(dir, rc.job_id);
-                    if (claim === 'already_resolved') {
-                        await finalizeResolvedInteraction(rc.job_id);
-                        return;
-                    }
-                    if (claim === 'claimed')
-                        return;
-                    try {
-                        await ask(deck, { dir });
-                        // Pass the held claim: finalize re-acquires the same exclusive
-                        // resolve.lock, which THIS worker still holds — without the claim it
-                        // would see its own live lock, return 'claimed', and never deliver
-                        // the answer (stranding the asker). The held claim makes finalize
-                        // run under our lock; _run's finally still owns the release.
-                        await finalizeResolvedInteraction(rc.job_id, claim);
-                    }
-                    finally {
-                        claim.release();
-                    }
-                }
-                else {
-                    await ask(deck, { dir });
-                }
-                // notify: no job — nothing to write
-            }
-            else if (rc.mode === 'review') {
-                // The _run worker is already its own dedicated tmux pane with a TTY, so
-                // run nvim directly in it (noTmux) instead of letting launchReview
-                // split off a SECOND pane and sit polling.
-                //
-                // BUG REGRESSION (raw-markdown review): the nvim buffer must stay the
-                // RAW source — anchored comments hang off source line numbers — so the
-                // termrender render the help promises (panels/callouts/mermaid) lives
-                // in its OWN live pane opened beside this worker. `display` spawns the
-                // managed termrender binary in watch mode, so it re-renders on every
-                // save exactly like the nvim buffer reloads. Best-effort: off-tmux or
-                // renderer-unavailable degrades to editor-only. The pane id is merged
-                // into run.json so `human cancel` can kill it; the finally clears it on
-                // every exit of the editor (submit, quit, or failure).
-                let renderPane;
-                try {
-                    renderPane = display(rc.file, { window: 'split' }).paneId;
-                }
-                catch {
-                    /* render pane is best-effort; the review itself must not die */
-                }
-                // Dock the render pane BESIDE this worker pane. tmux resolves an
-                // untargeted split-window against the attached client's current window
-                // (which wins over $TMUX_PANE), so the pane can land in whatever window
-                // the user happens to be looking at — away from the editor. move-pane
-                // with explicit src/dst is deterministic: raw source and rendered doc
-                // always sit side by side.
-                const selfPane = process.env['TMUX_PANE'];
-                if (renderPane !== undefined && selfPane !== undefined && selfPane !== '') {
-                    spawnSync('tmux', ['move-pane', '-h', '-s', renderPane, '-t', selfPane], { stdio: 'ignore' });
-                }
-                if (renderPane !== undefined) {
-                    const rcPath = join(dir, 'run.json');
-                    const cur = readJson(rcPath);
-                    if (cur !== null)
-                        atomicWriteJson(rcPath, { ...cur, render_pane_id: renderPane });
-                }
-                try {
-                    const res = await launchReview(rc.file, {
-                        output: rc.output,
-                    });
-                    await pushFinal(rc.job_id, JSON.stringify(res));
-                }
-                finally {
-                    if (renderPane !== undefined)
-                        killPane(renderPane, rc.file);
-                }
-            }
+        const node = getNode(jobId);
+        // Replay-safe: an already-terminal (or reaped) bridge needs no further work.
+        if (node === null || node.status === 'done' || node.status === 'dead' || node.status === 'canceled') {
+            return { delivered: true };
         }
-        catch (e) {
-            if (rc.job_id !== undefined) {
-                await pushFinal(rc.job_id, JSON.stringify({ error: 'human_run_failed', message: String(e) }));
+        if (result.kind === 'canceled') {
+            transition(jobId, 'finalize');
+            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 { delivered: true };
+        }
+        if (result.kind === 'review') {
+            const feedback = result.result;
+            await pushFinal(jobId, JSON.stringify(feedback));
+            return { delivered: true };
         }
+        // deck
+        const env = envelopeFromDeckResult(result.responses, result.summary, result.completedAt, event.responsePath);
+        await pushFinal(jobId, JSON.stringify(env));
+        return { delivered: true };
     },
 });