@crouton-kit/humanloop 0.3.8 → 0.3.10

package/dist/api.js

@@ -25,11 +25,17 @@ function buildSummary(deck, responses) {
         const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
         let picked;
         if (r.selectedOptionIds !== undefined) {
-            const labels = r.selectedOptionIds
+            const oc = r.optionComments;
+            const parts = r.selectedOptionIds
                 .map((id) => it.options.find((o) => o.id === id))
                 .filter((o) => o !== undefined)
-                .map((o) => o.label);
-            picked = labels.length > 0 ? labels.join(', ') : undefined;
+                .map((o) => {
+                const note = oc !== undefined ? oc[o.id] : undefined;
+                return typeof note === 'string' && note.length > 0
+                    ? `${o.label} ("${note}")`
+                    : o.label;
+            });
+            picked = parts.length > 0 ? parts.join(', ') : undefined;
         }
         else if (r.selectedOptionId !== undefined) {
             picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;

package/dist/cli.js

@@ -5,7 +5,7 @@ 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 { launchReview, reviewVimscript } from './editor/review.js';
 import { validateDeck } from './inbox/deck-schema.js';
 import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
@@ -244,6 +244,11 @@ const RESPONSE_SCHEMA = {
                     selectedOptionId: { type: 'string' },
                     selectedOptionIds: { type: 'array', items: { type: 'string' } },
                     freetext: { type: 'string' },
+                    optionComments: {
+                        type: 'object',
+                        description: 'Multi-select per-option comments, keyed by option id.',
+                        additionalProperties: { type: 'string' },
+                    },
                 },
             },
         },
@@ -559,7 +564,13 @@ reviewCmd
     '         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')
+    'Effects: spawns nvim/vim read-only DETACHED in a tmux pane when tmux=true\n' +
+    '         and $TMUX set; returns before the human starts. Writes\n' +
+    '         <dir>/review.vim, <dir>/feedback.json (on finish), <dir>/job.log.\n' +
+    '         autosaves feedback JSON; the open pane live-reloads the source on\n' +
+    '         disk edits. The review is open-ended (a human may take many\n' +
+    '         minutes) — collect via `hl job result` with wait:true, run\n' +
+    '         backgrounded so the call does not block on the human.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
     const input = parseStdinJson();
@@ -571,15 +582,52 @@ reviewCmd
         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 useTmux = input.tmux !== false;
+    // Shared job dir: the detached child reuses the parent's via input.dir;
+    // a top-level call mints one. The review.vim is written up front (and the
+    // job_started logged) so the job is recognizable as a live review — and so
+    // the child sources the exact vimscript — before any pane is spawned.
+    const jobDir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-review-'));
+    mkdirSync(jobDir, { recursive: true });
     const jobId = basename(jobDir);
-    appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'review open job started', data: { jobId, file: absFile } });
+    if (!input.dir) {
+        writeFileSync(join(jobDir, 'review.vim'), reviewVimscript());
+        appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'review open job started', data: { jobId, file: absFile } });
+    }
+    // tmux path: detach a child that owns the editor pane and return the handle
+    // now, mirroring `deck ask`. The child re-enters this leaf with tmux:false
+    // and the shared dir, falling through to the in-process branch below.
+    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({ file: absFile, output, editor: input.editor ?? null, tmux: false, dir: jobDir });
+        const cmd = `echo ${sq(childInput)} | ${sq(process.execPath)} ${sq(scriptPath)} review open`;
+        try {
+            execFileSync('tmux', ['split-window', '-d', '-h', cmd], { stdio: 'ignore' });
+        }
+        catch (spawnErr) {
+            const msg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
+            appendJobLog(jobDir, { 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,
+            output,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes the review. They may take many minutes — run this backgrounded; you will be notified on completion.`,
+        }) + '\n');
+        process.exit(0);
+    }
+    // In-process path: the detached child (this pane is its TTY), or a degraded
+    // top-level call with no tmux. launchReview blocks until the editor exits.
     try {
         const result = await launchReview(absFile, {
             output,
             editor: (input.editor && typeof input.editor === 'string') ? input.editor : undefined,
-            noTmux,
+            noTmux: true,
+            jobDir,
         });
         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));
@@ -587,6 +635,7 @@ reviewCmd
             job_id: jobId,
             output,
             follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to retrieve the feedback.`,
+            ...(input.dir ? {} : { _note: 'No tmux: launchReview blocked synchronously. Result is already available.' }),
         }) + '\n');
         process.exit(0);
     }

