@ian-pascoe/pi-termctrl 0.8.3 → 0.9.0

package/README.md

@@ -38,8 +38,8 @@ the session's directory. A `cwd` that is missing or not a directory fails with a
 error naming the resolved path.
 
 `terminal_start` and `terminal_send` wait until the Terminal **settles**: at the
-first of 250 ms of screen quiet, a `wait_for_text` match, process exit, or
-`wait_ms` running out. `wait_for_text` is a literal substring, or a regex when
+first of 250 ms of screen quiet, a `wait_for_text` match, process exit,
+`wait_ms` running out, or a Queued Steer (see below). `wait_for_text` is a literal substring, or a regex when
 written as `/source/flags`; with `wait_for_text`, quiet alone does not end the
 wait, and text already on the screen before `terminal_send` counts only after
 the screen changes. Default waits are 2 s for `terminal_start`, 500 ms for `terminal_send`
@@ -54,10 +54,22 @@ 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
-their reason too.
+Results say why the wait ended in `settle_reason` (`matched`, `timeout`, `quiet`,
+`exited` or `steered`) and in their first line, such as
+`t1 running · settled: timeout`; a `wait_for_text` that timed out or was
+steered adds that the pattern was not seen. Polls report their reason too.
+
+**Steer Yield.** Pi hands the agent a Queued Steer (a message the user or a
+parent agent queued while it works) only after every tool call in the current
+batch has returned, so a long wait would delay it. When a Queued Steer is
+pending for the session, the settle wait of `terminal_start` and `terminal_send`
+ends at once with `settle_reason: "steered"` (`t1 running · settled: steered`).
+Input (`text`, `keys`) is still typed first, and the Terminal keeps running; poll
+it again with `terminal_send` once you have read the message. A steer stays
+pending until Pi starts the next turn, so a call that starts while one is
+pending settles immediately after typing its input. Calls waiting in the Call
+queue still run in order, each yielding as soon as it reaches its settle wait.
+Follow-ups never count.
 
 Sending `text` or `keys` to an exited Terminal is an error that names its exit
 code or signal; a poll (neither `text` nor `keys`) still returns its final screen.
