@ian-pascoe/pi-termctrl 0.5.0 → 0.7.0

package/README.md

@@ -64,10 +64,11 @@ code or signal; a poll (neither `text` nor `keys`) still returns its final scree
 
 Results contain the visible screen, the log lines that scrolled off since the
 agent's previous result, `state`, `exit_code` or `signal` once exited, and
-`changed: false` when the screen matches the previous result. Scrolled-off lines
-include lines the agent saw on an earlier screen, so a line rewritten in place,
-such as a progress line, arrives in its final form. Tools that declare
-structured output give `codemode` scripts typed values.
+`changed: false` when the screen matches the previous result. A line the agent
+saw on an earlier screen is not repeated when it scrolls off unchanged; a line
+rewritten in place since, such as a progress line or a prompt the agent typed
+at, arrives again in its final form. Tools that declare structured output give
+`codemode` scripts typed values.
 
 Scrolled-off lines are best effort: they come from termctrl's scrollback, which
 is limited (several hundred lines; fewer when lines are long) and drops its
@@ -80,11 +81,14 @@ scrollback holds before that result, its oldest lines are lost without
 `output_missing`, because termctrl does not report the trimming. Run commands
 whose complete output matters with `bash`, or redirect their output to a file.
 
-A result is limited to Pi's 2000 lines or 50 KB. The screen is kept first, from
-its bottom, and the newest scrolled-off lines fill the rest. When anything is
-cut, every line of the result goes to
-`$TMPDIR/pi-termctrl/<pid>-<id>-output-<n>.log`, named in the result's notice
-and `full_output_path`.
+Scrolled-off lines are limited by `termctrl.scrollback` (100 lines or 16 KB by
+default). Past it, a result keeps the first and last lines and puts a
+`[… N lines omitted …]` line between them. A whole result is limited to Pi's
+2000 lines or 50 KB: the screen is kept first, from its bottom, and the
+scrolled-off lines fill the rest. With `scrollback` set to `false`, only Pi's
+limits apply and the newest scrolled-off lines are kept. When anything is cut,
+every line of the result goes to `$TMPDIR/pi-termctrl/<pid>-<id>-output-<n>.log`,
+named in the result's notice and `full_output_path`.
 
 `keys` are termctrl key names: `Enter`, `Escape`, `ArrowUp`, `ArrowDown`,
 `ArrowLeft`, `ArrowRight`, `Tab`, `Shift+Tab`, `Backspace`, `Delete`, `Home`,
@@ -185,9 +189,16 @@ the session that started the entry, and wait across `/reload`.
 `/ps` opens an overlay listing every entry in the Pi process, including those of
 in-process child agents, with kind, id, owner (`root` or `child`), state and
 age, plus a live preview of the selected Terminal's screen or Background job's
-log tail. Keys: `↑`/`↓` select, `k` stops without confirmation (the agent gets an
-Exit notification), `x` removes an exited entry, `Esc` closes. The footer shows
-`N running` while anything is live. In RPC mode `/ps` sends a one-line summary;
+log tail. It uses Pi's selector frame, with a Status Mark before each entry
+(`●` running, `✓` exited cleanly, `✗` failed, `■` ended by a signal). Keys:
+`↑`/`↓` select, `k` stops without confirmation (the agent gets an Exit
+notification), `x` removes an exited entry, `Esc` closes. The footer shows
+`● termctrl N running` while anything is live.
+
+The `terminal_*` tools render like `bash` in the transcript: a header with the
+tool name and target, the last 5 screen lines (`ctrl+o` expands), and a `Took`
+footer. Exit notifications show one row per exit, marked `✓` for a clean exit and
+`■` otherwise. In RPC mode `/ps` sends a one-line summary;
 print mode has no UI but keeps the tools and notifications.
 
 ## Lifecycle
@@ -214,17 +225,19 @@ by field:
     "replaceBash": true,
     "defaultViewport": { "cols": 120, "rows": 40 },
     "exitTailLines": 20,
