pi-pier 0.4.1 → 0.4.2

package/src/plugins/subagent.ts

@@ -84,24 +84,35 @@ export interface SubagentDeps {
   logRouting?: (row: RoutingTelemetryRecord) => void;
 }
 
+/** Sent with every request: what a call needs. Details live in SUBAGENT_MANUAL (`action: "help"`). */
 const SUBAGENT_DESCRIPTION = [
-  'Delegate a self-contained subtask to an isolated subagent that runs in its own herdr pane as an interactive pi session (separate context window; it does NOT see this conversation). A human can also open that pane and talk to the subagent directly.',
-  '`action` (optional, default "spawn"): spawn | resume | list | send | interrupt | output | role.',
-  '[spawn] `description`: short display label for the pane; `prompt`: the COMPLETE task — include all needed context, since only the prompt reaches the subagent. The description also doubles as the todo-reconcile key: when delegating a todo entry, use the entry content WITHOUT its ` <sub>` marker as the description, and the entry is auto-completed when this subagent settles.',
-  '[spawn] The subagent shares this workspace and works independently; the result is its final text answer.',
-  '[spawn] Concurrent delegation is supported: several spawn calls in one message run in parallel (at most 4 at once). Use this for well-scoped, independent subtasks; do not delegate the current step itself.',
-  '[spawn] `run_in_background` (default false): when true, the call returns immediately with an agentId; the subagent keeps running in its pane. Use action list to see its state, action send to give it follow-up work, action interrupt to stop it. When it settles, you receive a notification message with its closing output.',
-  '[spawn] `tab` (optional): name of a task tab to place the subagent into (join if a tab with this name exists, otherwise create it). Overrides the default placement. Default placement groups by git worktree: a subagent working in your checkout shares your tab; one working in a separate worktree (pass its path via `cwd`; create worktrees with `git worktree add`) gets its own tab named after the worktree directory.',
-  '[spawn] `role` + `allowed_tools`: when role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes the composed manifest — baseline ∪ allowed_tools minus role-deny tools (deny always wins). Custom roles: drop a JSON profile into .pi-herdr/roles/ (master/worker-default reserved). Unknown role names remain display labels only.',
-  '[spawn] `isolate` (default false): creates a FRESH git worktree for this subagent and runs it there (branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/). Three-way choice: heavy independent writing in parallel with your own edits or other workers, or work needing its own clean reviewable diff → isolate; read-mostly or sequential helper work → omit (shared checkout, writes guarded by the write-lock); targeting an existing directory/worktree → cwd. In isolate mode the subagent\'s writes cannot conflict with your checkout; its panes group into a tab named after the worktree; its prompt is prefixed with commit discipline (commit to its own branch, NEVER push); when it settles you get a diff summary (commits since base, files changed, uncommitted count). Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd.',
-  '[resume] `taskId`: revive a finished (collected) subagent from the delegation ledger — opens its saved conversation in a new pane (pi --session), then use action send to give it new work. The ledger is an append-only JSONL file, one row per status change (same taskId rows = generations, latest row is current): fields taskId, description, status (running|settled|consumed|closed), outcome (closing text), paneId, sessionFile, launchCommand, createdAt. Ledgers are per-checkout at ~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl, but resume searches every checkout this master has spawned into, not only the current cwd. A still-running task is not resumed — use action send or output. Use action list for live panes.',
-  '[list] no extra parameters: list background subagents with live state (running / idle), pane ids, last activity, role, and descriptions. Foreground one-shot panes are not listed.',
-  '[output] `agentId` (required, the subagent pane id): view incremental output of a running or background subagent since the last output call. Text returned to the model is bounded (default 6000 chars) with status metadata (running/idle/blocked/settled), revision, and a truncated flag. When the delta cannot be computed the full text is returned with a "buffer scrolled or reset" note — that is normal for fullscreen TUI panes, not a crash indicator. Use this to observe subagent progress before settlement.',
-  '[interrupt] `agentId`: abort the current turn (fire-and-return). The pane stays; you can send again.',
-  '[role] `agentId` + `role`: switch that worker\'s role profile mid-session (pi 0.86 transcript tool delta — the new toolset applies on its next request and survives resume). Same role resolution as spawn; the reply reports the tool diff. Use when a task outgrew its delegation (needs more tools) or should be narrowed.',
-  '[send] `agentId` + `message`: follow-up to a background subagent. If working, delivered at next tool-call gap (steer, seconds); if idle, wakes a new turn. After settle, send to wake it; do not spawn a duplicate.',
+  'Delegate a self-contained task to a subagent: an isolated pi session in its own herdr pane (separate context — it does NOT see this conversation; a human can talk to it in that pane).',
+  'Actions (default spawn): spawn | send | output | list | interrupt | resume | role | help.',
+  'spawn: `prompt` is the COMPLETE task, since only the prompt reaches it; `description` labels the pane and is the todo-reconcile key — when delegating a todo entry, pass its content without the ` <sub>` marker and the entry auto-completes on settle. Several spawns in one message run in parallel (max 4).',
+  'A foreground spawn BLOCKS this call for up to ~5 minutes; pass run_in_background: true for long tasks. A background (or timed-out foreground) worker\'s settlement notice arrives automatically at your next tool boundary — no need to sleep or poll.',
+  'send: follow-up to a running or settled worker (steered between its tool calls). output: what it printed since your last check, plus its final report once done. resume: revive a collected task by taskId. role: switch a worker\'s role profile mid-session.',
+  'help: the full manual (isolate/cwd/tab placement, role profiles, the delegation ledger).',
 ].join(' ');
 
