pi-pier 0.2.6 → 0.3.0

package/src/efficiency-config-io.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface PiCompactionSettings {
+  enabled?: boolean;
+  keepRecentTokens?: number;
+}
+
+function readCompactionSettings(filePath: string): PiCompactionSettings {
+  if (!existsSync(filePath)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !('compaction' in parsed)) return {};
+    const compaction = parsed.compaction;
+    if (!compaction || typeof compaction !== 'object') return {};
+    const result: PiCompactionSettings = {};
+    if ('enabled' in compaction && typeof compaction.enabled === 'boolean') result.enabled = compaction.enabled;
+    if ('keepRecentTokens' in compaction && typeof compaction.keepRecentTokens === 'number') {
+      result.keepRecentTokens = compaction.keepRecentTokens;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+function defaultAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+}
+
+/** Read pi's own compaction settings (global, plus the project file when trusted). */
+export function loadPiNativeCompactionSettings(opts: {
+  cwd?: string;
+  isProjectTrusted?: boolean;
+  agentDir?: string;
+} = {}): PiCompactionSettings {
+  const cwd = opts.cwd ?? process.cwd();
+  const globalSettings = readCompactionSettings(join(opts.agentDir ?? defaultAgentDir(), 'settings.json'));
+  if (!opts.isProjectTrusted) return globalSettings;
+  const projectSettings = readCompactionSettings(join(cwd, '.pi', 'settings.json'));
+  return { ...globalSettings, ...projectSettings };
+}
+
+export function readJsonConfig(filePath: string, onError?: (error: unknown) => void): unknown | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8')) as unknown;
+  } catch (error) {
+    onError?.(error);
+    return undefined;
+  }
+}

package/src/efficiency-store.ts

