@iseoane/agent-depot 0.6.12 → 0.6.14

package/dist/src/tui/preview-render.js

@@ -0,0 +1,93 @@
+import { commandLine, itemWarnings } from "../preview-model.js";
+import { theme } from "./theme.js";
+export const span = (text, color, bold = false) => bold ? { text, color, bold } : { text, color };
+// Ink drops the height of an empty Text, so a blank separator keeps one space.
+const BLANK = [span(" ", theme.value)];
+export function lineText(line) {
+    return line.map(({ text }) => text).join("");
+}
+export function textLine(text) {
+    return [span(text, theme.value)];
+}
+export function fieldLine(label, value) {
+    return [span(label, theme.field), span(` ${value}`, theme.value)];
+}
+const ROW_INDENT = "   ";
+// The views escape control characters once, as they draw.
+const TERMINAL = { terminal: true };
+// A recipe's manual text can span lines; escaped inside one line, its breaks would show as `\x0a`.
+const LINE_BREAK = /\r\n|\r|\n/u;
+function rowLines(row) {
+    switch (row.kind) {
+        case "field": {
+            const [first = "", ...rest] = row.value.split(LINE_BREAK);
+            return [
+                [span(`${ROW_INDENT}${row.label}:`, theme.field), ...(first === "" ? [] : [span(` ${first}`, theme.value)])],
+                ...rest.map((line) => [span(`${ROW_INDENT}${line}`, theme.value)]),
+            ];
+        }
+        case "text":
+            return [[span(`${ROW_INDENT}${"  ".repeat(row.indent ?? 0)}${row.text}`, theme.value)]];
+        case "warning":
+            return [[span(`${ROW_INDENT}⚠ ${row.text}`, theme.warning)]];
+        case "command": {
+            const where = [row.executable, row.cwd === undefined ? undefined : `in ${row.cwd}`].filter((part) => part !== undefined);
+            return [
+                [span(`${ROW_INDENT}$ ${commandLine(row.argv, TERMINAL)}`, theme.value)],
+                ...(where.length === 0 ? [] : [[span(`${ROW_INDENT}${where.join(" · ")}`, theme.legend)]]),
+            ];
+        }
+    }
+}
+function itemLines(item) {
+    const title = [span(` ${item.title}`, theme.value, true)];
+    if (item.detail !== undefined)
+        title.push(span(`  ${item.detail}`, theme.legend));
+    if (item.version !== undefined)
+        title.push(span(`  ${item.version.from} → ${item.version.to}`, theme.version));
+    return [title, ...item.rows.flatMap(rowLines)];
+}
+/** One block per step joined by a tree gutter: what the step runs or asks for, then dimmed where it runs. */
+export function stepBlockLines(steps) {
+    return steps.flatMap((step, index) => {
+        const last = index === steps.length - 1;
+        const branch = last ? "└" : index === 0 ? "┌" : "├";
+        const row = (...spans) => [span(last ? "   " : " │ ", theme.field), ...spans];
+        const where = [`in ${step.cwd}`, ...(step.environment ? [`on ${step.environment}`] : [])].join(" · ");
+        return [
+            [span(` ${branch} ${step.step}`, theme.field)],
+            ...(step.argv ? [row(span(`$ ${commandLine(step.argv, TERMINAL)}`, theme.value))] : []),
+            ...(step.manual ? step.manual.split(LINE_BREAK).map((line, position) => row(span(position === 0 ? `Manual: ${line}` : line, theme.value))) : []),
+            ...(step.declaration ? [row(span(step.declaration, theme.value))] : []),
+            ...(step.pattern ? [row(span(`Version pattern: ${step.pattern}`, theme.value))] : []),
+            step.argv && step.executable === undefined
+                ? row(span(`${commandLine(step.argv.slice(0, 1), TERMINAL)} not found in PATH`, theme.warning), span(` · ${where}`, theme.legend))
+                : row(span(step.executable ? `${step.executable} · ${where}` : where, theme.legend)),
+            ...(step.warning ? [row(span(`⚠ ${step.warning}`, theme.warning))] : []),
+        ];
+    });
+}
+/** The document as preview lines: action and counts, context, every warning, one section per type, then the failures. */
+export function renderPreviewDocument(document) {
+    const warnings = [
+        ...document.warnings,
+        ...document.sections.flatMap(({ items }) => items.flatMap((item) => itemWarnings(item).map((warning) => `${item.title}: ${warning}`))),
+    ];
+    const lines = [
+        [span(document.action, theme.accent, true), span(`  ${document.summary}`, theme.legend)],
+        ...document.context.map((line) => [span(` ${line}`, theme.legend)]),
+        ...warnings.map((warning) => [span(` ⚠ ${warning}`, theme.warning)]),
+    ];
+    for (const section of document.sections) {
+        lines.push(BLANK, [span(section.heading, theme.field, true)]);
+        section.items.forEach((item, position) => {
+            if (position > 0)
+                lines.push(BLANK);
+            lines.push(...itemLines(item));
+        });
+    }
+    if (document.failures.length > 0) {
+        lines.push(BLANK, [span("FAILED", theme.error, true)], ...document.failures.map((failure) => [span(` ${failure}`, theme.error)]));
+    }
+    return lines;
+}

