@ian-pascoe/pi-termctrl 0.1.0 → 0.2.0

package/README.md

@@ -29,6 +29,7 @@ For a local checkout, run `pi -e ./packages/pi-termctrl/src/index.ts`.
 | `terminal_send`  | `id`, `text?`, `keys?`, `wait_for_text?`, `wait_ms?`      |
 | `terminal_stop`  | `id`: a Terminal id (`t1`) or Background job id (`b1`)    |
 | `terminal_list`  | none                                                      |
+| `terminal_wait`  | `ids?`, `wait_ms?` (default and maximum 300000)           |
 
 `terminal_start` runs `command` through the shell Pi's `bash` uses (the
 `shellPath` setting, otherwise Pi's default bash), applies `shellCommandPrefix`,
@@ -87,6 +88,15 @@ or their session shuts down. `terminal_list` lists the caller's Terminals and,
 in a separate `background_jobs` section, its Background jobs with their log
 paths.
 
+`terminal_wait` blocks until one of the caller's Terminals or Background jobs
+exits: those listed in `ids`, otherwise every one still running. It returns
+every exit by then, in the same form as an Exit notification, plus what is still
+running, and those exits send no Exit notification. It also returns when
+`wait_ms` runs out, when the call is aborted, or as soon as a message is queued
+for the agent, such as the user steering or another entry's Exit notification;
+a watched entry that exits after that is notified as usual. With nothing to
+wait for it returns at once. Terminal exits are noticed within about 500 ms.
+
 ## `bash` replacement
 
 With `termctrl.replaceBash` (default `true`), Pi Termctrl replaces Pi's `bash`
@@ -106,9 +116,10 @@ older output becomes an omission line in the log. Once backgrounded, a
 command's `timeout` is cleared, Esc and turn aborts no
 longer reach it, and its output so far and all later output go to
 `$TMPDIR/pi-termctrl/<pid>-<id>.log`. The result says
-`Command moved to the background as b<n>`, includes the output so far, and
-gives the log path; read the log with `read` and stop the job with
-`terminal_stop`. Its structured result follows Pi's `bash` output schema, except
+`Command moved to the background as b<n>`, includes the output so far, gives
+the log path, and tells the agent not to poll the log but to wait for the Exit
+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.
 
 A Background job's log is deleted when the job is stopped, when the user
@@ -124,11 +135,16 @@ backgrounding paths do not exist.
 
 When a Terminal or Background job exits and the agent has neither seen the exit
 in a `terminal_*` result nor stopped it, Pi Termctrl sends an Exit notification:
-the id, command, exit code or signal, duration, and the last
-`termctrl.exitTailLines` lines of the final screen or log. Exits in the same tick
-share one message. It steers a working agent and starts a turn when the agent is
-idle. `terminal_start {notify: false}` opts a Terminal out. Notifications go
-only to the session that started the entry, and wait across `/reload`.
+the id, command, exit code or signal, duration, where to find the full output
+(a Background job's log path, or `terminal_send` for a Terminal's final screen),
+and the last `termctrl.exitTailLines` lines of the final screen or log. Seeing
+a Terminal running in a `terminal_*` result does not count as seeing its exit.
+Exits reported by `terminal_wait` are not notified again. Exits in the same tick
+share one message. While the agent works, notifications wait for the end of its
+current turn, then steer it, so an exit a tool call in that turn reported is
+not notified. When the agent is idle, a notification starts a turn.
+`terminal_start {notify: false}` opts a Terminal out. Notifications go only to
+the session that started the entry, and wait across `/reload`.
 
 ## `/ps` and footer
 
@@ -184,7 +200,8 @@ GNU/Linux on arm64 or x64 through optional dependencies. Set `TERMCTRL_BINARY`
 to use another binary. Where no binary resolves (Windows, musl, or
 `--omit=optional`), Pi Termctrl shows one diagnostic and registers no
 `terminal_start` or `terminal_send`; the `bash` replacement, Background jobs,