@@ -0,0 +1,312 @@
+/**
+ * D101-D103 Efficiency Storage & I/O Adapter.
+ *
+ * Implements safe, content-addressed storage for ObservationPack and
+ * Evidence-Preserving Reducer, along with telemetry log appending and
+ * secure bash un-truncated output reading.
+ *
+ * Security & Integrity:
+ *  - Mode 0700 for directories, 0600 for object and log files.
+ *  - O_NOFOLLOW to forbid symlinks.
+ *  - Safe sessionId regex validation.
+ *  - EEXIST integrity verification (rejects corrupted collisions).
+ */
+
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import {
+  countLines,
+  sha256Hex,
+  sliceBufferChunk,
+  type RecallSliceResult,
+} from './observation-core.ts';
+
+export const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+export const BASH_LOG_NAME_RE = /^pi-bash-.*\.log$/;
+
+const READ_OBJECT_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
+const CREATE_OBJECT_FLAGS =
+  constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+
+const verifiedObjectCache = new Set<string>();
+
+export function clearVerifiedObjectCacheForTest(): void {
+  verifiedObjectCache.clear();
+}
+
+export interface StorageObjectResult {
+  path: string;
+  bytes: number;
+  lines: number;
+  hash: string;
+}
+
+export function isValidSessionId(id: string | null | undefined): boolean {
+  return typeof id === 'string' && id.length > 0 && SAFE_SESSION_ID_RE.test(id);
+}
+
+export function resolveSessionRoot(
+  sessionDir: string | null | undefined,
+  sessionId: string | null | undefined,
+): string | null {
+  if (!sessionDir || typeof sessionDir !== 'string') return null;
+  if (!isValidSessionId(sessionId)) return null;
+  return join(sessionDir, 'herdr-pi', sessionId!);
+}
+
+export function observationObjectPath(root: string, obsId: string): string {
+  return join(root, 'observation-pack', 'objects', `${obsId}.txt`);
+}
+
+export function reducerObjectPath(root: string, sha256: string): string {
+  return join(root, 'evidence-preserving-reducer', 'objects', `${sha256}.txt`);
+}
+
+export function efficiencyLogPath(
+  root: string,
+  mechanism: 'compact' | 'observation' | 'reducer' | 'jev',
+  customPath?: string,
+): string {
+  if (customPath && typeof customPath === 'string') return resolve(customPath);
+  return join(root, 'efficiency-logs', `${mechanism}.jsonl`);
+}
+
+export const MAX_OBJECTS_PER_DIR = 300;
+export const MAX_OBJECTS_TOTAL_BYTES = 50 * 1024 * 1024; // 50MB
+
+export async function pruneObjectsDirectory(
+  dir: string,
+  limits: { maxFiles?: number; maxTotalBytes?: number } = {},
+): Promise<number> {
+  const maxFiles = limits.maxFiles ?? MAX_OBJECTS_PER_DIR;
+  const maxTotalBytes = limits.maxTotalBytes ?? MAX_OBJECTS_TOTAL_BYTES;
+
+  try {
+    const entries = await readdir(dir);
+    const files: Array<{ name: string; path: string; size: number; mtimeMs: number }> = [];
+    let totalBytes = 0;
+
+    for (const name of entries) {
+      if (!name.endsWith('.txt')) continue;
+      const p = join(dir, name);
+      try {
+        const s = await stat(p);
+        if (s.isFile() && !s.isSymbolicLink()) {
+          files.push({ name, path: p, size: s.size, mtimeMs: s.mtimeMs });
+          totalBytes += s.size;
+        }
+      } catch {
+        /* ignore stat errors */
+      }
+    }
+
+    if (files.length <= maxFiles && totalBytes <= maxTotalBytes) {
+      return 0;
+    }
+
+    // Sort by mtime ascending (oldest first)
+    files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+    let removedCount = 0;
+    for (const f of files) {
+      if (files.length - removedCount <= maxFiles && totalBytes <= maxTotalBytes) {
+        break;
+      }
+      try {
+        await rm(f.path, { force: true });
+        removedCount++;
+        totalBytes -= f.size;
+        for (const k of verifiedObjectCache.keys()) {
+          if (k.startsWith(f.path)) verifiedObjectCache.delete(k);
+        }
+      } catch {
+        /* ignore unlink errors */
+      }
+    }
+    return removedCount;
+  } catch {
+    return 0;
+  }
+}
+
+/** Prune both content-addressed object dirs of one session root; returns total removed files. */
+export async function pruneSessionObjects(
+  sessionRoot: string,
+  limits: { maxFiles?: number; maxTotalBytes?: number } = {},
+): Promise<number> {
+  const targets = [
+    join(sessionRoot, 'observation-pack', 'objects'),
+    join(sessionRoot, 'evidence-preserving-reducer', 'objects'),
+  ];
+  let removed = 0;
+  for (const dir of targets) {
+    removed += await pruneObjectsDirectory(dir, limits);
+  }
+  return removed;
+}
+
+let storeWriteCounter = 0;
+
+export async function storeContentAddressedObject(
+  filePath: string,
+  content: string,
+  precomputed?: { bytes?: number; hash?: string; lines?: number },
+): Promise<StorageObjectResult> {
+  const contentBytes = precomputed?.bytes ?? Buffer.byteLength(content, 'utf8');
+  const hash = precomputed?.hash ?? sha256Hex(content);
+  const lines = precomputed?.lines ?? countLines(content);
+
+  const dir = dirname(filePath);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const dirStats = await lstat(dir);
+  if (!dirStats.isDirectory() || dirStats.isSymbolicLink()) {
+    throw new Error(`Target directory is not a safe directory: ${dir}`);
+  }
+
+  let handle;
+  try {
+    handle = await open(filePath, CREATE_OBJECT_FLAGS, 0o600);
+    await handle.writeFile(content, { encoding: 'utf8' });
+    const writtenStat = await handle.stat();
+    verifiedObjectCache.add(`${filePath}:${contentBytes}:${writtenStat.mtimeMs}:${hash}`);
+  } catch (err) {
+    if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
+      // Verify existing file integrity
+      const existingHandle = await open(filePath, READ_OBJECT_FLAGS);
+      try {
+        const existingStat = await existingHandle.stat();
+        if (!existingStat.isFile()) {
+          throw new Error(`Existing object is not a regular file: ${filePath}`);
+        }
+        if (existingStat.size !== contentBytes) {
+          throw new Error(`Existing object size mismatch: ${existingStat.size} vs ${contentBytes}`);
+        }
+        // mtime-aware cache key: prevents reading large files repeatedly if mtime hasn't changed
+        const mtimeKey = `${filePath}:${contentBytes}:${existingStat.mtimeMs}:${hash}`;
+        if (!verifiedObjectCache.has(mtimeKey)) {
+          const existingData = await existingHandle.readFile();
+          if (sha256Hex(existingData) !== hash) {
+            throw new Error(`Existing object hash mismatch: ${filePath}`);
+          }
+          verifiedObjectCache.add(mtimeKey);
+        }
+      } finally {
+        await existingHandle.close();
+      }
+    } else {
+      throw err;
+    }
+  } finally {
+    await handle?.close();
+  }
+
+  storeWriteCounter++;
+  if (storeWriteCounter % 50 === 0) {
+    void pruneObjectsDirectory(dir).catch(() => {});
+  }
+
+  return {
+    path: filePath,
+    bytes: contentBytes,
+    lines,
+    hash,
+  };
+}
+
+export async function readStoredObjectChunk(
+  filePath: string,
+  offset: number,
+  limits: { maxBytes: number; maxLines: number },
+): Promise<RecallSliceResult> {
+  let handle;
+  try {
+    handle = await open(filePath, READ_OBJECT_FLAGS);
+    const fileStat = await handle.stat();
+    if (!fileStat.isFile()) {
+      throw new Error(`Stored object is not a regular file: ${filePath}`);
+    }
+    if (offset > fileStat.size) {
+      throw new Error(`Offset ${offset} exceeds object size ${fileStat.size}`);
+    }
+
+    const available = Math.max(0, fileStat.size - offset);
+    const buffer = Buffer.alloc(Math.min(available, limits.maxBytes + 4));
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+    return sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
+  } finally {
+    await handle?.close();
+  }
+}
+
+export const MAX_EFFICIENCY_LOG_BYTES = 5 * 1024 * 1024; // 5MB rotation ceiling
+
+export async function appendEfficiencyLog(
+  logPath: string,
+  record: Record<string, unknown>,
+): Promise<void> {
+  const line = `${JSON.stringify(record)}\n`;
+  const dir = dirname(logPath);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+
+  // Rotate log if exceeds maximum size to prevent unbounded disk growth
+  try {
+    const s = await stat(logPath);
+    if (s.size > MAX_EFFICIENCY_LOG_BYTES) {
+      const oldPath = `${logPath}.old`;
+      await rm(oldPath, { force: true });
+      await rename(logPath, oldPath);
+    }
+  } catch {
+    /* file may not exist yet, continue */
+  }
+
+  let handle;
+  try {
+    handle = await open(logPath, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND, 0o600);
+    await handle.writeFile(line, { encoding: 'utf8' });
+  } finally {
+    await handle?.close();
+  }
+}
+
+/**
+ * Safely reads Pi's untruncated bash output from temporary file.
+ */
+export async function readBashFullOutput(
+  rawPath: string | null | undefined,
+  maxChars: number,
+): Promise<{ content: string; bytes: number; lines: number } | null> {
+  if (!rawPath || typeof rawPath !== 'string') return null;
+
+  const fileName = basename(rawPath);
+  if (!BASH_LOG_NAME_RE.test(fileName)) return null;
+
+  try {
+    const realTmp = await realpath(tmpdir());
+    const realFile = await realpath(rawPath);
+    const rel = relative(realTmp, realFile);
+    if (rel.startsWith('..') || isAbsolute(rel)) return null;
+
+    const fileStat = await stat(realFile);
+    if (!fileStat.isFile() || fileStat.isSymbolicLink()) return null;
+
+    // Check size within reasonable limit
+    if (fileStat.size > maxChars * 4) return null;
+
+    let handle = await open(realFile, READ_OBJECT_FLAGS);
+    try {
+      const content = await handle.readFile({ encoding: 'utf8' });
+      return {
+        content,
+        bytes: Buffer.byteLength(content, 'utf8'),
+        lines: countLines(content),
+      };
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return null;
+  }
+}

package/src/focus-poller.ts

@@ -0,0 +1,244 @@
+/**
+ * D-4: herdr 0.9.0 resolved mouse focus client-side, so `pane.focused` never reached plugins.
+ * Each pier pane sampled `layout.export` and replayed `pane.focused` into heat-reflow.mjs.
+ *
+ * Herdr 0.9.1 delivers `pane.focused` to the workbench hook. Default polling is therefore off
+ * (0 ms) on ≥0.9.1 so a click is not followed by a second reflow ~8s later. Herdr <0.9.1 keeps
+ * the 1500ms sampler. `PIER_FOCUS_POLL_MS` overrides either default; 0 disables.
+ */
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Poll cadence for older Herdr (< 0.9.1). */
+export const FOCUS_POLL_DEFAULT_MS = 1500;
+/** Herdr 0.9.1+: native pane.focused is authoritative; default poller off to avoid a delayed second reflow. */
+export const FOCUS_POLL_HERDR_091_MS = 0;
+
+/** Check if Herdr server version is 0.9.1 or later. */
+export function isHerdr091OrLater(version?: string | null): boolean {
+  if (!version) return false;
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return false;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  const patch = Number(m[3]);
+  if (major > 0) return true;
+  if (minor > 9) return true;
+  if (minor === 9 && patch >= 1) return true;
+  return false;
+}
+
+/** Determine default poll cadence based on Herdr server version. */
+export function resolveDefaultFocusPollMs(herdrVersion?: string | null): number {
+  return isHerdr091OrLater(herdrVersion) ? FOCUS_POLL_HERDR_091_MS : FOCUS_POLL_DEFAULT_MS;
+}
+/**
+ * Minimum gap between two reflow triggers. Re-clicking the same pane quickly must not spawn a
+ * process per click; the workbench debounces per tab (150 ms) on top of this.
+ */
+export const FOCUS_FIRE_MIN_INTERVAL_MS = 700;
+
+export interface FocusSample {
+  /** Pane focused in the sampled tab (null when the server reported no focus). */
+  readonly focusedPaneId: string | null;
+  /** Panes currently in that tab, used to tell a click apart from a spawn auto-focus. */
+  readonly paneIds: readonly string[];
+}
+
+export interface FocusPollerState {
+  readonly lastFocusedPaneId: string | null;
+  readonly lastPaneIds: readonly string[];
+  readonly lastFireAt: number;
+}
+
+/** Minimal flatten of a herdr layout tree (`{type:'pane',pane_id}` / `{type:'split',first,second}`). */
+export function collectPaneIds(root: unknown): string[] {
+  const out: string[] = [];
+  const walk = (node: unknown): void => {
+    if (node === null || typeof node !== 'object') return;
+    const n = node as { pane_id?: unknown; first?: unknown; second?: unknown };
+    if (typeof n.pane_id === 'string') {
+      out.push(n.pane_id);
+      return;
+    }
+    walk(n.first);
+    walk(n.second);
+  };
+  walk(root);
+  return out;
+}
+
+/** `layout.export` payload → sample. `focusedPaneId` is optional for older clients. */
+export function parseFocusSample(
+  layout: { root: unknown; focusedPaneId?: string | null } | null | undefined,
+): FocusSample | null {
+  if (!layout || !('root' in layout)) return null;
+  const paneIds = collectPaneIds(layout.root);
+  const focused = typeof layout.focusedPaneId === 'string' ? layout.focusedPaneId : null;
+  return { focusedPaneId: focused, paneIds };
+}
+
+export interface FocusTick {
+  readonly fire: boolean;
+  readonly cause: 'user' | null;
+  readonly state: FocusPollerState;
+}
+
+/**
+ * Decide whether one sample should trigger a reflow.
+ *
+ * Fires only on a *transition* into "I am focused" (so a steady focus never re-triggers) and at most
+ * once per `minIntervalMs`. `cause` is 'user' when the pane set did not change in the same sample:
+ * a click moves focus and nothing else, whereas a spawn auto-focus always comes with a new pane.
+ * The workbench uses that distinction for its 3 s pane-age whitelist (F1: a freshly created pane
+ * must not grab the layout through an automatic focus).
+ */
+export function planFocusTick(opts: {
+  myPaneId: string;
+  sample: FocusSample;
+  prev: FocusPollerState | null;
+  now: number;
+  minIntervalMs?: number;
+}): FocusTick {
+  const minInterval = opts.minIntervalMs ?? FOCUS_FIRE_MIN_INTERVAL_MS;
+  const prev = opts.prev;
+  const next: FocusPollerState = {
+    lastFocusedPaneId: opts.sample.focusedPaneId,
+    lastPaneIds: opts.sample.paneIds,
+    lastFireAt: prev?.lastFireAt ?? 0,
+  };
+  const noFire = (): FocusTick => ({ fire: false, cause: null, state: next });
+
+  if (opts.myPaneId === '') return noFire();
+  // First sample only records the baseline: a pi that starts in the focused pane must not reflow on
+  // startup (that is not a click, and it would fight whatever layout the user had).
+  if (prev === null) return noFire();
+  if (opts.sample.focusedPaneId !== opts.myPaneId) return noFire();
+  if (prev.lastFocusedPaneId === opts.myPaneId) return noFire();
+  if (opts.now - prev.lastFireAt < minInterval) return noFire();
+
+  const setUnchanged =
+    prev.lastPaneIds.length === opts.sample.paneIds.length &&
+    prev.lastPaneIds.every((id, i) => id === opts.sample.paneIds[i]);
+  return {
+    fire: true,
+    cause: setUnchanged ? 'user' : null,
+    state: { ...next, lastFireAt: opts.now },
+  };
+}
+
+/* ─────────────────────────── runner ─────────────────────────── */
+
+export interface FocusPollerDeps {
+  /** Layout of the caller's own tab (the client already exposes `layout.export`). */
+  sample(): Promise<FocusSample | null>;
+  /** Replay a pane.focused reflow for `paneId`. Must never throw. */
+  fire(paneId: string, cause: 'user' | null): void;
+  myPaneId: string;
+  intervalMs?: number;
+  minIntervalMs?: number;
+  now?: () => number;
+  setIntervalFn?: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearIntervalFn?: (handle: NodeJS.Timeout) => void;
+  /** Diagnostics only: polling failures are expected while herdr restarts. */
+  onError?: (err: unknown) => void;
+}
+
+export interface FocusPoller {
+  /** One sampling pass (exposed for tests; the interval calls the same function). */
+  tick(): Promise<void>;
+  stop(): void;
+}
+
+export function startFocusPoller(deps: FocusPollerDeps): FocusPoller {
+  const intervalMs = deps.intervalMs ?? FOCUS_POLL_DEFAULT_MS;
+  const now = deps.now ?? (() => Date.now());
+  const setIntervalFn = deps.setIntervalFn ?? ((fn, ms) => setInterval(fn, ms));
+  const clearIntervalFn =
+    deps.clearIntervalFn ?? ((handle: NodeJS.Timeout) => { clearInterval(handle); });
+  let state: FocusPollerState | null = null;
+  let inFlight = false;
+  let stopped = false;
+  let handle: NodeJS.Timeout | null = null;
+
+  async function tick(): Promise<void> {
+    if (stopped || inFlight) return;
+    inFlight = true;
+    try {
+      const sample = await deps.sample();
+      if (sample === null) return;
+      const decision = planFocusTick({
+        myPaneId: deps.myPaneId,
+        sample,
+        prev: state,
+        now: now(),
+        minIntervalMs: deps.minIntervalMs,
+      });
+      state = decision.state;
+      if (decision.fire) deps.fire(deps.myPaneId, decision.cause);
+    } catch (err) {
+      // A failed sample must not advance the baseline: the next tick re-reads the layout.
+      deps.onError?.(err);
+    } finally {
+      inFlight = false;
+    }
+  }
+
+  if (intervalMs > 0) {
+    handle = setIntervalFn(() => { void tick(); }, intervalMs);
+    handle.unref?.(); // never keep pi's event loop alive on our account
+  }
+
+  return {
+    tick,
+    stop(): void {
+      stopped = true;
+      if (handle !== null) {
+        clearIntervalFn(handle);
+        handle = null;
+      }
+    },
+  };
+}
+
+/** The workbench's reflow entry point; overridable for relocated checkouts. */
+export function reflowScriptPath(env: NodeJS.ProcessEnv = process.env): string {
+  const root = env.PIER_WORKBENCH_ROOT?.trim();
+  if (root) return join(root, 'scripts', 'heat-reflow.mjs');
+  // packages/pier-ext/src/focus-poller.ts -> packages/pier-workbench/scripts/heat-reflow.mjs
+  return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'pier-workbench', 'scripts', 'heat-reflow.mjs');
+}
+
+export interface SpawnReflowOpts {
+  paneId: string;
+  cause: 'user' | null;
+  env?: NodeJS.ProcessEnv;
+  /** Injection seam for tests (defaults to child_process.spawn). */
+  spawnFn?: typeof spawn;
+}
+
+/**
+ * Fire-and-forget replay of the `pane.focused` hook.
+ * Why a child process: it is exactly how herdr runs the hook, so the workbench script keeps its own
+ * event parsing, debounce and state file — pier never duplicates layout logic.
+ */
+export function spawnReflow(opts: SpawnReflowOpts): void {
+  const env = opts.env ?? process.env;
+  const spawnFn = opts.spawnFn ?? spawn;
+  const payload = JSON.stringify({
+    event: 'pane_focused',
+    type: 'pane_focused',
+    data: { type: 'pane_focused', pane_id: opts.paneId, cause: opts.cause },
+  });
+  try {
+    const child = spawnFn(process.execPath, [reflowScriptPath(env)], {
+      env: { ...env, HERDR_PLUGIN_EVENT: 'pane.focused', HERDR_PLUGIN_EVENT_JSON: payload },
+      stdio: 'ignore',
+    });
+    child.on?.('error', () => { /* Missing script / dead exec: polling must never break pi. */ });
+    child.unref?.();
+  } catch {
+    /* Best-effort: focus heat is a comfort feature; the click still focuses the pane. */
+  }
+}

