@crouton-kit/humanloop 0.3.2 → 0.3.5

package/dist/api.js

@@ -55,13 +55,15 @@ export async function ask(deck, opts = {}) {
     const dir = opts.dir ?? managedDir();
     mkdirSync(dir, { recursive: true });
     atomicWriteJson(deckPath(dir), deck);
-    const { responses, completedAt, responsePath } = await resolveInteractionDir(dir, deck, {
+    const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
         sessionId: opts.sessionId,
         cols: opts.cols,
         rows: opts.rows,
     });
     return {
-        summary: buildSummary(deck, responses),
+        // `answeredDeck` === `deck` unless an agent ran `hl deck update`
+        // mid-flight; the summary must describe the questions actually answered.
+        summary: buildSummary(answeredDeck, responses),
         responsePath,
         schema: RESPONSE_SCHEMA_ID,
         responses,

package/dist/cli.js

@@ -9,6 +9,7 @@ import { launchReview } from './editor/review.js';
 import { validateDeck } from './inbox/deck-schema.js';
 import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
+import { renderMarkdown, checkMarkdown } from './render/termrender.js';
 import { scanInbox } from './inbox/scan.js';
 import { deckPath, atomicWriteJson, readJson, responsePath, } from './inbox/convention.js';
 // ── Version ───────────────────────────────────────────────────────────────────
@@ -297,6 +298,7 @@ program
     '  deck       — structured set of interactions (questions) for the human\n' +
     '  review     — freeform markdown document review with anchored comments\n' +
     '  view       — passive live render of a file in a tmux pane\n' +
+    '  doc        — render or validate directive-flavored markdown to stdout\n' +
     '  inbox      — list/resolve all pending interactions across root dirs\n' +
     '  job        — a running or completed kickoff (deck ask / review / inbox)\n' +
     '  schema     — JSON Schema for deck, resolution, or feedback payloads\n' +
@@ -305,6 +307,7 @@ program
     '  hl deck   — write questions, get answers      | use when: material decisions\n' +
     '  hl review — markdown doc review               | use when: doc feedback needed\n' +
     '  hl view   — live render in pane               | use when: displaying a file\n' +
+    '  hl doc    — render/validate to stdout         | use when: piping rendered markdown\n' +
     '  hl inbox  — browse pending interactions       | use when: clearing a backlog\n' +
     '  hl job    — inspect/wait/cancel running jobs  | use when: polling job output\n' +
     '  hl schema — print JSON Schemas                | use when: validating inputs\n' +
@@ -313,7 +316,17 @@ program
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
 // ── deck ──────────────────────────────────────────────────────────────────────
-const deckCmd = program.command('deck').description('Write questions, get answers from the human.');
+const deckCmd = program.command('deck').description('Write questions, get answers from the human.\n' +
+    '\n' +
+    'Children:\n' +
+    '  hl deck ask      — spawn the decisions TUI, return a job handle | use when: posing material decisions\n' +
+    '  hl deck update   — replace the deck of a LIVE ask job in place   | use when: the questions changed after ask\n' +
+    '  hl deck validate — preflight a deck object, no side effects      | use when: checking a deck before ask\n' +
+    '\n' +
+    'A `deck update` rewrites the live job\'s deck.json; the TUI pane the\n' +
+    'human is looking at reloads it automatically within ~1s (answers whose\n' +
+    'interaction ids still exist are kept). Read this leaf\'s -h before calling\n' +
+    'it — it mutates a session a human is actively in.');
 deckCmd
     .command('ask')
     .description('Kickoff: spawn the decisions TUI and return immediately.\n' +
@@ -324,7 +337,9 @@ deckCmd
     '\n' +
     'Effects: writes <dir>/deck.json, <dir>/progress.json (live),\n' +
     '         <dir>/response.json (on finish), <dir>/job.log (JSONL).\n' +
-    '         Spawns TUI detached in a tmux pane when tmux=true and $TMUX set.\n')
+    '         Spawns TUI detached in a tmux pane when tmux=true and $TMUX set.\n' +
+    '         While the job is live the TUI watches <dir>/deck.json: a later\n' +
+    '         `hl deck update` rewrites it and the pane reloads automatically.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
     const input = parseStdinJson();
@@ -407,7 +422,7 @@ deckCmd
         process.stdout.write(JSON.stringify({
             job_id: jobId,
             dir,
-            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes.`,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes. If the questions change before they answer, pipe {"job_id":"${jobId}","deck":{...}} to hl deck update — the pane reloads automatically.`,
         }) + '\n');
         process.exit(0);
     }
@@ -435,6 +450,74 @@ deckCmd
         });
     }
 });
