pi-pier 0.4.1 → 0.4.3

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') {

package/src/plugins/todo.ts

@@ -15,7 +15,7 @@ import { makeProgressUpdate } from '../subagent-core.ts';
 import { TODO_DETAILS_KEY, TODO_STATUSES, TODO_TOOL_NAME, formatTodoConfirmation, type TodoItem } from '../vocab.ts';
 import { toolError } from '../tool-error.ts';
 import { formatAge, isArchived } from '../stale-core.ts';
-import { TODO_EDIT_CUSTOM_TYPE, completionTransitions, fuzzyFind, listsEqual, makeSnapshot, normalizeStrict, revertedCompleted, validateTodos, type TodoEditOp } from '../todo-core.ts';
+import { TODO_ARCHIVE_WINDOW_CUSTOM_TYPE, TODO_EDIT_CUSTOM_TYPE, completionTransitions, fuzzyFind, listsEqual, makeSnapshot, normalizeStrict, revertedCompleted, todoListHash, validateTodos, type TodoEditOp } from '../todo-core.ts';
 import { formatTodoSummary, renderTodoGroups } from '../todo-window.ts';
 import { unifiedWidgetLines, type WorkerWidgetRow } from '../tree-view.ts';
 import { swallow } from '../swallow.ts';
@@ -52,13 +52,10 @@ export interface TodoDeps {
 }
 
 const TOOL_DESCRIPTION = [
-  'Record and update the complete task list for the current work. Every call REPLACES the entire list (last write wins), so always resend the full list.',
-  'Entries: `content` (non-empty, unique; short imperative, what-not-how; no numbering prefixes), `status` (pending | in_progress | completed | blocked | abandoned), optional `blocker` (only when blocked: what it is waiting for), optional `phase` (group name for multi-stage plans; omit for a flat list).',
-  'Keep the list short (at most 15 entries): one entry per meaningful unit of work, not per micro-step.',
-  'Mark tasks you are actively working on as in_progress; several may be in_progress when work genuinely runs in parallel.',
-  'Before stopping, reconcile open entries: anything waiting on a human (decision, approval, or an ops action you cannot perform) must be marked blocked with a blocker note — never left pending, and never executed just to clear the list; finished or obsolete entries must be completed or removed.',
-  'Do not make todo_write the only tool call of a turn — batch it together with real work.',
-  'Delegated work belongs on this list too. When you hand an entry to a subagent, append ` <sub>` to its content (the subagent is doing it, not you); when the subagent settles, a matching entry is auto-completed — you will see "Reconciled:" in the settlement note. If no auto-match fired, update the entry yourself.',
+  'Record the complete task list for the current work. Every call REPLACES the whole list, so always resend it in full.',
+  'Entries: `content` (unique short imperative, no numbering), `status`, `blocker` (only when blocked: what it waits for), optional `phase` (group for a multi-stage plan). At most 15 entries, one per meaningful unit of work; several may be in_progress when work truly runs in parallel.',
+  'Do not make todo_write the only tool call of a turn — batch it with real work.',
+  'When you hand an entry to a subagent, append ` <sub>` to its content; it auto-completes when the subagent settles ("Reconciled:" in the note), otherwise update it yourself.',
 ].join(' ');
 
 
@@ -126,7 +123,7 @@ export default function todoPlugin(ctx: Context): void {
     staleNotices = 0;
   });
 
