@ian-pascoe/pi-termctrl 0.4.1 → 0.5.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
@@ -119,8 +126,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 +146,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 +213,18 @@ by field:
   "termctrl": {
     "replaceBash": true,
     "defaultViewport": { "cols": 120, "rows": 40 },
-    "exitTailLines": 20
+    "exitTailLines": 20,
+    "bashTail": { "lines": 300, "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 |
 
 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.5.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.
+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 { BashTailLimits } 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?: BashTailLimits | 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: BashTailLimits,
+  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: BashTailLimits | 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: BashTailLimits): 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: BashTailLimits): 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: BashTailLimits | 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

@@ -182,6 +182,7 @@ class PiTermctrlController {
           shellPath,
           registry: currentRegistry,
           calls,
+          bashTail: settings.bashTail,
         }),
       );
     }

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,16 @@ 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 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;
   readonly warnings: readonly string[];
 }
 
@@ -39,18 +49,26 @@ interface TermctrlLayer {
   cols?: number;
   rows?: number;
   exitTailLines?: number;
+  bashTailEnabled?: boolean;
+  bashTailLines?: number;
+  bashTailBytes?: number;
 }
 
-export const DEFAULT_TERMCTRL_SETTINGS: Omit<ResolvedTermctrlSettings, "warnings"> = {
+export const DEFAULT_TERMCTRL_SETTINGS: Omit<ResolvedTermctrlSettings, "warnings" | "bashTail"> & {
+  readonly bashTail: BashTailLimits;
+} = {
   replaceBash: true,
   defaultViewport: { cols: 120, rows: 40 },
   exitTailLines: 20,
+  bashTail: { maxLines: 300, 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 ExitTailLinesSchema = Type.Integer({ minimum: 0, maximum: EXIT_TAIL_LIMIT });
 
 function isJsonObject(value: JsonValue): value is JsonObject {
@@ -84,6 +102,9 @@ 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":
+        readBashTail(value, path, layer, warnings);
+        break;
       case "defaultViewport":
         readViewport(value, path, layer, warnings);
         break;
@@ -109,6 +130,39 @@ 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;
+  }
+  if (!isJsonObject(value)) {
+    warnings.push(`${path}: expected a boolean, 0, or a JSON object`);
+    return;
+  }
+  let valid = 0;
+  for (const [key, limit] of Object.entries(value)) {
+    if (key === "lines") {
+      if (Value.Check(BashTailLinesSchema, limit)) {
+        layer.bashTailLines = 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;
+        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) layer.bashTailEnabled = true;
+}
+
 /** Resolve global and trusted-project `termctrl` settings, keeping valid fields around warnings. */
 export function resolveTermctrlSettings(reader: TermctrlSettingsReader): ResolvedTermctrlSettings {
   const warnings: string[] = [];
@@ -123,6 +177,15 @@ 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,
     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 = 5;
 
 /** 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. */
@@ -457,6 +459,7 @@ export class TermctrlRegistry {
         generation: slot.generation,
         finalScreen: undefined,
         activeCalls: 0,
+        callQueue: { running: false, waiting: [] },
         lastScreen: undefined,
         logCursor: 0,
         logAnchor: [],

package/src/terminal-tools.ts

@@ -580,17 +580,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 +653,7 @@ async function driveTerminal<T>(
     }
     throw error;
   } finally {
+    release?.();
     entry.activeCalls--;
   }
 }
@@ -665,7 +721,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),
@@ -680,10 +738,17 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
   });
 }
 
-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 +783,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.registry, 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 +798,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();
@@ -763,20 +826,41 @@ 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) {
   return defineTool<typeof StopParameters, StopResult>({
@@ -793,15 +877,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.`