+deckCmd
+    .command('update')
+    .description('Replace the deck of a LIVE ask job; the human\'s TUI pane reloads.\n' +
+    '\n' +
+    'stdin  { job_id: string (required), deck: object (required) }\n' +
+    'stdout { ok: true, job_id: string, interactions: int, follow_up: string }\n' +
+    '\n' +
+    'The TUI watches deck.json and reloads within ~1s of this write. Answers\n' +
+    'whose interaction id still exists in the new deck are preserved; new or\n' +
+    'id-changed interactions appear unanswered. In-flight unsubmitted input\n' +
+    '(a comment being typed) is discarded on reload.\n' +
+    '\n' +
+    'Errors: job_not_found (no such job_id) | job_not_live (already\n' +
+    'done/failed/canceled — nothing to reload) | deck_invalid (deck rejected;\n' +
+    'the old deck stays in place, run hl deck validate first).\n' +
+    '\n' +
+    'Effects: atomically rewrites <dir>/deck.json; appends a deck_updated\n' +
+    'event to <dir>/job.log. No effect on response.json/progress.json.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    if (!input.job_id || typeof input.job_id !== 'string') {
+        emitError({ error: 'bad_input', message: 'job_id is required', field: 'job_id', next: 'Provide: {"job_id": "<id>", "deck": {...}}' });
+    }
+    if (!input.deck || typeof input.deck !== 'object') {
+        emitError({ error: 'bad_input', message: 'deck is required and must be an object', field: 'deck', next: "Run: echo '{\"kind\":\"deck\"}' | hl schema show" });
+    }
+    const dir = resolveJobDir(input.job_id);
+    if (!existsSync(dir) || !existsSync(deckPath(dir))) {
+        emitError({ error: 'job_not_found', message: `Job not found: ${input.job_id}`, next: 'Check the job_id returned by hl deck ask.' });
+    }
+    const state = detectJobState(dir);
+    if (state !== 'live') {
+        emitError({
+            error: 'job_not_live',
+            message: `Job is ${state}; its deck can no longer be reloaded.`,
+            received: state,
+            next: 'The human already finished. Start a fresh deck with hl deck ask.',
+        });
+    }
+    let deck;
+    try {
+        const _v = {};
+        void _v;
+        deck = validateDeck(input.deck);
+    }
+    catch (validationErr) {
+        emitError({
+            error: 'deck_invalid',
+            message: `deck validation failed: ${validationErr instanceof Error ? validationErr.message : String(validationErr)}`,
+            received: input.deck,
+            next: "The live deck is unchanged. Fix the deck, then: echo '{\"deck\":{...}}' | hl deck validate",
+        });
+    }
+    atomicWriteJson(deckPath(dir), deck);
+    appendJobLog(dir, {
+        level: 'info', event: 'deck_updated',
+        message: `deck replaced (${deck.interactions.length} interaction(s)); pane reloads on next watch tick`,
+        data: { jobId: basename(dir), interactions: deck.interactions.length },
+    });
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        job_id: basename(dir),
+        interactions: deck.interactions.length,
+        follow_up: `The pane reloads within ~1s. Still resolve with hl job result {"job_id":"${basename(dir)}","wait":true}.`,
+    }) + '\n');
+    process.exit(0);
+});
 deckCmd
     .command('validate')
     .description('Preflight deck validation — no side effects.\n' +
@@ -546,6 +629,79 @@ viewCmd
     }
     process.exit(0);
 });
