@ian-pascoe/pi-termctrl 0.4.1 → 0.6.0

package/README.md

@@ -47,6 +47,13 @@ with input, and 30 s for a `terminal_send` with neither `text` nor `keys` (a
 poll, which settles on quiet only after new output). Every `wait_ms` clamps to
 5 minutes.
 
+Calls to one Terminal run one at a time, in arrival order: a parallel batch of
+`terminal_send` calls each types, presses keys, and settles before the next
+starts, so every result shows its own call's screen; a `terminal_stop` waits its
+turn too, then reports what the calls ahead of it left. A call queued behind a
+stop finds the Terminal gone. Calls to different Terminals stay concurrent. Aborting a waiting
+call removes it without affecting the running one.
+
 Results say why the wait ended in `settle_reason` (`matched`, `timeout`, `quiet`
 or `exited`) and in their first line, such as `t1 running · settled: timeout`; a
 `wait_for_text` that timed out adds that the pattern was not seen. Polls report
@@ -57,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
@@ -73,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`,
@@ -119,8 +130,8 @@ Each terminal tool declares MCP-style `annotations`, which Pi reports through `p
 With `termctrl.replaceBash` (default `true`), Pi Termctrl replaces Pi's `bash`
 tool with Pi's own definition plus one parameter, `background?: boolean`.
 Commands still run on pipes through Pi's local `exec`, so Pi keeps spawning,
-process-tree kills, truncation and rendering, and foreground results are
-unchanged. A command becomes a Background job in two ways:
+process-tree kills and rendering, and foreground results differ from Pi's only
+by the shorter tail below. A command becomes a Background job in two ways:
 
 - **`background: true`** waits 2 s. A command that finishes first returns an
   ordinary result; otherwise the call returns a background result. If the cap
@@ -139,6 +150,16 @@ notification or call `terminal_wait`; read the log with `read` and stop the job
 with `terminal_stop`. Its structured result follows Pi's `bash` output schema, except
 that `exit_code` is absent and `background: { id, log_path }` is present.
 
