@crouton-kit/humanloop 0.3.22 → 0.3.23

package/dist/api.js

@@ -7,52 +7,11 @@ import { pickFromInbox } from './inbox/tui.js';
 import { deckPath, atomicWriteJson, readJson, stampCanvasNode } from './inbox/convention.js';
 import { getTerminalSize } from './tui/terminal.js';
 import { notifyDeck } from './inbox/deck-factories.js';
+import { buildSummary } from './summary.js';
 const RESPONSE_SCHEMA_ID = 'humanloop.response/v2';
 function managedDir() {
     return mkdtempSync(join(tmpdir(), 'hl-ix-'));
 }
-/**
- * Deterministic, no-LLM resolution summary — one line per answered
- * interaction: `"<title>: <option label>[ — <freetext>]"`.
- */
-function buildSummary(deck, responses) {
-    const byId = new Map(responses.map((r) => [r.id, r]));
-    const lines = [];
-    for (const it of deck.interactions) {
-        const r = byId.get(it.id);
-        if (r === undefined)
-            continue;
-        const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
-        let picked;
-        if (r.selectedOptionIds !== undefined) {
-            const oc = r.optionComments;
-            const parts = r.selectedOptionIds
-                .map((id) => it.options.find((o) => o.id === id))
-                .filter((o) => o !== undefined)
-                .map((o) => {
-                const note = oc !== undefined ? oc[o.id] : undefined;
-                return typeof note === 'string' && note.length > 0
-                    ? `${o.label} ("${note}")`
-                    : o.label;
-            });
-            picked = parts.length > 0 ? parts.join(', ') : undefined;
-        }
-        else if (r.selectedOptionId !== undefined) {
-            picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;
-        }
-        let val;
-        if (picked !== undefined && ft !== undefined)
-            val = `${picked} — ${ft}`;
-        else if (picked !== undefined)
-            val = picked;
-        else if (ft !== undefined)
-            val = ft;
-        else
-            val = '(skipped)';
-        lines.push(`${it.title}: ${val}`);
-    }
-    return lines.join('\n');
-}
 /**
  * Resolve a deck against an interaction directory and return the resolution
  * envelope. Writes `<dir>/deck.json` (the request, per the convention) and,

package/dist/cli.js

@@ -12,6 +12,7 @@ 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';
 // ── Version ───────────────────────────────────────────────────────────────────
 const HL_VERSION = '0.2.1';
 function emitError(err, exitCode = 1) {
@@ -898,8 +899,15 @@ function tryReadJobResult(dir, kind) {
         if (!raw)
             return null;
         const dk = readJson(deckPath(dir));
+        // Prefer the summary persisted at write time. Legacy response.json files
+        // (written before the summary field existed) lack it — rebuild it from the
+        // deck if it's still on disk, else fall back to ''.
+        let summary = typeof raw.summary === 'string' ? raw.summary : '';
+        if (summary === '' && dk) {
+            summary = buildSummary(dk, raw.responses);
+        }
         return {
-            summary: '',
+            summary,
             responsePath: rp,
             schema: 'humanloop.response/v2',
             responses: raw.responses,

package/dist/inbox/convention.d.ts

@@ -21,6 +21,6 @@ export declare function isClaimed(dir: string): boolean;
 export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 export declare function readJson<T>(path: string): T | null;
-export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string): string;
+export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;

package/dist/inbox/convention.js

@@ -1,5 +1,6 @@
 import { existsSync, statSync, writeFileSync, renameSync, readFileSync, unlinkSync, mkdirSync } from 'fs';
 import { dirname } from 'path';
+import { buildSummary } from '../summary.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
 export function deckPath(dir) {
     return `${dir}/deck.json`;
@@ -81,9 +82,15 @@ export function readJson(path) {
     }
 }
 // ── High-level write helpers ──────────────────────────────────────────────────
-export function writeResponse(dir, responses, completedAt) {
+export function writeResponse(dir, responses, completedAt, deck) {
     const p = responsePath(dir);
-    atomicWriteJson(p, { responses, completedAt });
+    // Persist the deterministic summary alongside the raw responses so
+    // `hl job result` can return a populated summary without re-deriving it (or
+    // silently emitting ''). When the deck is known at write time we compute it
+    // here; the deck is deterministic input so this never diverges from ask()'s
+    // envelope summary.
+    const summary = deck !== undefined ? buildSummary(deck, responses) : '';
+    atomicWriteJson(p, { responses, completedAt, summary });
     return p;
 }
 export function writeProgress(dir, responses) {

package/dist/inbox/tui.js

@@ -1,16 +1,7 @@
-import stringWidth from 'string-width';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize, } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
+import { RESET, BOLD, DIM, ITALIC, CYAN, RED, GRAY, YELLOW, truncateRow } from '../tui/ansi.js';
 // ── ANSI helpers (local to this module) ──────────────────────────────────────
-const ESC = '\x1b[';
-const RESET = `${ESC}0m`;
-const BOLD = `${ESC}1m`;
-const DIM = `${ESC}2m`;
-const ITALIC = `${ESC}3m`;
-const CYAN = `${ESC}36m`;
-const RED = `${ESC}31m`;
-const GRAY = `${ESC}90m`;
-const YELLOW = `${ESC}33m`;
 function ansiColor(text, color) {
     switch (color) {
         case 'gray': return `${GRAY}${text}${RESET}`;
@@ -44,26 +35,6 @@ export function formatTimeAgo(iso) {
         return `${minutes}m ago`;
     return 'just now';
 }
-// ── truncate (ported from sisyphus src/tui/lib/format.ts:19-37) ──────────────
-function truncate(text, max) {
-    const clean = text.replace(/\n/g, ' ').replace(/✅/g, '✓').replace(/❌/g, '✗').replace(/\p{Emoji_Presentation}/gu, '');
-    if (max < 4)
-        return clean.slice(0, max);
-    const w = stringWidth(clean);
-    if (w <= max)
-        return clean;
-    let result = clean;
-    while (stringWidth(result) > max - 1 && result.length > 0) {
-        const cut = result.lastIndexOf(' ', result.length - 2);
-        if (cut > max * 0.4) {
-            result = result.slice(0, cut);
-        }
-        else {
-            result = result.slice(0, result.length - 1);
-        }
-    }
-    return result + '…';
-}
 // ── buildInboxLines ───────────────────────────────────────────────────────────
 export function buildInboxLines(items, width, selectedIndex) {
     const lines = [];
@@ -93,11 +64,11 @@ export function buildInboxLines(items, width, selectedIndex) {
         else {
             row += ' ';
         }
-        row += `${BOLD}${truncate(titleText, maxTitle)}${RESET}`;
+        row += `${BOLD}${truncateRow(titleText, maxTitle)}${RESET}`;
         row += `  ${DIM}${blocked}${RESET}`;
         lines.push(row);
         if (item.subtitle) {
-            lines.push(`      ${DIM}${truncate(item.subtitle, contentWidth - 6)}${RESET}`);
+            lines.push(`      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`);
         }
     }
     return lines;

package/dist/summary.d.ts

@@ -0,0 +1,9 @@
+import type { Deck, InteractionResponse } from './types.js';
+/**
+ * Deterministic, no-LLM resolution summary — one line per answered
+ * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
+ * (envelope summary), `writeResponse` (persisted into response.json at write
+ * time), and `hl job result` (fallback rebuild for legacy response.json files
+ * written before the summary field existed).
+ */
+export declare function buildSummary(deck: Deck, responses: InteractionResponse[]): string;