+// ── doc ───────────────────────────────────────────────────────────────────────
+const docCmd = program.command('doc').description('Render or validate directive-flavored markdown to stdout.\n' +
+    '\n' +
+    'Children:\n' +
+    '  hl doc check  — validate directive syntax, no output | use when: preflighting before write\n' +
+    '  hl doc render — render markdown to ANSI/plain stdout | use when: piping rendered text to a file or consumer\n' +
+    '\n' +
+    'These wrap the pinned termrender binary that humanloop manages. Consumers\n' +
+    'should never call `termrender` directly — go through hl/SDK so there is one\n' +
+    'org-wide caller.\n');
+docCmd
+    .command('check')
+    .description('Validate directive-flavored markdown without rendering.\n' +
+    '\n' +
+    'stdin  { source?: string, path?: string }   exactly one required\n' +
+    'stdout { ok: bool, error?: string }\n' +
+    'exit   0 always (validation failures are not process errors)\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    const src = resolveDocSource(input);
+    const res = checkMarkdown(src);
+    process.stdout.write(JSON.stringify(res) + '\n');
+    process.exit(0);
+});
+docCmd
+    .command('render')
+    .description('Render directive-flavored markdown to ANSI or plain text on stdout.\n' +
+    '\n' +
+    'stdin  { source?: string, path?: string, width?: int=process.stdout.columns||100, color?: bool=true }\n' +
+    'stdout the rendered text (raw bytes; not JSON)\n' +
+    'exit   0 on success, non-zero on bad input\n' +
+    '\n' +
+    'When color=false, ANSI escape sequences are stripped from the output.\n' +
+    'Use this for feeding rendered content to other agents that need plain\n' +
+    'text without color codes.\n')
+    .helpOption('-h, --help', 'Show help')
+    .action(() => {
+    const input = parseStdinJson();
+    const src = resolveDocSource(input);
+    const width = typeof input.width === 'number' && input.width > 0
+        ? input.width
+        : (process.stdout.columns || 100);
+    const lines = renderMarkdown(src, width);
+    let out = lines.join('\n');
+    if (input.color === false) {
+        // Strip ANSI escape sequences for plain-text consumers.
+        // eslint-disable-next-line no-control-regex
+        out = out.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+    }
+    process.stdout.write(out);
+    if (!out.endsWith('\n'))
+        process.stdout.write('\n');
+    process.exit(0);
+});
+function resolveDocSource(input) {
+    const hasSource = typeof input.source === 'string' && input.source.length > 0;
+    const hasPath = typeof input.path === 'string' && input.path.length > 0;
+    if (hasSource === hasPath) {
+        emitError({
+            error: 'bad_input',
+            message: 'provide exactly one of {source, path}',
+            next: 'stdin like {"source": "..."} or {"path": "/abs/file.md"}',
+        });
+    }
+    if (hasSource)
+        return input.source;
+    const abs = resolve(input.path);
+    if (!existsSync(abs)) {
+        emitError({ error: 'file_not_found', message: `path not found: ${abs}`, next: 'check the path' });
+    }
+    return readFileSync(abs, 'utf-8');
+}
 // ── inbox ─────────────────────────────────────────────────────────────────────
 const inboxCmd = program.command('inbox').description('Browse and resolve pending interactions across root dirs.');
 inboxCmd

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

