pi-pier 0.3.0 → 0.3.1

package/src/pi-surface.ts

@@ -1,13 +1,11 @@
 /**
  * Proxy the pi ExtensionAPI registration surface (D79).
  *
- * pi exposes registration without unregister APIs: tools overwrite by name, but event
- * listeners accumulate. HMR therefore needs tombstoned, generation-scoped wrappers so
- * old listeners become inert while the latest generation remains active.
- *
- * Because HMR emits reload after mounting the replacement (d87), mounting a key retires
- * older generations immediately. The ledger then collects only generations registered
- * through the reload boundary; explicit disposal retires every generation.
+ * pi 0.86+ `pi.on()` returns an unsubscribe, so event handlers are truly removed when their generation
+ * retires (RFC docs/rfc-pi-0.86-dynamic-tools.md §5). Tools and commands have no unregister API: tools
+ * overwrite by name, so retired generations keep tombstoned wrappers there. HMR emits reload after
+ * mounting the replacement, so mounting a key retires older generations immediately; the ledger then
+ * collects only generations registered through the reload boundary.
  */
 import type { DisposeLedger } from './ledger.ts';
 
@@ -28,6 +26,19 @@ interface Group {
   alive: boolean;
   /** Monotonic mount generation used by the ledger disposer to determine its collection boundary. */
   epoch: number;
+  unsubscribes: Array<() => void>;
+}
+
+/** Flip the tombstone and drain any native unsubscribes; retirement must never throw. */
+function retireGroup(group: Group): void {
+  group.alive = false;
+  for (const off of group.unsubscribes) {
+    try {
+      off();
+    } catch {
+    }
+  }
+  group.unsubscribes.length = 0;
 }
 
 /** Proxy for pi's registration surface (D79); non-registration methods (append/exec/setActiveTools, etc.) pass through raw. */
@@ -51,16 +62,13 @@ export class PiSurface<P extends object> {
     return this.pi;
   }
 
