pi-pier 0.3.0 → 0.4.1

package/src/lock-core.ts

@@ -1,34 +1,31 @@
-/** Why: Preserve the established compatibility and safety behavior (D3, M18, S2). */
+/**
+ * M18 file-level write locks (S2: soft veto by default, `PI_HERDR_WRITE_LOCK=1` makes it hard).
+ *
+ * A lock is a *beacon*, not a mutex: the pane editing a file reports a token
+ * (`lock-<hash>` → `paneId|path`, see herdr-client.reportLockTokens) and every other pane reads
+ * the token table to warn or block. Tokens must match `^[A-Za-z0-9_-]{1,32}$` with ≤16 keys per
+ * report, hence the hashed key and the path inside the value.
+ */
 import { resolve, sep } from 'node:path';
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export const WRITE_LOCK_ENV = 'PI_HERDR_WRITE_LOCK';
-/** Why: Preserve the established compatibility and safety behavior. */
 export const WRITE_TOOLS = ['write', 'edit'] as const;
-/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_TOKEN_PREFIX = 'lock-';
-/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_BATCH_LIMIT = 16;
-/** Why: Preserve the established compatibility and safety behavior. */
 export const LOCK_TTL_MS = 60 * 60 * 1000;
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export interface LockAgentView {
   paneId: string;
   tokens: Record<string, string | null>;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
+/** Case-folded, separator-unified absolute path: the key every lock lookup agrees on. */
 export function normalizeLockPath(p: string, cwd: string): string {
   const abs = resolve(cwd, p);
   const unified = sep === '\\' ? abs.replace(/\\/g, '/') : abs;
   return unified.toLowerCase().replace(/\/+$/, '');
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
-/** Why: Preserve the established compatibility and safety behavior. */
 export function fnv1a64(s: string): string {
   let h = 0xcbf29ce484222325n;
   for (let i = 0; i < s.length; i++) {
@@ -52,13 +49,10 @@ export function parseLockTokenValue(v: string): { holderPaneId: string; path: st
   return { holderPaneId: v.slice(0, i), path: v.slice(i + 1) };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export function isLockTokenKey(key: string): boolean {
   return key.startsWith(LOCK_TOKEN_PREFIX) && key.length > LOCK_TOKEN_PREFIX.length;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export function writePathsOfTool(toolName: string, input: unknown): string[] {
   if (!(WRITE_TOOLS as readonly string[]).includes(toolName)) return [];
   const p = (input as { path?: unknown } | null | undefined)?.path;
@@ -66,22 +60,20 @@ export function writePathsOfTool(toolName: string, input: unknown): string[] {
 }
 
 /**
- * B7: write-locks only see the write/edit tools, so a `bash` command that redirects into a file
- * bypasses the beacon entirely (`> file`, `>> file`, `tee file`, `sed -i`, `truncate -s 0`).
- * We do not try to parse shell: this extracts the *obvious* redirect/tee targets so the lock layer
- * can raise a soft warning, and the limitation stays documented rather than implied.
- *
- * Pure and conservative: unknown syntax yields no paths, and a failure here must never block.
+ * B7: write-locks only see the write/edit tools, so a `bash` command that redirects into a file bypasses
+ * the beacon entirely (`> file`, `>> file`, `tee file`, `sed -i`, `truncate -s 0`). We do not try to parse
+ * shell: this extracts the *obvious* targets so the lock layer can warn (never block) — a false negative is
+ * cheap, a false block is not.
  */
 export function bashWriteTargets(command: unknown): string[] {
   if (typeof command !== 'string' || command.trim() === '') return [];
   const found: string[] = [];
-  // Quoted or bare targets; stops at shell metacharacters. Deliberately ignores process substitution.
+  // Quoted or bare targets; stops at shell metacharacters, ignores process substitution.
   const target = String.raw`(?:'([^']+)'|"([^"]+)"|([^\s;|&<>()]+))`;
   const patterns = [
-    new RegExp(String.raw`(?:^|[^0-9>])>>?\s*` + target, 'g'),      // > file, >> file
-    new RegExp(String.raw`\btee\s+(?:-a\s+)?` + target, 'g'),        // tee [-a] file
-    new RegExp(String.raw`\btruncate\s+-s\s*0\s+` + target, 'g'),   // truncate -s 0 file
+    new RegExp(String.raw`(?:^|[^0-9>])>>?\s*` + target, 'g'), // > file, >> file
+    new RegExp(String.raw`\btee\s+(?:-a\s+)?` + target, 'g'), // tee [-a] file
+    new RegExp(String.raw`\btruncate\s+-s\s*0\s+` + target, 'g'), // truncate -s 0 file
   ];
   for (const re of patterns) {
     for (const m of command.matchAll(re)) {
@@ -90,8 +82,8 @@ export function bashWriteTargets(command: unknown): string[] {
       if (isObviousPath(path, quoted)) found.push(path);
     }
   }
-  // `sed -i '' 's/a/b/' file`: the first argument is the (possibly empty) backup suffix and the second
-  // the expression, so take the LAST argument as the file rather than guessing the argument order.
+  // `sed -i '' 's/a/b/' file`: the first argument is the (possibly empty) backup suffix and the
+  // second the expression, so the LAST argument is the file.
   for (const m of command.matchAll(/\bsed\s+-i[^\s]*\s+([^|;&\n]+)/g)) {
     const args = splitShellWords(m[1] ?? '');
     for (let i = args.length - 1; i >= 0; i -= 1) {
@@ -114,23 +106,18 @@ function isObviousPath(path: string, quoted = false): boolean {
 /** Whitespace split that keeps quoted segments together and strips their quotes. */
 function splitShellWords(input: string): string[] {
   const out: string[] = [];
-  const re = /'([^']*)'|"([^"]*)"|(\S+)/g;
-  for (const m of input.matchAll(re)) out.push(m[1] ?? m[2] ?? m[3] ?? '');
+  for (const m of input.matchAll(/'([^']*)'|"([^"]*)"|(\S+)/g)) out.push(m[1] ?? m[2] ?? m[3] ?? '');
   return out.filter((s) => s !== '');
 }
 
 /** Soft hint shown after a bash call that wrote into a path another pane has locked. */
-export function formatBashLockHint(normPath: string, holders: readonly string[]): string {
+function formatBashLockHint(normPath: string, holders: readonly string[]): string {
   return `Note: this bash command wrote to ${normPath}, which ${holdersLabel(holders)} is editing. `
     + `Write-locks only cover the write/edit tools, so this write was not blocked: re-read the file before your next edit.`;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
-/**
- * Every *other* pane currently holding a beacon for this path (deduped, in list order).
- * A lock is a beacon rather than a mutex, so several panes can hold the same path.
- */
+/** Every *other* pane holding a beacon for this path (deduped, in list order — several panes can hold
+ *  the same path, so callers get the whole list). */
 export function findLockHolders(
   agents: readonly LockAgentView[],
   ownPaneId: string,
@@ -149,24 +136,17 @@ export function findLockHolders(
   return holders;
 }
 
-export function findLockConflict(
-  agents: readonly LockAgentView[],
-  ownPaneId: string,
-  normPath: string,
-): { holderPaneId: string } | null {
-  const [first] = findLockHolders(agents, ownPaneId, normPath);
-  return first === undefined ? null : { holderPaneId: first };
-}
-
-/** Where to look for the full holder table: humans use the slash command, agents can read herdr's tokens. */
-export const LOCK_HOLDERS_HINT =
+/** Where to look for the full holder table: humans use the slash command, agents read herdr tokens. */
+const LOCK_HOLDERS_HINT =
   'holders: /locks (human view in this pane) · herdr agent list → tokens (agent-readable)';
 
 function holdersLabel(holders: readonly string[]): string {
   return holders.length === 1 ? `pane ${holders[0]}` : `panes ${holders.join(', ')}`;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+function formatConflictWarning(normPath: string, holders: readonly string[]): string {
+  return `⚠️ write conflict: ${normPath} is locked by ${holdersLabel(holders)} (edited in another pane that has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes. ${LOCK_HOLDERS_HINT}`;
+}
 
 export type WriteGuardPlan =
   | { kind: 'skip' }
@@ -182,8 +162,6 @@ export function planWriteGuard(opts: {
   cwd: string;
   hard: boolean;
 }): WriteGuardPlan {
-  // B7: bash redirects are invisible to the write tools, so warn (never block) when their obvious
-  // targets collide with a lock beacon held by another pane.
   const isBash = opts.toolName === 'bash';
   const raw = isBash
     ? bashWriteTargets((opts.input as { command?: unknown } | null | undefined)?.command)
@@ -211,8 +189,6 @@ export function planWriteGuard(opts: {
   return { kind: 'pass', paths };
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
-
 export function acquireTokensFor(normPaths: readonly string[], paneId: string): Record<string, string> {
   const out: Record<string, string> = {};
   for (const p of normPaths) out[lockTokenKey(p)] = lockTokenValue(p, paneId);
@@ -224,7 +200,3 @@ export function releaseTokensFor(normPaths: readonly string[]): Record<string, n
   for (const p of normPaths) out[lockTokenKey(p)] = null;
   return out;
 }
-
-export function formatConflictWarning(normPath: string, holders: readonly string[]): string {
-  return `⚠️ write conflict: ${normPath} is locked by ${holdersLabel(holders)} (edited in another pane that has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes. ${LOCK_HOLDERS_HINT}`;
-}

package/src/manifest-compose.ts

@@ -1,21 +1,21 @@
-/** Why: Preserve the established compatibility and safety behavior (C7). */
+/**
+ * Manifest composition (C7 v2 three-state permissions): role baseline ∪ model suggestion,
+ * minus deny rules, with the D82 unknown-tools stance carried through.
+ */
 import type { PermissionAction, RoleManifest, UnknownToolStance } from './role-manifest.ts';
+import type { RuntimeRoleManifest } from './tool-gate.ts';
 import { loadRoleConfig } from './role-loader.ts';
 
 export interface ManifestSources {
   roleBaseline: readonly string[];
   modelSuggested: readonly string[];
   rulePermissions: Record<string, PermissionAction>;
-  /** Why: Preserve the established compatibility and safety behavior (D82). */
+  /** D82: stance for tools outside the composed set. */
   unknownTools?: UnknownToolStance;
 }
 
-export interface ComposedManifest {
-  tools: string[];
-  permissions: Record<string, PermissionAction>;
-  /** Why: Preserve the established compatibility and safety behavior (D82). */
-  unknownTools: UnknownToolStance;
-}
+/** What composeManifest produces: the runtime manifest minus the identity/section fields. */
+export type ComposedManifest = Omit<RuntimeRoleManifest, 'role' | 'version' | 'services' | 'guidelines'>;
 
 export class ManifestError extends Error {
   readonly code: 'EMPTY_MANIFEST' | 'INVALID_ROLE_CONFIG';
@@ -26,6 +26,11 @@ export class ManifestError extends Error {
   }
 }
 
+export interface ComposedForRole {
+  role: RoleManifest;
+  manifest: ComposedManifest;
+}
+
 export function composeManifest(sources: ManifestSources): ComposedManifest {
   const baseline = sources.roleBaseline.filter((t): t is string => typeof t === 'string' && t.trim() !== '');
   if (baseline.length === 0) {
@@ -40,21 +45,18 @@ export function composeManifest(sources: ManifestSources): ComposedManifest {
   ]);
   const rules = sources.rulePermissions ?? {};
   const defaultAction: PermissionAction = rules['*'] ?? 'allow';
-  const stance: UnknownToolStance = sources.unknownTools ?? 'deny';
 
   const tools: string[] = [];
   const permissions: Record<string, PermissionAction> = {};
-  // Why: Preserve the established compatibility and safety behavior (D82).
-  // Why: Preserve the established compatibility and safety behavior.
-  for (const [k, v] of Object.entries(rules)) {
-    if (k === '*') continue; // Why: Preserve the established compatibility and safety behavior.
-    permissions[k] = v;
+  // Rule keys outside the candidate set stay in permissions: an allow-stance role keeps its
+  // deny rules for tools the model never suggested (D82 excluded families).
+  for (const [key, action] of Object.entries(rules)) {
+    if (key !== '*') permissions[key] = action;
   }
   for (const tool of candidates) {
     const action = rules[tool] ?? defaultAction;
     permissions[tool] = action;
-    if (action === 'deny') continue; // Why: Preserve the established compatibility and safety behavior.
-    tools.push(tool);
+    if (action !== 'deny') tools.push(tool);
   }
 
   if (tools.length === 0) {
@@ -66,16 +68,15 @@ export function composeManifest(sources: ManifestSources): ComposedManifest {
     );
   }
 
-  tools.sort(); // Why: Preserve the established compatibility and safety behavior.
-  return { tools, permissions, unknownTools: stance };
+  tools.sort();
+  return { tools, permissions, unknownTools: sources.unknownTools ?? 'deny' };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (WS-D8). */
 export function composeForRole(
   roleName: string,
   modelSuggested: readonly string[],
   opts?: { loadRole?: typeof loadRoleConfig; loadRoleOpts?: Parameters<typeof loadRoleConfig>[1] },
-): { role: RoleManifest; manifest: ComposedManifest } {
+): ComposedForRole {
   const load = opts?.loadRole ?? loadRoleConfig;
   const role = load(roleName, opts?.loadRoleOpts);
   const manifest = composeManifest({
@@ -86,3 +87,17 @@ export function composeForRole(
   });
   return { role, manifest };
 }
+
+/** Project a composed profile onto the runtime shape — the one place role-file fields become runtime fields. */
+export function toRuntimeManifest(composed: ComposedForRole): RuntimeRoleManifest {
+  const { role, manifest } = composed;
+  return {
+    role: role.role,
+    version: role.version,
+    tools: manifest.tools,
+    permissions: manifest.permissions,
+    unknownTools: manifest.unknownTools,
+    services: role.services ?? {},
+    ...(role.guidelines?.length ? { guidelines: role.guidelines } : {}),
+  };
+}

package/src/observation-core.ts

@@ -1,23 +1,18 @@
 /**
- * D101 ObservationPack Core.
- *
- * Pure algorithmic functions for large observation detection, deterministic ID derivation,
- * complete-line excerpt generation, chunk slicing with UTF-8 safety, and rolling prefix cache
- * economics.
- *
- * No I/O in this core; storage I/O lives in efficiency-store.ts.
+ * ObservationPack cores: large-observation detection, deterministic ids, complete-line excerpts,
+ * UTF-8-safe chunk slicing, rolling prefix cache economics. Storage I/O is in efficiency-store.ts.
  */
 import { createHash } from 'node:crypto';
 import { TOKEN_ACCOUNT_CACHE_RATIO } from './compact-economics-core.ts';
 import { FAILURE_SIGNAL } from './reducer-core.ts';
 
-export const DEFAULT_THRESHOLD_BYTES = 10 * 1024; // 10KB
-export const DEFAULT_FULL_SENDS = 2;
-export const DEFAULT_EXCERPT_BYTES = 1024;
-export const CHARS_PER_TOKEN = 4;
-export const OBSERVATION_ID_RE = /^obs_[a-f0-9]{24}$/;
+// Fallbacks used only when a caller omits a field; DEFAULT_EFFICIENCY_CONFIG.observationPack is the
+// canonical set (thresholdBytes lives there alone — every pack decision goes through resolved config).
+const DEFAULT_FULL_SENDS = 2;
+const DEFAULT_EXCERPT_BYTES = 1024;
+const CHARS_PER_TOKEN = 4;
 
-/** Marker from Evidence-Preserving Reducer to avoid double packing. */
+/** Marker from the evidence-preserving reducer, used to avoid double packing. */
 export const REDUCER_RECEIPT_PREFIX = 'sol_pi_evidence_receipt_v1';
 
 export function sha256Hex(val: string | Buffer): string {
@@ -38,60 +33,41 @@ export function countLines(text: string): number {
 }
 
 export function isObservationId(id: string): boolean {
-  return OBSERVATION_ID_RE.test(id);
+  return /^obs_[a-f0-9]{24}$/.test(id);
 }
 
 export function deriveObservationId(toolName: string, toolCallId: string, contentHash: string): string {
-  const combined = `${toolName}\0${toolCallId}\0${contentHash}`;
-  return `obs_${sha256Hex(combined).slice(0, 24)}`;
+  return `obs_${sha256Hex(`${toolName}\0${toolCallId}\0${contentHash}`).slice(0, 24)}`;
 }
 
+/** A receipt must be a line of its own — a mere mention inside a log body is not a receipt. */
 export function containsReducerReceipt(text: string): boolean {
   if (!text.includes(REDUCER_RECEIPT_PREFIX)) return false;
   return text.split('\n').some((line) => line.trim() === REDUCER_RECEIPT_PREFIX);
 }
 
+/** Whole lines only, from the head or the tail; the scanned window never exceeds budgetBytes * 4 chars. */
 export function completeLineExcerpt(text: string, budgetBytes: number, fromEnd: boolean): string {
   if (budgetBytes <= 0 || text.length === 0) return '';
 
-  if (!fromEnd) {
-    // Head excerpt: candidate never exceeds budgetBytes * 4 chars
-    const candidate = text.slice(0, Math.min(text.length, budgetBytes * 4));
-    let lastEnd = 0;
-    let totalBytes = 0;
-    let searchIndex = 0;
-    while (searchIndex < candidate.length) {
-      const nextNewline = candidate.indexOf('\n', searchIndex);
-      if (nextNewline === -1) break;
-      const lineEnd = nextNewline + 1;
-      const line = candidate.slice(lastEnd, lineEnd);
-      const lineBytes = Buffer.byteLength(line, 'utf8');
-      if (totalBytes + lineBytes > budgetBytes) break;
-      totalBytes += lineBytes;
-      lastEnd = lineEnd;
-      searchIndex = lineEnd;
-    }
-    return candidate.slice(0, lastEnd);
-  } else {
-    // Tail excerpt: candidate never exceeds budgetBytes * 4 chars from end
-    const startOffset = Math.max(0, text.length - budgetBytes * 4);
-    const candidate = text.slice(startOffset);
-    const lines = candidate.split(/(?<=\n)/);
-    const selected: string[] = [];
-    let selectedBytes = 0;
-    for (let i = lines.length - 1; i >= 0; i--) {
-      const line = lines[i]!;
-      // If startOffset > 0, the first line of candidate might be partial, skip unless it follows a newline
-      if (i === 0 && startOffset > 0 && text[startOffset - 1] !== '\n') {
-        break;
-      }
-      const lineBytes = Buffer.byteLength(line, 'utf8');
-      if (selectedBytes + lineBytes > budgetBytes) break;
-      selected.unshift(line);
-      selectedBytes += lineBytes;
-    }
-    return selected.join('');
+  const window = budgetBytes * 4;
+  const start = fromEnd ? Math.max(0, text.length - window) : 0;
+  const end = fromEnd ? text.length : Math.min(text.length, window);
+  const lines = text.slice(start, end).split(/(?<=\n)/);
+  const selected: string[] = [];
+  let selectedBytes = 0;
+  for (let i = fromEnd ? lines.length - 1 : 0; i >= 0 && i < lines.length; i += fromEnd ? -1 : 1) {
+    const line = lines[i]!;
+    // The head keeps terminated lines only; the tail also keeps the log's final unterminated line.
+    if (!fromEnd && !line.endsWith('\n')) break;
+    if (fromEnd && i === 0 && start > 0 && text[start - 1] !== '\n') break;
+    const lineBytes = Buffer.byteLength(line, 'utf8');
+    if (selectedBytes + lineBytes > budgetBytes) break;
+    selectedBytes += lineBytes;
+    if (fromEnd) selected.unshift(line);
+    else selected.push(line);
   }
+  return selected.join('');
 }
 
 export interface ObservationPlaceholderInput {
@@ -104,10 +80,8 @@ export interface ObservationPlaceholderInput {
   fullSends?: number;
   excerptBudget?: number;
   /**
-   * P0-3 (RFC docs/rfc-jev-integration.md §3): a selected middle window that
-   * replaces whichever head/tail half carries fewer failure-signal lines.
-   * Absent (jev off / low confidence / no signal lines) -> byte-identical
-   * legacy head+tail layout.
+   * P0-3 (RFC docs/rfc-jev-integration.md §3): a selected middle window replacing whichever
+   * head/tail half carries fewer failure-signal lines. Absent → byte-identical legacy layout.
    */
   middle?: { text: string; label: string };
 }
@@ -133,8 +107,8 @@ export function formatObservationPlaceholder(input: ObservationPlaceholderInput)
   let tailLabel = `[middle omitted; last complete lines, up to ${tailBudget} bytes]`;
 
   if (input.middle) {
-    // Fewer signal lines loses its slot; ties replace head because the tail
-    // half usually carries the log's final summary.
+    // Fewer signal lines loses its slot; ties replace head because the tail half usually carries
+    // the log's final summary.
     if (signalLineCount(tail) < signalLineCount(head)) {
       tail = completeLineExcerpt(input.middle.text, tailBudget, false);
       tailLabel = `[middle omitted; selected excerpt — ${input.middle.label}, up to ${tailBudget} bytes]`;
@@ -168,10 +142,7 @@ export interface RecallSliceResult {
   eof: boolean;
 }
 
-/**
- * Trims multi-byte UTF-8 sequence from buffer boundary if cut mid-character.
- */
-export function trimUtf8End(buffer: Buffer, limit: number): number {
+function trimUtf8End(buffer: Buffer, limit: number): number {
   let end = limit;
   while (end > 0 && end < buffer.length && ((buffer[end] ?? 0) & 0xc0) === 0x80) {
     end -= 1;
@@ -179,9 +150,7 @@ export function trimUtf8End(buffer: Buffer, limit: number): number {
   return end;
 }
 
-/**
- * Slices a memory buffer safely at byte offsets without cutting UTF-8 characters.
- */
+/** Byte offsets, never cutting a UTF-8 character. */
 export function sliceBufferChunk(
   buf: Buffer,
   offset: number,
@@ -191,40 +160,30 @@ export function sliceBufferChunk(
     return { text: '', bytes: 0, lines: 0, nextOffset: buf.length, eof: true };
   }
 
-  const available = buf.length - offset;
-  let end = Math.min(available, limits.maxBytes);
+  let end = Math.min(buf.length - offset, limits.maxBytes);
   let newlineCount = 0;
-
   for (let i = 0; i < end; i++) {
-    if (buf[offset + i] === 0x0a) {
-      newlineCount++;
-      if (newlineCount === limits.maxLines) {
-        end = i + 1;
-        break;
-      }
+    if (buf[offset + i] === 0x0a && ++newlineCount === limits.maxLines) {
+      end = i + 1;
+      break;
     }
   }
 
-  const trimmedEnd = trimUtf8End(buf.subarray(offset), end);
-  const chunkBuf = buf.subarray(offset, offset + trimmedEnd);
+  const chunkBuf = buf.subarray(offset, offset + trimUtf8End(buf.subarray(offset), end));
   const text = chunkBuf.toString('utf8');
-  const bytes = chunkBuf.length;
-  const lines = countLines(text);
-  const nextOffset = offset + bytes;
-  const eof = nextOffset >= buf.length;
-
-  return { text, bytes, lines, nextOffset, eof };
+  const nextOffset = offset + chunkBuf.length;
+  return {
+    text,
+    bytes: chunkBuf.length,
+    lines: countLines(text),
+    nextOffset,
+    eof: nextOffset >= buf.length,
+  };
 }
 
 /**
- * Evaluates whether replacing an earlier message with a placeholder is profitable
- * under rolling prefix cache models.
- *
- * `cacheWriteReadRatio` must already be resolved by the caller via
- * `resolveCacheRatioFromCost` (same value OCC uses). It used to coerce
- * `'auto'|null` to a hardcoded 12.5 here, which silently diverged from OCC's
- * resolution and made OBS under-pack on implicit-cache models (2026-09-17
- * review: 20/72 packs deferred to sendCount 3–175).
+ * `cacheWriteReadRatio` must already be resolved by the caller via `resolveCacheRatioFromCost` (the
+ * same value OCC uses); a raw `'auto'` would silently diverge from OCC's resolution.
  */
 export function shouldPackForCache(opts: {
   removedTokens: number;
@@ -234,15 +193,8 @@ export function shouldPackForCache(opts: {
 }): boolean {
   if (opts.removedTokens <= 0) return false;
   const ratio = opts.cacheWriteReadRatio ?? TOKEN_ACCOUNT_CACHE_RATIO;
+  if (ratio <= 1.0) return true; // No incremental write cost over reads.
 
-  if (ratio <= 1.0) {
-    return true; // No incremental write cost over reads
-  }
-
-  const incrementalRatio = ratio - 1.0;
   const remaining = Math.max(1, opts.expectedRemainingRequests);
-  const benefitTokens = opts.removedTokens * remaining;
-  const costTokens = opts.tailTokensAfter * incrementalRatio;
-
-  return benefitTokens > costTokens;
+  return opts.removedTokens * remaining > opts.tailTokensAfter * (ratio - 1.0);
 }

package/src/pane-title.ts

@@ -1,39 +1,24 @@
-/**
- * Projects the pane todo snapshot into a herdr pane header/sidebar (M22, D62/D68).
- *
- * The pi session JSONL remains authoritative; this layer only condenses the snapshot into a title and blocked badge.
- * herdr truncates title/state_label to 80 characters, so truncate locally to avoid cutting an emoji in half.
- */
+/** Projects the pane todo snapshot into a herdr pane header/sidebar (M22, D62/D68); the pi session
+ *  JSONL stays authoritative and herdr truncates title/state_label at 80 chars, so truncate locally
+ *  to avoid cutting an emoji in half. */
 import { countTodos, PI_HERDR_META_KEY, type TodoItem } from './vocab.ts';
 import { formatAge, isArchived } from './stale-core.ts';
 
 /** herdr's character limit for title/state_label (from official documentation and schema measurements). */
-export const TITLE_MAX = 80;
-/** Empty list: callers send clear_title rather than an empty string. */
-export const TITLE_EMPTY = null;
-/**
- * Valid state_labels keys are only idle|working|blocked|done|unknown
- * (herdr socket-api; the early WIRE `todo` value was rejected as invalid_state_label).
- */
+const TITLE_MAX = 80;
+/** Valid state_labels keys are only idle|working|blocked|done|unknown (herdr socket-api). */
 export const BLOCKED_LABEL_KEY = 'blocked';
 
-/**
- * D93: custom sidebar token for the todo summary (referenced as `$pi-todo` by herdr `[ui.sidebar.agents]`).
- * Keep its value in the same format and source as the pane title (`▶i ○p ■b ✓c (N/M) · activity`).
- */
-export const SIDEBAR_TODO_TOKEN = 'pi-todo';
+/** D93: custom sidebar token for the todo summary, referenced as `$pi-todo` by herdr
+ *  `[ui.sidebar.agents]`; its value keeps the pane-title format (`▶i ○p ■b ✓c (N/M) · activity`). */
+const SIDEBAR_TODO_TOKEN = 'pi-todo';
 /** D95: token marking an ask_user_question wait (the workbench heat scale uses it to distinguish ask from block). */
 export const SIDEBAR_ASK_TOKEN = 'pi-ask';
 
-/**
- * D93: build the pi-todo token patch for report_metadata.
- * A title becomes the token value so the sidebar can render `$pi-todo`; no todo becomes an empty string so herdr's
- * patch semantics remove the key rather than retaining an old summary.
- *
- * D96 correction: **do not merge stale**. Stale (16 nulls) is a one-time cleanup sent separately via reportMetadata;
- * merging would make 17 entries exceed herdr's tokens maxProperties=16, rejecting the entire request and dropping
- * both title and tokens (observed on the user's machine: pane title and sidebar token disappeared; D93 regression root cause).
- */
+/** D93: build the pi-todo token patch for report_metadata (no todo = an empty string, because herdr's
+ *  patch semantics remove empty keys). D96: never merge the stale cleanup in here — stale(16) +
+ *  pi-todo(1) exceeds herdr's tokens maxProperties=16 and the rejected request would drop both the
+ *  title and the tokens. */
 export function sidebarTodoTokens(title: string | null): Record<string, string> {
   return { [SIDEBAR_TODO_TOKEN]: title ?? '' };
 }
@@ -45,20 +30,18 @@ function clipTitle(s: string): string {
 }
 
 /**
- * `▶i ○p ■b ✓c (N/M [~eta]) · <activity>` (D91 unifies the four black-and-white status glyphs).
- * activity is the first in_progress item, then fallbackDescription, then only the counts.
- * Empty list → null. progressSuffix (M16) is produced by formatProgressSuffix.
- *
- * Anti-freeze behavior (stale-core D): once all work is complete and the wall clock expires (archived), lower the
- * dead list to `✓N done <age>` instead of presenting it as a fully weighted current-state view; report_agent's tool
- * badge/activity line explains what is happening, while the todo token reports only the plan's actual state.
+ * `▶i ○p ■b ✓c (N/M [~eta]) · <activity>` (D91 unifies the four status glyphs). activity is the
+ * first in_progress item, then fallbackDescription, then only the counts. Empty list → null, which
+ * callers translate into clear_title; progressSuffix (M16) comes from formatProgressSuffix.
+ * Anti-freeze (stale-core D): once all work completed and the wall clock expired (archived), the
+ * dead list degrades to `✓N done <age>` instead of presenting itself as a current-state view.
  */
 export function formatPaneTitle(
   items: readonly TodoItem[],
   fallbackDescription?: string | null,
   opts?: { progressSuffix?: string | null; lastWriteAt?: number | null; now?: number },
 ): string | null {
-  if (items.length === 0) return TITLE_EMPTY;
+  if (items.length === 0) return null;
   const c = countTodos(items);
   const now = opts?.now ?? Date.now();
   if (isArchived(items, opts?.lastWriteAt ?? null, now)) {
@@ -82,9 +65,7 @@ export function formatBlockedLabel(items: readonly TodoItem[]): string | null {
   return clipTitle(text);
 }
 
-/**
- * The first post-upgrade report clears the old 16-key chunks (herdr merges tokens by key, so omitted nulls remain—M13b).
- */
+/** The first post-upgrade report clears the old 16-key chunks (herdr merges tokens by key, so omitted nulls would otherwise remain — M13b). */
 export function staleTokenClearance(): Record<string, null> {
   const tokens: Record<string, null> = { [PI_HERDR_META_KEY]: null };
   for (let i = 0; i < STALE_CHUNK_COUNT; i++) {