package/dist/summary.js

@@ -0,0 +1,45 @@
+/**
+ * Deterministic, no-LLM resolution summary — one line per answered
+ * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
+ * (envelope summary), `writeResponse` (persisted into response.json at write
+ * time), and `hl job result` (fallback rebuild for legacy response.json files
+ * written before the summary field existed).
+ */
+export function buildSummary(deck, responses) {
+    const byId = new Map(responses.map((r) => [r.id, r]));
+    const lines = [];
+    for (const it of deck.interactions) {
+        const r = byId.get(it.id);
+        if (r === undefined)
+            continue;
+        const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
+        let picked;
+        if (r.selectedOptionIds !== undefined) {
+            const oc = r.optionComments;
+            const parts = r.selectedOptionIds
+                .map((id) => it.options.find((o) => o.id === id))
+                .filter((o) => o !== undefined)
+                .map((o) => {
+                const note = oc !== undefined ? oc[o.id] : undefined;
+                return typeof note === 'string' && note.length > 0
+                    ? `${o.label} ("${note}")`
+                    : o.label;
+            });
+            picked = parts.length > 0 ? parts.join(', ') : undefined;
+        }
+        else if (r.selectedOptionId !== undefined) {
+            picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;
+        }
+        let val;
+        if (picked !== undefined && ft !== undefined)
+            val = `${picked} — ${ft}`;
+        else if (picked !== undefined)
+            val = picked;
+        else if (ft !== undefined)
+            val = ft;
+        else
+            val = '(skipped)';
+        lines.push(`${it.title}: ${val}`);
+    }
+    return lines.join('\n');
+}