+/** Returned by `action: "help"`: the reference text that used to ride every request. */
+const SUBAGENT_MANUAL = [
+  'subagent manual',
+  '',
+  'spawn — the subagent shares this workspace and works independently; its result is its final text answer. Do not delegate the current step itself. Placement: by default panes group by git worktree — a subagent in your checkout shares your tab, one in a separate worktree gets its own tab named after the worktree directory. `tab` joins or creates a named task tab instead. `cwd` targets an existing directory or worktree (create worktrees with git worktree add).',
+  '',
+  'isolate (default false) — creates a FRESH git worktree (branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/). Choose it for heavy independent writing in parallel with your own edits or other workers, or work needing its own clean reviewable diff; omit it for read-mostly or sequential helper work (shared checkout, writes guarded by the write-lock); use cwd for an existing directory/worktree. Its writes cannot conflict with your checkout, its prompt is prefixed with commit discipline (commit to its own branch, never push), and on settle you get a diff summary (commits since base, files changed, uncommitted count). Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd.',
+  '',
+  'role + allowed_tools — when role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes baseline ∪ allowed_tools minus role-deny tools (deny always wins). Custom roles: drop a JSON profile into .pi-herdr/roles/ (master/worker-default reserved). Unknown role names stay display labels. action role switches a live worker (pi transcript tool delta: applies on its next request, survives resume); the reply reports the tool diff.',
+  '',
+  'list — background subagents with live state (running / idle), pane ids, last activity, role and description; foreground one-shot panes are not listed.',
+  '',
+  'output — `agentId` required; returns the delta since your last output call (default 6000 chars, max_chars 100-16000) with status (running/idle/blocked/settled), revision and a truncated flag. TUI chrome is stripped; once the worker has finished, the complete transcript report is attached. A "buffer scrolled or reset" note means the full text was returned — normal for fullscreen TUI panes.',
+  '',
+  'send — `agentId` + `message`: if working, delivered at its next tool-call gap (seconds); if idle or settled, wakes a new turn. Do not spawn a duplicate for the same task. interrupt — aborts its current turn; the pane stays and you can send again.',
+  '',
+  'resume — `taskId`: revives a collected subagent from the delegation ledger in a new pane (pi --session); then use send. The ledger is append-only JSONL, one row per status change (taskId, description, status running|settled|consumed|closed, outcome, paneId, sessionFile, launchCommand, createdAt), per checkout at ~/.pi/agent/herdr-pi/history/<flattened-cwd>/history.jsonl; resume searches every checkout this master spawned into. A still-running task is not resumed — use send or output.',
+].join('\n');
+
 const SUBAGENT_CONCURRENCY = 4;
 
 function defaultAgentSessionsDir(): string {
@@ -224,8 +235,8 @@ export default function subagentPlugin(ctx: Context): void {
     if (port.current === boundPort) port.current = null;
   }, 'subagent-port');
 
