pi-pier 0.3.0 → 0.4.1

package/src/swallow.ts

@@ -1,16 +1,11 @@
 /**
- * B9: swallowed exceptions. Cleaning up after a failure is often correct (`catch {}` around a
- * best-effort write), but "silently correct" and "silently broken" look identical from the outside —
- * this repo has twice shipped a long-lived `ReferenceError` hidden by an empty catch (pane GC, and
- * `todo` manual-edit persistence), discovered weeks later by accident.
- *
- * `swallow(tag, err)` keeps the cleanup behaviour, but records the event in a bounded ring buffer and
- * — when `PIER_TRACE`/`PI_HERDR_TRACE` is set — writes it to stderr, so `/pier-config` can show the
- * recent ones and a bug report can quote them.
+ * `swallow(tag, err)` keeps catch-site cleanup behaviour, but records the event in a bounded ring
+ * buffer and — when `PIER_TRACE`/`PI_HERDR_TRACE` is set — writes it to stderr, so `/pier-config` can
+ * show the recent ones and a bug report can quote them.
  */
 
 export interface SwallowedError {
-  /** Short, stable site label, e.g. 'todo.persist-edit'. */
+  /** Stable site label, e.g. 'todo.persist-edit'. */
   readonly tag: string;
   readonly message: string;
   /** Epoch ms. */
@@ -34,15 +29,14 @@ function describe(err: unknown): string {
   }
 }
 