package/dist/tui/ansi.d.ts

@@ -0,0 +1,43 @@
+export declare const ESC = "\u001B[";
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const ITALIC = "\u001B[3m";
+export declare const RED = "\u001B[31m";
+export declare const GREEN = "\u001B[32m";
+export declare const YELLOW = "\u001B[33m";
+export declare const CYAN = "\u001B[36m";
+export declare const GRAY = "\u001B[90m";
+export declare const REVERSE = "\u001B[7m";
+export declare function sanitize(text: string): string;
+export declare function singleLine(text: string): string;
+export declare function hline(width: number, char?: string): string;
+export declare function padRight(text: string, width: number): string;
+/** Char-based width truncation with a trailing ellipsis. The canonical deck
+ *  renderer variant. */
+export declare function truncate(text: string, maxWidth: number): string;
+/** Word-aware truncation that also flattens newlines and strips decorative
+ *  emoji — tuned for dense inbox rows (ported from sisyphus format.ts). Kept
+ *  distinct from `truncate` because those two surfaces want different behavior. */
+export declare function truncateRow(text: string, max: number): string;
+/** Word-wrap on whitespace; splits on `\n` into separate paragraphs. */
+export declare function wrap(text: string, maxWidth: number): string[];
+/** Hard character wrap that ignores word boundaries; splits on `\n`. Used for
+ *  free-form input buffers where every character (including runs without
+ *  spaces) must stay on screen. */
+export declare function hardWrap(text: string, maxWidth: number): string[];
+/**
+ * Pad each non-empty line with leading spaces to horizontally center the
+ * `contentWidth`-wide block within `cols`. Wide terminals get breathing room;
+ * narrow panes skip centering. Empty lines stay empty so frame diffing keeps
+ * them as cheap no-ops.
+ */
+export declare function centerHorizontal(lines: string[], cols: number, contentWidth: number): string[];
+/**
+ * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
+ * escape sequences through untouched. Every line written to the terminal must
+ * fit within the columns, or it physically wraps onto the next row — which
+ * breaks diffFrame's one-logical-line-per-row model and strands spillover text
+ * on rows the differ believes are empty (so it never erases them).
+ */
+export declare function clipLine(line: string, maxWidth: number): string;

package/dist/tui/ansi.js

