@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/commands/human.js

@@ -1,463 +1,19 @@
 // `crtr human` subtree — in-process humanloop bridge.
 //
-// Kickoff leaves (ask/approve/review) create a kind:'human' job, write
-// deck.json/run.json into the per-cwd interaction dir, spawn a detached
-// `crtr human _run` pane, and return immediately. The agent polls the existing
-// `crtr job read result|status|logs` / `crtr job cancel` — no new poll surface.
-// notify/show create no job. _run runs the blocking humanloop call at the pane
-// TTY and writes the job result itself.
+// Kickoff leaves (ask/approve/review) create a kind:'human' node under the
+// asking node, write deck.json/run.json into the per-cwd interaction dir, spawn
+// a detached `crtr human _run` pane, and return immediately. The human's answer
+// is pushed as the node's final report, which fans out to the asking node's
+// inbox — no polling surface. notify/show create no node. _run runs the blocking
+// humanloop call at the pane TTY and pushes the result itself.
 //
 // TTY safety: every leaf is argv-only — none declares a stdin parameter, so
 // the spawned pane's TTY stays free for humanloop's raw-mode input. Control
 // params travel via CRTR_HUMAN_DIR (set inline in the spawned command) +
 // run.json, never stdin.
-import { defineBranch, defineLeaf } from '../core/command.js';
-import { InputError } from '../core/io.js';
-import { createJob, writeResult, recordJobPane, appendEvent, readResult as jobsReadResult } from '../core/jobs.js';
-import { spawnAndDetach, shellQuote, isInTmux, countPanesInCurrentWindow } from '../core/spawn.js';
-import { interactionsRoot, interactionDir } from '../core/artifact.js';
-import { paginate } from '../core/pagination.js';
-import { readConfig } from '../core/config.js';
-import { mkdirSync, existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { ask, launchReview, display, inbox, scanInbox, validateDeck, approveDeck, notifyDeck, parseDeck, deckPath, atomicWriteJson, readJson, } from '@crouton-kit/humanloop';
-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'}]}.";
-function resolveMaxPanes() {
-    return readConfig('user').max_panes_per_window;
-}
-function pickPlacement() {
-    return countPanesInCurrentWindow() >= resolveMaxPanes() ? 'new-window' : 'split-h';
-}
-function runCmd(dir) {
-    return `CRTR_HUMAN_DIR=${shellQuote(dir)} crtr human _run`;
-}
-function followUpResult(jobId) {
-    return `crtr job read result ${jobId}`;
-}
-function followUpDrain(jobId) {
-    return ('Not in tmux: a human must drain it — run `crtr human inbox` (or re-run ' +
-        `inside tmux). Then: crtr job read result ${jobId}`);
-}
-/**
- * Spawn the detached `_run` pane for a job-backed kickoff, record the pane for
- * cancellation, log the start, and return whether the pane spawned plus the
- * appropriate follow_up. Degrades to the inbox-drain follow_up (job still
- * created) when not in tmux / spawn fails — kickoffs are intentionally
- * non-fatal off-tmux.
- */
-function spawnHumanJob(jobId, idir, cwd) {
-    const spawn = spawnAndDetach({
-        command: runCmd(idir),
-        cwd,
-        jobId,
-        placement: pickPlacement(),
-        killAfterSeconds: 0,
-        failGuard: true,
-    });
-    if (spawn.status !== 'spawned') {
-        return { spawned: false, follow_up: followUpDrain(jobId) };
-    }
-    if (spawn.paneId !== undefined)
-        recordJobPane(jobId, spawn.paneId);
-    const paneLabel = spawn.paneId !== undefined ? spawn.paneId : 'unknown';
-    appendEvent(jobId, {
-        level: 'info',
-        event: 'worker_started',
-        message: `human pane ${paneLabel} spawned`,
-    });
-    return { spawned: true, follow_up: followUpResult(jobId) };
-}
-// ---------------------------------------------------------------------------
-// ask
-// ---------------------------------------------------------------------------
-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: 'Poll with `crtr job read result|status|logs`; cancel with `crtr job cancel`.' },
-            { 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" job 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 } = createJob('human', { cwd });
-        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
-// ---------------------------------------------------------------------------
-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: 'Poll with `crtr job read result`; result is {approved, …envelope}.' },
-            { 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" job 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 } = createJob('human', { cwd });
-        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
-// ---------------------------------------------------------------------------
-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: 'The kind:"human" job backing this review. Cancel with `crtr job cancel`.' },
-            { 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" job 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 } = createJob('human', { cwd });
-        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 } = 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, the pane closes, or the job is
-        // canceled. Infinity = no timeout (the human owns the clock); the poll in
-        // readResult still reaps a dead pane, so this never hangs on a closed pane.
-        const r = await jobsReadResult(jobId, { waitMs: Infinity });
-        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)
-// ---------------------------------------------------------------------------
-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 crtr job.',
-        ],
-    },
-    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,
-                failGuard: false,
-            });
-            shown = spawn.status === 'spawned';
-        }
-        return { shown, dir: idir };
-    },
-});
-// ---------------------------------------------------------------------------
-// show (no job, non-blocking passthrough)
-// ---------------------------------------------------------------------------
-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 };
-    },
-});
-// ---------------------------------------------------------------------------
-// inbox (human-invoked, blocking)
-// ---------------------------------------------------------------------------
-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)
-// ---------------------------------------------------------------------------
-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)
-// ---------------------------------------------------------------------------
-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 job-backed modes writes result.json via the job model.'],
-    },
-    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') {
-                    writeResult(rc.job_id, env, 'done');
-                }
-                else if (rc.mode === 'approve') {
-                    const sel = env.responses.find((r) => r.id === rc.approve_iid)?.selectedOptionId;
-                    writeResult(rc.job_id, {
-                        approved: sel === 'yes',
-                        summary: env.summary,
-                        responses: env.responses,
-                        responsePath: env.responsePath,
-                        completedAt: env.completedAt,
-                    }, 'done');
-                }
-                // 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,
-                });
-                writeResult(rc.job_id, res, 'done');
-            }
-        }
-        catch (e) {
-            if (rc.job_id !== undefined) {
-                writeResult(rc.job_id, { error: 'human_run_failed', message: String(e) }, 'failed');
-            }
-        }
-    },
-});
-// ---------------------------------------------------------------------------
-// branch
-// ---------------------------------------------------------------------------
+import { defineBranch } from '../core/command.js';
+import { humanAsk, humanApprove, humanReview, humanNotify, humanShow } from './human/prompts.js';
+import { humanInbox, humanList, humanRun } from './human/queue.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
@@ -469,7 +25,7 @@ export function registerHuman() {
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Reach for human whenever you have a question for the user or want their feedback — never guess or assume when a person can decide. ask puts a structured choice in front of them; approve gates a handoff on a Yes/No sign-off; review collects anchored comments on a plan or spec; notify informs without blocking; show puts a file live on screen. Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask/approve/review are the DEFAULT channel for questions, sign-offs, and feedback — reach for them even for quick or open-ended asks (use `allowFreetext`), and don't substitute prose in your reply. ask and approve are kickoffs: they create kind:'human' jobs and return instantly, never blocking — peek later with `crtr job read result|status` (no `wait`). review is different: it BLOCKS until the human submits, so background the call if you want to keep working (your harness notifies you when it finishes). 'Humans respond on human time' describes response latency only — it is never a reason to avoid asking. Cancel with `crtr job cancel`. notify/show create no job.",
+            model: "Reach for human whenever you have a question for the user or want their feedback — never guess or assume when a person can decide. ask puts a structured choice in front of them; approve gates a handoff on a Yes/No sign-off; review collects anchored comments on a plan or spec; notify informs without blocking; show puts a file live on screen. Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask/approve/review are the DEFAULT channel for questions, sign-offs, and feedback — reach for them even for quick or open-ended asks (use `allowFreetext`), and don't substitute prose in your reply. ask and approve are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the answer is pushed to your inbox when the human responds, so just keep working and you'll be woken with it. review is different: it BLOCKS until the human submits, so background the call if you want to keep working (your harness notifies you when it finishes). 'Humans respond on human time' describes response latency only — it is never a reason to avoid asking. notify/show create no node.",
             children: [
                 { name: 'ask', desc: 'put a decision deck to a person', useWhen: 'a structured choice needs a human' },
                 { name: 'approve', desc: 'a Yes/No approval gate', useWhen: 'gating a handoff on human sign-off' },

package/dist/commands/node.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../core/command.js';
+export declare function registerNode(): BranchDef;