+**Output tail.** With `termctrl.bashTail` (default `{ lines: 300, bytes: 16384 }`),
+the output the model sees from a foreground `bash` call, and the "output so far" of
+a backgrounding result, is cut to the last 300 lines or 16 KB, whichever is hit
+first, instead of Pi's 2,000 lines or 50 KB. The cut keeps Pi's notice, for example
+`[Showing lines 4701-5000 of 5000 (16.0KB or 300 line limit). Full output: /tmp/pi-bash-….log]`,
+and names the limits actually used. The named file always holds every line: Pi's own
+full-output file when Pi also cut the output, otherwise one Pi Termctrl writes beside
+it in `$TMPDIR` (like Pi's, it is not deleted). The tool description names the limits in force. Set `bashTail` to `false`
+or `0` to restore Pi's limits. Values above Pi's limits are rejected, and an object with no valid field leaves a lower layer's setting in place.
+
 A Background job's log is deleted when the job is stopped, when the user
 removes it in `/ps`, or when its session shuts down for any reason except
 reload. `bash` calls from `codemode` scripts behave the same. User `!` commands
@@ -196,16 +217,20 @@ by field:
   "termctrl": {
     "replaceBash": true,
     "defaultViewport": { "cols": 120, "rows": 40 },
-    "exitTailLines": 20
+    "exitTailLines": 20,
+    "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 |
+| 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.4.1",
+  "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,8 @@ 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. Classify the failure as settings, binary resolution, `bash` conflict, cap, or process behaviour.
-6. 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.
+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.
 
 Ask before stopping a Terminal or Background job you did not start.

package/src/bash-replacement.ts

@@ -1,4 +1,6 @@
-import { createWriteStream, mkdirSync, openSync, type WriteStream } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { createWriteStream, mkdirSync, openSync, writeFileSync, type WriteStream } from "node:fs";
+import { tmpdir } from "node:os";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import {
@@ -9,13 +11,17 @@ import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   type BashOperations,
+  type BashToolDetails,
   type BashToolOptions,
   type ExtensionToolContext,
   type ExtensionUIContext,
+  type TruncationOptions,
+  type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
 import { Type, type TSchema } from "typebox";
 import { KILLED_EXIT, TermctrlRegistry } from "./termctrl-registry.js";
+import type { LineByteLimits } from "./pi-termctrl-settings.js";
 import { termctrlTemporaryDirectory } from "./termctrl-driver.js";
 import type { TerminalExit } from "./terminal-driver.js";
 
@@ -29,6 +35,12 @@ const TAIL_LIMIT_CHARS = 64 * 1024;
 
 type ExecOptions = Parameters<BashOperations["exec"]>[2];
 
+function countNewlines(data: Buffer): number {
+  let count = 0;
+  for (let at = data.indexOf(10); at !== -1; at = data.indexOf(10, at + 1)) count++;
+  return count;
+}
+
 /** Path of a Background job's log. The pid keeps concurrent Pi processes apart. */
 export function backgroundLogPath(id: string): string {
   return join(termctrlTemporaryDirectory(), `${process.pid}-${id}.log`);
@@ -39,6 +51,14 @@ interface BackgroundOutcome {
   readonly id: string;
   readonly logPath: string;
   readonly output: string;
+  /** What the in-memory buffer dropped from the head of `output`. */
+  readonly dropped: DroppedOutput;
+}
+
+/** Output that left the in-memory buffer, which a tail's totals still have to count. */
+interface DroppedOutput {
+  readonly lines: number;
+  readonly bytes: number;
 }
 
 /**
@@ -50,6 +70,7 @@ class BashCall {
   private readonly chunks: Buffer[] = [];
   private bufferedBytes = 0;
   private droppedBytes = 0;
+  private droppedNewlines = 0;
   private recent = "";
   private readonly decoder = new TextDecoder();
   private log: WriteStream | undefined;
@@ -74,6 +95,17 @@ class BashCall {
     });
   }
 
+  /** Everything the foreground call printed that is still buffered, for the model-visible tail. */
+  foregroundOutput() {
+    if (this.isBackgrounded) return undefined;
+    const raw = Buffer.concat(this.chunks);
+    return { text: new TextDecoder().decode(raw), raw, dropped: this.dropped() };
+  }
+
+  private dropped(): DroppedOutput {
+    return { lines: this.droppedNewlines, bytes: this.droppedBytes };
+  }
+
   /** The `BashOperations.exec` Pi's `execute` calls. */
   async exec(
     command: string,
@@ -136,6 +168,7 @@ class BashCall {
       const dropped = this.chunks.shift();
       this.bufferedBytes -= dropped?.length ?? 0;
       this.droppedBytes += dropped?.length ?? 0;
+      if (dropped !== undefined) this.droppedNewlines += countNewlines(dropped);
     }
     this.forwardData?.(data);
   }
@@ -190,7 +223,12 @@ class BashCall {
     const output = this.decoder.decode(Buffer.concat(this.chunks), { stream: true });
     this.chunks.length = 0;
     this.remember(output);
-    this.resolveBackground({ id: entry.id, logPath: entry.child.logPath, output });
+    this.resolveBackground({
+      id: entry.id,
+      logPath: entry.child.logPath,
+      output,
+      dropped: this.dropped(),
+    });
     return true;
   }
 }
@@ -244,6 +282,11 @@ export interface BashReplacementOptions {
   readonly shellPath: string | undefined;
   readonly registry: () => TermctrlRegistry;
   readonly calls: RunningBashCalls;
+  /**
+   * 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?: LineByteLimits | undefined;
   /** Builds Pi's `bash` definition; tests wrap it to observe what reaches Pi's accumulator. */
   readonly definitionFactory?: typeof createBashToolDefinition;
 }
@@ -269,25 +312,156 @@ function backgroundOutputSchema(builtin: TSchema | undefined) {
   });
 }
 
-function backgroundResult(outcome: BackgroundOutcome, startedAt: number) {
-  const truncation = truncateTail(outcome.output);
+/** The notice after a cut tail, naming the limits that cut it and where every line is. */
+function tailNotice(truncation: TruncationResult, fullOutput: string, logPath: string): string {
+  const lastLine = truncation.totalLines;
+  if (truncation.lastLinePartial) {
+    const lineBytes = Buffer.byteLength(fullOutput.slice(fullOutput.lastIndexOf("\n") + 1));
+    return `[Showing last ${formatSize(truncation.outputBytes)} of line ${lastLine} (line is ${formatSize(lineBytes)}). Full output: ${logPath}]`;
+  }
+  const first = truncation.totalLines - truncation.outputLines + 1;
+  return `[Showing lines ${first}-${lastLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} or ${truncation.maxLines} line limit). Full output: ${logPath}]`;
+}
+
+/** The status Pi appends after the output on a failure, abort, or timeout. */
+const PI_STATUS =
+  /\n\n(Command exited with code -?\d+|Command aborted|Command timed out after [^\n]+|Command terminated without an exit code)$/u;
+/** Pi's cut notice, as the last thing before its status. */
+const PI_NOTICE_AT_END = /\[Showing [^\n]*Full output: ([^\]\n]+)\]$/u;
+
+/**
+ * Where Pi saved the full output of a call whose output Pi itself cut. A command can print text
+ * that looks like Pi's notice, so this is consulted only when Pi's own limits were exceeded, and a
+ * rejection's text is read only at the notice Pi puts directly before its status.
+ */
+function piFullOutputPath(text: string, details: BashToolDetails | undefined): string | undefined {
+  if (details?.fullOutputPath !== undefined) return details.fullOutputPath;
+  const status = PI_STATUS.exec(text);
+  if (status === null) return undefined;
+  return PI_NOTICE_AT_END.exec(text.slice(0, status.index))?.[1];
+}
+
+/** Save the whole output beside Pi's own `pi-bash-*.log` files. */
+function saveFullOutput(raw: Buffer): string | undefined {
+  const path = join(tmpdir(), `pi-bash-${randomBytes(8).toString("hex")}.log`);
+  try {
+    writeFileSync(path, raw, { mode: 0o600, flag: "wx" });
+    return path;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `truncateTail` over a buffer that dropped its head: the totals count the dropped output too. */
+function truncateBuffered(
+  output: string,
+  dropped: DroppedOutput,
+  limits: TruncationOptions,
+): TruncationResult {
+  const truncation = truncateTail(output, limits);
+  if (dropped.bytes === 0) return truncation;
+  return {
+    ...truncation,
+    truncated: true,
+    truncatedBy: truncation.truncatedBy ?? "bytes",
+    totalLines: truncation.totalLines + dropped.lines,
+    totalBytes: truncation.totalBytes + dropped.bytes,
+  };
+}
+
+/**
+ * Cut a foreground result's text to `limits`. Returns undefined when the output already fits, which
+ * leaves Pi's text as it is: Pi's limits are never tighter than `limits`.
+ */
+function limitForegroundText(
+  call: BashCall,
+  piText: string,
+  piDetails: BashToolDetails | undefined,
+  limits: LineByteLimits,
+  hasStatus: boolean,
+) {
+  const output = call.foregroundOutput();
+  if (output === undefined) return undefined;
+  const truncation = truncateBuffered(output.text, output.dropped, {
+    maxLines: limits.maxLines,
+    maxBytes: limits.maxBytes,
+  });
+  if (!truncation.truncated) return undefined;
+  const piCut = truncateBuffered(output.text, output.dropped, {}).truncated;
+  const logPath =
+    (piCut ? piFullOutputPath(piText, piDetails) : undefined) ?? saveFullOutput(output.raw);
+  const notice = tailNotice(truncation, output.text, logPath ?? "(could not be saved)");
+  // Pi appends a status only to a failure; a successful command's output may merely look like one.
+  const status = hasStatus ? PI_STATUS.exec(piText) : null;
+  const suffix = status === null ? "" : `\n\n${status[1] ?? ""}`;
+  return {
+    text: `${truncation.content}\n\n${notice}${suffix}`,
+    details: logPath === undefined ? { truncation } : { truncation, fullOutputPath: logPath },
+  };
+}
+
+function backgroundResult(
+  outcome: BackgroundOutcome,
+  startedAt: number,
+  limits: LineByteLimits | undefined,
+) {
+  const truncation = truncateBuffered(outcome.output, outcome.dropped, limits ?? {});
   let text = truncation.content;
   if (truncation.truncated) {
-    text += `\n\n[Showing lines ${truncation.totalLines - truncation.outputLines + 1}-${truncation.totalLines} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} or ${DEFAULT_MAX_LINES} line limit). Full output: ${outcome.logPath}]`;
+    text += `\n\n${tailNotice(truncation, outcome.output, outcome.logPath)}`;
   }
+  // Scripts get the same contract as a finished call's structured result: Pi's limits, not the tail.
+  const structured = truncateBuffered(outcome.output, outcome.dropped, {});
   const status = `Command moved to the background as ${outcome.id}. Its output so far and all later output go to ${outcome.logPath}. You will get an Exit notification when it ends, so do not poll the log in a loop; to block until it ends, call terminal_wait. Stop it with terminal_stop {"id": "${outcome.id}"}.`;
   return {
     content: [{ type: "text" as const, text: text === "" ? status : `${text}\n\n${status}` }],
     details: undefined,
     structuredContent: {
-      output: truncation.content,
-      truncated: truncation.truncated,
+      output: structured.content,
+      truncated: structured.truncated,
       wall_time_seconds: Math.round((performance.now() - startedAt) / 100) / 10,
       background: { id: outcome.id, log_path: outcome.logPath },
     },
   };
 }
 
+type BashResult = Awaited<ReturnType<ReturnType<typeof createBashToolDefinition>["execute"]>>;
+
+function limitResult(call: BashCall, result: BashResult, limits: LineByteLimits): BashResult {
+  const [first] = result.content;
+  if (first?.type !== "text") return result;
+  const limited = limitForegroundText(
+    call,
+    first.text,
+    result.details,
+    limits,
+    result.isError === true,
+  );
+  if (limited === undefined) return result;
+  return {
+    ...result,
+    content: [{ type: "text", text: limited.text }],
+    details: limited.details,
+  };
+}
+
+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);
+  return limited === undefined ? error : new Error(limited.text, { cause: error });
+}
+
+/** Pi's description names its own limits; name the ones in force instead. */
+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)}`;
+  // If Pi rewords its description, still tell the model the limits in force.
+  if (!description.includes(piLimits)) return `${description} Output is truncated to last ${ours}.`;
+  return description.replace(piLimits, ours);
+}
+
 /** Pi's `bash` definition plus `background`, executed through Pi's own pipes. */
 export function createBashReplacement(options: BashReplacementOptions) {
   const builtinOptions: BashToolOptions = {};
@@ -308,6 +482,7 @@ export function createBashReplacement(options: BashReplacementOptions) {
   });
   return {
     ...builtin,
+    description: describeTail(builtin.description, options.bashTail),
     parameters,
     outputSchema: backgroundOutputSchema(builtin.outputSchema),
     async execute(
@@ -333,7 +508,8 @@ export function createBashReplacement(options: BashReplacementOptions) {
               if (!backgrounded) onUpdate(update);
             };
       const startedAt = performance.now();
-      const running = inner.execute(
+      const limits = options.bashTail;
+      const piRunning = inner.execute(
         toolCallId,
         params.timeout === undefined
           ? { command: params.command }
@@ -342,6 +518,17 @@ export function createBashReplacement(options: BashReplacementOptions) {
         forwardUpdate,
         context,
       );
+      const running =
+        limits === undefined
+          ? piRunning
+          : piRunning.then(
+              (result) => limitResult(call, result, limits),
+              (error: Error) => {
+                // Pi's `bash` rejects only with Errors; anything else passes through unchanged.
+                if (!(error instanceof Error)) throw error;
+                throw limitError(call, error, limits);
+              },
+            );
       running.catch(() => {});
       options.calls.add(call, context.ui);
       const yieldTimer =
@@ -361,7 +548,7 @@ export function createBashReplacement(options: BashReplacementOptions) {
         ]);
         if (winner.kind === "finished") return winner.result;
         backgrounded = true;
-        return backgroundResult(winner.outcome, startedAt);
+        return backgroundResult(winner.outcome, startedAt, options.bashTail);
       } finally {
         clearTimeout(yieldTimer);
         options.calls.delete(call);

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({
@@ -182,6 +193,7 @@ class PiTermctrlController {
           shellPath,
           registry: currentRegistry,
           calls,
+          bashTail: settings.bashTail,
         }),
       );
     }
@@ -194,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

@@ -1,4 +1,9 @@
-import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  type SettingsManager,
+  type TruncationOptions,
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
@@ -15,11 +20,24 @@ export interface TerminalViewport {
   readonly rows: number;
 }
 
+/** 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` 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[];
 }
 