@@ -0,0 +1,210 @@
+import stringWidth from 'string-width';
+// ── ANSI escape constants ─────────────────────────────────────────────────────
+// The single home for these — both the deck renderer (render.ts) and the inbox
+// picker (inbox/tui.ts) import from here rather than keeping their own copies.
+export const ESC = '\x1b[';
+export const RESET = `${ESC}0m`;
+export const BOLD = `${ESC}1m`;
+export const DIM = `${ESC}2m`;
+export const ITALIC = `${ESC}3m`;
+export const RED = `${ESC}31m`;
+export const GREEN = `${ESC}32m`;
+export const YELLOW = `${ESC}33m`;
+export const CYAN = `${ESC}36m`;
+export const GRAY = `${ESC}90m`;
+export const REVERSE = `${ESC}7m`;
+// ── Text helpers ──────────────────────────────────────────────────────────────
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+export function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+export function singleLine(text) {
+    return sanitize(text).replace(/\s+/g, ' ').trim();
+}
+export function hline(width, char = '─') {
+    if (width < 1)
+        return '';
+    return char.repeat(width);
+}
+export function padRight(text, width) {
+    const w = stringWidth(text);
+    if (w >= width)
+        return text;
+    return text + ' '.repeat(width - w);
+}
+/** Char-based width truncation with a trailing ellipsis. The canonical deck
+ *  renderer variant. */
+export function truncate(text, maxWidth) {
+    if (maxWidth < 1)
+        return '';
+    if (stringWidth(text) <= maxWidth)
+        return text;
+    const chars = [...text];
+    let w = 0;
+    let out = '';
+    for (const ch of chars) {
+        const cw = stringWidth(ch);
+        if (w + cw + 1 > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    return out + '…';
+}
+/** Word-aware truncation that also flattens newlines and strips decorative
+ *  emoji — tuned for dense inbox rows (ported from sisyphus format.ts). Kept
+ *  distinct from `truncate` because those two surfaces want different behavior. */
+export function truncateRow(text, max) {
+    const clean = text.replace(/\n/g, ' ').replace(/✅/g, '✓').replace(/❌/g, '✗').replace(/\p{Emoji_Presentation}/gu, '');
+    if (max < 4)
+        return clean.slice(0, max);
+    const w = stringWidth(clean);
+    if (w <= max)
+        return clean;
+    let result = clean;
+    while (stringWidth(result) > max - 1 && result.length > 0) {
+        const cut = result.lastIndexOf(' ', result.length - 2);
+        if (cut > max * 0.4) {
+            result = result.slice(0, cut);
+        }
+        else {
+            result = result.slice(0, result.length - 1);
+        }
+    }
+    return result + '…';
+}
+function sliceByWidth(s, maxWidth) {
+    let w = 0;
+    let out = '';
+    for (const ch of s) {
+        const cw = stringWidth(ch);
+        if (w + cw > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    if (out === '' && s.length > 0)
+        out = [...s][0];
+    return out;
+}
+/** Word-wrap on whitespace; splits on `\n` into separate paragraphs. */
+export function wrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const out = [];
+    const paragraphs = text.split('\n');
+    for (let p = 0; p < paragraphs.length; p++) {
+        const para = paragraphs[p];
+        if (para === '') {
+            out.push('');
+            continue;
+        }
+        const words = para.split(/[ \t]+/).filter(Boolean);
+        let current = '';
+        for (let word of words) {
+            while (stringWidth(word) > maxWidth) {
+                if (current) {
+                    out.push(current);
+                    current = '';
+                }
+                const piece = sliceByWidth(word, maxWidth);
+                out.push(piece);
+                word = word.slice(piece.length);
+            }
+            const candidate = current ? `${current} ${word}` : word;
+            if (stringWidth(candidate) <= maxWidth) {
+                current = candidate;
+            }
+            else {
+                if (current)
+                    out.push(current);
+                current = word;
+            }
+        }
+        if (current)
+            out.push(current);
+    }
+    return out.length > 0 ? out : [''];
+}
+/** Hard character wrap that ignores word boundaries; splits on `\n`. Used for
+ *  free-form input buffers where every character (including runs without
+ *  spaces) must stay on screen. */
+export function hardWrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const segments = text.split('\n');
+    const out = [];
+    for (const seg of segments) {
+        if (seg.length === 0) {
+            out.push('');
+            continue;
+        }
+        let current = '';
+        let currentW = 0;
+        for (const ch of [...seg]) {
+            const cw = stringWidth(ch);
+            if (currentW + cw > maxWidth) {
+                out.push(current);
+                current = ch;
+                currentW = cw;
+            }
+            else {
+                current += ch;
+                currentW += cw;
+            }
+        }
+        out.push(current);
+    }
+    return out;
+}
+/**
+ * Pad each non-empty line with leading spaces to horizontally center the
+ * `contentWidth`-wide block within `cols`. Wide terminals get breathing room;
+ * narrow panes skip centering. Empty lines stay empty so frame diffing keeps
+ * them as cheap no-ops.
+ */
+export function centerHorizontal(lines, cols, contentWidth) {
+    const extraPad = Math.max(0, Math.floor((cols - contentWidth) / 2));
+    if (extraPad === 0)
+        return lines;
+    const pad = ' '.repeat(extraPad);
+    return lines.map((line) => (line === '' ? '' : pad + line));
+}
+/**
+ * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
+ * escape sequences through untouched. Every line written to the terminal must
+ * fit within the columns, or it physically wraps onto the next row — which
+ * breaks diffFrame's one-logical-line-per-row model and strands spillover text
+ * on rows the differ believes are empty (so it never erases them).
+ */
+export function clipLine(line, maxWidth) {
+    if (maxWidth < 1)
+        return '';
+    if (stringWidth(line) <= maxWidth)
+        return line; // string-width ignores ANSI
+    let out = '';
+    let w = 0;
+    let i = 0;
+    let sawAnsi = false;
+    while (i < line.length) {
+        if (line[i] === '\x1b') {
+            const m = /^\x1b\[[0-9;?]*[a-zA-Z]|^\x1b[@-_]/.exec(line.slice(i));
+            if (m !== null) {
+                out += m[0];
+                i += m[0].length;
+                sawAnsi = true;
+                continue;
+            }
+        }
+        const ch = String.fromCodePoint(line.codePointAt(i));
+        const cw = stringWidth(ch);
+        if (w + cw > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return sawAnsi ? out + RESET : out;
+}

package/dist/tui/app.js

@@ -1,7 +1,10 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
-import { dirname, resolve as resolvePath } from 'node:path';
+import { dirname, resolve as resolvePath, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
-import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
+import { diffFrame, renderOverview, renderItemReview, renderFinal, clampItemReviewScroll } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { defaultGenerateVisual } from '../visuals/generate.js';
@@ -113,12 +116,14 @@ function fireVisuals(internals, interactions) {
             internals.state.visuals.set(interaction.id, r.ok
                 ? { questionId: interaction.id, content: r.ansi, status: 'ready' }
                 : { questionId: interaction.id, content: '', status: 'error' });
+            internals.callbacks.onDirty?.();
         }).catch(() => {
             if (!internals.mounted)
                 return;
             if (!internals.state.interactions.some((x) => x.id === interaction.id))
                 return;
             internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'error' });
+            internals.callbacks.onDirty?.();
         });
     }
 }
@@ -130,7 +135,7 @@ export function mountPanel(opts) {
         mounted: true,
         generateVisual: opts.generateVisual,
         progressPath: opts.progressPath,
-        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit },
+        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty },
     };
     assignShortcuts(internals.state.interactions);
     rebindPersist(internals);
