@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/commands/human/prompts.js

@@ -0,0 +1,269 @@
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { spawnNode } from '../../core/runtime/nodes.js';
+import { interactionDir } from '../../core/artifact.js';
+import { isInTmux, spawnAndDetach } from '../../core/spawn.js';
+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';
+/** 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;
+}
+// ---------------------------------------------------------------------------
+// ask
+// ---------------------------------------------------------------------------
+export const humanAsk = defineLeaf({
+    name: 'ask',
+    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.',
+        guide: 'Use this for quick, open-ended, and nuanced asks alike — not just "formal" multiple-choice. Set `allowFreetext: true` (with `freetextLabel`) when the answer is open-ended; offer a few `options` as starting points even for judgment calls. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body 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: 'context-file', name: 'deck', required: true, constraint: 'Contains a humanloop deck. Validated before any job is created.', shape: DECK_SCHEMA_HINT },
+            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Accepted for symmetry with the job contract; the kickoff never blocks.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json/run.json/response.json.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek. The human may take minutes to hours — never block waiting on this.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a kind:"human" node under you and writes deck.json/run.json to the interaction dir.',
+            'Spawns the decision TUI in a detached tmux pane (when in tmux).',
+        ],
+    },
+    run: async (input) => {
+        let deck;
+        try {
+            deck = validateDeck(input['deck']);
+        }
+        catch (e) {
+            throw new InputError({
+                error: 'deck_invalid',
+                message: String(e),
+                field: 'deck',
+                next: DECK_SCHEMA_HINT,
+            });
+        }
+        const cwd = process.cwd();
+        const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+        const idir = interactionDir(jobId, cwd);
+        mkdirSync(idir, { recursive: true });
+        atomicWriteJson(deckPath(idir), deck);
+        const rc = { mode: 'ask', job_id: jobId };
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
+        return { job_id: jobId, dir: idir, follow_up };
+    },
+});
+// ---------------------------------------------------------------------------
+// approve
+// ---------------------------------------------------------------------------
+export const humanApprove = defineLeaf({
+    name: 'approve',
+    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.',
+        guide: 'The body 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: 'title', type: 'string', required: true, constraint: 'The question shown to the human.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Optional one-line context.' },
+            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this approval; the {approved, …envelope} result is pushed to your inbox when answered.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek. The human may take minutes to hours — never block waiting on this.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a kind:"human" node under you and writes a Yes/No validation deck.',
+            'Spawns the approval TUI in a detached tmux pane (when in tmux).',
+        ],
+    },
+    run: async (input) => {
+        const title = input['title'];
+        const subtitle = input['subtitle'];
+        const body = input['body'];
+        const deck = approveDeck(title, {
+            ...(subtitle !== undefined ? { subtitle } : {}),
+            ...(body !== undefined ? { body } : {}),
+        });
+        const cwd = process.cwd();
+        const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-approve', lifecycle: 'terminal' }).node_id;
+        const idir = interactionDir(jobId, cwd);
+        mkdirSync(idir, { recursive: true });
+        atomicWriteJson(deckPath(idir), deck);
+        const rc = { mode: 'approve', job_id: jobId, approve_iid: 'approve' };
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
+        return { job_id: jobId, dir: idir, follow_up };
+    },
+});
+// ---------------------------------------------------------------------------
+// review
+// ---------------------------------------------------------------------------
+export const humanReview = defineLeaf({
+    name: 'review',
+    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.',
+        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.' },
+        ],
+        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.',
+        ],
+    },
+    run: async (input) => {
+        const fileArg = input['file'];
+        const abs = resolve(fileArg);
+        if (!existsSync(abs)) {
+            throw new InputError({
+                error: 'file_not_found',
+                message: `file not found: ${abs}`,
+                field: 'file',
+                next: 'Provide an absolute path to an existing .md file.',
+            });
+        }
+        if (!abs.endsWith('.md')) {
+            throw new InputError({
+                error: 'invalid_field',
+                message: `review requires a .md file: ${abs}`,
+                field: 'file',
+                next: 'Point `file` at a Markdown (.md) artifact.',
+            });
+        }
+        const cwd = process.cwd();
+        const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-review', lifecycle: 'terminal' }).node_id;
+        const idir = interactionDir(jobId, cwd);
+        mkdirSync(idir, { recursive: true });
+        const outputArg = input['output'];
+        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;
+    },
+});
+// ---------------------------------------------------------------------------
+// notify (no job)
+// ---------------------------------------------------------------------------
+export const humanNotify = defineLeaf({
+    name: 'notify',
+    help: {
+        name: 'human notify',
+        summary: 'show a fire-and-forget acknowledgement; creates no job',
+        guide: 'The body 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: 'title', type: 'string', required: true, constraint: 'The notification headline.' },
+            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
+        ],
+        output: [
+            { name: 'shown', type: 'boolean', required: true, constraint: 'True if the TUI pane was spawned; false when not in tmux (deck surfaces in `human inbox`).' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Writes a notify deck to the per-project interactions root.',
+            'Spawns the acknowledgement TUI in a detached tmux pane when in tmux. Creates no node.',
+        ],
+    },
+    run: async (input) => {
+        const title = input['title'];
+        const body = input['body'];
+        const deck = notifyDeck(title, body !== undefined ? { body } : {});
+        const cwd = process.cwd();
+        const id = `nfy-${randomBytes(4).toString('hex')}`;
+        const idir = interactionDir(id, cwd);
+        mkdirSync(idir, { recursive: true });
+        atomicWriteJson(deckPath(idir), deck);
+        const rc = { mode: 'notify' };
+        atomicWriteJson(join(idir, 'run.json'), rc);
+        let shown = false;
+        if (isInTmux()) {
+            const spawn = spawnAndDetach({
+                command: runCmd(idir),
+                cwd,
+                placement: pickPlacement(),
+                killAfterSeconds: 0,
+            });
+            shown = spawn.status === 'spawned';
+        }
+        return { shown, dir: idir };
+    },
+});
+// ---------------------------------------------------------------------------
+// show (no job, non-blocking passthrough)
+// ---------------------------------------------------------------------------
+export const humanShow = defineLeaf({
+    name: 'show',
+    help: {
+        name: 'human show',
+        summary: 'put a file live on screen in a tmux pane via humanloop display',
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file 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: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
+            { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },
+        ],
+        output: [
+            { name: 'pane_id', type: 'string | null', required: true, constraint: 'Tmux pane id, or null when not displayed.' },
+            { name: 'reason', type: 'string | null', required: true, constraint: 'Why no pane was created, or null on success.' },
+        ],
+        outputKind: 'object',
+        effects: ['Spawns a live-watch tmux pane when possible. No job. Always exits 0.'],
+    },
+    run: async (input) => {
+        const path = input['path'];
+        const windowArg = input['window'];
+        const window = windowArg !== undefined ? windowArg : 'auto';
+        // `human show` must never fail the caller: any display error degrades to
+        // {pane_id:null, reason} with exit 0 (matches humanloop display semantics).
+        let paneId;
+        try {
+            const r = display(path, { window, maxPanes: resolveMaxPanes() });
+            paneId = r.paneId;
+        }
+        catch {
+            paneId = undefined;
+        }
+        if (paneId !== undefined) {
+            return { pane_id: paneId, reason: null };
+        }
+        const reason = isInTmux()
+            ? 'renderer unavailable (termrender/uv missing)'
+            : 'not in tmux';
+        return { pane_id: null, reason };
+    },
+});

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

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

package/dist/commands/human/queue.js

@@ -0,0 +1,133 @@
+import { defineLeaf } from '../../core/command.js';
+import { pushFinal } from '../../core/feed/feed.js';
+import { interactionsRoot } from '../../core/artifact.js';
+import { paginate } from '../../core/pagination.js';
+import { join } from 'node:path';
+import { inbox, scanInbox, parseDeck, deckPath, ask, launchReview, readJson, } from '@crouton-kit/humanloop';
+// ---------------------------------------------------------------------------
+// inbox (human-invoked, blocking)
+// ---------------------------------------------------------------------------
+export const humanInbox = defineLeaf({
+    name: 'inbox',
+    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.' }],
+        outputKind: 'object',
+        effects: ['Resolves pending interactions in the per-project interactions root via the TUI.'],
+    },
+    run: async () => {
+        await inbox([interactionsRoot(process.cwd())]);
+        return { drained: true };
+    },
+});
+// ---------------------------------------------------------------------------
+// list (read-only, paginated)
+// ---------------------------------------------------------------------------
+export const humanList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'human list',
+        summary: 'paginated list of pending, unclaimed interactions, oldest first',
+        params: [
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20, max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: "Opaque token from a previous response's next_cursor. Omit on first call." },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, kind, blocked_since}. Oldest first.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Pass on the next call to continue. null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Total pending interactions.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const limitRaw = input['limit'];
+        const limit = Math.min(Math.max(1, limitRaw), 100);
+        const cursor = input['cursor'];
+        const raw = scanInbox([interactionsRoot(process.cwd())]);
+        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,
+        }))
+            .sort((a, b) => {
+            const ka = `${a.blocked_since}|${a.id}`;
+            const kb = `${b.blocked_since}|${b.id}`;
+            return ka < kb ? -1 : ka > kb ? 1 : 0;
+        });
+        const page = paginate(items, { limit, cursor }, {
+            defaultLimit: 20,
+            maxLimit: 100,
+            keyOf: (i) => `${i.blocked_since}|${i.id}`,
+            total: 'count',
+        });
+        return { items: page.items, next_cursor: page.next_cursor, total: page.total };
+    },
+});
+// ---------------------------------------------------------------------------
+// _run (hidden worker; not listed in branch help)
+// ---------------------------------------------------------------------------
+export const humanRun = defineLeaf({
+    name: '_run',
+    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.' }],
+        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).'],
+    },
+    run: async () => {
+        const dir = process.env['CRTR_HUMAN_DIR'];
+        if (dir === undefined || dir === '') {
+            process.exit(1);
+        }
+        const rc = readJson(join(dir, 'run.json'));
+        if (rc === null) {
+            process.exit(1);
+        }
+        try {
+            if (rc.mode === 'ask' || rc.mode === 'approve' || 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));
+                }
+                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,
+                    }));
+                }
+                // 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. This matches how ask/approve
+                // render in-place and avoids the redundant side pane.
+                const res = await launchReview(rc.file, {
+                    output: rc.output,
+                    noTmux: true,
+                });
+                await pushFinal(rc.job_id, JSON.stringify(res));
+            }
+        }
+        catch (e) {
+            if (rc.job_id !== undefined) {
+                await pushFinal(rc.job_id, JSON.stringify({ error: 'human_run_failed', message: String(e) }));
+            }
+        }
+    },
+});

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

@@ -0,0 +1,43 @@
+export declare const DECK_SCHEMA_HINT: string;
+export interface RunRecord {
+    mode: 'ask' | 'approve' | 'notify' | 'review';
+    job_id?: string;
+    approve_iid?: string;
+    file?: string;
+    output?: 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;
+/**
+ * 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.
+ *
+ * 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.
+ */
+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.
+ */
+export declare function waitForFinalReport(nodeId: string, paneId?: string): Promise<HumanResult>;