-`terminal_stop` and `terminal_list` keep working wherever Pi's `bash` does.
+`terminal_stop`, `terminal_list` and `terminal_wait` keep working wherever Pi's
+`bash` does.
 
 Not supported: attaching to or taking over a Terminal, recordings, mouse input,
 resize, raw bytes, persistence across Pi restarts, and graceful `SIGTERM`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [

package/skills/pi-termctrl/SKILL.md

@@ -2,6 +2,7 @@
 name: pi-termctrl
 description: Configure or diagnose Pi Termctrl when Terminal tools are missing, the bash replacement conflicts with another extension, Background jobs misbehave, or termctrl settings need changing.
 license: MIT
+disable-model-invocation: true
 ---
 
 # Pi Termctrl

package/src/bash-replacement.ts

@@ -273,7 +273,7 @@ function backgroundResult(outcome: BackgroundOutcome, startedAt: number) {
   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}]`;
   }
-  const status = `Command moved to the background as ${outcome.id}. Its output so far and all later output go to ${outcome.logPath}; read that file to check progress, and stop it with terminal_stop {"id": "${outcome.id}"}. You will get an Exit notification when it ends.`;
+  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,

package/src/exit-notification.ts

@@ -17,6 +17,7 @@ const ExitNotificationDetailsSchema = Type.Object({
       exit_code: Type.Union([Type.Number(), Type.Null()]),
       signal: Type.Union([Type.String(), Type.Null()]),
       duration_ms: Type.Number(),
+      log_path: Type.Optional(Type.String()),
     }),
   ),
 });
@@ -41,7 +42,8 @@ export function formatDuration(milliseconds: number): string {
   return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
 }
 
-function lastLines(output: string, count: number): string {
+/** The last `count` lines of `output`, without trailing blank lines. */
+export function lastLines(output: string, count: number): string {
   if (count === 0) return "";
   const lines = output.replace(/\n+$/u, "").split("\n");
   return lines.slice(-count).join("\n");
@@ -52,6 +54,24 @@ function headline(notice: ExitNotice): string {
   return `${label} ${notice.id} ${describeExitStatus(notice.exit)} after ${formatDuration(notice.durationMs)}: ${notice.command}`;
 }
 
+/** Where the agent finds the rest of an exited entry's output. */
+function pointer(notice: ExitNotice): string {
+  if (notice.logPath !== undefined) return `Log: ${notice.logPath}`;
+  return `terminal_send {"id": "${notice.id}"} returns its final screen.`;
+}
+
+/**
+ * Describe one exit: what ended and how, where its full output is, and its last `tailLines` lines.
+ * Exit notifications and `terminal_wait` results share this text.
+ */
+export function formatExitNotice(notice: ExitNotice, tailLines: number): string {
+  const head = `${headline(notice)}\n${pointer(notice)}`;
+  const tail = lastLines(notice.output, tailLines);
+  if (tail === "") return head;
+  const source = notice.kind === "terminal" ? "final screen" : "output";
+  return `${head}\nLast lines of ${source}:\n${tail}`;
+}
+
 /** The text and details of one Exit notification message. */
 export interface ExitNotificationMessage {
   readonly content: string;
@@ -63,26 +83,21 @@ export function formatExitNotification(
   notices: readonly ExitNotice[],
   tailLines: number,
 ): ExitNotificationMessage {
-  const content = notices
-    .map((notice) => {
-      const tail = lastLines(notice.output, tailLines);
-      const source = notice.kind === "terminal" ? "final screen" : "output";
-      return tail === ""
-        ? headline(notice)
-        : `${headline(notice)}\nLast lines of ${source}:\n${tail}`;
-    })
-    .join("\n\n");
   return {
-    content,
+    content: notices.map((notice) => formatExitNotice(notice, tailLines)).join("\n\n"),
     details: {
-      exits: notices.map((notice) => ({
-        id: notice.id,
-        kind: notice.kind === "job" ? ("background_job" as const) : ("terminal" as const),
-        command: notice.command,
-        exit_code: notice.exit.code,
-        signal: notice.exit.signal,
-        duration_ms: notice.durationMs,
-      })),
+      exits: notices.map((notice) => {
+        const exit: ExitNotificationDetails["exits"][number] = {
+          id: notice.id,
+          kind: notice.kind === "job" ? "background_job" : "terminal",
+          command: notice.command,
+          exit_code: notice.exit.code,
+          signal: notice.exit.signal,
+          duration_ms: notice.durationMs,
+        };
+        if (notice.logPath !== undefined) exit.log_path = notice.logPath;
+        return exit;
+      }),
     },
   };
 }

package/src/pi-termctrl-extension.ts

@@ -24,6 +24,7 @@ import {
   createTerminalSendTool,
   createTerminalStartTool,
   createTerminalStopTool,
+  createTerminalWaitTool,
   type TerminalShell,
 } from "./terminal-tools.js";
 
@@ -40,6 +41,7 @@ interface ActiveSession {
   readonly ps: TermctrlPsController;
   readonly shell: () => TerminalShell;
   readonly viewport: TerminalViewport;
+  readonly exitTailLines: number;
 }
 
 /**
@@ -50,6 +52,14 @@ interface ActiveSession {
  */
 class PiTermctrlController {
   private active: ActiveSession | undefined;
+  /**
+   * Exit notifications sent mid-turn would queue in Pi as steering messages, beyond recall, while
+   * a tool call in the same turn, such as `terminal_wait`, can still report the exit. During an
+   * agent run they therefore wait for the turn's end, when Pi reads steering messages and those
+   * tool results are known.
+   */
+  private runActive = false;
+  private atTurnEnd = false;
   private readonly binary: TermctrlBinaryResolution;
   private readonly registry: TermctrlRegistry;
 
@@ -88,11 +98,36 @@ class PiTermctrlController {
     }
     this.pi.on("session_start", (_event, context) => this.start(context));
     this.pi.on("session_shutdown", (event) => this.shutdown(event));
+    this.pi.on("agent_start", () => {
+      this.runActive = true;
+    });
+    this.pi.on("turn_end", () => {
+      this.atTurnEnd = true;
+      try {
+        this.flushNotifications();
+      } finally {
+        this.atTurnEnd = false;
+      }
+    });
+    this.pi.on("agent_end", () => {
+      this.runActive = false;
+      this.flushNotifications();
+    });
+  }
+
+  private flushNotifications(): void {
+    (TermctrlRegistry.current() ?? this.registry).flush();
   }
 
   private registerManagementTools(): void {
     this.pi.registerTool(createTerminalStopTool(this.registry));
     this.pi.registerTool(createTerminalListTool(this.registry));
+    this.pi.registerTool(
+      createTerminalWaitTool({
+        registry: this.registry,
+        exitTailLines: () => this.session().exitTailLines,
+      }),
+    );
   }
 
   private session(): ActiveSession {
@@ -112,7 +147,9 @@ class PiTermctrlController {
     }
     const registry = this.registry;
     const owner = context.sessionManager.getSessionId();
+    this.runActive = false;
     registry.bindOwner(owner, (notices) => {
+      if (this.runActive && !this.atTurnEnd) return false;
       const message = formatExitNotification(notices, settings.exitTailLines);
       this.pi.sendMessage(
         {
@@ -123,13 +160,14 @@ class PiTermctrlController {
         },
         { triggerTurn: true, deliverAs: "steer" },
       );
+      return true;
     });
 
     const shellPath = settingsManager.getShellPath();
     const commandPrefix = settingsManager.getShellCommandPrefix();
     if (this.binary.kind === "missing") {
       context.ui.notify(
-        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}`,
+        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}\nRun /skill:pi-termctrl to diagnose.`,
         "warning",
       );
       if (settings.replaceBash) this.registerManagementTools();
@@ -156,6 +194,7 @@ class PiTermctrlController {
         return { shell: shell.shell, args: shell.args, commandPrefix };
       },
       viewport: settings.defaultViewport,
+      exitTailLines: settings.exitTailLines,
     };
   }
 

package/src/termctrl-registry.ts

@@ -7,12 +7,13 @@ import type {
   TerminalLaunchRequest,
 } from "./terminal-driver.js";
 import { isDriverGone } from "./terminal-driver.js";
+import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 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 = 3;
+export const REGISTRY_VERSION = 4;
 
 /** Live Terminals plus Background jobs allowed across the whole process. */
 export const LIVE_ENTRY_CAP = 16;
@@ -58,6 +59,8 @@ interface EntryBase {
   seen: boolean;
   stopRequested: StopRequester | undefined;
   readonly notify: boolean;
+  /** `terminal_wait` calls watching this entry; they report its exit instead of a notification. */
+  watchers: number;
 }
 
 /** A PTY program driven through termctrl. */
@@ -101,10 +104,16 @@ export interface ExitNotice {
   readonly durationMs: number;
   /** The final screen of a Terminal or the recent log output of a Background job. */
   readonly output: string;
+  /** A Background job's log. */
+  readonly logPath?: string;
 }
 
-/** Delivers a batch of Exit notifications to one owner session. Throwing keeps the batch queued. */
-export type NotificationDelivery = (notices: readonly ExitNotice[]) => void;
+/**
+ * Delivers a batch of Exit notifications to one owner session. Returning `false` defers the batch:
+ * it stays queued until the next {@link TermctrlRegistry.flush}. Throwing keeps it queued and
+ * unbinds the owner.
+ */
+export type NotificationDelivery = (notices: readonly ExitNotice[]) => boolean;
 
 /** Request to start one Terminal. */
 export interface TerminalStartRequest {
@@ -271,12 +280,18 @@ export class TermctrlRegistry {
       const due = notices.filter((notice) => this.state.entries.get(notice.id)?.seen !== true);
       this.state.pending.delete(owner);
       if (due.length === 0) continue;
+      const requeue = () =>
+        this.state.pending.set(owner, [...due, ...(this.state.pending.get(owner) ?? [])]);
       try {
-        delivery(due);
+        // Only an explicit `false` defers: deliveries bound by an older module return nothing.
+        if (delivery(due) === false) {
+          requeue();
+          continue;
+        }
         for (const notice of due) this.markSeen(notice.id);
       } catch {
         this.state.owners.delete(owner);
-        this.state.pending.set(owner, [...due, ...(this.state.pending.get(owner) ?? [])]);
+        requeue();
       }
     }
   }
@@ -288,27 +303,61 @@ export class TermctrlRegistry {
     setImmediate(() => state.current.flush());
   }
 
-  private queueNotice(entry: TermctrlEntry, output: string): void {
-    if (!entry.notify || entry.seen || entry.stopRequested === "agent" || entry.exit === null) {
-      return;
-    }
-    const notices = this.state.pending.get(entry.owner) ?? [];
-    notices.push({
+  /** Describe an exited entry's exit, or `undefined` while it runs. */
+  noticeFor(entry: TermctrlEntry): ExitNotice | undefined {
+    if (entry.exit === null) return undefined;
+    const base = {
       id: entry.id,
       kind: entry.kind,
       command: entry.command,
       exit: entry.exit,
       durationMs: (entry.exitedAt ?? Date.now()) - entry.startedAt,
-      output,
-    });
+    };
+    return entry.kind === "job"
+      ? { ...base, output: entry.child.tail(), logPath: entry.child.logPath }
+      : { ...base, output: entry.finalScreen ?? "" };
+  }
+
+  private queueNotice(entry: TermctrlEntry): void {
+    if (!entry.notify || entry.seen || entry.stopRequested === "agent" || entry.watchers > 0) {
+      return;
+    }
+    const notice = this.noticeFor(entry);
+    if (notice === undefined) return;
+    const notices = this.state.pending.get(entry.owner) ?? [];
+    if (notices.some((queued) => queued.id === entry.id)) return;
+    notices.push(notice);
     this.state.pending.set(entry.owner, notices);
     this.scheduleFlush();
   }
 
-  /** Record that the agent has seen an entry's exit in a tool result. */
+  /**
+   * Watch entries for a `terminal_wait` call: their exits queue no Exit notification while watched.
+   * The returned release ends the watch and queues the notification of any exit the caller did not
+   * mark seen, such as one that happened after its wait ended.
+   */
+  watch(entries: readonly TermctrlEntry[]): () => void {
+    for (const entry of entries) entry.watchers++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      for (const entry of entries) {
+        entry.watchers--;
+        if (entry.state === "exited" && this.state.entries.has(entry.id)) {
+          this.queueNotice(entry);
+        }
+      }
+    };
+  }
+
+  /**
+   * Record that the agent has seen an entry's exit in a tool result. A running entry has no exit to
+   * see yet, so seeing it running leaves its later Exit notification due.
+   */
   markSeen(id: string): void {
     const entry = this.state.entries.get(id);
-    if (entry !== undefined) entry.seen = true;
+    if (entry?.state === "exited") entry.seen = true;
   }
 
   // ── Queries ───────────────────────────────────────────────────────────────
@@ -379,7 +428,7 @@ export class TermctrlRegistry {
         cwd: request.cwd,
         viewport: request.viewport,
       };
-      let slot = await this.ensureDriver();
+      let slot = await this.startDriver();
       let handle: TerminalHandle;
       try {
         handle = await slot.driver.launch(launch);
@@ -387,7 +436,7 @@ export class TermctrlRegistry {
         const error = cause instanceof Error ? cause : new Error(String(cause));
         if (!isDriverGone(error)) throw error;
         this.driverDied(slot.generation);
-        slot = await this.ensureDriver();
+        slot = await this.startDriver();
         handle = await slot.driver.launch(launch);
       }
       const entry: TerminalEntry = {
@@ -403,6 +452,7 @@ export class TermctrlRegistry {
         seen: false,
         stopRequested: undefined,
         notify: request.notify,
+        watchers: 0,
         handle,
         generation: slot.generation,
         finalScreen: undefined,
@@ -420,6 +470,16 @@ export class TermctrlRegistry {
     }
   }
 
+  /** Ensure a driver, pointing the agent at the troubleshooting Skill when none can start. */
+  private async startDriver(): Promise<DriverSlot> {
+    try {
+      return await this.ensureDriver();
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      throw new Error(`${error.message}\n\n${TROUBLESHOOTING_HINT}`, { cause });
+    }
+  }
+
   private async ensureDriver(): Promise<DriverSlot> {
     if (this.state.driver !== undefined) return this.state.driver;
     if (this.state.driverStarting !== undefined) return this.state.driverStarting;
@@ -456,7 +516,7 @@ export class TermctrlRegistry {
     entry.exitedAt = Date.now();
     entry.finalScreen = finalScreen;
     if (seen) entry.seen = true;
-    this.queueNotice(entry, finalScreen);
+    this.queueNotice(entry);
     this.syncWatcher();
     this.emitChange();
     this.closeIdleDriver();
@@ -557,6 +617,7 @@ export class TermctrlRegistry {
       seen: false,
       stopRequested: undefined,
       notify: true,
+      watchers: 0,
       child,
       settled,
       settle,
@@ -574,7 +635,7 @@ export class TermctrlRegistry {
     entry.exit = exit;
     entry.exitedAt = Date.now();
     entry.settle();
-    this.queueNotice(entry, entry.child.tail());
+    this.queueNotice(entry);
     this.emitChange();
   }
 

package/src/terminal-tools.ts

@@ -17,10 +17,11 @@ import type {
   TermctrlRegistry,
   TerminalEntry,
 } from "./termctrl-registry.js";
-import { describeExitStatus } from "./exit-notification.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 { TerminalExit, TerminalSnapshot } from "./terminal-driver.js";
+import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 /** Screen quiet period that settles a Terminal. */
 export const QUIET_MS = 250;
@@ -29,6 +30,8 @@ export const START_WAIT_MS = 2_000;
 export const INPUT_WAIT_MS = 500;
 export const POLL_WAIT_MS = 30_000;
 export const MAX_WAIT_MS = 5 * 60_000;
+/** How often `terminal_wait` checks for a queued message, which raises no event it can await. */
+export const PENDING_CHECK_MS = 100;
 
 const CONTROL_KEYS = Array.from(
   { length: 26 },
@@ -157,7 +160,10 @@ const StartParameters = Type.Object(
     cwd: Type.Optional(Type.String({ description: "Working directory (default: current)" })),
     wait_ms: WaitMsSchema,
     notify: Type.Optional(
-      Type.Boolean({ description: "Send an Exit notification when it exits (default true)" }),
+      Type.Boolean({
+        description:
+          "Send an Exit notification when it exits (default true); to block until it exits, use terminal_wait",
+      }),
     ),
   },
   { additionalProperties: false },
@@ -187,6 +193,66 @@ const StopParameters = Type.Object(
 
 const ListParameters = Type.Object({}, { additionalProperties: false });
 
+const WaitParameters = Type.Object(
+  {
+    ids: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "Terminal or Background job ids to wait for (default: all of yours still running)",
+      }),
+    ),
+    wait_ms: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        description: "Maximum milliseconds to wait (default and maximum 300000)",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const EntryKindSchema = Type.Union([Type.Literal("terminal"), Type.Literal("background_job")]);
+
+const WaitResultSchema = Type.Object({
+  reason: Type.Union(
+    [
+      Type.Literal("exited"),
+      Type.Literal("timeout"),
+      Type.Literal("message"),
+      Type.Literal("aborted"),
+      Type.Literal("nothing_running"),
+    ],
+    {
+      description:
+        "Why the wait ended: an exit, wait_ms, a message queued for you, cancellation, or nothing to wait for",
+    },
+  ),
+  exited: Type.Array(
+    Type.Object({
+      id: Type.String(),
+      kind: EntryKindSchema,
+      command: Type.String(),
+      exit_code: Type.Optional(Type.Number()),
+      signal: Type.Optional(Type.String()),
+      duration_ms: Type.Number(),
+      output: Type.String({
+        description: "Last lines of a Terminal's final screen or a Background job's output",
+      }),
+      log_path: Type.Optional(Type.String({ description: "Background job only: its log" })),
+    }),
+  ),
+  running: Type.Array(
+    Type.Object({
+      id: Type.String(),
+      kind: EntryKindSchema,
+      command: Type.String(),
+      age_seconds: Type.Number(),
+    }),
+  ),
+});
+type WaitResult = Static<typeof WaitResultSchema>;
+type WaitReason = WaitResult["reason"];
+
 /** Clamp a requested wait to the fixed 0 to 5 minute range. */
 export function clampWait(requested: number | undefined, fallback: number): number {
   return Math.min(MAX_WAIT_MS, Math.max(0, requested ?? fallback));
@@ -480,7 +546,10 @@ async function driveTerminal<T>(
   } catch (cause) {
     const error = cause instanceof Error ? cause : new Error(String(cause));
     if (registry.reportTerminalError(entry, error)) {
-      throw new Error(`${entry.id} was lost because the termctrl driver exited`, { cause });
+      throw new Error(
+        `${entry.id} was lost because the termctrl driver exited\n\n${TROUBLESHOOTING_HINT}`,
+        { cause },
+      );
     }
     throw error;
   } finally {
@@ -684,6 +753,142 @@ function listLine(entry: TermctrlEntry, now: number): string {
   return `${entry.id} ${state} · ${age}s · ${entry.command}${log}`;
 }
 
+/** Session-scoped values `terminal_wait` reads at call time. */
+export interface TerminalWaitRuntime {
+  readonly registry: TermctrlRegistry;
+  readonly exitTailLines: () => number;
+}
+
+/** The entries one `terminal_wait` call watches: the listed ids, or every running entry. */
+function waitTargets(
+  registry: TermctrlRegistry,
+  owner: string,
+  ids: readonly string[] | undefined,
+): TermctrlEntry[] {
+  if (ids === undefined) {
+    // An exit whose Exit notification is still queued has not reached the agent yet.
+    return registry.ownedEntries(owner).filter((entry) => entry.state === "running" || !entry.seen);
+  }
+  const targets = new Map<string, TermctrlEntry>();
+  for (const id of ids) {
+    const entry = registry.find(owner, id);
+    if (entry === undefined) throw unknownId(id);
+    targets.set(id, entry);
+  }
+  return [...targets.values()];
+}
+
+/** Wait until a target exits, the wait runs out, the call is aborted, or a message is queued. */
+function awaitExit(
+  registry: TermctrlRegistry,
+  targets: readonly TermctrlEntry[],
+  waitMs: number,
+  signal: AbortSignal | undefined,
+  hasPendingMessages: () => boolean,
+): Promise<WaitReason> {
+  const deadline = Date.now() + waitMs;
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let unsubscribe: (() => void) | undefined;
+    const check = () => {
+      let reason: WaitReason | undefined;
+      if (targets.some((entry) => entry.state === "exited")) reason = "exited";
+      else if (signal?.aborted === true) reason = "aborted";
+      else if (hasPendingMessages()) reason = "message";
+      else if (Date.now() >= deadline) reason = "timeout";
+      if (reason === undefined) {
+        clearTimeout(timer);
+        timer = setTimeout(check, Math.max(0, Math.min(PENDING_CHECK_MS, deadline - Date.now())));
+        return;
+      }
+      clearTimeout(timer);
+      unsubscribe?.();
+      signal?.removeEventListener("abort", check);
+      resolve(reason);
+    };
+    unsubscribe = registry.onChange(check);
+    signal?.addEventListener("abort", check, { once: true });
+    check();
+  });
+}
+
+const WAIT_REASON_TEXT = {
+  timeout: (waitMs) => `Nothing exited within ${Math.round(waitMs / 1000)}s.`,
+  message: () => "Returned early: a message is waiting for you.",
+  aborted: () => "Wait cancelled.",
+  nothing_running: () => "Nothing to wait for: you have no running Terminals or Background jobs.",
+} satisfies Record<Exclude<WaitReason, "exited">, (waitMs: number) => string>;
+
+/** `terminal_wait`: block until a Terminal or Background job exits. */
+export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
+  const { registry } = runtime;
+  return defineTool<typeof WaitParameters, WaitResult>({
+    name: "terminal_wait",
+    label: "terminal_wait",
+    description:
+      "Wait until one of your Terminals or Background jobs exits, then return every exit so far and what is still running. Returns early when wait_ms (default 300000) runs out or a message is queued for you. Exits it returns send no Exit notification.",
+    promptSnippet: "Wait for a Terminal or Background job to exit",
+    promptGuidelines: [
+      "Do not poll a Background job's log or a Terminal in a loop to learn when it finishes: keep working and rely on its Exit notification, or call terminal_wait when nothing else can proceed.",
+    ],
+    parameters: WaitParameters,
+    outputSchema: WaitResultSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, context) {
+      const owner = ownerOf(context);
+      const targets = waitTargets(registry, owner, params.ids);
+      const waitMs = clampWait(params.wait_ms, MAX_WAIT_MS);
+      let reason: WaitReason = "nothing_running";
+      const result: WaitResult = { reason, exited: [], running: [] };
+      const parts: string[] = [];
+      if (targets.length > 0) {
+        const release = registry.watch(targets);
+        try {
+          reason = await awaitExit(registry, targets, waitMs, signal, () =>
+            context.hasPendingMessages(),
+          );
+          const tailLines = runtime.exitTailLines();
+          for (const entry of targets) {
+            const notice = registry.noticeFor(entry);
+            if (notice === undefined) continue;
+            registry.markSeen(entry.id);
+            parts.push(formatExitNotice(notice, tailLines));
+            const exited: WaitResult["exited"][number] = {
+              id: notice.id,
+              kind: notice.kind === "job" ? "background_job" : "terminal",
+              command: notice.command,
+              ...exitFields(notice.exit),
+              duration_ms: notice.durationMs,
+              output: lastLines(notice.output, tailLines),
+            };
+            if (notice.logPath !== undefined) exited.log_path = notice.logPath;
+            result.exited.push(exited);
+          }
+        } finally {
+          release();
+        }
+      }
+      result.reason = reason;
+      if (reason !== "exited") parts.unshift(WAIT_REASON_TEXT[reason](waitMs));
+      const now = Date.now();
+      const running = registry.ownedEntries(owner).filter((entry) => entry.state === "running");
+      result.running = running.map((entry) => ({
+        id: entry.id,
+        kind: entry.kind === "job" ? "background_job" : "terminal",
+        command: entry.command,
+        age_seconds: Math.round((now - entry.startedAt) / 1000),
+      }));
+      if (running.length > 0) {
+        parts.push(`Still running:\n${running.map((entry) => listLine(entry, now)).join("\n")}`);
+      }
+      return {
+        content: [{ type: "text" as const, text: parts.join("\n\n") }],
+        details: result,
+        structuredContent: result,
+      };
+    },
+  });
+}
+
 /** `terminal_list`: list the caller's Terminals and Background jobs. */
 export function createTerminalListTool(registry: TermctrlRegistry) {
   return defineTool<typeof ListParameters, ListResult>({

package/src/troubleshooting-skill.ts

@@ -0,0 +1,9 @@
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of this package's user-invoked troubleshooting Skill. */
+export const TROUBLESHOOTING_SKILL_PATH = fileURLToPath(
+  new URL("../skills/pi-termctrl/SKILL.md", import.meta.url),
+);
+
+/** Model-facing pointer appended to failures this package's Skill diagnoses. */
+export const TROUBLESHOOTING_HINT = `For diagnosis, read the pi-termctrl troubleshooting Skill at ${TROUBLESHOOTING_SKILL_PATH}.`;