-    "bashTail": { "lines": 300, "bytes": 16384 }
+    "bashTail": { "lines": 300, "bytes": 16384 },
+    "scrollback": { "lines": 100, "bytes": 16384 }
   }
 }
 ```
 
-| Setting           | Default                        | Meaning                                                                                                |
-| ----------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| `replaceBash`     | `true`                         | Replace `bash` to enable Background jobs                                                               |
-| `defaultViewport` | `{ cols: 120, rows: 40 }`      | Terminal size; each dimension 1 to 1000                                                                |
-| `exitTailLines`   | `20`                           | Lines of output in an Exit notification, 0–1000                                                        |
-| `bashTail`        | `{ lines: 300, bytes: 16384 }` | Model-visible `bash` output tail: `lines` 1–2000, `bytes` 1–51200; `false` or `0` restores Pi's limits |
+| Setting           | Default                        | Meaning                                                                                                    |
+| ----------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `replaceBash`     | `true`                         | Replace `bash` to enable Background jobs                                                                   |
+| `defaultViewport` | `{ cols: 120, rows: 40 }`      | Terminal size; each dimension 1 to 1000                                                                    |
+| `exitTailLines`   | `20`                           | Lines of output in an Exit notification, 0–1000                                                            |
+| `bashTail`        | `{ lines: 300, bytes: 16384 }` | Model-visible `bash` output tail: `lines` 1–2000, `bytes` 1–51200; `false` or `0` restores Pi's limits     |
+| `scrollback`      | `{ lines: 100, bytes: 16384 }` | Scrolled-off lines in a Terminal result, keeping the first and last; same ranges and opt-out as `bashTail` |
 
 Invalid values keep the lower layer and unknown keys produce warnings at session
 start. Use `/reload` after editing settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -34,11 +34,12 @@
     "provenance": true
   },
   "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.5.0",
     "@kitlangton/terminal-control": "^1.2.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {

package/skills/pi-termctrl/SKILL.md

@@ -11,7 +11,7 @@ disable-model-invocation: true
 2. If `terminal_start` is missing, check the startup diagnostic. Confirm the platform has a packaged `termctrl` binary or that `TERMCTRL_BINARY` names an executable one.
 3. If `bash` lacks the `background` parameter, check `termctrl.replaceBash` and look for another extension that also registers `bash`.
 4. Call `terminal_list` to inspect live and exited Terminals and Background jobs. Ask the user to open `/ps` for a live preview.
-5. If `bash` results are shorter than expected, check `termctrl.bashTail` (default 300 lines or 16 KB; `false` restores Pi's limits); the result's notice names the limits and the file holding every line.
+5. If `bash` results are shorter than expected, check `termctrl.bashTail` (default 300 lines or 16 KB; `false` restores Pi's limits); the result's notice names the limits and the file holding every line. If a Terminal result's `scrolled_off` shows `[… N lines omitted …]`, check `termctrl.scrollback` (default 100 lines or 16 KB) the same way.
 6. Classify the failure as settings, binary resolution, `bash` conflict, cap, or process behaviour.
 7. For a requested change, edit one settings layer, validate its JSON, and reload Pi. Finish when the expected tools appear or one exact cause remains.
 

package/src/bash-replacement.ts

@@ -19,9 +19,10 @@ import {
   type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
+import { noticeText } from "@ian-pascoe/pi-utils/ui";
 import { Type, type TSchema } from "typebox";
 import { KILLED_EXIT, TermctrlRegistry } from "./termctrl-registry.js";
-import type { BashTailLimits } from "./pi-termctrl-settings.js";
+import type { LineByteLimits } from "./pi-termctrl-settings.js";
 import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
 import type { TerminalExit } from "./terminal-driver.js";
 
@@ -264,7 +265,10 @@ export class RunningBashCalls {
       try {
         call.background(this.registry());
       } catch (error) {
-        ui.notify(error instanceof Error ? error.message : String(error), "warning");
+        ui.notify(
+          noticeText("Termctrl", error instanceof Error ? error.message : String(error)),
+          "warning",
+        );
       }
     }
   }
@@ -286,7 +290,7 @@ export interface BashReplacementOptions {
    * Limits on the model-visible tail of a result and of "output so far"; undefined keeps Pi's own
    * limits. Pi's `bash` accepts no limits, so the replacement tightens what Pi returns.
    */
-  readonly bashTail?: BashTailLimits | undefined;
+  readonly bashTail?: LineByteLimits | undefined;
   /** Builds Pi's `bash` definition; tests wrap it to observe what reaches Pi's accumulator. */
   readonly definitionFactory?: typeof createBashToolDefinition;
 }
@@ -377,7 +381,7 @@ function limitForegroundText(
   call: BashCall,
   piText: string,
   piDetails: BashToolDetails | undefined,
-  limits: BashTailLimits,
+  limits: LineByteLimits,
   hasStatus: boolean,
 ) {
   const output = call.foregroundOutput();
@@ -403,7 +407,7 @@ function limitForegroundText(
 function backgroundResult(
   outcome: BackgroundOutcome,
   startedAt: number,
-  limits: BashTailLimits | undefined,
+  limits: LineByteLimits | undefined,
 ) {
   const truncation = truncateBuffered(outcome.output, outcome.dropped, limits ?? {});
   let text = truncation.content;
@@ -427,7 +431,7 @@ function backgroundResult(
 
 type BashResult = Awaited<ReturnType<ReturnType<typeof createBashToolDefinition>["execute"]>>;
 
-function limitResult(call: BashCall, result: BashResult, limits: BashTailLimits): BashResult {
+function limitResult(call: BashCall, result: BashResult, limits: LineByteLimits): BashResult {
   const [first] = result.content;
   if (first?.type !== "text") return result;
   const limited = limitForegroundText(
@@ -445,7 +449,7 @@ function limitResult(call: BashCall, result: BashResult, limits: BashTailLimits)
   };
 }
 
-function limitError(call: BashCall, error: Error, limits: BashTailLimits): Error {
+function limitError(call: BashCall, error: Error, limits: LineByteLimits): Error {
   // Only Pi's output-plus-status messages are rewritten; any other error passes through.
   if (!PI_STATUS.test(error.message)) return error;
   const limited = limitForegroundText(call, error.message, undefined, limits, true);
@@ -453,7 +457,7 @@ function limitError(call: BashCall, error: Error, limits: BashTailLimits): Error
 }
 
 /** Pi's description names its own limits; name the ones in force instead. */
-function describeTail(description: string, limits: BashTailLimits | undefined): string {
+function describeTail(description: string, limits: LineByteLimits | undefined): string {
   if (limits === undefined) return description;
   const piLimits = `${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB`;
   const ours = `${limits.maxLines} lines or ${formatSize(limits.maxBytes)}`;

package/src/exit-notification.ts

@@ -1,5 +1,14 @@
 import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
 import { Text, type Component } from "@earendil-works/pi-tui";
+import {
+  COLLAPSED_LINES,
+  customMessageBox,
+  expandHint,
+  joinInline,
+  previewBody,
+  statusMark,
+  summaryExpandHint,
+} from "@ian-pascoe/pi-utils/ui";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import type { ExitNotice } from "./termctrl-registry.js";
@@ -110,19 +119,55 @@ function messageText(content: RenderedMessage["content"]): string {
   return content.map((part) => (part.type === "text" ? part.text : "")).join("");
 }
 
-/** Compact renderer: one line per exit, with the full text when expanded. */
+type MessageTheme = Parameters<ExitNotificationRenderer>[2];
+
+function exitRow(theme: MessageTheme, exit: ExitNotificationDetails["exits"][number]): string {
+  const done = exit.exit_code === 0 && exit.signal === null;
+  const body = (text: string) => theme.fg("customMessageText", text);
+  const status = describeExitStatus({ code: exit.exit_code, signal: exit.signal });
+  return `${statusMark(theme, done ? "done" : "stopped")} ${body(theme.bold(exit.id))} ${joinInline(
+    theme,
+    [body(status), body(formatDuration(exit.duration_ms)), theme.fg("muted", exit.command)],
+  )}`;
+}
+
+/** The Collapsed View's rows: at most 10, then the Expand Hint for the rest or for the full text. */
+function collapsedRows(theme: MessageTheme, rows: readonly string[]): string[] {
+  const hidden = rows.length - COLLAPSED_LINES.fallback;
+  if (hidden > 0) return [...rows.slice(0, COLLAPSED_LINES.fallback), expandHint(theme, hidden)];
+  const last = rows.length - 1;
+  return rows.map((row, index) => (index === last ? `${row}${summaryExpandHint(theme)}` : row));
+}
+
+/** `exit`, or `N exits` when several Terminals or Background jobs ended together. */
+function exitHeading(details: ExitNotificationDetails | undefined): string {
+  const count = Value.Check(ExitNotificationDetailsSchema, details) ? details.exits.length : 1;
+  return count === 1 ? "exit" : `${count} exits`;
+}
+
+/**
+ * Pi's custom-message look: a `customMessageBg` box under a bold `[termctrl] exit` label.
+ * Collapsed, it shows one Status Mark row per exit; expanded, the full text.
+ */
 export const renderExitNotification: ExitNotificationRenderer = (
   message,
   options,
   theme,
 ): Component => {
-  if (options.expanded || !Value.Check(ExitNotificationDetailsSchema, message.details)) {
-    return new Text(theme.fg("muted", messageText(message.content)), options.outputPad, 0);
-  }
-  const lines = message.details.exits.map((exit) => {
-    const failed = exit.exit_code !== 0 || exit.signal !== null;
-    const status = describeExitStatus({ code: exit.exit_code, signal: exit.signal });
-    return `${theme.fg(failed ? "warning" : "success", "■")} ${theme.bold(exit.id)} ${status} · ${formatDuration(exit.duration_ms)} · ${theme.fg("muted", exit.command)}`;
-  });
-  return new Text(lines.join("\n"), options.outputPad, 0);
+  const details = message.details;
+  const rows =
+    !options.expanded && Value.Check(ExitNotificationDetailsSchema, details)
+      ? collapsedRows(
+          theme,
+          details.exits.map((exit) => exitRow(theme, exit)),
+        )
+      : previewBody(theme, messageText(message.content).replace(/\n+$/u, "").split("\n"), {
+          limit: COLLAPSED_LINES.fallback,
+          expanded: options.expanded,
+          color: "customMessageText",
+        });
+  const heading = theme.fg("customMessageText", exitHeading(details));
+  return customMessageBox(theme, { outputPad: options.outputPad, source: "termctrl", heading }, [
+    new Text(rows.join("\n"), 0, 0),
+  ]);
 };

package/src/pi-termctrl-extension.ts

@@ -7,6 +7,7 @@ import {
   type ExtensionFactory,
   type SessionShutdownEvent,
 } from "@earendil-works/pi-coding-agent";
+import { expandMessageOnClick, noticeText } from "@ian-pascoe/pi-utils/ui";
 import { createBashReplacement, RunningBashCalls } from "./bash-replacement.js";
 import {
   EXIT_NOTIFICATION_TYPE,
@@ -17,7 +18,11 @@ import { TermctrlPsController } from "./ps-panel.js";
 import { resolveTermctrlBinary, type TermctrlBinaryResolution } from "./termctrl-binary.js";
 import { createTermctrlDriver } from "./termctrl-driver.js";
 import { TermctrlRegistry } from "./termctrl-registry.js";
-import { resolveTermctrlSettings, type TerminalViewport } from "./pi-termctrl-settings.js";
+import {
+  resolveTermctrlSettings,
+  type LineByteLimits,
+  type TerminalViewport,
+} from "./pi-termctrl-settings.js";
 import type { TerminalDriver } from "./terminal-driver.js";
 import {
   createTerminalListTool,
@@ -41,6 +46,7 @@ interface ActiveSession {
   readonly ps: TermctrlPsController;
   readonly shell: () => TerminalShell;
   readonly viewport: TerminalViewport;
+  readonly scrollback: LineByteLimits | undefined;
   readonly exitTailLines: number;
 }
 
@@ -79,7 +85,10 @@ class PiTermctrlController {
   }
 
   register(): void {
-    this.pi.registerMessageRenderer(EXIT_NOTIFICATION_TYPE, renderExitNotification);
+    this.pi.registerMessageRenderer(
+      EXIT_NOTIFICATION_TYPE,
+      expandMessageOnClick(renderExitNotification),
+    );
     this.pi.registerCommand("ps", {
       description: "Show and stop Terminals and Background jobs",
       handler: async () => {
@@ -91,6 +100,7 @@ class PiTermctrlController {
         registry: this.registry,
         shell: () => this.session().shell(),
         viewport: () => this.session().viewport,
+        scrollback: () => this.session().scrollback,
       };
       this.pi.registerTool(createTerminalStartTool(runtime));
       this.pi.registerTool(createTerminalSendTool(runtime));
@@ -120,7 +130,12 @@ class PiTermctrlController {
   }
 
   private registerManagementTools(): void {
-    this.pi.registerTool(createTerminalStopTool(this.registry));
+    this.pi.registerTool(
+      createTerminalStopTool({
+        registry: this.registry,
+        scrollback: () => this.session().scrollback,
+      }),
+    );
     this.pi.registerTool(createTerminalListTool(this.registry));
     this.pi.registerTool(
       createTerminalWaitTool({
@@ -143,7 +158,10 @@ class PiTermctrlController {
     );
     const settings = resolveTermctrlSettings(settingsManager);
     if (settings.warnings.length > 0) {
-      context.ui.notify(`Pi Termctrl settings:\n- ${settings.warnings.join("\n- ")}`, "warning");
+      context.ui.notify(
+        noticeText("Termctrl", `Settings:\n- ${settings.warnings.join("\n- ")}`),
+        "warning",
+      );
     }
     const registry = this.registry;
     const owner = context.sessionManager.getSessionId();
@@ -167,7 +185,10 @@ class PiTermctrlController {
     const commandPrefix = settingsManager.getShellCommandPrefix();
     if (this.binary.kind === "missing") {
       context.ui.notify(
-        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
+        noticeText(
+          "Termctrl",
+          `Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
+        ),
         "warning",
       );
       if (settings.replaceBash) this.registerManagementTools();
