@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/commands/chord.js

@@ -0,0 +1,143 @@
+// `crtr canvas chord` — the tmux prefix-menu dispatcher.
+//
+// The alt+c display-menu can't see the cursor node or read config at popup time
+// — it only knows the active pane. So every config-driven prefix chord routes
+// through this one leaf: tmux passes `--pane '#{pane_id}'` + `--key <k>`, and
+// the dispatcher resolves the node in that pane, reads
+// `canvasNav.prefixBinds[key]`, interpolates the template vars, and execs
+// `crtr <argv>`. This keeps the menu static while the behaviour stays fully
+// config-driven (no per-node menu rebuild).
+//
+// Two special cases bypass the bind table:
+//   • a digit key 1..9 → focus report N (the Nth live report of the pane node)
+//   • a bind whose `run` is the sentinel `__graph__` → send-keys `/graph` into
+//     the pane (toggles the in-pi GRAPH modal); the menu emits this directly so
+//     the dispatcher only handles it defensively.
+//
+// execFile (never `sh -c`) runs the interpolated argv, so a node name with
+// shell metacharacters can never inject — each argv element is literal.
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { readConfig } from '../core/config.js';
+import { sendKeysEnter } from '../core/runtime/tmux.js';
+import { nodeInPane } from './node.js';
+import { getNode, subscribersOf, subscriptionsOf, view, fullName, } from '../core/canvas/index.js';
+const pexec = promisify(execFile);
+/** Template vars available to a `run` string. Single-valued vars interpolate
+ *  in place (preserving spaces, e.g. a node name); `{subtree}` is multi-valued
+ *  and a bare `{subtree}` token expands to several argv elements. */
+function buildVars(selfId) {
+    const node = getNode(selfId);
+    const manager = subscribersOf(selfId)[0]?.node_id ?? '';
+    return {
+        id: selfId,
+        self: selfId,
+        lane: selfId,
+        name: node !== null ? fullName(node) : selfId,
+        manager,
+        subtree: view(selfId).join(' '),
+    };
+}
+/** Split a `run` string argv-style and interpolate the template vars. A bare
+ *  `{subtree}` token expands to several argv elements; every other placeholder
+ *  is substituted in place (kept as one element so a multi-word name survives
+ *  as a single argument under execFile). */
+function interpolateArgv(run, vars) {
+    const out = [];
+    for (const tok of run.split(/\s+/).filter((t) => t !== '')) {
+        if (tok === '{subtree}') {
+            for (const part of (vars['subtree'] ?? '').split(/\s+/).filter((p) => p !== ''))
+                out.push(part);
+            continue;
+        }
+        out.push(tok.replace(/\{(\w+)\}/g, (_, name) => vars[name] ?? ''));
+    }
+    return out;
+}
+export const chordLeaf = defineLeaf({
+    name: 'chord',
+    description: 'tmux prefix-menu dispatcher (bound by alt+c; not run by hand)',
+    whenToUse: 'never directly — the alt+c menu routes config-driven chords through it',
+    help: {
+        name: 'canvas chord',
+        summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, look up canvasNav.prefixBinds[--key], interpolate, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id whose node the chord acts on. Defaults to $TMUX_PANE / your current pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'key',
+                type: 'string',
+                required: true,
+                constraint: 'The chord key pressed after alt+c (e.g. m, e, or a digit 1-9 for focus report N).',
+            },
+        ],
+        output: [
+            { name: 'ran', type: 'boolean', required: true, constraint: 'True when an action was dispatched.' },
+            { name: 'key', type: 'string', required: true, constraint: 'Echo of the chord key.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node the chord resolved against.' },
+            { name: 'action', type: 'string', required: false, constraint: 'What ran: a crtr argv string, "graph-toggle", or "noop".' },
+        ],
+        outputKind: 'object',
+        effects: ['Runs a `crtr` subcommand (focus/close/tmux-spread/…) or sends `/graph` into the pane, per the matched bind.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const key = input['key'].trim();
+        const selfId = nodeInPane(pane);
+        if (selfId === undefined) {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no node found in this pane',
+                next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
+            });
+        }
+        // Digit keys 1..9 → focus the Nth live report (generated, not a bind entry).
+        if (/^[1-9]$/.test(key)) {
+            const n = parseInt(key, 10);
+            const reports = subscriptionsOf(selfId)
+                .map((r) => r.node_id)
+                .filter((id) => {
+                const s = getNode(id)?.status;
+                return s === 'active' || s === 'idle';
+            });
+            const target = reports[n - 1];
+            if (target === undefined)
+                return { ran: false, key, node_id: selfId, action: 'noop' };
+            try {
+                await pexec('crtr', ['node', 'focus', target], { timeout: 15_000 });
+            }
+            catch {
+                /* best-effort */
+            }
+            return { ran: true, key, node_id: selfId, action: `node focus ${target}` };
+        }
+        const bind = readConfig('user').canvasNav.prefixBinds[key];
+        if (bind === undefined)
+            return { ran: false, key, node_id: selfId, action: 'noop' };
+        // The GRAPH-toggle sentinel: type /graph into the pane (the menu normally
+        // emits this directly; handle it here too so a manual chord still works).
+        if (bind.run === '__graph__') {
+            if (pane !== undefined && pane !== '')
+                sendKeysEnter(pane, '/graph');
+            return { ran: true, key, node_id: selfId, action: 'graph-toggle' };
+        }
+        const argv = interpolateArgv(bind.run, buildVars(selfId));
+        if (argv.length === 0)
+            return { ran: false, key, node_id: selfId, action: 'noop' };
+        try {
+            await pexec('crtr', argv, { timeout: 15_000 });
+        }
+        catch {
+            /* best-effort: the keystroke just acts; errors are surfaced by the inner cmd */
+        }
+        return { ran: true, key, node_id: selfId, action: `crtr ${argv.join(' ')}` };
+    },
+});

