@crouton-kit/humanloop 0.3.30 → 0.3.31

package/dist/editor/feedback.d.ts

@@ -0,0 +1,18 @@
+import type { FeedbackComment, FeedbackResult } from '../types.js';
+export declare function sanitizeFeedbackComments(raw: unknown): FeedbackComment[];
+export declare function parseFeedbackComments(raw: unknown): {
+    ok: true;
+    comments: FeedbackComment[];
+} | {
+    ok: false;
+    message: string;
+};
+export declare function buildDraftFeedbackResult(file: string, comments: FeedbackComment[], savedAt?: string): FeedbackResult;
+export declare function buildFinalFeedbackResult(file: string, comments: FeedbackComment[], timestamp?: string): FeedbackResult;
+export declare function readStoredFeedbackResult(path: string, expectedFile?: string): FeedbackResult | null;
+export declare function readStoredDraftFeedbackResult(path: string, expectedFile: string): FeedbackResult | null;
+export declare function serializeFeedbackResult(result: FeedbackResult): string;
+export declare function writeFeedbackResult(path: string, result: FeedbackResult): string;
+export declare function writeDraftFeedbackResult(path: string, file: string, comments: FeedbackComment[], savedAt?: string): FeedbackResult;
+export declare function writeFinalFeedbackResult(path: string, file: string, comments: FeedbackComment[], timestamp?: string): FeedbackResult;
+export declare function writeSubmitFlag(path: string): void;

package/dist/editor/feedback.js

