@crouton-kit/humanloop 0.3.29 → 0.3.31

package/dist/api.js

@@ -5,6 +5,7 @@ import { resolveInteractionDir } from './tui/app.js';
 import { scanInbox } from './inbox/scan.js';
 import { pickFromInbox } from './inbox/tui.js';
 import { deckPath, atomicWriteJson, readJson, stampCanvasNode } from './inbox/convention.js';
+import { resolveDeckBodyPaths } from './inbox/deck-schema.js';
 import { getTerminalSize } from './tui/terminal.js';
 import { notifyDeck } from './inbox/deck-factories.js';
 import { buildSummary } from './summary.js';
@@ -20,6 +21,11 @@ function managedDir() {
 export async function ask(deck, opts = {}) {
     const dir = opts.dir ?? managedDir();
     mkdirSync(dir, { recursive: true });
+    // Canonical bodyPath → body normalization boundary (see deck-schema.ts) —
+    // resolved BEFORE the deck is ever written to disk, so every reader
+    // downstream (terminal render, the live-reload poller, the browser server)
+    // only ever sees a plain `body`.
+    deck = resolveDeckBodyPaths(deck, dir);
     stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {

package/dist/browser/open.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Best-effort open a URL in the user's default browser: `open` on macOS,
+ * `xdg-open` on Linux. Never throws and never blocks the handoff — an
+ * unsupported platform or a missing binary just prints the URL so the human
+ * can open it by hand.
+ */
+export declare function openBrowser(url: string): void;

package/dist/browser/open.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+/**
+ * Best-effort open a URL in the user's default browser: `open` on macOS,
+ * `xdg-open` on Linux. Never throws and never blocks the handoff — an
+ * unsupported platform or a missing binary just prints the URL so the human
+ * can open it by hand.
+ */
+export function openBrowser(url) {
+    const bin = process.platform === 'darwin' ? 'open'
+        : process.platform === 'linux' ? 'xdg-open'
+            : null;
+    if (bin === null) {
+        process.stderr.write(`humanloop: open this URL in a browser: ${url}\n`);
+        return;
+    }
+    try {
+        const child = spawn(bin, [url], { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            process.stderr.write(`humanloop: could not launch "${bin}" — open this URL manually: ${url}\n`);
+        });
+        child.unref();
+    }
+    catch {
+        process.stderr.write(`humanloop: open this URL in a browser: ${url}\n`);
+    }
+}

package/dist/browser/server.d.ts

@@ -0,0 +1,62 @@
+import type { Deck, FeedbackResult, InteractionResponse } from '../types.js';
+export interface WebServerOpts {
+    /** Interaction dir — the deck.json / response.json / progress.json convention. */
+    dir: string;
+    /** The deck to serve. Re-read from disk on every GET in case it changed. */
+    deck: Deck;
+    /**
+     * Fired once the browser's submit has been written to response.json —
+     * exactly once per server instance, only for the first accepted submit
+     * (later submits get a 409 and never re-fire this). `responsePath`/
+     * `completedAt` are already persisted to disk — the caller converges the
+     * host surface, it must NOT write the result again. Fired only after the
+     * submit's own HTTP 200 has finished flushing to its socket, so it is
+     * safe for this callback to `stop()` the server (which force-closes all
+     * open sockets) without racing the ack the browser is waiting on.
+     */
+    onSubmit?: (responses: InteractionResponse[], completedAt: string, responsePath: string) => void;
+}
+export interface ReviewWebServerOpts {
+    /** Shared review job dir — carries review.vim and feedback.json. */
+    jobDir: string;
+    /** Absolute source file under review. */
+    file: string;
+    /** Absolute feedback JSON output path. */
+    output: string;
+    /** Optional submit sentinel written on final browser submit. */
+    submitFlagPath?: string;
+    /** Fired after the HTTP submit ack has finished flushing. */
+    onSubmit?: (result: FeedbackResult, submittedAt: string, outputPath: string) => void;
+    /** Test-only override for how long `requestTakeBack()` waits for open tabs
+     *  to ack a flush before giving up and broadcasting `taken-back` anyway.
+     *  Defaults to 2000ms in real usage. */
+    takeBackAckTimeoutMs?: number;
+}
+export interface WebServerHandle {
+    /** `http://127.0.0.1:<port>/` — open this in a browser. */
+    url: string;
+    port: number;
+    /** Mark this server as the active editing authority — until called, the
+     *  write endpoints (review draft/submit) 409 with `not_handed_off`. Deck's
+     *  implementation is a documented no-op: a deck server is only ever created
+     *  post-handoff (see `enterHandoff` in tui/app.ts), so it has no separate
+     *  activation moment to gate. */
+    activate(): void;
+    /** Ask every connected browser tab to flush any pending edit and ack, then
+     *  broadcast `{type:'taken-back'}`. Bounded by a timeout so a tab that never
+     *  acks (closed, network hiccup) can't hang take-back forever. Safe to call
+     *  with zero open sockets (e.g. the browser was never opened). */
+    requestTakeBack(): Promise<void>;
+    /** Stop listening, close all sockets (WS and HTTP), and tear down. */
+    stop(): Promise<void>;
+}
+/**
+ * Start an on-demand local HTTP+WS server over one interaction dir. Binds to
+ * an ephemeral port on 127.0.0.1 only (never 0.0.0.0 — this is a same-machine
+ * handoff, not a shareable link). The caller owns the lifecycle: start it
+ * when the human hands off to the browser, `stop()` it on take-back or once
+ * `onSubmit` fires.
+ */
+export declare function startWebServer(opts: WebServerOpts): Promise<WebServerHandle>;
+/** Start a review-mode browser server over one markdown review job. */
+export declare function startReviewWebServer(opts: ReviewWebServerOpts): Promise<WebServerHandle>;

package/dist/browser/server.js

@@ -0,0 +1,440 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, extname, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
+import { deckPath, readJson, writeResponse, clearProgress } from '../inbox/convention.js';
+import { buildDraftFeedbackResult, buildFinalFeedbackResult, parseFeedbackComments, readStoredDraftFeedbackResult, serializeFeedbackResult, writeFeedbackResult, writeSubmitFlag, } from '../editor/feedback.js';
+// See $CRTR_CONTEXT_DIR/phase1-server-contract.md for the deck HTTP/WS API this
+// module implements — this file is the reference implementation for the deck
+// surface, and the review surface reuses the same static/WS skeleton.
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8',
+};
+// Compiled server.js lives at dist/browser/server.js; the Vite SPA bundle
+// builds into dist/web (see web/vite.config.ts) — siblings under dist/, so
+// this never collides with tsc's own output tree.
+const STATIC_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', 'web');
+function send(res, status, body, contentType) {
+    res.writeHead(status, { 'Content-Type': contentType, 'Content-Length': Buffer.byteLength(body) });
+    res.end(body);
+}
+function sendJson(res, status, value) {
+    send(res, status, JSON.stringify(value), 'application/json; charset=utf-8');
+}
+async function readRequestBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function serveStatic(reqPath, res) {
+    // Strip query string + guard path traversal. Unknown paths (and `/`) fall
+    // back to index.html — there is no server-side routing, the SPA owns it.
+    const safePath = reqPath.split('?')[0].replace(/\.\.(\/|\\)/g, '');
+    let filePath = join(STATIC_ROOT, safePath === '/' ? '/index.html' : safePath);
+    if (!existsSync(filePath))
+        filePath = join(STATIC_ROOT, 'index.html');
+    try {
+        const body = await readFile(filePath);
+        const type = MIME[extname(filePath)] ?? 'application/octet-stream';
+        res.writeHead(200, { 'Content-Type': type, 'Content-Length': body.length });
+        res.end(body);
+    }
+    catch {
+        send(res, 404, 'humanloop: dist/web is missing — run `npm run build` (which builds the web/ SPA too) before opening the browser surface.', 'text/plain; charset=utf-8');
+    }
+}
+function wrongSurface(expected) {
+    return { error: 'wrong_surface', expected };
+}
+function createServerScaffold() {
+    let handleRequest = async () => { };
+    const httpServer = createServer((req, res) => {
+        void handleRequest(req, res);
+    });
+    const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
+    const sockets = new Set();
+    wss.on('connection', (ws) => {
+        sockets.add(ws);
+        ws.on('close', () => sockets.delete(ws));
+    });
+    let stopped = false;
+    // Resolves once every currently-open socket's `ws.send` has actually
+    // flushed its payload to the OS socket buffer — NOT once the browser has
+    // received/processed it. Callers that follow a broadcast with a teardown
+    // (stop()/closeAllConnections()) must await this first, or the terminate
+    // can race the send and the frame never leaves the process.
+    function broadcast(message) {
+        const payload = JSON.stringify(message);
+        const flushed = [];
+        for (const ws of sockets) {
+            if (ws.readyState !== ws.OPEN)
+                continue;
+            flushed.push(new Promise((resolveSend) => { ws.send(payload, () => resolveSend()); }));
+        }
+        return Promise.all(flushed).then(() => undefined);
+    }
+    function setHandler(next) {
+        handleRequest = next;
+    }
+    function stop() {
+        if (stopped)
+            return Promise.resolve();
+        stopped = true;
+        return new Promise((resolveStop) => {
+            for (const ws of sockets)
+                ws.terminate();
+            wss.close();
+            // Ephemeral, single-purpose server: force-close any lingering keep-alive
+            // sockets rather than waiting on http.Server#close's default drain-first
+            // behavior.
+            httpServer.closeAllConnections();
+            httpServer.close(() => resolveStop());
+        });
+    }
+    return { httpServer, broadcast, setHandler, stop, sockets };
+}
+async function listen(server) {
+    await new Promise((resolveListen, rejectListen) => {
+        server.once('error', rejectListen);
+        server.listen(0, '127.0.0.1', () => resolveListen());
+    });
+    const address = server.address();
+    return typeof address === 'object' && address !== null ? address.port : 0;
+}
+async function startDeckServer(opts) {
+    let deck = opts.deck;
+    const dir = opts.dir;
+    let submitted = null;
+    const scaffold = createServerScaffold();
+    scaffold.setHandler(async (req, res) => {
+        const url = req.url ?? '/';
+        if (url === '/api/surface' && req.method === 'GET') {
+            sendJson(res, 200, { kind: 'deck' });
+            return;
+        }
+        if (url === '/api/interaction' && req.method === 'GET') {
+            // Re-read deck.json in case an agent rewrote it mid-handoff (mirrors
+            // the terminal deck's own live-reload poll in resolveInteractionDir).
+            // Best-effort — falls back to the in-memory deck if the read fails.
+            const onDisk = readJson(deckPath(dir));
+            if (onDisk !== null)
+                deck = onDisk;
+            sendJson(res, 200, { dir, deck });
+            return;
+        }
+        if (url === '/api/submit' && req.method === 'POST') {
+            let parsed;
+            try {
+                parsed = JSON.parse(await readRequestBody(req));
+            }
+            catch {
+                sendJson(res, 400, { error: 'bad_json', message: 'Request body is not valid JSON.' });
+                return;
+            }
+            if (!Array.isArray(parsed.responses)) {
+                sendJson(res, 400, { error: 'bad_input', message: 'responses must be an array.' });
+                return;
+            }
+            // Single-assignment: the first accepted submit wins. A later submit
+            // (double-click, a second open tab, a retry) never re-writes
+            // response.json or re-fires onSubmit — it gets the same canonical
+            // result back via 409.
+            if (submitted !== null) {
+                sendJson(res, 409, { ok: false, error: 'already_submitted', ...submitted });
+                return;
+            }
+            const responses = parsed.responses;
+            const completedAt = new Date().toISOString();
+            // Canonical write — the exact helper the terminal path uses, so nothing
+            // downstream of response.json can tell which surface produced it.
+            const responsePath = writeResponse(dir, responses, completedAt, deck);
+            submitted = { responsePath, completedAt };
+            clearProgress(dir);
+            // Await the flush BEFORE registering the finish callback that can
+            // trigger caller-side stop() — that ordering is what closes the race
+            // between a lost WS frame and the teardown it precedes.
+            await scaffold.broadcast({ type: 'converged' });
+            // Ack-ordering guarantee: the HTTP caller must always receive its 200
+            // body before any lifecycle teardown can close its socket.
+            res.once('finish', () => {
+                opts.onSubmit?.(responses, completedAt, responsePath);
+            });
+            sendJson(res, 200, { ok: true, responsePath, completedAt });
+            return;
+        }
+        if (url.startsWith('/api/review')) {
+            sendJson(res, 404, wrongSurface('deck'));
+            return;
+        }
+        await serveStatic(url, res);
+    });
+    const port = await listen(scaffold.httpServer);
+    const url = `http://127.0.0.1:${port}/`;
+    return {
+        url,
+        port,
+        // No-op: a deck server is only ever started post-handoff (enterHandoff in
+        // tui/app.ts), so it has no separate activation moment to gate.
+        activate() { },
+        async requestTakeBack() {
+            await scaffold.broadcast({ type: 'taken-back' });
+        },
+        stop() {
+            return scaffold.stop();
+        },
+    };
+}
+async function startReviewServer(opts) {
+    const { jobDir, file, output, submitFlagPath } = opts;
+    const scaffold = createServerScaffold();
+    let activated = false;
+    let version = 0;
+    let ackWaiter = null;
+    const TAKE_BACK_ACK_TIMEOUT_MS = opts.takeBackAckTimeoutMs ?? 2000;
+    let currentResult = readStoredDraftFeedbackResult(output, file)
+        ?? buildDraftFeedbackResult(file, [], new Date().toISOString());
+    function refreshInitialDraftFromDisk() {
+        if (version !== 0 || currentResult.submitted)
+            return;
+        const onDisk = readStoredDraftFeedbackResult(output, file);
+        if (onDisk === null)
+            return;
+        if (serializeFeedbackResult(onDisk) !== serializeFeedbackResult(currentResult)) {
+            currentResult = onDisk;
+            version += 1;
+        }
+    }
+    function currentSnapshot() {
+        return currentResult;
+    }
+    // Bounded wait for `expected` open tabs to POST /api/review/take-back-ack
+    // after a take-back-requested broadcast. Resolves early once every tab has
+    // acked, or after `timeoutMs` regardless — a tab that never acks (closed,
+    // network hiccup) can't hang take-back forever.
+    function waitForTakeBackAcks(expected, timeoutMs) {
+        if (expected <= 0)
+            return Promise.resolve();
+        return new Promise((resolveWait) => {
+            let settled = false;
+            const timer = setTimeout(finish, timeoutMs);
+            function finish() {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                ackWaiter = null;
+                resolveWait();
+            }
+            ackWaiter = { expected, count: 0, resolve: finish };
+        });
+    }
+    scaffold.setHandler(async (req, res) => {
+        const url = req.url ?? '/';
+        if (url === '/api/surface' && req.method === 'GET') {
+            sendJson(res, 200, { kind: 'review' });
+            return;
+        }
+        if (url === '/api/review' && req.method === 'GET') {
+            refreshInitialDraftFromDisk();
+            let content;
+            try {
+                content = await readFile(file, 'utf8');
+            }
+            catch (err) {
+                sendJson(res, 404, {
+                    error: 'source_not_found',
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                return;
+            }
+            sendJson(res, 200, {
+                kind: 'review',
+                file,
+                output,
+                jobId: basename(jobDir),
+                content,
+                result: currentSnapshot(),
+                version,
+                activated,
+            });
+            return;
+        }
+        if (url === '/api/review/take-back-ack' && req.method === 'POST') {
+            // No activation gate needed — acking a flush request is safe regardless
+            // of handoff state.
+            if (ackWaiter !== null) {
+                ackWaiter.count += 1;
+                if (ackWaiter.count >= ackWaiter.expected)
+                    ackWaiter.resolve();
+            }
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+        if (url === '/api/review/draft' && req.method === 'PUT') {
+            let parsed;
+            try {
+                parsed = JSON.parse(await readRequestBody(req));
+            }
+            catch {
+                sendJson(res, 400, { error: 'bad_json', message: 'Request body is not valid JSON.' });
+                return;
+            }
+            if (!activated) {
+                sendJson(res, 409, { error: 'not_handed_off', message: 'Review authority has not been handed off to the browser yet.' });
+                return;
+            }
+            refreshInitialDraftFromDisk();
+            if (currentResult.submitted) {
+                sendJson(res, 409, { error: 'already_submitted', result: currentSnapshot() });
+                return;
+            }
+            if (!Number.isInteger(parsed.baseVersion)) {
+                sendJson(res, 400, { error: 'bad_input', message: 'baseVersion must be an integer.' });
+                return;
+            }
+            if (parsed.baseVersion !== version) {
+                sendJson(res, 409, { error: 'stale_draft', version, result: currentSnapshot() });
+                return;
+            }
+            const parsedComments = parseFeedbackComments(parsed.comments);
+            if (!parsedComments.ok) {
+                sendJson(res, 400, { error: 'bad_input', message: parsedComments.message });
+                return;
+            }
+            const savedAt = new Date().toISOString();
+            const nextResult = buildDraftFeedbackResult(file, parsedComments.comments, savedAt);
+            try {
+                writeFeedbackResult(output, nextResult);
+            }
+            catch (err) {
+                sendJson(res, 500, { error: 'internal', message: err instanceof Error ? err.message : String(err) });
+                return;
+            }
+            currentResult = nextResult;
+            version += 1;
+            await scaffold.broadcast({ type: 'review-draft-updated', version, savedAt });
+            sendJson(res, 200, { ok: true, result: currentSnapshot(), version });
+            return;
+        }
+        if (url === '/api/review/submit' && req.method === 'POST') {
+            let parsed;
+            try {
+                parsed = JSON.parse(await readRequestBody(req));
+            }
+            catch {
+                sendJson(res, 400, { error: 'bad_json', message: 'Request body is not valid JSON.' });
+                return;
+            }
+            if (!activated) {
+                sendJson(res, 409, { error: 'not_handed_off', message: 'Review authority has not been handed off to the browser yet.' });
+                return;
+            }
+            refreshInitialDraftFromDisk();
+            if (currentResult.submitted) {
+                sendJson(res, 409, {
+                    ok: false,
+                    error: 'already_submitted',
+                    output,
+                    submittedAt: currentResult.submittedAt,
+                    result: currentSnapshot(),
+                });
+                return;
+            }
+            if (!Number.isInteger(parsed.baseVersion)) {
+                sendJson(res, 400, { error: 'bad_input', message: 'baseVersion must be an integer.' });
+                return;
+            }
+            if (parsed.baseVersion !== version) {
+                sendJson(res, 409, { error: 'stale_draft', version, result: currentSnapshot() });
+                return;
+            }
+            const parsedComments = parseFeedbackComments(parsed.comments);
+            if (!parsedComments.ok) {
+                sendJson(res, 400, { error: 'bad_input', message: parsedComments.message });
+                return;
+            }
+            const submittedAt = new Date().toISOString();
+            const nextResult = buildFinalFeedbackResult(file, parsedComments.comments, submittedAt);
+            try {
+                writeFeedbackResult(output, nextResult);
+                currentResult = nextResult;
+                if (submitFlagPath !== undefined && submitFlagPath.length > 0) {
+                    writeSubmitFlag(submitFlagPath);
+                }
+            }
+            catch (err) {
+                sendJson(res, 500, { error: 'internal', message: err instanceof Error ? err.message : String(err) });
+                return;
+            }
+            // Await the flush BEFORE registering the finish callback that can
+            // trigger caller-side stop() — that ordering is what closes the race
+            // between a lost WS frame and the teardown it precedes.
+            await scaffold.broadcast({ type: 'converged' });
+            res.once('finish', () => {
+                opts.onSubmit?.(currentSnapshot(), submittedAt, output);
+            });
+            sendJson(res, 200, { ok: true, output, submittedAt, result: currentSnapshot() });
+            return;
+        }
+        if (url.startsWith('/api/interaction') || url === '/api/submit') {
+            sendJson(res, 404, wrongSurface('review'));
+            return;
+        }
+        await serveStatic(url, res);
+    });
+    const port = await listen(scaffold.httpServer);
+    const url = `http://127.0.0.1:${port}/`;
+    return {
+        url,
+        port,
+        activate() {
+            activated = true;
+        },
+        async requestTakeBack() {
+            const targets = [...scaffold.sockets].filter((ws) => ws.readyState === ws.OPEN);
+            if (targets.length > 0) {
+                // Arm the ack waiter BEFORE broadcasting take-back-requested — a very
+                // fast browser could otherwise flush its dirty draft and POST
+                // /api/review/take-back-ack while the broadcast's own ws.send flush
+                // callbacks are still resolving. Arming after the broadcast (the old
+                // order) drops that ack on the floor (ackWaiter was still null when
+                // it arrived), forcing the full timeout even though the flush
+                // already succeeded. Starting the waiter first, then awaiting both
+                // the broadcast flush and the waiter together, closes that window.
+                const acked = waitForTakeBackAcks(targets.length, TAKE_BACK_ACK_TIMEOUT_MS);
+                await Promise.all([scaffold.broadcast({ type: 'take-back-requested' }), acked]);
+            }
+            await scaffold.broadcast({ type: 'taken-back' });
+        },
+        stop() {
+            return scaffold.stop();
+        },
+    };
+}
+/**
+ * Start an on-demand local HTTP+WS server over one interaction dir. Binds to
+ * an ephemeral port on 127.0.0.1 only (never 0.0.0.0 — this is a same-machine
+ * handoff, not a shareable link). The caller owns the lifecycle: start it
+ * when the human hands off to the browser, `stop()` it on take-back or once
+ * `onSubmit` fires.
+ */
+export async function startWebServer(opts) {
+    return startDeckServer(opts);
+}
+/** Start a review-mode browser server over one markdown review job. */
+export async function startReviewWebServer(opts) {
+    return startReviewServer(opts);
+}

package/dist/cli.js

@@ -6,13 +6,15 @@ import { tmpdir } from 'node:os';
 import { resolve, join, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { launchReview, reviewVimscript } from './editor/review.js';
-import { validateDeck } from './inbox/deck-schema.js';
+import { writeFeedbackResult } from './editor/feedback.js';
+import { validateDeck, resolveDeckBodyPaths } from './inbox/deck-schema.js';
 import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
 import { renderMarkdown, checkMarkdown } from './render/termrender.js';
 import { scanInbox } from './inbox/scan.js';
 import { deckPath, atomicWriteJson, readJson, responsePath, stampCanvasNode, } from './inbox/convention.js';
 import { buildSummary } from './summary.js';
+import { INTERACTION_KINDS } from './types.js';
 // ── Version ───────────────────────────────────────────────────────────────────
 const HL_VERSION = '0.2.1';
 function emitError(err, exitCode = 1) {
@@ -218,7 +220,7 @@ const REQUEST_SCHEMA = {
                     },
                     allowFreetext: { type: 'boolean' },
                     freetextLabel: { type: 'string' },
-                    kind: { type: 'string', enum: ['notify', 'decision', 'context', 'error'] },
+                    kind: { type: 'string', enum: [...INTERACTION_KINDS] },
                 },
             },
         },
@@ -372,6 +374,19 @@ deckCmd
     }
     const dir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-ix-'));
     mkdirSync(dir, { recursive: true });
+    // Canonical bodyPath → body normalization boundary (deck-schema.ts) —
+    // resolved before deck.json is ever written, so terminal render, the
+    // live-reload poller, and the browser server all just see `body`.
+    try {
+        deck = resolveDeckBodyPaths(deck, dir);
+    }
+    catch (bodyErr) {
+        emitError({
+            error: 'deck_invalid',
+            message: bodyErr instanceof Error ? bodyErr.message : String(bodyErr),
+            next: 'Fix bodyPath (must point at a real file inside the interaction dir) and retry.',
+        });
+    }
     stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const jobId = basename(dir);
@@ -510,6 +525,17 @@ deckCmd
             next: "The live deck is unchanged. Fix the deck, then: echo '{\"deck\":{...}}' | hl deck validate",
         });
     }
