pi-pier 0.2.6 → 0.3.0

package/src/core/terminal.ts

@@ -10,9 +10,15 @@ import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
 import type { PiSurface } from '../pi-surface.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,
+  TERM_REMINDER_CUSTOM_TYPE,
   TERMINALS_CUSTOM_TYPE,
   activeTerminalPaneIds,
   classifyReadiness,
@@ -21,15 +27,20 @@ import {
   detectFullscreenTUI,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
+  planIdleTerminalReminder,
+  planShellInit,
   promptStrategyFor,
   registerTerminal,
   stripAnsi,
   summarizeSessions,
+  terminalReminderGraceMs,
   validateSendText,
   validateSignal,
   type ReadCursor,
   type TerminalEntry,
 } from '../terminal-core.ts';
+import { swallow } from '../swallow.ts';
+import { pierOption } from '../pier-options.ts';
 
 export interface TerminalStateSlot {
   /** Lets index GC preserve panes that host active terminals. */
@@ -60,7 +71,8 @@ export default function terminalPlugin(ctx: Context): void {
   function persistTerminals(): void {
     try {
       pi.appendEntry?.(TERMINALS_CUSTOM_TYPE, makeTerminalsRegistry(terminals));
-    } catch {
+    } catch (err) {
+      swallow('terminal.persist-registry', err);
       /* Persistence is best-effort because terminal operation must not depend on session logging. */
     }
   }
@@ -95,53 +107,166 @@ export default function terminalPlugin(ctx: Context): void {
     rebuildTerminals(eventCtx);
   });
 
-  const TERM_READ_MAX = Number(process.env.PI_HERDR_TERM_READ_MAX ?? READ_MAX_CHARS) || READ_MAX_CHARS;
-  const errText = (msg: string) => ({ content: [{ type: 'text' as const, text: `Error: ${msg}` }], details: {} });
+  // 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.
+  scoped.on('session_shutdown', async () => {
+    idleReminderTimer && clearTimeout(idleReminderTimer);
+    idleReminderTimer = null;
+    const open = terminals.filter((t) => t.status === 'open');
+    if (open.length === 0) return;
+    await Promise.allSettled(open.map((t) => client.closePane(t.paneId)));
+    const now = Date.now();
+    terminals = terminals.map((t) =>
+      t.status === 'open' ? { ...t, status: 'closed' as const, closedAt: now } : t,
+    );
+    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.
+  const piSend = surface.raw as {
+    sendMessage?: (
+      message: { customType: string; content: string; display?: boolean },
+      opts?: { deliverAs?: string; triggerTurn?: boolean },
+    ) => Promise<void>;
+  };
+  let idleReminders = 0;
+  let idleReminderTimer: NodeJS.Timeout | null = null;
+  scoped.on('agent_start', () => {
+    if (idleReminderTimer !== null) {
+      clearTimeout(idleReminderTimer);
+      idleReminderTimer = null;
+    }
+  });
+  scoped.on('agent_settled', async () => {
+    if (idleReminderTimer !== null) {
+      clearTimeout(idleReminderTimer);
+      idleReminderTimer = null;
+    }
+    const plan = planIdleTerminalReminder({
+      open: terminals.filter((t) => t.status === 'open'),
+      now: Date.now(),
+      reminders: idleReminders,
+    });
+    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 …
+    const now = Date.now();
+    const ids = new Set(plan.ids);
+    terminals = terminals.map((t) => (ids.has(t.terminalId) ? { ...t, 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. */
+        }
+      })();
+    }, terminalReminderGraceMs());
+    idleReminderTimer.unref?.();
+  });
+
+  const TERM_READ_MAX = Number(pierOption('PIER_TERM_READ_MAX') ?? READ_MAX_CHARS) || READ_MAX_CHARS;
+  /** wait action: default and ceiling for the blocking output wait (an LLM call must not hang forever). */
+  const WAIT_DEFAULT_MS = 120_000;
+  const WAIT_MAX_MS = 600_000;
+  /** wait action: recent-tail size handed back on timeout so the model can decide the next move. */
+  const WAIT_TAIL_CHARS = 2_000;
+
+  /** A1: a hard failure must throw (pi sets isError only for throws); non-failures stay results. */
+  const fail = (msg: string): never => toolError(msg);
 
   scoped.registerTool({
     name: 'terminal',
     label: 'Terminal',
     description: [
       'Manage persistent interactive terminals (resident shells in dedicated herdr panes).',
-      'Operations: open (create session), send (type commands), read (capture output), signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close (kill shell), list (show all).',
+      '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.',
     ].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: [
+      'Prefer bash for one-shot commands: it is cheaper and returns output directly. Use terminal only when state must persist (server, REPL, watch loop, interactive prompt) or when you need to wait for output that appears later.',
+      'Open once, then send/read/wait against the same terminal_id; do not open a new terminal per command.',
+      'After send, read to confirm the command actually started. Multi-line text is executed line by line.',
+      'wait is for output you expect (a sentinel, a startup line); it returns the recent tail on timeout so you can decide instead of re-polling.',
+      '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' }),
       cwd: Type.Optional(Type.String({ description: '[open] Working directory for the shell (defaults to session cwd)' })),
-      terminal_id: Type.Optional(Type.String({ description: '[send|read|signal|close] Terminal id returned by open action' })),
+      terminal_id: Type.Optional(Type.String({ description: '[send|wait|read|signal|close] Terminal id returned by open action' })),
       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' })),
+      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)' })),
       max_chars: Type.Optional(Type.Number({ description: '[read] Output cap for this read (default 10000)' })),
       key: Type.Optional(Type.String({ description: '[signal] Control key: ctrl+c | ctrl+d | ctrl+z | esc | enter' })),
     }),