-  scoped.on('before_agent_start', async (eventCtx?: unknown) => {
+  scoped.on('before_agent_start', async (eventCtx?: unknown, ctx?: unknown) => {
     // pi 1.2+ also fires this for extension-triggered runs; skip the ones that would double-inject
     // or consume the guard cadence (stop reminder, config guide, third-party custom runs).
     if (!shouldRunTodoRead(eventCtx)) return;
@@ -139,12 +136,28 @@ export default function todoPlugin(ctx: Context): void {
       now: Date.now(),
       staleNotices,
       lastStaleGuardTurn,
+      archiveWindowOffered: todos.archiveWindowOffered,
     });
     if (plan.inject && plan.effect === 'stale-notice') {
       staleNotices += 1;
       lastStaleGuardTurn = todoReadTurn;
     }
-    // Empty, archive, and R2 rewrite notices share one cadence so adjacent notices do not each consume the grace window.
+    // Persist the one-window offer against this list identity: the plugin closure dies with the
+    // process, and on /resume the same dead list must reach the terminal clear instead of re-warning.
+    if (plan.inject && plan.offerArchiveWindow) {
+      try {
+        appendEntry(TODO_ARCHIVE_WINDOW_CUSTOM_TYPE, {
+          version: 1,
+          itemsHash: todoListHash(todos.items),
+        });
+      } catch (err) {
+        // The in-memory mark still advances escalation in this process.
+        swallow('todo.persist-archive-window', err);
+      }
+      todos.markArchiveWindowOffered();
+    }
+    // Empty-list guards and the archive rewrite window share one cadence so adjacent notices do not
+    // each consume the grace window; the terminal clear is immediate and only marks the tick.
     if (plan.inject && (plan.effect === 'empty-guard' || plan.archived)) {
       lastEmptyGuardTurn = todoReadTurn;
     }
@@ -159,6 +172,11 @@ export default function todoPlugin(ctx: Context): void {
         swallow('todo.persist-archive', err);
       }
       todos.replace([], { source: 'archive' });
+      // The clear is the one todo mutation outside the tool/human paths that must refresh the
+      // title, sidebar token and widget; the dead list would otherwise stay authoritative. The hook's
+      // first argument is the event (no ui), so render through the run ctx; tests pass a ui ctx first.
+      mirrorTodos();
+      renderWidget(ctx ?? eventCtx);
     }
     todoReadTurn += 1;
     if (!plan.inject) return;
@@ -194,11 +212,18 @@ export default function todoPlugin(ctx: Context): void {
       const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
       if (role === 'assistant' && typeof stopReason === 'string') lastAssistantStopReason = stopReason;
     });
-    for (const ev of ['agent_start', 'session_shutdown']) scoped.on(ev, () => cancelTodoReminder());
-    scoped.on('agent_settled', async () => {
+    // A retry starts a fresh turn, not necessarily a fresh agent_start: cancel the pending reminder
+    // there too so a provider-error retry cannot be interrupted by a stale 30 s timer.
+    for (const ev of ['agent_start', 'turn_start', 'session_shutdown']) scoped.on(ev, () => cancelTodoReminder());
+    scoped.on('agent_settled', async (event: unknown) => {
       cancelTodoReminder();
+      // pi ≥ 1.1 carries `aborted` on agent_settled: authoritative for ESC mid-tool, where stopReason
+      // tracking sees a stale natural reason and would still schedule a reminder.
+      const aborted = event !== null && typeof event === 'object'
+        && 'aborted' in event && event.aborted === true;
       const plan = planStopTodoReminder({
         lastStopReason: lastAssistantStopReason,
+        aborted,
         intentionalAbort: stopReminder.isIntentionalAbort?.() ?? false,
         compactionInFlight: stopReminder.isCompactionInFlight?.() ?? false,
         reminders: todoReminders,
@@ -236,23 +261,20 @@ export default function todoPlugin(ctx: Context): void {
     label: 'Todo',
     description: TOOL_DESCRIPTION,
     promptGuidelines: [
-      'Before stopping with open todo_write entries, reconcile them: entries waiting on a human decision, approval, or ops action must be marked blocked with a blocker note — never left pending, and never executed just to clear the list.',
+      'Before stopping, reconcile open entries: anything waiting on a human (decision, approval, an ops action you cannot perform) is marked blocked with a blocker note — never left pending, never executed just to clear the list; finished or obsolete entries are completed or removed.',
     ],
     parameters: Type.Object({
       todos: Type.Array(
         Type.Object(
           {
-            content: Type.String({ description: 'What the task is — a short imperative line' }),
-            status: Type.Union(
-              TODO_STATUSES.map((status) => Type.Literal(status)),
-              { description: TODO_STATUSES.join(' | ') },
-            ),
-            blocker: Type.Optional(Type.String({ description: 'Only when status is "blocked": what it is waiting for. Omit the field entirely (never an empty string) for other statuses' })),
-            phase: Type.Optional(Type.String({ description: 'Optional group name (≤30 chars); omit for a flat list (never an empty string)' })),
+            content: Type.String({ description: 'Short imperative line' }),
+            status: Type.Union(TODO_STATUSES.map((status) => Type.Literal(status))),
+            blocker: Type.Optional(Type.String({ description: 'Only for blocked; omit otherwise (never an empty string)' })),
+            phase: Type.Optional(Type.String({ description: 'Group name (≤30 chars); omit for a flat list' })),
           },
           { additionalProperties: false },
         ),
-        { description: 'The COMPLETE task list; this call replaces the previous list' },
+        { description: 'The COMPLETE list; replaces the previous one' },
       ),
     }),
     async execute(toolCallId: string, params: ToolParams, signal: AbortSignal | undefined, onUpdate: ((update: unknown) => void) | undefined, eventCtx: unknown) {
@@ -354,7 +376,7 @@ export default function todoPlugin(ctx: Context): void {
       }
       const age = archivedAgeMs();
       const head = formatTodoSummary(todos.items)
-        + (age != null ? ` · archived ${formatAge(age)}（不再注入）` : '');
+        + (age != null ? ` · archived ${formatAge(age)} (no longer injected)` : '');
       ui?.notify?.([head, ...body].join('\n'), 'info');
     },
   });

package/src/reducer-invoker.ts

@@ -68,6 +68,8 @@ type ReducerModelOutput = {
   content?: readonly unknown[];
   text?: unknown;
   usage?: UsageLike;
+  stopReason?: string;
+  errorMessage?: string;
 };
 
 type ReducerModel = NonNullable<ExtensionContext['model']>;
@@ -103,7 +105,7 @@ function resolveCandidate(
   if (!isTrusted) {
     if (!untrustedWarningEmitted) {
       untrustedWarningEmitted = true;
-      console.warn('[pi-herdr] EPR 提炼已在未受信任项目中被安全禁用');
+      console.warn('[pi-herdr] EPR refinement is safely disabled in untrusted projects');
     }
     return undefined;
   }
@@ -139,23 +141,23 @@ function resolveCandidate(
 }
 
 /**
- * Step 6, jev first (RFC §3 P0-1): a confident jev rejection is authoritative even for regex-listed
- * commands; the regex list decides only when jev is absent, fails or answers below the confidence
- * gate (credential-shaped command lines stay local).
+ * Step 6, regex first: only regex-listed commands are candidates; jev may veto them (a confident
+ * rejection is authoritative) but never promotes an unlisted command. Asking jev about every result
+ * flipped 0 of 437 decisions over a week while blocking each tool result ~0.8s and uploading every
+ * command line (D122). Jev failures, low confidence and credential-shaped commands keep the regex hit.
  */
 async function isDiagnosticCandidate(
   command: string,
   gate: JevEprGateDependency | undefined,
   sessionId: string | undefined,
 ): Promise<boolean> {
-  const regexHit = isDiagnosticCommand(command);
-  if (!gate || containsLikelySecret(command)) return regexHit;
+  if (!isDiagnosticCommand(command)) return false;
+  if (!gate || containsLikelySecret(command)) return true;
   const result = await gate.ask(diagnosticGateRequest(command), {
     questionId: 'epr-diagnostic-gate',
     timeoutMs: 2500, // cold TLS hit 1002ms at 1s; at 1500ms a real session still saw 14/73 calls (19%) time out — 2.5s keeps the gate decisive without stalling reducers
     sessionId,
-    // regex_hit makes the flip observable: how often and in which direction jev overrides the regex list (jev.jsonl).
-    extra: { site: 'epr-gate', commandSha256: sha256Hex(command), regexHit },
+    extra: { site: 'epr-gate', commandSha256: sha256Hex(command) },
     enrich: ({ answers }) => {
       if (!answers) return {};
       const verdict = evaluateDiagnosticGate(answers, gate.getMinConfidence());
@@ -167,10 +169,9 @@ async function isDiagnosticCandidate(
       };
     },
   });
-  if (!result.ok) return regexHit;
+  if (!result.ok) return true;
   const verdict = evaluateDiagnosticGate(result.answers, gate.getMinConfidence());
-  if (verdict.hit) return true;
-  return isDiagnosticGateUnanswered(verdict) ? regexHit : false;
+  return verdict.hit || isDiagnosticGateUnanswered(verdict);
 }
 
 /** Step 7: the untruncated source; both failure modes write the same `truncated-source` evidence
@@ -317,7 +318,10 @@ export async function handleReducerToolResult(
   if (config.localOnly) return undefined; // Archival is the whole job in local-only mode.
 
   const reducer = resolveReducerModel(ctx, config);
-  if (!reducer) return undefined;
+  if (!reducer) {
+    await log({ sourceBytes, model: config.model ?? 'default', verificationOk: false, reason: 'no-reducer-model', action: 'fallback_full_text' });
+    return undefined;
+  }
   /** Evidence row for a fail-open exit taken after the reducer model was resolved. */
   const fallbackRow = (reason: string, durationMs: number, extra: Record<string, unknown> = {}): Promise<void> =>
     log({
@@ -354,7 +358,14 @@ export async function handleReducerToolResult(
     : typeof output.text === 'string'
       ? output.text
       : '';
-  if (!modelOutput.trim()) return undefined;
+  if (!modelOutput.trim()) {
+    // pi's complete() reports provider failures as an empty `error` message instead of throwing.
+    await fallbackRow(output.stopReason === 'error' ? 'invoke-failed' : 'empty-output', durationMs, {
+      ...(output.stopReason ? { stopReason: output.stopReason } : {}),
+      ...(output.errorMessage ? { error: output.errorMessage } : {}),
+    });
+    return undefined;
+  }
 
   const validated = validateReceipt(modelOutput, sourceHash, body, event.isError);
   if (!validated.ok) {
@@ -377,7 +388,10 @@ export async function handleReducerToolResult(
     totalTokens: output.usage?.totalTokens,
   });
   const receiptBytes = Buffer.byteLength(receipt, 'utf8');
-  if (receiptBytes >= sourceBytes) return undefined;
+  if (receiptBytes >= sourceBytes) {
+    await fallbackRow('receipt-not-smaller', durationMs, { receiptBytes });
+    return undefined;
+  }
 
   await log({
     sourceBytes,