@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/human/queue.js

@@ -3,13 +3,13 @@ import { InputError } from '../../core/io.js';
 import { pushFinal } from '../../core/feed/feed.js';
 import { interactionsRoot, interactionDir } from '../../core/artifact.js';
 import { paginate } from '../../core/pagination.js';
-import { getNode, subscribersOf } from '../../core/canvas/index.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 { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { closeSync, existsSync, linkSync, openSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
+import { inbox, scanInbox, parseDeck, deckPath, responsePath, progressPath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
 // stranded-answer healing
@@ -18,12 +18,26 @@ import { killPane } from './shared.js';
  *  `<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) {
+function summarizeResponses(responses, deck) {
+    const interactions = new Map((deck?.interactions ?? []).map((it) => [it.id, it]));
     return responses
         .map((r) => {
-        const opt = r.selectedOptionId ?? '';
+        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 `${r.id}: ${opt}${ft}`;
+        return `${it?.title ?? r.id}: ${picked}${ft}`;
     })
         .join('\n');
 }
@@ -39,47 +53,56 @@ function summarizeResponses(responses) {
  *  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) {
-    const node = getNode(jobId);
-    if (node === null)
-        return false;
-    if (node.status !== 'active' && node.status !== 'idle')
+export async function finalizeResolvedInteraction(jobId, claim) {
+    const firstNode = getNode(jobId);
+    if (firstNode === null)
         return false;
-    const idir = interactionDir(jobId, node.cwd);
-    if (!isResolved(idir))
+    const idir = interactionDir(jobId, firstNode.cwd);
+    const ownedClaim = claim ?? acquireInteractionClaim(idir, jobId, { allowResolved: true });
+    if (ownedClaim === 'already_resolved' || ownedClaim === 'claimed')
         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.` },
-            });
+    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;
         }
-        return true;
-    }
-    const responses = resp['responses'] ?? [];
-    const completedAt = resp['completedAt'] ?? new Date().toISOString();
-    const summary = summarizeResponses(responses);
-    if (rc.mode === 'approve') {
-        const sel = responses.find((r) => r.id === rc.approve_iid)?.selectedOptionId;
-        await pushFinal(jobId, JSON.stringify({ approved: sel === 'yes', summary, responses, responsePath: responsePath(idir), completedAt }));
-    }
-    else {
+        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,
@@ -89,8 +112,12 @@ export async function finalizeResolvedInteraction(jobId) {
             completedAt,
         };
         await pushFinal(jobId, JSON.stringify(env));
+        return true;
+    }
+    finally {
+        if (claim === undefined)
+            ownedClaim.release();
     }
