@cruxy/cli 1.6.0 → 1.7.1

package/dist/tools/file/apply-patch.js

@@ -5,34 +5,93 @@ import { resolveToolPath, toPosix } from "./paths.js";
 import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
-const HunkSchema = z.object({
+/**
+ * ONE FLAT OPERATION SHAPE — deliberately flat, and it must stay that way.
+ *
+ * The provider rejects a tool schema nested 8 or more levels deep, and it
+ * rejects the entire REQUEST when any tool trips it: one over-deep schema kills
+ * every turn of every session, which is exactly how 1.7.0 died in the field.
+ * JSON Schema's own wrapper keys (`properties`, `items`, `anyOf`) are containers
+ * too, so every semantic level an author writes costs two, and a union costs two
+ * more on top. The previous shape — a discriminated union of operations, each
+ * carrying an array of hunk OBJECTS — rendered 11 levels deep.
+ *
+ * Neither lever alone was enough (both measured, see schema-depth.test.ts):
+ * keeping the union and flattening hunks still renders 8; dropping the union and
+ * keeping the hunk array renders 9. So both go. The discriminator survives as a
+ * plain `type` enum, and the per-variant field requirements the union used to
+ * encode are enforced by {@link refineOperation} below — `superRefine` is a
+ * runtime check that adds NO depth to the rendered schema, so the model still
+ * gets a precise rejection for a malformed operation, just from zod instead of
+ * from the schema's shape.
+ *
+ * The multi-hunk capability is NOT lost: a path may appear in as many `update`
+ * operations as it likes, and they apply in order against the running content —
+ * the same semantics the `hunks` array had, spelled one hunk per operation.
+ */
+const OperationSchema = z
+    .object({
+    type: z
+        .enum(["update", "create", "delete"])
+        .describe('What to do: "update" replaces oldStr with newStr in an existing file; ' +
+        '"create" writes a new file from content; "delete" removes an existing file.'),
+    path: z.string().describe("Path to the file, relative to the root."),
     oldStr: z
         .string()
         .min(1)
-        .describe("Exact text to replace; must occur exactly once in the file."),
-    newStr: z.string().describe("Replacement text."),
-});
-const OperationSchema = z.discriminatedUnion("type", [
-    z.object({
-        type: z.literal("update"),
-        path: z
-            .string()
-            .describe("Path to an existing file, relative to the root."),
-        hunks: z
-            .array(HunkSchema)
-            .min(1)
-            .describe("Edits applied in order; each oldStr must match exactly once."),
-    }),
-    z.object({
-        type: z.literal("create"),
-        path: z.string().describe("Path for a new file; must not already exist."),
-        content: z.string().describe("Full UTF-8 contents of the new file."),
-    }),
-    z.object({
-        type: z.literal("delete"),
-        path: z.string().describe("Path to an existing file to delete."),
-    }),
-]);
+        .optional()
+        .describe("update only — exact text to replace; must occur exactly once in the " +
+        "file as it stands when this operation runs."),
+    newStr: z
+        .string()
+        .optional()
+        .describe("update only — the replacement text (may be empty to delete)."),
+    content: z
+        .string()
+        .optional()
+        .describe("create only — full UTF-8 contents of the new file."),
+})
+    .superRefine(refineOperation);
+/**
+ * The per-variant requirements the discriminated union used to express in the
+ * schema. Enforced here so a malformed operation is still rejected before
+ * `execute` runs, with a message naming the exact field.
+ */
+function refineOperation(op, ctx) {
+    const needs = (field) => {
+        if (op[field] === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [field],
+                message: `"${field}" is required when type is "${op.type}"`,
+            });
+        }
+    };
+    const forbid = (field) => {
+        if (op[field] !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [field],
+                message: `"${field}" is not allowed when type is "${op.type}"`,
+            });
+        }
+    };
+    if (op.type === "update") {
+        needs("oldStr");
+        needs("newStr");
+        forbid("content");
+        return;
+    }
+    if (op.type === "create") {
+        needs("content");
+        forbid("oldStr");
+        forbid("newStr");
+        return;
+    }
+    forbid("oldStr");
+    forbid("newStr");
+    forbid("content");
+}
 const parameters = z.object({
     operations: z
         .array(OperationSchema)
@@ -50,14 +109,19 @@ export const applyPatchTool = {
     name: "apply_patch",
     description: "Apply multiple edits across one or more files in a single, atomic, reviewed change — preferred over many edit_file calls for multi-file or multi-hunk work. " +
         "Input is { operations: [...] } where each operation is one of: " +
-        '{ "type":"update", "path", "hunks":[{ "oldStr", "newStr" }] } — replace each oldStr (which must match EXACTLY ONCE in the file, like edit_file; hunks apply in order) with newStr; ' +
+        '{ "type":"update", "path", "oldStr", "newStr" } — replace oldStr (which must match EXACTLY ONCE in the file, like edit_file) with newStr; ' +
         '{ "type":"create", "path", "content" } — create a new file (must not already exist); ' +
         '{ "type":"delete", "path" } — delete an existing file. ' +
+        "To make several edits to the SAME file, list several update operations with the same path: they apply in order, each one matching against the result of the previous. " +
+        "A path used by a create or a delete may appear only once. " +
         "The whole patch is validated before anything is written: if any operation is invalid, nothing is applied and the failing operation is reported.",
     parameters,
     async execute(input, ctx) {
-        const planned = [];
-        const seen = new Set();
+        // One track per path, in first-touch order. Repeated `update` operations on
+        // a path fold into its track, each hunk matching against the running content
+        // — so a file is still written exactly once, from one final byte string.
+        const tracks = new Map();
+        const order = [];
         for (let i = 0; i < input.operations.length; i++) {
             const op = input.operations[i];
             let abs;
@@ -67,18 +131,29 @@ export const applyPatchTool = {
             catch (err) {
                 return { ok: false, error: opError(i, op, err.message) };
             }
-            if (seen.has(abs)) {
-                return {
-                    ok: false,
-                    error: opError(i, op, "duplicate path in patch"),
-                };
+            const existing = tracks.get(abs);
+            if (existing) {
+                // Only an update chain may share a path. A create or a delete alongside
+                // anything else on the same path is an order-dependent muddle, and the
+                // shape that preceded this one couldn't express it either.
+                if (existing.kind !== "update" || op.type !== "update") {
+                    return {
+                        ok: false,
+                        error: opError(i, op, `path already used by operation ${existing.firstOp + 1}; only repeated "update" operations may share a path`),
+                    };
+                }
+                const failure = applyHunk(i, op, existing);
+                if (failure)
+                    return { ok: false, error: failure };
+                continue;
             }
-            seen.add(abs);
-            const planResult = await planOp(i, op, abs, ctx);
-            if (!planResult.ok)
-                return planResult;
-            planned.push(planResult.planned);
+            const opened = await openTrack(i, op, abs, ctx);
+            if (!opened.ok)
+                return opened;
+            tracks.set(abs, opened.track);
+            order.push(abs);
         }
+        const planned = order.map((abs) => toPlanned(tracks.get(abs)));
         // One approval for the whole patch — denial writes nothing.
         const decision = await ctx.requestApproval({
             kind: "patch",
@@ -114,27 +189,31 @@ export const applyPatchTool = {
         return { ok: true, output: `applied patch:\n${applied.join("\n")}` };
     },
 };
-/** Validate one operation against the filesystem and compute its final bytes. */
-async function planOp(i, op, abs, ctx) {
+/** Validate the FIRST operation on a path and open its track. */
+async function openTrack(i, op, abs, ctx) {
     // Forward-slash for model-facing output (the `applied` lines and error
     // messages), consistent with every other path tool — see {@link toPosix}.
     const rel = toPosix(path.relative(ctx.cwd, abs));
+    const base = { abs, rel, firstOp: i, hunks: [] };
     if (op.type === "create") {
         if (await exists(abs)) {
             return { ok: false, error: opError(i, op, "file already exists") };
         }
+        const content = op.content ?? "";
         return {
             ok: true,
-            planned: { op: "create", abs, rel, content: op.content },
+            track: { ...base, kind: "create", content, eol: detectEol(content) },
         };
     }
     if (op.type === "delete") {
         if (!(await exists(abs))) {
             return { ok: false, error: opError(i, op, "file not found") };
         }
-        return { ok: true, planned: { op: "delete", abs, rel } };
+        return {
+            ok: true,
+            track: { ...base, kind: "delete", content: "", eol: "\n" },
+        };
     }
-    // update: read, then apply each hunk in order against the running content.
     let content;
     try {
         content = await fs.readFile(abs, "utf8");
@@ -145,34 +224,49 @@ async function planOp(i, op, abs, ctx) {
         }
         return { ok: false, error: opError(i, op, err.message) };
     }
-    // Detect the file's line ending once, from the original bytes, so every hunk
-    // re-encodes newStr to the same convention as content mutates across hunks.
-    const fileEol = detectEol(content);
-    for (let h = 0; h < op.hunks.length; h++) {
-        const { oldStr, newStr } = op.hunks[h];
-        const match = findMatch(content, oldStr);
-        if (match.kind === "none") {
-            return {
-                ok: false,
-                error: opError(i, op, `hunk ${h + 1}: oldStr not found`),
-            };
-        }
-        if (match.kind === "ambiguous") {
-            return {
-                ok: false,
-                error: opError(i, op, `hunk ${h + 1}: oldStr not unique (${match.count} matches${tierLabel(match.tier)})`),
-            };
-        }
-        // Splice by offset so `$` patterns in newStr aren't interpreted.
-        content =
-            content.slice(0, match.start) +
-                applyEol(newStr, fileEol) +
-                content.slice(match.end);
-    }
-    return {
-        ok: true,
-        planned: { op: "update", abs, rel, content, hunks: op.hunks },
+    const track = {
+        ...base,
+        kind: "update",
+        content,
+        eol: detectEol(content),
     };
+    const failure = applyHunk(i, op, track);
+    return failure ? { ok: false, error: failure } : { ok: true, track };
+}
+/**
+ * Apply one update operation's hunk to its track's running content. Returns an
+ * error string on failure, or `undefined` on success (the track is mutated).
+ */
+function applyHunk(i, op, track) {
+    const { oldStr, newStr } = op;
+    // Guaranteed present by `refineOperation`; re-checked so the narrowing is
+    // structural rather than a cast, and a schema regression fails loud.
+    if (oldStr === undefined || newStr === undefined) {
+        return opError(i, op, 'update requires both "oldStr" and "newStr"');
+    }
+    const match = findMatch(track.content, oldStr);
+    if (match.kind === "none") {
+        return opError(i, op, "oldStr not found");
+    }
+    if (match.kind === "ambiguous") {
+        return opError(i, op, `oldStr not unique (${match.count} matches${tierLabel(match.tier)})`);
+    }
+    // Splice by offset so `$` patterns in newStr aren't interpreted.
+    track.content =
+        track.content.slice(0, match.start) +
+            applyEol(newStr, track.eol) +
+            track.content.slice(match.end);
+    track.hunks.push({ oldStr, newStr });
+    return undefined;
+}
+/** Collapse a finished track into the single write it represents. */
+function toPlanned(track) {
+    const { kind, abs, rel, content, hunks } = track;
+    if (kind === "delete")
+        return { op: "delete", abs, rel };
+    if (kind === "create")
+        return { op: "create", abs, rel, content };
+    return { op: "update", abs, rel, content, hunks };
 }
 /** Shape a planned op into its approval-preview form. */
 function toPreview(p) {

package/dist/tui/app.js

@@ -5,6 +5,7 @@ import { TUI_ONLY_COMMANDS } from "../cli/command-catalog.js";
 import { selectList } from "../components/select.js";
 import { viewLabel, viewOrder } from "./views.js";
 import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
+import { ModeRing } from "./mode-ring.js";
 import { openPalette } from "./palette.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { CLOSABLE_PANELS, columnOf, RAIL_PANELS, } from "./layout.js";
@@ -263,7 +264,11 @@ async function readLine(keys, renderer, hooks) {
                     // Mode is a property of the session, not of the message — losing a
                     // half-written prompt to a mode switch would make the binding one
                     // people learn not to press.
-                    hooks.cycleMode();
+                    //
+                    // The chip moves on this keypress; the session hears about it when the
+                    // ring stops turning (Q5). Passing `paint` gives the ring a way to
+                    // correct the chip if the settle resolves somewhere else.
+                    hooks.cycleMode(paint);
                     paint();
                     break;
                 case "page-up":
@@ -302,6 +307,11 @@ async function readLine(keys, renderer, hooks) {
         }
     }
     finally {
+        // The line is over — by Enter, by EOF, by Ctrl+C. Whatever the ring stopped
+        // on is what the user chose, and it is committed and announced HERE rather
+        // than a debounce later, so the mode is in force before the turn it was
+        // chosen for runs and its log event lands ahead of that turn's messages.
+        hooks.settleMode();
         keys.restore();
     }
 }
@@ -476,9 +486,14 @@ export async function runTui(session, renderer, opts = {}) {
         theme: renderer.theme,
         fit: (line) => line,
     };
+    // The mode ring (Q5). The chip follows every press; the session is told once,
+    // when the presses stop — see `mode-ring.ts` for why passing through a mode is
+    // not the same as choosing it.
+    const ring = new ModeRing(session, (mode) => announceMode(out, mode), opts.modeSettleMs);
     const hooks = {
-        mode: () => session.getMode(),
-        cycleMode: () => announceMode(out, session.cycleMode()),
+        mode: () => ring.current(),
+        cycleMode: (repaint) => ring.advance(repaint),
+        settleMode: () => ring.settle(),
         openPalette: () => openPalette(renderer, lease, opts.slashCommands ?? []),
     };
     // The TUI's picker (P6 track 1): an overlay drawer on the SAME reader this

package/dist/tui/index.js

@@ -8,9 +8,10 @@ export { createOverviewView } from "./overview.js";
 export { createGitView, gitViewLines, GIT_VIEW_MAX_FILES, } from "./git-view.js";
 export { createTasksView, tasksViewLines, TASKS_VIEW_MAX_JOBS, TASKS_VIEW_TAIL, } from "./tasks-view.js";
 export { createSettingsView, settingsViewLines, formatSettingValue, } from "./settings-view.js";
-export { TuiRenderer, PAINT_INTERVAL_MS, VIEW_PULSE_MS, SCROLL_PAGE_OVERLAP, SCROLLBACK_LINES, } from "./renderer.js";
+export { TuiRenderer, EXIT_TAIL_LINES, PAINT_INTERVAL_MS, VIEW_PULSE_MS, SCROLL_PAGE_OVERLAP, SCROLLBACK_LINES, } from "./renderer.js";
 export { CONVERSATION_VIEW, cycleView, navLines, viewLabel, viewOrder, } from "./views.js";
 export { runTui, renderInput, TUI_COMMANDS } from "./app.js";
 export { openPalette, paletteItems, paletteInsertion, paletteLabel, } from "./palette.js";
 export { canOverlay, createKeyLease, createOverlayFrame, createOverlayIO, } from "./overlay.js";
-export { supportsTui } from "./supports.js";
+export { supportsTui, usesAltScreen } from "./supports.js";
+export { installScreenGuard, restoreAllScreens, screenGuardCount, RESTORE_SIGNALS, SIGNAL_EXIT_CODES, } from "./restore.js";

package/dist/tui/mode-ring.js

@@ -0,0 +1,84 @@
+import { nextMode } from "../agent/index.js";
+/**
+ * The Shift+Tab mode ring, debounced (Q5).
+ *
+ * Shift+Tab walks a four-entry cycle, so reaching `full-auto` from `manual`
+ * means passing THROUGH `auto-approve` and `plan`. Every press used to be a
+ * commit: three `setMode` calls, three `mode` events appended to the session
+ * log, and three announcements — two of them for modes the user was not stopping
+ * on and never saw. The log then read as a session that deliberately chose
+ * auto-approve, then planning, then full-auto, which is not what happened; and
+ * the conversation column filled with descriptions of modes that were already
+ * gone by the time they were painted.
+ *
+ * So the ring turns freely and commits once. `current()` is the mode the ring is
+ * POINTING AT — the chip reads it, so every press still lands instantly on
+ * screen, which is the feedback the keypress owes the user. The session only
+ * hears about it once the presses stop, and that single commit is what gets
+ * announced and journaled.
+ *
+ * The chip is not a promise. `setMode` returns the EFFECTIVE mode (a session
+ * with no plan runner cannot enter a planning mode), so a settle that resolves
+ * elsewhere corrects the chip and announces where it actually landed.
+ */
+/** Quiet period after the last press before the ring is taken as settled. */
+export const MODE_SETTLE_MS = 400;
+export class ModeRing {
+    session;
+    announce;
+    settleMs;
+    /** Where the ring is pointing, or null when it matches the committed mode. */
+    pending = null;
+    timer = null;
+    /** Repaint for a settle that lands on the timer rather than on a key. */
+    repaint;
+    constructor(session, announce, settleMs = MODE_SETTLE_MS) {
+        this.session = session;
+        this.announce = announce;
+        this.settleMs = settleMs;
+    }
+    /** The mode to SHOW. Pure — safe on the paint path, called every keystroke. */
+    current() {
+        return this.pending ?? this.session.getMode();
+    }
+    /**
+     * One press of Shift+Tab: advance the ring and restart the quiet period.
+     * `repaint` runs after a settle that lands on the timer, because the input
+     * row's chip is a stored string and a correction to it needs a new paint.
+     */
+    advance(repaint) {
+        this.pending = nextMode(this.current());
+        this.repaint = repaint;
+        this.arm();
+    }
+    /**
+     * Commit what the ring stopped on, now — the caller knows the turn is over
+     * (Enter, EOF) and will not wait out the timer. A no-op when nothing is
+     * pending, so it is safe in a `finally` on every line.
+     */
+    settle() {
+        this.disarm();
+        const want = this.pending;
+        if (want === null)
+            return;
+        this.pending = null;
+        this.announce(this.session.setMode(want));
+    }
+    arm() {
+        this.disarm();
+        const timer = setTimeout(() => {
+            this.timer = null;
+            this.settle();
+            this.repaint?.();
+        }, this.settleMs);
+        // A decorative debounce must never be the reason a process stays alive.
+        timer.unref?.();
+        this.timer = timer;
+    }
+    disarm() {
+        if (this.timer === null)
+            return;
+        clearTimeout(this.timer);
+        this.timer = null;
+    }
+}

package/dist/tui/renderer.js

@@ -12,6 +12,8 @@ import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, ov
 import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
 import { limitsPanelLines } from "./limits-panel.js";
+import { installScreenGuard, } from "./restore.js";
+import { usesAltScreen } from "./supports.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
  * only one that owns the whole screen rather than a single managed line.
@@ -35,8 +37,36 @@ import { limitsPanelLines } from "./limits-panel.js";
  *    Paints are marked dirty and flushed at most every {@link PAINT_INTERVAL_MS},
  *    which keeps streaming smooth without a redraw per token.
  */
+/**
+ * Enter the alternate screen buffer and hide the cursor (Q4 track 3), and the
+ * exact inverse. Emitted as one pair by one object, in one order, so there is
+ * no arrangement of them that can leave a terminal half-restored.
+ *
+ * The cursor is hidden because this renderer DRAWS its caret (see
+ * `renderInput`): the real cursor parks wherever the last painted row ended,
+ * which is a second, wrong caret blinking somewhere in the frame.
+ */
+const ENTER_ALT_SCREEN = "\x1b[?1049h\x1b[?25l";
+const LEAVE_ALT_SCREEN = "\x1b[?25h\x1b[?1049l";
 /** Coalescing window for repaints (~30fps). */
 export const PAINT_INTERVAL_MS = 33;
+/**
+ * Logical lines of the conversation echoed into the NORMAL buffer when the TUI
+ * exits cleanly (Q4 track 3).
+ *
+ * The alternate screen is discarded when it is left — that is the whole point
+ * of it, and it is why the shell comes back exactly as it was. It also means
+ * the session the user just had would be gone the instant they typed `/exit`:
+ * no transcript in the scrollback, nothing to copy an error message out of,
+ * nothing to page back through. Losing that is a real regression, and an env
+ * knob nobody finds is not a fix for it.
+ *
+ * A dozen lines is chosen to be a REMINDER rather than a transcript. It is
+ * enough to carry the last answer and the command that produced it, and short
+ * enough that quitting a long session does not dump a screenful into the shell.
+ * The session log is the transcript; this is the tail.
+ */
+export const EXIT_TAIL_LINES = 12;
 /**
  * How often a selected view that reports itself {@link ViewSource.live} gets
  * repainted with no other event to prompt it (P7 track 5).
@@ -57,6 +87,18 @@ export class TuiRenderer {
     theme;
     out;
     frame;
+    /**
+     * The process-level restore backstop (Q4 track 1). Installed at construction
+     * — the moment this renderer starts owning the screen — and dropped in
+     * {@link close}, so a process with no TUI up carries no handlers.
+     */
+    guard;
+    /** Whether this renderer took the alternate screen and owes the inverse. */
+    altScreen;
+    /** Lines the opening banner occupies — the buffer's contents at construction. */
+    openingLines;
+    /** Logical lines committed since construction, INCLUDING ones rolled off. */
+    committed = 0;
     /** Committed conversation content, UNWRAPPED — wrapped fresh at each paint. */
     buffer = [];
     /** The streamed line still being assembled (no newline seen yet). */
@@ -149,7 +191,35 @@ export class TuiRenderer {
         this.initialModel = opts.model;
         this.tools = opts.tools;
         this.buffer = mainWelcome(this.theme, "/help for commands · /exit to quit");
-        this.frame = createFrame((text) => this.out.write(text), caps);
+        this.openingLines = this.buffer.length;
+        // THE ALTERNATE SCREEN (Q4 track 3), taken before a single byte is painted.
+        //
+        // This is what makes track 2's absolute addressing safe to use here. Rows
+        // land at screen positions 1..n, so without a buffer of its own the shell
+        // would overwrite whatever the terminal was showing — the user's last
+        // screenful of shell history, gone rather than scrolled into scrollback.
+        // On the alternate screen there is nothing to overwrite, and leaving it
+        // restores the normal buffer byte for byte: the prompt cruxy was started
+        // from comes back exactly as it was, with no frame-shaped hole in it.
+        //
+        // The inverse is owed from this line onward, which is why track 1 landed
+        // first: `close()` is not the only way out of this constructor's reach.
+        this.altScreen = opts.altScreen ?? usesAltScreen(caps);
+        if (this.altScreen)
+            out.write(ENTER_ALT_SCREEN);
+        // ABSOLUTE rows (Q4 track 2). This renderer owns the viewport outright, so
+        // it has no reason to infer where its rows are from where the cursor was
+        // left — and every reason not to. A frame this tall repaints thirty times a
+        // second; one cursor position the walk got wrong (a stray byte, a soft-wrap
+        // the width math did not predict, a scroll) would put every subsequent
+        // paint one row further off, with no paint able to recover. Row 1 is row 1.
+        this.frame = createFrame((text) => this.out.write(text), caps, {
+            absolute: true,
+        });
+        // Installed here, not in `close()`'s vicinity, because the window it covers
+        // opens with the first paint: from this line on there is a shell on screen
+        // that only this object knows how to take down.
+        this.guard = installScreenGuard(() => this.releaseScreen(), opts.signals);
         // The single shared clock (U.10): an inert clock under reduced motion, so
         // the spinner is drawn once statically and no timer is ever scheduled.
         this.clock = createFrameClock(caps.spinner);
@@ -763,11 +833,78 @@ export class TuiRenderer {
         this.unsubscribeResize = null;
         this.unsubscribeModel?.();
         this.unsubscribeModel = null;
-        // Erase the whole shell: after the TUI exits the terminal holds zero
-        // leftover bytes from it, exactly like a resolved component frame.
-        this.frame.clear();
+        // Erase the whole shell through the SAME path a signal takes (Q4 track 1),
+        // so a clean exit and a killed one leave the terminal in one state rather
+        // than two that drift apart the next time either is edited. The guard is
+        // idempotent, so the two can also race harmlessly.
+        this.guard.restoreScreen();
+        this.guard.dispose();
+        // AFTER the screen is handed back, so this lands in the normal buffer and
+        // survives in the shell's scrollback (Q4 track 3). On the clean path only:
+        // a signal handler's job is to give the terminal up, not to write a report
+        // into a shell the user may not be looking at.
+        this.printExitTail();
     }
     // ── internals ─────────────────────────────────────────────────────────────
+    /**
+     * Hand the terminal back (Q4 track 1): everything {@link close} does to the
+     * SCREEN, and nothing it does to the session. This is what the signal and
+     * exit handlers run, so it must be safe from a context where nothing async
+     * can be awaited and nothing that throws will be reported.
+     *
+     * After the TUI releases the screen the terminal holds zero leftover bytes
+     * from it, exactly like a resolved component frame.
+     *
+     * `closed` is set here rather than only in `close()`: on the signal path this
+     * is the last thing that runs before `process.exit`, and a repaint scheduled
+     * in between would draw a shell back onto a terminal that has just been
+     * handed over.
+     */
+    releaseScreen() {
+        this.closed = true;
+        this.frame.clear();
+        // The exact inverse of the constructor's pair, and the last bytes this
+        // renderer ever writes to the managed screen.
+        if (this.altScreen)
+            this.out.write(LEAVE_ALT_SCREEN);
+    }
+    /**
+     * Echo the tail of the conversation into the normal buffer (Q4 track 3).
+     *
+     * The alternate screen is discarded when it is left, so without this the
+     * session would vanish the moment the user typed `/exit` — no transcript in
+     * the scrollback, no error message left to copy, nothing to page back
+     * through. That is a regression the alternate screen would otherwise trade
+     * for a clean prompt, and it is not a trade worth making silently.
+     *
+     * Nothing is printed for a session that produced nothing: opening the shell
+     * and quitting leaves the terminal exactly as it was found, which is what the
+     * alternate screen is for. When some output DID roll past the tail, the count
+     * says so — and it counts every line ever committed, including the ones that
+     * rolled off the scrollback buffer entirely, so the number is the true amount
+     * hidden rather than the amount this object still happens to remember.
+     *
+     * Lines go out unwrapped and untruncated. The normal buffer soft-wraps them,
+     * which is right: this is the copy the user keeps, and nothing in it should be
+     * cut to a width the terminal is no longer being managed at.
+     */
+    printExitTail() {
+        if (this.committed === 0)
+            return;
+        const shown = this.buffer.slice(Math.max(0, this.buffer.length - EXIT_TAIL_LINES));
+        if (shown.length === 0)
+            return;
+        const hidden = this.openingLines + this.committed - shown.length;
+        const notice = hidden > 0
+            ? [
+                this.theme.muted(`… ${hidden} earlier line${hidden === 1 ? "" : "s"} not shown`),
+            ]
+            : [];
+        // Leading and trailing blank rows: this is a quotation dropped into the
+        // shell, and it needs to read as separate from both the prompt above it and
+        // whatever the exit path prints below.
+        this.out.write(["", ...notice, ...shown, ""].join("\n"));
+    }
     newPrinter() {
         return createStreamPrinter((text) => {
             this.commit(this.highlighter.push(text));
@@ -814,6 +951,10 @@ export class TuiRenderer {
             this.scrollOffset += added;
         }
         this.buffer.push(...lines);
+        // Counted here rather than measured off the buffer at exit, because the
+        // buffer forgets: `committed` has to keep counting past the roll-off below
+        // for the exit tail's "N earlier lines" to be a true number.
+        this.committed += lines.length;
         if (this.buffer.length > SCROLLBACK_LINES) {
             this.buffer = this.buffer.slice(this.buffer.length - SCROLLBACK_LINES);
         }