-    async execute(_tc, params, _sig, _upd, ctx) {
+    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 errText(action
-            ? `unknown action "${action}" (valid: open, send, read, signal, close, list)`
-            : 'action is required (open, send, read, signal, close, list)');
+          return fail(action
+            ? `unknown action "${action}" (valid: open, send, wait, read, signal, close, list)`
+            : 'action is required (open, send, wait, read, signal, close, list)');
       }
     },
   });
 
-  async function executeTerminalOpen(params, ctx) {
-    if (!client.available || !env) return errText('terminal tools require a herdr-managed pane');
+  /** Probe whether the shell sits at its interactive prompt (advisory: probe failures degrade to 'busy'). */
+  async function probeReadiness(paneId: string): Promise<'prompt' | 'silent' | 'busy'> {
+    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';
+      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';
+    }
+  }
+
+  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
       : (ctx as { cwd?: string }).cwd ?? process.cwd();
     const r = registerTerminal(terminals, {
@@ -150,27 +275,28 @@ export default function terminalPlugin(ctx: Context): void {
       cwd,
       createdAt: Date.now(),
     });
-    if (!r.ok) return errText(r.error);
+    if (!r.ok) return fail(r.error);
     let paneId: string;
     try {
       paneId = await client.splitPane({ direction: 'right', cwd, focus: false, targetPaneId: env.paneId });
     } catch (e) {
-      return errText(`failed to split terminal pane: ${(e as Error).message}`);
+      const hint = herdrUnavailableHint(e);
+      return fail(hint ?? `failed to split terminal pane: ${(e as Error).message}`);
     }
     r.entry.paneId = paneId;
     terminals = r.entries;
     persistTerminals();
+    const readiness = await probeReadiness(paneId);
     const prompt = promptStrategyFor();
-    let readiness: 'prompt' | 'silent' | 'busy' = 'busy';
-    try {
-      const matched = await client.waitForOutput(paneId, { type: 'regex', value: prompt.waitPattern }, READINESS_TIMEOUT_MS);
-      if (matched) readiness = 'prompt';
-      else {
-        const read = await client.readPane(paneId, { stripAnsi: false });
-        readiness = classifyReadiness(stripAnsi(read.text), { silentMs: 0, prompt });
+    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 */
       }
-    } catch {
-      /* Readiness is advisory, so probe failures still leave a usable terminal. */
     }
     const text = [
       `terminal ${r.entry.terminalId} open (pane ${paneId})`,
@@ -180,51 +306,140 @@ export default function terminalPlugin(ctx: Context): void {
     return { content: [{ type: 'text', text }], details: { terminal_id: r.entry.terminalId, pane_id: paneId, readiness } };
   }
 
-  async function executeTerminalSend(params) {
+  async function executeTerminalSend(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
-    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const v = validateSendText(typeof params?.text === 'string' ? params.text : '');
-    if (!v.ok) return errText(v.error);
+    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 */
+        }
+      }
+      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.
+      const readiness = await probeReadiness(entry.paneId);
+      if (readiness !== 'prompt') {
+        return fail(
+          `shell is ${readiness === 'busy' ? 'busy (a previous command may still be running)' : 'silent (no prompt detected)'} — text was NOT sent. `
+            + 'Use action read to inspect the pane, or omit wait_prompt to send anyway.',
+        );
+      }
+    }
     try {
       await client.sendPaneText(entry.paneId, v.text);
     } catch (e) {
-      return errText(`send failed (pane may be closed): ${(e as Error).message}`);
+      // B5: a dead herdr socket would otherwise read as "pane may be closed", which sends the
+      // 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}`);
     }
     touchTerminal(entry);
     return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)` }], details: { terminal_id: entry.terminalId } };
   }
 
-  async function executeTerminalRead(params) {
+  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)`);
+    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;
+    if (useRegex) {
+      try {
+        new RegExp(raw);
+      } catch (e) {
+        return fail(`invalid regex: ${(e as Error).message}`);
+      }
+    }
+    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 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' };
+      }
+    } 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.
+      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 {
+        content: [{ type: 'text', text: `no match within ${timeoutMs}ms (${reason}).${tail ? `\nrecent output tail:\n${tail}` : ''}` }],
+        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 },
+    };
+  }
+
+  async function executeTerminalRead(params: ToolParams) {
     let paneId: string | null = null;
     let entry: TerminalEntry | null = null;
     if (typeof params?.terminal_id === 'string') {
       entry = findOpenTerminal(params.terminal_id);
-      if (!entry) return errText(`unknown or closed terminal "${params.terminal_id}" (see action list)`);
+      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);
-        if (!target || (!ownTab && !ownTerminal)) {
-          return errText('pane_id read is limited to panes in this session\'s own tab or self-created terminal panes');
-        }
-        paneId = params.pane_id;
+        allowed = Boolean(target) && Boolean(ownTab || ownTerminal);
+        if (allowed) paneId = params.pane_id;
       } catch (e) {
-        return errText(`pane lookup failed: ${(e as Error).message}`);
+        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');
       }
     } else {
-      return errText('provide terminal_id (or pane_id for a direct own-tab read)');
+      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 });
     } catch (e) {
-      return errText(`read failed (pane may be closed): ${(e as Error).message}`);
+      return fail(herdrUnavailableHint(e) ?? `read failed (pane may be closed): ${(e as Error).message}`);
     }
     // T6 inspects raw output because ANSI stripping would erase alternate-screen evidence.
     const tui = detectFullscreenTUI(read.text);