@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+// Column validity is only meaningful WITHIN a single line: `colEnd > colStart`
+// compares two byte offsets into the SAME line. For a multi-line range,
+// `colStart` is relative to the START line and `colEnd` is relative to the
+// (different) END line, so a numeric `colEnd > colStart` comparison is
+// meaningless and can reject a perfectly valid range (e.g. a short last line
+// legitimately has a smaller colEnd than the start line's colStart). Mirrors
+// web/src/lib/sourceMap.ts's `hasValidRangeColumns` — src/ can't import from
+// web/, so this is the local equivalent.
+function hasValidRangeColumns(line, endLine, colStart, colEnd) {
+    if (colStart === undefined || colEnd === undefined)
+        return false;
+    if (line === endLine)
+        return colEnd > colStart;
+    return true;
+}
+export function sanitizeFeedbackComments(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const r of raw) {
+        if (!isRecord(r))
+            continue;
+        const comment = typeof r.comment === 'string' ? r.comment.trim() : '';
+        if (!comment)
+            continue;
+        const line = Number(r.line) || 1;
+        const endLine = Number(r.endLine) || line;
+        const colStart = Number.isInteger(r.colStart) ? r.colStart : undefined;
+        const colEnd = Number.isInteger(r.colEnd) ? r.colEnd : undefined;
+        const validCols = hasValidRangeColumns(line, endLine, colStart, colEnd);
+        out.push({
+            id: typeof r.id === 'string' && r.id ? r.id : `c${out.length}`,
+            line,
+            endLine,
+            colStart: validCols ? colStart : undefined,
+            colEnd: validCols ? colEnd : undefined,
+            quote: typeof r.quote === 'string' && r.quote ? r.quote : undefined,
+            lineText: typeof r.lineText === 'string' ? r.lineText : '',
+            comment,
+            createdAt: typeof r.createdAt === 'string' ? r.createdAt : nowIso(),
+        });
+    }
+    return out;
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function isPositiveInteger(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
+function isNonNegativeInteger(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0;
+}
+// Strict, per-item validator for the browser-write API (PUT /api/review/draft,
+// POST /api/review/submit) — malformed anchors are rejected with a 400
+// instead of being silently normalized/dropped. `sanitizeFeedbackComments`
+// stays the separate, deliberately permissive path for loading legacy on-disk
+// drafts (readStoredFeedbackResult/readStoredDraftFeedbackResult), which must
+// keep tolerating old/hand-edited files.
+export function parseFeedbackComments(raw) {
+    if (!Array.isArray(raw)) {
+        return { ok: false, message: 'comments must be an array.' };
+    }
+    const comments = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (!isRecord(item))
+            return { ok: false, message: `comments[${i}] must be an object.` };
+        const { id, comment, line, endLine, lineText, createdAt, colStart, colEnd, quote } = item;
+        if (!isNonEmptyString(id))
+            return { ok: false, message: `comments[${i}].id must be a non-empty string.` };
+        if (!isNonEmptyString(comment))
+            return { ok: false, message: `comments[${i}].comment must be a non-empty string.` };
+        if (!isPositiveInteger(line))
+            return { ok: false, message: `comments[${i}].line must be a positive integer.` };
+        if (!isPositiveInteger(endLine))
+            return { ok: false, message: `comments[${i}].endLine must be a positive integer.` };
+        if (endLine < line)
+            return { ok: false, message: `comments[${i}].endLine must be >= line.` };
+        if (typeof lineText !== 'string')
+            return { ok: false, message: `comments[${i}].lineText must be a string.` };
+        if (!isNonEmptyString(createdAt))
+            return { ok: false, message: `comments[${i}].createdAt must be a non-empty string.` };
+        const hasColStart = colStart !== undefined;
+        const hasColEnd = colEnd !== undefined;
+        if (hasColStart !== hasColEnd)
+            return { ok: false, message: `comments[${i}].colStart/colEnd must be provided together.` };
+        let outColStart;
+        let outColEnd;
+        if (hasColStart && hasColEnd) {
+            if (!isNonNegativeInteger(colStart) || !isNonNegativeInteger(colEnd)) {
+                return { ok: false, message: `comments[${i}].colStart/colEnd must be non-negative integers.` };
+            }
+            if (line === endLine && colEnd <= colStart) {
+                return { ok: false, message: `comments[${i}].colEnd must be greater than colStart on a single-line range.` };
+            }
+            outColStart = colStart;
+            outColEnd = colEnd;
+        }
+        if (quote !== undefined && typeof quote !== 'string') {
+            return { ok: false, message: `comments[${i}].quote must be a string when present.` };
+        }
+        comments.push({
+            id, line, endLine,
+            colStart: outColStart, colEnd: outColEnd,
+            quote: typeof quote === 'string' && quote.length > 0 ? quote : undefined,
+            lineText, comment: comment.trim(), createdAt,
+        });
+    }
+    return { ok: true, comments };
+}
+export function buildDraftFeedbackResult(file, comments, savedAt = nowIso()) {
+    return {
+        file: resolve(file),
+        submitted: false,
+        approved: false,
+        comments: sanitizeFeedbackComments(comments),
+        savedAt,
+    };
+}
+export function buildFinalFeedbackResult(file, comments, timestamp = nowIso()) {
+    const sanitized = sanitizeFeedbackComments(comments);
+    return {
+        file: resolve(file),
+        submitted: true,
+        approved: sanitized.length === 0,
+        comments: sanitized,
+        submittedAt: timestamp,
+        savedAt: timestamp,
+    };
+}
+export function readStoredFeedbackResult(path, expectedFile) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw) || typeof raw.file !== 'string')
+        return null;
+    if (expectedFile !== undefined && raw.file !== expectedFile)
+        return null;
+    const comments = sanitizeFeedbackComments(raw.comments);
+    if (raw.submitted === true) {
+        const submittedAt = typeof raw.submittedAt === 'string' ? raw.submittedAt : nowIso();
+        const savedAt = typeof raw.savedAt === 'string' ? raw.savedAt : submittedAt;
+        return {
+            file: raw.file,
+            submitted: true,
+            approved: comments.length === 0,
+            comments,
+            submittedAt,
+            savedAt,
+        };
+    }
+    const savedAt = typeof raw.savedAt === 'string' ? raw.savedAt : nowIso();
+    return {
+        file: raw.file,
+        submitted: false,
+        approved: false,
+        comments,
+        savedAt,
+    };
+}
+export function readStoredDraftFeedbackResult(path, expectedFile) {
+    const result = readStoredFeedbackResult(path, resolve(expectedFile));
+    return result !== null && !result.submitted ? result : null;
+}
+export function serializeFeedbackResult(result) {
+    return JSON.stringify(result, null, 2) + '\n';
+}
+export function writeFeedbackResult(path, result) {
+    const payload = serializeFeedbackResult(result);
+    const tmp = `${path}.tmp`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(tmp, payload);
+    renameSync(tmp, path);
+    return path;
+}
+export function writeDraftFeedbackResult(path, file, comments, savedAt = nowIso()) {
+    const result = buildDraftFeedbackResult(file, comments, savedAt);
+    writeFeedbackResult(path, result);
+    return result;
+}
+export function writeFinalFeedbackResult(path, file, comments, timestamp = nowIso()) {
+    const result = buildFinalFeedbackResult(file, comments, timestamp);
+    writeFeedbackResult(path, result);
+    return result;
+}
+export function writeSubmitFlag(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, '');
+}

