pi-pier 0.2.6 → 0.3.0

package/src/lock-core.ts

@@ -65,21 +65,105 @@ export function writePathsOfTool(toolName: string, input: unknown): string[] {
   return typeof p === 'string' && p.trim() ? [p] : [];
 }
 
+/**
+ * B7: write-locks only see the write/edit tools, so a `bash` command that redirects into a file
+ * bypasses the beacon entirely (`> file`, `>> file`, `tee file`, `sed -i`, `truncate -s 0`).
+ * We do not try to parse shell: this extracts the *obvious* redirect/tee targets so the lock layer
+ * can raise a soft warning, and the limitation stays documented rather than implied.
+ *
+ * Pure and conservative: unknown syntax yields no paths, and a failure here must never block.
+ */
+export function bashWriteTargets(command: unknown): string[] {
+  if (typeof command !== 'string' || command.trim() === '') return [];
+  const found: string[] = [];
+  // Quoted or bare targets; stops at shell metacharacters. Deliberately ignores process substitution.
+  const target = String.raw`(?:'([^']+)'|"([^"]+)"|([^\s;|&<>()]+))`;
+  const patterns = [
+    new RegExp(String.raw`(?:^|[^0-9>])>>?\s*` + target, 'g'),      // > file, >> file
+    new RegExp(String.raw`\btee\s+(?:-a\s+)?` + target, 'g'),        // tee [-a] file
+    new RegExp(String.raw`\btruncate\s+-s\s*0\s+` + target, 'g'),   // truncate -s 0 file
+  ];
+  for (const re of patterns) {
+    for (const m of command.matchAll(re)) {
+      const path = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+      const quoted = m[1] !== undefined || m[2] !== undefined;
+      if (isObviousPath(path, quoted)) found.push(path);
+    }
+  }
+  // `sed -i '' 's/a/b/' file`: the first argument is the (possibly empty) backup suffix and the second
+  // the expression, so take the LAST argument as the file rather than guessing the argument order.
+  for (const m of command.matchAll(/\bsed\s+-i[^\s]*\s+([^|;&\n]+)/g)) {
+    const args = splitShellWords(m[1] ?? '');
+    for (let i = args.length - 1; i >= 0; i -= 1) {
+      const candidate = args[i]!;
+      if (candidate.startsWith('-')) continue;
+      if (isObviousPath(candidate)) found.push(candidate);
+      break;
+    }
+  }
+  return [...new Set(found)];
+}
+
+/** Only unquoted, metacharacter-free paths count as "obvious" (anything else is left to the shell). */
+function isObviousPath(path: string, quoted = false): boolean {
+  if (path === '' || path === '/' || path.startsWith('$')) return false;
+  if (/['"`$*?{}()[\]]/.test(path)) return false; // Never a literal path (expansion, glob, nested quotes).
+  return quoted ? true : !/\s/.test(path); // An explicitly quoted target may contain spaces.
+}
+
+/** Whitespace split that keeps quoted segments together and strips their quotes. */
+function splitShellWords(input: string): string[] {
+  const out: string[] = [];
+  const re = /'([^']*)'|"([^"]*)"|(\S+)/g;
+  for (const m of input.matchAll(re)) out.push(m[1] ?? m[2] ?? m[3] ?? '');
+  return out.filter((s) => s !== '');
+}
+
+/** Soft hint shown after a bash call that wrote into a path another pane has locked. */
+export function formatBashLockHint(normPath: string, holders: readonly string[]): string {
+  return `Note: this bash command wrote to ${normPath}, which ${holdersLabel(holders)} is editing. `
+    + `Write-locks only cover the write/edit tools, so this write was not blocked: re-read the file before your next edit.`;
+}
+
 /** Why: Preserve the established compatibility and safety behavior. */
 
