@crouton-kit/humanloop 0.1.4 → 0.3.1

package/dist/cli.js

@@ -1,204 +1,879 @@
 #!/usr/bin/env node
-import { Command, Option } from 'commander';
-import { writeFileSync } from 'fs';
-import { launchTui } from './tui/app.js';
-import { dispatchToTmuxPane } from './tui/tmux.js';
-import { findRecentSessionId } from './conversation/reader.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';
+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 {
+        const _io = {};
+        void _io;
+        stdinResult.value = readFileSync('/dev/stdin', 'utf8');
+        stdinResult.ok = true;
+    }
+    catch (stdinErr) {
+        process.stderr.write(`[hl] stdin read error: ${stdinErr instanceof Error ? stdinErr.message : String(stdinErr)}\n`);
+    }
+    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 {
+        const _p = {};
+        void _p;
+        parseResult.value = JSON.parse(raw);
+        parseResult.ok = true;
+    }
+    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.',
+        });
+    }
+    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;
+    }
+    catch (writeErr) {
+        void Object.assign(logResult, { error: String(writeErr) }); // best-effort; never throws
+    }
+}
+// ── 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 _s = {};
+        void _s;
+        scanResult.entries = readdirSync(td);
+    }
+    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;
+        }
+    }
+    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';
+        }
+    }
+    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 deck ask (v2)',
+    type: 'object',
+    required: ['interactions'],
+    properties: {
+        title: { type: 'string', description: 'Optional deck title shown in the TUI header' },
+        interactions: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                type: 'object',
+                required: ['id', 'title', 'options'],
+                properties: {
+                    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',
+                        items: {
+                            type: 'object',
+                            required: ['id', 'label'],
+                            properties: {
+                                id: { type: 'string' },
+                                label: { type: 'string' },
+                                description: { type: 'string' },
+                                shortcut: { type: 'string', description: 'Single char. Auto-assigned if absent.' },
+                            },
+                        },
+                    },
+                    allowFreetext: { type: 'boolean' },
+                    freetextLabel: { type: 'string' },
+                    kind: { type: 'string', enum: ['notify', 'validation', 'decision', 'context', 'error'] },
+                },
+            },
+        },
+    },
+};
+const RESPONSE_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'humanloop.response/v2',
+    description: 'Resolution envelope emitted by hl deck ask / returned by ask().',
+    type: 'object',
+    required: ['summary', 'responsePath', 'schema', 'responses', 'completedAt'],
+    properties: {
+        summary: { type: 'string' },
+        responsePath: { type: 'string' },
+        schema: { const: 'humanloop.response/v2' },
+        responses: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id'],
+                properties: {
+                    id: { type: 'string' },
+                    selectedOptionId: { type: 'string' },
+                    selectedOptionIds: { type: 'array', items: { type: 'string' } },
+                    freetext: { type: 'string' },
+                },
+            },
+        },
+        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
     .name('hl')
