@ian-pascoe/pi-termctrl 0.5.0 → 0.6.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`,
@@ -214,17 +218,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.6.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [

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

@@ -21,7 +21,7 @@ import {
 import { matchesKey } from "@earendil-works/pi-tui";
 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";
 
@@ -286,7 +286,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 +377,7 @@ function limitForegroundText(
   call: BashCall,
   piText: string,
   piDetails: BashToolDetails | undefined,
-  limits: BashTailLimits,
+  limits: LineByteLimits,
   hasStatus: boolean,
 ) {
   const output = call.foregroundOutput();
@@ -403,7 +403,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 +427,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 +445,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 +453,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/pi-termctrl-extension.ts

@@ -17,7 +17,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 +45,7 @@ interface ActiveSession {
   readonly ps: TermctrlPsController;
   readonly shell: () => TerminalShell;
   readonly viewport: TerminalViewport;
+  readonly scrollback: LineByteLimits | undefined;
   readonly exitTailLines: number;
 }
 
@@ -91,6 +96,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 +126,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({
@@ -195,6 +206,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,
   };
 }

package/src/termctrl-registry.ts

@@ -13,7 +13,7 @@ import type { TerminalViewport } from "./pi-termctrl-settings.js";
 /** The `globalThis` key every registry version shares. Its value always satisfies {@link RegistrySlot}. */
 export const REGISTRY_KEY = Symbol.for("@ian-pascoe/pi-termctrl/registry");
 /** Bump on any change to the state's shape: a reloaded module must not adopt an older shape. */
-export const REGISTRY_VERSION = 5;
+export const REGISTRY_VERSION = 6;
 
 /** Live Terminals plus Background jobs allowed across the whole process. */
 export const LIVE_ENTRY_CAP = 16;
@@ -84,6 +84,11 @@ export interface TerminalEntry extends EntryBase {
    * last lines before the cursor, or, while the cursor is 0, the log's first line.
    */
   logAnchor: readonly string[];
+  /**
+   * The screen rows the agent last received, which start at `logCursor` in the log; `undefined`
+   * marks a row cut from that result. Lines that scroll off unchanged are not reported again.
+   */
+  seenRows: readonly (string | undefined)[];
 }
 
 /** A `bash` command moved to the background. */
@@ -463,6 +468,7 @@ export class TermctrlRegistry {
         lastScreen: undefined,
         logCursor: 0,
         logAnchor: [],
+        seenRows: [],
       };
       this.state.entries.set(id, entry);
       this.syncWatcher();

package/src/terminal-tools.ts

@@ -7,7 +7,6 @@ import {
   formatSize,
   truncateTail,
   type ExtensionToolContext,
-  type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import type { Key } from "@kitlangton/terminal-control";
 import { Type, type Static } from "typebox";
@@ -19,7 +18,7 @@ import type {
 } from "./termctrl-registry.js";
 import { describeExitStatus, formatExitNotice, lastLines } from "./exit-notification.js";
 import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
-import type { TerminalViewport } from "./pi-termctrl-settings.js";
+import type { LineByteLimits, TerminalViewport } from "./pi-termctrl-settings.js";
 import type { TerminalExit, TerminalSnapshot } from "./terminal-driver.js";
 import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
@@ -73,8 +72,13 @@ export interface TerminalToolRuntime {
   readonly registry: TermctrlRegistry;
   readonly shell: () => TerminalShell;
   readonly viewport: () => TerminalViewport;
+  /** The `termctrl.scrollback` limits; undefined leaves only Pi's limits on the whole result. */
+  readonly scrollback: () => LineByteLimits | undefined;
 }
 
+/** What building a Terminal result reads; `terminal_stop` also stops Background jobs and needs only this. */
+export type TerminalResultRuntime = Pick<TerminalToolRuntime, "registry" | "scrollback">;
+
 const TerminalStateSchema = Type.Union([Type.Literal("running"), Type.Literal("exited")]);
 
 const SettleReasonSchema = Type.Union(
@@ -405,10 +409,11 @@ function locateScreen(lines: readonly string[], screen: readonly string[], floor
 
 /**
  * Lines that left the screen since the previous result, advancing the Terminal's log cursor.
- * Lines still on the result's screen stay unread, so a line rewritten after the agent saw it, such
- * as a progress line, is reported in its final form once it scrolls off. When the cursor cannot be
- * found again, because termctrl dropped lines the agent never received or the screen was cleared,
- * every line termctrl still holds is reported and the result says that earlier output is missing.
+ * Lines still on the result's screen stay unread. Once they scroll off, a line the agent saw is
+ * skipped if it is unchanged, while a line rewritten since, such as a progress line or a prompt the
+ * agent typed at, is reported in its final form. When the cursor cannot be found again, because
+ * termctrl dropped lines the agent never received or the screen was cleared, every line termctrl
+ * still holds is reported and the result says that earlier output is missing.
  */
 async function takeScrolledOff(entry: TerminalEntry, screen: string): Promise<ScrolledOff> {
   let logs: string;
@@ -421,7 +426,10 @@ async function takeScrolledOff(entry: TerminalEntry, screen: string): Promise<Sc
   const located = locateCursor(lines, entry.logCursor, entry.logAnchor);
   const screenLines = screen === "" ? [] : screen.split("\n");
   const boundary = locateScreen(lines, screenLines, located ?? 0);
-  const scrolled = lines.slice(Math.min(located ?? 0, boundary), boundary);
+  const seen = located === undefined ? [] : entry.seenRows;
+  const scrolled = lines
+    .slice(Math.min(located ?? 0, boundary), boundary)
+    .filter((line, row) => line !== seen[row]);
   entry.logCursor = boundary;
   entry.logAnchor =
     boundary > 0 ? lines.slice(Math.max(0, boundary - ANCHOR_LINES), boundary) : lines.slice(0, 1);
@@ -442,35 +450,135 @@ interface FittedOutput {
   readonly notice?: string;
 }
 
-function emptyTruncation(content: string): TruncationResult {
-  const totalLines = content === "" ? 0 : content.split("\n").length;
+/** The scrolled-off lines a result shows. */
+interface ShownScrolled {
+  readonly content: string;
+  readonly truncated: boolean;
+  readonly totalLines: number;
+  readonly outputLines: number;
+  /** Describes a cut to the `termctrl.scrollback` limits; absent for a cut to Pi's limits alone. */
+  readonly summary?: string;
+}
+
+function omissionMarker(count: number): string {
+  return `[… ${count} lines omitted …]`;
+}
+
+function describeLimits(limits: LineByteLimits): string {
+  return `(${formatSize(limits.maxBytes)} or ${limits.maxLines} line limit)`;
+}
+
+/**
+ * Keep the first and last scrolled-off lines within `limits`, splitting them evenly and marking
+ * the omitted lines between them on a line of its own. Returns `undefined` when the limits leave
+ * no room for a line beside the marker.
+ */
+function keepStartAndEnd(
+  lines: readonly string[],
+  limits: LineByteLimits,
+): ShownScrolled | undefined {
+  // Each kept line is counted with the newline that joins it to the marker or its neighbour.
+  const bodyLines = limits.maxLines - 1;
+  const bodyBytes = limits.maxBytes - Buffer.byteLength(omissionMarker(lines.length), "utf8");
+  if (bodyLines < 1 || bodyBytes < 2) return undefined;
+  const head: string[] = [];
+  let headBytes = 0;
+  const headLines = Math.ceil(bodyLines / 2);
+  const headByteLimit = Math.floor(bodyBytes / 2);
+  for (const line of lines) {
+    const size = Buffer.byteLength(line, "utf8") + 1;
+    if (head.length >= headLines || headBytes + size > headByteLimit) break;
+    head.push(line);
+    headBytes += size;
+  }
+  const tail: string[] = [];
+  let tailBytes = 0;
+  let lastLineCut = false;
+  const tailByteLimit = bodyBytes - headBytes;
+  for (let index = lines.length - 1; index >= head.length; index--) {
+    if (tail.length >= bodyLines - head.length) break;
+    const line = lines[index] ?? "";
+    const size = Buffer.byteLength(line, "utf8") + 1;
+    if (tailBytes + size > tailByteLimit) {
+      // A last line too long for the limits on its own still shows its end.
+      if (head.length === 0 && tail.length === 0) {
+        tail.push(truncateTail(line, { maxLines: 1, maxBytes: tailByteLimit - 1 }).content);
+        lastLineCut = true;
+      }
+      break;
+    }
+    tail.unshift(line);
+    tailBytes += size;
+  }
+  const omitted = lines.length - head.length - tail.length;
+  const kept = omitted > 0 ? [...head, omissionMarker(omitted), ...tail] : [...head, ...tail];
+  const shown = lastLineCut
+    ? `the end of scrolled-off line ${lines.length} of ${lines.length}`
+    : `the first ${head.length} and last ${tail.length} of ${lines.length} scrolled-off lines`;
+  return {
+    content: kept.join("\n"),
+    truncated: true,
+    totalLines: lines.length,
+    outputLines: head.length + tail.length,
+    summary: `Showing ${shown} ${describeLimits(limits)}.`,
+  };
+}
+
+/** Keep the newest scrolled-off lines within `limits`. */
+function keepNewest(lines: readonly string[], limits: LineByteLimits): ShownScrolled {
+  const newest = truncateTail(lines.join("\n"), limits);
+  return {
+    content: newest.content,
+    truncated: newest.truncated,
+    totalLines: lines.length,
+    outputLines: newest.outputLines,
+  };
+}
+
+/**
+ * Fit the scrolled-off lines into the lines and bytes the screen left. With `termctrl.scrollback`
+ * limits, a cut keeps their start and end; without them, their newest lines.
+ */
+function fitScrolled(
+  lines: readonly string[],
+  room: LineByteLimits,
+  scrollback: LineByteLimits | undefined,
+): ShownScrolled {
+  if (room.maxLines <= 0 || room.maxBytes <= 0) {
+    return { content: "", truncated: lines.length > 0, totalLines: lines.length, outputLines: 0 };
+  }
+  if (scrollback === undefined) return keepNewest(lines, room);
+  const limits = {
+    maxLines: Math.min(scrollback.maxLines, room.maxLines),
+    maxBytes: Math.min(scrollback.maxBytes, room.maxBytes),
+  };
+  const text = lines.join("\n");
+  if (lines.length <= limits.maxLines && Buffer.byteLength(text, "utf8") <= limits.maxBytes) {
+    return { content: text, truncated: false, totalLines: lines.length, outputLines: lines.length };
+  }
+  const kept = keepStartAndEnd(lines, limits);
+  if (kept !== undefined) return kept;
+  const newest = keepNewest(lines, limits);
   return {
-    content: "",
-    truncated: content !== "",
-    truncatedBy: content === "" ? null : "bytes",
-    totalLines,
-    totalBytes: Buffer.byteLength(content, "utf8"),
-    outputLines: 0,
-    outputBytes: 0,
-    lastLinePartial: false,
-    firstLineExceedsLimit: false,
-    maxLines: 0,
-    maxBytes: 0,
+    ...newest,
+    summary: `Showing the last ${newest.outputLines} of ${lines.length} scrolled-off lines ${describeLimits(limits)}.`,
   };
 }
 
 /**
  * Fit a result into Pi's 2000-line and 50 KB limits. The screen is kept first, from its bottom;
- * the newest scrolled-off lines fill what is left. When anything is cut, every line of the result
- * goes to a full output file that lasts until the owner's session shuts down.
+ * the scrolled-off lines fill what is left, within the `termctrl.scrollback` limits. When anything
+ * is cut, every line of the result goes to a full output file that lasts until the owner's session
+ * shuts down.
  */
 async function fitOutput(
   registry: TermctrlRegistry,
   entry: TerminalEntry,
   screen: string,
   scrolled: ScrolledOff,
+  scrollback: LineByteLimits | undefined,
 ): Promise<FittedOutput> {
-  const fitted = await truncateOutput(registry, entry, screen, scrolled.lines);
+  const fitted = await truncateOutput(registry, entry, screen, scrolled.lines, scrollback);
   if (!scrolled.gap) return { ...fitted, gap: false };
   const notice = fitted.notice === undefined ? GAP_NOTICE : `${GAP_NOTICE}\n${fitted.notice}`;
   return { ...fitted, gap: true, notice };
@@ -481,24 +589,29 @@ async function truncateOutput(
   entry: TerminalEntry,
   screen: string,
   scrolled: readonly string[],
+  scrollback: LineByteLimits | undefined,
 ): Promise<Omit<FittedOutput, "gap">> {
   const limits = { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES };
-  const scrolledText = scrolled.join("\n");
   const shownScreen = truncateTail(screen, limits);
-  const lineBudget = limits.maxLines - shownScreen.outputLines;
-  // One byte for the newline that joins the scrolled-off lines to the screen.
-  const byteBudget = limits.maxBytes - shownScreen.outputBytes - 1;
-  const shownScrolled =
-    lineBudget > 0 && byteBudget > 0
-      ? truncateTail(scrolledText, { maxLines: lineBudget, maxBytes: byteBudget })
-      : emptyTruncation(scrolledText);
+  // A screen cut to fit leaves no room. One byte for the newline that joins the scrolled-off lines
+  // to the screen.
+  const room = shownScreen.truncated
+    ? { maxLines: 0, maxBytes: 0 }
+    : {
+        maxLines: limits.maxLines - shownScreen.outputLines,
+        maxBytes: limits.maxBytes - shownScreen.outputBytes - 1,
+      };
+  const shownScrolled = fitScrolled(scrolled, room, scrollback);
+  const scrolledText = scrolled.join("\n");
   if (!shownScreen.truncated && !shownScrolled.truncated)
     return { screen, scrolledOff: scrolledText };
 
   const total = shownScrolled.totalLines + shownScreen.totalLines;
   const shown = shownScrolled.outputLines + shownScreen.outputLines;
   const fitted = { screen: shownScreen.content, scrolledOff: shownScrolled.content };
-  const range = `[Showing lines ${total - shown + 1}-${total} of ${total} (${formatSize(DEFAULT_MAX_BYTES)} or ${DEFAULT_MAX_LINES} line limit).`;
+  const summary =
+    shownScrolled.summary ??
+    `Showing lines ${total - shown + 1}-${total} of ${total} (${formatSize(DEFAULT_MAX_BYTES)} or ${DEFAULT_MAX_LINES} line limit).`;
   const directory = termctrlTemporaryDirectory();
   let path: string;
   try {
@@ -509,9 +622,21 @@ async function truncateOutput(
     await writeFile(path, full, { encoding: "utf8", mode: 0o600 });
   } catch (cause) {
     const reason = cause instanceof Error ? cause.message : String(cause);
-    return { ...fitted, notice: `${range} The full output could not be saved: ${reason}]` };
+    return { ...fitted, notice: `[${summary} The full output could not be saved: ${reason}]` };
   }
-  return { ...fitted, fullOutputPath: path, notice: `${range} Full output: ${path}]` };
+  return { ...fitted, fullOutputPath: path, notice: `[${summary} Full output: ${path}]` };
+}
+
+/**
+ * The rows of `screen` that the agent received, aligned with `screen`: rows cut from the top of a
+ * screen too large for the result, or shortened to fit it, are `undefined`.
+ */
+function shownRows(screen: string, shown: string): (string | undefined)[] {
+  const rows = screen === "" ? [] : screen.split("\n");
+  if (shown === screen) return rows;
+  const kept = shown === "" ? [] : shown.split("\n");
+  const cut = rows.length - kept.length;
+  return rows.map((row, index) => (kept[index - cut] === row ? row : undefined));
 }
 
 /** Says that `wait_for_text` was not seen when its wait timed out. */
@@ -544,7 +669,7 @@ function formatTerminalText(
 
 /** Build the agent's view of a Terminal after a wait, recording the exit as seen. */
 async function terminalResult(
-  registry: TermctrlRegistry,
+  { registry, scrollback }: TerminalResultRuntime,
   entry: TerminalEntry,
   snapshot: TerminalSnapshot | undefined,
   settleReason: SettleReason,
@@ -555,7 +680,9 @@ async function terminalResult(
     entry.state === "running" || snapshot !== undefined
       ? await takeScrolledOff(entry, screen)
       : NOTHING_SCROLLED;
-  const output = await fitOutput(registry, entry, screen, scrolled);
+  const output = await fitOutput(registry, entry, screen, scrolled, scrollback());
+  // The screen now starts at the log cursor; when the cursor did not move, neither do the rows.
+  if (scrolled !== NOTHING_SCROLLED) entry.seenRows = shownRows(screen, output.screen);
   if (snapshot?.state === "exited") {
     registry.terminalExited(entry.id, snapshot.exit ?? { code: null, signal: null }, screen, true);
   }
@@ -732,7 +859,7 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
           baseline: undefined,
           signal,
         });
-        return terminalResult(runtime.registry, entry, snapshot, reason);
+        return terminalResult(runtime, entry, snapshot, reason);
       });
     },
   });
@@ -785,7 +912,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
       const hasInput = (params.text ?? "") !== "" || keys.length > 0;
       return driveTerminal(runtime.registry, entry, signal, async () => {
         if (entry.state === "exited") {
-          if (!hasInput) return terminalResult(runtime.registry, entry, undefined, "exited");
+          if (!hasInput) return terminalResult(runtime, entry, undefined, "exited");
           // The error tells the agent about the exit, so a deferred Exit notification is redundant.
           runtime.registry.markSeen(entry.id);
           throw new InputToExitedError(entry.id, entry.exit);
@@ -814,7 +941,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
           signal,
         });
         return terminalResult(
-          runtime.registry,
+          runtime,
           entry,
           snapshot,
           reason,
@@ -862,7 +989,7 @@ function stopTerminalInTurn(
 }
 
 /** `terminal_stop`: stop a Terminal or Background job and forget it. */
-export function createTerminalStopTool(registry: TermctrlRegistry) {
+export function createTerminalStopTool({ registry, scrollback }: TerminalResultRuntime) {
   return defineTool<typeof StopParameters, StopResult>({
     name: "terminal_stop",
     label: "terminal_stop",
@@ -906,7 +1033,13 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
         const changed = previousScreen !== screen;
         // A screen the agent already saw is not repeated, whether the Terminal was running or exited.
         const repeated = !changed;
-        const output = await fitOutput(registry, entry, repeated ? "" : screen, scrolled);
+        const output = await fitOutput(
+          registry,
+          entry,
+          repeated ? "" : screen,
+          scrolled,
+          scrollback(),
+        );
         result.changed = changed;
         if (!repeated) result.screen = output.screen;
         if (!repeated || output.scrolledOff !== "") result.scrolled_off = output.scrolledOff;