-  /**
-   * Get a module-scoped registration surface. Each call creates a new generation, retiring older
-   * generations for the same key so HMR replacement and manual remounting share one lifecycle.
-   * The ledger registers each key once and registers it again only after its entry is consumed.
-   */
+  /** Get a module-scoped registration surface; each call creates a new generation, retiring older ones
+   *  for the same key. The ledger registers each key once and again only after its entry is consumed. */
   forModule(key: string): ScopedSurface {
     this.epochCounter += 1;
     const epoch = this.epochCounter;
-    for (const g of this.generations.get(key) ?? []) g.alive = false;
-    const group: Group = { alive: true, epoch };
+    for (const g of this.generations.get(key) ?? []) retireGroup(g);
+    const group: Group = { alive: true, epoch, unsubscribes: [] };
     this.generations.set(key, [group]);
     this.groups.set(key, group);
     if (this.ledger && !this.ledgerEntryEpoch.has(key)) {
@@ -72,7 +80,7 @@ export class PiSurface<P extends object> {
           key,
           (this.generations.get(key) ?? []).filter((g) => {
             if (g.epoch <= bound) {
-              g.alive = false;
+              retireGroup(g);
               return false;
             }
             return true;
@@ -94,9 +102,8 @@ export class PiSurface<P extends object> {
         );
       },
       registerCommand: (name, options) => {
-        // pi stores commands as Map<name> (verified in the dist implementation), so same-name
-        // registration replaces safely; the handler tombstone is a symmetry safeguard even though
-        // replacement means the old handler will no longer be called.
+        // pi stores commands as Map<name>, so same-name registration replaces safely; the handler
+        // tombstone is a symmetry safeguard even though the old handler will no longer be called.
         const handler = options.handler as ((...a: unknown[]) => unknown) | undefined;
         const wrapped = handler
           ? (...a: unknown[]) => (group!.alive ? handler(...a) : undefined)
@@ -105,23 +112,28 @@ export class PiSurface<P extends object> {
           .registerCommand?.(name, wrapped ? { ...options, handler: wrapped } : options);
       },
       on: (event, handler) => {
+        // Pass-through while alive, tombstone after retirement; when pi (0.86+) returns an unsubscribe,
+        // retirement also removes the registration so HMR churn cannot grow the dispatch list.
         const wrapped = (...a: unknown[]) => (group!.alive ? handler(...a) : undefined);
-        (this.pi as { on?: (e: string, h: (...a: unknown[]) => unknown) => void }).on?.(event, wrapped);
+        const unsubscribe: unknown = (
+          this.pi as { on?: (e: string, h: (...a: unknown[]) => unknown) => unknown }
+        ).on?.(event, wrapped);
+        if (typeof unsubscribe === 'function') {
+          group.unsubscribes.push(unsubscribe as () => void);
+        }
       },
     };
   }
 
-  /** Retire all generations for a key during explicit disposal; return false when the key is absent. */
   disposeModule(key: string): boolean {
     const had = this.groups.has(key);
-    for (const g of this.generations.get(key) ?? []) g.alive = false;
+    for (const g of this.generations.get(key) ?? []) retireGroup(g);
     this.generations.delete(key);
     this.groups.delete(key);
     this.ledgerEntryEpoch.delete(key);
     return had;
   }
 
-  /** Number of live module groups, for tests and diagnostics. */
   get moduleCount(): number {
     return this.groups.size;
   }

package/src/pier-options.ts

@@ -1,63 +1,71 @@
 /**
- * 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:
+ * B10 environment naming. `PIER_*` is the canonical namespace for *pier options* (timeouts, windows,
+ * toggles); the historical `PI_HERDR_*` spelling stays accepted as a fallback alias.
  *
- *  - `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.
+ * `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.
+ * `pierOption()` is the single reader; this registry is also the single source of the numeric
+ * bounds/defaults behind `runtimePolicy` (runtime-policy.ts) and the `/pier-config` catalog
+ * (config-catalog-core.ts), so a knob cannot mean three different things.
  */
+
+/** RuntimePolicy field fed by an integer option (see runtime-policy.ts). */
+export type PolicyField =
+  | 'subagentTimeoutMs'
+  | 'gcTickMs'
+  | 'pollIntervalMs'
+  | 'settlementWindowMs'
+  | 'observationWindowMs'
+  | 'foregroundPatienceMs'
+  | 'sessionTtlSeconds'
+  | 'gitTimeoutMs'
+  | 'readinessTimeoutMs';
+
 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;
+  /** Integer option: smallest value the readers accept (omitted for string/enum options). */
+  readonly min?: number;
+  /** Integer option read into `RuntimePolicy`. */
+  readonly policy?: PolicyField;
 }
 
-/** Every pier option, with its alias and default. Keep in sync with `runtimePolicy`/config readers. */
+/** Every pier option, with its alias, default and bounds. */
 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_GIT_TIMEOUT_MS', legacy: 'PI_HERDR_GIT_TIMEOUT_MS', fallback: '10000', min: 1, policy: 'gitTimeoutMs', description: 'git command timeout (worktree/status batches)' },
+  { name: 'PIER_SUBAGENT_TIMEOUT_MS', legacy: 'PI_HERDR_SUBAGENT_TIMEOUT_MS', fallback: '600000', min: 1000, policy: 'subagentTimeoutMs', description: 'subagent inactivity budget before forced termination' },
+  { name: 'PIER_READY_TIMEOUT_MS', legacy: 'PI_HERDR_READY_TIMEOUT_MS', fallback: '90000', min: 1000, policy: 'readinessTimeoutMs', description: 'how long to wait for a spawned pane to open its pipe (a dead pane fails fast)' },
+  { name: 'PIER_OBSERVATION_WINDOW_MS', legacy: 'PI_HERDR_OBSERVATION_WINDOW_MS', fallback: '30000', min: 0, policy: 'observationWindowMs', description: 'observation window before a subagent is called settled' },
+  { name: 'PIER_POLL_INTERVAL_MS', legacy: 'PI_HERDR_POLL_INTERVAL_MS', fallback: '30000', min: 1000, policy: 'pollIntervalMs', description: 'subagent poll cadence' },
+  { name: 'PIER_GC_TICK_MS', legacy: 'PI_HERDR_GC_TICK_MS', fallback: '30000', min: 1000, policy: 'gcTickMs', description: 'idle GC sweep cadence (panes/worktrees)' },
+  { name: 'PIER_SETTLEMENT_WINDOW_MS', legacy: 'PI_HERDR_SETTLEMENT_WINDOW_MS', fallback: '60000', min: 0, policy: 'settlementWindowMs', description: 'settlement notice window / machine-inject grace / takeover idle' },
+  { name: 'PIER_FOREGROUND_PATIENCE_MS', legacy: 'PI_HERDR_FOREGROUND_PATIENCE_MS', fallback: '300000', min: 0, policy: 'foregroundPatienceMs', description: 'foreground patience before demoting a subagent to background' },
+  { name: 'PIER_SESSION_TTL_SECONDS', legacy: 'PI_HERDR_SESSION_TTL_SECONDS', fallback: '600', min: 0, policy: 'sessionTtlSeconds', description: 'session retention after a subagent exits, before GC' },
+  { name: 'PIER_FOCUS_POLL_MS', fallback: '1500', min: 0, description: 'pane-focus sampling cadence for the heat layout (0 disables; event-first on herdr 0.9.1+)' },
   { 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_TRACE', legacy: 'PI_HERDR_TRACE', fallback: '', description: 'write diagnostics (renderers, swallowed errors) to stderr (or to this file when it is a path)' },
+  { name: 'PIER_TERM_IDLE_MS', legacy: 'PI_HERDR_TERM_IDLE_MS', fallback: '1800000', min: 1, description: 'idle time before pier nudges about an open terminal (0/NaN falls back to the default)' },
+  { name: 'PIER_TERM_GRACE_MS', legacy: 'PI_HERDR_TERM_GRACE_MS', fallback: '30000', min: 1, description: 'settle grace before the terminal idle nudge (0/NaN falls back to the default)' },
+  { name: 'PIER_TERM_READ_MAX', legacy: 'PI_HERDR_TERM_READ_MAX', fallback: '8000', min: 1, description: 'characters returned per terminal read (0/NaN falls back to the default)' },
+  { name: 'PIER_TODO_GRACE_MS', legacy: 'PI_HERDR_TODO_GRACE_MS', fallback: '30000', min: 1, description: 'settle grace before the unfinished-todo reminder (0/NaN falls back to the default)' },
   { 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).
- */
+/** Canonical name → legacy alias → fallback; an empty string counts as unset for both. */
 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]) {
+  for (const key of [name, spec?.legacy]) {
     if (!key) continue;
     const raw = env[key];
     if (typeof raw === 'string' && raw.trim() !== '') return raw;
@@ -65,18 +73,6 @@ export function pierOption(
   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;
@@ -85,12 +81,20 @@ export function pierOptionRows(env: NodeJS.ProcessEnv = process.env): Array<{
 }> {
   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 };
+    if (own || viaLegacy) {
+      return { name: spec.name, value: String(own ? env[spec.name] : legacyRaw), source: own ? 'env' : 'legacy-env', description: spec.description };
     }
     return { name: spec.name, value: spec.fallback, source: 'default' as const, description: spec.description };
   });
 }
+
+/** `/pier-config doctor` table, 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 === 'default' ? 'default' : row.source === 'env' ? 'env' : 'env (legacy name)';
+    return `  ${row.name} = ${row.value}  (${source})  — ${row.description}`;
+  });
+}

package/src/pipe-channel.ts

@@ -1,15 +1,14 @@
 /**
- * M11 separates the human/machine channels (D45–D47) by having the pi extension
- * create its own Windows named pipe.
+ * M11 separates the human/machine channels (D45–D47) by having the pi extension create its own
+ * Windows named pipe.
  *
  *  - Controller (client): one connection per request, matching the herdr client;
- *  - Child pane (server): when PI_HERDR_SUBAGENT=1, the extension starts a server at
- *    session_start and injects prompt/follow_up through pi.sendUserMessage (visible in TUI);
- *  - Completion data is not sent back; authoritative state lives in herdr, session JSONL,
- *    and history (D47).
+ *  - Child pane (server): when PI_HERDR_SUBAGENT=1, the extension starts a server at session_start
+ *    and injects prompt/follow_up through pi.sendUserMessage (visible in TUI);
+ *  - Completion data is not sent back; authoritative state lives in herdr, session JSONL, and
+ *    history (D47).
  *
- * This file contains only pure transport-layer logic for isolated tests; index.ts
- * performs pi injection in the server callback.
+ * Only pure transport-layer logic here; index.ts performs pi injection in the server callback.
  */
 import * as net from 'node:net';
 import * as fs from 'node:fs';
@@ -52,6 +51,13 @@ export type PipeRequest =
       steer?: boolean;
     }
   | { type: 'interrupt'; id: string }