@@ -34,23 +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;
+  bashTail?: LineByteLimitsLayer;
+  scrollback?: LineByteLimitsLayer;
 }
 
-export const DEFAULT_TERMCTRL_SETTINGS: Omit<ResolvedTermctrlSettings, "warnings"> = {
+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 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 {
@@ -84,6 +121,10 @@ function readLayer(
         if (Value.Check(ExitTailLinesSchema, value)) layer.exitTailLines = value;
         else warnings.push(`${path}: expected an integer from 0 to ${EXIT_TAIL_LIMIT}`);
         break;
+      case "bashTail":
+      case "scrollback":
+        layer[key] = readLineByteLimits(value, path, warnings);
+        break;
       case "defaultViewport":
         readViewport(value, path, layer, warnings);
         break;
@@ -109,6 +150,55 @@ function readViewport(value: JsonValue, path: string, layer: TermctrlLayer, warn
   }
 }
 
+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 {};
+  }
+  const limits: LineByteLimitsLayer = {};
+  let valid = 0;
+  for (const [key, limit] of Object.entries(value)) {
+    if (key === "lines") {
+      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(LimitBytesSchema, limit)) {
+        limits.bytes = limit;
+        valid++;
+      } else warnings.push(`${path}.bytes: expected an integer from 1 to ${DEFAULT_MAX_BYTES}`);
+    } else {
+      warnings.push(`${path}.${key}: unknown field`);
+    }
+  }
+  // An object with only invalid fields must not override a lower layer's opt-out.
+  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. */
 export function resolveTermctrlSettings(reader: TermctrlSettingsReader): ResolvedTermctrlSettings {
   const warnings: string[] = [];
@@ -123,6 +213,8 @@ export function resolveTermctrlSettings(reader: TermctrlSettingsReader): Resolve
     },
     exitTailLines:
       projectLayer.exitTailLines ?? globalLayer.exitTailLines ?? defaults.exitTailLines,