package/dist/editor/review.js

@@ -1,7 +1,10 @@
 import { spawn, spawnSync, execFileSync } from 'child_process';
-import { readFileSync, existsSync, writeFileSync, renameSync, mkdtempSync } from 'fs';
+import { existsSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { resolve, join } from 'path';
+import { openBrowser } from '../browser/open.js';
+import { startReviewWebServer } from '../browser/server.js';
+import { readStoredFeedbackResult, writeDraftFeedbackResult, writeFinalFeedbackResult, } from './feedback.js';
 function shellQuote(s) {
     if (s.length > 0 && /^[a-zA-Z0-9_\-./:@%+=]+$/.test(s))
         return s;
@@ -35,6 +38,8 @@ export function reviewVimscript() {
         `" The rest is the read-only guard, comment commands, and autosave.`,
         `let g:hl_out = $HL_OUTPUT`,
         `let g:hl_src = $HL_SOURCE`,
+        `let g:hl_review_url = $HL_REVIEW_URL`,
+        `let g:hl_handoff_flag = $HL_HANDOFF_FLAG`,
         `let s:comments = []`,
         `let s:idseq = 0`,
         `let s:ns = exists('*nvim_create_namespace') ? nvim_create_namespace('hl_review') : -1`,
@@ -306,11 +311,22 @@ export function reviewVimscript() {
         `  qa!`,
         `endfunction`,
         ``,
+        `function! s:HandOff() abort`,
+        `  call s:Save()`,
+        `  if g:hl_handoff_flag ==# ''`,
+        `    echohl ErrorMsg | echo 'Browser handoff unavailable' | echohl NONE`,
+        `    return`,
+        `  endif`,
+        `  call writefile([''], g:hl_handoff_flag)`,
+        `  qa!`,
+        `endfunction`,
+        ``,
         `command! HLComment call <SID>Comment('n')`,
         `command! HLList call <SID>List()`,
         `command! HLUndo call <SID>Undo()`,
         `command! HLSubmit call <SID>Submit()`,
-        `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)'`,
+        `command! HLBrowser call <SID>HandOff()`,
+        `command! HLHelp echo 'REVIEW  <Space>c comment   <Space>l list   <Space>u undo-last   <Space>s submit & quit   <Space>w browser handoff   |  in list: e/<CR> edit · dd delete · q close'`,
         ``,
         `" Highlights are (re)applied after any colorscheme so the user's theme`,
         `" (e.g. gloam) loads first, then our anchor highlight sits on top.`,
@@ -397,6 +413,7 @@ export function reviewVimscript() {
         `  nnoremap <buffer> <silent> <Space>l :call <SID>List()<CR>`,
         `  nnoremap <buffer> <silent> <Space>u :call <SID>Undo()<CR>`,
         `  nnoremap <buffer> <silent> <Space>s :call <SID>Submit()<CR>`,
+        `  nnoremap <buffer> <silent> <Space>w :call <SID>HandOff()<CR>`,
         `  call s:Hi()`,
         `  call s:Load()`,
         `  call s:Marks()`,
@@ -404,7 +421,7 @@ export function reviewVimscript() {
         `  " 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`,
+        `  echohl Question | echo 'hl review — c comment · l list · u undo · s submit · w browser  (:HLHelp)' | echohl NONE`,
         `endfunction`,
         `autocmd VimEnter * call s:Setup()`,
         `autocmd VimLeavePre * call s:Save()`,
@@ -426,40 +443,6 @@ export function reviewVimscript() {
         ``,
     ].join('\n');
 }
-function atomicWrite(path, data) {
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, data);
-    renameSync(tmp, path);
-}
-function sanitizeComments(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    const out = [];
-    for (const r of raw) {
-        if (typeof r !== 'object' || r === null)
-            continue;
-        const c = r;
-        const comment = typeof c.comment === 'string' ? c.comment.trim() : '';
-        if (!comment)
-            continue;
-        const line = Number(c.line) || 1;
-        const endLine = Number(c.endLine) || line;
-        const colStart = Number.isInteger(c.colStart) ? c.colStart : undefined;
-        const colEnd = Number.isInteger(c.colEnd) ? c.colEnd : undefined;
-        out.push({
-            id: typeof c.id === 'string' && c.id ? c.id : `c${out.length}`,
-            line,
-            endLine,
-            colStart: colStart !== undefined && colEnd !== undefined && colEnd > colStart ? colStart : undefined,
-            colEnd: colStart !== undefined && colEnd !== undefined && colEnd > colStart ? colEnd : undefined,
-            quote: typeof c.quote === 'string' && c.quote ? c.quote : undefined,
-            lineText: typeof c.lineText === 'string' ? c.lineText : '',
-            comment,
-            createdAt: typeof c.createdAt === 'string' ? c.createdAt : new Date().toISOString(),
-        });
-    }
-    return out;
-}
 const FEEDBACK_SCHEMA = '{file, submitted, approved, comments:[{id, line, endLine, quote?, colStart?, colEnd?, lineText, comment, createdAt}], submittedAt, savedAt}';
 function rangeLabel(c) {
     const cols = Number.isInteger(c.colStart) && Number.isInteger(c.colEnd);
@@ -559,6 +542,61 @@ function runInCurrentTerminal(bin, args, env) {
         child.on('exit', () => resolvePromise());
     });
 }
+function clearFlag(path) {
+    rmSync(path, { force: true });
+}
+function readDraftComments(path, absFile) {
+    const stored = readStoredFeedbackResult(path, absFile);
+    return stored?.comments ?? [];
+}
+function finalizeReviewOutput(outPath, absFile, didSubmit) {
+    const comments = readDraftComments(outPath, absFile);
+    return didSubmit
+        ? writeFinalFeedbackResult(outPath, absFile, comments)
+        : writeDraftFeedbackResult(outPath, absFile, comments);
+}
+async function waitForParkedReviewSubmit(submitted) {
+    process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
+        '  The terminal editor is parked; the browser is the editing authority.\n' +
+        '  Press w to take back into nvim, or Ctrl+C to exit with an unsubmitted draft.\n\n');
+    if (!process.stdin.isTTY) {
+        const result = await submitted;
+        return { type: 'submitted', result };
+    }
+    return new Promise((resolveAction) => {
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        let settled = false;
+        const cleanup = () => {
+            stdin.off('data', onData);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolveAction(action);
+        };
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8');
+            if (text === 'w' || text === 'W')
+                finish({ type: 'take-back' });
+            if (text === '\u0003')
+                finish({ type: 'cancel' });
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+        submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
+    });
+}
+async function stopReviewServer(handle) {
+    if (handle !== null)
+        await handle.stop();
+}
 /**
  * Open a markdown file in a clean, read-only Neovim/Vim review session. The
  * human anchors comments to source lines/selections with native vim motions
@@ -579,76 +617,107 @@ export async function launchReview(file, opts) {
     const initPath = join(dir, 'review.vim');
     if (!existsSync(initPath))
         writeFileSync(initPath, reviewVimscript());
-    const env = {
-        ...process.env,
-        HL_OUTPUT: outPath,
-        HL_SOURCE: absFile,
-        ...(opts.submitFlagPath ? { HL_SUBMIT_FLAG: opts.submitFlagPath } : {}),
-    };
+    const handoffFlagPath = join(dir, 'browser-handoff.flag');
     // `-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
     // review layer pulls in ONLY the colorscheme + treesitter styling itself.
     const editorArgs = ['-u', 'NONE', '-n', '-i', 'NONE', absFile, '-c', `source ${initPath}`];
     const inTmux = !!process.env.TMUX && !opts.noTmux;
-    process.stderr.write(`\nhumanloop: opening "${absFile}" for review in ${bin}` +
-        (inTmux ? ' (tmux pane).\n' : '.\n') +
-        `  Answers : ${outPath}\n` +
-        `  Keys    : <Space>c comment · <Space>l list · <Space>u undo · <Space>s submit & quit  (or :HLComment/:HLSubmit)\n` +
-        `  Status  : BLOCKING — waiting for you to finish the review and quit the editor.\n\n`);
-    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',
-            ...envPairs,
-            shellQuote(bin),
-            ...editorArgs.map(shellQuote),
-        ].join(' ');
-        try {
-            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' });
+    async function runEditor(reviewUrl) {
+        const env = {
+            ...process.env,
+            HL_OUTPUT: outPath,
+            HL_SOURCE: absFile,
+            HL_REVIEW_URL: reviewUrl,
+            HL_HANDOFF_FLAG: handoffFlagPath,
+            ...(opts.submitFlagPath ? { HL_SUBMIT_FLAG: opts.submitFlagPath } : {}),
+        };
+        process.stderr.write(`\nhumanloop: opening "${absFile}" for review in ${bin}` +
+            (inTmux ? ' (tmux pane).\n' : '.\n') +
+            `  Answers : ${outPath}\n` +
+            `  Browser : available after <Space>w hands off (or :HLBrowser)\n` +
+            `  Keys    : <Space>c comment · <Space>l list · <Space>u undo · <Space>s submit & quit · <Space>w browser  (or :HLComment/:HLSubmit/:HLBrowser)\n` +
+            `  Status  : BLOCKING — waiting for you to finish the review.\n\n`);
+        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)}`,
+                `HL_REVIEW_URL=${shellQuote(reviewUrl)}`,
+                `HL_HANDOFF_FLAG=${shellQuote(handoffFlagPath)}`,
+                ...(opts.submitFlagPath ? [`HL_SUBMIT_FLAG=${shellQuote(opts.submitFlagPath)}`] : []),
+            ];
+            const paneCmd = [
+                'exec',
+                'env',
+                ...envPairs,
+                shellQuote(bin),
+                ...editorArgs.map(shellQuote),
+            ].join(' ');
+            try {
+                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);
+                }
             }
-            else {
-                await runInTmuxPane(paneCmd);
+            catch (err) {
+                process.stderr.write(`tmux dispatch failed, running in current terminal: ${err instanceof Error ? err.message : String(err)}\n`);
+                await runInCurrentTerminal(bin, editorArgs, env);
             }
         }
-        catch (err) {
-            process.stderr.write(`tmux dispatch failed, running in current terminal: ${err instanceof Error ? err.message : String(err)}\n`);
+        else {
             await runInCurrentTerminal(bin, editorArgs, env);
         }
     }
-    else {
-        await runInCurrentTerminal(bin, editorArgs, env);
-    }
-    let comments = [];
-    if (existsSync(outPath)) {
+    while (true) {
+        clearFlag(handoffFlagPath);
+        let resolveSubmitted;
+        const submitted = new Promise((resolveSubmittedPromise) => {
+            resolveSubmitted = resolveSubmittedPromise;
+        });
+        const server = await startReviewWebServer({
+            jobDir: dir,
+            file: absFile,
+            output: outPath,
+            submitFlagPath: opts.submitFlagPath,
+            onSubmit: (result) => resolveSubmitted(result),
+        });
         try {
-            const prior = JSON.parse(readFileSync(outPath, 'utf8'));
-            comments = sanitizeComments(prior.comments);
+            await runEditor(server.url);
+            if (existsSync(handoffFlagPath)) {
+                server.activate();
+                process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
+                openBrowser(server.url);
+                const action = await waitForParkedReviewSubmit(submitted);
+                if (action.type === 'submitted') {
+                    await stopReviewServer(server);
+                    clearFlag(handoffFlagPath);
+                    return action.result;
+                }
+                if (action.type === 'take-back') {
+                    await server.requestTakeBack();
+                    await stopReviewServer(server);
+                    clearFlag(handoffFlagPath);
+                    process.stderr.write('humanloop: taking review back into the terminal editor.\n');
+                    continue;
+                }
+                await stopReviewServer(server);
+                clearFlag(handoffFlagPath);
+                return finalizeReviewOutput(outPath, absFile, false);
+            }
+            await stopReviewServer(server);
+            const didSubmit = opts.submitFlagPath ? existsSync(opts.submitFlagPath) : true;
+            return finalizeReviewOutput(outPath, absFile, didSubmit);
         }
-        catch {
-            // unreadable autosave — treat as no comments rather than failing the run
+        catch (err) {
+            await stopReviewServer(server);
+            throw err;
         }
     }
-    const now = new Date().toISOString();
-    const didSubmit = opts.submitFlagPath ? existsSync(opts.submitFlagPath) : true;
-    const result = {
-        file: absFile,
-        submitted: didSubmit,
-        approved: didSubmit && comments.length === 0,
-        comments,
-        ...(didSubmit ? { submittedAt: now } : {}),
-        savedAt: now,
-    };
-    atomicWrite(outPath, JSON.stringify(result, null, 2) + '\n');
-    return result;
 }

package/dist/inbox/deck-schema.d.ts

@@ -38,6 +38,7 @@ export declare const deckSchema: z.ZodObject<{
             decision: "decision";
             context: "context";
             error: "error";
+            review: "review";
         }>>;
         preAnswered: z.ZodOptional<z.ZodObject<{
             selectedOptionId: z.ZodOptional<z.ZodString>;
@@ -47,6 +48,18 @@ export declare const deckSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare function inlineBodyPath(deckPath: string, bodyPath: string): string;
+/**
+ * The ONE canonical `bodyPath` → `body` normalization boundary. Resolves every
+ * interaction's `bodyPath` (relative to `dir`, the interaction directory) into
+ * `body` and strips `bodyPath` from the result.
+ *
+ * Call this once, right before a deck is (re)written to `<dir>/deck.json` —
+ * `hl deck ask`, `hl deck update`, and the public `ask()` API all do — so
+ * every reader downstream (the terminal TUI's render + its live-reload
+ * poller, the browser server's `/api/interaction`) only ever sees a plain
+ * `body` and never has to special-case `bodyPath` itself. `parseDeck` (below)
+ * reuses this same function when reading a deck straight off disk.
+ */
+export declare function resolveDeckBodyPaths(deck: Deck, dir: string): Deck;
 export declare function parseDeck(deckPath: string): Deck;
 export declare function validateDeck(parsed: unknown): Deck;