-export function findLockConflict(
+/**
+ * Every *other* pane currently holding a beacon for this path (deduped, in list order).
+ * A lock is a beacon rather than a mutex, so several panes can hold the same path.
+ */
+export function findLockHolders(
   agents: readonly LockAgentView[],
   ownPaneId: string,
   normPath: string,
-): { holderPaneId: string } | null {
+): string[] {
   const key = lockTokenKey(normPath);
+  const holders: string[] = [];
   for (const a of agents) {
     const v = a.tokens[key];
     if (typeof v !== 'string' || !v) continue;
     const parsed = parseLockTokenValue(v);
-    if (parsed && parsed.holderPaneId !== ownPaneId) return { holderPaneId: parsed.holderPaneId };
+    if (parsed && parsed.holderPaneId !== ownPaneId && !holders.includes(parsed.holderPaneId)) {
+      holders.push(parsed.holderPaneId);
+    }
   }
-  return null;
+  return holders;
+}
+
+export function findLockConflict(
+  agents: readonly LockAgentView[],
+  ownPaneId: string,
+  normPath: string,
+): { holderPaneId: string } | null {
+  const [first] = findLockHolders(agents, ownPaneId, normPath);
+  return first === undefined ? null : { holderPaneId: first };
+}
+
+/** Where to look for the full holder table: humans use the slash command, agents can read herdr's tokens. */
+export const LOCK_HOLDERS_HINT =
+  'holders: /locks (human view in this pane) · herdr agent list → tokens (agent-readable)';
+
+function holdersLabel(holders: readonly string[]): string {
+  return holders.length === 1 ? `pane ${holders[0]}` : `panes ${holders.join(', ')}`;
 }
 
 /** Why: Preserve the established compatibility and safety behavior. */
@@ -87,8 +171,8 @@ export function findLockConflict(
 export type WriteGuardPlan =
   | { kind: 'skip' }
   | { kind: 'pass'; paths: string[] }
-  | { kind: 'warn'; paths: string[]; holderPaneId: string; warning: string }
-  | { kind: 'block'; paths: string[]; holderPaneId: string; reason: string };
+  | { kind: 'warn'; paths: string[]; holderPaneIds: string[]; warning: string }
+  | { kind: 'block'; paths: string[]; holderPaneIds: string[]; reason: string };
 
 export function planWriteGuard(opts: {
   toolName: string;
@@ -98,25 +182,30 @@ export function planWriteGuard(opts: {
   cwd: string;
   hard: boolean;
 }): WriteGuardPlan {
-  const raw = writePathsOfTool(opts.toolName, opts.input);
+  // B7: bash redirects are invisible to the write tools, so warn (never block) when their obvious
+  // targets collide with a lock beacon held by another pane.
+  const isBash = opts.toolName === 'bash';
+  const raw = isBash
+    ? bashWriteTargets((opts.input as { command?: unknown } | null | undefined)?.command)
+    : writePathsOfTool(opts.toolName, opts.input);
   if (raw.length === 0) return { kind: 'skip' };
   const paths = raw.map((p) => normalizeLockPath(p, opts.cwd));
   for (const norm of paths) {
-    const conflict = findLockConflict(opts.agents, opts.ownPaneId, norm);
-    if (!conflict) continue;
-    if (opts.hard) {
+    const holders = findLockHolders(opts.agents, opts.ownPaneId, norm);
+    if (holders.length === 0) continue;
+    if (opts.hard && !isBash) {
       return {
         kind: 'block',
         paths,
-        holderPaneId: conflict.holderPaneId,
-        reason: `file locked by pane ${conflict.holderPaneId}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing.`,
+        holderPaneIds: holders,
+        reason: `file locked by ${holdersLabel(holders)}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing. ${LOCK_HOLDERS_HINT}`,
       };
     }
     return {
       kind: 'warn',
       paths,
-      holderPaneId: conflict.holderPaneId,
-      warning: formatConflictWarning(norm, conflict.holderPaneId),
+      holderPaneIds: holders,
+      warning: isBash ? formatBashLockHint(norm, holders) : formatConflictWarning(norm, holders),
     };
   }
   return { kind: 'pass', paths };
@@ -136,6 +225,6 @@ export function releaseTokensFor(normPaths: readonly string[]): Record<string, n
   return out;
 }
 
-export function formatConflictWarning(normPath: string, holderPaneId: string): string {
-  return `⚠️ write conflict: ${normPath} is locked by pane ${holderPaneId} (it edited this file and has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes.`;
+export function formatConflictWarning(normPath: string, holders: readonly string[]): string {
+  return `⚠️ write conflict: ${normPath} is locked by ${holdersLabel(holders)} (edited in another pane that has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes. ${LOCK_HOLDERS_HINT}`;
 }

package/src/observation-core.ts

@@ -0,0 +1,248 @@
+/**
+ * D101 ObservationPack Core.
+ *
+ * Pure algorithmic functions for large observation detection, deterministic ID derivation,
+ * complete-line excerpt generation, chunk slicing with UTF-8 safety, and rolling prefix cache
+ * economics.
+ *
+ * No I/O in this core; storage I/O lives in efficiency-store.ts.
+ */
+import { createHash } from 'node:crypto';
+import { TOKEN_ACCOUNT_CACHE_RATIO } from './compact-economics-core.ts';
+import { FAILURE_SIGNAL } from './reducer-core.ts';
+
+export const DEFAULT_THRESHOLD_BYTES = 10 * 1024; // 10KB
+export const DEFAULT_FULL_SENDS = 2;
+export const DEFAULT_EXCERPT_BYTES = 1024;
+export const CHARS_PER_TOKEN = 4;
+export const OBSERVATION_ID_RE = /^obs_[a-f0-9]{24}$/;
+
+/** Marker from Evidence-Preserving Reducer to avoid double packing. */
+export const REDUCER_RECEIPT_PREFIX = 'sol_pi_evidence_receipt_v1';
+
+export function sha256Hex(val: string | Buffer): string {
+  return createHash('sha256').update(val).digest('hex');
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let lines = text.endsWith('\n') ? 0 : 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 0x0a) lines++;
+  }
+  return lines;
+}
+
+export function isObservationId(id: string): boolean {
+  return OBSERVATION_ID_RE.test(id);
+}
+
+export function deriveObservationId(toolName: string, toolCallId: string, contentHash: string): string {
+  const combined = `${toolName}\0${toolCallId}\0${contentHash}`;
+  return `obs_${sha256Hex(combined).slice(0, 24)}`;
+}
+
+export function containsReducerReceipt(text: string): boolean {
+  if (!text.includes(REDUCER_RECEIPT_PREFIX)) return false;
+  return text.split('\n').some((line) => line.trim() === REDUCER_RECEIPT_PREFIX);
+}
+
+export function completeLineExcerpt(text: string, budgetBytes: number, fromEnd: boolean): string {
+  if (budgetBytes <= 0 || text.length === 0) return '';
+
+  if (!fromEnd) {
+    // Head excerpt: candidate never exceeds budgetBytes * 4 chars
+    const candidate = text.slice(0, Math.min(text.length, budgetBytes * 4));
+    let lastEnd = 0;
+    let totalBytes = 0;
+    let searchIndex = 0;
+    while (searchIndex < candidate.length) {
+      const nextNewline = candidate.indexOf('\n', searchIndex);
+      if (nextNewline === -1) break;
+      const lineEnd = nextNewline + 1;
+      const line = candidate.slice(lastEnd, lineEnd);
+      const lineBytes = Buffer.byteLength(line, 'utf8');
+      if (totalBytes + lineBytes > budgetBytes) break;
+      totalBytes += lineBytes;
+      lastEnd = lineEnd;
+      searchIndex = lineEnd;
+    }
+    return candidate.slice(0, lastEnd);
+  } else {
+    // Tail excerpt: candidate never exceeds budgetBytes * 4 chars from end
+    const startOffset = Math.max(0, text.length - budgetBytes * 4);
+    const candidate = text.slice(startOffset);
+    const lines = candidate.split(/(?<=\n)/);
+    const selected: string[] = [];
+    let selectedBytes = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i]!;
+      // If startOffset > 0, the first line of candidate might be partial, skip unless it follows a newline
+      if (i === 0 && startOffset > 0 && text[startOffset - 1] !== '\n') {
+        break;
+      }
+      const lineBytes = Buffer.byteLength(line, 'utf8');
+      if (selectedBytes + lineBytes > budgetBytes) break;
+      selected.unshift(line);
+      selectedBytes += lineBytes;
+    }
+    return selected.join('');
+  }
+}
+
+export interface ObservationPlaceholderInput {
+  id: string;
+  toolName: string;
+  bytes: number;
+  lines: number;
+  tokens: number;
+  text: string;
+  fullSends?: number;
+  excerptBudget?: number;
+  /**
+   * P0-3 (RFC docs/rfc-jev-integration.md §3): a selected middle window that
+   * replaces whichever head/tail half carries fewer failure-signal lines.
+   * Absent (jev off / low confidence / no signal lines) -> byte-identical
+   * legacy head+tail layout.
+   */
+  middle?: { text: string; label: string };
+}
+
+function signalLineCount(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 0;
+  for (const line of text.split('\n')) {
+    if (FAILURE_SIGNAL.test(line)) count++;
+  }
+  return count;
+}
+
+export function formatObservationPlaceholder(input: ObservationPlaceholderInput): string {
+  const fullSends = input.fullSends ?? DEFAULT_FULL_SENDS;
+  const excerptBudget = input.excerptBudget ?? DEFAULT_EXCERPT_BYTES;
+  const headBudget = Math.floor(excerptBudget / 2);
+  const tailBudget = excerptBudget - headBudget;
+
+  let head = completeLineExcerpt(input.text, headBudget, false);
+  let tail = completeLineExcerpt(input.text, tailBudget, true);
+  let headLabel = `[first complete lines, up to ${headBudget} bytes]`;
+  let tailLabel = `[middle omitted; last complete lines, up to ${tailBudget} bytes]`;
+
+  if (input.middle) {
+    // Fewer signal lines loses its slot; ties replace head because the tail
+    // half usually carries the log's final summary.
+    if (signalLineCount(tail) < signalLineCount(head)) {
+      tail = completeLineExcerpt(input.middle.text, tailBudget, false);
+      tailLabel = `[middle omitted; selected excerpt — ${input.middle.label}, up to ${tailBudget} bytes]`;
+    } else {
+      head = completeLineExcerpt(input.middle.text, headBudget, false);
+      headLabel = `[selected excerpt — ${input.middle.label}, up to ${headBudget} bytes]`;
+    }
+  }
+
+  return [
+    `[large tool result replaced after its first ${fullSends} provider requests]`,
+    `id: ${input.id}`,
+    `tool: ${input.toolName}`,
+    `original_bytes: ${input.bytes}`,
+    `original_lines: ${input.lines}`,
+    `estimated_tokens: ${input.tokens}`,
+    `retrieve: call obs_recall with {"id":"${input.id}","offset":0}; continue with returned next_offset`,
+    headLabel,
+    head,
+    tailLabel,
+    tail,
+    `[${input.bytes} original bytes omitted; recall via obs_recall]`,
+  ].join('\n');
+}
+
+export interface RecallSliceResult {
+  text: string;
+  bytes: number;
+  lines: number;
+  nextOffset: number;
+  eof: boolean;
+}
+
+/**
+ * Trims multi-byte UTF-8 sequence from buffer boundary if cut mid-character.
+ */
+export function trimUtf8End(buffer: Buffer, limit: number): number {
+  let end = limit;
+  while (end > 0 && end < buffer.length && ((buffer[end] ?? 0) & 0xc0) === 0x80) {
+    end -= 1;
+  }
+  return end;
+}
+
+/**
+ * Slices a memory buffer safely at byte offsets without cutting UTF-8 characters.
+ */
+export function sliceBufferChunk(
+  buf: Buffer,
+  offset: number,
+  limits: { maxBytes: number; maxLines: number },
+): RecallSliceResult {
+  if (offset >= buf.length) {
+    return { text: '', bytes: 0, lines: 0, nextOffset: buf.length, eof: true };
+  }
+
+  const available = buf.length - offset;
+  let end = Math.min(available, limits.maxBytes);
+  let newlineCount = 0;
+
+  for (let i = 0; i < end; i++) {
+    if (buf[offset + i] === 0x0a) {
+      newlineCount++;
+      if (newlineCount === limits.maxLines) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+
+  const trimmedEnd = trimUtf8End(buf.subarray(offset), end);
+  const chunkBuf = buf.subarray(offset, offset + trimmedEnd);
+  const text = chunkBuf.toString('utf8');
+  const bytes = chunkBuf.length;
+  const lines = countLines(text);
+  const nextOffset = offset + bytes;
+  const eof = nextOffset >= buf.length;
+
+  return { text, bytes, lines, nextOffset, eof };
+}
+
+/**
+ * Evaluates whether replacing an earlier message with a placeholder is profitable
+ * under rolling prefix cache models.
+ *
+ * `cacheWriteReadRatio` must already be resolved by the caller via
+ * `resolveCacheRatioFromCost` (same value OCC uses). It used to coerce
+ * `'auto'|null` to a hardcoded 12.5 here, which silently diverged from OCC's
+ * resolution and made OBS under-pack on implicit-cache models (2026-09-17
+ * review: 20/72 packs deferred to sendCount 3–175).
+ */
+export function shouldPackForCache(opts: {
+  removedTokens: number;
+  tailTokensAfter: number;
+  expectedRemainingRequests: number;
+  cacheWriteReadRatio: number | null;
+}): boolean {
+  if (opts.removedTokens <= 0) return false;
+  const ratio = opts.cacheWriteReadRatio ?? TOKEN_ACCOUNT_CACHE_RATIO;
+
+  if (ratio <= 1.0) {
+    return true; // No incremental write cost over reads
+  }
+
+  const incrementalRatio = ratio - 1.0;
+  const remaining = Math.max(1, opts.expectedRemainingRequests);
+  const benefitTokens = opts.removedTokens * remaining;
+  const costTokens = opts.tailTokensAfter * incrementalRatio;
+
+  return benefitTokens > costTokens;
+}

package/src/pier-options.ts

@@ -0,0 +1,96 @@
+/**
+ * B10: environment naming. Two prefixes grew side by side — `PI_HERDR_*` (mostly older tuning knobs)
+ * and `PIER_*` (newer ones). Telling them apart by memory is impossible, so this module fixes one
+ * rule and enforces it in code:
+ *
+ *  - `PIER_*` is the canonical namespace for *pier options* (timeouts, windows, toggles). It reads
+ *    the historical `PI_HERDR_*` spelling as a fallback alias, so existing shells keep working.
+ *  - `PI_HERDR_SUBAGENT`, `PI_HERDR_ROLE_MANIFEST`, `PI_HERDR_TUI`, `PI_HERDR_META_KEY` stay as they
+ *    are: those are *contracts* handed to the child process by pier itself (or read by pi/herdr), and
+ *    renaming them would split running workers from their parent.
+ *
+ * `pierOption()` is the single reader; `pierConfigCatalog()` feeds `/pier-config` so the knobs are
+ * discoverable in one place instead of only by reading the source.
+ */
+export interface OptionSpec {
+  /** Canonical name. */
+  readonly name: string;
+  /** Historical `PI_HERDR_*` spelling still accepted. */
+  readonly legacy?: string;
+  /** Default when neither name is set. */
+  readonly fallback: string;
+  readonly description: string;
+}
+
+/** Every pier option, with its alias and default. Keep in sync with `runtimePolicy`/config readers. */
+export const PIER_OPTIONS: readonly OptionSpec[] = [
+  // Numeric fallbacks MUST equal runtime-policy.ts (guarded by test/pier-options.test.ts): the table is
+  // what `/pier-config doctor` shows, so a hand-typed number here is a documented lie.
+  { name: 'PIER_GIT_TIMEOUT_MS', legacy: 'PI_HERDR_GIT_TIMEOUT_MS', fallback: '10000', description: 'git command timeout (worktree/status batches)' },
+  { name: 'PIER_SUBAGENT_TIMEOUT_MS', legacy: 'PI_HERDR_SUBAGENT_TIMEOUT_MS', fallback: '600000', description: 'subagent inactivity budget before forced termination' },
+  { name: 'PIER_READY_TIMEOUT_MS', legacy: 'PI_HERDR_READY_TIMEOUT_MS', fallback: '90000', description: 'how long to wait for a spawned pane to open its pipe' },
+  { name: 'PIER_OBSERVATION_WINDOW_MS', legacy: 'PI_HERDR_OBSERVATION_WINDOW_MS', fallback: '30000', description: 'observation window before a subagent is called settled' },
+  { name: 'PIER_POLL_INTERVAL_MS', legacy: 'PI_HERDR_POLL_INTERVAL_MS', fallback: '30000', description: 'subagent poll cadence' },
+  { name: 'PIER_GC_TICK_MS', legacy: 'PI_HERDR_GC_TICK_MS', fallback: '30000', description: 'idle GC sweep cadence (panes/worktrees)' },
+  { name: 'PIER_FOCUS_POLL_MS', fallback: '1500', description: 'pane-focus sampling cadence for the heat layout (0 disables; 0.9.1+ defaults to 0)' },
+  { name: 'PIER_TERMINAL_PROMPT', legacy: 'PI_HERDR_TERMINAL_PROMPT', fallback: '(auto from $SHELL)', description: 'prompt strategy for terminal readiness: bash|zsh|powershell|pwsh' },
+  { name: 'PIER_SLIM_FRAME', legacy: 'PI_HERDR_SLIM_FRAME', fallback: '1', description: 'mutation frame around todo-tool cards (0 disables)' },
+  { name: 'PIER_TRACE', legacy: 'PI_HERDR_TRACE', fallback: '', description: 'write diagnostics (renderers, swallowed errors) to stderr' },
+  { name: 'PIER_TERM_IDLE_MS', legacy: 'PI_HERDR_TERM_IDLE_MS', fallback: '1800000', description: 'idle time before pier nudges about an open terminal' },
+  { name: 'PIER_TERM_GRACE_MS', legacy: 'PI_HERDR_TERM_GRACE_MS', fallback: '30000', description: 'settle grace before the terminal idle nudge' },
+  { name: 'PIER_TERM_READ_MAX', legacy: 'PI_HERDR_TERM_READ_MAX', fallback: '8000', description: 'characters returned per terminal read' },
+  { name: 'PIER_TODO_GRACE_MS', legacy: 'PI_HERDR_TODO_GRACE_MS', fallback: '30000', description: 'settle grace before the unfinished-todo reminder' },
+  { name: 'PIER_HMR', legacy: 'PI_HERDR_HMR', fallback: '', description: 'dev: enable the cordis HMR boundary (requires --expose-internals)' },
+  { name: 'PIER_SETTLEMENT_WINDOW_MS', legacy: 'PI_HERDR_SETTLEMENT_WINDOW_MS', fallback: '60000', description: 'settlement notice window / machine-inject grace / takeover idle' },
+  { name: 'PIER_FOREGROUND_PATIENCE_MS', legacy: 'PI_HERDR_FOREGROUND_PATIENCE_MS', fallback: '300000', description: 'foreground patience before demoting a subagent to background' },
+  { name: 'PIER_SESSION_TTL_SECONDS', legacy: 'PI_HERDR_SESSION_TTL_SECONDS', fallback: '600', description: 'session retention after a subagent exits, before GC' },
+  { name: 'PIER_ISOLATE_SWEEP_ORPHANS', legacy: 'PI_HERDR_ISOLATE_SWEEP_ORPHANS', fallback: '', description: 'opt-in sweeping of isolate worktrees this session never registered' },
+];
+
+/**
+ * Read a pier option: canonical name first, then the legacy alias, then the fallback.
+ * An empty string counts as unset for both names (shells export empty vars easily).
+ */
+export function pierOption(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const spec = PIER_OPTIONS.find((o) => o.name === name);
+  const legacy = spec?.legacy;
+  for (const key of [name, legacy]) {
+    if (!key) continue;
+    const raw = env[key];
+    if (typeof raw === 'string' && raw.trim() !== '') return raw;
+  }
+  return undefined;
+}
+
+/**
+ * Human-readable option table for `/pier-config doctor`, one line per option:
+ * `NAME = value (source) — description`. Legacy env names are called out so a stale export is visible.
+ */
+export function formatOptionRows(env: NodeJS.ProcessEnv = process.env): string[] {
+  return pierOptionRows(env).map((row) => {
+    const source = row.source === 'env' ? 'env' : row.source === 'legacy-env' ? 'env (legacy name)' : 'default';
+    return `  ${row.name} = ${row.value}  (${source})  — ${row.description}`;
+  });
+}
+
+/** `/pier-config` catalog rows: name, effective value and where it came from. */
+export function pierOptionRows(env: NodeJS.ProcessEnv = process.env): Array<{
+  name: string;
+  value: string;
+  source: 'env' | 'legacy-env' | 'default';
+  description: string;
+}> {
+  return PIER_OPTIONS.map((spec) => {
+    const own = typeof env[spec.name] === 'string' && env[spec.name]!.trim() !== '';
+    if (own) return { name: spec.name, value: String(env[spec.name]), source: 'env' as const, description: spec.description };
+    const legacyRaw = spec.legacy ? env[spec.legacy] : undefined;
+    const viaLegacy = typeof legacyRaw === 'string' && legacyRaw.trim() !== '';
+    if (viaLegacy) {
+      return { name: spec.name, value: String(legacyRaw), source: 'legacy-env' as const, description: spec.description };
+    }
+    return { name: spec.name, value: spec.fallback, source: 'default' as const, description: spec.description };
+  });
+}

package/src/pipe-channel.ts

@@ -12,6 +12,7 @@
  * performs pi injection in the server callback.
  */
 import * as net from 'node:net';
+import * as fs from 'node:fs';
 import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
 
 function encodePaneId(paneId: string): string {
@@ -64,6 +65,14 @@ export type PipeResponse =
   | { type: 'ok'; id: string; detail?: string }
   | { type: 'error'; id: string; message: string };
 
+/**
+ * Response side of the protocol (`ok` / `error`). Requests never use these tags, so this is a sound
+ * discriminator for narrowing a parsed line at the answering end.
+ */
+export function isPipeResponse(value: PipeRequest | PipeResponse): value is PipeResponse {
+  return value.type === 'ok' || value.type === 'error';
+}
+
 /** Parse one JSON line, returning null for malformed input. */
 export function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
   const t = (line ?? '').trim();
@@ -110,7 +119,7 @@ export function pipeRequest(
       settled = true;
       sock.destroy();
       const parsed = parsePipeLine(buf.slice(0, i));
-      if (!parsed) {
+      if (!parsed || !isPipeResponse(parsed)) {
         reject(new Error(`pipe ${pipeName}: bad response frame`));
         return;
       }
@@ -123,6 +132,13 @@ export function pipeRequest(
         reject(err);
       }
     });
+    sock.on('close', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(`pipe ${pipeName}: connection closed`));
+      }
+    });
   });
 }
 