+  | {
+      /** P0 (RFC §4.4): master switches a worker's role; the worker applies the manifest swap and
+       * replies ok/error. Mixed-version peers answer `unknown type role`, which the master surfaces. */
+      type: 'role';
+      id: string;
+      role: string;
+    }
   | {
       /** D50: fast-path settlement reply from child to requester, with summary and session path for progressive disclosure. */
       type: 'reply';
@@ -65,31 +71,25 @@ 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 {
+/** Response side of the protocol (`ok` / `error`): requests never use these tags, so this is a sound
+ * discriminator when narrowing a parsed line at the answering end. */
+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 {
+function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
   const t = (line ?? '').trim();
   if (!t) return null;
   try {
     const obj = JSON.parse(t);
     if (obj && typeof obj === 'object' && typeof obj.type === 'string') return obj as PipeRequest | PipeResponse;
   } catch {
-    /* Malformed line. */
   }
   return null;
 }
 
-/**
- * One connection, one request: connect → write JSON line → wait for JSON line → close.
- * Timeout / connect failure / bad frame throw (caller retries).
- */
+/** One connection, one request: connect → write JSON line → wait for JSON line → close. Timeout /
+ * connect failure / bad frame throw (caller retries). */
 export function pipeRequest(
   pipeName: string,
   payload: PipeRequest,
@@ -142,9 +142,6 @@ export function pipeRequest(
   });
 }
 
-/**
- * Try new then legacy pipe names so a new client can still reach an old server.
- */
 export async function pipeRequestTo(
   cwd: string,
   paneId: string,
@@ -163,45 +160,18 @@ export async function pipeRequestTo(
   throw lastErr instanceof Error ? lastErr : new Error(`pipe ${names[0] ?? paneId}: unreachable`);
 }
 
-/** Ping with retry (readiness probe). Accepts one name or new+legacy candidates. */
-export async function pingUntilReady(
-  pipeName: string | readonly string[],
-  timeoutMs: number,
-  intervalMs = 1000,
-): Promise<boolean> {
-  const names = typeof pipeName === 'string' ? [pipeName] : pipeName;
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    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 */
-      }
-    }
-    await new Promise((r) => setTimeout(r, intervalMs));
-  }
-  return false;
-}
-
-export type PipeMessageHandler = (req: PipeRequest) => Promise<PipeResponse>;
+type PipeMessageHandler = (req: PipeRequest) => Promise<PipeResponse>;
 