package/dist/editor/review.d.ts

@@ -6,7 +6,33 @@ export interface ReviewOptions {
     editor?: string;
     /** Force running in the current terminal even when $TMUX is set. */
     noTmux?: boolean;
+    /**
+     * When set, an explicit `<Space>s` / `:HLSubmit` invocation writes a sentinel
+     * file at this path. Node-side uses the file's existence to gate `submitted: true`.
+     * When omitted, any editor exit finalizes `submitted: true` (legacy behavior).
+     */
+    submitFlagPath?: string;
+    /**
+     * When true and $TMUX is set and !opts.noTmux, launch via
+     * `tmux display-popup -E` instead of `tmux split-window`.
+     * display-popup -E is synchronous so no poll loop is needed.
+     */
+    tmuxPopup?: boolean;
+    /** Override the default 90%/90% popup size. Only used when tmuxPopup is true. */
+    popupSize?: {
+        w: string;
+        h: string;
+    };
+    /**
+     * Reuse this directory for `review.vim` instead of minting a fresh temp dir.
+     * The async `review open` kickoff passes its job dir so the detached child
+     * sources the same vimscript the parent already wrote there (which also lets
+     * the job be recognized as a review while it's still live). When the file
+     * already exists it is left untouched.
+     */
+    jobDir?: string;
 }