package/src/gc-core.ts

@@ -54,3 +54,88 @@ export function shouldClosePane(opts: {
   if (opts.herdrStatus !== 'idle' && opts.herdrStatus !== 'done') return false;
   return (opts.consumedAt ?? 0) > 0 && opts.consumedAt! < opts.prevTurnStart;
 }
+
+/* ── Isolate worktree collection (why the rules are this narrow) ──────
+ * The first version treated ANY branch under `refs/heads/pier/` as pier-owned, so
+ * every pier master session swept the whole namespace. A worker session lives in
+ * exactly such a worktree, and its own branch is trivially an ancestor of its own
+ * HEAD and clean once it commits — so the sweep deleted the worktree the process
+ * was running in (observed twice: 01a06ae3-era workers and the env-hook worker).
+ * Ownership must therefore be explicit: only branches registered in THIS session's
+ * subagent registry are candidates, the current working directory is never a
+ * candidate, and untracked `pier/*` branches require an explicit opt-in.
+ */
+
+/** True when `path` is `parent` or lives inside it (both resolved, no I/O). */
+export function isPathInside(path: string, parent: string): boolean {
+  const norm = (p: string): string => p.replace(/[\\/]+/g, '/').replace(/\/+$/, '');
+  const child = norm(path);
+  const base = norm(parent);
+  if (!child || !base) return false;
+  return child === base || child.startsWith(`${base}/`);
+}
+
+export interface IsolateSweepCandidate {
+  branch: string;
+  worktreePath: string;
+}
+
+export interface IsolateSweepSkip {
+  branch: string;
+  reason: 'unregistered' | 'pending' | 'self' | 'no-worktree';
+}
+
+export interface IsolateSweepPlan {
+  candidates: IsolateSweepCandidate[];
+  skipped: IsolateSweepSkip[];
+}
+
+/**
+ * Decide which isolate worktrees this session may collect.
+ * Pure: callers pass git output, the subagent registry and the process cwd.
+ */
+export function planIsolateSweep(input: {
+  /** Every `refs/heads/pier/*` branch name. */
+  branches: readonly string[];
+  /** branch → worktree path, from `git worktree list --porcelain`. */
+  worktreesByBranch: ReadonlyMap<string, string>;
+  /** Branches of isolate entries in this session's registry. */
+  registeredBranches: ReadonlySet<string>;
+  /** Branches created but not yet registered (worktree add → subs.set window). */
+  pendingBranches: ReadonlySet<string>;
+  /** Session-owned isolates that may be collected, with their recorded path. */
+  sessionOwned: ReadonlyArray<{ branch: string; worktreePath: string }>;
+  /** Path to protect (normally process.cwd()). */
+  cwd: string;
+  /** Explicit opt-in for branches this session never registered. */
+  sweepOrphans: boolean;
+}): IsolateSweepPlan {
+  const candidates = new Map<string, IsolateSweepCandidate>();
+  const skipped: IsolateSweepSkip[] = [];
+  const add = (branch: string, worktreePath: string): void => {
+    if (isPathInside(input.cwd, worktreePath)) {
+      skipped.push({ branch, reason: 'self' });
+      return;
+    }
+    candidates.set(branch, { branch, worktreePath });
+  };
+
+  if (input.sweepOrphans) {
+    for (const branch of input.branches) {
+      if (input.registeredBranches.has(branch)) continue;
+      if (input.pendingBranches.has(branch)) {
+        skipped.push({ branch, reason: 'pending' });
+        continue;
+      }
+      const wtPath = input.worktreesByBranch.get(branch);
+      if (wtPath) add(branch, wtPath);
+    }
+  }
+
+  for (const entry of input.sessionOwned) {
+    const wtPath = input.worktreesByBranch.get(entry.branch) ?? entry.worktreePath;
+    add(entry.branch, wtPath);
+  }
+
+  return { candidates: [...candidates.values()], skipped };
+}