-    return true;
 }
 /** Sweep every interaction under the cwd's interactions root and deliver-back +
  *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
@@ -139,6 +166,76 @@ export const humanInbox = defineLeaf({
         return { drained: true, delivered };
     },
 });
+function allInteractionRoots() {
+    const roots = new Set();
+    roots.add(interactionsRoot(process.cwd()));
+    for (const node of listNodes())
+        roots.add(interactionsRoot(node.cwd));
+    return [...roots];
+}
+function nodeRefs() {
+    return listNodes().map((n) => ({ node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent }));
+}
+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 askingNodeFor(jobId, deck, dir, nodes) {
+    const stamped = deck?.source?.nodeId;
+    if (stamped !== undefined && stamped !== '') {
+        const found = nodes.find((n) => n.node_id === stamped);
+        if (found !== undefined)
+            return found;
+    }
+    const bridge = getNode(jobId);
+    if (bridge?.parent !== undefined && bridge.parent !== null) {
+        const parent = nodes.find((n) => n.node_id === bridge.parent);
+        if (parent !== undefined)
+            return parent;
+    }
+    for (const n of nodes) {
+        const root = interactionsRoot(n.cwd);
+        if (dir === root || dir.startsWith(`${root}/`))
+            return n;
+    }
+    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);
+    if (getNode(jobId) === null)
+        return null;
+    const asking = askingNodeFor(jobId, deck, item.dir, nodes);
+    const conversation = resolveConversation(asking, nodes);
+    return {
+        id: item.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,
+        ...(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 } : {}),
+    };
+}
+function interactionDirForJob(jobId) {
+    const node = getNode(jobId);
+    if (node === null) {
+        throw new InputError({ error: 'not_found', message: `no interaction node: ${jobId}`, field: 'job_id', next: 'Pass a job_id from `crtr human list`.' });
+    }
+    return { dir: interactionDir(jobId, node.cwd) };
+}
 // ---------------------------------------------------------------------------
 // list (read-only, paginated)
 // ---------------------------------------------------------------------------
@@ -154,7 +251,7 @@ export const humanList = defineLeaf({
             { 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, kind, blocked_since}. Oldest first.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, kind, blocked_since}, enriched when derivable with 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.' },
         ],
@@ -165,15 +262,13 @@ export const humanList = defineLeaf({
         const limitRaw = input['limit'];
         const limit = Math.min(Math.max(1, limitRaw), 100);
         const cursor = input['cursor'];
-        const raw = scanInbox([interactionsRoot(process.cwd())]);
+        const nodes = nodeRefs();
+        const raw = scanInbox(allInteractionRoots());
         const items = raw
-            .map((i) => ({
-            id: i.id,
-            dir: i.dir,
-            title: i.title !== undefined ? i.title : null,
-            kind: i.kind !== undefined ? i.kind : null,
-            blocked_since: i.blockedSince,
-        }))
+            .flatMap((i) => {
+            const item = summarizeDeckItem(i, readJson(deckPath(i.dir)), nodes);
+            return item === null ? [] : [item];
+        })
             .sort((a, b) => {
             const ka = `${a.blocked_since}|${a.id}`;
             const kb = `${b.blocked_since}|${b.id}`;
@@ -189,18 +284,308 @@ export const humanList = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// cancel — retract a pending ask/approve/review
+// 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 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 { dir } = interactionDirForJob(jobId);
+        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 nodes = nodeRefs();
+        const asking = askingNodeFor(jobId, deck, dir, nodes);
+        const conversation = resolveConversation(asking, nodes);
+        const first = deck.interactions[0];
+        return {
+            id: jobId,
+            title: deck.title ?? first?.title ?? null,
+            kind: first?.kind ?? null,
+            blocked_since: deck.source?.blockedSince ?? null,
+            ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name } : {}),
+            ...(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,
+                prompt: it.body ?? it.title,
+                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 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 {
+        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 {
+        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(),
+    };
+}
+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',
+    help: {
+        name: 'human resolve',
+        summary: 'write deck answers atomically and deliver them 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?}.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call wrote and delivered the answer.' },
+            { 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.'],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const { dir } = interactionDirForJob(jobId);
+        const { responses, completedAt } = parseResolveBody(input['body']);
+        try {
+            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 claim = acquireInteractionClaim(dir, jobId, { markProgress: true, respectProgress: true });
+        if (claim === 'already_resolved')
+            return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+        if (claim === 'claimed')
+            return { resolved: false, job_id: jobId, reason: 'claimed' };
+        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 };
+        }
+        finally {
+            claim.release();
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// cancel — retract a pending ask/review
 // ---------------------------------------------------------------------------
 export const humanCancel = defineLeaf({
     name: 'cancel',
-    description: 'retract a pending ask/approve/review',
+    description: 'retract a pending ask/review',
     whenToUse: 'a question went stale before the human answered',
     help: {
         name: 'human cancel',
-        summary: 'retract a pending ask/approve/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`/`approve`/`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 — 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.',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/approve/review.' },
+            { 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: [
@@ -224,7 +609,7 @@ export const humanCancel = defineLeaf({
                 error: 'not_found',
                 message: `no interaction node: ${jobId}`,
                 field: 'job_id',
-                next: 'Pass the job_id from human ask/approve/review, or list pending with `crtr human list`.',
+                next: 'Pass the job_id from human ask/review, or list pending with `crtr human list`.',
             });
         }
         // Resolve the interaction dir from the node's RECORDED cwd: interaction dirs
@@ -312,21 +697,31 @@ export const humanRun = defineLeaf({
             process.exit(1);
         }
         try {
-            if (rc.mode === 'ask' || rc.mode === 'approve' || rc.mode === 'notify') {
+            if (rc.mode === 'ask' || rc.mode === 'notify') {
                 const deck = parseDeck(deckPath(dir));
-                const env = await ask(deck, { dir });
                 if (rc.mode === 'ask') {
-                    await pushFinal(rc.job_id, JSON.stringify(env));
+                    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 if (rc.mode === 'approve') {
-                    const sel = env.responses.find((r) => r.id === rc.approve_iid)?.selectedOptionId;
-                    await pushFinal(rc.job_id, JSON.stringify({
-                        approved: sel === 'yes',
-                        summary: env.summary,
-                        responses: env.responses,
-                        responsePath: env.responsePath,
-                        completedAt: env.completedAt,
-                    }));
+                else {
+                    await ask(deck, { dir });
                 }
                 // notify: no job — nothing to write
             }

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

@@ -1,9 +1,8 @@
 import { type DetachResult } from '../../core/spawn.js';
 export declare const DECK_SCHEMA_HINT: string;
 export interface RunRecord {
-    mode: 'ask' | 'approve' | 'notify' | 'review';
+    mode: 'ask' | 'notify' | 'review';
     job_id?: string;
-    approve_iid?: string;
     file?: string;
     output?: string;
     /** tmux pane id of the detached TUI, recorded so `human cancel` can kill it. */
@@ -32,7 +31,7 @@ export declare function resolveHumanTarget(): string | undefined;
 /**
  * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
  * session the user is watching (`resolveHumanTarget`). The single spawn path
- * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * behind ask/review (`spawnHumanJob`) and notify. `detached: true` keeps
  * the user's view put — the prompt lands beside the watched node without
  * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
  */
@@ -55,7 +54,7 @@ export declare function followUpReview(_jobId: string): string;
  *
  * Completion routing needs no bookkeeping here: the human node was created
  * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits — for ask, approve, AND review —
+ * so the `pushFinal` the `_run` worker emits — for ask AND review —
  * fans the answer straight into the asking node's inbox. The pane id is recorded
  * on run.json (not returned) so `human cancel` can later kill the TUI.
  */