-  const injectNotice = (content: string): Promise<void> => {
-    if (d.deliverNotice) return d.deliverNotice(content);
+  const injectNotice = (content: string, paneId?: string): Promise<void> => {
+    if (d.deliverNotice) return d.deliverNotice(content, paneId);
     pi.sendUserMessage?.(content, { deliverAs: 'followUp' });
     return Promise.resolve();
   };
@@ -353,7 +364,7 @@ export default function subagentPlugin(ctx: Context): void {
         [DELEGATION_ENV]: JSON.stringify({
           parentPaneId: env?.paneId ?? '',
           parentSessionId: bareSessionId(d.getSessionId()),
-          // Phase 2: report_progress needs the master's pipe; kind 'task' maps to the composed default.
+          // todo_sync needs the master's pipe; kind 'task' maps to the composed default.
           parentPipe: pipeNameFor(process.cwd(), env?.paneId ?? ''),
           taskId: entry.taskId,
           description: entry.description,
@@ -638,7 +649,9 @@ export default function subagentPlugin(ctx: Context): void {
     const lines: string[] = [];
     for (const sub of byTask.values()) {
       const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
-      const wtTag = sub.isolate ? ` [wt: ${sub.isolate.branch}]` : '';
+      // The branch (`pier/<slug>`) is not a directory; printing it made masters cd into
+      // `<repo>/pier/<slug>`. Always print the absolute worktree path they can actually enter.
+      const wtTag = sub.isolate ? ` [wt: ${sub.isolate.worktreePath}]` : '';
       if (sub.status === 'closed') {
         lines.push(`${sub.taskId.slice(0, 8)} [idle] (${sub.kind}, closed; action send revives)${tabTag}${wtTag} ${sub.description}`);
         continue;
@@ -692,6 +705,7 @@ export default function subagentPlugin(ctx: Context): void {
     // carry the final report. No preferred file — start from herdr's per-pane report, not a stale registry value.
     readFinalReport: async (paneId: string, entryCwd: string) =>
       (await session.subSessionState(paneId, entryCwd, 0)).text,
+    persistSubs,
   };
 
   const ACTIONS: Record<string, (params: ToolParams, toolCtx: unknown, onUpdate?: (u: unknown) => void) => Promise<unknown>> = {
@@ -702,6 +716,7 @@ export default function subagentPlugin(ctx: Context): void {
     interrupt: (params, toolCtx) => executeSubagentInterrupt(params, toolCtx),
     output: (params, toolCtx) => executeSubagentOutput(params, toolCtx, outputActionDeps),
     role: (params, toolCtx) => executeSubagentRole(params, toolCtx),
+    help: async () => ({ content: [{ type: 'text', text: SUBAGENT_MANUAL }], details: {} }),
   };
 
   scoped.registerTool({
@@ -709,15 +724,12 @@ export default function subagentPlugin(ctx: Context): void {
     label: 'Subagent',
     // B4: the model picks tools from the system prompt's snippet/guideline surface; delegation
     // decisions are made here, so state them rather than hoping for recall.
-    promptSnippet: 'subagent: delegate a self-contained task to a pi worker pane (spawn/isolate/background/send/output/interrupt/resume/list/role).',
+    promptSnippet: 'subagent: delegate a self-contained task to a pi worker pane (spawn/isolate/background/send/output/interrupt/resume/list/role/help).',
     promptGuidelines: [
-      'Use subagent when the work is self-contained and the result is what matters: pipelines that would flood this context, long builds/test runs, or independent parts of a bigger change that can proceed in parallel.',
-      'Prefer run_in_background: true for work that will not finish in a few tool calls, then collect with action: "output" — a foreground subagent blocks this turn.',
-      'Use isolate: true when the worker will write files for a task you (or another worker) are editing at the same time, or when you want its own reviewable branch; use cwd to send work into an existing worktree (create it with git worktree add first).',
-      'Keep the prompt complete and self-contained: the worker does not see this conversation, so include paths, acceptance criteria, the test command, and what to report back.',
-      'Do not poll with action: "output" in a tight loop: the pane pushes a settlement notice when it finishes. Check once, then continue other work.',
-      'Send follow-up instructions with action: "send" (delivered as a steer between tool calls) instead of spawning a second worker for the same task.',
-      'Pass agentId, taskId, message, and max_chars as top-level arguments. Do not wrap them in a parameters object.',
+      'Use subagent for self-contained work whose result is what matters: output that would flood this context, long builds/test runs, or independent parts of a bigger change that can run in parallel.',
+      'The worker does not see this conversation: put paths, acceptance criteria, the test command and what to report back into the prompt.',
+      'Use isolate: true when the worker writes files you or another worker edit at the same time, or when its work needs its own reviewable branch.',
+      'Pass agentId, taskId, message and max_chars as top-level arguments, not inside a parameters object.',
     ],
     description: SUBAGENT_DESCRIPTION,
     parameters: Type.Object({
@@ -729,19 +741,20 @@ export default function subagentPlugin(ctx: Context): void {
         Type.Literal('interrupt'),
         Type.Literal('output'),
         Type.Literal('role'),
-      ], { description: 'Operation to perform (default: spawn)' })),
-      description: Type.Optional(Type.String({ description: '[spawn] Short label for this subtask (pane title)' })),
-      prompt: Type.Optional(Type.String({ description: '[spawn] The complete self-contained task for the subagent' })),
-      run_in_background: Type.Optional(Type.Boolean({ description: '[spawn] Return immediately with an agentId; the subagent keeps running in its own pane (default false)' })),
-      cwd: Type.Optional(Type.String({ description: '[spawn] Working directory for the subagent (absolute, or relative to this workspace). Use it to delegate into a git worktree: panes group by worktree — same checkout as you share your tab; a separate worktree gets its own tab named after the worktree directory. Create worktrees yourself with git worktree add. Use isolate:true instead when you want a FRESH worktree created for this task rather than targeting an existing one' })),
-      isolate: Type.Optional(Type.Boolean({ description: '[spawn] Create a fresh git worktree and run the subagent there. Use when the task writes files heavily and independently — in parallel with your own edits or other workers\' — or needs its own clean, reviewable diff. For read-mostly or sequential helper work omit it (shared checkout, writes guarded by the write-lock); use `cwd` only to target an existing directory/worktree (e.g. a retained pier worktree). Mechanics: branch pier/<slug> from your HEAD under ~/.herdr/worktrees/<repo>/; its writes cannot conflict with your checkout; panes group into a tab named after the worktree; the prompt is prefixed with commit discipline (commit to its branch, never push); on settle you get a diff summary. Review with git log/diff HEAD..<branch>, merge with git merge --no-ff <branch>; once merged and clean the worktree auto-removes (branch kept). Mutually exclusive with cwd' })),
-      role: Type.Optional(Type.String({ description: '[spawn|role] Role label or profile name. [spawn] When role matches a profile (searched: workspace .pi-herdr/roles/ → user-global ~/.pi/agent/herdr-pi/roles/ → builtin), the worker toolset becomes the composed manifest. Unknown role names remain display labels only. [role] Target profile for the mid-session switch' })),
-      tab: Type.Optional(Type.String({ description: '[spawn] Name of a task tab to place the subagent into (join if exists, otherwise create). Default placement groups by git worktree.' })),
-      allowed_tools: Type.Optional(Type.Array(Type.String(), { description: '[spawn] Additional tools for role composition (union with role baseline)' })),
-      taskId: Type.Optional(Type.String({ description: '[resume] The task id to revive from the delegation ledger' })),
-      agentId: Type.Optional(Type.String({ description: '[send|interrupt|output|role] The subagent reference: task slug (e.g. "fix-auth"), herdr pane id, or "slug@paneId" as printed by spawn/list' })),
-      message: Type.Optional(Type.String({ description: '[send] The follow-up message' })),
-      max_chars: Type.Optional(Type.Integer({ description: '[output] Maximum characters of output delta to return (default 6000, 100-16000)' })),
+        Type.Literal('help'),
+      ], { description: 'Default spawn' })),
+      description: Type.Optional(Type.String({ description: '[spawn] Pane label; also the todo-reconcile key' })),
+      prompt: Type.Optional(Type.String({ description: '[spawn] The complete self-contained task' })),
+      run_in_background: Type.Optional(Type.Boolean({ description: '[spawn] Return at once; the settlement notice arrives later (default false)' })),
+      cwd: Type.Optional(Type.String({ description: '[spawn] Existing directory or worktree to run in (absolute or workspace-relative); exclusive with isolate' })),
+      isolate: Type.Optional(Type.Boolean({ description: '[spawn] Run in a fresh git worktree (branch pier/<slug>) for heavy parallel writes or a reviewable diff; settle reports a diff summary (see help)' })),
+      role: Type.Optional(Type.String({ description: '[spawn|role] Role profile name; unknown names are display labels only' })),
+      tab: Type.Optional(Type.String({ description: '[spawn] Task tab to join or create (default: grouped by worktree)' })),
+      allowed_tools: Type.Optional(Type.Array(Type.String(), { description: '[spawn] Extra tools on top of the role baseline' })),
+      taskId: Type.Optional(Type.String({ description: '[resume] Task id from the delegation ledger' })),
+      agentId: Type.Optional(Type.String({ description: '[send|interrupt|output|role] Slug, pane id, or slug@paneId as printed by spawn/list' })),
+      message: Type.Optional(Type.String({ description: '[send] Follow-up message' })),
+      max_chars: Type.Optional(Type.Integer({ description: '[output] Output cap (default 6000, 100-16000)' })),
     }),
     outputSchema: SUBAGENT_OUTPUT_SCHEMA,
     // B2: `action` is optional in the schema; normalize it so the validated arguments and the

package/src/plugins/terminal.ts

@@ -4,6 +4,9 @@
  * pi surface, the herdr client/environment and the state slot used by index GC; terminal-core holds the
  * pure, independently testable logic.
  */
+import { open } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve as resolvePath } from 'node:path';
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
 import { cordisGet } from '../cordis-services.ts';
@@ -18,14 +21,20 @@ import {
   activeTerminalPaneIds,
   classifyReadiness,
   closeTerminal,
+  compilePattern,
   computeIncrement,
   classifyWaitMatch,
+  detectContinuationPrompt,
   detectFullscreenTUI,
+  echoSafeWaitSuggestion,
+  excerptAroundMatch,
   foldTerminalsRegistry,
   makeTerminalsRegistry,
   planTerminalReminder,
   planShellInit,
   promptStrategyFor,
+  regexLiteralPrefix,
+  redirectedSentinel,
   registerTerminal,
   sentinelEchoHazard,
   stripAnsi,
@@ -45,7 +54,31 @@ 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>;
+type ActionHandler = (params: ToolParams, ctx: unknown, signal?: AbortSignal) => Promise<unknown>;
+
+/** File waits poll the log in-process; one tick per second keeps a 10-minute wait to ~600 reads. */
+const FILE_WAIT_POLL_MS = 1000;
+/** Only the log's tail is matched: a sentinel is the newest line, and a multi-GB log must not be read whole. */
+const FILE_WAIT_TAIL_BYTES = 1024 * 1024;
+
+/** The last `maxBytes` of a file as UTF-8, or null when it does not exist (yet). */
+async function readFileTail(path: string, maxBytes: number): Promise<string | null> {
+  let handle;
+  try {
+    handle = await open(path, 'r');
+  } catch {
+    return null;
+  }
+  try {
+    const { size } = await handle.stat();
+    const length = Math.min(size, maxBytes);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, size - length);
+    return buffer.toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
 
 export interface TerminalStateSlot {
   /** Lets index GC preserve panes that host active terminals. */
@@ -172,19 +205,20 @@ export default function terminalPlugin(ctx: Context): void {
     });
     turnStartedAt = null;
     if (!plan.due || plan.content == null) return;
-    // 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, nudges: (t.nudges ?? (t.nudgedAt != null ? 1 : 0)) + 1, nudgedAt: now }
-      : t));
-    persistTerminals();
+    // Deliver the notice as a queued followUp WITHOUT triggerTurn — a reminder must never wake the
+    // agent. The per-terminal count is bumped only when the timer fires: agent_start cancels the
+    // grace timer, and a cancelled reminder must not consume one of the two allowed nudges.
     const content = plan.content;
     idleReminderTimer = setTimeout(() => {
       idleReminderTimer = null;
       const send = piSend.sendMessage;
       if (typeof send !== 'function') return;
+      const now = Date.now();
+      const ids = new Set(plan.ids);
+      terminals = terminals.map((t) => (ids.has(t.terminalId) && t.status === 'open'
+        ? { ...t, nudges: (t.nudges ?? (t.nudgedAt != null ? 1 : 0)) + 1, nudgedAt: now }
+        : t));
+      persistTerminals();
       try {
         // Fire-and-forget in pi (void); a synchronous throw is still swallowed here.
         send(
@@ -222,31 +256,29 @@ export default function terminalPlugin(ctx: Context): void {
     name: 'terminal',
     label: 'Terminal',
     description: [
-      '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.',
-      '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.',
+      'Persistent interactive shells in dedicated herdr panes; cwd, environment and background processes survive across calls.',
+      'Actions: open, send (type a command), wait (block until output matches), read, signal (ctrl+c/ctrl+d/ctrl+z/esc/enter), close, list.',
+      'Long job: send "cmd; echo TERM_DONE_$?" and wait with regex "^TERM_DONE_[0-9]" — the shell echoes typed commands, so a literal "TERM_DONE_" would match its own echo. When output and sentinel go to a log ("cmd > run.log 2>&1; echo DONE_$? >> run.log"), wait with file: "run.log" instead of sleeping in bash.',
     ].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.',
+      'Prefer bash for one-shot commands. Use terminal only when state must persist (server, REPL, watch loop, interactive prompt) or output appears later; open once and reuse the terminal_id.',
+      'wait returns the recent tail on timeout, so decide from it instead of re-polling.',
+      'Close the terminal when the work is done — it occupies a pane and is never auto-reclaimed.',
     ],
     parameters: Type.Object({
-      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: '[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 (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)' })),
-      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' })),
+      action: Type.Union(TERMINAL_ACTIONS.map((name) => Type.Literal(name))),
+      cwd: Type.Optional(Type.String({ description: '[open] Shell working directory (default: session cwd)' })),
+      terminal_id: Type.Optional(Type.String({ description: '[open] Optional id for the new terminal (default term-N); [others] id returned by open' })),
+      text: Type.Optional(Type.String({ description: '[send] Command text (Enter appended; multi-line runs line by line)' })),
+      wait_prompt: Type.Optional(Type.Boolean({ description: '[send] Refuse instead of queueing when the shell is not at a prompt' })),
+      pattern: Type.Optional(Type.String({ description: '[wait] Literal text or regex to wait for (must not occur in the sent command text)' })),
+      file: Type.Optional(Type.String({ description: '[wait] Watch this log file instead of the pane (relative to the terminal cwd; may not exist yet)' })),
+      regex: Type.Optional(Type.Boolean({ description: '[wait] pattern is a regex (default literal)' })),
+      timeout_ms: Type.Optional(Type.Number({ description: '[wait] Default 120000, max 600000' })),
+      pane_id: Type.Optional(Type.String({ description: '[read] Read another pane in your own tab' })),
+      max_chars: Type.Optional(Type.Number({ description: `[read] Output cap (default ${READ_MAX_CHARS})` })),
+      key: Type.Optional(Type.String({ description: '[signal] ctrl+c | ctrl+d | ctrl+z | esc | enter' })),
     }),
     async execute(_tc: string, params: ToolParams, _sig: AbortSignal | undefined, _upd: unknown, ctx: unknown) {
       const action = typeof params?.action === 'string' ? params.action : '';
@@ -257,7 +289,7 @@ export default function terminalPlugin(ctx: Context): void {
           ? `unknown action "${action}" (valid: ${valid})`
           : `action is required (${valid})`);
       }
-      return handler(params, ctx);
+      return handler(params, ctx, _sig);
     },
   });
 
@@ -274,8 +306,9 @@ export default function terminalPlugin(ctx: Context): void {
     }
   }
 
-  /** 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. */
+  /** Best-effort history-expansion init right after a shell becomes usable (zsh needs
+   *  `setopt NO_BANG_HIST`, bash `set +H`); 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;
@@ -301,12 +334,28 @@ export default function terminalPlugin(ctx: Context): void {
       createdAt: Date.now(),
     });
     if (!r.ok) return fail(r.error);
+    // Stack new terminals below the most recent one instead of halving the pi master pane again:
+    // every right-split of the master shrinks both (45 → 22 → 11 columns), which breaks output
+    // wrapping and multi-word waits. The first terminal still splits the master to the right.
+    const anchor = [...terminals].reverse().find((t) => t.status === 'open') ?? null;
+    const targetPaneId = anchor?.paneId ?? env.paneId;
+    const direction = anchor ? 'down' : 'right';
     let paneId: string;
     try {
-      paneId = await client.splitPane({ direction: 'right', cwd, focus: false, targetPaneId: env.paneId });
+      paneId = await client.splitPane({ direction, cwd, focus: false, targetPaneId });
     } catch (e) {
-      const hint = herdrUnavailableHint(e);
-      return fail(hint ?? `failed to split terminal pane: ${(e as Error).message}`);
+      if (!anchor) {
+        const hint = herdrUnavailableHint(e);
+        return fail(hint ?? `failed to split terminal pane: ${(e as Error).message}`);
+      }
+      // A terminal restored from an earlier session can point at a pane herdr no longer has: fall
+      // back to the master instead of failing to open at all.
+      try {
+        paneId = await client.splitPane({ direction: 'right', cwd, focus: false, targetPaneId: env.paneId });
+      } catch (fallbackError) {
+        const hint = herdrUnavailableHint(fallbackError);
+        return fail(hint ?? `failed to split terminal pane: ${(fallbackError as Error).message}`);
+      }
     }
     r.entry.paneId = paneId;
     terminals = r.entries;
@@ -330,9 +379,10 @@ 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) {
-      await injectShellInit(entry);
-      entry.initialized = true;
-      persistTerminals();
+      if (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
@@ -356,10 +406,31 @@ export default function terminalPlugin(ctx: Context): void {
     // 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 } };
+    // An incomplete command leaves the shell at a secondary prompt (`dquote>`, `heredoc>`, …):
+    // every later send is swallowed by it, so surface the wedge instead of reporting success.
+    let pending: string | null = null;
+    try {
+      const snapshot = await client.readPane(entry.paneId, { stripAnsi: false });
+      pending = detectContinuationPrompt(stripAnsi(snapshot.text));
+    } catch {
+      /* A pane read is advisory here: a transport failure must not turn a successful send into an error. */
+    }
+    if (pending) {
+      return fail(
+        `shell is waiting for more input (${pending}) — the sent command left an incomplete quote, heredoc, or block, `
+          + 'and later text is swallowed by that continuation prompt. Send the missing terminator, or interrupt with '
+          + 'terminal(action: "signal", key: "ctrl+c"), then re-send a complete command.',
+      );
+    }
+    const hint = redirectedSentinel(v.text);
+    const fileHint = hint
+      ? `\nnote: the sentinel ${hint.prefix}$? is written to ${hint.file}, not the pane — wait for it with `
+        + `terminal(action: "wait", terminal_id: "${entry.terminalId}", file: "${hint.file}", pattern: "${echoSafeWaitSuggestion(hint.prefix) ?? hint.prefix}", regex: true) instead of sleeping.`
+      : '';
+    return { content: [{ type: 'text', text: `sent to ${entry.terminalId} (${v.text.length} chars)${fileHint}` }], details: { terminal_id: entry.terminalId } };
   }
 
