@crouton-kit/humanloop 0.2.1 → 0.3.2

package/dist/cli.js

@@ -1,357 +1,195 @@
 #!/usr/bin/env node
-import { Command, Option } from 'commander';
-import { writeFileSync, mkdtempSync } from 'fs';
-import { tmpdir } from 'os';
-import { resolve, join } from 'path';
-import { dispatchToTmuxPane } from './tui/tmux.js';
-import { findRecentSessionId } from './conversation/reader.js';
-import { launchReview, formatFeedbackSummary } from './editor/review.js';
-import { parseDeck } from './inbox/deck-schema.js';
+import { Command } from 'commander';
+import { writeFileSync, mkdirSync, mkdtempSync, existsSync, readFileSync, appendFileSync, statSync, } from 'node:fs';
+import { readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, join, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { launchReview } from './editor/review.js';
+import { validateDeck } from './inbox/deck-schema.js';
 import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
-const program = new Command();
-program
-    .name('hl')
-    .description('Human-in-the-loop decision TUI.\n' +
-    '\n' +
-    'Use this when you (the agent) need the human to make a material decision\n' +
-    'before continuing — design tradeoffs, approval gates, picks between real\n' +
-    'alternatives. Blocks on an interactive TUI and returns answers as JSON.\n' +
-    'Reach for it when you have 2+ structured questions, or one decision with\n' +
-    'genuine tradeoffs; for a single freetext question, ask inline instead.\n' +
-    '\n' +
-    'AUDIENCE — the deck you write is read by a busy, technical human. Use\n' +
-    'progressive disclosure so the reader can stop at any layer:\n' +
-    '  • title    — noun-phrase topic (≤4 words). Scannable like an inbox.\n' +
-    '  • subtitle — TL;DR. One plain sentence framing the choice or stakes.\n' +
-    '  • body     — ELI12 markdown. Plain language up top, deeper material\n' +
-    '               under a heading the reader can skip.\n' +
-    'The reader can connect dots — do not write engineer-to-engineer jargon.\n' +
-    'See `hl ask --help` for content guidance and a worked example.\n' +
-    '\n' +
-    'Workflow:\n' +
-    '  1. Write a deck file matching `hl schema` (a JSON object with interactions[]).\n' +
-    '  2. Run `hl ask <file>`; it blocks and prints a ResolutionEnvelope JSON to stdout.\n' +
-    '  3. Parse the JSON; look up answers by `id` (humans can skip questions).')
-    .version('0.1.0')
-    .addHelpText('after', '\nExamples:\n' +
-    '  hl schema                          # print the input JSON schema\n' +
-    '  hl schema response                 # print the resolution-envelope schema\n' +
-    '  hl ask deck.json                   # open TUI, block, print envelope JSON\n' +
-    '  hl ask deck.json --dir /tmp/ix     # store progress/response.json in /tmp/ix\n' +
-    '  hl ask deck.json --no-tmux         # run in current pane even inside tmux\n' +
-    '  hl inbox /tmp/box                  # resolve pending interactions under a root\n' +
-    '  hl display plan.md                 # live-render a file in a tmux pane\n');
-program
-    .command('ask')
-    .description('Open the decisions TUI on <file> and block until the human finishes review.\n' +
-    'Prints a ResolutionEnvelope JSON to stdout (or to --output / --write-to).')
-    .argument('<file>', 'Path to deck JSON file (see `hl schema` for format)')
-    .option('--dir <interaction-dir>', 'Interaction directory holding progress.json/response.json. Default: a managed temp dir under os.tmpdir().')
-    .option('--session-id <id>', 'Claude session ID; enables per-interaction visual context from conversation history. Defaults to the most recent session in cwd.')
-    .option('--no-visuals', 'Skip visual context generation (faster, no haiku calls)')
-    .option('--output <path>', 'Write result JSON to <path> instead of stdout')
-    .option('--no-tmux', 'Do not auto-dispatch the TUI to a new tmux pane even when $TMUX is set')
-    .addOption(new Option('--write-to <path>', 'internal: tmux child mode').hideHelp())
-    .addHelpText('after', '\n' +
-    'CONTENT — what to write in each interaction\n' +
-    '  The deck is read by a busy, technical human. Use progressive\n' +
-    '  disclosure so the reader can stop at any layer:\n' +
-    '\n' +
-    '    title      Noun-phrase topic (≤4 words). The *thing* being\n' +
-    '               decided, not the decision. \'Database\' not \'Use\n' +
-    '               Postgres\'. The reader scans titles like an inbox.\n' +
-    '    subtitle   TL;DR — one plain-English sentence framing the\n' +
-    '               choice or stakes. Action-ready if the call is\n' +
-    '               obvious. No jargon, no library names without\n' +
-    '               context.\n' +
-    '    body       ELI12 markdown. Audience: a smart engineer joining\n' +
-    '               the codebase — capable, but does not want a wall of\n' +
-    '               jargon. Lead with what is at stake in plain language.\n' +
-    '               Tuck anything denser (technical specifics, alternatives\n' +
-    '               considered, edge cases, related context) under a\n' +
-    '               heading like `## Details` or `## Alternatives` so the\n' +
-    '               reader can skip past it. Every layer below the TL;DR\n' +
-    '               is optional reading.\n' +
-    '\n' +
-    '  AVOID: walls of jargon; raw schema dumps or stack traces in body;\n' +
-    '  titles that bury the topic; subtitles that restate the title;\n' +
-    '  options that are not real alternatives; asking the human anything\n' +
-    '  you could decide yourself from the code.\n' +
-    '\n' +
-    'INPUT FORMAT\n' +
-    '  JSON file with an `interactions` array. Each interaction has an `id`,\n' +
-    '  `title`, `options[]`, and optional `subtitle`, `body`, `allowFreetext`.\n' +
-    '  Run `hl schema` for the full schema. Example with pyramid content:\n' +
-    '    {\n' +
-    '      "interactions": [\n' +
-    '        {\n' +
-    '          "id": "db",\n' +
-    '          "title": "Database",\n' +
-    '          "subtitle": "Postgres or SQLite for the new capture store?",\n' +
-    '          "body": "Two services will write at the same time, which is the crux.\\n\\nPostgres handles concurrent writes natively. SQLite serializes them — fine at low traffic, but we expect bursts.\\n\\n## Details\\nSQLite WAL still serializes writers; Postgres uses MVCC.",\n' +
-    '          "options": [\n' +
-    '            {"id":"pg","label":"Postgres"},\n' +
-    '            {"id":"sqlite","label":"SQLite"}\n' +
-    '          ],\n' +
-    '          "allowFreetext": true\n' +
-    '        },\n' +
-    '        {\n' +
-    '          "id": "retry",\n' +
-    '          "title": "Retry policy",\n' +
-    '          "subtitle": "How aggressively should we retry publish failures?",\n' +
-    '          "body": "Affects the reliability budget. Too aggressive and we hammer downstream during outages; too lax and transient blips become user-visible.",\n' +
-    '          "options": [],\n' +
-    '          "allowFreetext": true\n' +
-    '        }\n' +
-    '      ]\n' +
-    '    }\n' +
-    '\n' +
-    'OUTPUT FORMAT (stdout on success, JSON — a ResolutionEnvelope)\n' +
-    '  {\n' +
-    '    "summary": "<one line per answered interaction>",\n' +
-    '    "responsePath": "/abs/path/to/<dir>/response.json",\n' +
-    '    "schema": "humanloop.response/v2",\n' +
-    '    "responses": [ ... ],\n' +
-    '    "completedAt": "2026-04-20T15:23:00.000Z"\n' +
-    '  }\n' +
-    '\n' +
-    '  On-disk <dir>/response.json holds only { responses, completedAt }.\n' +
-    '  Run `hl schema response` for the envelope schema.\n' +
-    '\n' +
-    '  Response shape:\n' +
-    '    { id: string, selectedOptionId?: string, freetext?: string }\n' +
-    '\n' +
-    '  The human can skip interactions. `responses` may have FEWER entries than\n' +
-    '  input interactions — look up by `id`, do not assume index alignment.\n' +
-    '\n' +
-    'BEHAVIOR\n' +
-    '  tmux       When $TMUX is set, the TUI auto-splits into a new pane to the\n' +
-    '             right (-d keeps focus on the caller). Disable with --no-tmux.\n' +
-    '  storage    progress.json/response.json live in --dir (default: a managed\n' +
-    '             temp dir). Responses persist atomically after every change;\n' +
-    '             a hard kill resumes from progress.json on the next run.\n' +
-    '             response.json is written when the human finishes.\n' +
-    '  visuals    With --session-id (or auto-detected) haiku generates a short\n' +
-    '             ANSI context block per interaction from recent conversation turns.\n' +
-    '\n' +
-    'EXIT CODES\n' +
-    '  0  success — result JSON emitted\n' +
-    '  1  error — message on stderr (file missing, invalid JSON, empty\n' +
-    '     interactions, no TTY, etc.)\n')
-    .action(async (file, opts) => {
-    const sessionId = opts.visuals
-        ? (opts.sessionId || findRecentSessionId(process.cwd()) || findRecentSessionId() || undefined)
-        : undefined;
-    const dir = opts.dir ? resolve(opts.dir) : mkdtempSync(join(tmpdir(), 'hl-ix-'));
-    const emit = (result) => {
-        const json = JSON.stringify(result, null, 2) + '\n';
-        if (opts.writeTo) {
-            writeFileSync(opts.writeTo, json);
-        }
-        else if (opts.output) {
-            writeFileSync(opts.output, json);
-        }
-        else {
-            process.stdout.write(json);
-        }
-    };
+import { scanInbox } from './inbox/scan.js';
+import { deckPath, atomicWriteJson, readJson, responsePath, } from './inbox/convention.js';
+// ── Version ───────────────────────────────────────────────────────────────────
+const HL_VERSION = '0.2.1';
+function emitError(err, exitCode = 1) {
+    process.stdout.write(JSON.stringify(err) + '\n');
+    process.exit(exitCode);
+}
+function emitStderrError(err, exitCode = 1) {
+    process.stderr.write(JSON.stringify(err) + '\n');
+    process.exit(exitCode);
+}
+// ── stdin reader ──────────────────────────────────────────────────────────────
+function readStdin() {
+    let content = '';
+    const stdinResult = { ok: false, value: '' };
     try {
-        if (process.env.TMUX && opts.tmux && !opts.writeTo) {
-            try {
-                const result = await dispatchToTmuxPane(file, { sessionId, visuals: opts.visuals, dir });
-                emit(result);
-                process.exit(0);
-            }
-            catch (err) {
-                process.stderr.write(`tmux dispatch failed, running locally: ${err instanceof Error ? err.message : String(err)}\n`);
-            }
-        }
-        const deck = parseDeck(resolve(file));
-        const result = await ask(deck, { dir, sessionId });
-        emit(result);
-        process.exit(0);
+        const _io = {};
+        void _io;
+        stdinResult.value = readFileSync('/dev/stdin', 'utf8');
+        stdinResult.ok = true;
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`ERROR: ${msg}\n`);
-        if (msg.includes('ENOENT') || msg.includes('no such file')) {
-            process.stderr.write('\nFix: pass a path to an existing deck JSON file.\nSee format: hl schema\n');
-        }
-        else if (msg.includes('not valid JSON') || msg.includes('JSON')) {
-            process.stderr.write('\nFix: the deck file must be valid JSON matching `hl schema`.\n');
-        }
-        else if (msg.includes('TTY')) {
-            process.stderr.write('\nFix: hl needs an interactive terminal. If the caller captures stdin,\nrun inside tmux so hl can auto-dispatch the TUI to a new pane, or pipe\nstdin from /dev/tty.\n');
-        }
-        else {
-            process.stderr.write('\nFix: the deck file must match `hl schema`. Run `hl schema` to see the required shape.\n');
-        }
-        process.exit(1);
+    catch (stdinErr) {
+        process.stderr.write(`[hl] stdin read error: ${stdinErr instanceof Error ? stdinErr.message : String(stdinErr)}\n`);
     }
-});
-program
-    .command('inbox')
-    .description('Resolve pending interactions across one or more root directories.\n' +
-    'Each root\'s immediate subdirs are treated as interaction dirs (a dir\n' +
-    'with deck.json and no response.json is pending). Lists them, lets the\n' +
-    'human pick and resolve one at a time, writing each response.json.')
-    .argument('<roots...>', 'Root dir(s) whose immediate subdirs are interaction dirs')
-    .addHelpText('after', '\n' +
-    'BEHAVIOR\n' +
-    '  Runs in the current terminal (requires a TTY). Up/down (or j/k) to\n' +
-    '  navigate, enter to resolve the selected interaction, q/esc to quit.\n' +
-    '  After each resolution the list rescans — resolved items drop out.\n' +
-    '\n' +
-    'EXIT CODES\n' +
-    '  0  finished (human quit, or nothing pending)\n' +
-    '  1  error (no TTY, unreadable root, etc.)\n' +
-    '\n' +
-    'Examples:\n' +
-    '  hl inbox /tmp/box\n' +
-    '  hl inbox ~/.sisyphus/asks ~/.crtr/pending\n')
-    .action(async (roots) => {
+    content = stdinResult.value;
+    return content;
+}
+function parseStdinJson() {
+    const raw = readStdin().trim();
+    if (!raw) {
+        emitStderrError({
+            error: 'bad_stdin_json',
+            message: 'No input on stdin. Expected a JSON object.',
+            next: "Pipe a JSON object to stdin, e.g.: echo '{\"deck\":{...}}' | hl deck ask",
+        });
+    }
+    let parsed;
+    const parseResult = { ok: false };
     try {
-        await inbox(roots.map((r) => resolve(r)));
-        process.exit(0);
+        const _p = {};
+        void _p;
+        parseResult.value = JSON.parse(raw);
+        parseResult.ok = true;
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`ERROR: ${msg}\n`);
-        if (msg.includes('TTY')) {
-            process.stderr.write('\nFix: hl inbox needs an interactive terminal.\n');
-        }
-        process.exit(1);
+    catch (parseErr) {
+        emitStderrError({
+            error: 'bad_stdin_json',
+            message: `stdin is not valid JSON: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`,
+            received: raw.slice(0, 200),
+            next: 'Pipe a valid JSON object to stdin.',
+        });
     }
-});
-program
-    .command('display')
-    .description('Render <path> live in a tmux pane (via the managed termrender). The pane\n' +
-    'live-updates as the file changes. Auto-splits, or opens a new window when\n' +
-    'the current window is at its pane budget.')
-    .argument('<path>', 'Path to the markdown/text file to render')
-    .option('--no-watch', 'Render once instead of live-watching the file')
-    .option('--new-window', 'Open in a new tmux window instead of splitting the current one')
-    .addHelpText('after', '\n' +
-    'EXIT CODES\n' +
-    '  0  spawned (prints the pane id) — or no-op when not in tmux / renderer\n' +
-    '     unavailable (message on stderr)\n' +
-    '\n' +
-    'Examples:\n' +
-    '  hl display plan.md\n' +
-    '  hl display plan.md --no-watch\n' +
-    '  hl display plan.md --new-window\n')
-    .action((path, opts) => {
-    const res = display(resolve(path), {
-        watch: opts.watch,
-        window: opts.newWindow ? 'new' : 'auto',
-    });
-    if (res.paneId) {
-        process.stdout.write(`opened in tmux pane ${res.paneId} (live — edits to the file refresh the view)\n`);
+    if (parseResult.ok)
+        parsed = parseResult.value;
+    return parsed;
+}
+function jobLogPath(dir) {
+    return join(dir, 'job.log');
+}
+function appendJobLog(dir, entry) {
+    const line = { ts: new Date().toISOString(), ...entry };
+    const serialized = JSON.stringify(line) + '\n';
+    const logResult = { wrote: false };
+    try {
+        const _l = {};
+        void _l;
+        appendFileSync(jobLogPath(dir), serialized);
+        logResult.wrote = true;
     }
-    else {
-        process.stderr.write('display: no pane opened (not in tmux, or termrender unavailable)\n');
+    catch (writeErr) {
+        void Object.assign(logResult, { error: String(writeErr) }); // best-effort; never throws
     }
-    process.exit(0);
-});
-program
-    .command('propose')
-    .description('Open a markdown document in a read-only editor review session and block\n' +
-    'until the human finishes and quits. Use this when you have produced a\n' +
-    'document (plan, design doc, spec, draft) and need targeted human review\n' +
-    'before continuing — not a structured decision (use `hl ask` for that).')
-    .argument('<file>', 'Path to the markdown (.md) file to get feedback on')
-    .option('--output <path>', 'Path for the answers JSON (live autosave + finalized on exit). Default: <file>.feedback.json')
-    .option('--editor <bin>', 'Editor binary to use. Default: first of nvim, vim on PATH')
-    .option('--no-tmux', 'Run the editor in the current terminal instead of a tmux split pane')
-    .addHelpText('after', '\n' +
-    'WHAT THIS IS FOR\n' +
-    '  Freeform review of a markdown doc you wrote. The human leaves comments\n' +
-    '  anchored to real source lines or visual selections using native vim\n' +
-    '  keybindings — you do not predefine questions; the human tells you what\n' +
-    '  is wrong and where.\n' +
-    '\n' +
-    'BEHAVIOR\n' +
-    '  • Opens the file READ-ONLY in a CLEAN editor (nvim -u NONE: no\n' +
-    '    init.lua / LazyVim / plugins / keymaps). Look/feel is ONLY the\n' +
-    '    user\'s gloam colorscheme + built-in treesitter markdown\n' +
-    '    highlighting. Review keys are buffer-scoped on <Space>,\n' +
-    '    plus :HL* commands.\n' +
-    '  • When $TMUX is set, opens in a split pane (disable with --no-tmux);\n' +
-    '    otherwise takes over the current terminal.\n' +
-    '  • Comments autosave to the answers JSON continuously. A killed/closed\n' +
-    '    session RESUMES from the autosave on next run.\n' +
-    '  • ANY quit submits. On editor exit the JSON is finalized (submitted:true)\n' +
-    '    and echoed to stdout, then the command exits 0.\n' +
-    '  • Quitting with zero comments sets approved:true ("looks good").\n' +
-    '\n' +
-    '  In-editor (<Space> maps; or use the :HL* commands):\n' +
-    '    <Space>c / :HLComment   Comment on the visual selection or current line\n' +
-    '    <Space>l / :HLList      Toggle comments list\n' +
-    '    <Space>u / :HLUndo      Undo last comment\n' +
-    '    <Space>s / :HLSubmit    Submit & quit\n' +
-    '\n' +
-    'OUTPUT\n' +
-    '  stdout is a COMPACT listing (kept small so it does not clog context):\n' +
-    '  a header with the source path, then per comment:\n' +
-    '\n' +
-    '     1. L46:5-35\n' +
-    '        text:    <the original text in that span>\n' +
-    '        comment: <the human\'s note>\n' +
-    '\n' +
-    '  Range is L<line> (whole line), L<line>:<colStart>-<colEnd> (partial\n' +
-    '  selection), or L<l1>-<l2> / L<l1>:<c1>-<l2>:<c2> across lines. text\n' +
-    '  is the exact selected quote, or the whole line(s) when there was no\n' +
-    '  partial selection. Zero comments => "approved" (looks good, proceed).\n' +
-    '\n' +
-    '  The FULL record is written to --output (default <file>.feedback.json);\n' +
-    '  stdout ends with its path + this schema (read the file only if you\n' +
-    '  actually need the verbose fields — usually you do not):\n' +
-    '    {file, submitted, approved,\n' +
-    '     comments:[{id, line, endLine, quote?, colStart?, colEnd?,\n' +
-    '                lineText, comment, createdAt}],\n' +
-    '     submittedAt, savedAt}\n' +
-    '  cols are 0-based byte offsets, colEnd exclusive. Act on each comment\n' +
-    '  via the source path + range (quote/cols when present).\n' +
-    '\n' +
-    'EXIT CODES\n' +
-    '  0  finished — feedback summary emitted\n' +
-    '  1  error (file missing, no nvim/vim found)\n' +
-    '\n' +
-    'Examples:\n' +
-    '  hl propose plan.md\n' +
-    '  hl propose plan.md --output /tmp/fb.json\n' +
-    '  hl propose plan.md --no-tmux\n' +
-    '  hl propose plan.md --editor vim\n')
-    .action(async (file, opts) => {
+}
+// ── job dir resolution ────────────────────────────────────────────────────────
+function resolveJobDir(jobId) {
+    if (jobId.startsWith('/'))
+        return jobId;
+    const td = tmpdir();
+    const candidate = join(td, jobId);
+    if (existsSync(candidate))
+        return candidate;
+    let entries = [];
+    const scanResult = { entries: [] };
     try {
-        const output = opts.output ?? `${file}.feedback.json`;
-        const result = await launchReview(file, { output, editor: opts.editor, noTmux: !opts.tmux });
-        process.stdout.write(formatFeedbackSummary(result, resolve(output)) + '\n');
-        process.exit(0);
+        const _s = {};
+        void _s;
+        scanResult.entries = readdirSync(td);
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`ERROR: ${msg}\n`);
-        if (msg.startsWith('Markdown file not found')) {
-            process.stderr.write('\nFix: pass a path to an existing markdown file.\n');
+    catch (readdirErr) {
+        void Object.assign(scanResult, { error: String(readdirErr) }); // opportunistic scan
+        return candidate;
+    }
+    entries = scanResult.entries;
+    for (const e of entries) {
+        if (e === jobId || basename(e) === jobId) {
+            const full = join(td, e);
+            if (existsSync(join(full, 'deck.json')))
+                return full;
         }
-        else if (msg.startsWith('Editor not found') || msg.startsWith('No editor found')) {
-            process.stderr.write('\nFix: install Neovim (`brew install neovim`) or pass --editor <path>.\n');
+    }
+    return candidate;
+}
+function detectJobKind(dir) {
+    if (existsSync(join(dir, 'deck.json')))
+        return 'deck';
+    if (existsSync(join(dir, 'feedback.json')) || existsSync(join(dir, 'review.vim')))
+        return 'review';
+    return 'inbox';
+}
+function tryParseJson(text) {
+    try {
+        const _j = {};
+        void _j;
+        return JSON.parse(text);
+    }
+    catch (parseErr) {
+        void String(parseErr);
+        return null;
+    }
+}
+function readLogLines(logPath) {
+    try {
+        const _r = {};
+        void _r;
+        return readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+    }
+    catch (readErr) {
+        void String(readErr);
+        return [];
+    }
+}
+function detectJobState(dir) {
+    if (existsSync(join(dir, 'response.json')))
+        return 'done';
+    if (existsSync(join(dir, 'feedback.json'))) {
+        const fb = tryParseJson(readFileSync(join(dir, 'feedback.json'), 'utf8'));
+        if (fb && fb.submitted)
+            return 'done';
+    }
+    const logPath = jobLogPath(dir);
+    if (existsSync(logPath)) {
+        const lines = readLogLines(logPath);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const entry = tryParseJson(lines[i]);
+            if (!entry)
+                continue;
+            if (entry.event === 'job_failed')
+                return 'failed';
+            if (entry.event === 'job_canceled')
+                return 'canceled';
+            if (entry.event === 'job_finished')
+                return 'done';
         }
-        process.exit(1);
     }
-});
+    return 'live';
+}
+function lastLogEvent(dir) {
+    const logPath = jobLogPath(dir);
+    if (!existsSync(logPath))
+        return null;
+    const lines = readLogLines(logPath);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const entry = tryParseJson(lines[i]);
+        if (entry)
+            return entry;
+    }
+    return null;
+}
+// ── tmux child-mode env var (internal, not a CLI flag) ───────────────────────
+// When the parent dispatches to a tmux pane, it sets HL_WRITE_TO=<path> so the
+// child writes its result there instead of stdout. Implementation detail only.
+const INTERNAL_WRITE_TO = process.env['HL_WRITE_TO'];
+// ── Schemas ───────────────────────────────────────────────────────────────────
 const REQUEST_SCHEMA = {
     $schema: 'https://json-schema.org/draft/2020-12/schema',
-    description: 'Input schema for hl ask (v2)',
+    description: 'Input schema for hl deck ask (v2)',
     type: 'object',
     required: ['interactions'],
     properties: {
-        title: {
-            type: 'string',
-            description: 'Optional deck title shown in the TUI header',
-        },
+        title: { type: 'string', description: 'Optional deck title shown in the TUI header' },
         interactions: {
             type: 'array',
             minItems: 1,
@@ -359,14 +197,13 @@ const REQUEST_SCHEMA = {
                 type: 'object',
                 required: ['id', 'title', 'options'],
                 properties: {
-                    id: { type: 'string', description: 'Unique identifier. Used to look up answers in the output — never assume index alignment.' },
-                    title: { type: 'string', description: 'Noun-phrase topic (≤4 words) — the *thing* being decided, not the decision. \'Database\' not \'Use Postgres\'. The reader scans titles like an inbox.' },
-                    subtitle: { type: 'string', description: 'TL;DR — one plain-English sentence framing the choice or stakes. Action-ready if the call is obvious. No jargon, no library names without context.' },
-                    body: { type: 'string', description: 'ELI12 markdown. Audience: a smart engineer joining the codebase — capable, but does not want a wall of jargon. Lead with what is at stake in plain language. Tuck anything denser (technical specifics, alternatives considered, edge cases) under a heading like `## Details` or `## Alternatives` so the reader can skip past. Every layer below the TL;DR is optional reading.' },
-                    bodyPath: { type: 'string', description: 'Path to a markdown file used in place of `body`; inlined before mount, resolved relative to the deck JSON\'s directory and confined to it. Same content guidance as `body`.' },
+                    id: { type: 'string', description: 'Unique identifier.' },
+                    title: { type: 'string', description: 'Noun-phrase topic (≤4 words).' },
+                    subtitle: { type: 'string' },
+                    body: { type: 'string', description: 'ELI12 markdown body.' },
+                    bodyPath: { type: 'string', description: 'Path to a markdown file used in place of body.' },
                     options: {
                         type: 'array',
-                        description: 'Selectable choices. Empty for freetext-only interactions.',
                         items: {
                             type: 'object',
                             required: ['id', 'label'],
@@ -374,26 +211,13 @@ const REQUEST_SCHEMA = {
                                 id: { type: 'string' },
                                 label: { type: 'string' },
                                 description: { type: 'string' },
-                                shortcut: {
-                                    type: 'string',
-                                    description: 'Single char shortcut. Auto-assigned if absent. Avoid: c r n p q j k space',
-                                },
+                                shortcut: { type: 'string', description: 'Single char. Auto-assigned if absent.' },
                             },
                         },
                     },
-                    allowFreetext: {
-                        type: 'boolean',
-                        description: 'If true, user can add a freetext comment (or respond freely if options is empty)',
-                    },
-                    freetextLabel: {
-                        type: 'string',
-                        description: 'Prompt shown above the freetext input. Default: "Comment" or "Response"',
-                    },
-                    kind: {
-                        type: 'string',
-                        enum: ['notify', 'validation', 'decision', 'context', 'error'],
-                        description: 'Display hint — opaque to humanloop, used by consumers for inbox icons',
-                    },
+                    allowFreetext: { type: 'boolean' },
+                    freetextLabel: { type: 'string' },
+                    kind: { type: 'string', enum: ['notify', 'validation', 'decision', 'context', 'error'] },
                 },
             },
         },
@@ -402,54 +226,654 @@ const REQUEST_SCHEMA = {
 const RESPONSE_SCHEMA = {
     $schema: 'https://json-schema.org/draft/2020-12/schema',
     $id: 'humanloop.response/v2',
-    description: 'Resolution envelope emitted by `hl ask` / returned by ask(). The on-disk <dir>/response.json holds only { responses, completedAt }; responsePath points at it.',
+    description: 'Resolution envelope emitted by hl deck ask / returned by ask().',
     type: 'object',
     required: ['summary', 'responsePath', 'schema', 'responses', 'completedAt'],
     properties: {
-        summary: {
-            type: 'string',
-            description: 'Deterministic, no-LLM. One line per answered interaction: "<title>: <option label>[ — <freetext>]".',
-        },
-        responsePath: {
-            type: 'string',
-            description: 'Absolute path to the on-disk response.json ({ responses, completedAt }).',
-        },
-        schema: {
-            const: 'humanloop.response/v2',
-            description: 'Identifies this response contract.',
-        },
+        summary: { type: 'string' },
+        responsePath: { type: 'string' },
+        schema: { const: 'humanloop.response/v2' },
         responses: {
             type: 'array',
-            description: 'Inline answers. May have FEWER entries than input interactions — humans can skip. Look up by id.',
             items: {
                 type: 'object',
                 required: ['id'],
                 properties: {
                     id: { type: 'string' },
                     selectedOptionId: { type: 'string' },
+                    selectedOptionIds: { type: 'array', items: { type: 'string' } },
                     freetext: { type: 'string' },
                 },
             },
         },
-        completedAt: {
-            type: 'string',
-            description: 'ISO 8601 timestamp when the human finished.',
+        completedAt: { type: 'string' },
+    },
+};
+const FEEDBACK_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    description: 'FeedbackResult written by hl review open / launchReview().',
+    type: 'object',
+    required: ['file', 'submitted', 'approved', 'comments', 'savedAt'],
+    properties: {
+        file: { type: 'string', description: 'Absolute path to the reviewed markdown file.' },
+        submitted: { type: 'boolean' },
+        approved: { type: 'boolean', description: 'True when submitted with zero comments.' },
+        comments: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'line', 'endLine', 'lineText', 'comment', 'createdAt'],
+                properties: {
+                    id: { type: 'string' },
+                    line: { type: 'integer', description: '1-based source line (start).' },
+                    endLine: { type: 'integer', description: '1-based source line (end).' },
+                    quote: { type: 'string' },
+                    colStart: { type: 'integer' },
+                    colEnd: { type: 'integer' },
+                    lineText: { type: 'string' },
+                    comment: { type: 'string' },
+                    createdAt: { type: 'string' },
+                },
+            },
         },
+        submittedAt: { type: 'string' },
+        savedAt: { type: 'string' },
     },
 };
+// ── Commander tree ────────────────────────────────────────────────────────────
+const program = new Command();
 program
-    .command('schema')
-    .description('Print a JSON Schema. `request` (default) = the `hl ask` deck input; `response` = the resolution envelope.')
-    .argument('[kind]', 'request | response', 'request')
-    .addHelpText('after', '\n' +
-    'Use `request` to learn the input format for `hl ask`; `response` to learn\n' +
-    'the envelope `hl ask` prints (schema id "humanloop.response/v2").\n' +
+    .name('hl')
+    .description(`hl ${HL_VERSION} — human-in-the-loop TUI bridge for agents\n` +
+    '\n' +
+    'I/O contract: every leaf reads ONE JSON object from stdin; writes ONE JSON\n' +
+    'object (or JSONL for streams) to stdout; exits 0 on success, non-zero on\n' +
+    'error. Errors are always a JSON object on stdout:\n' +
+    '  { error: <code>, message, next }  — codes: bad_stdin_json | bad_input |\n' +
+    '  deck_invalid | file_not_found | editor_not_found | job_not_found |\n' +
+    '  not_ready | not_in_tmux | internal\n' +
+    '\n' +
+    'Concepts:\n' +
+    '  deck       — structured set of interactions (questions) for the human\n' +
+    '  review     — freeform markdown document review with anchored comments\n' +
+    '  view       — passive live render of a file in a tmux pane\n' +
+    '  inbox      — list/resolve all pending interactions across root dirs\n' +
+    '  job        — a running or completed kickoff (deck ask / review / inbox)\n' +
+    '  schema     — JSON Schema for deck, resolution, or feedback payloads\n' +
+    '\n' +
+    'Subtrees:\n' +
+    '  hl deck   — write questions, get answers      | use when: material decisions\n' +
+    '  hl review — markdown doc review               | use when: doc feedback needed\n' +
+    '  hl view   — live render in pane               | use when: displaying a file\n' +
+    '  hl inbox  — browse pending interactions       | use when: clearing a backlog\n' +
+    '  hl job    — inspect/wait/cancel running jobs  | use when: polling job output\n' +
+    '  hl schema — print JSON Schemas                | use when: validating inputs\n' +
+    '\n' +
+    'Globals: -h / --help on any node.\n')
+    .helpOption('-h, --help', 'Show help')
+    .addHelpCommand(false);
+// ── deck ──────────────────────────────────────────────────────────────────────
+const deckCmd = program.command('deck').description('Write questions, get answers from the human.');
+deckCmd
+    .command('ask')
+    .description('Kickoff: spawn the decisions TUI and return immediately.\n' +
+    '\n' +
+    'stdin  { deck: object (required), dir?: string|null,\n' +
+    '         sessionId?: string|null, visuals?: bool=true, tmux?: bool=true }\n' +
+    'stdout { job_id: string, dir: string (absolute), follow_up: string }\n' +
+    '\n' +
+    'Effects: writes <dir>/deck.json, <dir>/progress.json (live),\n' +
+    '         <dir>/response.json (on finish), <dir>/job.log (JSONL).\n' +
+    '         Spawns TUI detached in a tmux pane when tmux=true and $TMUX set.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(async () => {
+    const input = parseStdinJson();
+    if (!input.deck || typeof input.deck !== 'object') {
+        emitError({
+            error: 'bad_input',
+            message: 'deck is required and must be an object',
+            field: 'deck',
+            next: "Run: echo '{\"kind\":\"deck\"}' | hl schema show",
+        });
+    }
+    let deck;
+    try {
+        const _v = {};
+        void _v;
+        deck = validateDeck(input.deck);
+    }
+    catch (validationErr) {
+        emitError({
+            error: 'deck_invalid',
+            message: `deck validation failed: ${validationErr instanceof Error ? validationErr.message : String(validationErr)}`,
+            received: input.deck,
+            next: "Fix the deck object. Run: echo '{\"deck\":{...}}' | hl deck validate",
+        });
+    }
+    const dir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-ix-'));
+    mkdirSync(dir, { recursive: true });
+    atomicWriteJson(deckPath(dir), deck);
+    const jobId = basename(dir);
+    const visuals = input.visuals !== false;
+    const useTmux = input.tmux !== false;
+    let sessionId;
+    if (visuals) {
+        if (input.sessionId && typeof input.sessionId === 'string') {
+            sessionId = input.sessionId;
+        }
+        else {
+            // dynamic import to avoid pulling heavy dep into parse path
+            const { findRecentSessionId } = await import('./conversation/reader.js');
+            sessionId = findRecentSessionId(process.cwd()) || findRecentSessionId() || undefined;
+        }
+    }
+    appendJobLog(dir, { level: 'info', event: 'job_started', message: 'deck ask job started', data: { jobId } });
+    if (INTERNAL_WRITE_TO) {
+        // Child mode: run ask() in-process, write result to INTERNAL_WRITE_TO
+        try {
+            const result = await ask(deck, { dir, sessionId });
+            appendJobLog(dir, { level: 'info', event: 'job_finished', message: 'deck resolved', data: { jobId } });
+            writeFileSync(INTERNAL_WRITE_TO, JSON.stringify(result) + '\n');
+            process.exit(0);
+        }
+        catch (askErr) {
+            appendJobLog(dir, {
+                level: 'error', event: 'job_failed',
+                message: askErr instanceof Error ? askErr.message : String(askErr),
+            });
+            process.exit(1);
+        }
+    }
+    if (process.env['TMUX'] && useTmux) {
+        const scriptPath = process.argv[1];
+        if (!scriptPath) {
+            emitError({ error: 'internal', message: 'Cannot determine hl script path', next: 'Report this as a bug.' });
+        }
+        const sq = (s) => /^[a-zA-Z0-9_\-./:@%+=]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+        const childInput = JSON.stringify({ deck, dir, sessionId, visuals, tmux: false });
+        const cmd = `echo ${sq(childInput)} | ${sq(process.execPath)} ${sq(scriptPath)} deck ask`;
+        try {
+            execFileSync('tmux', ['split-window', '-d', '-h', cmd], { stdio: 'ignore' });
+        }
+        catch (spawnErr) {
+            const msg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
+            appendJobLog(dir, { level: 'error', event: 'job_failed', message: `tmux spawn failed: ${msg}` });
+            emitError({
+                error: 'internal',
+                message: `tmux spawn failed: ${msg}`,
+                next: 'Check that $TMUX is set. Or pass tmux:false.',
+            });
+        }
+        process.stdout.write(JSON.stringify({
+            job_id: jobId,
+            dir,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes.`,
+        }) + '\n');
+        process.exit(0);
+    }
+    // Non-tmux path: ask() runs in-process (will block or fail without TTY — degraded).
+    appendJobLog(dir, { level: 'warn', event: 'job_started', message: 'no tmux; ask() runs in-process' });
+    try {
+        const result = await ask(deck, { dir, sessionId });
+        appendJobLog(dir, { level: 'info', event: 'job_finished', message: 'deck resolved', data: { jobId } });
+        writeFileSync(join(dir, 'response.json'), JSON.stringify({ responses: result.responses, completedAt: result.completedAt }, null, 2));
+        process.stdout.write(JSON.stringify({
+            job_id: jobId,
+            dir,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to retrieve the result.`,
+            _note: 'Non-tmux path: ask() blocked synchronously. Result is already available.',
+        }) + '\n');
+        process.exit(0);
+    }
+    catch (askErr) {
+        const msg = askErr instanceof Error ? askErr.message : String(askErr);
+        appendJobLog(dir, { level: 'error', event: 'job_failed', message: msg });
+        emitError({
+            error: 'internal',
+            message: `ask() failed: ${msg}`,
+            next: 'Set tmux:true (or run inside tmux) so the TUI can open an interactive pane.',
+        });
+    }
+});
+deckCmd
+    .command('validate')
+    .description('Preflight deck validation — no side effects.\n' +
+    '\n' +
+    'stdin  { deck: object }\n' +
+    'stdout { ok: bool, errors: [{field, message}] }\n' +
+    'exit   0 if ok, 1 if invalid\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.deck) {
+        emitError({ error: 'bad_input', message: 'deck is required', field: 'deck', next: 'Provide: {"deck": {...}}' });
+    }
+    try {
+        validateDeck(input.deck);
+        process.stdout.write(JSON.stringify({ ok: true, errors: [] }) + '\n');
+        process.exit(0);
+    }
+    catch (validationErr) {
+        const errors = parseValidationErrors(validationErr);
+        process.stdout.write(JSON.stringify({ ok: false, errors }) + '\n');
+        process.exit(1);
+    }
+});
+function parseValidationErrors(e) {
+    if (e && typeof e === 'object' && 'issues' in e) {
+        const issues = e.issues;
+        return issues.map((iss) => ({ field: iss.path.join('.'), message: iss.message }));
+    }
+    return [{ field: '', message: e instanceof Error ? e.message : String(e) }];
+}
+// ── review ────────────────────────────────────────────────────────────────────
+const reviewCmd = program.command('review').description('Markdown document review with anchored comments.');
+reviewCmd
+    .command('open')
+    .description('Kickoff: spawn the read-only editor review and return immediately.\n' +
+    '\n' +
+    'stdin  { file: string (required, .md), output?: string|null,\n' +
+    '         editor?: string|null, tmux?: bool=true }\n' +
+    'stdout { job_id: string, output: string (absolute), follow_up: string }\n' +
+    '\n' +
+    'Effects: spawns nvim/vim read-only; autosaves feedback JSON.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(async () => {
+    const input = parseStdinJson();
+    if (!input.file || typeof input.file !== 'string') {
+        emitError({ error: 'bad_input', message: 'file is required', field: 'file', next: 'Provide: {"file": "/path/to/doc.md"}' });
+    }
+    const absFile = resolve(input.file);
+    if (!existsSync(absFile)) {
+        emitError({ error: 'file_not_found', message: `File not found: ${absFile}`, field: 'file', next: 'Check the file path.' });
+    }
+    const output = resolve(input.output ? input.output : `${absFile}.feedback.json`);
+    const noTmux = input.tmux === false;
+    const jobDir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+    const jobId = basename(jobDir);
+    appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'review open job started', data: { jobId, file: absFile } });
+    try {
+        const result = await launchReview(absFile, {
+            output,
+            editor: (input.editor && typeof input.editor === 'string') ? input.editor : undefined,
+            noTmux,
+        });
+        appendJobLog(jobDir, { level: 'info', event: 'job_finished', message: 'review finished', data: { comments: result.comments.length } });
+        writeFileSync(join(jobDir, 'feedback.json'), JSON.stringify(result, null, 2));
+        process.stdout.write(JSON.stringify({
+            job_id: jobId,
+            output,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to retrieve the feedback.`,
+        }) + '\n');
+        process.exit(0);
+    }
+    catch (reviewErr) {
+        const msg = reviewErr instanceof Error ? reviewErr.message : String(reviewErr);
+        appendJobLog(jobDir, { level: 'error', event: 'job_failed', message: msg });
+        if (msg.startsWith('Markdown file not found')) {
+            emitError({ error: 'file_not_found', message: msg, next: 'Check the file path.' });
+        }
+        if (msg.startsWith('Editor not found') || msg.startsWith('No editor found')) {
+            emitError({ error: 'editor_not_found', message: msg, next: 'Install Neovim (brew install neovim) or pass editor.' });
+        }
+        emitError({ error: 'internal', message: msg, next: 'Check stderr for details.' });
+    }
+});
+// ── view ──────────────────────────────────────────────────────────────────────
+const viewCmd = program.command('view').description('Passive live render of a file in a tmux pane.');
+viewCmd
+    .command('show')
+    .description('Render a file live in a tmux pane — passive, no result.\n' +
+    '\n' +
+    'stdin  { path: string (required), watch?: bool=true, window?: "split"|"new"="split" }\n' +
+    'stdout { pane_id: string|null, reason: string|null }\n' +
+    'exit   0 always (not-in-tmux / renderer-unavailable is NOT an error)\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.path || typeof input.path !== 'string') {
+        emitError({ error: 'bad_input', message: 'path is required', field: 'path', next: 'Provide: {"path": "/abs/path/file.md"}' });
+    }
+    const absPath = resolve(input.path);
+    const watch = input.watch !== false;
+    const window = input.window === 'new' ? 'new' : 'split';
+    const res = display(absPath, { watch, window });
+    if (res.paneId) {
+        process.stdout.write(JSON.stringify({ pane_id: res.paneId, reason: null }) + '\n');
+    }
+    else {
+        process.stdout.write(JSON.stringify({ pane_id: null, reason: 'Not in tmux or termrender unavailable.' }) + '\n');
+    }
+    process.exit(0);
+});
+// ── inbox ─────────────────────────────────────────────────────────────────────
+const inboxCmd = program.command('inbox').description('Browse and resolve pending interactions across root dirs.');
+inboxCmd
+    .command('list')
+    .description('Read-only paginated query of pending interactions.\n' +
+    '\n' +
+    'stdin  { roots: string[] (required, ≥1), limit?: int=20 (max 100), cursor?: string|null }\n' +
+    'stdout { items: [{dir,title,askedBy,blockedSince,interactionCount}],\n' +
+    '         next_cursor: string|null, total: int|null }\n' +
+    'Sorted by blockedSince ascending.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!Array.isArray(input.roots) || input.roots.length === 0) {
+        emitError({ error: 'bad_input', message: 'roots must be a non-empty array', field: 'roots', next: 'Provide: {"roots": ["/path/to/inbox"]}' });
+    }
+    const roots = input.roots.map((r) => resolve(r));
+    const limit = Math.min(typeof input.limit === 'number' ? input.limit : 20, 100);
+    const allItems = scanInbox(roots);
+    const total = allItems.length;
+    let startIdx = 0;
+    if (input.cursor) {
+        const idx = allItems.findIndex((it) => it.dir === input.cursor);
+        startIdx = idx >= 0 ? idx : 0;
+    }
+    const page = allItems.slice(startIdx, startIdx + limit);
+    const nextCursor = startIdx + limit < total ? allItems[startIdx + limit]?.dir : null;
+    const items = page.map((it) => {
+        const dk = readJson(deckPath(it.dir));
+        return {
+            dir: it.dir,
+            title: it.title,
+            askedBy: it.source?.askedBy,
+            blockedSince: it.blockedSince,
+            interactionCount: dk ? dk.interactions.length : 1,
+        };
+    });
+    process.stdout.write(JSON.stringify({
+        items,
+        next_cursor: nextCursor !== undefined ? nextCursor : null,
+        total,
+    }) + '\n');
+    process.exit(0);
+});
+inboxCmd
+    .command('resolve')
+    .description('Kickoff: spawn the inbox-walker TUI detached.\n' +
+    '\n' +
+    'stdin  { roots: string[] (required) }\n' +
+    'stdout { job_id: string, follow_up: string }\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(async () => {
+    const input = parseStdinJson();
+    if (!Array.isArray(input.roots) || input.roots.length === 0) {
+        emitError({ error: 'bad_input', message: 'roots must be a non-empty array', field: 'roots', next: 'Provide: {"roots": ["/path/to/inbox"]}' });
+    }
+    const roots = input.roots.map((r) => resolve(r));
+    const jobDir = mkdtempSync(join(tmpdir(), 'hl-inbox-'));
+    const jobId = basename(jobDir);
+    appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'inbox resolve job started', data: { jobId, roots } });
+    try {
+        await inbox(roots);
+        appendJobLog(jobDir, { level: 'info', event: 'job_finished', message: 'inbox resolved', data: { jobId } });
+        process.stdout.write(JSON.stringify({
+            job_id: jobId,
+            follow_up: `Inbox walk complete. Call hl job result with stdin {"job_id":"${jobId}"} for summary.`,
+        }) + '\n');
+        process.exit(0);
+    }
+    catch (inboxErr) {
+        const msg = inboxErr instanceof Error ? inboxErr.message : String(inboxErr);
+        appendJobLog(jobDir, { level: 'error', event: 'job_failed', message: msg });
+        emitError({ error: 'internal', message: msg, next: 'Ensure the roots are valid directories.' });
+    }
+});
+// ── job ───────────────────────────────────────────────────────────────────────
+const jobCmd = program.command('job').description('Inspect, wait on, or cancel running jobs.');
+jobCmd
+    .command('status')
+    .description('Read-only job state snapshot.\n' +
     '\n' +
-    'Examples:\n' +
-    '  hl schema > deck.schema.json       # save the request schema\n' +
-    '  hl schema response | jq            # pretty-print the response schema\n')
-    .action((kind) => {
-    const schema = kind === 'response' ? RESPONSE_SCHEMA : REQUEST_SCHEMA;
-    process.stdout.write(JSON.stringify(schema, null, 2) + '\n');
+    'stdin  { job_id: string }\n' +
+    'stdout { state: "live"|"done"|"failed"|"canceled", kind: "deck"|"review"|"inbox",\n' +
+    '         age_seconds: number, last_event: {ts,event,message}|null }\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>"}' });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir)) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id.' });
+    }
+    let ageSecs = 0;
+    try {
+        const _st = {};
+        void _st;
+        const st = statSync(dir);
+        ageSecs = Math.round((Date.now() - st.birthtimeMs) / 1000);
+    }
+    catch (statErr) {
+        void String(statErr); // stat unavailable — report 0
+    }
+    const state = detectJobState(dir);
+    const kind = detectJobKind(dir);
+    const last = lastLogEvent(dir);
+    process.stdout.write(JSON.stringify({
+        state,
+        kind,
+        age_seconds: ageSecs,
+        last_event: last ? { ts: last.ts, event: last.event, message: last.message } : null,
+    }) + '\n');
+    process.exit(0);
+});
+function tryReadJobResult(dir, kind) {
+    if (kind === 'deck') {
+        const rp = responsePath(dir);
+        if (!existsSync(rp))
+            return null;
+        const raw = tryParseJson(readFileSync(rp, 'utf8'));
+        if (!raw)
+            return null;
+        const dk = readJson(deckPath(dir));
+        return {
+            summary: '',
+            responsePath: rp,
+            schema: 'humanloop.response/v2',
+            responses: raw.responses,
+            completedAt: raw.completedAt,
+            _note: dk ? `Deck had ${dk.interactions.length} interaction(s)` : undefined,
+        };
+    }
+    if (kind === 'review') {
+        const fp = join(dir, 'feedback.json');
+        if (!existsSync(fp))
+            return null;
+        return tryParseJson(readFileSync(fp, 'utf8'));
+    }
+    // inbox
+    const logPath = jobLogPath(dir);
+    if (!existsSync(logPath))
+        return null;
+    if (detectJobState(dir) !== 'done')
+        return null;
+    const lines = readLogLines(logPath);
+    let resolved = 0;
+    for (const line of lines) {
+        const entry = tryParseJson(line);
+        if (entry && entry.event === 'inbox_resolved')
+            resolved++;
+    }
+    return { resolved };
+}
+jobCmd
+    .command('result')
+    .description('Retrieve terminal payload of a finished job.\n' +
+    '\n' +
+    'stdin  { job_id: string, wait?: bool=false }\n' +
+    'stdout deck   → ResolutionEnvelope (humanloop.response/v2)\n' +
+    '       review → FeedbackResult\n' +
+    '       inbox  → { resolved: int }\n' +
+    '       not done + wait:false → { error:"not_ready", ... } exit 1\n' +
+    '       wait:true blocks until sidecar appears or job terminates.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(async () => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>", "wait": true}' });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir)) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id.' });
+    }
+    const wait = input.wait === true;
+    const kind = detectJobKind(dir);
+    if (!wait) {
+        const result = tryReadJobResult(dir, kind);
+        if (result === null) {
+            emitError({ error: 'not_ready', message: 'Job is not yet complete.', next: 'Retry with wait:true to block until done.' }, 1);
+        }
+        process.stdout.write(JSON.stringify(result) + '\n');
+        process.exit(0);
+    }
+    await new Promise((resolvePromise) => {
+        const poll = setInterval(() => {
+            const result = tryReadJobResult(dir, kind);
+            if (result !== null) {
+                clearInterval(poll);
+                process.stdout.write(JSON.stringify(result) + '\n');
+                process.exit(0);
+            }
+            const state = detectJobState(dir);
+            if (state === 'failed' || state === 'canceled') {
+                clearInterval(poll);
+                emitError({ error: 'not_ready', message: `Job ended with state: ${state}`, next: 'Check hl job logs for details.' }, 1);
+            }
+        }, 200);
+        void resolvePromise;
+    });
+});
+jobCmd
+    .command('logs')
+    .description('Stream job.log events (JSONL).\n' +
+    '\n' +
+    'stdin  { job_id: string, since?: string|null,\n' +
+    '         level?: "debug"|"info"|"warn"|"error"="info", follow?: bool=false }\n' +
+    'stdout JSONL — one event per line: { ts, level, event, message, data? }\n' +
+    'follow:false → emit historical then exit; follow:true → stream until done.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(async () => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>"}' });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir)) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id.' });
+    }
+    const levelOrder = { debug: 0, info: 1, warn: 2, error: 3 };
+    const inputLevel = (input.level && input.level in levelOrder) ? input.level : 'info';
+    const minLevel = levelOrder[inputLevel];
+    const since = input.since;
+    const follow = input.follow === true;
+    const logPath = jobLogPath(dir);
+    let emittedCount = 0;
+    function emitLogLines() {
+        const lines = readLogLines(logPath);
+        for (let i = emittedCount; i < lines.length; i++) {
+            const entry = tryParseJson(lines[i]);
+            if (!entry)
+                continue;
+            if (since && entry.ts <= since)
+                continue;
+            const entryLevel = entry.level in levelOrder ? levelOrder[entry.level] : 0;
+            if (entryLevel < minLevel)
+                continue;
+            process.stdout.write(JSON.stringify(entry) + '\n');
+        }
+        emittedCount = lines.length;
+    }
+    emitLogLines();
+    if (!follow) {
+        process.exit(0);
+    }
+    await new Promise((resolvePromise) => {
+        const poll = setInterval(() => {
+            emitLogLines();
+            const state = detectJobState(dir);
+            if (state === 'done' || state === 'failed' || state === 'canceled') {
+                clearInterval(poll);
+                process.exit(0);
+            }
+        }, 200);
+        void resolvePromise;
+    });
+});
+jobCmd
+    .command('cancel')
+    .description('Best-effort cancel: signal the job pane and close it if possible.\n' +
+    '\n' +
+    'stdin  { job_id: string }\n' +
+    'stdout { canceled: bool, message: string }\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>"}' });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir)) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id.' });
+    }
+    let canceled = false;
+    let message = 'No tmux pane found; signal not delivered (job may already be done).';
+    if (process.env['TMUX']) {
+        try {
+            const panes = execFileSync('tmux', ['list-panes', '-a', '-F', '#{pane_id} #{pane_current_command}'], { encoding: 'utf8' });
+            for (const line of panes.split('\n')) {
+                const paneId = line.split(' ')[0];
+                if (!paneId)
+                    continue;
+                try {
+                    execFileSync('tmux', ['send-keys', '-t', paneId, 'q', ''], { stdio: 'ignore' });
+                }
+                catch (sendErr) {
+                    void String(sendErr); // best-effort per pane
+                }
+            }
+            canceled = true;
+            message = 'Signal delivered to tmux pane(s).';
+        }
+        catch (tmuxErr) {
+            message = `tmux pane lookup failed: ${tmuxErr instanceof Error ? tmuxErr.message : String(tmuxErr)}`;
+        }
+    }
+    appendJobLog(dir, { level: 'info', event: 'job_canceled', message: `cancel requested: ${message}` });
+    process.stdout.write(JSON.stringify({ canceled, message }) + '\n');
+    process.exit(0);
+});
+// ── schema ────────────────────────────────────────────────────────────────────
+const schemaCmd = program.command('schema').description('Print JSON Schemas for hl data types.');
+schemaCmd
+    .command('show')
+    .description('Print the JSON Schema for a data kind.\n' +
+    '\n' +
+    'stdin  { kind?: "deck"|"resolution"|"feedback"="deck" }\n' +
+    'stdout the JSON Schema object\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    const kind = (typeof input.kind === 'string' && input.kind) ? input.kind : 'deck';
+    if (kind === 'resolution') {
+        process.stdout.write(JSON.stringify(RESPONSE_SCHEMA, null, 2) + '\n');
+    }
+    else if (kind === 'feedback') {
+        process.stdout.write(JSON.stringify(FEEDBACK_SCHEMA, null, 2) + '\n');
+    }
+    else if (kind === 'deck') {
+        process.stdout.write(JSON.stringify(REQUEST_SCHEMA, null, 2) + '\n');
+    }
+    else {
+        emitError({
+            error: 'bad_input',
+            message: `Unknown kind: ${kind}. Valid: deck, resolution, feedback`,
+            field: 'kind',
+            next: 'Provide: {"kind": "deck"} or {"kind": "resolution"} or {"kind": "feedback"}',
+        });
+    }
 });
 program.parse();