pi-pier 0.3.0 → 0.4.1

package/src/{core → plugins}/terminal.ts

@@ -1,20 +1,15 @@
 /**
  * M14 terminal loader entry for the D78 mount tree and D81 responsibility split.
- *
- * Keeping this as a Cordis loader plugin makes the terminal surface hot-swappable. Services
- * provide the D79 tombstone-aware pi surface, herdr client/environment, and the state slot
- * used by index GC. Avoiding an index.ts import preserves an acyclic dependency graph, while
- * terminal-core remains independently testable pure logic.
+ * A Cordis loader plugin so the terminal surface stays hot-swappable: services provide the tombstone-aware
+ * pi surface, the herdr client/environment and the state slot used by index GC; terminal-core holds the
+ * pure, independently testable logic.
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
-import type { PiSurface } from '../pi-surface.ts';
+import { cordisGet } from '../cordis-services.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
 import { herdrUnavailableHint } from '../herdr-client.ts';
 import { toolError } from '../tool-error.ts'
-
-/** Raw tool arguments: every field is validated inside the action handlers. */
-type ToolParams = Record<string, unknown> | undefined;;
 import {
   READINESS_TIMEOUT_MS,
   READ_MAX_CHARS,
@@ -24,50 +19,62 @@ import {
   classifyReadiness,
   closeTerminal,
   computeIncrement,
+  classifyWaitMatch,
   detectFullscreenTUI,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
-  planIdleTerminalReminder,
+  planTerminalReminder,
   planShellInit,
   promptStrategyFor,
   registerTerminal,
+  sentinelEchoHazard,
   stripAnsi,
   summarizeSessions,
   terminalReminderGraceMs,
   validateSendText,
   validateSignal,
   type ReadCursor,
+  type ReadinessTier,
   type TerminalEntry,
 } from '../terminal-core.ts';
 import { swallow } from '../swallow.ts';
 import { pierOption } from '../pier-options.ts';
 
+type ToolParams = Record<string, unknown> | undefined;
+
+/** Terminal tool actions; the tool schema union and the handler map are both keyed by this list. */
+const TERMINAL_ACTIONS = ['open', 'send', 'wait', 'read', 'signal', 'close', 'list'] as const;
+type TerminalAction = (typeof TERMINAL_ACTIONS)[number];
+type ActionHandler = (params: ToolParams, ctx: unknown) => Promise<unknown>;
+
 export interface TerminalStateSlot {
   /** Lets index GC preserve panes that host active terminals. */
   activePaneIds: () => Set<string>;
 }
 
-interface TerminalDeps {
+export interface TerminalDeps {
   client: HerdrClientLike;
   env: { paneId: string; tabId: string } | null;
   state: TerminalStateSlot;
 }
 
 export default function terminalPlugin(ctx: Context): void {
-  const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
-  const { client, env, state } = ctx.get('pi-herdr.terminal-deps') as TerminalDeps;
+  const surface = cordisGet(ctx, 'pi-herdr.surface');
+  const { client, env, state } = cordisGet(ctx, 'pi-herdr.terminal-deps');
   const pi = surface.raw as {
     appendEntry?: (customType: string, data: unknown) => void;
   };
   // Keying the surface by this file lets HMR tombstone and replace exactly this registration.
   const scoped = surface.forModule(import.meta.url);
 
-  /* ── M14 resident terminal tools (D71 / T1–T6) ────────────────────
-   * Dedicated herdr panes preserve shell state without reusing the pi TUI pane, and active
-   * terminal panes remain exempt from index GC. Workers omit this master-side entry. */
+  /* M14 resident terminal tools: dedicated herdr panes preserve shell state without reusing the pi TUI pane,
+   * and active terminal panes remain exempt from index GC. Workers omit this master-side entry. */
 
   let terminals: TerminalEntry[] = [];
 
+  /** Last text sent per terminal (in-memory): lets `wait` refuse patterns that match their own echo. */
+  const lastSentText = new Map<string, string>();
+
   function persistTerminals(): void {
     try {
       pi.appendEntry?.(TERMINALS_CUSTOM_TYPE, makeTerminalsRegistry(terminals));
@@ -97,7 +104,6 @@ export default function terminalPlugin(ctx: Context): void {
     persistTerminals();
   }
 
-  // Expose active panes so index GC does not collect resident terminal shells.
   state.activePaneIds = () => activeTerminalPaneIds(terminals);
 
   scoped.on('session_start', async (_event: unknown, eventCtx: unknown) => {
@@ -108,9 +114,8 @@ export default function terminalPlugin(ctx: Context): void {
   });
 
   // Session teardown (quit / Ctrl+D / SIGTERM) is the last chance to reclaim resident shells:
-  // terminals are persistent by design, so a master that exits without closing them leaks live
-  // zsh panes. Session SWITCH never fires this event (only session_start/session_tree), so
-  // switching branches cannot kill shells that the registry replays on the next session_start.
+  // a master that exits without closing them leaks live zsh panes. Session SWITCH never fires this
+  // event, so switching branches cannot kill shells that session_start replays from the registry.
   scoped.on('session_shutdown', async () => {
     idleReminderTimer && clearTimeout(idleReminderTimer);
     idleReminderTimer = null;
@@ -124,18 +129,20 @@ export default function terminalPlugin(ctx: Context): void {
     persistTerminals();
   });
 
-  // Turn-end nudge: remind the model to close terminals idle past the threshold (wF:p7 orphan —
-  // a one-shot background compile left a dead split in the main tab forever). Same delivery
-  // shape as the todo stop reminder: grace window, cancel on agent_start, capped followUp.
+  // Turn-end nudge: remind the model to close terminals it just used, then once more after the idle
+  // threshold. Same delivery shape as the todo stop reminder: grace window, cancel on agent_start,
+  // capped per terminal.
   const piSend = surface.raw as {
     sendMessage?: (
       message: { customType: string; content: string; display?: boolean },
       opts?: { deliverAs?: string; triggerTurn?: boolean },
-    ) => Promise<void>;
+    ) => void;
   };
-  let idleReminders = 0;
+  /** Start of the current agent run; terminals touched since then count as "used this turn". */
+  let turnStartedAt: number | null = null;
   let idleReminderTimer: NodeJS.Timeout | null = null;
   scoped.on('agent_start', () => {
+    turnStartedAt = Date.now();
     if (idleReminderTimer !== null) {
       clearTimeout(idleReminderTimer);
       idleReminderTimer = null;
@@ -146,35 +153,46 @@ export default function terminalPlugin(ctx: Context): void {
       clearTimeout(idleReminderTimer);
       idleReminderTimer = null;
     }
-    const plan = planIdleTerminalReminder({
-      open: terminals.filter((t) => t.status === 'open'),
+    const open = await Promise.all(
+      terminals
+        .filter((t) => t.status === 'open')
+        .map(async (t) => {
+          // A pane running a foreground job (dev server, REPL, load test) is in use even when the
+          // last tool interaction is old: nudge only after it is back at a shell prompt.
+          const info = await client.processInfo(t.paneId).catch(() => null);
+          const busy = info?.shellPid != null
+            && info.foreground.some((p) => p.pid != null && p.pid !== info.shellPid);
+          return { ...t, busy };
+        }),
+    );
+    const plan = planTerminalReminder({
+      open,
       now: Date.now(),
-      reminders: idleReminders,
+      turnStartedAt,
     });
+    turnStartedAt = null;
     if (!plan.due || plan.content == null) return;
-    // 01a06ae3 goodbye-loop: mark the covered terminals nudged NOW (persisted), and deliver the
-    // notice as a queued followUp WITHOUT triggerTurn — a reminder alone must never wake the
-    // agent, or a farewell exchange loops: wake → polite goodbye → settle → nudge → wake …
+    // Goodbye-loop guard: bump each covered terminal's nudge count NOW (persisted), and deliver the
+    // notice as a queued followUp WITHOUT triggerTurn — a reminder must never wake the agent.
     const now = Date.now();
     const ids = new Set(plan.ids);
-    terminals = terminals.map((t) => (ids.has(t.terminalId) ? { ...t, nudgedAt: now } : t));
+    terminals = terminals.map((t) => (ids.has(t.terminalId)
+      ? { ...t, nudges: (t.nudges ?? (t.nudgedAt != null ? 1 : 0)) + 1, nudgedAt: now }
+      : t));
     persistTerminals();
-    idleReminders += 1;
     const content = plan.content;
     idleReminderTimer = setTimeout(() => {
       idleReminderTimer = null;
-      void (async () => {
-        const send = piSend.sendMessage;
-        if (typeof send !== 'function') return;
-        try {
-          await send(
-            { customType: TERM_REMINDER_CUSTOM_TYPE, content, display: true },
-            { deliverAs: 'followUp' },
-          );
-        } catch {
-          /* Delivery failure is non-fatal; the cap already bounds retries. */
-        }
-      })();
+      const send = piSend.sendMessage;
+      if (typeof send !== 'function') return;
+      try {
+        // Fire-and-forget in pi (void); a synchronous throw is still swallowed here.
+        send(
+          { customType: TERM_REMINDER_CUSTOM_TYPE, content, display: true },
+          { deliverAs: 'followUp' },
+        );
+      } catch {
+      }
     }, terminalReminderGraceMs());
     idleReminderTimer.unref?.();
   });
@@ -189,6 +207,17 @@ export default function terminalPlugin(ctx: Context): void {
   /** A1: a hard failure must throw (pi sets isError only for throws); non-failures stay results. */
   const fail = (msg: string): never => toolError(msg);
 
+  // Action routing: each handler validates its own params, and `open` additionally needs the tool ctx.
+  const handlers: Record<TerminalAction, ActionHandler> = {
+    open: executeTerminalOpen,
+    send: executeTerminalSend,
+    wait: executeTerminalWait,
+    read: executeTerminalRead,
+    signal: executeTerminalSignal,
+    close: executeTerminalClose,
+    list: executeTerminalList,
+  };
+
   scoped.registerTool({
     name: 'terminal',
     label: 'Terminal',
@@ -196,10 +225,7 @@ export default function terminalPlugin(ctx: Context): void {
       'Manage persistent interactive terminals (resident shells in dedicated herdr panes).',
       'Operations: open (create session), send (type commands), wait (block until output matches a pattern), read (capture output), signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close (kill shell), list (show all).',
       'The shell keeps cwd, environment variables, and background processes across calls.',
-      'Use for dev servers, REPLs, or multi-step shell work — not one-shot bash calls.',
-      'Close a terminal with action: "close" as soon as the work in it is done — finished terminals are never auto-reclaimed and keep occupying a pane.',
-      'Long job pattern: send "cmd; echo TERM_DONE_$?" then wait with pattern "TERM_DONE_" — the sentinel also carries the exit code; redirect verbose output to a log file and read the file, because output between two reads is lost.',
-      'After send, use read to confirm the command actually started; multi-line text executes line-by-line. send(wait_prompt: true) refuses to queue text while a previous command is still running.',
+      'Long job pattern: send "cmd; echo TERM_DONE_$?" then wait with regex "^TERM_DONE_[0-9]" — the shell echoes the typed command, so a literal wait on "TERM_DONE_" would match its own echo instantly; keep the sentinel distinguishable from its echo. Redirect verbose output to a log file and read the file, because output between two reads is lost.',
     ].join(' '),
     promptSnippet: 'terminal: a persistent shell in its own pane — use for dev servers, REPLs, and multi-step shell work that must keep state between calls.',
     promptGuidelines: [
@@ -210,20 +236,12 @@ export default function terminalPlugin(ctx: Context): void {
       'Close the terminal as soon as the work is done — a finished terminal keeps occupying a pane and is never auto-reclaimed.',
     ],
     parameters: Type.Object({
-      action: Type.Union([
-        Type.Literal('open'),
-        Type.Literal('send'),
-        Type.Literal('wait'),
-        Type.Literal('read'),
-        Type.Literal('signal'),
-        Type.Literal('close'),
-        Type.Literal('list'),
-      ], { description: 'Terminal operation to perform' }),
+      action: Type.Union(TERMINAL_ACTIONS.map((name) => Type.Literal(name)), { description: 'Terminal operation to perform' }),
       cwd: Type.Optional(Type.String({ description: '[open] Working directory for the shell (defaults to session cwd)' })),
-      terminal_id: Type.Optional(Type.String({ description: '[send|wait|read|signal|close] Terminal id returned by open action' })),
+      terminal_id: Type.Optional(Type.String({ description: '[open] optional requested id for the new terminal (defaults to auto-assigned term-N); [send|wait|read|signal|close] terminal id returned by open' })),
       text: Type.Optional(Type.String({ description: '[send] Command text to type and run (Enter appended automatically)' })),
       wait_prompt: Type.Optional(Type.Boolean({ description: '[send] Verify the shell is back at a prompt before sending; refuses with the detected readiness instead of queueing text behind a running command' })),
-      pattern: Type.Optional(Type.String({ description: '[wait] Literal text or regular expression to wait for in pane output' })),
+      pattern: Type.Optional(Type.String({ description: '[wait] Literal text or regular expression to wait for in pane output (must not occur in the command text you sent — echoed input matches too)' })),
       regex: Type.Optional(Type.Boolean({ description: '[wait] Treat pattern as a regular expression (default: literal substring)' })),
       timeout_ms: Type.Optional(Type.Number({ description: '[wait] Give up after this many ms (default 120000, max 600000)' })),
       pane_id: Type.Optional(Type.String({ description: '[read] Direct pane read (limited to own tab panes only)' })),
@@ -232,39 +250,43 @@ export default function terminalPlugin(ctx: Context): void {
     }),
     async execute(_tc: string, params: ToolParams, _sig: AbortSignal | undefined, _upd: unknown, ctx: unknown) {
       const action = typeof params?.action === 'string' ? params.action : '';
-      switch (action) {
-        case 'open': return executeTerminalOpen(params, ctx);
-        case 'send': return executeTerminalSend(params);
-        case 'wait': return executeTerminalWait(params);
-        case 'read': return executeTerminalRead(params);
-        case 'signal': return executeTerminalSignal(params);
-        case 'close': return executeTerminalClose(params);
-        case 'list': return executeTerminalList();
-        default:
-          return fail(action
-            ? `unknown action "${action}" (valid: open, send, wait, read, signal, close, list)`
-            : 'action is required (open, send, wait, read, signal, close, list)');
+      const handler: ActionHandler | undefined = handlers[action as TerminalAction];
+      if (!handler) {
+        const valid = TERMINAL_ACTIONS.join(', ');
+        return fail(action
+          ? `unknown action "${action}" (valid: ${valid})`
+          : `action is required (${valid})`);
       }
+      return handler(params, ctx);
     },
   });
 
   /** Probe whether the shell sits at its interactive prompt (advisory: probe failures degrade to 'busy'). */
-  async function probeReadiness(paneId: string): Promise<'prompt' | 'silent' | 'busy'> {
+  async function probeReadiness(paneId: string): Promise<ReadinessTier> {
     const prompt = promptStrategyFor();
     try {
       const waitRes = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
-      const isMatched = waitRes && typeof waitRes === 'object' && 'matched' in waitRes
-        ? (waitRes as { matched: boolean }).matched
-        : Boolean(waitRes);
-      if (isMatched) return 'prompt';
+      if (waitRes.matched) return 'prompt';
       const read = await client.readPane(paneId, { stripAnsi: false });
       return classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
     } catch {
-      /* Readiness is advisory, so probe failures still leave a usable terminal. */
       return 'busy';
     }
   }
 
+  /** Best-effort `set +H` right after a shell becomes usable (history expansion would wedge it);
+   *  returns whether the command was injected, so a shell not yet at its prompt retries later. */
+  async function injectShellInit(entry: TerminalEntry, readiness?: ReadinessTier): Promise<boolean> {
+    const init = planShellInit({ strategy: promptStrategyFor(), readiness });
+    if (!init.shouldInit || !init.command) return false;
+    try {
+      await client.sendPaneText(entry.paneId, init.command);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   async function executeTerminalOpen(params: ToolParams, ctx: unknown) {
     if (!client.available || !env) return fail('terminal tools require a herdr-managed pane');
     const cwd = typeof params?.cwd === 'string' && params.cwd ? params.cwd
@@ -273,6 +295,9 @@ export default function terminalPlugin(ctx: Context): void {
       paneId: env.paneId, // Reserve a valid id until split returns the terminal pane.
       tabId: env.tabId,
       cwd,
+      // Adopt the caller-requested id so `open {terminal_id}` + `send {terminal_id}` agree;
+      // silently ignoring it made the follow-up send fail on an unknown terminal.
+      terminalId: typeof params?.terminal_id === 'string' ? params.terminal_id : null,
       createdAt: Date.now(),
     });
     if (!r.ok) return fail(r.error);
@@ -287,16 +312,9 @@ export default function terminalPlugin(ctx: Context): void {
     terminals = r.entries;
     persistTerminals();
     const readiness = await probeReadiness(paneId);
-    const prompt = promptStrategyFor();
-    const init = planShellInit({ strategy: prompt, readiness });
-    if (init.shouldInit && init.command) {
-      try {
-        await client.sendPaneText(paneId, init.command);
-        r.entry.initialized = true;
-        persistTerminals();
-      } catch {
-        /* Shell init is best-effort: failure to set +H does not block terminal usage */
-      }
+    if (await injectShellInit(r.entry, readiness)) {
+      r.entry.initialized = true;
+      persistTerminals();
     }
     const text = [
       `terminal ${r.entry.terminalId} open (pane ${paneId})`,
@@ -312,22 +330,13 @@ export default function terminalPlugin(ctx: Context): void {
     const v = validateSendText(typeof params?.text === 'string' ? params.text : '');
     if (!v.ok) return fail(v.error);
     if (!entry.initialized) {
-      const prompt = promptStrategyFor();
-      const init = planShellInit({ strategy: prompt });
-      if (init.shouldInit && init.command) {
-        try {
-          await client.sendPaneText(entry.paneId, init.command);
-        } catch {
-          /* Shell init is best-effort */
-        }
-      }
+      await injectShellInit(entry);
       entry.initialized = true;
       persistTerminals();
     }
     if (params?.wait_prompt === true) {
-      // Orchestration convention: read before writing. Text typed while a previous command still
-      // owns the foreground gets queued and fires later, which reads as "the shell ignored me".
-      // Refuse with the observed readiness instead of guessing.
+      // Orchestration convention: read before writing. Text typed while a previous command still owns the
+      // foreground gets queued and fires later, which reads as "the shell ignored me"; refuse with the observed readiness.
       const readiness = await probeReadiness(entry.paneId);
       if (readiness !== 'prompt') {
         return fail(
@@ -343,6 +352,9 @@ export default function terminalPlugin(ctx: Context): void {
       // model hunting for a pane that is fine. Prefer the actionable transport sentence.
       return fail(herdrUnavailableHint(e) ?? `send failed (pane may be closed): ${(e as Error).message}`);
     }
+    // In-memory only (never persisted): the wait echo-hazard check needs the text this pane last
+    // received, because the shell echoes typed commands back into the pane.
+    lastSentText.set(entry.terminalId, v.text);
     touchTerminal(entry);
     return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
   }
@@ -350,6 +362,8 @@ export default function terminalPlugin(ctx: Context): void {
   async function executeTerminalWait(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
     if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    // Waiting on a pane is use: keep it out of the "used this turn" cleanup nudge at settle.
+    touchTerminal(entry);
     const raw = typeof params?.pattern === 'string' ? params.pattern : '';
     if (!raw) return fail('pattern is required (literal text, or a regular expression with regex: true)');
     const useRegex = params?.regex === true;
@@ -360,33 +374,37 @@ export default function terminalPlugin(ctx: Context): void {
         return fail(`invalid regex: ${(e as Error).message}`);
       }
     }
+    // The shell echoes typed commands into the pane, so a pattern contained in the last sent text
+    // matches its own echo and "succeeds" instantly, before the job finishes (observed: a
+    // minutes-long batch matched in 112ms on the echo of its own `echo SENTINEL`).
+    if (sentinelEchoHazard({ pattern: raw, regex: useRegex, lastSentText: lastSentText.get(entry.terminalId) })) {
+      const shown = raw.length > 80 ? `${raw.slice(0, 80)}…` : raw;
+      return fail(
+        `pattern "${shown}" also appears in the command text sent to ${entry.terminalId} — the shell echoes typed commands, `
+        + 'so the wait would match its own echo and return before the job finishes. '
+        + 'That command is still running: do NOT re-send it (text typed behind a running command just queues). '
+        + 'Watch progress with action read, or wait for a marker the running command itself prints that does not occur in the command text. '
+        + 'For future sends, use a sentinel distinguishable from its echo: send `cmd; echo DONE_$?` and wait with regex "^DONE_[0-9]" '
+        + '(the echo contains `DONE_$?`, which that regex cannot match).',
+      );
+    }
     const requested = typeof params?.timeout_ms === 'number' && params.timeout_ms > 0 ? params.timeout_ms : WAIT_DEFAULT_MS;
     const timeoutMs = Math.min(Math.max(requested, 1000), WAIT_MAX_MS);
+    const started = Date.now();
     const matcher = useRegex ? { type: 'regex' as const, value: raw } : { type: 'substring' as const, value: raw };
     let waitResult: { matched: boolean; reason?: 'timeout' | 'unavailable' };
     try {
-      const res = await client.waitForOutput(entry.paneId, matcher, timeoutMs);
-      if (typeof res === 'object' && res !== null && 'matched' in res) {
-        waitResult = res as { matched: boolean; reason?: 'timeout' | 'unavailable' };
-      } else if (res === true) {
-        waitResult = { matched: true };
-      } else if (res === false) {
-        waitResult = { matched: false, reason: 'timeout' };
-      } else {
-        waitResult = { matched: false, reason: 'unavailable' };
-      }
+      waitResult = await client.waitForOutput(entry.paneId, matcher, timeoutMs);
     } catch (e) {
       return fail(herdrUnavailableHint(e) ?? `wait failed (pane may be closed): ${(e as Error).message}`);
     }
     if (!waitResult.matched) {
-      // wait-for-text convention: on timeout, hand back the recent tail so the model can decide
-      // the next move instead of re-polling blind.
+      // wait-for-text convention: on timeout, hand back the recent tail instead of re-polling blind.
       let tail = '';
       try {
         const read = await client.readPane(entry.paneId, { stripAnsi: false });
         tail = stripAnsi(read.text).slice(-WAIT_TAIL_CHARS);
       } catch {
-        /* The pane is gone; the timeout text alone still tells the model it is stuck. */
       }
       const reason = waitResult.reason === 'timeout' ? 'timeout' : 'wait unavailable';
       return {
@@ -394,47 +412,87 @@ export default function terminalPlugin(ctx: Context): void {
         details: { terminal_id: entry.terminalId, matched: false, pattern: raw, reason },
       };
     }
-    return {
-      content: [{ type: 'text', text: `matched in ${entry.terminalId} — output is ready, use action read to inspect it` }],
-      details: { terminal_id: entry.terminalId, matched: true, pattern: raw },
+    // herdr matches the whole pane, including text a prior read already returned, and a second
+    // waitForOutput on that same text returns immediately. After a stale hit, poll the unread
+    // increment until a new occurrence appears or the original budget is gone — do not re-enter
+    // waitForOutput (that busy-loops on the old match).
+    const deadline = started + timeoutMs;
+    const cursor: ReadCursor | null = entry.readRevision != null
+      ? { revision: entry.readRevision, len: entry.readLen ?? 0, tail: entry.readTail ?? '', eoTail: entry.readEoTail ?? '' }
+      : null;
+    const shown = raw.length > 80 ? `${raw.slice(0, 80)}…` : raw;
+    let sawStale = false;
+    const staleFailure = {
+      content: [{ type: 'text' as const, text: `pattern "${shown}" matched only in already-read output of ${entry.terminalId}; no new output contains it. This is not a new event — do not treat the job as finished. Wait for a marker that has not appeared yet, or use action read.` }],
+      details: { terminal_id: entry.terminalId, matched: false, stale: true, pattern: raw },
     };
+    while (true) {
+      let paneText = '';
+      try {
+        const read = await client.readPane(entry.paneId, { stripAnsi: false });
+        paneText = stripAnsi(read.text);
+      } catch {
+        if (sawStale) return staleFailure;
+        return {
+          content: [{ type: 'text', text: `matched in ${entry.terminalId} — output is ready, use action read to inspect it` }],
+          details: { terminal_id: entry.terminalId, matched: true, pattern: raw },
+        };
+      }
+      const classified = classifyWaitMatch(cursor, paneText, raw, useRegex);
+      if (classified.kind === 'fresh') {
+        return {
+          content: [{ type: 'text', text: `matched in ${entry.terminalId} — new output contains the pattern:\n${classified.excerpt}` }],
+          details: { terminal_id: entry.terminalId, matched: true, pattern: raw },
+        };
+      }
+      if (classified.kind !== 'stale') {
+        return {
+          content: [{ type: 'text', text: `matched in ${entry.terminalId} — output is ready, use action read to inspect it` }],
+          details: { terminal_id: entry.terminalId, matched: true, pattern: raw },
+        };
+      }
+      sawStale = true;
+      const left = deadline - Date.now();
+      if (left <= 0) return staleFailure;
+      const { promise, resolve } = Promise.withResolvers<void>();
+      setTimeout(resolve, Math.min(400, left));
+      await promise;
+    }
+  }
+
+  /** T5: a direct `pane_id` read is limited to panes in this session's own tab or to self-created terminal
+   *  panes, so one task can never read another's pane. Returns the error text instead of throwing. */
+  async function resolveDirectPaneId(paneId: string): Promise<{ ok: true; paneId: string } | { ok: false; error: string }> {
+    let panes;
+    try {
+      panes = await client.listPanes();
+    } catch (e) {
+      return { ok: false, error: herdrUnavailableHint(e) ?? `pane lookup failed: ${(e as Error).message}` };
+    }
+    const target = panes.find((p) => p.paneId === paneId);
+    const ownTab = Boolean(target?.tabId) && target?.tabId === env?.tabId;
+    if (!target || !(ownTab || activeTerminalPaneIds(terminals).has(paneId))) {
+      return { ok: false, error: 'pane_id read is limited to panes in this session\'s own tab or self-created terminal panes' };
+    }
+    return { ok: true, paneId };
   }
 
   async function executeTerminalRead(params: ToolParams) {
-    let paneId: string | null = null;
+    let paneId: string;
     let entry: TerminalEntry | null = null;
     if (typeof params?.terminal_id === 'string') {
       entry = findOpenTerminal(params.terminal_id);
       if (!entry) return fail(`unknown or closed terminal "${params.terminal_id}" (see action list)`);
       paneId = entry.paneId;
     } else if (typeof params?.pane_id === 'string') {
-      // T5 limits direct reads to this task tab or owned terminals to prevent cross-task access.
-      // A1: the guard result is carried out of the try block — a thrown tool error must not be eaten
-      // by the lookup catch below (it would be reported as a bogus "pane lookup failed").
-      let allowed = false;
-      let lookupError: unknown = null;
-      try {
-        const panes = await client.listPanes();
-        const target = panes.find((p) => p.paneId === params.pane_id);
-        const ownTab = target?.tabId && target.tabId === env?.tabId;
-        const ownTerminal = activeTerminalPaneIds(terminals).has(params.pane_id);
-        allowed = Boolean(target) && Boolean(ownTab || ownTerminal);
-        if (allowed) paneId = params.pane_id;
-      } catch (e) {
-        lookupError = e;
-      }
-      if (lookupError !== null) {
-        return fail(herdrUnavailableHint(lookupError) ?? `pane lookup failed: ${(lookupError as Error).message}`);
-      }
-      if (!allowed) {
-        return fail('pane_id read is limited to panes in this session\'s own tab or self-created terminal panes');
-      }
+      const resolved = await resolveDirectPaneId(params.pane_id);
+      if (!resolved.ok) return fail(resolved.error);
+      paneId = resolved.paneId;
     } else {
       return fail('provide terminal_id (or pane_id for a direct own-tab read)');
     }
     const maxChars = typeof params?.max_chars === 'number' && params.max_chars > 0
       ? Math.min(params.max_chars, TERM_READ_MAX) : TERM_READ_MAX;
-    if (paneId === null) return fail('no readable pane resolved (pass terminal_id, or pane_id for an own-tab pane)');
     let read: { text: string; revision: number; truncated: boolean };
     try {
       read = await client.readPane(paneId, { stripAnsi: false });
@@ -504,6 +562,7 @@ export default function terminalPlugin(ctx: Context): void {
       }
     }
     terminals = closeTerminal(terminals, entry.terminalId, Date.now()).entries;
+    lastSentText.delete(entry.terminalId);
     persistTerminals();
     return { content: [{ type: 'text', text: `terminal ${entry.terminalId} closed` }], details: { terminal_id: entry.terminalId } };
   }