@@ -6,6 +6,12 @@ export declare const interactionOptionSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     shortcut: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const preAnswerSchema: z.ZodObject<{
+    selectedOptionId: z.ZodOptional<z.ZodString>;
+    selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freetext: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const deckSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodObject<{
@@ -35,6 +41,12 @@ export declare const deckSchema: z.ZodObject<{
             context: "context";
             error: "error";
         }>>;
+        preAnswered: z.ZodOptional<z.ZodObject<{
+            selectedOptionId: z.ZodOptional<z.ZodString>;
+            selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            freetext: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function inlineBodyPath(deckPath: string, bodyPath: string): string;

package/dist/inbox/deck-schema.js

@@ -10,6 +10,12 @@ export const interactionOptionSchema = z.object({
     description: z.string().optional(),
     shortcut: z.string().optional(),
 });
+export const preAnswerSchema = z.object({
+    selectedOptionId: z.string().optional(),
+    selectedOptionIds: z.array(z.string()).optional(),
+    freetext: z.string().optional(),
+    label: z.string().optional(),
+});
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
     title: z.string().min(1, { error: 'title must be non-empty' }),
@@ -21,6 +27,7 @@ const interactionSchema = z.object({
     allowFreetext: z.boolean().optional(),
     freetextLabel: z.string().optional(),
     kind: z.enum(['notify', 'validation', 'decision', 'context', 'error']).optional(),
+    preAnswered: preAnswerSchema.optional(),
 });
 const deckSourceSchema = z.object({
     sessionName: z.string().optional(),

package/dist/tui/app.d.ts

@@ -18,11 +18,18 @@ export interface ResolveDirOpts {
  * with skips) write `<dir>/response.json` atomically and drop the progress
  * file. A hard process kill leaves `progress.json` for a later resume —
  * `tryResume` (unchanged logic) reads the new dir-derived path.
+ *
+ * While the panel is mounted, `<dir>/deck.json` is polled for changes (an
+ * agent calling `hl deck update`). On a valid rewrite the panel is reloaded
+ * in place via `loadDeck`, so the human's pane reflects the new questions
+ * without a respawn; answers for surviving interaction ids are kept. The
+ * returned `deck` is the one actually answered (post-reload).
  */
 export declare function resolveInteractionDir(dir: string, deck: Deck, opts?: ResolveDirOpts): Promise<{
     responses: InteractionResponse[];
     completedAt: string;
     responsePath: string;
+    deck: Deck;
 }>;
 export declare function launchTui(decisionsPath: string, sessionId?: string): Promise<{
     responses: InteractionResponse[];

package/dist/tui/app.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
@@ -6,7 +6,7 @@ import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { defaultGenerateVisual } from '../visuals/generate.js';
 import { validateDeck } from '../inbox/deck-schema.js';
-import { progressPath as progressPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
+import { progressPath as progressPathFor, deckPath as deckPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
 /** Validate an arbitrary parsed value as a Deck. Delegates to the canonical
  * Zod validator in `inbox/deck-schema.ts` (the single source of truth shared
  * with sisyphus). Kept exported for back-compat. */
@@ -18,12 +18,36 @@ function buildInitialState(deck) {
     // Single-question decks skip the overview list — there's nothing to overview,
     // and overview hides the option hotkeys so users press 'y' and nothing happens.
     const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
+    const responses = new Map();
+    const preAnsweredIds = new Set();
+    // Seed responses + preAnsweredIds from any `preAnswered` field. The seeded
+    // response counts as answered for navigation/auto-advance, but is rendered
+    // distinctly so the human knows it carried over. `tryResume` runs after and
+    // takes priority — mid-deck progress should not be overwritten by defaults.
+    for (const interaction of deck.interactions) {
+        const pa = interaction.preAnswered;
+        if (pa === undefined)
+            continue;
+        const response = { id: interaction.id };
+        if (pa.selectedOptionId !== undefined)
+            response.selectedOptionId = pa.selectedOptionId;
+        if (pa.selectedOptionIds !== undefined)
+            response.selectedOptionIds = [...pa.selectedOptionIds];
+        if (pa.freetext !== undefined)
+            response.freetext = pa.freetext;
+        responses.set(interaction.id, response);
+        preAnsweredIds.add(interaction.id);
+    }
+    // Start cursor on the first unanswered interaction — humans land where they
+    // need to act. If every interaction is pre-answered, fall back to index 0.
+    const firstUnanswered = deck.interactions.findIndex((i) => !responses.has(i.id));
     return {
         phase: initialPhase,
-        currentIndex: 0,
+        currentIndex: firstUnanswered >= 0 ? firstUnanswered : 0,
         interactions: deck.interactions,
-        responses: new Map(),
+        responses,
         visuals: new Map(),
+        preAnsweredIds,
         inputMode: null,
         selectedAction: 0,
         detailExpanded: false,
@@ -179,6 +203,11 @@ export function mountPanel(opts) {
                 return false;
             return internals.state.inputMode === null;
         },
+        atDeckTop() {
+            if (!internals.mounted)
+                return true;
+            return internals.state.phase === 'overview' && internals.state.inputMode === null;
+        },
     };
 }
 /**
@@ -187,6 +216,12 @@ export function mountPanel(opts) {
  * with skips) write `<dir>/response.json` atomically and drop the progress
  * file. A hard process kill leaves `progress.json` for a later resume —
  * `tryResume` (unchanged logic) reads the new dir-derived path.
+ *
+ * While the panel is mounted, `<dir>/deck.json` is polled for changes (an
+ * agent calling `hl deck update`). On a valid rewrite the panel is reloaded
+ * in place via `loadDeck`, so the human's pane reflects the new questions
+ * without a respawn; answers for surviving interaction ids are kept. The
+ * returned `deck` is the one actually answered (post-reload).
  */
 export async function resolveInteractionDir(dir, deck, opts = {}) {
     let conversationContext = '';
@@ -212,6 +247,12 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
         let prevFrameLocal = [];
         let lastResponses = [];
         let onData;
+        // The deck the human is actually answering. An agent may replace it
+        // mid-flight via `hl deck update` (atomic deck.json rewrite); the poller
+        // below reloads the panel in place and tracks the live deck here so the
+        // returned envelope/summary describes what was answered, not the kickoff.
+        let currentDeck = deck;
+        let deckWatch = null;
         const flushHost = (lines) => {
             const { rows: currentRows } = getTerminalSize();
             const { writes, nextPrevFrame } = diffFrame(prevFrameLocal, lines, currentRows);
@@ -222,6 +263,10 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             prevFrameLocal = nextPrevFrame;
         };
         const finalize = (responses) => {
+            if (deckWatch !== null) {
+                clearInterval(deckWatch);
+                deckWatch = null;
+            }
             restoreTerminal();
             process.stdin.removeListener('data', onData);
             panel?.unmount();
@@ -229,7 +274,7 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             // Resolved supersedes in-progress: write response.json, drop progress.json.
             const rp = writeResponse(dir, responses, completedAt);
             clearProgress(dir);
-            resolve({ responses, completedAt, responsePath: rp });
+            resolve({ responses, completedAt, responsePath: rp, deck: currentDeck });
         };
         panel = mountPanel({
             deck,
@@ -248,6 +293,49 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             },
         });
         flushHost(panel.render());
+        // ── Live deck reload ──────────────────────────────────────────────────
+        // Poll deck.json mtime (cheap stat; full read only on change). atomicWrite
+        // does write-tmp + rename, so stat/read always see a whole file — no
+        // fs.watch rename flakiness. The TUI never writes deck.json, so there is
+        // no feedback loop. A structurally identical rewrite is ignored so a
+        // no-op touch never disrupts the human mid-answer.
+        const deckFile = deckPathFor(dir);
+        const deckMtime = () => {
+            try {
+                return statSync(deckFile).mtimeMs;
+            }
+            catch {
+                return 0;
+            }
+        };
+        let lastDeckMtime = deckMtime();
+        let lastDeckJson = JSON.stringify(currentDeck);
+        deckWatch = setInterval(() => {
+            if (panel === null)
+                return;
+            const m = deckMtime();
+            if (m === 0 || m === lastDeckMtime)
+                return;
+            lastDeckMtime = m;
+            let nextDeck;
+            try {
+                const parsed = JSON.parse(readFileSync(deckFile, 'utf8'));
+                nextDeck = validateDeck(parsed);
+            }
+            catch {
+                // Mid-rename, invalid, or rejected by schema: keep the live deck,
+                // retry on the next tick. `hl deck update` validates before writing,
+                // so a persistently bad file is an out-of-band edit, not our concern.
+                return;
+            }
+            const nextJson = JSON.stringify(nextDeck);
+            if (nextJson === lastDeckJson)
+                return; // touch / identical content
+            lastDeckJson = nextJson;
+            currentDeck = nextDeck;
+            panel.loadDeck(nextDeck, { progressPath: progressPathFor(dir) });
+            flushHost(panel.render());
+        }, 500);
         onData = (data) => {
             const { input: inp, key } = parseKeypress(data);
             panel.handleKey(inp, key);

package/dist/tui/input.js

@@ -117,7 +117,8 @@ function handleItemReview(input, key, state, render) {
         render();
         return;
     }
-    if (input === 'q') {
+    // q / Esc step back to the deck overview (one level up from a card).
+    if (input === 'q' || key.escape) {
         state.phase = 'overview';
         render();
         return;
@@ -172,7 +173,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
             return;
         }
         submitOption(state, interaction, matched.id, undefined);
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
         render();
         return;
     }
@@ -203,13 +204,13 @@ function handleInteractionAction(input, key, state, interaction, render) {
     if (key.return && state.selectedAction < opts.length) {
         if (interaction.multiSelect) {
             commitMulti(state, interaction);
-            advanceItem(state, 1);
+            advanceToNextUnanswered(state);
             render();
             return;
         }
         const o = opts[state.selectedAction];
         submitOption(state, interaction, o.id, undefined);
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
         render();
         return;
     }
@@ -257,7 +258,12 @@ function handleInputMode(input, key, state, render) {
             submitOption(state, interaction, attached, mode.buffer);
         }
         state.inputMode = null;
-        advanceItem(state, 1);
+        advanceToNextUnanswered(state);
+        render();
+        return;
+    }
+    if (key.backspace && key.meta) {
+        mode.buffer = deleteWordBack(mode.buffer);
         render();
         return;
     }
@@ -277,11 +283,23 @@ function handleInputMode(input, key, state, render) {
         render();
     }
 }
+function deleteWordBack(buffer) {
+    const chars = [...buffer];
+    while (chars.length > 0 && /\s/.test(chars[chars.length - 1]))
+        chars.pop();
+    while (chars.length > 0 && !/\s/.test(chars[chars.length - 1]))
+        chars.pop();
+    return chars.join('');
+}
 // ── Final ────────────────────────────────────────────────────────────────────
 function handleFinal(input, key, state, render, exit) {
     if (key.return) {
         exit();
     }
+    else if (key.escape) {
+        state.phase = 'overview';
+        render();
+    }
     else if (input === 'p') {
         state.phase = 'item-review';
         state.currentIndex = state.interactions.length - 1;
@@ -302,6 +320,27 @@ function advanceItem(state, direction) {
     state.detailExpanded = false;
     state.scrollOffset = 0;
 }
+/**
+ * Move to the next interaction WITHOUT a response, falling through to the
+ * final phase if every following interaction is already answered (whether
+ * user-answered or `preAnswered`-seeded). Used by all post-submit advance
+ * sites so the human flies through pre-approved items by hitting Enter; raw
+ * `n`/`p` still step one at a time via `advanceItem`.
+ */
+function advanceToNextUnanswered(state) {
+    let next = state.currentIndex + 1;
+    while (next < state.interactions.length && state.responses.has(state.interactions[next].id)) {
+        next++;
+    }
+    if (next >= state.interactions.length) {
+        state.phase = 'final';
+        return;
+    }
+    state.currentIndex = next;
+    state.selectedAction = 0;
+    state.detailExpanded = false;
+    state.scrollOffset = 0;
+}
 function actionCount(interaction) {
     return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);
 }
@@ -312,6 +351,9 @@ function submitOption(state, interaction, selectedOptionId, freetext) {
     if (freetext !== undefined)
         response.freetext = freetext;
     state.responses.set(interaction.id, response);
+    // Explicit user submission overrides any preAnswered seed — flip the icon
+    // from "previously answered" to user-answered.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
 // ── Multi-select ─────────────────────────────────────────────────────────────
@@ -328,6 +370,8 @@ function toggleMulti(state, interaction, optionId) {
     if (existing?.freetext !== undefined)
         response.freetext = existing.freetext;
     state.responses.set(interaction.id, response);
+    // User edited the checked set — no longer a passive carry-over.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }
 /** Ensure a (possibly empty) response exists so the interaction counts as
@@ -342,5 +386,7 @@ function commitMulti(state, interaction, freetext) {
     if (ft !== undefined)
         response.freetext = ft;
     state.responses.set(interaction.id, response);
+    // Explicit confirm overrides any preAnswered seed.
+    state.preAnsweredIds.delete(interaction.id);
     state.persist?.();
 }

package/dist/tui/render.js

@@ -166,7 +166,10 @@ export function renderOverview(state, cols, rows) {
     for (let i = 0; i < state.interactions.length; i++) {
         const interaction = state.interactions[i];
         const response = state.responses.get(interaction.id);
-        const icon = response ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
+        const preAnswered = state.preAnsweredIds.has(interaction.id);
+        const icon = response
+            ? (preAnswered ? `${DIM}◆${RESET}` : `${GREEN}✓${RESET}`)
+            : `${DIM}○${RESET}`;
         const label = singleLine(interaction.title);
         const cursor = i === state.currentIndex ? `${CYAN}▸${RESET} ` : '  ';
         const labelMax = Math.max(10, cols - 16);
@@ -238,6 +241,16 @@ export function renderItemReview(state, cols, rows) {
             preLines.push(`  ${DIM}${line}${RESET}`);
         }
     }
+    // "Previously answered" marker — shown only while the seed is intact (no user
+    // override yet). The label comes from preAnswered.label so callers can be
+    // domain-specific ("Previously approved", "Carried over from prior pass").
+    if (state.preAnsweredIds.has(interaction.id)) {
+        const customLabel = interaction.preAnswered !== undefined ? interaction.preAnswered.label : undefined;
+        const label = typeof customLabel === 'string' && customLabel.length > 0
+            ? customLabel
+            : 'Previously answered';
+        preLines.push(`  ${DIM}${ITALIC}◆ ${sanitize(label)} — press n/p to review, or any option to override${RESET}`);
+    }
     // Body: rendered question body + expanded visual block (scrollable)
     const bodyLines = [];
     if (interaction.body) {
@@ -425,7 +438,10 @@ export function renderFinal(state, cols, rows) {
     const questionRows = [];
     for (const interaction of state.interactions) {
         const response = state.responses.get(interaction.id);
-        const icon = response ? `${GREEN}✓${RESET}` : `${YELLOW}○${RESET}`;
+        const preAnswered = state.preAnsweredIds.has(interaction.id);
+        const icon = response
+            ? (preAnswered ? `${DIM}◆${RESET}` : `${GREEN}✓${RESET}`)
+            : `${YELLOW}○${RESET}`;
         const label = singleLine(interaction.title);
         questionRows.push(`  ${icon} ${truncate(label, Math.max(10, maxW - 4))}`);
         if (response) {

package/dist/tui/terminal.d.ts

@@ -4,6 +4,7 @@ export interface Key {
     return: boolean;
     escape: boolean;
     ctrl: boolean;
+    meta: boolean;
     tab: boolean;
     backspace: boolean;
 }

package/dist/tui/terminal.js

@@ -5,6 +5,7 @@ function emptyKey() {
         return: false,
         escape: false,
         ctrl: false,
+        meta: false,
         tab: false,
         backspace: false,
     };
@@ -24,6 +25,13 @@ export function parseKeypress(data) {
         key.return = true;
         return { input: '', key };
     }
+    // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
+    // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
+    if (str === '\x1b\x7f' || str === '\x1b\b') {
+        key.meta = true;
+        key.backspace = true;
+        return { input: '', key };
+    }
     if (str === '\x1b') {
         key.escape = true;
         return { input: '', key };

package/dist/types.d.ts

@@ -6,6 +6,23 @@ export interface InteractionOption {
     description?: string;
     shortcut?: string;
 }
+/**
+ * Seed an interaction with an answer the caller already has on hand — e.g. a
+ * prior approval the human shouldn't have to re-confirm. When present, the
+ * panel: (a) populates `responses[id]` from these fields at mount, (b) renders
+ * a distinct "previously answered" marker in overview/final and labels it in
+ * item-review, and (c) skips past the interaction on post-submit auto-advance.
+ * The human can still navigate to it with `n`/`p` and override the seeded
+ * answer — once they do, it renders as user-answered.
+ */
+export interface InteractionPreAnswer {
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    /** One-line marker shown in the answered chrome (e.g. "Previously approved").
+     *  Defaults to "Previously answered" when omitted. */
+    label?: string;
+}
 export interface Interaction {
     id: string;
     title: string;
@@ -19,6 +36,7 @@ export interface Interaction {
     allowFreetext?: boolean;
     freetextLabel?: string;
     kind?: InteractionKind;
+    preAnswered?: InteractionPreAnswer;
 }
 export interface InteractionResponse {
     id: string;
@@ -84,6 +102,10 @@ export interface TuiState {
     interactions: Interaction[];
     responses: Map<string, InteractionResponse>;
     visuals: Map<string, VisualBlock>;
+    /** Ids of interactions whose response was seeded from `Interaction.preAnswered`
+     *  and which the human has not yet overridden. Drives the distinct
+     *  "previously answered" rendering and the skip-on-advance behavior. */
+    preAnsweredIds: Set<string>;
     inputMode: InputMode;
     selectedAction: number;
     detailExpanded: boolean;
@@ -156,4 +178,10 @@ export interface MountedPanel {
         progressPath?: string;
     }): void;
     canAcceptHostKeys(): boolean;
+    /**
+     * True when the deck is at its top level: overview phase with no active
+     * comment/freetext input. A host that owns mount/unmount uses this to decide
+     * whether Esc should step back inside the deck (false) or tear it down (true).
+     */
+    atDeckTop(): boolean;
 }

package/package.json

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