pi-pier 0.2.6 → 0.3.0

package/src/terminal-core.ts

@@ -1,4 +1,5 @@
 /** 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. */
@@ -10,8 +11,13 @@ export const READ_MAX_CHARS = 8000;
 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.
+ * 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.
+ */
+export const PROMPT_TAIL_RE = /[$>#❯%]\s*$/;
 
 export interface PromptStrategy {
   /** herdr waitForOutput regex source. */
@@ -20,19 +26,41 @@ export interface PromptStrategy {
 }
 
 export const POSIX_PROMPT: PromptStrategy = {
-  waitPattern: '[$>#❯]\\s*$',
+  waitPattern: '[$>#❯%]\\s*$',
   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*$/,
 };
 
-/** `PIER_TERMINAL_PROMPT=powershell` selects the Windows strategy; default stays POSIX so existing panes do not flip. */
+export const PWSH_PROMPT: PromptStrategy = POWERSHELL_PROMPT; // same object: identity checks stay valid
+
+/**
+ * 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.
+ */
 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();
+  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;
 }
 /** Why: Preserve the established compatibility and safety behavior (T6). */
 export const SIGNAL_KEYS = ['ctrl+c', 'ctrl+d', 'ctrl+z', 'esc', 'enter'] as const;
@@ -57,13 +85,15 @@ export interface TerminalEntry {
   label: string | null;
   createdAt: number;
   lastActivityAt: number;
+  /** Idle-nudge bookkeeping: set when this terminal has been nudged once (per-entry, persisted). */
+  nudgedAt: number | null;
   status: 'open' | 'closed';
   closedAt: number | null;
-  /** Why: Preserve the established compatibility and safety behavior. */
-  readRevision: number | null;
-  readLen: number;
-  readTail: string;
-  readEoTail: string;
+  readRevision?: number | null;
+  readLen?: number;
+  readTail?: string;
+  readEoTail?: string;
+  initialized?: boolean;
 }
 
 export interface TerminalsRegistry {
@@ -107,6 +137,7 @@ export function registerTerminal(
     label: opts.label ?? (opts.cwd ? basename(opts.cwd.replace(/\\/g, '/')) || opts.cwd : null),
     createdAt: opts.createdAt,
     lastActivityAt: opts.createdAt,
+    nudgedAt: null,
     status: 'open',
     closedAt: null,
     readRevision: null,
@@ -302,6 +333,43 @@ export function makeTerminalsRegistry(terminals: TerminalEntry[] = []): Terminal
   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;
+}
+
+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.readiness !== undefined && opts.readiness !== 'prompt') {
+    return { shouldInit: false, command: null };
+  }
+  return { shouldInit: true, command: cmd };
+}
+
 export function foldTerminalsRegistry(entries: readonly BranchEntryLike3[]): TerminalEntry[] {
   let found: TerminalEntry[] = [];
   for (const entry of entries) {
@@ -318,13 +386,96 @@ 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,
         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. */
+
+/** 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. */
+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;
+}
+
+/** Grace from agent_settled to injection, letting the user read the answer and intervene; cancel on agent_start. */
+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 {
+  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). */
+  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;
+  /** Terminal ids this nudge covers; the caller marks them nudged at schedule time. */
+  ids: string[];
+}
+
+function noIdleInject(reminders: number): IdleTerminalReminderPlan {
+  return { due: false, content: null, nextReminders: reminders, ids: [] };
+}
+
+/**
+ * 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.
+ */
+export function planIdleTerminalReminder(
+  input: { open: readonly IdleTerminalInput[]; now: number; reminders: number },
+): IdleTerminalReminderPlan {
+  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 list = idle.map((t) => `- ${t.terminalId} (${t.label ?? t.cwd})`).join('\n');
+  const content = [
+    `<system-reminder>Open terminal(s) idle for a while (nudge ${input.reminders + 1}/${TERM_REMINDERS_MAX}):`,
+    list,
+    '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),
+  };
+}