+    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 = 4;
+export const REGISTRY_VERSION = 6;
 
 /** Live Terminals plus Background jobs allowed across the whole process. */
 export const LIVE_ENTRY_CAP = 16;
@@ -71,8 +71,10 @@ export interface TerminalEntry extends EntryBase {
   readonly cwd: string;
   /** The screen captured when the Terminal exited. */
   finalScreen: string | undefined;
-  /** Number of agent tool calls currently driving this Terminal; the exit watcher skips them. */
+  /** Number of agent tool calls running or queued to drive this Terminal; the exit watcher skips them. */
   activeCalls: number;
+  /** The agent's calls to this Terminal: one runs at a time and the rest wait in arrival order. */
+  readonly callQueue: { running: boolean; readonly waiting: (() => void)[] };
   /** The screen the agent last received, for `changed: false`. */
   lastScreen: string | undefined;
   /** Count of log lines that scrolled off before the agent's last result. */
@@ -82,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. */
@@ -457,9 +464,11 @@ export class TermctrlRegistry {
         generation: slot.generation,
         finalScreen: undefined,
         activeCalls: 0,
+        callQueue: { running: false, waiting: [] },
         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);
   }
@@ -580,17 +707,72 @@ async function terminalResult(
   };
 }
 
+/** A call that was removed from its Terminal's queue before it started. */
+class CallCancelledError extends Error {
+  constructor(id: string) {
+    super(`The call to ${id} was cancelled before it started.`);
+    this.name = "CallCancelledError";
+  }
+}
+
+/**
+ * Wait for this call's turn on a Terminal. Calls to one Terminal run one at a time, each typing,
+ * pressing keys and settling before the next starts, so a parallel batch of sends gets screens
+ * that match its calls. Calls to other Terminals are unaffected. Aborting a waiting call removes
+ * it from the queue and rejects it; the running call is untouched.
+ */
+function awaitTurn(entry: TerminalEntry, signal: AbortSignal | undefined): Promise<() => void> {
+  const queue = entry.callQueue;
+  const release = () => {
+    const next = queue.waiting.shift();
+    if (next === undefined) queue.running = false;
+    else next();
+  };
+  if (signal?.aborted === true) return Promise.reject(new CallCancelledError(entry.id));
+  if (!queue.running) {
+    queue.running = true;
+    return Promise.resolve(release);
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      const index = queue.waiting.indexOf(start);
+      if (index !== -1) queue.waiting.splice(index, 1);
+      reject(new CallCancelledError(entry.id));
+    };
+    const start = () => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(release);
+    };
+    queue.waiting.push(start);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Run one call against a Terminal in its turn. A call that waited finds the Terminal as the calls
+ * ahead left it, so `run` must read the Terminal's state itself. A Terminal that a call ahead
+ * stopped is gone by then.
+ */
 async function driveTerminal<T>(
   registry: TermctrlRegistry,
   entry: TerminalEntry,
+  signal: AbortSignal | undefined,
   run: () => Promise<T>,
 ): Promise<T> {
+  // Counted while queued too, so the exit watcher leaves a Terminal the agent is driving alone.
   entry.activeCalls++;
+  let release: (() => void) | undefined;
   try {
+    release = await awaitTurn(entry, signal);
+    if (registry.find(entry.owner, entry.id) !== entry) throw unknownId(entry.id);
     return await run();
   } catch (cause) {
     const error = cause instanceof Error ? cause : new Error(String(cause));
-    if (registry.reportTerminalError(entry, error)) {
+    if (
+      release !== undefined &&
+      !(error instanceof InputToExitedError) &&
+      registry.reportTerminalError(entry, error)
+    ) {
       throw new Error(
         `${entry.id} was lost because the termctrl driver exited\n\n${TROUBLESHOOTING_HINT}`,
         { cause },
@@ -598,6 +780,7 @@ async function driveTerminal<T>(
     }
     throw error;
   } finally {
+    release?.();
     entry.activeCalls--;
   }
 }
@@ -665,7 +848,9 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
       });
       // Launching, including a cold driver start, does not count toward the quiet period.
       const startedAt = Date.now();
-      return driveTerminal(runtime.registry, entry, async () => {
+      // The Terminal is running and nothing else knows its id yet, so the call never queues; an
+      // abort ends the wait but must still return the id, or the agent could not reach the Terminal.
+      return driveTerminal(runtime.registry, entry, undefined, async () => {
         const { snapshot, reason } = await settleTerminal(entry, {
           mode: "start",
           waitMs: clampWait(params.wait_ms, START_WAIT_MS),
@@ -674,16 +859,23 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
           baseline: undefined,
           signal,
         });
-        return terminalResult(runtime.registry, entry, snapshot, reason);
+        return terminalResult(runtime, entry, snapshot, reason);
       });
     },
   });
 }
 