@@ -134,9 +146,12 @@ paths.
 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_ms` runs out, when the call is aborted, or as a Steer Yield with
+`reason: "steered"` as soon as a Queued Steer is pending for the session, such
+as the user steering or a parent agent's message; whatever it waited on keeps
+running, and a watched entry that exits after that is notified as usual. A
+follow-up never ends the wait, and neither does another entry's Exit
+notification: Exit notifications wait for the end of the turn. With nothing to
 wait for it returns at once. Terminal exits are noticed within about 500 ms.
 
 ### Tool annotations
@@ -149,13 +164,22 @@ 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 and rendering, and foreground results differ from Pi's only
-by the shorter tail below. A command becomes a Background job in two ways:
+by the shorter tail below. A command becomes a Background job in three 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
   is reached during those 2 s, the command stays in the foreground.
 - **Ctrl+B** while an agent `bash` call runs moves every running call to the
   background. At other times Ctrl+B stays the editor's cursor-left.
+- **Steer Yield**: when a Queued Steer becomes pending for the session, every
+  running `bash` call of that session moves to the background at once, exactly
+  as Ctrl+B does, so the message reaches the agent without waiting for the
+  command. A call that starts while a Queued Steer is pending becomes a
+  Background job as soon as it has started, even with `background: false`. The
+  result says why, as in
+  `Command moved to the background as b3 because a message was queued for you`.
+  If the job cap is reached, the call stays in the foreground and the user gets
+  a notification saying so. Follow-ups never count.
 
 Up to 16 MiB of a command's output is kept in memory until it is backgrounded;
 older output becomes an omission line in the log. Once backgrounded, a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -34,7 +34,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.8.0",
+    "@ian-pascoe/pi-utils": "^0.9.0",
     "@kitlangton/terminal-control": "^1.2.1"
   },
   "peerDependencies": {

package/src/bash-replacement.ts

@@ -19,6 +19,7 @@ import {
   type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
+import { hasQueuedSteer, onQueuedSteer } from "@ian-pascoe/pi-utils/queued-steer";
 import { noticeText } from "@ian-pascoe/pi-utils/ui";
 import { Type, type TSchema } from "typebox";
 import { KILLED_EXIT, TermctrlRegistry } from "./termctrl-registry.js";
@@ -47,9 +48,14 @@ export function backgroundLogPath(id: string): string {
   return join(termctrlTemporaryDirectory(), `${process.pid}-${id}.log`);
 }
 
+/** What moved a running call to the background without the model asking: the user, or a Steer Yield. */
+export type BackgroundCause = "user" | "steer";
+
 /** What a backgrounded call reports to the agent. */
 interface BackgroundOutcome {
   readonly id: string;
+  /** What moved the call; undefined when the model asked for the background. */
+  readonly cause: BackgroundCause | undefined;
   readonly logPath: string;
   readonly output: string;
   /** What the in-memory buffer dropped from the head of `output`. */
@@ -85,9 +91,11 @@ class BashCall {
   private resolveBackground!: (outcome: BackgroundOutcome) => void;
   readonly backgrounded: Promise<BackgroundOutcome>;
   private isBackgrounded = false;
+  /** Runs right after the command was handed to Pi's `exec`, before it can print anything. */
+  onStarted: (() => void) | undefined;
 
   constructor(
-    private readonly owner: string,
+    readonly owner: string,
     private readonly command: string,
     private readonly local: BashOperations,
   ) {
@@ -142,7 +150,9 @@ class BashCall {
         signal: this.controller.signal,
       };
       if (env !== undefined) localOptions.env = env;
-      const result = await this.local.exec(command, cwd, localOptions);
+      const running = this.local.exec(command, cwd, localOptions);
+      this.onStarted?.();
+      const result = await running;
       this.finish({ code: result.exitCode, signal: null });
       return result;
     } catch (error) {
@@ -188,7 +198,7 @@ class BashCall {
   }
 
   /** Move the running command to the background. Returns false when it already finished. */
-  background(registry: TermctrlRegistry): boolean {
+  background(registry: TermctrlRegistry, cause?: BackgroundCause): boolean {
     if (this.isBackgrounded || this.settled || !this.started) return false;
     // An aborted or timed-out command is already dying; let Pi report it.
     if (this.controller.signal.aborted) return false;
@@ -226,6 +236,7 @@ class BashCall {
     this.remember(output);
     this.resolveBackground({
       id: entry.id,
+      cause,
       logPath: entry.child.logPath,
       output,
       dropped: this.dropped(),
@@ -234,22 +245,31 @@ class BashCall {
   }
 }
 
-/** The agent `bash` calls running in one session, and the Ctrl+B subscription while any run. */
+/** Pi's `bash` calls running in one session, and the Ctrl+B and Queued Steer subscriptions while any run. */
 export class RunningBashCalls {
   private readonly calls = new Set<BashCall>();
   private unsubscribe: (() => void) | undefined;
 
   constructor(private readonly registry: () => TermctrlRegistry) {}
 
-  /** Track a call; the first one subscribes to Ctrl+B. */
+  /** Track a call; the first one subscribes to Ctrl+B and to Queued Steers for its session. */
   add(call: BashCall, ui: ExtensionUIContext): void {
     this.calls.add(call);
+    // A call that starts while a steer is pending moves at once; later steers reach it below.
+    call.onStarted = () => {
+      if (hasQueuedSteer(call.owner)) this.backgroundOne(call, ui, "steer");
+    };
     if (this.unsubscribe !== undefined) return;
-    this.unsubscribe = ui.onTerminalInput((data) => {
+    const stopSteers = onQueuedSteer(call.owner, () => this.backgroundAll(ui, "steer"));
+    const stopInput = ui.onTerminalInput((data) => {
       if (!matchesKey(data, "ctrl+b")) return undefined;
       this.backgroundAll(ui);
       return { consume: true };
     });
+    this.unsubscribe = () => {
+      stopSteers();
+      stopInput();
+    };
   }
 
   /** Stop tracking a call; the last one releases Ctrl+B back to the editor. */
@@ -259,17 +279,29 @@ export class RunningBashCalls {
     this.dispose();
   }
 
-  /** Move every running call to the background. */
-  backgroundAll(ui: Pick<ExtensionUIContext, "notify">): void {
-    for (const call of this.calls) {
-      try {
-        call.background(this.registry());
-      } catch (error) {
-        ui.notify(
-          noticeText("Termctrl", error instanceof Error ? error.message : String(error)),
-          "warning",
-        );
-      }
+  /** Move every running call to the background, as Ctrl+B does and as a Queued Steer does. */
+  backgroundAll(ui: Pick<ExtensionUIContext, "notify">, cause: BackgroundCause = "user"): void {
+    for (const call of this.calls) this.backgroundOne(call, ui, cause);
+  }
+
+  private backgroundOne(
+    call: BashCall,
+    ui: Pick<ExtensionUIContext, "notify">,
+    cause: BackgroundCause,
+  ): void {
+    try {
+      call.background(this.registry(), cause === "steer" ? cause : undefined);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      ui.notify(
+        noticeText(
+          "Termctrl",
+          cause === "steer"
+            ? `A message was queued for the agent, but its running bash call stayed in the foreground: ${reason}`
+            : reason,
+        ),
+        "warning",
+      );
     }
   }
 
@@ -416,7 +448,8 @@ function backgroundResult(
   }
   // 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}"}.`;