-/** Diagnostics switch shared with the rest of the extension (`PIER_TRACE`, legacy `PI_HERDR_TRACE`). */
 function traceEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   const raw = env.PIER_TRACE ?? env.PI_HERDR_TRACE;
   return typeof raw === 'string' && raw.trim() !== '' && raw !== '0';
 }
 
 /**
- * Record a caught error that is being intentionally ignored.
- * Returns nothing: call sites stay `} catch (err) { swallow('tag', err); }` and keep their cleanup.
+ * Record a caught error that is being intentionally ignored; call sites keep their cleanup and stay
+ * `} catch (err) { swallow('tag', err); }`.
  */
 export function swallow(tag: string, err: unknown, env: NodeJS.ProcessEnv = process.env): void {
   const entry: SwallowedError = { tag, message: describe(err), at: Date.now() };
@@ -56,15 +50,11 @@ export function swallowedErrors(): readonly SwallowedError[] {
   return [...buffer];
 }
 
-/** Test seam: drop buffered entries. */
 export function resetSwallowedErrors(): void {
   buffer.length = 0;
 }
 
-/**
- * Render the recent swallowed errors for `/pier-config`.
- * Empty input returns an explicit "none" line so the section is never ambiguous.
- */
+/** Render for `/pier-config`; the section is never ambiguous even with no entries. */
 export function formatSwallowedErrors(entries: readonly SwallowedError[] = swallowedErrors()): string {
   if (entries.length === 0) return 'swallowed errors: none this session';
   const lines = entries.slice(-10).map((e) => {

package/src/terminal-core.ts

@@ -1,21 +1,15 @@
-/** Why: Preserve the established compatibility and safety behavior (D71, M14, T1–T6, T3, T6). */
 import { pierOption } from './pier-options.ts';
 import { basename } from 'node:path';
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export const TERMINALS_CUSTOM_TYPE = 'pi-herdr.terminals';
 export const MAX_TERMINALS = 8;
 export const READ_MAX_CHARS = 8000;
-/** Why: Preserve the established compatibility and safety behavior. */
-export const READ_HARD_CAP_CHARS = 200;
 export const READINESS_TIMEOUT_MS = 30_000;
 export const SILENCE_IDLE_MS = 2000;
 /** POSIX / PowerShell / Nushell / Zsh prompt tail.
- * Why: macOS default zsh prompt ends with `%` (e.g. `user@host ~ % `), while sh/bash use `$`
- * (or `#` for root) and nushell/starship use `❯`. Anchoring to line tail (\s*$) prevents false
- * matches on percentage values in ordinary command output (e.g. `downloaded 50%`), as interactive
- * prompts terminate at the prompt symbol without trailing text.
+ * sh/bash end with `$` (root `#`), macOS zsh with `%`, nushell/starship with `❯`; anchoring to the
+ * line tail (\s*$) avoids matching percentage values in ordinary output (`downloaded 50%`), since
+ * interactive prompts end at the prompt symbol with no trailing text.
  */
 export const PROMPT_TAIL_RE = /[$>#❯%]\s*$/;
 
@@ -30,53 +24,43 @@ export const POSIX_PROMPT: PromptStrategy = {
   tailRe: PROMPT_TAIL_RE,
 };
 
-export const BASH_PROMPT: PromptStrategy = POSIX_PROMPT;
-export const ZSH_PROMPT: PromptStrategy = POSIX_PROMPT;
-
 /** cmd.exe / PowerShell: `>` still matches POSIX; this also accepts `PS C:\\>` without a trailing `$`. */
 export const POWERSHELL_PROMPT: PromptStrategy = {
   waitPattern: '(PS [^\\n>]+|>)\\s*$',
   tailRe: /(PS [^\n>]+|>)\s*$/,
 };
 
-export const PWSH_PROMPT: PromptStrategy = POWERSHELL_PROMPT; // same object: identity checks stay valid
+/** Shell name (lowercased basename from $SHELL, or a PIER_TERMINAL_PROMPT value) → strategy. */
+const PROMPT_STRATEGIES: Record<string, PromptStrategy> = {
+  bash: POSIX_PROMPT,
+  zsh: POSIX_PROMPT,
+  pwsh: POWERSHELL_PROMPT,
+  'pwsh.exe': POWERSHELL_PROMPT,
+  powershell: POWERSHELL_PROMPT,
+  'powershell.exe': POWERSHELL_PROMPT,
+};
 
-/**
- * Strategy selection covering bash, zsh, powershell/pwsh.
- * Explicit `PIER_TERMINAL_PROMPT` env var takes precedence; otherwise `SHELL` is inspected.
- * Default remains POSIX so existing Windows/Linux panes without explicit configuration do not flip.
- */
+/** Explicit `PIER_TERMINAL_PROMPT` wins over `$SHELL`; the default stays POSIX so unconfigured panes
+ *  never flip strategy. */
 export function promptStrategyFor(env: NodeJS.ProcessEnv = process.env): PromptStrategy {
   // B10: canonical PIER_TERMINAL_PROMPT, legacy PI_HERDR_TERMINAL_PROMPT alias.
   const prompt = pierOption('PIER_TERMINAL_PROMPT', env)?.trim().toLowerCase();
-  if (prompt === 'powershell' || prompt === 'pwsh') return POWERSHELL_PROMPT;
-  if (prompt === 'bash') return BASH_PROMPT;
-  if (prompt === 'zsh') return ZSH_PROMPT;
-  if (!prompt && env.SHELL) {
-    const sh = basename(env.SHELL.replace(/\\/g, '/')).toLowerCase();
-    if (sh === 'pwsh' || sh === 'powershell' || sh === 'powershell.exe' || sh === 'pwsh.exe') {
-      return POWERSHELL_PROMPT;
-    }
-    if (sh === 'bash') return BASH_PROMPT;
-    if (sh === 'zsh') return ZSH_PROMPT;
-  }
-  return POSIX_PROMPT;
+  const shell = prompt || basename((env.SHELL ?? '').replace(/\\/g, '/')).toLowerCase();
+  return PROMPT_STRATEGIES[shell] ?? POSIX_PROMPT;
 }
-/** Why: Preserve the established compatibility and safety behavior (T6). */
+
 export const SIGNAL_KEYS = ['ctrl+c', 'ctrl+d', 'ctrl+z', 'esc', 'enter'] as const;
 export type SignalKey = (typeof SIGNAL_KEYS)[number];
 
 const FULLSCREEN_SEQUENCES = [
-  '\x1b[?1049h', // Why: Preserve the established compatibility and safety behavior.
-  '\x1b[?47h', // Why: Preserve the established compatibility and safety behavior.
-  '\x1b[2J\x1b[H', // Why: Preserve the established compatibility and safety behavior.
+  '\x1b[?1049h',
+  '\x1b[?47h',
+  '\x1b[2J\x1b[H',
 ] as const;
 
 export const RESET_MARKER = '…[buffer reset — earlier output scrolled away or cleared]…';
 export const TRUNCATE_MARKER = '…[truncated]…';
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export interface TerminalEntry {
   terminalId: string;
   paneId: string;
@@ -85,7 +69,9 @@ export interface TerminalEntry {
   label: string | null;
   createdAt: number;
   lastActivityAt: number;
-  /** Idle-nudge bookkeeping: set when this terminal has been nudged once (per-entry, persisted). */
+  /** Nudges delivered for this terminal (0..TERM_REMINDERS_MAX), persisted. */
+  nudges: number;
+  /** Timestamp of the last nudge; kept alongside `nudges` for legacy records and debugging. */
   nudgedAt: number | null;
   status: 'open' | 'closed';
   closedAt: number | null;
@@ -101,8 +87,6 @@ export interface TerminalsRegistry {
   terminals: TerminalEntry[];
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export function nextTerminalId(existingIds: readonly string[]): string {
   let max = 0;
   for (const id of existingIds) {
@@ -119,6 +103,8 @@ export function registerTerminal(
     tabId: string;
     cwd: string;
     label?: string | null;
+    /** Caller-requested id; when omitted (or unusable per validateTerminalId) a term-N id is assigned. */
+    terminalId?: string | null;
     createdAt: number;
   },
 ): { ok: true; entries: TerminalEntry[]; entry: TerminalEntry } | { ok: false; error: string } {
@@ -129,14 +115,17 @@ export function registerTerminal(
       error: `terminal limit reached (max ${MAX_TERMINALS} open terminals); close one with terminal(action: "close") before opening another`,
     };
   }
+  const requested = validateTerminalId(opts.terminalId, entries.map((e) => e.terminalId));
+  if (requested != null && !requested.ok) return { ok: false, error: requested.error };
   const entry: TerminalEntry = {
-    terminalId: nextTerminalId(entries.map((e) => e.terminalId)),
+    terminalId: requested != null && requested.ok ? requested.id : nextTerminalId(entries.map((e) => e.terminalId)),
     paneId: opts.paneId,
     tabId: opts.tabId,
     cwd: opts.cwd,
     label: opts.label ?? (opts.cwd ? basename(opts.cwd.replace(/\\/g, '/')) || opts.cwd : null),
     createdAt: opts.createdAt,
     lastActivityAt: opts.createdAt,
+    nudges: 0,
     nudgedAt: null,
     status: 'open',
     closedAt: null,
@@ -148,7 +137,24 @@ export function registerTerminal(
   return { ok: true, entries: [...entries, entry], entry };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** A requested terminal id must be a short single-token string that no existing terminal (open or
+ *  closed) already uses — ids stay addressable after close for `close`/`list`, so reuse would
+ *  retarget actions at the wrong pane. Returns null when no id was requested. */
+export function validateTerminalId(
+  id: string | null | undefined,
+  existingIds: readonly string[],
+): { ok: true; id: string } | { ok: false; error: string } | null {
+  const trimmed = (id ?? '').trim();
+  if (trimmed.length === 0) return null; // blank means "not provided" → auto-assigned term-N
+  if (trimmed.length > 64 || /\s/.test(trimmed)) {
+    return { ok: false, error: `invalid terminal_id "${trimmed.slice(0, 40)}": use 1-64 characters without whitespace, or omit it to get an auto-assigned term-N id` };
+  }
+  if (existingIds.includes(trimmed)) {
+    return { ok: false, error: `terminal_id "${trimmed}" is already used (open or closed); ids stay reserved for addressing — pick another or omit it` };
+  }
+  return { ok: true, id: trimmed };
+}
+
 export function closeTerminal(
   entries: readonly TerminalEntry[],
   terminalId: string,
@@ -163,13 +169,10 @@ export function closeTerminal(
   };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D71). */
 export function activeTerminalPaneIds(entries: readonly TerminalEntry[]): Set<string> {
   return new Set(entries.filter((e) => e.status === 'open').map((e) => e.paneId));
 }
 
-/** Why: Preserve the established compatibility and safety behavior (T6). */
-
 export function validateSendText(text: string): { ok: true; text: string } | { ok: false; error: string } {
   if (text.includes('\x1b')) {
     return {
@@ -177,7 +180,7 @@ export function validateSendText(text: string): { ok: true; text: string } | { o
       error: 'unsupported input: ANSI escape sequences cannot be sent as text; use terminal(action: "signal") for control keys, or plain commands only',
     };
   }
-  // Why: Preserve the established compatibility and safety behavior (C0).
+
   const stripped = text.replace(/[\r\n]+$/, '');
   const bad = stripped.match(/[\x00-\x08\x0b-\x1f\x7f]/);
   if (bad) {
@@ -200,7 +203,29 @@ export function validateSignal(key: string): { ok: true; key: SignalKey } | { ok
   return { ok: true, key: k };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (T6). */
+/**
+ * Whether a wait pattern would match the terminal's own echoed input: the shell echoes typed
+ * commands into the pane, so a pattern contained in the last sent text (`…; echo TERM_DONE_$?`
+ * waited on as literal `TERM_DONE_`) matches its own echo and returns "matched" before the job
+ * has produced anything. Detection is per terminal and best-effort: no send in this process
+ * lifetime → no hazard known → the wait proceeds unchanged.
+ */
+export function sentinelEchoHazard(opts: {
+  pattern: string;
+  regex?: boolean;
+  lastSentText?: string | null;
+}): boolean {
+  const sent = opts.lastSentText;
+  if (!sent) return false;
+  if (opts.regex) {
+    try {
+      return new RegExp(opts.pattern).test(sent);
+    } catch {
+      return false; // invalid regex is rejected by the caller before this runs
+    }
+  }
+  return sent.includes(opts.pattern);
+}
 
 export function detectFullscreenTUI(raw: string): { detected: boolean; sequence: string | null } {
   for (const seq of FULLSCREEN_SEQUENCES) {
@@ -211,21 +236,16 @@ export function detectFullscreenTUI(raw: string): { detected: boolean; sequence:
 
 export function stripAnsi(raw: string): string {
   return raw
-    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '') // Why: Preserve the established compatibility and safety behavior.
-    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, '') // Why: Preserve the established compatibility and safety behavior.
-    .replace(/\x1b[@-Z\\-_]/g, '') // Why: Preserve the established compatibility and safety behavior.
-    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ''); // Why: Preserve the established compatibility and safety behavior.
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, '')
+    .replace(/\x1b[@-Z\\-_]/g, '')
+    .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export interface ReadCursor {
   revision: number;
-  /** Why: Preserve the established compatibility and safety behavior. */
   len: number;
-  /** Why: Preserve the established compatibility and safety behavior. */
   tail: string;
-  /** Why: Preserve the established compatibility and safety behavior. */
   eoTail: string;
 }
 
@@ -233,14 +253,11 @@ export interface ReadIncrement {
   mode: 'none' | 'append' | 'reset';
   text: string;
   cursor: ReadCursor;
-  /** Why: Preserve the established compatibility and safety behavior. */
   hardCapped: boolean;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 const CURSOR_TAIL_CHARS = 64;
 
-/** Why: Preserve the established compatibility and safety behavior (M14). */
 export function computeIncrement(
   prev: ReadCursor | null,
   next: { text: string; revision: number },
@@ -265,19 +282,52 @@ export function computeIncrement(
     const bounded = boundText(suffix, maxChars);
     return { mode: 'append', text: bounded.text, cursor, hardCapped: bounded.capped };
   }
-  // Why: Preserve the established compatibility and safety behavior.
+
   const bounded = boundText(next.text, maxChars);
   const text = prev ? `${RESET_MARKER}\n${bounded.text}` : bounded.text;
   return { mode: 'reset', text, cursor, hardCapped: bounded.capped };
 }
 
+/** Window around the first hit so a later capped read cannot hide the match behind earlier lines. */
+export function excerptAroundMatch(text: string, pattern: string, regex: boolean, radius = 1500): string {
+  let index = -1;
+  let hitLen = pattern.length;
+  if (regex) {
+    const found = new RegExp(pattern).exec(text);
+    index = found?.index ?? -1;
+    hitLen = found?.[0].length ?? pattern.length;
+  } else {
+    index = text.indexOf(pattern);
+  }
+  if (index < 0) return text.slice(-radius);
+  const start = Math.max(0, index - radius);
+  const end = Math.min(text.length, index + hitLen + radius);
+  return `${start > 0 ? '…' : ''}${text.slice(start, end)}${end < text.length ? '…' : ''}`;
+}
+
+/**
+ * herdr waitForOutput matches the whole pane, including text a prior read already returned.
+ * A hit is fresh only when it sits in the unread increment; a hit only in consumed text is stale.
+ */
+export function classifyWaitMatch(
+  prev: ReadCursor | null,
+  paneText: string,
+  pattern: string,
+  regex: boolean,
+): { kind: 'fresh'; excerpt: string } | { kind: 'stale' } | { kind: 'absent' } {
+  const match = (text: string) => regex ? new RegExp(pattern).test(text) : text.includes(pattern);
+  const inc = computeIncrement(prev, { text: paneText, revision: prev?.revision ?? 0 }, paneText.length + 1);
+  const unread = inc.mode === 'append' ? inc.text : inc.mode === 'reset' ? paneText : '';
+  if (match(unread)) return { kind: 'fresh', excerpt: excerptAroundMatch(unread, pattern, regex) };
+  if (inc.mode !== 'reset' && match(paneText)) return { kind: 'stale' };
+  return { kind: 'absent' };
+}
+
 function boundText(text: string, maxChars: number): { text: string; capped: boolean } {
   if (text.length <= maxChars) return { text, capped: false };
   return { text: `${text.slice(text.length - maxChars)}\n${TRUNCATE_MARKER}`, capped: true };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (T3). */
-
 export type ReadinessTier = 'prompt' | 'silent' | 'busy';
 
 export function classifyReadiness(
@@ -291,8 +341,6 @@ export function classifyReadiness(
   return 'busy';
 }
 
-/** Why: Preserve the established compatibility and safety behavior (T6). */
-
 export interface TerminalSummary {
   terminalId: string;
   paneId: string;
@@ -321,56 +369,38 @@ export function summarizeSessions(
   return { terminals, stalePaneIds };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
-export interface BranchEntryLike3 {
-  type?: string;
-  customType?: string;
-  data?: unknown;
-}
-
 export function makeTerminalsRegistry(terminals: TerminalEntry[] = []): TerminalsRegistry {
   return { version: 1, terminals };
 }
 
-/**
- * Why: In interactive bash and zsh, history expansion (`!`) is active by default. Commands
- * containing `!` (such as `!|` or `if [ ! -f ... ]` or `!$`) trigger history expansion
- * (e.g. `zsh: event not found: \|`), wedging the managed shell and leaving the controller
- * waiting indefinitely (observed in session 01a08f37).
- * We disable history expansion for managed shells right after creation via `set +H` (supported
- * by both bash and zsh; equivalent to `unsetopt BANG_HIST` in zsh).
- * On Windows / PowerShell, `set +H` is unrecognized syntax and PowerShell does not use `!`
- * for history expansion, so init is skipped.
- *
- * Limits: `set +H` only affects the top-level persistent shell process. If a command spawns
- * a nested interactive subshell (e.g. `bash -i`), that subshell would re-enable its default options.
- */
-export function shellInitCommandFor(strategy: PromptStrategy = POSIX_PROMPT): string | null {
-  return strategy === POWERSHELL_PROMPT ? null : 'set +H';
-}
-
 export interface ShellInitPlan {
   readonly shouldInit: boolean;
   readonly command: string | null;
 }
 
+/**
+ * Plan the shell init command: `set +H` disables history expansion in managed bash/zsh shells, where `!`
+ * in ordinary commands (`!|`, `if [ ! -f ... ]`, `!$`) otherwise triggers `zsh: event not found: \|` and
+ * wedges the shell. PowerShell rejects the syntax and has no `!` history expansion, so it is skipped.
+ * Limit: the top-level shell only — a nested `bash -i` re-enables its own defaults; init is only worth
+ * sending once the shell is at its prompt and has not been initialized yet.
+ */
 export function planShellInit(opts: {
   strategy?: PromptStrategy;
   readiness?: ReadinessTier;
   initialized?: boolean;
 }): ShellInitPlan {
   if (opts.initialized) return { shouldInit: false, command: null };
-  const strategy = opts.strategy ?? POSIX_PROMPT;
-  const cmd = shellInitCommandFor(strategy);
-  if (!cmd) return { shouldInit: false, command: null };
+  if ((opts.strategy ?? POSIX_PROMPT) === POWERSHELL_PROMPT) return { shouldInit: false, command: null };
   if (opts.readiness !== undefined && opts.readiness !== 'prompt') {
     return { shouldInit: false, command: null };
   }
-  return { shouldInit: true, command: cmd };
+  return { shouldInit: true, command: 'set +H' };
 }
 
-export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): TerminalEntry[] {
+export function foldTerminalsRegistry(
+  entries: readonly { type?: string; customType?: string; data?: unknown }[],
+): TerminalEntry[] {
   let found: TerminalEntry[] = [];
   for (const entry of entries) {
     if (entry.type !== 'custom' || entry.customType !== TERMINALS_CUSTOM_TYPE) continue;
@@ -386,6 +416,9 @@ export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): Ter
         label: typeof t.label === 'string' ? t.label : null,
         createdAt: typeof t.createdAt === 'number' ? t.createdAt : 0,
         lastActivityAt: typeof t.lastActivityAt === 'number' ? t.lastActivityAt : 0,
+        nudges: typeof t.nudges === 'number'
+          ? Math.max(0, Math.min(TERM_REMINDERS_MAX, Math.floor(t.nudges)))
+          : (typeof t.nudgedAt === 'number' ? 1 : 0),
         nudgedAt: typeof t.nudgedAt === 'number' ? t.nudgedAt : null,
         status: t.status === 'closed' ? ('closed' as const) : ('open' as const),
         closedAt: typeof t.closedAt === 'number' ? t.closedAt : null,
@@ -399,19 +432,20 @@ export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): Ter
   return found;
 }
 
-/* ── Idle-terminal nudge: turn-end self-cleanup for shells the model forgot to close ──
- * Observed (wF:p7 orphan): a master opened a resident terminal for a one-shot background
- * compile, the job finished, and nothing ever closed the pane — terminals are persistent by
- * design, so the shell lingered as a dead split in the main tab. Decision core mirrors the
- * todo stop-reminder: pure plan here, delivery wiring in core/terminal. */
+/* ── Terminal nudge: turn-end self-cleanup for shells the model forgot to close ──
+ * Terminals persist by design, so a finished shell lingers as a dead split. Two notices per terminal:
+ *   1. at the end of the turn that used it ("used this turn") — or the first turn that finds it idle
+ *      past the threshold, for a shell nobody touched recently;
+ *   2. on a later settle once it has been idle past PIER_TERM_IDLE_MS.
+ * Delivery wiring mirrors the todo stop-reminder in plugins/terminal. */
 
-/** Cap idle-terminal nudges for the lifetime of the process (same shape as TODO_REMINDERS_MAX). */
+/** Per-terminal nudge cap: one after use, one after the idle threshold (goodbye-loop guard). */
 export const TERM_REMINDERS_MAX = 2;
 
-/** Idle threshold before a nudge is due; PI_HERDR_TERM_IDLE_MS is read per call so tests can use small values. */
+/** Idle threshold for the second nudge; the env var is read per call so tests can use small values. */
 export function terminalIdleMs(): number {
   // B10: canonical PIER_TERM_IDLE_MS, legacy PI_HERDR_TERM_IDLE_MS.
-  return Number(pierOption('PIER_TERM_IDLE_MS') ?? 30 * 60_000) || 30 * 60_000;
+  return Number(pierOption('PIER_TERM_IDLE_MS') ?? 5 * 60_000) || 5 * 60_000;
 }
 
 /** Grace from agent_settled to injection, letting the user read the answer and intervene; cancel on agent_start. */
@@ -419,63 +453,82 @@ export function terminalReminderGraceMs(): number {
   return Number(pierOption('PIER_TERM_GRACE_MS') ?? 30_000) || 30_000;
 }
 
-/** Custom message type for the idle-terminal nudge (registerMessageRenderer may restyle it). */
 export const TERM_REMINDER_CUSTOM_TYPE = 'pi-herdr.term-reminder';
 
-export interface IdleTerminalInput {
+export interface TerminalNudgeInput {
   terminalId: string;
   cwd: string;
   label: string | null;
   lastActivityAt: number;
-  /** Set once this terminal has been nudged; a nudged terminal is never nudged again (01a06ae3 goodbye-loop guard). */
+  /** Nudges already delivered; when absent, legacy `nudgedAt` counts as one. */
+  nudges?: number;
   nudgedAt?: number | null;
+  /** A non-shell foreground process owns the pane (dev server / running job); never nudge it. */
+  busy?: boolean;
 }
 
-export interface IdleTerminalReminderPlan {
-  /** Whether a nudge should be injected. */
+export interface TerminalReminderPlan {
   due: boolean;
-  /** Complete injected content, or null when due is false. */
   content: string | null;
-  /** Nudge count after successful injection, or the original count when due is false. */
-  nextReminders: number;
-  /** Terminal ids this nudge covers; the caller marks them nudged at schedule time. */
+  /** Terminals covered by this notice; the caller bumps each one's `nudges` at schedule time. */
   ids: string[];
 }
 
-function noIdleInject(reminders: number): IdleTerminalReminderPlan {
-  return { due: false, content: null, nextReminders: reminders, ids: [] };
+function noTerminalInject(): TerminalReminderPlan {
+  return { due: false, content: null, ids: [] };
+}
+
+function nudgesOf(t: TerminalNudgeInput): number {
+  return t.nudges ?? (t.nudgedAt != null ? 1 : 0);
+}
+
+/** `72m` / `3h12m`: the reason column reads at a glance without a timestamp. */
+function formatIdleAge(ms: number): string {
+  const minutes = Math.max(0, Math.floor(ms / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h${String(minutes % 60).padStart(2, '0')}m`;
 }
 
 /**
- * Due only when an OPEN terminal is idle past the threshold AND has never been nudged
- * (01a06ae3: a per-process counter alone let nudges resume after restarts and looped a
- * farewell exchange 52 times — a nudged terminal must stay nudged, persisted in the ledger).
- * Shells still hosting long-running work were touched recently, so the idle filter is what
- * keeps legitimate dev-server terminals out of the nudge.
+ * First notice: the terminal was used by the agent run that just settled, or it is already idle past
+ * the threshold. Second notice: a terminal with one nudge is idle past the threshold again. A shell
+ * touched recently is never nudged, so a dev server in active use stays out.
  */
-export function planIdleTerminalReminder(
-  input: { open: readonly IdleTerminalInput[]; now: number; reminders: number },
-): IdleTerminalReminderPlan {
+export function planTerminalReminder(
+  input: { open: readonly TerminalNudgeInput[]; now: number; turnStartedAt?: number | null },
+): TerminalReminderPlan {
   const idleMs = terminalIdleMs();
-  const idle = input.open.filter(
-    (t) => !t.nudgedAt && input.now - t.lastActivityAt >= idleMs,
-  );
-  if (idle.length === 0 || input.reminders >= TERM_REMINDERS_MAX) {
-    return noIdleInject(input.reminders);
+  const rows: string[] = [];
+  const ids: string[] = [];
+  for (const t of input.open) {
+    if (t.busy) continue;
+    const nudges = nudgesOf(t);
+    if (nudges >= TERM_REMINDERS_MAX) continue;
+    const idleFor = input.now - t.lastActivityAt;
+    const sinceNudge = t.nudgedAt != null ? input.now - t.nudgedAt : Number.POSITIVE_INFINITY;
+    const usedThisTurn = input.turnStartedAt != null && t.lastActivityAt >= input.turnStartedAt;
+    // Second notice waits another full idle window after the first one, so a pane that was already
+    // idle for an hour at nudge 1 is not nudged twice back-to-back on the next settle.
+    const reason = nudges === 0 && usedThisTurn
+      ? 'used this turn'
+      : nudges === 0 && idleFor >= idleMs
+        ? `idle ${formatIdleAge(idleFor)}`
+        : nudges === 1 && idleFor >= idleMs && sinceNudge >= idleMs
+          ? `still idle ${formatIdleAge(idleFor)}`
+          : null;
+    if (reason == null) continue;
+    rows.push(`- ${t.terminalId} (${t.label ?? t.cwd}) — ${reason} · nudge ${nudges + 1}/${TERM_REMINDERS_MAX}`);
+    ids.push(t.terminalId);
   }
-  const list = idle.map((t) => `- ${t.terminalId} (${t.label ?? t.cwd})`).join('\n');
+  if (ids.length === 0) return noTerminalInject();
   const content = [
-    `<system-reminder>Open terminal(s) idle for a while (nudge ${input.reminders + 1}/${TERM_REMINDERS_MAX}):`,
-    list,
+    '<system-reminder>Open terminal(s) that may be finished:',
+    ...rows,
     'This is an internal housekeeping notice — do NOT reply to the user and do NOT send any farewell on this notice.',
     'If the work in them is done, close them now with terminal(action: "close", terminal_id: "…").',
     'Keep a terminal only if a long-running process still needs that shell.',
     '</system-reminder>',
   ].join('\n');
-  return {
-    due: true,
-    content,
-    nextReminders: input.reminders + 1,
-    ids: idle.map((t) => t.terminalId),
-  };
+  return { due: true, content, ids };
 }