pi-pier 0.2.7 → 0.3.1

package/src/efficiency-store.ts

@@ -0,0 +1,299 @@
+/**
+ * D101-D103 efficiency storage: content-addressed objects (ObservationPack / EPR), telemetry appends
+ * and the un-truncated bash log reader. Integrity: directories 0700, files 0600, O_NOFOLLOW everywhere,
+ * session ids regex-validated, and an EEXIST collision is re-verified (size + sha256) instead of trusted.
+ */
+
+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';
+
+const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+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' | 'routing',
+  customPath?: string,
+): string {
+  if (customPath && typeof customPath === 'string') return resolve(customPath);
+  return join(root, 'efficiency-logs', `${mechanism}.jsonl`);
+}
+
+const MAX_OBJECTS_PER_DIR = 300;
+const MAX_OBJECTS_TOTAL_BYTES = 50 * 1024 * 1024;
+
+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 {
+      }
+    }
+
+    if (files.length <= maxFiles && totalBytes <= maxTotalBytes) {
+      return 0;
+    }
+
+    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 {
+      }
+    }
+    return removedCount;
+  } catch {
+    return 0;
+  }
+}
+
+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') {
+      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);
+    const sliced = sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
+    // sliceBufferChunk's nextOffset is relative to the window it was given (offset 0). Callers page
+    // with the absolute file offset from the header, so add the seek back.
+    const nextOffset = offset + sliced.nextOffset;
+    return { ...sliced, nextOffset, eof: nextOffset >= fileStat.size };
+  } finally {
+    await handle?.close();
+  }
+}
+
+/** Rotation ceiling: rename to `<log>.old` past this size so a log can never grow unbounded. */
+const MAX_EFFICIENCY_LOG_BYTES = 5 * 1024 * 1024;
+
+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 });
+
+  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 {
+  }
+
+  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;
+
+    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,223 @@
+/**
+ * D-4: herdr 0.9.1+ delivers `pane.focused`, so default polling is off (0 ms) there — a sampler
+ * would reflow a second time ~8 s after a click; older servers keep the 1500 ms 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;
+
+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;
+}
+
+export function resolveDefaultFocusPollMs(herdrVersion?: string | null): number {
+  return isHerdr091OrLater(herdrVersion) ? FOCUS_POLL_HERDR_091_MS : FOCUS_POLL_DEFAULT_MS;
+}
+/** Min gap between reflow triggers: re-clicking the same pane must not spawn a process per click (the
+ *  workbench debounces 150 ms per tab 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: only on a *transition* into "I am focused",
+ * 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, a spawn auto-focus comes with a new pane), so
+ * the workbench can keep its pane-age whitelist. Baseline sample never fires.
+ */
+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 },
+  };
+}
+
+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;
+  /** 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;
+  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 = setInterval(() => { void tick(); }, intervalMs);
+    handle.unref?.(); // never keep pi's event loop alive on our account
+  }
+
+  return {
+    tick,
+    stop(): void {
+      stopped = true;
+      if (handle !== null) {
+        clearInterval(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 as a child process — exactly how herdr runs it,
+ *  so the workbench script keeps its own event parsing, debounce and state file. */
+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 {
+  }
+}

package/src/gc-core.ts

@@ -1,7 +1,4 @@
-/**
- * Task-tab GC decisions (D29 rules as a pure function; M22 dropped resident exemption).
- * No I/O, no pi/herdr — unit-testable.
- */
+/** Task-tab GC decisions (D29 rules as a pure function; no I/O, no pi/herdr). */
 export type GcEntryKind = string;
 export type GcEntryStatus = 'running' | 'settled' | 'consumed' | 'closed';
 
@@ -17,14 +14,8 @@ function isFinished(status: GcEntryStatus): boolean {
   return status === 'consumed' || status === 'closed' || status === 'settled';
 }
 
-/**
- * Close a task tab only when every condition holds:
- *  - ≥1 work pane (the main tab with no delegated entries never closes);
- *  - every work pane is settled/consumed/closed (kind is not an exemption);
- *  - grace TTL elapsed (`ttlMs=0` means never auto-close);
- *  - no blocked pane (human-gate exemption);
- *  - remaining panes are idle/done/unknown (non-work panes may be unknown).
- */
+/** Close a task tab only when every work pane finished, the grace TTL elapsed (`ttlMs=0` means never
+ *  auto-close), no pane is blocked and the rest are idle/done/unknown. */
 export function shouldCloseTaskTab(opts: {
   entries: readonly GcEntryLike[];
   paneStatuses: readonly string[];
@@ -39,12 +30,8 @@ export function shouldCloseTaskTab(opts: {
   return true;
 }
 
-/**
- * Pane-level collection (orphan / compat path):
- *  - consumed before the previous turn (grace so the settlement notice is still visible);
- *  - herdr status idle/done (unknown/working/blocked retry next turn);
- *  - missing pane (status undefined) → record closed (caller handles the write).
- */
+/** Pane-level collection (orphan / compat path): consumed before the previous turn (grace so the
+ *  settlement notice is still visible); missing pane → record closed (caller handles the write). */
 export function shouldClosePane(opts: {
   consumedAt: number | null;
   herdrStatus: string | undefined;
@@ -54,3 +41,75 @@ 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 is deliberately narrow: `refs/heads/pier/*` is NOT proof of pier
+ * ownership — a worker session lives in such a worktree, so a namespace-wide sweep deletes the
+ * worktree its own process is running in. Only THIS session's registered branches are candidates,
+ * cwd never is, and untracked `pier/*` branches need an explicit opt-in. */
+
+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[];
+}
+
+/** Pure: callers pass git output, the subagent registry and the process cwd. */
+export function planIsolateSweep(input: {
+  branches: readonly string[];
+  /** branch → worktree path, from `git worktree list --porcelain`. */
+  worktreesByBranch: ReadonlyMap<string, string>;
+  registeredBranches: ReadonlySet<string>;
+  /** Branches created but not yet registered (worktree add → subs.set window). */
+  pendingBranches: ReadonlySet<string>;
+  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 };
+}