@@ -178,7 +194,21 @@ export type PipeMessageHandler = (req: PipeRequest) => Promise<PipeResponse>;
 export function startPipeServer(
   pipeName: string,
   handler: PipeMessageHandler,
+  onError?: (err: Error) => void,
 ): net.Server {
+  const socketPath = pipePathFor(pipeName);
+  // Why: On POSIX, a crash or ungraceful shutdown leaves the UNIX domain socket file behind.
+  // Subsequent listen calls fail with EADDRINUSE unless the stale socket is unlinked before bind.
+  // Windows named pipes live in kernel namespace (\\.\pipe\...) and require no unlinking.
+  // Best-effort on purpose: if the path cannot be removed (EACCES/EISDIR/ENAMETOOLONG) the
+  // subsequent listen reports the real failure through onError instead of a synchronous throw here.
+  if (process.platform !== 'win32') {
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      /* see above: listen surfaces the actionable error */
+    }
+  }
   const server = net.createServer((sock) => {
     sock.setEncoding('utf8');
     let buf = '';
@@ -188,11 +218,12 @@ export function startPipeServer(
       if (i < 0) return;
       const line = buf.slice(0, i);
       buf = buf.slice(i + 1);
-      const req = parsePipeLine(line);
-      if (!req) {
+      const parsedLine = parsePipeLine(line);
+      if (!parsedLine || isPipeResponse(parsedLine)) {
         sock.end(JSON.stringify({ type: 'error', id: '', message: 'bad frame' }) + '\n');
         return;
       }
+      const req: PipeRequest = parsedLine;
       void handler(req)
         .then((res) => {
           sock.end(JSON.stringify(res) + '\n');
@@ -209,9 +240,23 @@ export function startPipeServer(
       /* client disconnect: silent */
     });
   });
-  server.on('error', () => {
-    /* address in use: caller observes listen errors */
-  });
-  server.listen(pipePathFor(pipeName));
+  if (onError) {
+    server.on('error', onError);
+  } else {
+    // Always attach a listener: an EventEmitter 'error' event with no listener throws and would
+    // take the whole extension host down on a transient listen failure (EADDRINUSE/ENOTDIR).
+    // Callers that care pass onError to make the failure observable (F04).
+    server.on('error', () => { /* swallowed by design; pass onError to observe */ });
+  }
+  if (process.platform !== 'win32') {
+    server.on('close', () => {
+      try {
+        fs.unlinkSync(socketPath);
+      } catch {
+        /* best effort */
+      }
+    });
+  }
+  server.listen(socketPath);
   return server;
 }