-    .description('Human-in-the-loop decision TUI.\n' +
-    '\n' +
-    'Use this when you (the agent) need the human to validate decisions, choose\n' +
-    'between options, or provide freetext input before you continue. The tool\n' +
-    'blocks until the human finishes review and returns their responses as JSON.\n' +
-    '\n' +
-    'Workflow:\n' +
-    '  1. Write a deck file matching `hl schema` (a JSON object with interactions[]).\n' +
-    '  2. Run `hl create <file>`; it blocks and prints output JSON to stdout.\n' +
-    '  3. Parse the JSON; each response has id, optional selectedOptionId, optional freetext.\n' +
-    '\n' +
-    'Interaction options: supply options[] for choices; set allowFreetext for comment/freetext.')
-    .version('0.1.0')
-    .addHelpText('after', '\nExamples:\n' +
-    '  hl schema                          # print the input JSON schema\n' +
-    '  hl create deck.json                # open TUI, block, print responses JSON\n' +
-    '  hl create deck.json --output out.json   # write result to file\n' +
-    '  hl create deck.json --no-tmux     # run in current pane even inside tmux\n');
-program
-    .command('create')
-    .description('Open the decisions TUI on <file> and block until the human finishes review.\n' +
-    'Prints output JSON to stdout (or to --output / --write-to).')
-    .argument('<file>', 'Path to deck JSON file (see `hl schema` for format)')
-    .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' +
-    'INPUT FORMAT\n' +
-    '  JSON file with an `interactions` array. Each interaction has an `id`,\n' +
-    '  `title`, `options[]`, and optional `allowFreetext`. Run `hl schema`\n' +
-    '  for the full schema. Example:\n' +
-    '    {\n' +
-    '      "interactions": [\n' +
-    '        {"id":"i1","title":"Use Postgres","options":[\n' +
-    '          {"id":"approve","label":"Approve"},\n' +
-    '          {"id":"reject","label":"Reject"}\n' +
-    '        ],"allowFreetext":true},\n' +
-    '        {"id":"i2","title":"Migration tool","options":[\n' +
-    '          {"id":"prisma","label":"Prisma"},\n' +
-    '          {"id":"drizzle","label":"Drizzle"}\n' +
-    '        ]},\n' +
-    '        {"id":"i3","title":"Rate limit policy","options":[],"allowFreetext":true}\n' +
-    '      ]\n' +
-    '    }\n' +
-    '\n' +
-    'OUTPUT FORMAT (stdout on success, JSON)\n' +
-    '  {\n' +
-    '    "responses": [ ... ],\n' +
-    '    "completedAt": "2026-04-20T15:23:00.000Z"\n' +
-    '  }\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' +
-    '  progress   Responses are persisted atomically to <file>.progress.json after\n' +
-    '             every change. If the process is killed, the next run resumes\n' +
-    '             from where the human left off. The file is removed on full\n' +
-    '             completion; partial-response files are preserved.\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 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);
+    .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 {
-            process.stdout.write(json);
+            // 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 {
-        if (process.env.TMUX && opts.tmux && !opts.writeTo) {
-            try {
-                const result = await dispatchToTmuxPane(file, { sessionId, visuals: opts.visuals });
-                emit(result);
+        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' +
+    '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);
             }
-            catch (err) {
-                process.stderr.write(`tmux dispatch failed, running locally: ${err instanceof Error ? err.message : String(err)}\n`);
+            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');
         }
-        const result = await launchTui(file, sessionId);
-        emit(result);
+        emittedCount = lines.length;
+    }
+    emitLogLines();
+    if (!follow) {
         process.exit(0);
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`ERROR: ${msg}\n`);
-        if (msg.includes('not found')) {
-            process.stderr.write('\nFix: pass a path to an existing deck JSON file.\nSee format: hl schema\n');
-        }
-        else if (msg.includes('No interactions')) {
-            process.stderr.write('\nFix: the file must contain a non-empty `interactions` array.\nSee format: 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 if (msg.includes('JSON')) {
-            process.stderr.write('\nFix: the deck file must be valid JSON matching `hl schema`.\n');
+    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).';
         }
-        else if (msg.startsWith('interactions[') || msg.includes('Duplicate interaction id') || msg.includes('must be')) {
-            process.stderr.write('\nFix: the deck file must match `hl schema`. Run `hl schema` to see the required shape.\n');
+        catch (tmuxErr) {
+            message = `tmux pane lookup failed: ${tmuxErr instanceof Error ? tmuxErr.message : String(tmuxErr)}`;
         }
-        process.exit(1);
     }
+    appendJobLog(dir, { level: 'info', event: 'job_canceled', message: `cancel requested: ${message}` });
+    process.stdout.write(JSON.stringify({ canceled, message }) + '\n');
+    process.exit(0);
 });
-program
-    .command('schema')
-    .description('Print the v2 Interaction[] deck schema to stdout')
-    .addHelpText('after', '\n' +
-    'Use this to learn the exact input format for `hl create`.\n' +
-    '\n' +
-    'Example:\n' +
-    '  hl schema > deck.schema.json   # save for reference\n' +
-    '  hl schema | jq                 # pretty-print\n')
+// ── 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 schema = {
-        $schema: 'https://json-schema.org/draft/2020-12/schema',
-        description: 'Input schema for hl create (v2)',
-        type: 'object',
-        required: ['interactions'],
-        properties: {
-            title: {
-                type: 'string',
-                description: 'Optional deck title shown in the TUI header',
-            },
-            interactions: {
-                type: 'array',
-                minItems: 1,
-                items: {
-                    type: 'object',
-                    required: ['id', 'title', 'options'],
-                    properties: {
-                        id: { type: 'string', description: 'Unique identifier' },
-                        title: { type: 'string', description: 'Short display label (≤4 words). Required.' },
-                        subtitle: { type: 'string', description: 'One-line "why this matters"' },
-                        body: { type: 'string', description: 'Markdown body shown in item-review' },
-                        bodyPath: { type: 'string', description: 'Path to body file; sisyphus inlines before mount' },
-                        options: {
-                            type: 'array',
-                            description: 'Selectable choices. Empty for freetext-only interactions.',
-                            items: {
-                                type: 'object',
-                                required: ['id', 'label'],
-                                properties: {
-                                    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',
-                                    },
-                                },
-                            },
-                        },
-                        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 sisyphus for inbox icons',
-                        },
-                    },
-                },
-            },
-        },
-    };
-    process.stdout.write(JSON.stringify(schema, null, 2) + '\n');
+    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();