@@ -168,6 +173,11 @@ export function mountPanel(opts) {
                     internals.callbacks.onExit?.();
                 }
             });
+            // Pre-render clamp (input layer): keep scrollOffset within the current
+            // body's bounds so u/d stay responsive. The renderer itself is pure.
+            if (internals.state.phase === 'item-review') {
+                clampItemReviewScroll(internals.state, internals.cols, internals.rows);
+            }
         },
         render() {
             if (!internals.mounted)
@@ -177,6 +187,10 @@ export function mountPanel(opts) {
         handleResize(cols, rows) {
             internals.cols = cols;
             internals.rows = rows;
+            // New dimensions change the scroll bounds — re-clamp before laying out.
+            if (internals.state.phase === 'item-review') {
+                clampItemReviewScroll(internals.state, cols, rows);
+            }
             return renderLines();
         },
         unmount() {
@@ -208,6 +222,17 @@ export function mountPanel(opts) {
                 return true;
             return internals.state.phase === 'overview' && internals.state.inputMode === null;
         },
+        getInputBuffer() {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return undefined;
+            return internals.state.inputMode.buffer;
+        },
+        setInputBuffer(text) {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return;
+            internals.state.inputMode.buffer = text;
+            internals.state.inputMode.cursor = [...text].length;
+        },
     };
 }
 /**
@@ -285,7 +310,7 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             panel?.unmount();
             const completedAt = new Date().toISOString();
             // Resolved supersedes in-progress: write response.json, drop progress.json.
-            const rp = writeResponse(dir, responses, completedAt);
+            const rp = writeResponse(dir, responses, completedAt, currentDeck);
             clearProgress(dir);
             resolve({ responses, completedAt, responsePath: rp, deck: currentDeck });
         };
@@ -304,6 +329,12 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             onExit: () => {
                 finalize(lastResponses);
             },
+            // Async visual finished loading between keystrokes — repaint so the
+            // "loading context..." placeholder is replaced immediately.
+            onDirty: () => {
+                if (panel !== null)
+                    flushHost(panel.render());
+            },
         });
         flushHost(panel.render());
         // ── Live deck reload ──────────────────────────────────────────────────
@@ -349,8 +380,85 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             panel.loadDeck(nextDeck, { progressPath: progressPathFor(dir) });
             flushHost(panel.render());
         }, 500);
+        // $EDITOR escape hatch (ctrl+o): the host owns the stdin listener + raw
+        // mode, so it — not handleInputMode — is where the editor round-trip has
+        // to live. Detected here before delegating to the panel; only acts while
+        // an input-mode buffer exists (panel.getInputBuffer() undefined otherwise).
+        const runEditorEscapeHatch = (buffer) => {
+            if (panel === null)
+                return;
+            process.stdin.removeListener('data', onData);
+            process.stdout.removeListener('resize', onResize);
+            const tmpFile = join(tmpdir(), `hl-input-${randomUUID()}.txt`);
+            const editor = process.env.EDITOR || 'vi';
+            let next = buffer;
+            let errorMessage = null;
+            // Everything from suspending the TUI through the editor round-trip can
+            // throw (tmpfile write, spawn, readback) — a tmpdir write failure alone
+            // (e.g. /tmp full) used to escape with the listeners detached and the
+            // real terminal never restored. The try/finally below guarantees the
+            // finally branch — tmpfile cleanup, TUI restore, listener re-attach,
+            // resize-aware redraw — runs on every path, success or failure.
+            try {
+                restoreTerminal();
+                writeFileSync(tmpFile, buffer);
+                const result = spawnSync(editor, [tmpFile], { stdio: 'inherit' });
+                if (result.error) {
+                    errorMessage = `$EDITOR ("${editor}") failed to launch: ${result.error.message}`;
+                }
+                else if (result.signal !== null) {
+                    errorMessage = `$EDITOR ("${editor}") was killed by signal ${result.signal}`;
+                }
+                else if (result.status !== 0) {
+                    errorMessage = `$EDITOR ("${editor}") exited with status ${result.status}`;
+                }
+                else {
+                    let read = readFileSync(tmpFile, 'utf8');
+                    // Editors conventionally append a trailing newline on save; strip
+                    // exactly one so a round-trip that added nothing doesn't grow the
+                    // buffer by a blank line.
+                    if (read.endsWith('\n') && !buffer.endsWith('\n'))
+                        read = read.slice(0, -1);
+                    next = read;
+                }
+            }
+            catch (err) {
+                errorMessage = `$EDITOR round-trip failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            finally {
+                try {
+                    unlinkSync(tmpFile);
+                }
+                catch { /* best-effort cleanup — may never have been created */ }
+                setupTerminal();
+                process.stdin.on('data', onData);
+                process.stdout.on('resize', onResize);
+                // On any failure the original buffer is kept untouched. Re-sample the
+                // terminal size (it may have changed while the editor had it) so the
+                // post-editor redraw lays out for the CURRENT dimensions rather than
+                // the panel's stale cols/rows, same as the live resize listener does.
+                panel.setInputBuffer(errorMessage === null ? next : buffer);
+                const { cols: c, rows: r } = getTerminalSize();
+                const lines = panel.handleResize(c, r);
+                if (errorMessage !== null) {
+                    while (lines.length < r)
+                        lines.push('');
+                    lines[r - 1] = `  ${errorMessage}`.slice(0, c);
+                }
+                prevFrameLocal = [];
+                process.stdout.write('\x1b[2J\x1b[H');
+                flushHost(lines);
+            }
+        };
         onData = (data) => {
             const { input: inp, key } = parseKeypress(data);
+            if (key.ctrl && inp === 'o') {
+                const buf = panel.getInputBuffer();
+                if (buf !== undefined) {
+                    runEditorEscapeHatch(buf);
+                    return;
+                }
+            }
             panel.handleKey(inp, key);
             flushHost(panel.render());
         };