@@ -195,6 +216,7 @@ class PiTermctrlController {
         return { shell: shell.shell, args: shell.args, commandPrefix };
       },
       viewport: settings.defaultViewport,
+      scrollback: settings.scrollback,
       exitTailLines: settings.exitTailLines,
     };
   }

package/src/pi-termctrl-settings.ts

@@ -20,16 +20,24 @@ export interface TerminalViewport {
   readonly rows: number;
 }
 
-/** The most lines and bytes of the model-visible `bash` output: a foreground result or the output so far of a backgrounding one. */
-export type BashTailLimits = Readonly<Required<TruncationOptions>>;
+/** The most lines and bytes of model-visible output that a setting allows. */
+export type LineByteLimits = Readonly<Required<TruncationOptions>>;
 
 /** The effective `settings.termctrl` values after layering global and trusted project settings. */
 export interface ResolvedTermctrlSettings {
   readonly replaceBash: boolean;
   readonly defaultViewport: TerminalViewport;
   readonly exitTailLines: number;
-  /** Limits on the model-visible `bash` tail; undefined restores Pi's own limits. */
-  readonly bashTail: BashTailLimits | undefined;
+  /**
+   * Limits on the model-visible `bash` output: a foreground result or the output so far of a
+   * backgrounding one. Undefined restores Pi's own limits.
+   */
+  readonly bashTail: LineByteLimits | undefined;
+  /**
+   * Limits on the scrolled-off lines a Terminal result shows, kept from their start and end.
+   * Undefined restores Pi's own limits on the whole result.
+   */
+  readonly scrollback: LineByteLimits | undefined;
   readonly warnings: readonly string[];
 }
 