-/**
- * Server: one line in → handler → one line out → close.
- * Returns the server (caller closes it).
- */
+/** Server: one line in → handler → one line out → close. Returns the server (caller closes it). */
 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.
+  // POSIX leaves the UNIX domain socket behind after a crash, and the next listen fails with
+  // EADDRINUSE unless it is unlinked before bind (Windows named pipes need no unlink). Best-effort:
+  // if unlink fails, listen reports the real error through onError.
   if (process.platform !== 'win32') {
     try {
       fs.unlinkSync(socketPath);
@@ -243,9 +213,8 @@ export function startPipeServer(
   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).
+    // Always attach a listener: an EventEmitter 'error' with no listener throws and would take the
+    // whole extension host down on a transient listen failure; pass onError to observe it (F04).
     server.on('error', () => { /* swallowed by design; pass onError to observe */ });
   }
   if (process.platform !== 'win32') {
@@ -253,7 +222,6 @@ export function startPipeServer(
       try {
         fs.unlinkSync(socketPath);
       } catch {
-        /* best effort */
       }
     });
   }

package/src/platform-paths.ts

@@ -2,71 +2,38 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 /**
- * Platform-aware storage and workspace path resolution.
- * 
- * Why: Centralizes platform-specific path logic to support Windows (LOCALAPPDATA),
- * Unix XDG conventions, and testability through injection.
+ * Windows uses LOCALAPPDATA, Linux XDG, macOS keeps `~/.pi` (with XDG override); herdr keeps its
+ * worktrees next to the data dir on Windows/Linux but under `~/.herdr` on macOS. Injectable for tests.
  */
-
 export interface PlatformPaths {
-  /** Base directory for agent sessions and state */
   readonly agentDataDir: string
-  /** Base directory for worktrees */
   readonly worktreeBaseDir: string
-  /** Sessions subdirectory under agent data */
   readonly sessionsDir: string
 }
 