-function inputToExited(id: string, exit: TerminalExit | null): Error {
-  return new Error(
-    `${id} ${describeExit(exit)} and accepts no input. Poll it with terminal_send for its final screen, or remove it with terminal_stop.`,
-  );
+/**
+ * Input to a Terminal that exited. It is the agent's mistake, not a driver failure, even when the
+ * exit says the driver died: that loss was already reported.
+ */
+class InputToExitedError extends Error {
+  constructor(id: string, exit: TerminalExit | null) {
+    super(
+      `${id} ${describeExit(exit)} and accepts no input. Poll it with terminal_send for its final screen, or remove it with terminal_stop.`,
+    );
+    this.name = "InputToExitedError";
+  }
 }
 
 /** `terminal_send`: type text and keys into a Terminal, or poll it, and wait for it to settle. */
@@ -718,15 +910,13 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
         );
       }
       const hasInput = (params.text ?? "") !== "" || keys.length > 0;
-      if (entry.state === "exited") {
-        if (hasInput) {
+      return driveTerminal(runtime.registry, entry, signal, async () => {
+        if (entry.state === "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 inputToExited(entry.id, entry.exit);
+          throw new InputToExitedError(entry.id, entry.exit);
         }
-        return terminalResult(runtime.registry, entry, undefined, "exited");
-      }
-      return driveTerminal(runtime.registry, entry, async () => {
         const matches =
           params.wait_for_text === undefined ? undefined : parseWaitPattern(params.wait_for_text);
         const before =
@@ -735,7 +925,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
           // The exit watcher has not noticed this exit yet.
           const exit = before.exit ?? { code: null, signal: null };
           runtime.registry.terminalExited(entry.id, exit, before.screen, true);
-          throw inputToExited(entry.id, exit);
+          throw new InputToExitedError(entry.id, exit);
         }
         const baseline = matches === undefined ? undefined : before?.screen;
         const startedAt = Date.now();
@@ -751,7 +941,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
           signal,
         });
         return terminalResult(
-          runtime.registry,
+          runtime,
           entry,
           snapshot,
           reason,
@@ -763,22 +953,43 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
 }
 
 /** Capture the lines a Terminal scrolled off since the agent's last result, before it is stopped. */
-async function finalScrolledOff(
-  registry: TermctrlRegistry,
-  entry: TerminalEntry,
-): Promise<ScrolledOff> {
+async function finalScrolledOff(entry: TerminalEntry): Promise<ScrolledOff> {
   try {
     if (entry.state === "exited") return await takeScrolledOff(entry, entry.finalScreen ?? "");
-    return await driveTerminal(registry, entry, async () =>
-      takeScrolledOff(entry, (await entry.handle.snapshot()).screen),
-    );
+    return await takeScrolledOff(entry, (await entry.handle.snapshot()).screen);
   } catch {
     return NOTHING_SCROLLED;
   }
 }
 
+/** What a stop saw of a Terminal at its turn, before stopping it. */
+interface StopView {
+  readonly wasRunning: boolean;
+  readonly previousScreen: string | undefined;
+  readonly scrolled: ScrolledOff;
+  readonly entry: TermctrlEntry;
+}
+
+/**
+ * Stop a Terminal in its turn: the calls ahead have finished, so `wasRunning` and the previous
+ * screen are what they left, and calls queued behind find the Terminal gone.
+ */
+function stopTerminalInTurn(
+  registry: TermctrlRegistry,
+  known: TerminalEntry,
+  signal: AbortSignal | undefined,
+): Promise<StopView> {
+  return driveTerminal(registry, known, signal, async () => {
+    const wasRunning = known.state === "running";
+    const previousScreen = known.lastScreen;
+    const scrolled = await finalScrolledOff(known);
+    const entry = (await registry.stop(known.owner, known.id)) ?? known;
+    return { wasRunning, previousScreen, scrolled, entry };
+  });
+}
+
 /** `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",
@@ -793,15 +1004,19 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
       openWorldHint: false,
     },
     outputSchema: StopResultSchema,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+    async execute(_toolCallId, params, signal, _onUpdate, context) {
       const owner = ownerOf(context);
       const known = registry.find(owner, params.id);
       if (known === undefined) throw unknownId(params.id);
-      const wasRunning = known.state === "running";
-      const previousScreen = known.kind === "terminal" ? known.lastScreen : undefined;
-      const scrolled =
-        known.kind === "terminal" ? await finalScrolledOff(registry, known) : NOTHING_SCROLLED;
-      const entry = (await registry.stop(owner, params.id)) ?? known;
+      const { wasRunning, previousScreen, scrolled, entry } =
+        known.kind === "terminal"
+          ? await stopTerminalInTurn(registry, known, signal)
+          : {
+              wasRunning: known.state === "running",
+              previousScreen: undefined,
+              scrolled: NOTHING_SCROLLED,
+              entry: (await registry.stop(owner, params.id)) ?? known,
+            };
       const label = entry.kind === "terminal" ? "Terminal" : "Background job";
       const header = wasRunning
         ? `${label} ${entry.id} stopped.`
@@ -818,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;