package/dist/commands/human/shared.js

@@ -0,0 +1,107 @@
+import { readConfig } from '../../core/config.js';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../core/spawn.js';
+import { reportsDir } from '../../core/canvas/paths.js';
+export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
+    'source?:{sessionName?,askedBy?,blockedSince?}, ' +
+    'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
+    'description?,shortcut?}],multiSelect?,allowFreetext?,freetextLabel?,' +
+    "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
+export function resolveMaxPanes() {
+    return readConfig('user').max_panes_per_window;
+}
+export function pickPlacement() {
+    return countPanesInCurrentWindow() >= resolveMaxPanes() ? 'new-window' : 'split-h';
+}
+export function runCmd(dir) {
+    return `CRTR_HUMAN_DIR=${shellQuote(dir)} crtr human _run`;
+}
+export function followUpResult(_jobId) {
+    return "The human's answer is delivered to your inbox when they respond — no need to poll.";
+}
+export function followUpDrain(_jobId) {
+    return ('Not in tmux: a human must drain it — run `crtr human inbox` (or re-run ' +
+        'inside tmux). The answer then arrives in your inbox.');
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function spawnHumanJob(jobId, idir, cwd) {
+    const spawn = spawnAndDetach({
+        command: runCmd(idir),
+        cwd,
+        jobId,
+        placement: pickPlacement(),
+        killAfterSeconds: 0,
+    });
+    if (spawn.status !== 'spawned') {
+        return { spawned: false, follow_up: followUpDrain(jobId) };
+    }
+    return {
+        spawned: true,
+        follow_up: followUpResult(jobId),
+        ...(spawn.paneId !== undefined ? { paneId: spawn.paneId } : {}),
+    };
+}
+/** True when a tmux pane is still alive. */
+function paneAlive(paneId) {
+    const r = spawnSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    return r.status === 0 && r.stdout.trim() !== '';
+}
+/**
+ * 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.
+ */
+export function waitForFinalReport(nodeId, paneId) {
+    const dir = reportsDir(nodeId);
+    const findFinal = () => {
+        if (!existsSync(dir))
+            return null;
+        const files = readdirSync(dir).filter((f) => f.endsWith('-final.md')).sort();
+        return files.length > 0 ? join(dir, files[files.length - 1]) : null;
+    };
+    const parse = (path) => {
+        const body = readFileSync(path, 'utf8').replace(/^---[\s\S]*?---\n/, '').trim();
+        try {
+            return { status: 'done', result: JSON.parse(body) };
+        }
+        catch {
+            return { status: 'done' };
+        }
+    };
+    const immediate = findFinal();
+    if (immediate !== null)
+        return Promise.resolve(parse(immediate));
+    return new Promise((resolve) => {
+        const timer = setInterval(() => {
+            const p = findFinal();
+            if (p !== null) {
+                clearInterval(timer);
+                resolve(parse(p));
+                return;
+            }
+            if (paneId !== undefined && !paneAlive(paneId)) {
+                clearInterval(timer);
+                resolve({ status: 'closed', reason: 'review pane closed before submit' });
+            }
+        }, 1000);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    });
+}