-function getDefaultDataDir(): string {
-  const platform = process.platform
-  
-  if (platform === 'win32') {
-    // Windows: use LOCALAPPDATA or fallback to homedir
-    return process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
-  }
-  
-  // Unix: XDG_DATA_HOME or ~/.local/share on Linux, ~/.local/share on macOS
-  if (platform === 'linux') {
-    return process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
-  }
-  
-  // macOS: use ~/.local/share for consistency, but .pi is acceptable legacy
-  return process.env.XDG_DATA_HOME || join(homedir(), '.pi')
-}
-
-function getDefaultWorktreeDir(): string {
-  const platform = process.platform
-  
-  if (platform === 'win32') {
-    const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
-    return join(localAppData, 'herdr', 'worktrees')
-  }
-  
-  // Unix: use XDG_DATA_HOME or ~/.local/share
-  if (platform === 'linux') {
-    const dataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
-    return join(dataHome, 'herdr', 'worktrees')
-  }
-  
-  // macOS legacy: ~/.herdr/worktrees
-  return join(homedir(), '.herdr', 'worktrees')
+const PLATFORM_DEFAULTS: Record<string, {
+  readonly envVar: string
+  readonly homeFallback: readonly string[]
+  /** macOS keeps worktrees in ~/.herdr instead of under the data dir. */
+  readonly worktreesUnderData: boolean
+}> = {
+  win32: { envVar: 'LOCALAPPDATA', homeFallback: ['AppData', 'Local'], worktreesUnderData: true },
+  linux: { envVar: 'XDG_DATA_HOME', homeFallback: ['.local', 'share'], worktreesUnderData: true },
+  darwin: { envVar: 'XDG_DATA_HOME', homeFallback: ['.pi'], worktreesUnderData: false },
 }
 
 export function createPlatformPaths(overrides?: Partial<PlatformPaths>): PlatformPaths {
-  const defaultAgentDataDir = join(getDefaultDataDir(), 'agent')
-  const agentDataDir = overrides?.agentDataDir || defaultAgentDataDir
-  const sessionsDir = overrides?.sessionsDir || join(agentDataDir, 'sessions')
-  const worktreeBaseDir = overrides?.worktreeBaseDir || getDefaultWorktreeDir()
-  
+  const layout = PLATFORM_DEFAULTS[process.platform] ?? PLATFORM_DEFAULTS.darwin!
+  const dataDir = process.env[layout.envVar] || join(homedir(), ...layout.homeFallback)
+  const agentDataDir = overrides?.agentDataDir || join(dataDir, 'agent')
+
   return {
     agentDataDir,
-    sessionsDir,
-    worktreeBaseDir,
+    sessionsDir: overrides?.sessionsDir || join(agentDataDir, 'sessions'),
+    worktreeBaseDir: overrides?.worktreeBaseDir
+      || (layout.worktreesUnderData ? join(dataDir, 'herdr', 'worktrees') : join(homedir(), '.herdr', 'worktrees')),
   }
 }
 
-/**
- * Singleton platform paths for production use.
- * Tests should inject via createPlatformPaths().
- */
+/** Singleton for production; tests inject via createPlatformPaths(). */
 export const platformPaths = createPlatformPaths()

package/src/{core → plugins}/grid-shape.ts

@@ -1,14 +1,13 @@
 /**
  * D97: Always split the largest cell downward so spawned panes remain full-width strips.
  *
- * Heat reflow narrows unfocused cells, but full-width strips keep the slim-frame title
- * readable on one line. The previous grid topology produced narrow vertical cells whose
- * titles wrapped into unreadable columns. The overlay threshold complements both layouts:
- * new strips cross the row limit, while existing columns cross the column limit.
+ * Heat reflow narrows unfocused cells, but full-width strips keep the slim-frame title readable on
+ * one line. The overlay threshold complements both layouts: new strips cross the row limit, while
+ * existing columns cross the column limit.
  *
- * herdr 0.8.2 defines ratio as the first child's share. Because layout.apply creates a
- * new shell rather than attaching an existing pane, spawn-time incremental splits must
- * establish this topology; heat reflow owns only later sizing.
+ * herdr 0.8.2 defines ratio as the first child's share. Because layout.apply creates a new shell
+ * rather than attaching an existing pane, spawn-time incremental splits must establish this
+ * topology; heat reflow owns only later sizing.
  */
 
 export type ShapeNode =
@@ -71,9 +70,8 @@ export function paneCells(root: ShapeNode, width = 200, height = 50): PaneCell[]
 }
 
 /**
- * Split the largest eligible cell downward; preorder tie-breaking keeps the choice stable.
- * At D97's 200x50 model and ten-pane cap, strips eventually become slim title frames by design.
- * Exclusions protect resident non-agent panes such as the board from worker splits.
+ * Split the largest eligible cell downward; preorder tie-breaking keeps the choice stable, and exclusions
+ * protect resident non-agent panes such as the board from worker splits.
  */
 export function pickGridSplit(
   root: ShapeNode,

package/src/{core → plugins}/heat-plan.ts

@@ -1,35 +1,33 @@
 /**
- * Controlled mirror of workbench heat-layout for spawn-time pane.split ratio.
+ * Controlled mirror of workbench heat-layout for spawn-time pane.split ratio — do NOT merge with
+ * pier-workbench/src/heat-layout.ts (npm pi-pier has no workbench, and the workbench checkout has no
+ * pi-pier). Only planSpawnSplitRatio / simulateSplit / SPAWN_PLACEHOLDER_ID / fromShapeTree / LayoutNode
+ * are the interface; the weights stay in lockstep with packages/pier-workbench/test/heat-grid.test.ts.
  *
- * Cannot import pier-workbench (npm pi-pier has no workbench; workbench user-mode
- * checkout has no pi-pier). Canonical tree shape matches workbench LayoutNode.
- * Lockstep: packages/pier-workbench/test/heat-grid.test.ts.
- *
- * herdr v0.9.1 src/layout.rs split_at: first = original, second = new, ratio = first share.
+ * herdr src/layout.rs split_at: first = original, second = new, ratio = first share.
  */
 import { type ShapeNode } from './grid-shape.ts';
 
 export const SPAWN_PLACEHOLDER_ID = '__pier_new__';
-export const RATIO_FLOOR = 0.10;
-export const FOCUS_SHARE = 0.72;
-export const FOCUS_SHARE_BLOCKED = 0.60;
-export const MAX_AUTO_LAYOUT_PANES = 10;
-export const BLOCKED_WEIGHT = 3;
-export const ASK_WEIGHT = 2.5;
-export const WORKING_WEIGHT = 1.4;
-export const IDLE_WEIGHT = 1;
-export const SLIM_THRESHOLD = 4;
-export const SLIM_FACTOR = 0.6;
+const RATIO_FLOOR = 0.10;
+const FOCUS_SHARE = 0.72;
+const FOCUS_SHARE_BLOCKED = 0.60;
+const MAX_AUTO_LAYOUT_PANES = 10;
+const BLOCKED_WEIGHT = 3;
+const ASK_WEIGHT = 2.5;
+const WORKING_WEIGHT = 1.4;
+const IDLE_WEIGHT = 1;
+const SLIM_THRESHOLD = 4;
+const SLIM_FACTOR = 0.6;
 
 /** Same shape as pier-workbench heat-layout LayoutNode. */
 export type LayoutNode =
   | { type: 'pane'; pane_id: string }
   | { type: 'split'; direction: 'right' | 'down'; ratio: number; first: LayoutNode; second: LayoutNode };
 
-export type AgentStatusMap = Record<string, string>;
-export type AskFlagMap = Record<string, boolean>;
+type AgentStatusMap = Record<string, string>;
+type AskFlagMap = Record<string, boolean>;
 
-/** parseShapeTree (paneId) → LayoutNode (pane_id). */
 export function fromShapeTree(node: ShapeNode): LayoutNode {
   if (node.type === 'pane') return { type: 'pane', pane_id: node.paneId };
   const direction = node.direction === 'down' || node.direction === 'vertical' ? 'down' : 'right';
@@ -42,15 +40,15 @@ export function fromShapeTree(node: ShapeNode): LayoutNode {
   };
 }
 
-export function countPanes(node: LayoutNode): number {
+function countPanes(node: LayoutNode): number {
   return node.type === 'pane' ? 1 : countPanes(node.first) + countPanes(node.second);
 }
 
-export function flattenPanes(node: LayoutNode): string[] {
+function flattenPanes(node: LayoutNode): string[] {
   return node.type === 'pane' ? [node.pane_id] : [...flattenPanes(node.first), ...flattenPanes(node.second)];
 }
 
-export function containsPane(node: LayoutNode, paneId: string): boolean {
+function containsPane(node: LayoutNode, paneId: string): boolean {
   if (node.type === 'pane') return node.pane_id === paneId;
   return containsPane(node.first, paneId) || containsPane(node.second, paneId);
 }