@cruxy/cli 1.5.0 → 1.7.0

package/dist/subagent/orchestrator.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import { runAgent } from "../agent/loop.js";
-import { CruxyError, ErrorCode, messageOf, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { UNRESOLVED_TIER, } from "../budget/index.js";
+import { resolveTaskModel } from "../routing/index.js";
 import { Workspace } from "../workspace/index.js";
 import { Budget, resolveBudget } from "../agent/budget.js";
 import { scopeRegistry, SUBAGENT_WRITE_TOOLS } from "./registry-scope.js";
@@ -181,6 +183,28 @@ export class SubagentOrchestrator {
             return [];
         // Refuse overlapping write scope BEFORE any child is dispatched.
         this.assertDisjointWriteScopes(specs);
+        // Admission control (P10 track 3 / cli#212), also before dispatch. Ordered
+        // AFTER the scope check on purpose: an overlapping fan-out is malformed and
+        // must be refused whatever the budget says, and narrowing a malformed batch
+        // to two children would hide the overlap rather than report it.
+        const admitted = this.admitFanOut(specs);
+        if (admitted.kind === "refused") {
+            throw sessionBudgetExhausted(admitted.reason);
+        }
+        // The children that do not run come back as an explicit NOT-ADMITTED result
+        // carrying the reason, never as a silently shorter array. The parent model is
+        // the one that has to decide what to do about a half-dispatched plan, and it
+        // can only do that if it is told — a fan-out of 5 that returns 2 results with
+        // no explanation reads as three crashes. Position is preserved for the same
+        // reason the dispatched half preserves it: result i is spec i, always.
+        const dispatch = specs.slice(0, admitted.count);
+        const deferred = [];
+        if (admitted.kind === "narrowed") {
+            this.deps.logger.warn(admitted.reason);
+            for (let i = admitted.count; i < specs.length; i++) {
+                deferred.push(notAdmittedResult(admitted.reason));
+            }
+        }
         const controller = new AbortController();
         const onExternalAbort = () => controller.abort();
         if (opts.signal) {
@@ -189,10 +213,10 @@ export class SubagentOrchestrator {
             else
                 opts.signal.addEventListener("abort", onExternalAbort, { once: true });
         }
-        const results = new Array(specs.length);
-        const total = specs.length;
+        const results = new Array(dispatch.length);
+        const total = dispatch.length;
         try {
-            const settled = await Promise.allSettled(specs.map((spec, i) => this.sem.run(async () => {
+            const settled = await Promise.allSettled(dispatch.map((spec, i) => this.sem.run(async () => {
                 // Already cancelled (a fatal sibling or Ctrl-C fired first): record an
                 // honest cancelled result instead of starting a doomed run.
                 if (controller.signal.aborted) {
@@ -223,12 +247,51 @@ export class SubagentOrchestrator {
                 if (results[i] === undefined)
                     results[i] = cancelledResult();
             }
-            return results;
+            return [...results, ...deferred];
         }
         finally {
             opts.signal?.removeEventListener("abort", onExternalAbort);
         }
     }
+    /**
+     * Ask the session budget whether this batch fits (P10 track 3 / cli#212).
+     *
+     * The estimate is the batch's CEILING, not a guess at its actual draw:
+     * `count × perChildTokens × multiplier`, where `perChildTokens` is the local
+     * cap each child already runs under. A spec may narrow its own budget, so the
+     * per-child figure is the resolved one rather than the configured default —
+     * a fan-out of five deliberately-cheap children should not be refused on the
+     * arithmetic of five expensive ones.
+     *
+     * Tier: the router resolves per task class, and a child defaults to the
+     * `subagent` class. When routing cannot name a tier the request still draws on
+     * the pool, so it is weighed at the worst case rather than skipped — see
+     * `UNRESOLVED_TIER`.
+     */
+    admitFanOut(specs) {
+        const budget = this.deps.budget;
+        if (!budget)
+            return { kind: "allow", count: specs.length, maxTokens: 0 };
+        const { defaultBudget } = this.deps.config.subagent;
+        // The heaviest child in the batch sets the per-run figure. The bound has to
+        // hold for the batch as dispatched, and averaging would let one 64k child
+        // hide behind four 4k ones.
+        const perRunTokens = specs.reduce((max, spec) => Math.max(max, resolveBudget(defaultBudget, spec.budget).maxTokens), 0);
+        return budget.admit({
+            count: specs.length,
+            perRunTokens,
+            tier: this.fanOutTier(),
+        });
+    }
+    /** The tier a child would route to, or the unresolved/no-pool markers. */
+    fanOutTier() {
+        const router = this.deps.router;
+        if (!router)
+            return undefined; // no cruxy routing — not a weighted-pool request
+        // No tier means the router chose `auto` and the gateway decides — a request
+        // that still draws on the pool, so it is weighed at the worst case.
+        return resolveTaskModel(router, "subagent").tier ?? UNRESOLVED_TIER;
+    }
     /**
      * Resolve a child's scope from an optional root name. With a name: a
      * single-root workspace over that root (writes confined to it) + that root's
@@ -344,6 +407,20 @@ function cancelledResult() {
         usage: { input_tokens: 0, output_tokens: 0 },
     };
 }
+/**
+ * A child the budget would not admit. Zero usage and zero iterations, because
+ * that is literally what it consumed — a fabricated non-zero here would show up
+ * in the parent's accounting as spend that never happened.
+ */
+function notAdmittedResult(reason) {
+    return {
+        status: "not-admitted",
+        summary: "",
+        error: `${ErrorCode.SessionBudgetExhausted}: ${reason}`,
+        iterations: 0,
+        usage: { input_tokens: 0, output_tokens: 0 },
+    };
+}
 /** `artifacts` only when non-empty — absent beats `[]` in the parent's context. */
 function artifactsField(artifacts) {
     return artifacts.size > 0 ? { artifacts: [...artifacts].sort() } : {};

package/dist/theme/resolve.js

@@ -47,6 +47,7 @@ export function resolveTheme(caps) {
         sep: ` ${glyph.sep} `,
         color: caps.color,
         unicode: caps.unicode,
+        screenReader: caps.screenReader ?? false,
     };
 }
 /**

package/dist/tui/app.js

@@ -1,9 +1,11 @@
 import { DEFAULT_MODE, MODE_LABELS, modeAutoApproves, } from "../agent/index.js";
 import { completeLine } from "../components/autocomplete.js";
 import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
+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";
@@ -31,18 +33,20 @@ import { COLUMN_LABELS, PANEL_LABELS } from "./panels.js";
  */
 /**
  * Every command the TUI completes on Tab — the shared set plus this shell's own
- * panel commands (P5 track 5).
+ * panel and view commands (P5 track 5).
  *
  * This constant existed before and was consumed by NOTHING: exported from
  * `tui/index.ts`, imported nowhere, while the TUI had no completion at all.
  * It is wired to Tab now rather than deleted, because the thing it was reaching
  * for — the REPL's readline completer, which the TUI cannot use — is real.
+ *
+ * Both halves are derived (P10 track 0). The three names used to be written out
+ * here, in the palette, and in this file's `HELP`, and the reserved set knew
+ * about none of them.
  */
 export const TUI_COMMANDS = [
     ...SHARED_COMMANDS,
-    "/close",
-    "/open",
-    "/view",
+    ...TUI_ONLY_COMMANDS.map((c) => c.name),
 ].sort();
 const HELP = [
     "commands:",
@@ -260,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":
@@ -299,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();
     }
 }
@@ -473,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/approval-overlay.js

@@ -1,3 +1,4 @@
+import { themeForColor } from "../theme/index.js";
 /**
  * The approval prompt as an in-viewport modal (P5 track 2).
  *
@@ -28,6 +29,11 @@
  * gives exactly that behaviour without the prompt knowing it is in a modal.
  */
 export function createOverlayPromptIO(surface, lease, color) {
+    // The caret comes from the glyph table, not a literal (P11 track 1). It is a
+    // decorative mark whose meaning is carried by the text beside it, so the table
+    // degrades it to `|` on an ASCII terminal and to nothing at all for a screen
+    // reader — where a lone `▏` announces as noise on the end of every keystroke.
+    const t = themeForColor(color);
     /** Everything the prompt has written this interaction, verbatim. */
     let transcript = "";
     /** The line being typed into a `readLine` follow-up, if one is open. */
@@ -46,7 +52,7 @@ export function createOverlayPromptIO(surface, lease, color) {
         // always shows where the next character lands.
         if (typing !== null) {
             rows[Math.max(0, rows.length - 1)] =
-                `${rows[rows.length - 1] ?? ""}${typing}▏`;
+                `${rows[rows.length - 1] ?? ""}${typing}${t.glyph.cursorBar}`;
         }
         surface.setOverlay(rows);
     };

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/layout.js

@@ -164,10 +164,15 @@ export function scrollWindow(lines, rows, offset) {
  *
  * It names the key because a scrolled view is a mode, and a mode the user
  * cannot see the exit from is a trap — there is no scrollbar here to drag.
+ *
+ * The marks come from the glyph table (P11 track 1). This used to branch on
+ * `theme.unicode ? "↓" : "v"`, which is the resolver reimplemented inline and
+ * one table short: screen-reader mode leaves `unicode` TRUE and swaps the table
+ * instead, so the branch printed a bare `↓` to the one reader who could not use
+ * it, where `theme.glyph.caretDown` says "down".
  */
 export function scrollNotice(hiddenBelow, theme) {
-    const glyph = theme.unicode ? "↓" : "v";
-    return theme.warning(`${glyph} ${hiddenBelow} more line${hiddenBelow === 1 ? "" : "s"} below · PgDn / Esc to return`);
+    return theme.warning(`${theme.glyph.caretDown} ${hiddenBelow} more line${hiddenBelow === 1 ? "" : "s"} below${theme.sep}PgDn / Esc to return`);
 }
 /** Rows the overflow notice costs when at least one panel is dropped. */
 const OVERFLOW_ROWS = 1;

package/dist/tui/limits-panel.js

@@ -1,3 +1,4 @@
+import { compactTokens } from "../render/units.js";
 import { bindingWindow, usedFraction } from "../limits/index.js";
 /**
  * The limits panel (P9): what this credential may spend, and how much is left.
@@ -49,20 +50,11 @@ function stateStyle(theme, state) {
         return theme.warning;
     return theme.strong;
 }
-/** 14_000_000 → "14M", 8_700_000 → "8.7M", 125_000 → "125k", 900 → "900". */
-export function compactTokens(n) {
-    const abs = Math.abs(n);
-    if (abs >= 1_000_000)
-        return `${trimZero(n / 1_000_000)}M`;
-    if (abs >= 1_000)
-        return `${trimZero(n / 1_000)}k`;
-    return `${Math.round(n)}`;
-}
-/** One decimal, but only when it says something: 8.7 stays, 14.0 becomes 14. */
-function trimZero(n) {
-    const one = n.toFixed(1);
-    return one.endsWith(".0") ? one.slice(0, -2) : one;
-}
+/**
+ * Re-exported, not defined here any more (P10 track 3): `/budget` states the
+ * same windows in the same unit, so the two share one formatter.
+ */
+export { compactTokens };
 /** 27.77 → "$27.77", 29 → "$29", 0.5 → "$0.50". */
 export function usd(n) {
     return Number.isInteger(n) ? `$${n}` : `$${n.toFixed(2)}`;

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/palette.js

@@ -1,29 +1,21 @@
 import { fuzzyFind } from "../components/fuzzy.js";
-import { COMMAND_CATALOG } from "../cli/session-commands.js";
+import { COMMAND_CATALOG, TUI_ONLY_COMMANDS } from "../cli/command-catalog.js";
 import { canOverlay, createOverlayIO } from "./overlay.js";
-/** The TUI's own commands, which the shared catalogue deliberately excludes. */
-const PANEL_COMMANDS = [
-    {
-        name: "/close",
-        summary: "hide a panel or the whole rail",
-        args: "<sidebar | context | model | git | tools | rail>",
-    },
-    {
-        name: "/open",
-        summary: "show a hidden panel",
-        args: "<sidebar | context | model | git | tools | rail>",
-    },
-];
 /**
- * Everything the palette offers: the shared catalogue, this shell's panel
+ * Everything the palette offers: the shared catalogue, this shell's own
  * commands, and the project's own slash commands.
  *
- * Custom commands come LAST and are labelled. `resolveSlash` consults builtins
- * first, so a custom command named `clear` can never shadow `/clear` — listing
- * it above the builtin would show an order the dispatcher does not honour.
+ * The TUI's own three are {@link TUI_ONLY_COMMANDS} rather than a copy kept
+ * here. The copy had drifted — it listed `/close` and `/open` and had never
+ * gained `/view`, so the one shell with a palette was also the one place `/view`
+ * could not be discovered.
+ *
+ * Custom commands come LAST and are labelled. A custom command can no longer be
+ * named after a reserved one at all (the loader refuses the file), so this list
+ * cannot contain two rows for one name.
  */
 export function paletteItems(slashCommands = []) {
-    const builtins = [...COMMAND_CATALOG, ...PANEL_COMMANDS].map((c) => ({
+    const builtins = [...COMMAND_CATALOG, ...TUI_ONLY_COMMANDS].map((c) => ({
         name: c.name,
         summary: c.summary,
         ...(c.args === undefined ? {} : { args: c.args }),

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);
         }