+export declare function reviewVimscript(): string;
 /**
  * Compact stdout rendering for the agent: per comment just the line:col
  * range, the original text in that span, and the note — plus the source

package/dist/editor/review.js

@@ -26,12 +26,13 @@ function resolveEditor(override) {
 // The entire review UX as a clean, minimal Vimscript config sourced via `-u`.
 // Works in both Neovim and Vim 8+. The source file is opened read-only; the
 // human anchors comments to real source lines/selections and quits to submit.
-function reviewVimscript() {
+export function reviewVimscript() {
     return [
         `" hl propose — review layer. Runs on a CLEAN config (nvim -u NONE: no`,
         `" init.lua, no LazyVim, no plugins/keymaps). Look/feel is ONLY the user's`,
-        `" 'gloam' colorscheme + built-in treesitter markdown highlighting, applied`,
-        `" below. The rest is the read-only guard, comment commands, and autosave.`,
+        `" 'gloam' colorscheme + built-in treesitter markdown highlighting + (when`,
+        `" installed) render-markdown.nvim for GFM tables/headings, applied below.`,
+        `" The rest is the read-only guard, comment commands, and autosave.`,
         `let g:hl_out = $HL_OUTPUT`,
         `let g:hl_src = $HL_SOURCE`,
         `let s:comments = []`,
@@ -146,39 +147,103 @@ function reviewVimscript() {
         `  echo 'Removed last comment — ' . len(s:comments) . ' left'`,
         `endfunction`,
         ``,
-        `function! s:List() abort`,
-        `  let l:wid = bufwinid('__HL_Comments__')`,
-        `  if l:wid != -1`,
-        `    call win_gotoid(l:wid) | close | return`,
-        `  endif`,
+        `" Build the list buffer lines plus a parallel map from buffer line -> comment`,
+        `" index (0-based; -1 for non-actionable rows like the quote continuation or`,
+        `" the empty-state hint). Stored on the buffer so the action maps can resolve`,
+        `" which comment the cursor is on.`,
+        `function! s:ListLines() abort`,
         `  let l:lines = []`,
+        `  let l:map = []`,
         `  if empty(s:comments)`,
-        `    let l:lines = ['(no comments yet — select text or put the cursor on a line, then <Space>c  or  :HLComment)']`,
+        `    call add(l:lines, '(no comments yet — select text or put the cursor on a line, then <Space>c  or  :HLComment)')`,
+        `    call add(l:map, -1)`,
         `  else`,
-        `    let l:i = 1`,
+        `    let l:idx = 0`,
         `    for l:c in s:comments`,
         `      let l:ln = get(l:c,'line',0)`,
         `      let l:end = get(l:c,'endLine',l:ln)`,
         `      let l:loc = l:ln == l:end ? ('L' . l:ln) : ('L' . l:ln . '-' . l:end)`,
-        `      call add(l:lines, l:i . '. [' . l:loc . ']  ' . get(l:c,'comment',''))`,
+        `      call add(l:lines, (l:idx+1) . '. [' . l:loc . ']  ' . get(l:c,'comment',''))`,
+        `      call add(l:map, l:idx)`,
         `      if !empty(get(l:c,'quote',''))`,
         `        call add(l:lines, '      > ' . substitute(get(l:c,'quote',''), "\\n", ' / ', 'g'))`,
+        `        call add(l:map, l:idx)`,
         `      endif`,
-        `      let l:i += 1`,
+        `      let l:idx += 1`,
         `    endfor`,
         `  endif`,
-        `  botright 10split __HL_Comments__`,
-        `  setlocal buftype=nofile bufhidden=wipe noswapfile nobuflisted`,
-        `  setlocal nonumber nocursorline winfixheight signcolumn=no`,
+        `  return [l:lines, l:map]`,
+        `endfunction`,
+        ``,
+        `" Refill the (already-open) comments buffer in place and refresh the line map.`,
+        `function! s:RenderList() abort`,
+        `  let [l:lines, l:map] = s:ListLines()`,
+        `  let b:hl_map = l:map`,
         `  setlocal modifiable`,
+        `  silent! 1,$delete _`,
         `  call setline(1, l:lines)`,
         `  setlocal nomodifiable`,
+        `endfunction`,
+        ``,
+        `" Comment index (0-based) under the cursor in the comments buffer, or -1.`,
+        `function! s:ListIdx() abort`,
+        `  if !exists('b:hl_map') | return -1 | endif`,
+        `  let l:lnum = line('.')`,
+        `  if l:lnum < 1 || l:lnum > len(b:hl_map) | return -1 | endif`,
+        `  return b:hl_map[l:lnum - 1]`,
+        `endfunction`,
+        ``,
+        `function! s:ListDelete() abort`,
+        `  let l:idx = s:ListIdx()`,
+        `  if l:idx < 0`,
+        `    echohl WarningMsg | echo 'No comment on this line' | echohl NONE | return`,
+        `  endif`,
+        `  call remove(s:comments, l:idx)`,
+        `  call s:Save()`,
+        `  call s:Marks()`,
+        `  call s:RenderList()`,
+        `  echo 'Deleted comment — ' . len(s:comments) . ' left'`,
+        `endfunction`,
+        ``,
+        `function! s:ListEdit() abort`,
+        `  let l:idx = s:ListIdx()`,
+        `  if l:idx < 0`,
+        `    echohl WarningMsg | echo 'No comment on this line' | echohl NONE | return`,
+        `  endif`,
+        `  let l:cur = get(s:comments[l:idx], 'comment', '')`,
+        `  let l:txt = input('Edit comment: ', l:cur)`,
+        `  redraw`,
+        `  if empty(trim(l:txt))`,
+        `    echohl WarningMsg | echo 'Edit cancelled — comment unchanged' | echohl NONE | return`,
+        `  endif`,
+        `  let s:comments[l:idx]['comment'] = l:txt`,
+        `  call s:Save()`,
+        `  call s:RenderList()`,
+        `  echo 'Updated comment'`,
+        `endfunction`,
+        ``,
+        `function! s:List() abort`,
+        `  let l:wid = bufwinid('__HL_Comments__')`,
+        `  if l:wid != -1`,
+        `    call win_gotoid(l:wid) | close | return`,
+        `  endif`,
+        `  botright 10split __HL_Comments__`,
+        `  setlocal buftype=nofile bufhidden=wipe noswapfile nobuflisted`,
+        `  setlocal nonumber cursorline winfixheight signcolumn=no`,
+        `  call s:RenderList()`,
         `  nnoremap <buffer> <silent> q :close<CR>`,
         `  nnoremap <buffer> <silent> <Space>l :close<CR>`,
+        `  nnoremap <buffer> <silent> dd :call <SID>ListDelete()<CR>`,
+        `  nnoremap <buffer> <silent> e :call <SID>ListEdit()<CR>`,
+        `  nnoremap <buffer> <silent> <CR> :call <SID>ListEdit()<CR>`,
+        `  echohl Question | echo 'list — e/<CR> edit · dd delete · q/<Space>l close' | echohl NONE`,
         `endfunction`,
         ``,
         `function! s:Submit() abort`,
         `  call s:Save()`,
+        `  if $HL_SUBMIT_FLAG !=# ''`,
+        `    call writefile([''], $HL_SUBMIT_FLAG)`,
+        `  endif`,
         `  qa!`,
         `endfunction`,
         ``,
@@ -186,7 +251,7 @@ function reviewVimscript() {
         `command! HLList call <SID>List()`,
         `command! HLUndo call <SID>Undo()`,
         `command! HLSubmit call <SID>Submit()`,
-        `command! HLHelp echo 'REVIEW  <Space>c comment (visual or line)   <Space>l list   <Space>u undo-last   <Space>s submit & quit   — or :HLComment/:HLList/:HLUndo/:HLSubmit   (any quit submits)'`,
+        `command! HLHelp echo 'REVIEW  <Space>c comment   <Space>l list   <Space>u undo-last   <Space>s submit & quit   |  in list: e/<CR> edit · dd delete · q close   (any quit submits)'`,
         ``,
         `" Highlights are (re)applied after any colorscheme so the user's theme`,
         `" (e.g. gloam) loads first, then our anchor highlight sits on top.`,
@@ -212,9 +277,51 @@ function reviewVimscript() {
         `  if &filetype !=# 'markdown' | setlocal filetype=markdown | endif`,
         `  " gloam only defines treesitter @markup.* highlight groups for markdown,`,
         `  " so the styling needs treesitter active. Built-in treesitter plus the`,
-        `  " site-dir markdown parser render it with zero plugins.`,
+        `  " site-dir markdown parser render it with zero plugins. When the user has`,
+        `  " render-markdown.nvim installed (lazy dir / packpath), pull it in too so`,
+        `  " GFM tables and headings render the same as their normal editor — it only`,
+        `  " draws extmarks/conceal, so the read-only buffer text (and the line:col`,
+        `  " anchors comments hang off of) is never touched.`,
         `  if has('nvim')`,
-        `    silent! lua pcall(vim.treesitter.start, 0, 'markdown')`,
+        `    silent! lua << HLLUA`,
+        `pcall(vim.treesitter.start, 0, 'markdown')`,
+        `pcall(function()`,
+        `  local path = vim.fn.stdpath('data') .. '/lazy/render-markdown.nvim'`,
+        `  if vim.fn.isdirectory(path) == 0 then`,
+        `    local hits = vim.fn.globpath(vim.o.packpath, '*/*/render-markdown.nvim', false, true)`,
+        `    path = hits[1]`,
+        `  end`,
+        `  if not path or vim.fn.isdirectory(path) == 0 then return end`,
+        `  vim.opt.runtimepath:prepend(path)`,
+        `  vim.g.render_markdown_config = {`,
+        `    file_types = { 'markdown' },`,
+        `    completions = { lsp = { enabled = false } },`,
+        `    heading = { border = false },`,
+        `  }`,
+        `  vim.cmd('silent! runtime plugin/render-markdown.lua')`,
+        `  -- Defer the initial paint to the next tick: during VimEnter the window`,
+        `  -- isn't laid out yet, so an immediate render no-ops and tables show raw`,
+        `  -- until the first cursor move. api.render() forces a paint for the`,
+        `  -- buffer's window (the live autocmds the plugin installed keep it updated`,
+        `  -- on edits/scroll thereafter). render-markdown refuses to draw while a`,
+        `  -- prompt mode is active ('r' hit-enter, 'rm' more, 'r?' confirm) — e.g. a`,
+        `  -- wrapped :echo — so re-defer until we're back in a normal state.`,
+        `  local function paint()`,
+        `    local m = vim.api.nvim_get_mode().mode`,
+        `    if m == 'r' or m == 'rm' or m == 'r?' then`,
+        `      vim.defer_fn(paint, 60)`,
+        `      return`,
+        `    end`,
+        `    pcall(function()`,
+        `      require('render-markdown.api').render({`,
+        `        buf = vim.api.nvim_get_current_buf(),`,
+        `        win = vim.api.nvim_get_current_win(),`,
+        `      })`,
+        `    end)`,
+        `  end`,
+        `  vim.schedule(paint)`,
+        `end)`,
+        `HLLUA`,
         `  endif`,
         `  " Buffer-local <Space> maps. Clean config has no which-key/<leader>`,
         `  " bindings to collide with, and these are gone outside this buffer.`,
