pi-pier 0.3.0 → 0.3.1

package/src/efficiency-store.ts

@@ -1,15 +1,7 @@
 /**
- * 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).
+ * 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';
@@ -23,8 +15,8 @@ import {
   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 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 =
@@ -66,15 +58,15 @@ export function reducerObjectPath(root: string, sha256: string): string {
 
 export function efficiencyLogPath(
   root: string,
-  mechanism: 'compact' | 'observation' | 'reducer' | 'jev',
+  mechanism: 'compact' | 'observation' | 'reducer' | 'jev' | 'routing',
   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
+const MAX_OBJECTS_PER_DIR = 300;
+const MAX_OBJECTS_TOTAL_BYTES = 50 * 1024 * 1024;
 
 export async function pruneObjectsDirectory(
   dir: string,
@@ -98,7 +90,6 @@ export async function pruneObjectsDirectory(
           totalBytes += s.size;
         }
       } catch {
-        /* ignore stat errors */
       }
     }
 
@@ -106,7 +97,6 @@ export async function pruneObjectsDirectory(
       return 0;
     }
 
-    // Sort by mtime ascending (oldest first)
     files.sort((a, b) => a.mtimeMs - b.mtimeMs);
 
     let removedCount = 0;
@@ -122,7 +112,6 @@ export async function pruneObjectsDirectory(
           if (k.startsWith(f.path)) verifiedObjectCache.delete(k);
         }
       } catch {
-        /* ignore unlink errors */
       }
     }
     return removedCount;
@@ -131,7 +120,6 @@ export async function pruneObjectsDirectory(
   }
 }
 
-/** 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 } = {},
@@ -173,7 +161,6 @@ export async function storeContentAddressedObject(
     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();
@@ -234,13 +221,18 @@ export async function readStoredObjectChunk(
     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);
+    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();
   }
 }
 
-export const MAX_EFFICIENCY_LOG_BYTES = 5 * 1024 * 1024; // 5MB rotation ceiling
+/** 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,
@@ -250,7 +242,6 @@ export async function appendEfficiencyLog(
   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) {
@@ -259,7 +250,6 @@ export async function appendEfficiencyLog(
       await rename(logPath, oldPath);
     }
   } catch {
-    /* file may not exist yet, continue */
   }
 
   let handle;
@@ -271,9 +261,7 @@ export async function appendEfficiencyLog(
   }
 }
 
-/**
- * Safely reads Pi's untruncated bash output from temporary file.
- */
+/** Safely reads Pi's untruncated bash output from temporary file. */
 export async function readBashFullOutput(
   rawPath: string | null | undefined,
   maxChars: number,
@@ -292,7 +280,6 @@ export async function readBashFullOutput(
     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);

package/src/focus-poller.ts

@@ -1,10 +1,7 @@
 /**
- * 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.
+ * 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';
@@ -15,7 +12,6 @@ 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());
@@ -29,14 +25,11 @@ export function isHerdr091OrLater(version?: string | null): boolean {
   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.
- */
+/** 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 {
@@ -86,13 +79,10 @@ export interface FocusTick {
 }
 
 /**
- * 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).
+ * 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;
@@ -128,8 +118,6 @@ export function planFocusTick(opts: {
   };
 }
 
-/* ─────────────────────────── runner ─────────────────────────── */
-
 export interface FocusPollerDeps {
   /** Layout of the caller's own tab (the client already exposes `layout.export`). */
   sample(): Promise<FocusSample | null>;
@@ -139,8 +127,6 @@ export interface FocusPollerDeps {
   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;
 }
@@ -153,10 +139,7 @@ export interface FocusPoller {
 
 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); });
+  const now = deps.now ?? Date.now;
   let state: FocusPollerState | null = null;
   let inFlight = false;
   let stopped = false;
@@ -186,7 +169,7 @@ export function startFocusPoller(deps: FocusPollerDeps): FocusPoller {
   }
 
   if (intervalMs > 0) {
-    handle = setIntervalFn(() => { void tick(); }, intervalMs);
+    handle = setInterval(() => { void tick(); }, intervalMs);
     handle.unref?.(); // never keep pi's event loop alive on our account
   }
 
@@ -195,7 +178,7 @@ export function startFocusPoller(deps: FocusPollerDeps): FocusPoller {
     stop(): void {
       stopped = true;
       if (handle !== null) {
-        clearIntervalFn(handle);
+        clearInterval(handle);
         handle = null;
       }
     },
@@ -218,11 +201,8 @@ export interface SpawnReflowOpts {
   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.
- */
+/** 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;
@@ -239,6 +219,5 @@ export function spawnReflow(opts: SpawnReflowOpts): void {
     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

@@ -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;
@@ -55,18 +42,11 @@ export function shouldClosePane(opts: {
   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.
- */
+/* 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. */
 
-/** 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);
@@ -90,20 +70,14 @@ export interface IsolateSweepPlan {
   skipped: IsolateSweepSkip[];
 }
 
-/**
- * Decide which isolate worktrees this session may collect.
- * Pure: callers pass git output, the subagent registry and the process cwd.
- */
+/** 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;