@@ -241,7 +456,7 @@ export default function terminalPlugin(ctx: Context): void {
     }
     const prev: ReadCursor | null = entry
       ? (entry.readRevision != null
-        ? { revision: entry.readRevision, len: entry.readLen, tail: entry.readTail, eoTail: entry.readEoTail }
+        ? { revision: entry.readRevision, len: entry.readLen ?? 0, tail: entry.readTail ?? '', eoTail: entry.readEoTail ?? '' }
         : null)
       : null;
     const inc = computeIncrement(prev, { text: read.text, revision: read.revision }, maxChars);
@@ -263,24 +478,24 @@ export default function terminalPlugin(ctx: Context): void {
     };
   }
 
-  async function executeTerminalSignal(params) {
+  async function executeTerminalSignal(params: ToolParams) {
     const entry = findOpenTerminal(params?.terminal_id);
-    if (!entry) return errText(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
+    if (!entry) return fail(`unknown or closed terminal "${String(params?.terminal_id)}" (see action list)`);
     const v = validateSignal(typeof params?.key === 'string' ? params.key : '');
-    if (!v.ok) return errText(v.error);
+    if (!v.ok) return fail(v.error);
     try {
       await client.sendPaneKeys(entry.paneId, [v.key]);
     } catch (e) {
-      return errText(`signal failed (pane may be closed): ${(e as Error).message}`);
+      return fail(herdrUnavailableHint(e) ?? `signal failed (pane may be closed): ${(e as Error).message}`);
     }
     touchTerminal(entry);
     return { content: [{ type: 'text', text: `signal ${v.key} sent to ${entry.terminalId}` }], details: { terminal_id: entry.terminalId, key: v.key } };
   }
 
-  async function executeTerminalClose(params) {
+  async function executeTerminalClose(params: ToolParams) {
     const id = params?.terminal_id;
     const entry = terminals.find((t) => t.terminalId === id);
-    if (!entry) return errText(`unknown terminal "${String(id)}" (see action list)`);
+    if (!entry) return fail(`unknown terminal "${String(id)}" (see action list)`);
     if (entry.status === 'open') {
       try {
         await client.closePane(entry.paneId);
@@ -294,12 +509,18 @@ export default function terminalPlugin(ctx: Context): void {
   }
 
   async function executeTerminalList() {
-    let livePaneIds: string[] = [];
+    let livePanes: import('../herdr-client.ts').PaneListItem[] = [];
     try {
-      livePaneIds = (await client.listPanes()).map((p) => p.paneId);
+      livePanes = await client.listPanes();
     } catch {
       /* Treat a failed query as unknown rather than closed, because an empty live set only affects stale detection. */
     }
+    const livePaneIds = livePanes.map((p) => p.paneId);
+    const titleByPaneId = new Map<string, string>();
+    for (const p of livePanes) {
+      const cleanTitle = p.terminalTitleStripped ?? p.terminalTitle;
+      if (cleanTitle) titleByPaneId.set(p.paneId, cleanTitle);
+    }
     const s = summarizeSessions(terminals, livePaneIds);
     // T6 check 3: record vanished panes as closed across restarts rather than reviving them; tell the user to persist state.
     if (s.stalePaneIds.length > 0) {
@@ -313,9 +534,11 @@ export default function terminalPlugin(ctx: Context): void {
     if (s.terminals.length === 0) {
       return { content: [{ type: 'text', text: 'no terminals (open one with action open)' }], details: { terminals: [] } };
     }
-    const lines = s.terminals.map((t) =>
-      `- ${t.terminalId} [${t.live ? 'open' : 'closed'}] pane=${t.paneId} cwd=${t.cwd}${t.label ? ` (${t.label})` : ''}`,
-    );
+    const lines = s.terminals.map((t) => {
+      const cleanTitle = titleByPaneId.get(t.paneId);
+      const titleTag = cleanTitle && cleanTitle !== t.label ? ` title="${cleanTitle}"` : '';
+      return `- ${t.terminalId} [${t.live ? 'open' : 'closed'}] pane=${t.paneId} cwd=${t.cwd}${t.label ? ` (${t.label})` : ''}${titleTag}`;
+    });
     const note = s.stalePaneIds.length > 0
       ? '\nnote: terminal sessions do not survive pane closure/restart — persist results to files.'
       : '';