@@ -227,11 +334,29 @@ function reviewVimscript() {
         `  call s:Load()`,
         `  call s:Marks()`,
         `  redraw`,
-        `  echohl Question | echo 'hl review — <Space>c comment   <Space>l list   <Space>u undo   <Space>s submit & quit   (:HLHelp)' | echohl NONE`,
+        `  " Keep this hint short: a line that wraps past the cmdline triggers the`,
+        `  " hit-enter prompt, whose mode blocks the deferred render-markdown paint.`,
+        `  " The full key list lives in :HLHelp (and is printed to stderr on launch).`,
+        `  echohl Question | echo 'hl review — <Space>c comment · l list · u undo · s submit  (:HLHelp)' | echohl NONE`,
         `endfunction`,
         `autocmd VimEnter * call s:Setup()`,
         `autocmd VimLeavePre * call s:Save()`,
         ``,
+        `" Watchmode: the source is opened read-only here but may be rewritten on`,
+        `" disk by the agent while the human reviews. autoread + a periodic checktime`,
+        `" (timers fire even when the tmux pane is unfocused) reload the buffer`,
+        `" silently — it is never locally modified, so there is nothing to clobber.`,
+        `" On reload, re-run Setup (read-only guard, treesitter, maps) and redraw the`,
+        `" comment anchors, which the reload cleared. Comments live in s:comments /`,
+        `" the autosave file, not the buffer, so they survive; their line anchors may`,
+        `" drift if the edit moved text, which is expected — the human sees the latest.`,
+        `set autoread`,
+        `autocmd FocusGained,BufEnter,CursorHold * silent! checktime`,
+        `autocmd FileChangedShellPost * call s:Setup() | call s:Marks() | redraw`,
+        `if exists('*timer_start')`,
+        `  let s:hl_watch = timer_start(1000, {-> execute('silent! checktime')}, {'repeat': -1})`,
+        `endif`,
+        ``,
     ].join('\n');
 }
 function atomicWrite(path, data) {
@@ -285,7 +410,24 @@ function rangeLabel(c) {
 export function formatFeedbackSummary(result, feedbackJsonPath) {
     const n = result.comments.length;
     const out = [];
-    if (n === 0) {
+    if (!result.submitted) {
+        if (n > 0) {
+            out.push(`hl propose — draft saved: ${n} comment${n === 1 ? '' : 's'} on ${result.file} (not yet submitted)`);
+            out.push('');
+            result.comments.forEach((c, i) => {
+                const original = c.quote && c.quote.length > 0 ? c.quote : c.lineText;
+                const lines = original.split('\n');
+                out.push(` ${i + 1}. ${rangeLabel(c)}`);
+                lines.forEach((ln, k) => out.push(k === 0 ? `    text:    ${ln}` : `             ${ln}`));
+                out.push(`    comment: ${c.comment}`);
+                out.push('');
+            });
+        }
+        else {
+            out.push(`hl propose — draft saved: no comments yet on ${result.file}`);
+        }
+    }
+    else if (n === 0) {
         out.push(`hl propose — approved: 0 comments on ${result.file} (human signalled looks-good; proceed)`);
     }
     else {
@@ -364,10 +506,18 @@ export async function launchReview(file, opts) {
     }
     const outPath = resolve(opts.output);
     const bin = resolveEditor(opts.editor);
-    const dir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+    // When the async kickoff passes its job dir, source the review.vim the parent
+    // already wrote there; otherwise mint a private temp dir as before.
+    const dir = opts.jobDir ?? mkdtempSync(join(tmpdir(), 'hl-review-'));
     const initPath = join(dir, 'review.vim');
-    writeFileSync(initPath, reviewVimscript());
-    const env = { ...process.env, HL_OUTPUT: outPath, HL_SOURCE: absFile };
+    if (!existsSync(initPath))
+        writeFileSync(initPath, reviewVimscript());
+    const env = {
+        ...process.env,
+        HL_OUTPUT: outPath,
+        HL_SOURCE: absFile,
+        ...(opts.submitFlagPath ? { HL_SUBMIT_FLAG: opts.submitFlagPath } : {}),
+    };
     // `-u NONE`: do NOT load the user's init.lua / LazyVim / plugins / keymaps.
     // Default runtimepath still includes the config dir (for the gloam
     // colorscheme) and the site dir (for the treesitter markdown parser), so the
@@ -382,16 +532,27 @@ export async function launchReview(file, opts) {
     if (inTmux) {
         // `exec env …` so the editor replaces the shell and becomes the pane's
         // process (so tmux `#{pane_current_command}` is `nvim`, not the shell).
+        const envPairs = [
+            `HL_OUTPUT=${shellQuote(outPath)}`,
+            `HL_SOURCE=${shellQuote(absFile)}`,
+            ...(opts.submitFlagPath ? [`HL_SUBMIT_FLAG=${shellQuote(opts.submitFlagPath)}`] : []),
+        ];
         const paneCmd = [
             'exec',
             'env',
-            `HL_OUTPUT=${shellQuote(outPath)}`,
-            `HL_SOURCE=${shellQuote(absFile)}`,
+            ...envPairs,
             shellQuote(bin),
             ...editorArgs.map(shellQuote),
         ].join(' ');
         try {
-            await runInTmuxPane(paneCmd);
+            if (opts.tmuxPopup) {
+                const w = opts.popupSize ? opts.popupSize.w : '90%';
+                const h = opts.popupSize ? opts.popupSize.h : '90%';
+                execFileSync('tmux', ['display-popup', '-E', '-w', w, '-h', h, paneCmd], { stdio: 'inherit' });
+            }
+            else {
+                await runInTmuxPane(paneCmd);
+            }
         }
         catch (err) {
             process.stderr.write(`tmux dispatch failed, running in current terminal: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -412,12 +573,13 @@ export async function launchReview(file, opts) {
         }
     }
     const now = new Date().toISOString();
+    const didSubmit = opts.submitFlagPath ? existsSync(opts.submitFlagPath) : true;
     const result = {
         file: absFile,
-        submitted: true,
-        approved: comments.length === 0,
+        submitted: didSubmit,
+        approved: didSubmit && comments.length === 0,
         comments,
-        submittedAt: now,
+        ...(didSubmit ? { submittedAt: now } : {}),
         savedAt: now,
     };
     atomicWrite(outPath, JSON.stringify(result, null, 2) + '\n');

package/dist/tui/input.js

@@ -177,15 +177,37 @@ function handleInteractionAction(input, key, state, interaction, render) {
         render();
         return;
     }
-    // Comment mode: allowFreetext + options exist. Multi-select carries its
-    // checked set on submit, so don't pre-attach a single option.
+    // Comment mode: allowFreetext + options exist.
+    //
+    // Single-select: pre-attach the focused option (the comment qualifies that
+    // pick). Multi-select: also pre-attach the focused option — the comment is
+    // saved under `optionComments[id]` (per-option note) and submitting
+    // auto-checks the option. From the [c] freetext row in multi-select,
+    // start with no attachment so the comment becomes the overall freetext.
     if (input === 'c' && interaction.allowFreetext && opts.length > 0) {
-        const preselected = !interaction.multiSelect && state.selectedAction < opts.length
-            ? opts[state.selectedAction].id
-            : undefined;
-        state.inputMode = preselected !== undefined
-            ? { kind: 'comment', buffer: '', selectedOptionId: preselected }
-            : { kind: 'comment', buffer: '' };
+        const onOption = state.selectedAction < opts.length;
+        if (onOption) {
+            const optId = opts[state.selectedAction].id;
+            let prefill = '';
+            if (interaction.multiSelect) {
+                const existing = state.responses.get(interaction.id);
+                const prior = existing?.optionComments?.[optId];
+                if (typeof prior === 'string')
+                    prefill = prior;
+            }
+            state.inputMode = { kind: 'comment', buffer: prefill, selectedOptionId: optId };
+        }
+        else {
+            // On the [c] row in multi-select: pre-fill from existing overall freetext.
+            let prefill = '';
+            if (interaction.multiSelect) {
+                const existing = state.responses.get(interaction.id);
+                if (existing !== undefined && typeof existing.freetext === 'string') {
+                    prefill = existing.freetext;
+                }
+            }
+            state.inputMode = { kind: 'comment', buffer: prefill };
+        }
         render();
         return;
     }
@@ -250,6 +272,18 @@ function handleInputMode(input, key, state, render) {
     }
     if (key.return) {
         const interaction = state.interactions[state.currentIndex];
+        const perOption = interaction.multiSelect === true
+            && mode.kind === 'comment'
+            && mode.selectedOptionId !== undefined;
+        if (perOption) {
+            // Per-option comment: save under optionComments[id], auto-check the
+            // option (idempotent), stay on this interaction so the human can comment
+            // on another option.
+            setOptionComment(state, interaction, mode.selectedOptionId, mode.buffer);
+            state.inputMode = null;
+            render();
+            return;
+        }
         if (interaction.multiSelect) {
             commitMulti(state, interaction, mode.buffer);
         }
@@ -361,14 +395,20 @@ function submitOption(state, interaction, selectedOptionId, freetext) {
 // submitOption immediacy); Enter just confirms the accumulated set + advances.
 function toggleMulti(state, interaction, optionId) {
     const existing = state.responses.get(interaction.id);
-    const set = new Set(existing?.selectedOptionIds ?? []);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
+    const set = new Set(priorIds);
     if (set.has(optionId))
         set.delete(optionId);
     else
         set.add(optionId);
     const response = { id: interaction.id, selectedOptionIds: [...set] };
-    if (existing?.freetext !== undefined)
+    if (existing !== undefined && existing.freetext !== undefined)
         response.freetext = existing.freetext;
+    if (existing !== undefined && existing.optionComments !== undefined) {
+        response.optionComments = { ...existing.optionComments };
+    }
     state.responses.set(interaction.id, response);
     // User edited the checked set — no longer a passive carry-over.
     state.preAnsweredIds.delete(interaction.id);
@@ -378,15 +418,52 @@ function toggleMulti(state, interaction, optionId) {
  *  answered, optionally setting/replacing freetext. */
 function commitMulti(state, interaction, freetext) {
     const existing = state.responses.get(interaction.id);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
     const response = {
         id: interaction.id,
-        selectedOptionIds: [...(existing?.selectedOptionIds ?? [])],
+        selectedOptionIds: [...priorIds],
     };
-    const ft = freetext ?? existing?.freetext;
+    let ft;
+    if (freetext !== undefined)
+        ft = freetext;
+    else if (existing !== undefined)
+        ft = existing.freetext;
     if (ft !== undefined)
         response.freetext = ft;
+    if (existing !== undefined && existing.optionComments !== undefined) {
+        response.optionComments = { ...existing.optionComments };
+    }
     state.responses.set(interaction.id, response);
     // Explicit confirm overrides any preAnswered seed.
     state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
+/**
+ * Multi-select per-option comment: write `comment` to optionComments[optionId]
+ * and auto-check the option. Empty comment still records the entry (the user
+ * committed deliberately via Enter; Esc cancels without write).
+ */
+function setOptionComment(state, interaction, optionId, comment) {
+    const existing = state.responses.get(interaction.id);
+    const priorIds = existing !== undefined && existing.selectedOptionIds !== undefined
+        ? existing.selectedOptionIds
+        : [];
+    const set = new Set(priorIds);
+    set.add(optionId);
+    const priorComments = existing !== undefined && existing.optionComments !== undefined
+        ? existing.optionComments
+        : {};
+    const nextComments = { ...priorComments, [optionId]: comment };
+    const response = {
+        id: interaction.id,
+        selectedOptionIds: [...set],
+        optionComments: nextComments,
+    };
+    if (existing !== undefined && existing.freetext !== undefined)
+        response.freetext = existing.freetext;
+    state.responses.set(interaction.id, response);
+    state.preAnsweredIds.delete(interaction.id);
+    state.persist?.();
+}

package/dist/tui/render.js

@@ -289,10 +289,11 @@ export function renderItemReview(state, cols, rows) {
         const label = interaction.freetextLabel !== undefined
             ? interaction.freetextLabel
             : state.inputMode.kind === 'comment' ? 'Comment' : 'Response';
-        // Show attached option (single-select comment mode only) — Tab cycles.
-        // Multi-select comments carry the checked set, so no attach line.
+        // Show attached option in comment mode. For single-select the comment
+        // qualifies the pick; for multi-select an attached option means the
+        // comment is saved as a per-option note (and auto-checks the option).
         let attachedLine;
-        if (state.inputMode.kind === 'comment' && !interaction.multiSelect) {
+        if (state.inputMode.kind === 'comment') {
             const attachedId = state.inputMode.selectedOptionId;
             const opts = interaction.options;
             if (opts.length > 0) {
@@ -301,7 +302,7 @@ export function renderItemReview(state, cols, rows) {
                     : undefined;
                 const valueText = attached !== undefined
                     ? `${CYAN}${singleLine(attached.label)}${RESET}`
-                    : `${DIM}none${RESET}`;
+                    : `${DIM}none (overall)${RESET}`;
                 attachedLine = `  ${DIM}attached:${RESET} ${valueText}  ${DIM}[tab to cycle]${RESET}`;
             }
         }
@@ -382,10 +383,11 @@ function renderActions(interaction, selectedAction, maxW, existing) {
     const prefixWidth = multi ? 12 : 8;
     const indent = ' '.repeat(prefixWidth);
     const contentMax = Math.max(20, maxW - prefixWidth);
+    const optionComments = existing !== undefined ? existing.optionComments : undefined;
     for (let i = 0; i < opts.length; i++) {
         const o = opts[i];
         const cursor = i === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        const sc = o.shortcut ?? ' ';
+        const sc = o.shortcut === undefined ? ' ' : o.shortcut;
         const keyBadge = `${DIM}[${sc}]${RESET}`;
         const box = multi
             ? (checked.has(o.id) ? `${GREEN}[x]${RESET}` : `${DIM}[ ]${RESET}`) + ' '
@@ -401,10 +403,25 @@ function renderActions(interaction, selectedAction, maxW, existing) {
                 lines.push(`${indent}${DIM}${dl}${RESET}`);
             }
         }
+        if (multi && optionComments !== undefined) {
+            const note = optionComments[o.id];
+            if (typeof note === 'string' && note.length > 0) {
+                const noteLines = wrap(`✎ ${sanitize(note)}`, contentMax);
+                for (const nl of noteLines) {
+                    lines.push(`${indent}${YELLOW}${nl}${RESET}`);
+                }
+            }
+        }
     }
     if (interaction.allowFreetext && opts.length > 0) {
         const cursor = opts.length === selectedAction ? `${CYAN}▸${RESET}` : ' ';
-        const label = interaction.freetextLabel !== undefined ? interaction.freetextLabel : 'Add comment';
+        let label;
+        if (interaction.freetextLabel !== undefined)
+            label = interaction.freetextLabel;
+        else if (multi)
+            label = 'Add overall comment  (c on an option for per-option)';
+        else
+            label = 'Add comment';
         lines.push(`  ${cursor} ${DIM}[c]${RESET} ${label}`);
     }
     else if (interaction.allowFreetext && opts.length === 0) {
@@ -463,11 +480,17 @@ export function renderFinal(state, cols, rows) {
 }
 export function responseSummary(r, interaction) {
     if (r.selectedOptionIds !== undefined) {
-        const labels = r.selectedOptionIds
+        const oc = r.optionComments;
+        const parts = r.selectedOptionIds
             .map((id) => interaction.options.find((o) => o.id === id))
             .filter((o) => o !== undefined)
-            .map((o) => sanitize(o.label));
-        const picks = labels.length > 0 ? labels.join(', ') : '(none)';
+            .map((o) => {
+            const note = oc !== undefined ? oc[o.id] : undefined;
+            return typeof note === 'string' && note.length > 0
+                ? `${sanitize(o.label)} ("${sanitize(note)}")`
+                : sanitize(o.label);
+        });
+        const picks = parts.length > 0 ? parts.join(', ') : '(none)';
         if (r.freetext)
             return `${picks}: "${sanitize(r.freetext)}"`;
         return picks;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { Key } from './tui/terminal.js';
-export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+export type InteractionKind = 'notify' | 'validation' | 'decision' | 'context' | 'error' | 'review';
 export interface InteractionOption {
     id: string;
     label: string;
@@ -45,6 +45,10 @@ export interface InteractionResponse {
     /** Multi-select picks (set only for `multiSelect` interactions). */
     selectedOptionIds?: string[];
     freetext?: string;
+    /** Multi-select per-option comments, keyed by option id. Each entry is a
+     *  comment scoped to that specific option (independent of the overall
+     *  `freetext`). Set only for `multiSelect` interactions. */
+    optionComments?: Record<string, string>;
 }
 export interface DeckSource {
     sessionName?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",