package/src/todo-core.ts

@@ -171,8 +171,9 @@ export function revertedCompleted(prev: readonly TodoItem[], next: readonly Todo
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
-export function makeSnapshot(items: TodoItem[]): TodoSnapshot {
-  return { version: 1, items };
+export function makeSnapshot(items: readonly TodoItem[]): TodoSnapshot {
+  // Copy: the snapshot is persisted, the service list stays owned by TodosService.
+  return { version: 1, items: [...items] };
 }
 
 export interface BranchEntryLike {
@@ -263,7 +264,7 @@ export function foldLatestTodosMeta(entries: readonly BranchEntryLike[]): Folded
   let writtenAt: number | null = null;
   for (const entry of entries) {
     if (entry.type === 'message') {
-      const msg = entry.message;
+      const msg = entry.message as { role?: unknown; toolName?: unknown; details?: unknown } | null | undefined;
       if (typeof msg !== 'object' || msg === null) continue;
       if (msg.role !== 'toolResult' || msg.toolName !== TODO_TOOL_NAME) continue;
       const snapshot = extractSnapshotFromDetails(msg.details);
@@ -338,7 +339,7 @@ export function boundedView(items: readonly TodoItem[], budget: number): Bounded
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
-export function currentActivity(items: TodoItem[]): string | null {
+export function currentActivity(items: readonly TodoItem[]): string | null {
   return items.find((it) => it.status === 'in_progress')?.content ?? null;
 }
 

package/src/todo-reminder-core.ts

@@ -17,6 +17,7 @@
  *    running, a human gate is blocked, or no open items remain.
  */
 import { ABORT_STOP_REASON } from './settle-wake-core.ts';
+import { pierOption } from './pier-options.ts';
 
 /** Cap reminders for the lifetime of the process, matching the previous behavior. */
 export const TODO_REMINDERS_MAX = 3;
@@ -31,12 +32,17 @@ export const TODO_REMINDER_CUSTOM_TYPE = 'pi-herdr.todo-reminder';
  * can use a small value rather than freezing configuration at module load.
  */
 export function todoReminderGraceMs(): number {
-  return Number(process.env.PI_HERDR_TODO_GRACE_MS ?? 30_000) || 30_000;
+  // B10: canonical PIER_TODO_GRACE_MS, legacy PI_HERDR_TODO_GRACE_MS.
+  return Number(pierOption('PIER_TODO_GRACE_MS') ?? 30_000) || 30_000;
 }
 
 export interface TodoReminderInput {
   /** Stop reason of the last assistant turn before this settlement (null means treat it as natural completion). */
   lastStopReason: string | null;
+  /** True when abort was triggered intentionally by internal mechanisms like OCC. */
+  intentionalAbort?: boolean;
+  /** True when compaction is currently in-flight. */
+  compactionInFlight?: boolean;
   /** Number of reminders already injected. */
   reminders: number;
   /** Number of running background subagents; a positive value means the master is already waiting. */
@@ -67,6 +73,7 @@ function noInject(reminders: number): TodoReminderPlan {
  * (the missing guard in the 01a040cc incident).
  */
 export function planStopTodoReminder(input: TodoReminderInput): TodoReminderPlan {
+  if (input.intentionalAbort || input.compactionInFlight) return noInject(input.reminders);
   if (input.lastStopReason === ABORT_STOP_REASON) return noInject(input.reminders);
   if (input.reminders >= TODO_REMINDERS_MAX) return noInject(input.reminders);
   if (input.runningSubs > 0) return noInject(input.reminders);

package/src/todos-service.ts

@@ -15,6 +15,14 @@ export interface TodosConfig {
   allowParallelInProgress: boolean;
 }
 
+export type TodoCompletionSource = 'tool' | 'reconcile' | 'human' | 'archive';
+
+export interface TodoCompletedEvent {
+  count: number;
+  at: number;
+  source: TodoCompletionSource;
+}
+
 export class TodosService extends EventEmitter {
   private _items: TodoItem[] = [];
   /**
@@ -45,33 +53,37 @@ export class TodosService extends EventEmitter {
     return this._items.map((it) => ({ ...it }));
   }
 
-  replace(items: readonly TodoItem[]): { changed: boolean } {
+  replace(items: readonly TodoItem[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const next = items.map((it) => ({ ...it }));
     if (listsEqual(this._items, next)) return { changed: false };
     const before = this._items;
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'tool');
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
-  applyEdits(edits: readonly TodoEdit[]): { changed: boolean } {
+  applyEdits(edits: readonly TodoEdit[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
     const before = this._items;
     const next = applyTodoEdits(this._items, edits);
     if (listsEqual(before, next)) return { changed: false };
     this._items = next;
     this.lastWriteAt = Date.now();
-    this.emitCompletedTransitions(before, this._items);
+    this.emitCompletedTransitions(before, this._items, opts?.source ?? 'reconcile');
     this.emit('todo.edited', { edits, items: this._items });
     this.emit('todo.updated', { items: this._items });
     return { changed: true };
   }
 
   /** Why: Preserve the established compatibility and safety behavior (M16). */
-  private emitCompletedTransitions(before: readonly TodoItem[], after: readonly TodoItem[]): void {
+  private emitCompletedTransitions(
+    before: readonly TodoItem[],
+    after: readonly TodoItem[],
+    source: TodoCompletionSource = 'tool',
+  ): void {
     const count = countCompletedTransitions(before, after);
-    if (count > 0) this.emit('todo.completed', { count, at: Date.now() });
+    if (count > 0) this.emit('todo.completed', { count, at: Date.now(), source });
   }
 
   rebuild(entries: readonly unknown[]): void {

package/src/tool-error.ts

@@ -0,0 +1,26 @@
+/**
+ * A1: pi only marks a tool result as failed when `execute()` throws — "Returning a value never sets
+ * the error flag regardless of what properties you include in the return object"
+ * (pi docs/extensions.md, "Signaling errors").
+ *
+ * The round-2 audit found 20+ real failures in pier's tools returned as plain text, so neither the
+ * model nor pi's own hooks keyed on `event.isError` could see them (pier's B1 "subagent alive but
+ * reported no output" self-heal was dead code for exactly that reason). Every hard failure now goes
+ * through `toolError()`; deliberate non-failures (empty result set, "no match within Xms", a pane
+ * that simply has not produced output yet) stay normal results.
+ *
+ * The "Error: " prefix the old text returns carried is dropped: the provider's tool-result error
+ * channel and pi's red rendering already mark it, and keeping it would double the prefix once pi
+ * formats a thrown error.
+ */
+export class ToolError extends Error {
+  constructor(message: string) {
+    super(String(message).replace(/^Error:\s*/, ''));
+    this.name = 'ToolError';
+  }
+}
+
+/** Throw a tool failure (never returns). */
+export function toolError(message: string): never {
+  throw new ToolError(message);
+}

package/src/vocab.ts

@@ -48,13 +48,16 @@ export const TODO_TOOL_NAME = 'todo_write';
 /** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
-/** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
-export function formatTodoConfirmation(items: TodoItem[]): string {
+/** Confirmation copy (byte-aligned with DSH so model vocab transfers; blocked is appended only when present). */
+export function formatTodoConfirmation(items: readonly TodoItem[]): string {
   const c = countTodos(items);
-  return `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  const base = `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
+  // A4: blocked items used to be invisible here (the model read "nothing pending" while items sat
+  // blocked waiting on a human). Appending only when non-zero keeps the DSH-aligned wording intact.
+  return c.blocked > 0 ? `${base.slice(0, -1)}, ${c.blocked} blocked.` : base;
 }
 
-export function countTodos(items: TodoItem[]): TodoCounts {
+export function countTodos(items: readonly TodoItem[]): TodoCounts {
   let pending = 0;
   let inProgress = 0;
   let completed = 0;