-  async function executeTerminalWait(params: ToolParams) {
+  async function executeTerminalWait(params: ToolParams, _ctx?: unknown, signal?: AbortSignal) {
     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.
@@ -369,23 +440,34 @@ export default function terminalPlugin(ctx: Context): void {
     const useRegex = params?.regex === true;
     if (useRegex) {
       try {
-        new RegExp(raw);
+        compilePattern(raw);
       } catch (e) {
         return fail(`invalid regex: ${(e as Error).message}`);
       }
     }
+    if (typeof params?.file === 'string' && params.file.trim()) {
+      const file = params.file.trim();
+      const path = file.startsWith('~/') ? resolvePath(homedir(), file.slice(2)) : resolvePath(entry.cwd, file);
+      return waitForFile(entry, path, raw, useRegex, params, signal);
+    }
     // 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;
+      const literal = useRegex ? regexLiteralPrefix(raw) : raw;
+      const suggestion = echoSafeWaitSuggestion(literal);
+      const advice = suggestion
+        ? `For future sends, use a sentinel distinguishable from its echo: send \`cmd; echo ${literal}$?\` and wait with regex "${suggestion}" `
+          + '(the echoed command shows `$?`, which that regex cannot match).'
+        : '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).';
       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).',
+        + advice,
       );
     }
     const requested = typeof params?.timeout_ms === 'number' && params.timeout_ms > 0 ? params.timeout_ms : WAIT_DEFAULT_MS;