package/dist/src/tui/preview-window.js

@@ -1,6 +1,46 @@
+import { useWindowSize } from "ink";
 import stringWidth from "string-width";
 import { headerTabRowCount } from "./header-layout.js";
 const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+// Text shown in the TUI comes from recipes, Sources, Skills and Hosts. Raw, an ESC or carriage return redraws the terminal over the
+// lines under review and a bidi override reorders them; both also change the width the `y` gate was computed for. The zero-width joiner
+// stays because emoji sequences such as a person at a laptop are made with it.
+const UNSAFE_PATTERN = "(?!\\u200D)[\\p{Cc}\\p{Cf}\\u2028\\u2029]";
+const UNSAFE_CHARACTER = new RegExp(UNSAFE_PATTERN, "u");
+// A backslash run before text shaped like an escape we print (`\x1b`, `\u202e`, `\u{1f600}`), or before a character we escape.
+const ESCAPE_TEXT = "x[0-9a-f]{2}|u[0-9a-f]{4}|u\\{[0-9a-f]{1,6}\\}";
+const ESCAPABLE = new RegExp(`(\\\\+)(?:(${ESCAPE_TEXT})|(?=${UNSAFE_PATTERN}))|${UNSAFE_PATTERN}`, "giu");
+/** Whether `escape` (`x1b`, `u202e`, `u{1f600}`) names a character this module would print as an escape. */
+function namesEscapedCharacter(escape) {
+    const code = Number.parseInt(escape.replace(/^[xu]\{?|\}$/gu, ""), 16);
+    return code <= 0x10ffff && UNSAFE_CHARACTER.test(String.fromCodePoint(code));
+}
+/**
+ * `text` with control, format and line-separator characters replaced by visible escapes (`\x1b`, `\u202e`). A backslash run right
+ * before text that looks like one of those escapes is doubled, so a typed `\x1b` cannot pass for a real ESC; other backslashes,
+ * such as those of a Windows path, are left alone. Not idempotent: escape text once, where it enters a view.
+ */
+export function escapeControlText(text) {
+    return text.replace(ESCAPABLE, (match, backslashes, typed) => {
+        if (backslashes !== undefined) {
+            return typed !== undefined && !namesEscapedCharacter(typed) ? match : backslashes.repeat(2) + (typed ?? "");
+        }
+        const code = match.codePointAt(0);
+        const hex = code.toString(16);
+        if (code <= 0xff)
+            return `\\x${hex.padStart(2, "0")}`;
+        return code <= 0xffff ? `\\u${hex.padStart(4, "0")}` : `\\u{${hex}}`;
+    });
+}
+function escapeChrome(chrome) {
+    return {
+        ...chrome,
+        title: escapeControlText(chrome.title),
+        ...(chrome.action === undefined ? {} : { action: escapeControlText(chrome.action) }),
+        ...(chrome.consequence === undefined ? {} : { consequence: escapeControlText(chrome.consequence) }),
+        ...(chrome.cancel === undefined ? {} : { cancel: escapeControlText(chrome.cancel) }),
+    };
+}
 function wrapLine(line, width) {
     const segments = [...graphemes.segment(line)];
     if (segments.length === 0)
@@ -23,29 +63,120 @@ function wrapLine(line, width) {
     wrapped.push({ row, offset: rowOffset });
     return wrapped;
 }
-export function previewViewport(lines, cursor, terminalRows, terminalColumns, chrome = { title: "Confirmation", questions: ["Scroll to end before y; n cancels.", "Confirm? y/n"] }) {
+const MAX_BAR_WIDTH = 12;
+/** The consequence with its `y/n` keys picked out, as in a one-screen confirmation. */
+function consequenceSpans(consequence) {
+    const marker = consequence.indexOf("y/n");
+    if (marker < 0)
+        return [{ text: consequence, role: "consequence" }];
+    return [
+        { text: consequence.slice(0, marker), role: "consequence" },
+        { text: "y", role: "yes" },
+        { text: "/", role: "position" },
+        { text: "n", role: "no" },
+        ...(marker + 3 < consequence.length ? [{ text: consequence.slice(marker + 3), role: "position" }] : []),
+    ];
+}
+/** The progress line and the action line, before wrapping. */
+function footerSpans(state, chrome, width) {
+    const range = (total, start, end) => ` · ${start}–${end} of ${total}`;
+    const position = (cursor, start, end) => `Review ${cursor} of ${state.total}${state.windowed ? range(state.total, start, end) : ""}`;
+    // Sized for the widest position text so the bar, and so the footer height, never changes while paging.
+    const widest = position(state.total, state.total, state.total);
+    const barWidth = Math.min(Math.max(width - stringWidth(`read  100% · ${widest}`), 0), MAX_BAR_WIDTH);
+    const read = state.total === 0 ? 1 : state.end / state.total;
+    const filled = Math.floor(read * barWidth);
+    const bar = barWidth === 0 ? "" : `${"█".repeat(filled)}${"░".repeat(barWidth - filled)} `;
+    const progress = state.reachedEnd
+        ? [{ text: "read ✓", role: "read" }]
+        : [{ text: `read ${bar}${Math.floor(read * 100)}%`, role: "reading" }];
+    progress.push({ text: ` · ${position(state.cursor + 1, state.start + 1, state.end)}`, role: "position" });
+    if (!state.reachedEnd)
+        progress.push({ text: " · arrows/Pg page", role: "position" });
+    else if (chrome.consequence !== undefined)
+        progress.push({ text: " · ", role: "position" }, ...consequenceSpans(chrome.consequence));
+    const actions = chrome.action === undefined ? [] : [{ text: `[y] ${chrome.action}`, role: "action" }, { text: "  ", role: "cancel" }];
+    actions.push({ text: chrome.cancel ?? "[n] cancel", role: "cancel" });
+    return [progress, actions];
+}
+/** The spans covering `length` UTF-16 units of their joined text from `offset`. */
+export function sliceSpans(spans, offset, length) {
+    const end = offset + length;
+    let spanStart = 0;
+    const visible = [];
+    for (const span of spans) {
+        const spanEnd = spanStart + span.text.length;
+        const start = Math.max(offset, spanStart);
+        const stop = Math.min(end, spanEnd);
+        if (start < stop)
+            visible.push({ ...span, text: span.text.slice(start - spanStart, stop - spanStart) });
+        spanStart = spanEnd;
+    }
+    return visible;
+}
+function wrapSpans(spans, width) {
+    return wrapLine(spans.map(({ text }) => text).join(""), width).map(({ row, offset }) => sliceSpans(spans, offset, row.length));
+}
+/** `rows` cut to `maxRows`, the last kept row ending in an ellipsis when something was cut. */
+function clipRows(rows, maxRows) {
+    if (rows.length <= maxRows)
+        return rows;
+    const last = [...rows[maxRows - 1]];
+    const tail = last.pop();
+    const shortened = [...graphemes.segment(tail.text)].slice(0, -1).map(({ segment }) => segment).join("");
+    return [...rows.slice(0, maxRows - 1), [...last, ...(shortened ? [{ ...tail, text: shortened }] : []), { ...tail, text: "…" }]];
+}
+/**
+ * The footer lines wrapped to `width` within `maxRows`: the progress row, which carries the
+ * consequence, keeps all but one row if it needs them, the action row the rest. A cut row ends in an
+ * ellipsis instead of pushing the panel past the terminal.
+ */
+function layoutFooter([progressLine, actionLine], width, maxRows) {
+    const progress = wrapSpans(progressLine, width);
+    const actions = wrapSpans(actionLine, width);
+    const progressRows = Math.min(progress.length, Math.max(maxRows - 1, 1));
+    return [...clipRows(progress, progressRows), ...clipRows(actions, Math.max(maxRows - progressRows, 1))];
+}
+/** Footer rows for the widest position and both reading states, so paging never changes the height. */
+function reservedFooterRows(total, windowed, chrome, width, maxRows) {
+    const widest = { cursor: Math.max(total - 1, 0), start: Math.max(total - 1, 0), end: total, total, windowed };
+    return Math.max(layoutFooter(footerSpans({ ...widest, reachedEnd: false }, chrome, width), width, maxRows).length, layoutFooter(footerSpans({ ...widest, reachedEnd: true }, chrome, width), width, maxRows).length);
+}
+export function previewViewport(rawLines, cursor, terminalRows, terminalColumns, rawChrome) {
+    const lines = rawLines.map(escapeControlText);
+    const chrome = escapeChrome(rawChrome);
     const contentWidth = Math.max(terminalColumns - 8, 1);
     const wrapped = lines.flatMap((line, sourceLine) => wrapLine(line, contentWidth).map(({ row, offset }) => ({ row, sourceLine, offset })));
     const previewRows = wrapped.map(({ row }) => row);
+    const total = previewRows.length;
     const headerRows = headerTabRowCount(contentWidth) + 3;
     const titleRows = wrapLine(chrome.title, contentWidth).length;
-    const questionRows = Math.max(...chrome.questions.map(question => wrapLine(question, contentWidth).length));
-    const panelChromeRows = 2 + titleRows + questionRows + (chrome.footerRows ?? 1);
     const reservedRows = chrome.reservedRows !== undefined && chrome.reservedRows > 0 ? Math.ceil(chrome.reservedRows) : 0;
-    const availableRows = Math.max(terminalRows - headerRows - 1 - panelChromeRows - reservedRows, 1);
-    const height = previewRows.length > availableRows ? Math.max(availableRows - 1, 1) : availableRows;
-    const selected = Math.min(Math.max(cursor, 0), Math.max(previewRows.length - 1, 0));
-    const start = Math.min(Math.max(selected - Math.floor(height / 2), 0), Math.max(previewRows.length - height, 0));
-    const end = Math.min(start + height, previewRows.length);
+    const fixedRows = headerRows + 1 + 2 + titleRows + reservedRows;
+    // At least one preview row stays visible; the footer is cut to what remains.
+    const maxFooterRows = Math.max(terminalRows - fixedRows - 1, 2);
+    const rowsWithFooter = (windowed) => Math.max(terminalRows - fixedRows - reservedFooterRows(total, windowed, chrome, contentWidth, maxFooterRows), 1);
+    const windowed = total > rowsWithFooter(false);
+    const height = rowsWithFooter(windowed);
+    const selected = Math.min(Math.max(cursor, 0), Math.max(total - 1, 0));
+    const start = Math.min(Math.max(selected - Math.floor(height / 2), 0), Math.max(total - height, 0));
+    const end = Math.min(start + height, total);
+    const reachedEnd = end === total;
     return {
         rows: previewRows.slice(start, end),
         sourceLines: wrapped.slice(start, end).map(({ sourceLine }) => sourceLine),
         sourceOffsets: wrapped.slice(start, end).map(({ offset }) => offset),
         start,
         end,
-        total: previewRows.length,
+        total,
         cursor: selected,
         height,
-        reachedEnd: end === previewRows.length,
+        reachedEnd,
+        footer: layoutFooter(footerSpans({ reachedEnd, cursor: selected, start, end, total, windowed }, chrome, contentWidth), contentWidth, maxFooterRows),
     };
 }
+/** The viewport of a preview at the current terminal size; key handling and rendering share it. */
+export function usePreviewGeometry() {
+    const { rows, columns } = useWindowSize();
+    return (lines, cursor, chrome) => previewViewport(lines, cursor, rows || 24, columns || 80, chrome);
+}

package/dist/src/tui/profile-view.js

@@ -1,20 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { readFile } from "node:fs/promises";
-import { Box, Text, useWindowSize } from "ink";
+import path from "node:path";
+import { Box, useWindowSize } from "ink";
+import { PreEscapedText, Text } from "./safe-text.js";
 import stringWidth from "string-width";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { createAppOperations } from "../app-flow.js";
-import { buildProfileExport, describeProfileExportExclusion, describeProfilePackage, describeProfileReplica, describeProfileSkill, profileExportPreview, SKILL_EXPORT_EXPLANATION, writeProfileExport, } from "../profile-export.js";
+import { buildProfileExport, describeProfileExportExclusion, describeProfilePackage, describeProfileReplica, describeProfileSkill, profileExportPreview, requireOverwritableProfileExport, SKILL_EXPORT_EXPLANATION, writeProfileExport, } from "../profile-export.js";
 import { applyProfileImport, buildProfileImport, } from "../profile-import.js";
 import { PROFILE_FORMAT, PROFILE_FORMAT_V2, parseProfile } from "../profile.js";
 import { selectionKey } from "../package-model.js";
 import { packageOperationsOf } from "./environment.js";
 import { DEFAULT_PROFILE_FILE_NAME, exportDestination, fileNameNotice, pathExists, pickerStartDirectory, resolveExportFileName, } from "./file-picker-model.js";
 import { FilePicker } from "./file-picker.js";
-import { useKeys } from "./keys.js";
-import { previewViewport } from "./preview-window.js";
+import { isYes, useKeys } from "./keys.js";
+import { escapeControlText, usePreviewGeometry } from "./preview-window.js";
 import { answerYesNo, moveCursor, movePreviewCursor, toggleChoice } from "./mode-keys.js";
-import { BorderPanel, PreviewConfirm, PreviewLines, Working } from "./panel-parts.js";
+import { BorderPanel, PagedPreview, PreviewLines, Working } from "./panel-parts.js";
 import { clipText, elideMiddle, fitLines, wrapText } from "./text-wrap.js";
 import { theme } from "./theme.js";
 import { useMirrored, useMounted } from "./view-state.js";
@@ -136,6 +138,7 @@ function physicalListWindow(rows, rowHeights, selected, height) {
 /** An error naming a long path keeps its first and last rows, where the path starts and the reason ends. */
 const NAME_ERROR_ROWS = 3;
 const NAME_HINT = "Type to edit · Ctrl+U clear · Enter continue · Esc back to folder";
+const NOTE_CHROME = { title: "Export note", cancel: "[Esc] close" };
 /**
  * A `Label: value` line of the export name stage, wrapped to the panel and kept within `rows` rows. The
  * end of a path (its last folder, the file name) and the end of the typed name (where the cursor is) are
@@ -143,14 +146,16 @@ const NAME_HINT = "Type to edit · Ctrl+U clear · Enter continue · Esc back to
  * three or more a path keeps its first row too, around a count of the rows left out.
  */
 function NameField({ label, value, rows, width, tail = false }) {
-    const wrapped = wrapText(`${label}${value}`, width);
+    // Measured and drawn as escaped, so a hostile path or name takes the rows it is shown on.
+    const escapedValue = escapeControlText(value);
+    const wrapped = wrapText(`${label}${escapedValue}`, width);
     const cut = wrapped.length > rows;
     const keepsMiddleCount = cut && !tail && rows > 2;
     let shown = wrapped;
     if (keepsMiddleCount)
         shown = elideMiddle(wrapped, rows, width);
     else if (cut) {
-        const characters = Array.from(value);
+        const characters = Array.from(escapedValue);
         for (let dropped = 1; dropped <= characters.length; dropped += 1) {
             shown = wrapText(`${label}…${characters.slice(dropped).join("")}`, width);
             if (shown.length <= rows)
@@ -159,9 +164,9 @@ function NameField({ label, value, rows, width, tail = false }) {
     }
     return _jsx(_Fragment, { children: shown.map((line, index) => {
             if (index === 0 && line.startsWith(label)) {
-                return _jsxs(Text, { children: [_jsx(Text, { color: theme.field, children: label }), _jsx(Text, { color: theme.value, children: line.slice(label.length) })] }, index);
+                return _jsxs(PreEscapedText, { children: [_jsx(PreEscapedText, { color: theme.field, children: label }), _jsx(PreEscapedText, { color: theme.value, children: line.slice(label.length) })] }, index);
             }
-            return _jsx(Text, { color: keepsMiddleCount && index === 1 ? theme.muted : theme.value, children: line }, index);
+            return _jsx(PreEscapedText, { color: keepsMiddleCount && index === 1 ? theme.muted : theme.value, children: line }, index);
         }) });
 }
 function planEntries(plan) {
@@ -238,7 +243,7 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
     const [profile, setProfile] = useState();
     const [plan, setPlan] = useState();
     const diagnostics = useRef([]);
-    const { rows: terminalRows, columns: terminalColumns } = useWindowSize();
+    const { columns: terminalColumns } = useWindowSize();
     const panelWidth = Math.max((terminalColumns || 80) - 4, 1);
     const hintCursorRow = listRows(mode, rows, expandedGroupsRef.current)[cursorRef.current];
     const enterHint = hintCursorRow === undefined ? undefined
@@ -255,13 +260,17 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
     const titleRows = Math.max(Math.ceil(stringWidth("Export Profile") / panelWidth), 1);
     const hintRows = Math.max(Math.ceil(stringWidth(hintText) / panelWidth), 1);
     const height = useListHeight(listHeight, 4 + titleRows + hintRows);
-    const confirmChrome = () => ({
-        title: "Confirmation",
-        questions: [confirmRequest.current?.kind === "export"
-                ? "Save/Export Profile? (y/n) · arrows/PgUp/PgDn page · j/k line"
-                : "Apply Profile? (y/n) · arrows/PgUp/PgDn page · j/k line"],
-        footerRows: 2,
-    });
+    const previewGeometry = usePreviewGeometry();
+    const confirmChrome = () => {
+        const request = confirmRequest.current;
+        if (request?.kind !== "export")
+            return { title: "Confirmation", action: "Apply Profile", consequence: "Apply Profile? (y/n)" };
+        if (!request.overwrite)
+            return { title: "Confirmation", action: "Save/Export Profile", consequence: "Save/Export Profile? (y/n)" };
+        // The full path is on the Destination line; the base name keeps the footer short on narrow terminals.
+        const name = path.basename(request.file);
+        return { title: "Confirmation", action: `Overwrite ${name}`, consequence: `Overwrite ${name}? (y/n)` };
+    };
     const showLines = (next, nextMode) => {
         setLines(next);
         cursorTo(0);
@@ -348,6 +357,8 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
             let exists;
             try {
                 exists = await existsCheck(finalPath);
+                if (exists)
+                    await requireOverwritableProfileExport(finalPath);
             }
             catch (error) {
                 if (!mounted.current || nameRequest.current !== id || modeRef.current !== "export-name")
@@ -363,13 +374,10 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
                 return;
             if (current.kind !== "ok" || current.fileName !== fileName)
                 return;
-            if (exists) {
-                setNameError(`${finalPath} already exists; choose another name`);
-                return;
-            }
-            confirmRequest.current = { kind: "export", file: finalPath };
+            confirmRequest.current = { kind: "export", file: finalPath, overwrite: exists };
             setNameError(undefined);
-            showLines([`Destination: ${finalPath}`, ...profileExportPreview(chosenProfile(), diagnostics.current)], "confirm");
+            const destination = exists ? `Destination: ${finalPath} (exists; it will be replaced)` : `Destination: ${finalPath}`;
+            showLines([destination, ...profileExportPreview(chosenProfile(), diagnostics.current)], "confirm");
         })();
     };
     const confirmApply = () => {
@@ -379,7 +387,7 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
         void run(request.kind === "export" ? "Exporting…" : "Applying import…", async () => {
             let result;
             if (request.kind === "export") {
-                await writeProfileExport(request.file, chosenProfile());
+                await writeProfileExport(request.file, chosenProfile(), { overwrite: request.overwrite });
                 result = [`Exported profile to ${request.file}`];
             }
             else {
@@ -495,20 +503,21 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
                 setMode("export-list");
                 return;
             }
-            const next = movePreviewCursor(cursorRef.current, lines.length, input, key, height);
+            const viewport = previewGeometry(lines, cursorRef.current, NOTE_CHROME);
+            const next = movePreviewCursor(cursorRef.current, viewport.total, input, key, viewport.height);
             if (next !== undefined)
                 cursorTo(Math.max(0, next));
             return;
         }
         if (current === "confirm") {
-            answerYesNo(input, key, confirmApply, () => setMode(confirmRequest.current?.kind === "import" ? "import-list" : "export-name"));
-            if (input === "y" || input === "n" || key.escape)
-                return;
             // The preview cursor counts wrapped rows, not source lines, or a long destination would cap the paging.
-            const viewport = previewViewport(lines, cursorRef.current, terminalRows || 24, terminalColumns || 80, confirmChrome());
+            const viewport = previewGeometry(lines, cursorRef.current, confirmChrome());
             const next = movePreviewCursor(cursorRef.current, viewport.total, input, key, viewport.height);
             if (next !== undefined)
                 cursorTo(Math.max(0, next));
+            else if (!isYes(input, key) || viewport.reachedEnd) {
+                answerYesNo(input, key, confirmApply, () => setMode(confirmRequest.current?.kind === "import" ? "import-list" : "export-name"));
+            }
             return;
         }
         if (key.escape) {
@@ -574,7 +583,7 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
         if ("kind" in row)
             return 1;
         const prefixWidth = row.block === "excluded" ? 2 : stringWidth(`> [ ] ${row.ordinal ?? row.index + 1} `);
-        return wrapText(row.label, Math.max(panelWidth - prefixWidth, 1)).length;
+        return wrapText(escapeControlText(row.label), Math.max(panelWidth - prefixWidth, 1)).length;
     });
     const listWindow = physicalListWindow(displayRows, rowHeights, cursor, height);
     const window = listing ? listWindow : computeWindow(lines.length, cursor, height);
@@ -592,24 +601,24 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
             const prefix = `${marker}${" ".repeat(row.depth * 2)}${open ? "▾" : "▸"} `;
             const width = Math.max(panelWidth - stringWidth(prefix), 1);
             remainingRows -= 1;
-            return _jsxs(Text, { color: theme.group, bold: true, children: [prefix, clipText(row.label, width)] }, row.id);
+            return _jsxs(PreEscapedText, { color: theme.group, bold: true, children: [prefix, clipText(escapeControlText(row.label), width)] }, row.id);
         }
         if (row.block === "excluded") {
             const width = Math.max(panelWidth - stringWidth(marker), 1);
-            const label = fitLines(wrapText(row.label, width), remainingRows, width)
+            const label = fitLines(wrapText(escapeControlText(row.label), width), remainingRows, width)
                 .join(`\n${" ".repeat(stringWidth(marker))}`);
             remainingRows -= label.split("\n").length;
-            return _jsxs(Text, { color: theme.value, children: [marker, label] }, row.id);
+            return _jsxs(PreEscapedText, { color: theme.value, children: [marker, label] }, row.id);
         }
         // A row the import never changes has no checkbox: unchanged items rest, conflicts warn.
         const box = row.selectable ? `[${selected.some(choice => choice.id === row.id) ? "x" : " "}]` : "   ";
         const prefix = `${marker}${box} ${row.ordinal ?? row.index + 1} `;
         const width = Math.max(panelWidth - stringWidth(prefix), 1);
-        const label = fitLines(wrapText(row.label, width), remainingRows, width)
+        const label = fitLines(wrapText(escapeControlText(row.label), width), remainingRows, width)
             .join(`\n${" ".repeat(stringWidth(prefix))}`);
         remainingRows -= label.split("\n").length;
         const color = row.status === "conflict" ? theme.warning : row.status === "same" ? theme.muted : theme.value;
-        return _jsxs(Text, { children: [_jsx(Text, { color: theme.field, children: prefix }), _jsx(Text, { color: color, children: label })] }, row.id);
+        return _jsxs(PreEscapedText, { children: [_jsx(PreEscapedText, { color: theme.field, children: prefix }), _jsx(PreEscapedText, { color: color, children: label })] }, row.id);
     });
     const nameOutcome = resolveExportFileName(text);
     const liveDestination = nameOutcome.kind === "ok"
@@ -617,8 +626,8 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
     const nameNote = nameOutcome.kind === "ok" ? fileNameNotice(nameOutcome.fileName) : undefined;
     const extensionNote = nameOutcome.kind === "ok" && nameOutcome.appendedExtension
         ? `A name without an extension is saved as ${nameOutcome.fileName}.` : undefined;
-    const textRows = (value) => value === undefined ? 0 : wrapText(value, panelWidth).length;
-    const nameErrorLines = nameError === undefined ? [] : wrapText(nameError, panelWidth);
+    const textRows = (value) => value === undefined ? 0 : wrapText(escapeControlText(value), panelWidth).length;
+    const nameErrorLines = nameError === undefined ? [] : wrapText(escapeControlText(nameError), panelWidth);
     // Keys type into the name, so the stage cannot scroll; instead each long field keeps its end (and, given
     // three rows or more, its first row) within a share of the terminal. The confirmation pages the full destination.
     const nameFixedRows = 3 + textRows(nameNote) + textRows(extensionNote) + Math.min(nameErrorLines.length, NAME_ERROR_ROWS)
@@ -629,7 +638,7 @@ export function ProfileView({ operations, environment = {}, onCapturingChange, l
     const destinationRows = Math.floor(fieldRows / 3) + (fieldRows % 3 >= 1 ? 1 : 0);
     const nameRows = fieldRows - folderRows - destinationRows;
     return _jsxs(Box, { flexDirection: "column", children: [mode === "export-folder" ? _jsx(FilePicker, { purpose: "directory", listHeight: listHeight, startDirectory: exportDirectory ?? startDirectory, onCancel: () => setMode("export-list"), onChoose: selection => { if (selection.kind === "directory")
-                    chooseExportDirectory(selection.directory); } }) : null, mode === "import-browse" ? _jsx(FilePicker, { purpose: "file", listHeight: listHeight, startDirectory: importDirectory ?? startDirectory, notice: importNotice, onCancel: () => setMode("browse"), onChoose: chooseImportFile }) : null, listing ? _jsxs(BorderPanel, { title: mode === "export-list" ? "Export Profile" : "Import Profile", children: [listContent, _jsx(Text, { color: theme.legend, children: hintText }), window.indicator ? _jsx(Text, { color: theme.muted, children: window.indicator }) : null] }) : null, mode === "browse" ? _jsx(BorderPanel, { title: "Portable Profile", children: _jsx(Text, { color: theme.legend, children: "e export \u00B7 i import" }) }) : null, mode === "busy" && working ? _jsx(Working, { label: working.label, since: working.startedAt }) : null, mode === "export-name" ? _jsxs(BorderPanel, { title: "Export file name", children: [_jsx(NameField, { label: "Folder: ", value: exportDirectory ?? startDirectory, rows: folderRows, width: panelWidth }), _jsx(NameField, { label: "Name: ", value: `${text}_`, rows: nameRows, width: panelWidth, tail: true }), liveDestination === undefined ? null : _jsx(NameField, { label: "Destination: ", value: liveDestination, rows: destinationRows, width: panelWidth }), nameNote === undefined ? null : _jsx(Text, { color: theme.warning, children: nameNote }), extensionNote === undefined ? null : _jsx(Text, { color: theme.muted, children: extensionNote }), nameError === undefined ? null : nameErrorLines.length <= NAME_ERROR_ROWS
-                        ? _jsx(Text, { color: theme.error, children: nameError })
-                        : elideMiddle(nameErrorLines, NAME_ERROR_ROWS, panelWidth).map((line, index) => _jsx(Text, { color: theme.error, children: line }, index)), nameChecking === undefined ? null : _jsx(Working, { label: "Checking name\u2026", since: nameChecking }), _jsx(Text, { color: theme.legend, children: NAME_HINT })] }) : null, mode === "confirm" ? _jsx(PreviewConfirm, { lines: lines, cursor: cursor, chrome: confirmChrome(), question: confirmChrome().questions[0] }) : null, mode === "detail" ? _jsx(PreviewConfirm, { title: "Export note", lines: lines, cursor: cursor, question: "Esc close \u00B7 arrows/PgUp/PgDn page \u00B7 j/k line" }) : null, mode === "results" ? _jsxs(_Fragment, { children: [_jsx(PreviewLines, { lines: lines.slice(window.start, window.end) }), _jsx(Text, { children: "j/k scroll" })] }) : null, window.indicator && mode === "results" ? _jsx(Text, { children: window.indicator }) : null] });
+                    chooseExportDirectory(selection.directory); } }) : null, mode === "import-browse" ? _jsx(FilePicker, { purpose: "file", listHeight: listHeight, startDirectory: importDirectory ?? startDirectory, notice: importNotice, onCancel: () => setMode("browse"), onChoose: chooseImportFile }) : null, listing ? _jsxs(BorderPanel, { title: mode === "export-list" ? "Export Profile" : "Import Profile", children: [listContent, _jsx(Text, { color: theme.legend, children: hintText }), window.indicator ? _jsx(Text, { color: theme.muted, children: window.indicator }) : null] }) : null, mode === "browse" ? _jsx(BorderPanel, { title: "Portable Profile", children: _jsx(Text, { color: theme.legend, children: "e export \u00B7 i import" }) }) : null, mode === "busy" && working ? _jsx(Working, { label: working.label, since: working.startedAt }) : null, mode === "export-name" ? _jsxs(BorderPanel, { title: "Export file name", children: [_jsx(NameField, { label: "Folder: ", value: exportDirectory ?? startDirectory, rows: folderRows, width: panelWidth }), _jsx(NameField, { label: "Name: ", value: `${text}_`, rows: nameRows, width: panelWidth, tail: true }), liveDestination === undefined ? null : _jsx(NameField, { label: "Destination: ", value: liveDestination, rows: destinationRows, width: panelWidth }), nameNote === undefined ? null : _jsx(PreEscapedText, { color: theme.warning, children: escapeControlText(nameNote) }), extensionNote === undefined ? null : _jsx(PreEscapedText, { color: theme.muted, children: escapeControlText(extensionNote) }), nameError === undefined ? null : nameErrorLines.length <= NAME_ERROR_ROWS
+                        ? _jsx(PreEscapedText, { color: theme.error, children: escapeControlText(nameError) })
+                        : elideMiddle(nameErrorLines, NAME_ERROR_ROWS, panelWidth).map((line, index) => _jsx(PreEscapedText, { color: theme.error, children: line }, index)), nameChecking === undefined ? null : _jsx(Working, { label: "Checking name\u2026", since: nameChecking }), _jsx(Text, { color: theme.legend, children: NAME_HINT })] }) : null, mode === "confirm" ? _jsx(PagedPreview, { chrome: confirmChrome(), lines: lines, viewport: previewGeometry(lines, cursor, confirmChrome()) }) : null, mode === "detail" ? _jsx(PagedPreview, { chrome: NOTE_CHROME, lines: lines, viewport: previewGeometry(lines, cursor, NOTE_CHROME) }) : null, mode === "results" ? _jsxs(_Fragment, { children: [_jsx(PreviewLines, { lines: lines.slice(window.start, window.end) }), _jsx(Text, { children: "j/k scroll" })] }) : null, window.indicator && mode === "results" ? _jsx(Text, { children: window.indicator }) : null] });
 }