@@ -44,31 +52,42 @@ export interface TermctrlSettingsReader {
   getProjectSettings(): TermctrlSettingsDocumentInput;
 }
 
+/** The settings that limit model-visible output. */
+type LineByteLimitKey = "bashTail" | "scrollback";
+
+/** One layer's value for a `bashTail` or `scrollback` setting. */
+interface LineByteLimitsLayer {
+  enabled?: boolean;
+  lines?: number;
+  bytes?: number;
+}
+
 interface TermctrlLayer {
   replaceBash?: boolean;
   cols?: number;
   rows?: number;
   exitTailLines?: number;
-  bashTailEnabled?: boolean;
-  bashTailLines?: number;
-  bashTailBytes?: number;
+  bashTail?: LineByteLimitsLayer;
+  scrollback?: LineByteLimitsLayer;
 }
 
-export const DEFAULT_TERMCTRL_SETTINGS: Omit<ResolvedTermctrlSettings, "warnings" | "bashTail"> & {
-  readonly bashTail: BashTailLimits;
-} = {
+export const DEFAULT_TERMCTRL_SETTINGS: Omit<
+  ResolvedTermctrlSettings,
+  "warnings" | LineByteLimitKey
+> & { readonly [key in LineByteLimitKey]: LineByteLimits } = {
   replaceBash: true,
   defaultViewport: { cols: 120, rows: 40 },
   exitTailLines: 20,
   bashTail: { maxLines: 300, maxBytes: 16 * 1024 },
+  scrollback: { maxLines: 100, maxBytes: 16 * 1024 },
 };
 
 const JsonObjectSchema = Type.Record(Type.String(), Type.Any());
 const SettingsDocumentSchema = Type.Object({ termctrl: Type.Optional(Type.Any()) });
 const BooleanSchema = Type.Boolean();
 const ViewportDimensionSchema = Type.Integer({ minimum: 1, maximum: VIEWPORT_LIMIT });
-const BashTailLinesSchema = Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_LINES });
-const BashTailBytesSchema = Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_BYTES });
+const LimitLinesSchema = Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_LINES });
+const LimitBytesSchema = Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_BYTES });
 const ExitTailLinesSchema = Type.Integer({ minimum: 0, maximum: EXIT_TAIL_LIMIT });
 
 function isJsonObject(value: JsonValue): value is JsonObject {
@@ -103,7 +122,8 @@ function readLayer(
         else warnings.push(`${path}: expected an integer from 0 to ${EXIT_TAIL_LIMIT}`);
         break;
       case "bashTail":
-        readBashTail(value, path, layer, warnings);
+      case "scrollback":
+        layer[key] = readLineByteLimits(value, path, warnings);
         break;
       case "defaultViewport":
         readViewport(value, path, layer, warnings);
@@ -130,29 +150,28 @@ function readViewport(value: JsonValue, path: string, layer: TermctrlLayer, warn
   }
 }
 
-function readBashTail(value: JsonValue, path: string, layer: TermctrlLayer, warnings: string[]) {
-  if (Value.Check(BooleanSchema, value)) {
-    layer.bashTailEnabled = value;
-    return;
-  }
-  if (value === 0) {
-    layer.bashTailEnabled = false;
-    return;
-  }
+function readLineByteLimits(
+  value: JsonValue,
+  path: string,
+  warnings: string[],
+): LineByteLimitsLayer {
+  if (Value.Check(BooleanSchema, value)) return { enabled: value };
+  if (value === 0) return { enabled: false };
   if (!isJsonObject(value)) {
     warnings.push(`${path}: expected a boolean, 0, or a JSON object`);
-    return;
+    return {};
   }
+  const limits: LineByteLimitsLayer = {};
   let valid = 0;
   for (const [key, limit] of Object.entries(value)) {
     if (key === "lines") {
-      if (Value.Check(BashTailLinesSchema, limit)) {
-        layer.bashTailLines = limit;
+      if (Value.Check(LimitLinesSchema, limit)) {
+        limits.lines = limit;
         valid++;
       } else warnings.push(`${path}.lines: expected an integer from 1 to ${DEFAULT_MAX_LINES}`);
     } else if (key === "bytes") {
-      if (Value.Check(BashTailBytesSchema, limit)) {
-        layer.bashTailBytes = limit;
+      if (Value.Check(LimitBytesSchema, limit)) {
+        limits.bytes = limit;
         valid++;
       } else warnings.push(`${path}.bytes: expected an integer from 1 to ${DEFAULT_MAX_BYTES}`);
     } else {
@@ -160,7 +179,24 @@ function readBashTail(value: JsonValue, path: string, layer: TermctrlLayer, warn
     }
   }
   // An object with only invalid fields must not override a lower layer's opt-out.
-  if (valid > 0 || Object.keys(value).length === 0) layer.bashTailEnabled = true;
+  if (valid > 0 || Object.keys(value).length === 0) limits.enabled = true;
+  return limits;
+}
+
+/** Layer a `bashTail` or `scrollback` setting: the project's fields over the global ones, over the defaults. */
+function resolveLineByteLimits(
+  key: LineByteLimitKey,
+  globalLayer: TermctrlLayer,
+  projectLayer: TermctrlLayer,
+): LineByteLimits | undefined {
+  const global = globalLayer[key];
+  const project = projectLayer[key];
+  if (!(project?.enabled ?? global?.enabled ?? true)) return undefined;
+  const defaults = DEFAULT_TERMCTRL_SETTINGS[key];
+  return {
+    maxLines: project?.lines ?? global?.lines ?? defaults.maxLines,
+    maxBytes: project?.bytes ?? global?.bytes ?? defaults.maxBytes,
+  };
 }
 
 /** Resolve global and trusted-project `termctrl` settings, keeping valid fields around warnings. */
@@ -177,15 +213,8 @@ export function resolveTermctrlSettings(reader: TermctrlSettingsReader): Resolve
     },
     exitTailLines:
       projectLayer.exitTailLines ?? globalLayer.exitTailLines ?? defaults.exitTailLines,
-    bashTail:
-      (projectLayer.bashTailEnabled ?? globalLayer.bashTailEnabled ?? true)
-        ? {
-            maxLines:
-              projectLayer.bashTailLines ?? globalLayer.bashTailLines ?? defaults.bashTail.maxLines,
-            maxBytes:
-              projectLayer.bashTailBytes ?? globalLayer.bashTailBytes ?? defaults.bashTail.maxBytes,
-          }
-        : undefined,
+    bashTail: resolveLineByteLimits("bashTail", globalLayer, projectLayer),
+    scrollback: resolveLineByteLimits("scrollback", globalLayer, projectLayer),
     warnings,
   };
 }