@@ -406,7 +488,10 @@ export default function terminalPlugin(ctx: Context): void {
         tail = stripAnsi(read.text).slice(-WAIT_TAIL_CHARS);
       } catch {
       }
-      const reason = waitResult.reason === 'timeout' ? 'timeout' : 'wait unavailable';
+      // A wait that consumed its budget is a timeout even when the failing RPC reports itself as
+      // unavailable: the distinction tells the model whether to re-check the command or the server.
+      const consumedBudget = Date.now() - started >= timeoutMs * 0.95;
+      const reason = waitResult.reason === 'timeout' || consumedBudget ? '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 },
@@ -418,7 +503,13 @@ export default function terminalPlugin(ctx: Context): void {
     // 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 ?? '' }
+      ? {
+        revision: entry.readRevision,
+        len: entry.readLen ?? 0,
+        tail: entry.readTail ?? '',
+        textLen: entry.readTextLen ?? 0,
+        textHash: entry.readTextHash ?? 0,
+      }
       : null;
     const shown = raw.length > 80 ? `${raw.slice(0, 80)}…` : raw;
     let sawStale = false;
@@ -460,6 +551,53 @@ export default function terminalPlugin(ctx: Context): void {
     }
   }
 
+  /** `wait` on a log file: the sentinel of a redirected job never reaches the pane. A match already in
+   *  the file when the wait starts returns at once, labelled, so a leftover from an earlier run is visible. */
+  async function waitForFile(
+    entry: TerminalEntry,
+    path: string,
+    pattern: string,
+    useRegex: boolean,
+    params: ToolParams,
+    signal: AbortSignal | undefined,
+  ) {
+    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 matches = (text: string) => (useRegex ? compilePattern(pattern).test(text) : text.includes(pattern));
+    let text: string | null = null;
+    let wake: (() => void) | null = null;
+    const onAbort = () => wake?.();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+      for (let tick = 0; ; tick += 1) {
+        text = await readFileTail(path, FILE_WAIT_TAIL_BYTES);
+        if (text !== null && matches(text)) {
+          const when = tick === 0 ? 'already present when the wait started (truncate the log per run if this is an old one)' : `appeared after ${Math.round((Date.now() - started) / 1000)}s`;
+          return {
+            content: [{ type: 'text', text: `matched in ${path} — ${when}:\n${excerptAroundMatch(text, pattern, useRegex)}` }],
+            details: { terminal_id: entry.terminalId, matched: true, pattern, file: path, alreadyPresent: tick === 0 },
+          };
+        }
+        const left = started + timeoutMs - Date.now();
+        if (left <= 0 || signal?.aborted) break;
+        const { promise, resolve } = Promise.withResolvers<void>();
+        wake = resolve;
+        const timer = setTimeout(resolve, Math.min(FILE_WAIT_POLL_MS, left));
+        await promise;
+        clearTimeout(timer);
+      }
+    } finally {
+      signal?.removeEventListener('abort', onAbort);
+    }
+    const reason = signal?.aborted ? 'aborted' : 'timeout';
+    const tail = text === null ? `\n${path} does not exist.` : text ? `\nrecent file tail:\n${text.slice(-WAIT_TAIL_CHARS)}` : `\n${path} is empty.`;
+    return {
+      content: [{ type: 'text', text: `no match in ${path} within ${timeoutMs}ms (${reason}).${tail}` }],
+      details: { terminal_id: entry.terminalId, matched: false, pattern, file: path, reason },
+    };
+  }
+
   /** 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 }> {
@@ -514,7 +652,13 @@ export default function terminalPlugin(ctx: Context): void {
     }
     const prev: ReadCursor | null = entry
       ? (entry.readRevision != null
-        ? { revision: entry.readRevision, len: entry.readLen ?? 0, tail: entry.readTail ?? '', eoTail: entry.readEoTail ?? '' }
+        ? {
+          revision: entry.readRevision,
+          len: entry.readLen ?? 0,
+          tail: entry.readTail ?? '',
+          textLen: entry.readTextLen ?? 0,
+          textHash: entry.readTextHash ?? 0,
+        }
         : null)
       : null;
     const inc = computeIncrement(prev, { text: read.text, revision: read.revision }, maxChars);
@@ -522,7 +666,8 @@ export default function terminalPlugin(ctx: Context): void {
       entry.readRevision = inc.cursor.revision;
       entry.readLen = inc.cursor.len;
       entry.readTail = inc.cursor.tail;
-      entry.readEoTail = inc.cursor.eoTail;
+      entry.readTextLen = inc.cursor.textLen;
+      entry.readTextHash = inc.cursor.textHash;
       touchTerminal(entry);
     }
     if (inc.mode === 'none') {