pi-pier 0.2.7 → 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

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ *
+ * `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; 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 {
+  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, default and bounds. */
+export const PIER_OPTIONS: readonly OptionSpec[] = [
+  { 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 (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_ISOLATE_SWEEP_ORPHANS', legacy: 'PI_HERDR_ISOLATE_SWEEP_ORPHANS', fallback: '', description: 'opt-in sweeping of isolate worktrees this session never registered' },
+];
+
+/** 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);
+  for (const key of [name, spec?.legacy]) {
+    if (!key) continue;
+    const raw = env[key];
+    if (typeof raw === 'string' && raw.trim() !== '') return raw;
+  }
+  return undefined;
+}
+
+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() !== '';
+    const legacyRaw = spec.legacy ? env[spec.legacy] : undefined;
+    const viaLegacy = typeof legacyRaw === 'string' && legacyRaw.trim() !== '';
+    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,17 +1,17 @@
 /**
- * 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';
 import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
 
 function encodePaneId(paneId: string): string {
@@ -51,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';
@@ -64,23 +71,25 @@ export type PipeResponse =
   | { type: 'ok'; id: string; detail?: string }
   | { type: 'error'; id: string; message: string };
 
-/** Parse one JSON line, returning null for malformed input. */
-export function parsePipeLine(line: string): PipeRequest | PipeResponse | null {
+/** 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';
+}
+
+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,
@@ -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,12 +132,16 @@ export function pipeRequest(
         reject(err);
       }
     });
+    sock.on('close', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(`pipe ${pipeName}: connection closed`));
+      }
+    });
   });
 }
 
-/**
- * Try new then legacy pipe names so a new client can still reach an old server.
- */
 export async function pipeRequestTo(
   cwd: string,
   paneId: string,
@@ -147,38 +160,25 @@ 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);
+  // 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);
+    } catch {
+      /* see above: listen surfaces the actionable error */
+    }
+  }
   const server = net.createServer((sock) => {
     sock.setEncoding('utf8');
     let buf = '';
@@ -188,11 +188,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 +210,21 @@ 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' 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') {
+    server.on('close', () => {
+      try {
+        fs.unlinkSync(socketPath);
+      } catch {
+      }
+    });
+  }
+  server.listen(socketPath);
   return server;
 }

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,15 +70,16 @@ 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,
-  opts: { exclude?: ReadonlySet<string>; width?: number; height?: number } = {},
+  opts: { exclude?: ReadonlySet<string>; width?: number; height?: number; cells?: PaneCell[] } = {},
 ): { targetPaneId: string; direction: 'right' | 'down' } | null {
-  const cells = paneCells(root, opts.width ?? 200, opts.height ?? 50)
+  const cells = (opts.cells && opts.cells.length > 0
+    ? opts.cells
+    : paneCells(root, opts.width ?? 200, opts.height ?? 50))
     .filter((c) => !opts.exclude?.has(c.id));
   if (cells.length === 0) return null;
   let best = cells[0];