package/dist/src/tui/render.js

@@ -1,8 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
+import { createSourceRefreshSession } from "../source-refresh-session.js";
 import { App } from "./app.js";
 /** Renders the TUI and resolves once the user exits it. */
 export async function renderTui(operations, environment) {
-    const instance = render(_jsx(App, { operations: operations, environment: environment }), { alternateScreen: true });
+    const refreshSession = createSourceRefreshSession(operations);
+    const instance = render(_jsx(App, { operations: operations, environment: environment, refreshSession: refreshSession, 
+        // Test-only opt-out (tests/isolated-env.ts); manual and preview refreshes are unaffected.
+        refreshOnStart: process.env.AGENT_DEPOT_NO_BACKGROUND_REFRESH !== "1" }), { alternateScreen: true });
     await instance.waitUntilExit();
+    refreshSession.stop();
+    // Killing a refresh would leave its Source cache lock behind, so wait for the running ones instead.
+    if ([...refreshSession.snapshot().values()].some((state) => state.status === "refreshing")) {
+        process.stderr.write("Waiting for the Source refreshes still running to finish…\n");
+        await refreshSession.settled();
+    }
 }

package/dist/src/tui/safe-text.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text as InkText } from "ink";
+import { cloneElement, Fragment, isValidElement } from "react";
+import { escapeControlText } from "./preview-window.js";
+/** Ink's `Text` for text that was already passed through `escapeControlText`; escaping it again would double its backslashes. */
+export const PreEscapedText = InkText;
+// Messages and errors span lines on purpose and Ink lays them out, so a line break is the one control character left alone.
+const LINE_BREAK = /\r?\n/u;
+function escapeNode(node) {
+    if (typeof node === "string")
+        return node.split(LINE_BREAK).map(escapeControlText).join("\n");
+    if (Array.isArray(node))
+        return node.map(escapeNode);
+    if (isValidElement(node) && node.type === Fragment) {
+        return cloneElement(node, undefined, escapeNode(node.props.children));
+    }
+    return node;
+}
+/**
+ * The `Text` every view uses. Skill, recipe and App text can come from a remote Source or a user-written recipe; raw, an ESC
+ * sequence in it can retitle the window, write the clipboard or redraw the screen. Nested `Text` escapes its own children.
+ */
+export function Text({ children, ...props }) {
+    return _jsx(InkText, { ...props, children: escapeNode(children) });
+}

package/dist/src/tui/sources-mode.js

@@ -11,9 +11,9 @@ export function modeReducer(mode, event) {
         case "confirm":
             return event.action === "refresh"
                 ? { kind: "confirm", action: "refresh", sources: event.sources, cursor: 0 }
-                : { kind: "confirm", action: "remove", source: event.source };
+                : { kind: "confirm", action: "remove", source: event.source, cursor: 0 };
         case "preview-cursor":
-            return mode.kind === "confirm" && mode.action === "refresh" ? { ...mode, cursor: event.cursor } : mode;
+            return mode.kind === "confirm" ? { ...mode, cursor: event.cursor } : mode;
         case "busy":
             return busy(event.label, mode, () => event.startedAt);
         case "done":