+    // Same canonical bodyPath → body normalization boundary as `deck ask`.
+    try {
+        deck = resolveDeckBodyPaths(deck, dir);
+    }
+    catch (bodyErr) {
+        emitError({
+            error: 'deck_invalid',
+            message: bodyErr instanceof Error ? bodyErr.message : String(bodyErr),
+            next: 'The live deck is unchanged. Fix bodyPath (must point at a real file inside the interaction dir) and retry.',
+        });
+    }
     atomicWriteJson(deckPath(dir), deck);
     appendJobLog(dir, {
         level: 'info', event: 'deck_updated',
@@ -575,7 +601,9 @@ reviewCmd
     '         harness notifies you when it returns with the result.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
-    const input = parseStdinJson();
+    const input = process.env.HL_REVIEW_OPEN_INPUT
+        ? JSON.parse(process.env.HL_REVIEW_OPEN_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"}' });
     }
@@ -606,7 +634,7 @@ reviewCmd
         }
         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`;
+        const cmd = `HL_REVIEW_OPEN_INPUT=${sq(childInput)} ${sq(process.execPath)} ${sq(scriptPath)} review open`;
         try {
             execFileSync('tmux', ['split-window', '-d', '-h', cmd], { stdio: 'ignore' });
         }
@@ -623,15 +651,18 @@ reviewCmd
         await new Promise((resolvePromise) => {
             const poll = setInterval(() => {
                 const fp = join(jobDir, 'feedback.json');
-                if (existsSync(fp)) {
-                    const result = tryParseJson(readFileSync(fp, 'utf8'));
-                    if (result !== null) {
-                        clearInterval(poll);
-                        process.stdout.write(JSON.stringify({ job_id: jobId, output, status: 'done', result }) + '\n');
-                        process.exit(0);
-                    }
+                const result = existsSync(fp) ? tryParseJson(readFileSync(fp, 'utf8')) : null;
+                if (result !== null && result.submitted === true) {
+                    clearInterval(poll);
+                    process.stdout.write(JSON.stringify({ job_id: jobId, output, status: 'done', result }) + '\n');
+                    process.exit(0);
                 }
                 const state = detectJobState(jobDir);
+                if (state === 'done' && result !== null) {
+                    clearInterval(poll);
+                    process.stdout.write(JSON.stringify({ job_id: jobId, output, status: 'done', result }) + '\n');
+                    process.exit(0);
+                }
                 if (state === 'failed' || state === 'canceled') {
                     clearInterval(poll);
                     process.stdout.write(JSON.stringify({ job_id: jobId, output, status: state }) + '\n');
@@ -652,7 +683,7 @@ reviewCmd
             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));
+        writeFeedbackResult(join(jobDir, 'feedback.json'), result);
         process.stdout.write(JSON.stringify({
             job_id: jobId,
             output,