+  const why = outcome.cause === "steer" ? " because a message was queued for you" : "";
+  const status = `Command moved to the background as ${outcome.id}${why}. 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,
@@ -513,6 +546,8 @@ export function createBashReplacement(options: BashReplacementOptions) {
             };
       const startedAt = performance.now();
       const limits = options.bashTail;
+      // Tracked before Pi's `execute` runs, which may reach `exec` at once.
+      options.calls.add(call, context.ui);
       const piRunning = inner.execute(
         toolCallId,
         params.timeout === undefined
@@ -534,7 +569,6 @@ export function createBashReplacement(options: BashReplacementOptions) {
               },
             );
       running.catch(() => {});
-      options.calls.add(call, context.ui);
       const yieldTimer =
         params.background === true
           ? setTimeout(() => {

package/src/pi-termctrl-extension.ts

@@ -8,6 +8,7 @@ import {
   type SessionShutdownEvent,
 } from "@earendil-works/pi-coding-agent";
 import { acceptNullForOptionalArguments } from "@ian-pascoe/pi-utils/null-optional-arguments";
+import { trackQueuedSteers } from "@ian-pascoe/pi-utils/queued-steer";
 import { expandMessageOnClick, noticeText } from "@ian-pascoe/pi-utils/ui";
 import { createBashReplacement, RunningBashCalls } from "./bash-replacement.js";
 import {
@@ -86,6 +87,7 @@ class PiTermctrlController {
   }
 
   register(): void {
+    trackQueuedSteers(this.pi);
     this.pi.registerMessageRenderer(
       EXIT_NOTIFICATION_TYPE,
       expandMessageOnClick(renderExitNotification),

package/src/terminal-render.ts

@@ -351,7 +351,7 @@ export function renderListResult(
 const WAIT_REASON_SUMMARY = {
   exited: undefined,
   timeout: "Nothing exited before the wait ended",
-  message: "Returned early: a message is waiting",
+  steered: "Returned early: a message is queued for you",
   aborted: "Wait cancelled",
   nothing_running: "Nothing to wait for",
 } as const satisfies Record<WaitResult["reason"], string | undefined>;

package/src/terminal-tools.ts

@@ -8,6 +8,7 @@ import {
   truncateTail,
   type ExtensionToolContext,
 } from "@earendil-works/pi-coding-agent";
+import { watchQueuedSteer } from "@ian-pascoe/pi-utils/queued-steer";
 import type { Key } from "@kitlangton/terminal-control";
 import { Type, type Static } from "typebox";
 import type {
@@ -40,8 +41,6 @@ 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 },
@@ -93,10 +92,16 @@ export type TerminalResultRuntime = Pick<TerminalToolRuntime, "registry" | "scro
 const TerminalStateSchema = Type.Union([Type.Literal("running"), Type.Literal("exited")]);
 
 const SettleReasonSchema = Type.Union(
-  [Type.Literal("matched"), Type.Literal("timeout"), Type.Literal("quiet"), Type.Literal("exited")],
+  [
+    Type.Literal("matched"),
+    Type.Literal("timeout"),
+    Type.Literal("quiet"),
+    Type.Literal("exited"),
+    Type.Literal("steered"),
+  ],
   {
     description:
-      "Why the wait ended: wait_for_text matched, wait_ms ran out or the call was cancelled, the screen was quiet for 250 ms, or the Terminal exited",
+      "Why the wait ended: wait_for_text matched, wait_ms ran out or the call was cancelled, the screen was quiet for 250 ms, the Terminal exited, or a message was queued for you (steered; the Terminal keeps running)",
   },
 );
 
@@ -280,13 +285,13 @@ const WaitResultSchema = Type.Object({
     [
       Type.Literal("exited"),
       Type.Literal("timeout"),
-      Type.Literal("message"),
+      Type.Literal("steered"),
       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",
+        "Why the wait ended: an exit, wait_ms, a steer queued for you (steered), cancellation, or nothing to wait for",
     },
   ),
   exited: Type.Array(
@@ -342,12 +347,28 @@ interface SettleRequest {
   /** The screen before the call. A match already on it counts only once the screen changes. */
   readonly baseline: string | undefined;
   readonly signal: AbortSignal | undefined;
+  /** Aborts once a Queued Steer is pending, which ends the wait with a Steer Yield. */
+  readonly steer: AbortSignal | undefined;
+}
+
+/** Sleep `milliseconds`, or until `steer` aborts. */
+function pause(milliseconds: number, steer: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      steer?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, milliseconds);
+    steer?.addEventListener("abort", done, { once: true });
+  });
 }
 
 /**
  * Poll a Terminal until it settles: screen quiet for 250 ms, a `wait_for_text` match, process exit,
- * or the wait budget running out. A poll (no input) settles on quiet only after new output.
- * With `wait_for_text`, quiet does not settle the wait.
+ * the wait budget running out, or a Queued Steer (a Steer Yield; the Terminal keeps running). A
+ * poll (no input) settles on quiet only after new output. With `wait_for_text`, quiet does not
+ * settle the wait.
  */
 export async function settleTerminal(
   entry: TerminalEntry,
@@ -380,7 +401,8 @@ export async function settleTerminal(
       return { snapshot, reason: "quiet" };
     }
     if (now >= deadline || request.signal?.aborted === true) return { snapshot, reason: "timeout" };
-    await new Promise((resolve) => setTimeout(resolve, Math.min(POLL_MS, deadline - now)));
+    if (request.steer?.aborted === true) return { snapshot, reason: "steered" };
+    await pause(Math.min(POLL_MS, deadline - now), request.steer);
   }
 }
 
@@ -769,7 +791,7 @@ function screenMarker(label: string, screen: string, view: ScreenView): string {
 
 /** Says that `wait_for_text` was not seen when its wait timed out. */
 function unmatchedNote(reason: SettleReason, pattern: string | undefined): string | undefined {
-  return reason === "timeout" && pattern !== undefined
+  return (reason === "timeout" || reason === "steered") && pattern !== undefined
     ? `wait_for_text ${JSON.stringify(pattern)} was not seen before the wait ended.`
     : undefined;
 }
@@ -971,13 +993,27 @@ function shellCommand(shell: TerminalShell, command: string): [string, ...string
   return [shell.shell, ...shell.args, script];
 }
 
+/** Settle a Terminal for the session, ending the wait early when a Queued Steer is pending. */
+async function settleForSession(
+  entry: TerminalEntry,
+  sessionId: string,
+  request: Omit<SettleRequest, "steer">,
+): Promise<{ readonly snapshot: TerminalSnapshot; readonly reason: SettleReason }> {
+  const watch = watchQueuedSteer(sessionId);
+  try {
+    return await settleTerminal(entry, { ...request, steer: watch.signal });
+  } finally {
+    watch.dispose();
+  }
+}
+
 /** `terminal_start`: run a program in a new Terminal and wait for it to settle. */
 export function createTerminalStartTool(runtime: TerminalToolRuntime) {
   return defineTool<typeof StartParameters, TerminalResult>({
     name: "terminal_start",
     label: "terminal_start",
     description:
-      "Start a program in a new interactive Terminal (a PTY) and return its screen once it settles: 250 ms of quiet, exit, or wait_ms (default 2000). Use it for REPLs, TUIs, prompts and other programs that need input or a screen. Drive it with terminal_send and end it with terminal_stop.",
+      "Start a program in a new interactive Terminal (a PTY) and return its screen once it settles: 250 ms of quiet, exit, wait_ms (default 2000), or a message queued for you (settle_reason steered; the Terminal keeps running). Use it for REPLs, TUIs, prompts and other programs that need input or a screen. Drive it with terminal_send and end it with terminal_stop.",
     promptSnippet: "Start an interactive program (REPL, TUI, prompt) in a Terminal",
     promptGuidelines: [
       "Use terminal_start, terminal_send and terminal_stop for programs that need input or a screen; use bash for everything else.",
@@ -1007,7 +1043,7 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
       // 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, {
+        const { snapshot, reason } = await settleForSession(entry, ownerOf(context), {
           mode: "start",
           waitMs: clampWait(params.wait_ms, START_WAIT_MS),
           startedAt,
@@ -1040,7 +1076,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
     name: "terminal_send",
     label: "terminal_send",
     description:
-      "Type text and press keys in a Terminal, then return its screen once it settles: 250 ms of quiet, a wait_for_text match, exit, or wait_ms (default 500). With neither text nor keys it polls: it waits up to wait_ms (default 30000) for new output. Results include the lines that scrolled off since your previous result; a truncated result names a file with its full output. When the rows above the previous result's cursor row are unchanged, the screen shows only the rows from there down; an unchanged screen shows no rows; full_screen: true shows the whole screen.",
+      "Type text and press keys in a Terminal, then return its screen once it settles: 250 ms of quiet, a wait_for_text match, exit, wait_ms (default 500), or a message queued for you (settle_reason steered; the Terminal keeps running). With neither text nor keys it polls: it waits up to wait_ms (default 30000) for new output. Results include the lines that scrolled off since your previous result; a truncated result names a file with its full output. When the rows above the previous result's cursor row are unchanged, the screen shows only the rows from there down; an unchanged screen shows no rows; full_screen: true shows the whole screen.",
     promptSnippet: "Send input to a Terminal, or poll it, and read its screen",
     parameters: SendParameters,
     annotations: {
@@ -1094,7 +1130,7 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
         if (params.text !== undefined && params.text !== "") await entry.handle.type(params.text);
         const validKeys = keys.filter(isKey);
         if (validKeys.length > 0) await entry.handle.press(validKeys);
-        const { snapshot, reason } = await settleTerminal(entry, {
+        const { snapshot, reason } = await settleForSession(entry, ownerOf(context), {
           mode: hasInput ? "input" : "poll",
           waitMs: clampWait(params.wait_ms, hasInput ? INPUT_WAIT_MS : POLL_WAIT_MS),
           startedAt,
@@ -1267,43 +1303,44 @@ function waitTargets(
   return [...targets.values()];
 }
 
-/** Wait until a target exits, the wait runs out, the call is aborted, or a message is queued. */
+/**
+ * Wait until a target exits, the wait runs out, the call is aborted, or a Queued Steer is pending
+ * (`steer` aborts; the targets keep running).
+ */
 function awaitExit(
   registry: TermctrlRegistry,
   targets: readonly TermctrlEntry[],
   waitMs: number,
   signal: AbortSignal | undefined,
-  hasPendingMessages: () => boolean,
+  steer: AbortSignal,
 ): 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);
+    const cleanups: (() => void)[] = [];
+    const finish = (reason: WaitReason) => {
+      for (const cleanup of cleanups.splice(0)) cleanup();
       resolve(reason);
     };
-    unsubscribe = registry.onChange(check);
+    const check = () => {
+      if (targets.some((entry) => entry.state === "exited")) finish("exited");
+      else if (signal?.aborted === true) finish("aborted");
+      else if (steer.aborted) finish("steered");
+    };
+    const timer = setTimeout(() => finish("timeout"), waitMs);
+    cleanups.push(
+      () => clearTimeout(timer),
+      registry.onChange(check),
+      () => signal?.removeEventListener("abort", check),
+      () => steer.removeEventListener("abort", check),
+    );
     signal?.addEventListener("abort", check, { once: true });
+    steer.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.",
+  steered: () => "Returned early: a message is queued 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>;
@@ -1315,7 +1352,7 @@ export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
     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.",
+      "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 steer is queued for you; whatever it waited on keeps running. 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.",
@@ -1339,10 +1376,9 @@ export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
       const parts: string[] = [];
       if (targets.length > 0) {
         const release = registry.watch(targets);
+        const steer = watchQueuedSteer(owner);
         try {
-          reason = await awaitExit(registry, targets, waitMs, signal, () =>
-            context.hasPendingMessages(),
-          );
+          reason = await awaitExit(registry, targets, waitMs, signal, steer.signal);
           const tailLines = runtime.exitTailLines();
           for (const entry of targets) {
             const notice = registry.noticeFor(entry);
@@ -1361,6 +1397,7 @@ export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
             result.exited.push(exited);
           }
         } finally {
+          steer.dispose();
           release();
         }
       }