pi-pier 0.2.7 → 0.3.0

package/src/subagent-session-io.ts

@@ -5,21 +5,19 @@
  * order (reported path/id before recent-file fallback, excluding the parent
  * session). Keeping it in one adapter prevents settlement text from crossing sessions.
  */
-import { stat as statCb } from 'node:fs';
-import { promisify } from 'node:util';
+import { accessSync, constants, statSync } from 'node:fs';
 import type { HerdrClientLike } from './herdr-client.ts';
 import {
-  hasAssistantAfter,
-  hasPendingToolCall,
+  deriveSubSessionState,
   lastAssistantText,
   listSessionFiles,
   readSessionFile,
   sessionFileById,
+  type SessionEntryLike,
+  type SubSessionState,
 } from './session-tail.ts';
 import type { AliveProbe } from './subagent-core.ts';
 
-const statAsync = promisify(statCb);
-
 export interface SessionIoHost {
   client: HerdrClientLike;
   getSessionId: () => string;
@@ -32,10 +30,74 @@ export interface SessionIo {
   collectFinalText(paneId: string, cwd: string, sinceTs: number, attempts?: number): Promise<string | null>;
   readAskFlag(paneId: string): Promise<string | null>;
   probeAlive(paneId: string, cwd: string): Promise<AliveProbe>;
-  subSessionState(paneId: string, cwd: string, sinceTs: number): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }>;
+  subSessionState(paneId: string, cwd: string, sinceTs: number): Promise<SubSessionState>;
+}
+
+/** Cheap change fingerprint of a session file; null when it does not exist. */
+interface FileStamp {
+  size: number;
+  mtimeMs: number;
+}
+
+function stampOf(file: string): FileStamp | null {
+  try {
+    const s = statSync(file);
+    return { size: s.size, mtimeMs: s.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+/** Readable regular file check: parsing the file would read it in full (up to MBs). */
+function isReadableFile(file: string): boolean {
+  try {
+    if (!statSync(file).isFile()) return false;
+    accessSync(file, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Memo of values derived from a session file, keyed by path and invalidated by (size, mtime).
+ *
+ * Why: worker sessions grow to tens of MB, and the poll loop re-derives the same idle state every
+ * tick (collectFinalText re-derives up to `attempts` times). Measured on a 31.6MB session:
+ * file read + JSON.parse + derive ≈ 227ms, so an unchanged file must not be parsed twice.
+ * An append-only JSONL changes size on every write, so (size, mtime) is a sound fingerprint.
+ */
+class DerivedCache<T> {
+  private readonly entries = new Map<string, { stamp: FileStamp; sinceTs: number; value: T }>();
+  private readonly limit: number;
+
+  constructor(limit = 32) {
+    this.limit = limit;
+  }
+
+  get(file: string, stamp: FileStamp, sinceTs: number): T | undefined {
+    const hit = this.entries.get(file);
+    if (!hit || hit.stamp.size !== stamp.size || hit.stamp.mtimeMs !== stamp.mtimeMs || hit.sinceTs !== sinceTs) {
+      return undefined;
+    }
+    return hit.value;
+  }
+
+  set(file: string, stamp: FileStamp, sinceTs: number, value: T): void {
+    this.entries.delete(file);
+    this.entries.set(file, { stamp, sinceTs, value });
+    while (this.entries.size > this.limit) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
 }
 
 export function createSessionIo(h: SessionIoHost): SessionIo {
+  const stateCache = new DerivedCache<SubSessionState>();
+  const finalTextCache = new DerivedCache<string | null>();
+
   async function resolveSessionFileCandidates(paneId: string, cwd: string): Promise<string[]> {
     const out: string[] = [];
     try {
@@ -59,7 +121,7 @@ export function createSessionIo(h: SessionIoHost): SessionIo {
 
   async function resolveSessionFile(paneId: string, cwd: string): Promise<string | null> {
     for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      if (readSessionFile(file)) return file;
+      if (isReadableFile(file)) return file;
     }
     return null;
   }
@@ -72,10 +134,18 @@ export function createSessionIo(h: SessionIoHost): SessionIo {
   ): Promise<string | null> {
     for (let i = 0; i < attempts; i++) {
       for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-        const entries = readSessionFile(file);
+        const stamp = stampOf(file);
+        if (!stamp) continue;
+        const cached = finalTextCache.get(file, stamp, sinceTs);
+        if (cached !== undefined) {
+          if (cached) return cached;
+          continue;
+        }
+        const entries: SessionEntryLike[] | null = readSessionFile(file);
         if (!entries) continue;
-        const r = lastAssistantText(entries, { sinceTs });
-        if (r?.text) return r.text;
+        const text = lastAssistantText(entries, { sinceTs })?.text ?? null;
+        finalTextCache.set(file, stamp, sinceTs, text);
+        if (text) return text;
       }
       const wait = Promise.withResolvers<void>();
       setTimeout(wait.resolve, 500);
@@ -96,21 +166,31 @@ export function createSessionIo(h: SessionIoHost): SessionIo {
 
   async function probeAlive(paneId: string, cwd: string): Promise<AliveProbe> {
     const probe: AliveProbe = { paneExists: false, agentStatus: null, lastActivityMs: null };
+    let listed = false;
     try {
-      const agents = await h.client.listAgents();
-      const a = agents.find((x) => x.paneId === paneId);
-      probe.paneExists = a != null;
-      probe.agentStatus = a?.status ?? null;
+      const pane = (await h.client.listPanes()).find((p) => p.paneId === paneId);
+      listed = true;
+      probe.paneExists = pane != null;
+      probe.agentStatus = pane?.agentStatus ?? null;
+      if (pane?.foregroundCwd) probe.foregroundCwd = pane.foregroundCwd;
     } catch {
-      /* Fall back to session activity when agent.list is unavailable. */
+      /* pane.list unavailable — agent.list is a degraded fallback, not a death signal */
     }
-    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      try {
-        const mtime = (await statAsync(file)).mtimeMs;
-        if (probe.lastActivityMs == null || mtime > probe.lastActivityMs) probe.lastActivityMs = mtime;
-      } catch {
-        /* Session files can disappear during candidate scanning. */
+    try {
+      const a = (await h.client.listAgents()).find((x) => x.paneId === paneId);
+      if (a) {
+        if (!listed) probe.paneExists = true;
+        probe.agentStatus = a.status ?? probe.agentStatus;
+        if (a.foregroundCwd) probe.foregroundCwd = a.foregroundCwd;
       }
+    } catch {
+      /* agent.list is status-only; absence is not death */
+    }
+    for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
+      const stamp = stampOf(file);
+      // Session files can disappear during candidate scanning; a vanished file has no activity.
+      if (!stamp) continue;
+      if (probe.lastActivityMs == null || stamp.mtimeMs > probe.lastActivityMs) probe.lastActivityMs = stamp.mtimeMs;
     }
     return probe;
   }
@@ -119,20 +199,23 @@ export function createSessionIo(h: SessionIoHost): SessionIo {
     paneId: string,
     cwd: string,
     sinceTs: number,
-  ): Promise<{ text: string | null; pendingTool: boolean; activity: boolean }> {
+  ): Promise<SubSessionState> {
     for (const file of await resolveSessionFileCandidates(paneId, cwd)) {
-      const entries = readSessionFile(file);
-      // readSessionFile returns null when the path is missing or unreadable.
-      // herdr often reports a .jsonl path before the worker creates the file;
-      // waitAgent(idle) then returns immediately and this path used to throw
+      const stamp = stampOf(file);
+      // A missing or vanished path is skipped: herdr often reports a .jsonl path before the worker
+      // creates the file, and waitAgent(idle) returns immediately, which used to throw
       // `Cannot read properties of null (reading 'length')` (session 01a055c5).
+      if (!stamp) continue;
+      const cached = stateCache.get(file, stamp, sinceTs);
+      if (cached) return cached;
+      const entries = readSessionFile(file);
+      // An empty/unparsable file has no state to cache; the next candidate may still have one.
       if (!entries?.length) continue;
-      const r = lastAssistantText(entries, { sinceTs });
-      if (r?.text) return { text: r.text, pendingTool: false, activity: true };
-      if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true };
-      if (hasAssistantAfter(entries, sinceTs)) return { text: null, pendingTool: false, activity: true };
+      const state = deriveSubSessionState(entries, sinceTs);
+      stateCache.set(file, stamp, sinceTs, state);
+      return state;
     }
-    return { text: null, pendingTool: false, activity: false };
+    return { text: null, pendingTool: false, activity: false, turnEnded: false };
   }
 
   return {

package/src/subagent-spawn.ts

@@ -5,8 +5,15 @@
  * races (D26 mutex) and D86 worktree grouping belong in one adapter.
  */
 import type { HerdrClientLike } from './herdr-client.ts';
-import { pingUntilReady, pipeNameCandidates } from './pipe-channel.ts';
+import { pipeNameCandidates, pipeRequest } from './pipe-channel.ts';
 import { runtimePolicy } from './runtime-policy.ts';
+import {
+  READY_LIVENESS_SAMPLE_MS,
+  READY_TAIL_CHARS,
+  planReadyAttempt,
+  readyFailureText,
+  type ReadyFailure,
+} from './subagent-ready.ts';
 import {
   Semaphore,
   buildLaunchLine,
@@ -17,7 +24,8 @@ import {
   type TabPlacementPlan,
   type WorktreeZone,
 } from './subagent-core.ts';
-import { parseShapeTree, pickGridSplit } from './core/grid-shape.ts';
+import { parseShapeTree, pickGridSplit, type PaneCell } from './core/grid-shape.ts';
+import { fromShapeTree, planSpawnSplitRatio, type LayoutNode } from './core/heat-plan.ts';
 import type { GitIo } from './subagent-git-io.ts';
 
 export interface SpawnEnv {
@@ -37,8 +45,15 @@ export interface SpawnerHost {
   env: SpawnEnv | null;
   runtime: SpawnRuntime;
   git: GitIo;
+  /** Test override. Production reads `runtimePolicy.readinessTimeoutMs`. */
+  readinessTimeoutMs?: number;
 }
 
+/** A14: readiness outcome — failures explain themselves instead of collapsing into `false`. */
+export type ReadyOutcome =
+  | { ok: true }
+  | { ok: false; failure: ReadyFailure; message: string };
+
 export interface Spawner {
   spawnPaneInTaskTab(
     placement: { desiredTab?: string | null; description: string; zone?: WorktreeZone },
@@ -48,14 +63,14 @@ export interface Spawner {
   ): Promise<{ tabId: string; paneId: string; tabName: string }>;
   launchLine(resumeFile?: string | null, roleModel?: string | null, approve?: boolean): string;
   approveFor(cwd: string, masterCwd: string): Promise<boolean>;
-  waitSubReady(cwd: string, paneId: string): Promise<boolean>;
+  waitSubReady(cwd: string, paneId: string): Promise<ReadyOutcome>;
   liveTabs(): Promise<Array<{ tabName: string; tabId: string }>>;
   findExistingPane(sessionFile: string | null): Promise<{ paneId: string; tabId: string } | null>;
 }
 
 export function createSpawner(h: SpawnerHost): Spawner {
   const tabMutex = new Semaphore(1);
-  const readyTimeoutMs = runtimePolicy.readinessTimeoutMs;
+  const readyTimeoutMs = h.readinessTimeoutMs ?? runtimePolicy.readinessTimeoutMs;
 
   async function liveTabs(): Promise<Array<{ tabName: string; tabId: string }>> {
     try {
@@ -78,8 +93,107 @@ export function createSpawner(h: SpawnerHost): Spawner {
     return zone.zone === 'worktree';
   }
 
-  async function waitSubReady(cwd: string, paneId: string): Promise<boolean> {
-    return pingUntilReady(pipeNameCandidates(cwd, paneId), readyTimeoutMs);
+  /**
+   * A14: wait for the child's pipe with backoff, and give up early when the pane
+   * itself is gone from pane.list. Screen tail is sampled while the pane exists
+   * so a crash that leaves a shell still explains itself on timeout.
+   */
+  async function waitSubReady(cwd: string, paneId: string): Promise<ReadyOutcome> {
+    const names = pipeNameCandidates(cwd, paneId);
+    const startedAt = Date.now();
+    let attempt = 0;
+    let lastProbeAt = 0;
+    let alive: boolean | null = null;
+    let lastStatus: string | null = null;
+    let tail: string | null = null;
+
+    while (true) {
+      const now = Date.now();
+      const elapsedMs = now - startedAt;
+      // Liveness/agent sampling is much more expensive than a ping, so it runs on its own cadence.
+      if (now - lastProbeAt >= READY_LIVENESS_SAMPLE_MS || attempt === 0) {
+        lastProbeAt = now;
+        const probe = await probeChildPane(paneId);
+        alive = probe.alive;
+        lastStatus = probe.status;
+        if (probe.tail) tail = probe.tail;
+      }
+      const pinged = await pingAnyName(names);
+      const plan = planReadyAttempt({ elapsedMs, attempt, timeoutMs: readyTimeoutMs, alive, ready: pinged });
+      if (plan.kind === 'ready') return { ok: true };
+      if (plan.kind === 'give-up') {
+        let explainHint: string | null = null;
+        if (h.client.available) {
+          try {
+            const diag = await h.client.agentExplain(paneId);
+            if (diag && typeof diag === 'object') {
+              const explainObj = ((diag.explain ?? diag) as Record<string, unknown>);
+              const parts: string[] = [];
+              if (explainObj.skip_state_reason) parts.push(`skip reason: ${String(explainObj.skip_state_reason)}`);
+              if (explainObj.screen_detection_skip_reason) parts.push(`screen rule bypassed: ${String(explainObj.screen_detection_skip_reason)}`);
+              if (explainObj.matched_rule) parts.push(`matched rule: ${String(explainObj.matched_rule)}`);
+              if (explainObj.idle_fallback_reason) parts.push(`idle fallback: ${String(explainObj.idle_fallback_reason)}`);
+              if (parts.length > 0) explainHint = `Herdr detection diagnosis: ${parts.join('; ')}`;
+            }
+          } catch {
+            /* Best effort diagnostics; failures never mask the root error. */
+          }
+        }
+        const defaultHint = plan.reason === 'timeout' && lastStatus === 'working'
+          ? 'Tip: pass run_in_background to avoid blocking the master turn while the worker boots.'
+          : null;
+        const hint = [explainHint, defaultHint].filter(Boolean).join('\n') || null;
+        const failure: ReadyFailure = {
+          paneId,
+          reason: plan.reason,
+          elapsedMs: Math.max(elapsedMs, 1),
+          timeoutMs: readyTimeoutMs,
+          lastStatus,
+          tail,
+          hint,
+        };
+        return { ok: false, failure, message: readyFailureText(failure) };
+      }
+      attempt += 1;
+      await new Promise((r) => setTimeout(r, plan.delayMs));
+    }
+  }
+
+  /** One ping round over every candidate pipe name (mixed-version peers register different names). */
+  async function pingAnyName(names: readonly string[]): Promise<boolean> {
+    for (const name of names) {
+      try {
+        const res = await pipeRequest(name, { type: 'ping', id: `ping-${Date.now()}` }, 3000);
+        if (res.type === 'ok') return true;
+      } catch {
+        /* not ready on this name */
+      }
+    }
+    return false;
+  }
+
+  /** Pane liveness + last visible output; socket failures degrade to "unknown" rather than "dead". */
+  async function probeChildPane(paneId: string): Promise<{ alive: boolean | null; status: string | null; tail: string | null }> {
+    let alive: boolean | null = null;
+    let status: string | null = null;
+    try {
+      // pane.list includes unknown shells; agent.list does not (herdr 0.9.1 live probe).
+      // A fresh split is absent from agent.list until pi is identified — that is boot, not death.
+      const panes = await h.client.listPanes();
+      const pane = panes.find((p) => p.paneId === paneId);
+      alive = pane != null;
+      status = pane?.agentStatus ?? null;
+    } catch {
+      /* keep null: an unreachable socket must not be read as a dead child */
+    }
+    let tail: string | null = null;
+    try {
+      const read = await h.client.readPane(paneId, { stripAnsi: true });
+      if (read.text) tail = read.text.slice(-READY_TAIL_CHARS);
+    } catch {
+      /* recycled pane or socket blip — caller keeps the last cached tail */
+    }
+    return { alive, status, tail };
   }
 
   async function spawnPaneInTaskTab(
@@ -105,20 +219,51 @@ export function createSpawner(h: SpawnerHost): Spawner {
           allPanes.filter((p) => p.tabId === plan.tabId && p.agentStatus === 'unknown').map((p) => p.paneId),
         );
         let pick: { targetPaneId: string; direction: 'right' | 'down' } | null = null;
+        let heatRoot: LayoutNode | null = null;
+        let focusPaneId: string | null = null;
+        let zoomed = false;
         try {
           const snapshot = await h.client.exportLayout({ tabId: plan.tabId });
           const tree = snapshot?.root ? parseShapeTree(snapshot.root) : null;
-          if (tree) pick = pickGridSplit(tree, { exclude });
+          if (tree) {
+            heatRoot = fromShapeTree(tree);
+            focusPaneId = snapshot?.focusedPaneId ?? null;
+            zoomed = snapshot?.zoomed === true;
+            let cells: PaneCell[] | undefined;
+            try {
+              const live = await h.client.paneLayout({ paneId: allPanes.find((p) => p.tabId === plan.tabId)?.paneId });
+              if (live?.panes.length) {
+                cells = live.panes.map((p) => ({ id: p.paneId, x: p.x, y: p.y, w: p.w, h: p.h }));
+              }
+            } catch { /* pane.layout missing → 200×50 model */ }
+            pick = pickGridSplit(tree, { exclude, cells });
+          }
         } catch { /* layout export failure → legacy anchor split */ }
         const anchorPaneId = pick?.targetPaneId
           ?? allPanes.find((p) => p.tabId === plan.tabId && p.agentStatus !== 'unknown')?.paneId
           ?? allPanes.find((p) => p.tabId === plan.tabId)?.paneId;
         if (anchorPaneId) {
+          const direction = pick?.direction ?? 'down';
+          const statuses: Record<string, string> = {};
+          for (const p of allPanes) {
+            if (p.tabId === plan.tabId) statuses[p.paneId] = p.agentStatus;
+          }
+          const ratio = heatRoot && !zoomed
+            ? planSpawnSplitRatio({
+              root: heatRoot,
+              targetPaneId: anchorPaneId,
+              focusPaneId: focusPaneId ?? anchorPaneId,
+              direction,
+              statuses,
+            })
+            : null;
           const paneId = await h.client.splitPane({
-            direction: pick?.direction ?? 'down',
+            direction,
             cwd,
             env: envOver,
             targetPaneId: anchorPaneId,
+            focus: false,
+            ...(ratio != null ? { ratio } : {}),
           });
           await h.client.sendPaneText(paneId, launch);
           return { tabId: plan.tabId, paneId, tabName: plan.tabName };

package/src/swallow.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+
+export interface SwallowedError {
+  /** Short, 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);
+  }
+}
+
+/** 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.
+ */
+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];
+}
+
+/** 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.
+ */
+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,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;
@@ -61,6 +89,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 {
@@ -300,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) {
@@ -316,13 +386,14 @@ 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;
@@ -339,12 +410,13 @@ 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 {
-  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). */