pi-pier 0.2.7 → 0.3.1

package/src/swallow.ts

@@ -0,0 +1,65 @@
+/**
+ * `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 {
+  /** Stable site label, e.g. 'todo.persist-edit'. */
+  readonly tag: string;
+  readonly message: string;
+  /** Epoch ms. */
+  readonly at: number;
+}
+
+export const SWALLOW_BUFFER_MAX = 50;
+
+const buffer: SwallowedError[] = [];
+
+function describe(err: unknown): string {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code;
+    return code !== undefined ? `${err.name}: ${err.message} (code ${String(code)})` : `${err.name}: ${err.message}`;
+  }
+  if (typeof err === 'string') return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+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; 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() };
+  buffer.push(entry);
+  if (buffer.length > SWALLOW_BUFFER_MAX) buffer.splice(0, buffer.length - SWALLOW_BUFFER_MAX);
+  if (traceEnabled(env)) console.error(`[pier] swallowed ${tag}: ${entry.message}`);
+}
+
+/** Recent swallowed errors, oldest first (diagnostics only; never persisted). */
+export function swallowedErrors(): readonly SwallowedError[] {
+  return [...buffer];
+}
+
+export function resetSwallowedErrors(): void {
+  buffer.length = 0;
+}
+
+/** 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) => {
+    const hhmmss = new Date(e.at).toISOString().slice(11, 19);
+    return `${hhmmss} ${e.tag}: ${e.message}`;
+  });
+  return [`swallowed errors: ${entries.length} this session (last 10)`, ...lines].join('\n');
+}

package/src/terminal-core.ts

@@ -1,17 +1,17 @@
-/** 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 prompt tail. Why: herdr waitForOutput and local classify must share one pattern. */
-export const PROMPT_TAIL_RE = /[$>#❯]\s*$/;
+/** POSIX / PowerShell / Nushell / Zsh prompt tail.
+ * 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*$/;
 
 export interface PromptStrategy {
   /** herdr waitForOutput regex source. */
@@ -20,7 +20,7 @@ export interface PromptStrategy {
 }
 
 export const POSIX_PROMPT: PromptStrategy = {
-  waitPattern: '[$>#❯]\\s*$',
+  waitPattern: '[$>#❯%]\\s*$',
   tailRe: PROMPT_TAIL_RE,
 };
 
@@ -30,25 +30,37 @@ export const POWERSHELL_PROMPT: PromptStrategy = {
   tailRe: /(PS [^\n>]+|>)\s*$/,
 };
 
-/** `PIER_TERMINAL_PROMPT=powershell` selects the Windows strategy; default stays POSIX so existing panes do not flip. */
+/** 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,
+};
+
+/** 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 {
-  return env.PIER_TERMINAL_PROMPT === 'powershell' ? POWERSHELL_PROMPT : POSIX_PROMPT;
+  // B10: canonical PIER_TERMINAL_PROMPT, legacy PI_HERDR_TERMINAL_PROMPT alias.
+  const prompt = pierOption('PIER_TERMINAL_PROMPT', env)?.trim().toLowerCase();
+  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;
@@ -61,6 +73,11 @@ export interface TerminalEntry {
   nudgedAt: number | null;
   status: 'open' | 'closed';
   closedAt: number | null;
+  readRevision?: number | null;
+  readLen?: number;
+  readTail?: string;
+  readEoTail?: string;
+  initialized?: boolean;
 }
 
 export interface TerminalsRegistry {
@@ -68,8 +85,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) {
@@ -86,6 +101,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 } {
@@ -96,8 +113,10 @@ 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,
@@ -115,7 +134,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,
@@ -130,13 +166,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 {
@@ -144,7 +177,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) {
@@ -167,7 +200,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) {
@@ -178,21 +233,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;
 }
 
@@ -200,14 +250,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 },
@@ -232,19 +279,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(
@@ -258,8 +338,6 @@ export function classifyReadiness(
   return 'busy';
 }
 
-/** Why: Preserve the established compatibility and safety behavior (T6). */
-
 export interface TerminalSummary {
   terminalId: string;
   paneId: string;
@@ -288,19 +366,38 @@ export function summarizeSessions(
   return { terminals, stalePaneIds };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+export function makeTerminalsRegistry(terminals: TerminalEntry[] = []): TerminalsRegistry {
+  return { version: 1, terminals };
+}
 
-export interface BranchEntryLike3 {
-  type?: string;
-  customType?: string;
-  data?: unknown;
+export interface ShellInitPlan {
+  readonly shouldInit: boolean;
+  readonly command: string | null;
 }
 
-export function makeTerminalsRegistry(terminals: TerminalEntry[] = []): TerminalsRegistry {
-  return { version: 1, terminals };
+/**
+ * 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 };
+  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: '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;
@@ -316,38 +413,37 @@ 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,
+        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,
         readRevision: typeof t.readRevision === 'number' ? t.readRevision : null,
         readLen: typeof t.readLen === 'number' ? t.readLen : 0,
-        lastActivityAt: typeof t.lastActivityAt === 'number' ? t.lastActivityAt : 0,
-        nudgedAt: typeof t.nudgedAt === 'number' ? t.nudgedAt : null,
-        status: t.status === 'closed' ? ('closed' as const) : ('open' as const),
+        readTail: typeof t.readTail === 'string' ? t.readTail : '',
+        readEoTail: typeof t.readEoTail === 'string' ? t.readEoTail : '',
+        initialized: t.initialized === true,
       }));
   }
   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. */
+ * Terminals persist by design, so a finished shell lingers as a dead split; 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). */
 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 before a nudge is due; the env var is read per call so tests can use small values. */
 export function terminalIdleMs(): number {
-  return Number(process.env.PI_HERDR_TERM_IDLE_MS ?? 30 * 60_000) || 30 * 60_000;
+  // 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;
 }
 
 /** Grace from agent_settled to injection, letting the user read the answer and intervene; cancel on agent_start. */
 export function terminalReminderGraceMs(): number {
-  return Number(process.env.PI_HERDR_TERM_GRACE_MS ?? 30_000) || 30_000;
+  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 {
@@ -355,14 +451,12 @@ export interface IdleTerminalInput {
   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). */
+  /** Set once this terminal has been nudged; a nudged terminal is never nudged again (goodbye-loop guard). */
   nudgedAt?: number | null;
 }
 
 export interface IdleTerminalReminderPlan {
-  /** Whether a nudge should be injected. */
   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;
@@ -375,11 +469,8 @@ function noIdleInject(reminders: number): IdleTerminalReminderPlan {
 }
 
 /**
- * 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.
+ * Due only when an OPEN terminal is idle past the threshold and never nudged; the idle filter also
+ * keeps dev-server shells touched recently out of the nudge.
  */
 export function planIdleTerminalReminder(
   input: { open: readonly IdleTerminalInput[]; now: number; reminders: number },