package/dist/commands/daemon.js

@@ -14,6 +14,8 @@ import { readPidfile, isPidAlive } from '../daemon/crtrd.js';
 // ---------------------------------------------------------------------------
 const daemonStart = defineLeaf({
     name: 'start',
+    description: 'start the daemon in the background',
+    whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op if it is already running)',
     help: {
         name: 'canvas daemon start',
         summary: 'start the crtrd supervisor daemon in the background (no-op if already running)',
@@ -39,6 +41,8 @@ const daemonStart = defineLeaf({
 // ---------------------------------------------------------------------------
 const daemonStatus = defineLeaf({
     name: 'status',
+    description: 'check whether the daemon is running',
+    whenToUse: 'checking whether the crtrd supervisor is running — e.g. confirming supervision is up before relying on auto-revive',
     help: {
         name: 'canvas daemon status',
         summary: 'check whether the crtrd supervisor daemon is currently running',
@@ -63,6 +67,8 @@ const daemonStatus = defineLeaf({
 // ---------------------------------------------------------------------------
 const daemonStop = defineLeaf({
     name: 'stop',
+    description: 'stop the running daemon',
+    whenToUse: 'shutting the crtrd supervisor down, ending auto-revival of nodes on window exit',
     help: {
         name: 'canvas daemon stop',
         summary: 'send SIGTERM to the crtrd supervisor daemon',
@@ -97,15 +103,12 @@ const daemonStop = defineLeaf({
 // ---------------------------------------------------------------------------
 export const daemonBranch = defineBranch({
     name: 'daemon',
+    description: 'manage the crtrd supervisor process',
+    whenToUse: 'managing the crtrd supervisor that auto-revives nodes on window exit — start it, check its status, or stop it',
     help: {
         name: 'canvas daemon',
         summary: 'manage the crtrd canvas supervisor daemon',
         model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision.',
-        children: [
-            { name: 'start', desc: 'start the daemon in the background', useWhen: 'bringing up the supervisor for the first time in a session' },
-            { name: 'status', desc: 'check whether the daemon is running', useWhen: 'verifying the daemon is up before spawning canvas nodes' },
-            { name: 'stop', desc: 'stop the running daemon', useWhen: 'shutting down supervision' },
-        ],
     },
     children: [daemonStart, daemonStatus, daemonStop],
 });

package/dist/commands/dashboard.js

@@ -14,6 +14,8 @@ import { renderTree, renderForest, dashboardRows, dashboardRowsAll } from '../co
 // ---------------------------------------------------------------------------
 export const dashboardLeaf = defineLeaf({
     name: 'dashboard',
+    description: 'render the canvas as a subscription tree',
+    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on a human',
     help: {
         name: 'canvas dashboard',
         summary: 'render the canvas as an ASCII subscription tree — scoped to a root or the full forest',

package/dist/commands/human/prompts.js

@@ -7,7 +7,7 @@ import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { validateDeck, approveDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, waitForFinalReport, spawnHumanJob, pickPlacement, runCmd, resolveMaxPanes, } from './shared.js';
+import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, pickPlacement, runCmd, resolveMaxPanes, } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -17,6 +17,8 @@ function askingNode() {
 // ---------------------------------------------------------------------------
 export const humanAsk = defineLeaf({
     name: 'ask',
+    description: 'put a structured choice or open question to a person',
+    whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points). The kickoff never blocks, so the human answering on their own time is never a reason to skip the ask and guess instead',
     help: {
         name: 'human ask',
         summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. This is the default, expected channel for posing ANY question or decision to the user — reach for it instead of writing the question as prose in your reply.',
@@ -65,6 +67,8 @@ export const humanAsk = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanApprove = defineLeaf({
     name: 'approve',
+    description: 'a Yes/No sign-off gate',
+    whenToUse: 'a step needs an explicit human yes before it proceeds and a plain answer (not anchored comments) is enough: before a handoff, a merge or deploy, a destructive or irreversible operation, spending real budget, or acting on a risky plan. Reach for `ask` instead when you need them to choose among options or answer something open-ended; reach for `review` when the feedback belongs inline on a document',
     help: {
         name: 'human approve',
         summary: 'a Yes/No approval gate; returns a job handle immediately. The standard way to gate a handoff on human sign-off. Kickoff never blocks — peek at the result later rather than busy-waiting; the human answering on their own time is not a reason to skip the gate.',
@@ -109,27 +113,27 @@ export const humanApprove = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanReview = defineLeaf({
     name: 'review',
+    description: 'collect anchored comments on a .md (plan or spec)',
+    whenToUse: 'a human should comment line-by-line on a document rather than give one overall answer: reviewing a plan or spec before you build it, marking up a draft, flagging specific sections to change. The comments come back anchored to the lines they touch. Use `approve` instead for a single yes/no on the whole thing, or `ask` to pose a discrete choice',
     help: {
         name: 'human review',
-        summary: 'open a .md in a read-only review editor for anchored comments; BLOCKS until the human submits the review. Humans respond on human time (often >10 min) — if you want to keep working, background this call (your harness will notify you when it finishes).',
-        guide: 'Unlike ask/approve, this call does not return a job handle and walk away — it blocks until the human finishes reviewing and submits (or closes the pane). Run it in the background when you have other work to do; the harness surfaces the result on completion. The returned `result` is the humanloop FeedbackResult (anchored comments). The .md you point at is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        summary: "put a .md live on the human's screen for anchored, line-by-line comments; returns a job handle instantly (a non-blocking kickoff, like ask/approve). The pane tracks the file and re-renders on every save, so edit in place rather than re-presenting.",
+        guide: "A kickoff, not a blocking call: it returns at once and the human reviews on their own time. When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to `output`; you never poll, verify it opened, or background it. The pane is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.",
         params: [
             { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing .md file.' },
             { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the FeedbackResult JSON is written. Default: <dir>/feedback.json.' },
         ],
         output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of the kind:"human" node backing this review.' },
-            { name: 'output', type: 'string', required: true, constraint: 'Path the FeedbackResult JSON is autosaved to.' },
-            { name: 'status', type: 'string', required: true, constraint: 'Terminal state once the call unblocks: done (submitted), failed, canceled, or closed (pane went away before submit).' },
-            { name: 'result', type: 'object', required: false, constraint: 'The humanloop FeedbackResult (anchored comments). Present when status is done.' },
-            { name: 'reason', type: 'string', required: false, constraint: 'Short explanation when status is failed or closed.' },
-            { name: 'follow_up', type: 'string', required: false, constraint: 'Present only when off-tmux: a human must drain the review via `crtr human inbox`, then read the result.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of the kind:"human" node backing this review. Its FeedbackResult is pushed to your inbox when the human submits.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding run.json and the autosaved feedback.json.' },
+            { name: 'output', type: 'string', required: true, constraint: 'Path the FeedbackResult JSON is autosaved to when the human submits.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking road sign. The human may take minutes to hours; do not block, poll, or verify the pane — just end your turn and you are woken when they submit.' },
         ],
         outputKind: 'object',
         effects: [
             'Creates a kind:"human" node under you and writes run.json to the interaction dir.',
-            'Spawns a read-only nvim/vim review session in a detached tmux pane (when in tmux).',
-            'Blocks the calling process until the human submits, the pane closes, or the job is canceled.',
+            'Spawns a live, read-only review session (in a detached tmux pane when in tmux) that tracks the file and re-renders on save.',
+            'Returns instantly; the anchored comments fan into your inbox when the human submits (off-tmux, drain via `crtr human inbox`).',
         ],
     },
     run: async (input) => {
@@ -159,22 +163,15 @@ export const humanReview = defineLeaf({
         const output = outputArg !== undefined ? outputArg : join(idir, 'feedback.json');
         const rc = { mode: 'review', job_id: jobId, file: abs, output };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        const { spawned, follow_up, paneId } = spawnHumanJob(jobId, idir, cwd);
-        // Off-tmux: no pane to block on — fall back to the non-blocking handle the
-        // way ask/approve do, so the review can still be drained from the inbox.
-        if (!spawned) {
-            return { job_id: jobId, output, status: 'live', follow_up };
-        }
-        // In tmux: block until the human submits or the pane dies before submitting.
-        // No timeout (the human owns the clock); the pane-alive poll inside
-        // waitForFinalReport resolves 'closed' if the pane goes away first.
-        const r = await waitForFinalReport(jobId, paneId);
-        const out = { job_id: jobId, output, status: r.status };
-        if (r.result !== undefined)
-            out['result'] = r.result;
-        if (r.reason !== undefined)
-            out['reason'] = r.reason;
-        return out;
+        // review is a non-blocking kickoff, exactly like ask/approve: the detached
+        // `_run` worker pushes the FeedbackResult as this node's final report when
+        // the human submits, which fans into our inbox and wakes us (and is also
+        // autosaved to `output`). There is nothing to block on — the doc is live on
+        // the human's screen and tracks the file, so the caller keeps editing in
+        // place or simply ends its turn.
+        const { spawned, follow_up: drainFollowUp } = spawnHumanJob(jobId, idir, cwd);
+        const follow_up = spawned ? followUpReview(jobId) : drainFollowUp;
+        return { job_id: jobId, dir: idir, output, follow_up };
     },
 });
 // ---------------------------------------------------------------------------
@@ -182,6 +179,8 @@ export const humanReview = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanNotify = defineLeaf({
     name: 'notify',
+    description: 'fire-and-forget acknowledgement, no reply expected',
+    whenToUse: 'informing a person without blocking or expecting an answer',
     help: {
         name: 'human notify',
         summary: 'show a fire-and-forget acknowledgement; creates no job',
@@ -229,6 +228,8 @@ export const humanNotify = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanShow = defineLeaf({
     name: 'show',
+    description: "put a file live on the human's screen",
+    whenToUse: 'displaying a doc on screen while a human comments',
     help: {
         name: 'human show',
         summary: 'put a file live on screen in a tmux pane via humanloop display',

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

@@ -1,3 +1,4 @@
 export declare const humanInbox: import("../../core/command.js").LeafDef;
 export declare const humanList: import("../../core/command.js").LeafDef;
+export declare const humanCancel: import("../../core/command.js").LeafDef;
 export declare const humanRun: import("../../core/command.js").LeafDef;

package/dist/commands/human/queue.js

@@ -1,14 +1,22 @@
 import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
 import { pushFinal } from '../../core/feed/feed.js';
-import { interactionsRoot } from '../../core/artifact.js';
+import { interactionsRoot, interactionDir } from '../../core/artifact.js';
 import { paginate } from '../../core/pagination.js';
+import { getNode, subscribersOf } from '../../core/canvas/index.js';
+import { transition } from '../../core/runtime/lifecycle.js';
+import { appendInbox } from '../../core/feed/inbox.js';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { inbox, scanInbox, parseDeck, deckPath, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
 // 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',
@@ -28,6 +36,8 @@ export const humanInbox = defineLeaf({
 // ---------------------------------------------------------------------------
 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, unclaimed interactions, oldest first',
@@ -71,10 +81,103 @@ export const humanList = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// cancel — retract a pending ask/approve/review
+// ---------------------------------------------------------------------------
+export const humanCancel = defineLeaf({
+    name: 'cancel',
+    description: 'retract a pending ask/approve/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.',
+        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: '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: [
+            "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.',
+        ],
+    },
+    run: async (input) => {
+        const jobId = input['job_id'];
+        const reason = input['reason'];
+        const node = getNode(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/approve/review, or list pending with `crtr human list`.',
+            });
+        }
+        // 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)) {
+            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);
+        // (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.` },
+            });
+        }
+        return { canceled: true, job_id: jobId };
+    },
+    render: (r) => r['canceled'] === true
+        ? `<canceled job_id="${r['job_id']}"/>`
+        : `<cancel-noop job_id="${r['job_id']}">${r['reason'] ?? 'nothing to cancel'}</cancel-noop>`,
+});
+// ---------------------------------------------------------------------------
 // _run (hidden worker; not listed in branch help)
 // ---------------------------------------------------------------------------
 export const humanRun = defineLeaf({
     name: '_run',
+    tier: 'hidden',
     help: {
         name: 'human _run',
         summary: 'internal: the detached worker that runs the blocking humanloop call at the pane TTY',

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

@@ -5,39 +5,49 @@ export interface RunRecord {
     approve_iid?: string;
     file?: string;
     output?: string;
+    /** tmux pane id of the detached TUI, recorded so `human cancel` can kill it. */
+    pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
 export declare function pickPlacement(): 'split-h' | 'new-window';
 export declare function runCmd(dir: string): string;
 export declare function followUpResult(_jobId: string): string;
 export declare function followUpDrain(_jobId: string): string;
+/**
+ * Road sign for a spawned `human review`. It is a non-blocking kickoff, so the
+ * text steers the caller to stop rather than wait, verify, or re-present: the
+ * pane is already live and tracks the file, and the comments arrive via the
+ * inbox/wake when the human submits.
+ */
+export declare function followUpReview(_jobId: string): string;
 /**
  * Spawn the detached `_run` pane that drives the humanloop TUI for this node.
- * Returns whether the pane spawned, the follow_up text, and (when spawned) the
- * tmux pane id so a blocking caller (review) can detect the pane dying before
- * the human submits. Degrades to the inbox-drain follow_up when not in tmux /
- * spawn fails — kickoffs are intentionally non-fatal off-tmux.
+ * Returns whether the pane spawned and the follow_up road sign. Degrades to the
+ * inbox-drain follow_up when not in tmux / spawn fails — kickoffs are
+ * intentionally non-fatal off-tmux.
  *
  * 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 fans the answer straight into the
- * asking node's inbox.
+ * so the `pushFinal` the `_run` worker emits — for ask, approve, 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.
  */
 export declare function spawnHumanJob(jobId: string, idir: string, cwd: string): {
     spawned: boolean;
     follow_up: string;
-    paneId?: string;
 };
-export interface HumanResult {
-    status: string;
-    result?: unknown;
-    reason?: string;
-}
 /**
- * Block until `nodeId` emits a `final` report (the human submitted) or — when a
- * pane id is given — that pane dies before submitting (the human closed it).
- * Polls once a second: this is a human-time operation, so a coarse poll is fine
- * and sidesteps fs.watch directory-existence races. The `_run` worker writes
- * the humanloop result as the report body (JSON), which we parse back out.
+ * Best-effort kill of a humanloop worker pane. SAFETY-CRITICAL: a malformed or
+ * empty `-t` target makes tmux fall back to the CALLER's current pane, so a bad
+ * paneId could kill the agent's own pi pane (and, if it is the last pane, the
+ * whole session). This refuses to kill anything that is not provably the worker:
+ *
+ *   1. paneId must be a real tmux pane id (`%<n>`) — never an empty/odd string.
+ *   2. The pane's start command must contain `verify` (the interaction dir, which
+ *      humanloop bakes into the worker's `CRTR_HUMAN_DIR=... crtr human _run`
+ *      launch). A shell (`zsh -l`) or the agent's pi never matches, so we can
+ *      only ever kill the exact worker we spawned for this job.
+ *
+ * Returns true only when a matching pane was found and killed. Never throws.
  */
-export declare function waitForFinalReport(nodeId: string, paneId?: string): Promise<HumanResult>;
+export declare function killPane(paneId: string, verify: string): boolean;