pi-pier 0.2.7 → 0.3.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,43 +49,110 @@ 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;
   return typeof p === 'string' && p.trim() ? [p] : [];
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/**
+ * 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, 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
+  ];
+  for (const re of patterns) {
+    for (const m of command.matchAll(re)) {
+      const path = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+      const quoted = m[1] !== undefined || m[2] !== undefined;
+      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 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) {
+      const candidate = args[i]!;
+      if (candidate.startsWith('-')) continue;
+      if (isObviousPath(candidate)) found.push(candidate);
+      break;
+    }
+  }
+  return [...new Set(found)];
+}
+
+/** Only unquoted, metacharacter-free paths count as "obvious" (anything else is left to the shell). */
+function isObviousPath(path: string, quoted = false): boolean {
+  if (path === '' || path === '/' || path.startsWith('$')) return false;
+  if (/['"`$*?{}()[\]]/.test(path)) return false; // Never a literal path (expansion, glob, nested quotes).
+  return quoted ? true : !/\s/.test(path); // An explicitly quoted target may contain spaces.
+}
+
+/** Whitespace split that keeps quoted segments together and strips their quotes. */
+function splitShellWords(input: string): string[] {
+  const out: string[] = [];
+  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. */
+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.`;
+}
 
-export function findLockConflict(
+/** 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,
   normPath: string,
-): { holderPaneId: string } | null {
+): string[] {
   const key = lockTokenKey(normPath);
+  const holders: string[] = [];
   for (const a of agents) {
     const v = a.tokens[key];
     if (typeof v !== 'string' || !v) continue;
     const parsed = parseLockTokenValue(v);
-    if (parsed && parsed.holderPaneId !== ownPaneId) return { holderPaneId: parsed.holderPaneId };
+    if (parsed && parsed.holderPaneId !== ownPaneId && !holders.includes(parsed.holderPaneId)) {
+      holders.push(parsed.holderPaneId);
+    }
   }
-  return null;
+  return holders;
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** 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(', ')}`;
+}
+
+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' }
   | { kind: 'pass'; paths: string[] }
-  | { kind: 'warn'; paths: string[]; holderPaneId: string; warning: string }
-  | { kind: 'block'; paths: string[]; holderPaneId: string; reason: string };
+  | { kind: 'warn'; paths: string[]; holderPaneIds: string[]; warning: string }
+  | { kind: 'block'; paths: string[]; holderPaneIds: string[]; reason: string };
 
 export function planWriteGuard(opts: {
   toolName: string;
@@ -98,32 +162,33 @@ export function planWriteGuard(opts: {
   cwd: string;
   hard: boolean;
 }): WriteGuardPlan {
-  const raw = writePathsOfTool(opts.toolName, opts.input);
+  const isBash = opts.toolName === 'bash';
+  const raw = isBash
+    ? bashWriteTargets((opts.input as { command?: unknown } | null | undefined)?.command)
+    : writePathsOfTool(opts.toolName, opts.input);
   if (raw.length === 0) return { kind: 'skip' };
   const paths = raw.map((p) => normalizeLockPath(p, opts.cwd));
   for (const norm of paths) {
-    const conflict = findLockConflict(opts.agents, opts.ownPaneId, norm);
-    if (!conflict) continue;
-    if (opts.hard) {
+    const holders = findLockHolders(opts.agents, opts.ownPaneId, norm);
+    if (holders.length === 0) continue;
+    if (opts.hard && !isBash) {
       return {
         kind: 'block',
         paths,
-        holderPaneId: conflict.holderPaneId,
-        reason: `file locked by pane ${conflict.holderPaneId}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing.`,
+        holderPaneIds: holders,
+        reason: `file locked by ${holdersLabel(holders)}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing. ${LOCK_HOLDERS_HINT}`,
       };
     }
     return {
       kind: 'warn',
       paths,
-      holderPaneId: conflict.holderPaneId,
-      warning: formatConflictWarning(norm, conflict.holderPaneId),
+      holderPaneIds: holders,
+      warning: isBash ? formatBashLockHint(norm, holders) : formatConflictWarning(norm, holders),
     };
   }
   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);
@@ -135,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, holderPaneId: string): string {
-  return `⚠️ write conflict: ${normPath} is locked by pane ${holderPaneId} (it edited this file and has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes.`;
-}

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

@@ -0,0 +1,200 @@
+/**
+ * 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';
+
+// 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 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 {
+  return createHash('sha256').update(val).digest('hex');
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let lines = text.endsWith('\n') ? 0 : 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 0x0a) lines++;
+  }
+  return lines;
+}
+
+export function isObservationId(id: string): boolean {
+  return /^obs_[a-f0-9]{24}$/.test(id);
+}
+
+export function deriveObservationId(toolName: string, toolCallId: string, contentHash: string): string {
+  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 '';
+
+  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 {
+  id: string;
+  toolName: string;
+  bytes: number;
+  lines: number;
+  tokens: number;
+  text: string;
+  fullSends?: number;
+  excerptBudget?: number;
+  /**
+   * 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 };
+}
+
+function signalLineCount(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 0;
+  for (const line of text.split('\n')) {
+    if (FAILURE_SIGNAL.test(line)) count++;
+  }
+  return count;
+}
+
+export function formatObservationPlaceholder(input: ObservationPlaceholderInput): string {
+  const fullSends = input.fullSends ?? DEFAULT_FULL_SENDS;
+  const excerptBudget = input.excerptBudget ?? DEFAULT_EXCERPT_BYTES;
+  const headBudget = Math.floor(excerptBudget / 2);
+  const tailBudget = excerptBudget - headBudget;
+
+  let head = completeLineExcerpt(input.text, headBudget, false);
+  let tail = completeLineExcerpt(input.text, tailBudget, true);
+  let headLabel = `[first complete lines, up to ${headBudget} bytes]`;
+  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.
+    if (signalLineCount(tail) < signalLineCount(head)) {
+      tail = completeLineExcerpt(input.middle.text, tailBudget, false);
+      tailLabel = `[middle omitted; selected excerpt — ${input.middle.label}, up to ${tailBudget} bytes]`;
+    } else {
+      head = completeLineExcerpt(input.middle.text, headBudget, false);
+      headLabel = `[selected excerpt — ${input.middle.label}, up to ${headBudget} bytes]`;
+    }
+  }
+
+  return [
+    `[large tool result replaced after its first ${fullSends} provider requests]`,
+    `id: ${input.id}`,
+    `tool: ${input.toolName}`,
+    `original_bytes: ${input.bytes}`,
+    `original_lines: ${input.lines}`,
+    `estimated_tokens: ${input.tokens}`,
+    `retrieve: call obs_recall with {"id":"${input.id}","offset":0}; continue with returned next_offset`,
+    headLabel,
+    head,
+    tailLabel,
+    tail,
+    `[${input.bytes} original bytes omitted; recall via obs_recall]`,
+  ].join('\n');
+}
+
+export interface RecallSliceResult {
+  text: string;
+  bytes: number;
+  lines: number;
+  nextOffset: number;
+  eof: boolean;
+}
+
+function trimUtf8End(buffer: Buffer, limit: number): number {
+  let end = limit;
+  while (end > 0 && end < buffer.length && ((buffer[end] ?? 0) & 0xc0) === 0x80) {
+    end -= 1;
+  }
+  return end;
+}
+
+/** Byte offsets, never cutting a UTF-8 character. */
+export function sliceBufferChunk(
+  buf: Buffer,
+  offset: number,
+  limits: { maxBytes: number; maxLines: number },
+): RecallSliceResult {
+  if (offset >= buf.length) {
+    return { text: '', bytes: 0, lines: 0, nextOffset: buf.length, eof: true };
+  }
+
+  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 === limits.maxLines) {
+      end = i + 1;
+      break;
+    }
+  }
+
+  const chunkBuf = buf.subarray(offset, offset + trimUtf8End(buf.subarray(offset), end));
+  const text = chunkBuf.toString('utf8');
+  const nextOffset = offset + chunkBuf.length;
+  return {
+    text,
+    bytes: chunkBuf.length,
+    lines: countLines(text),
+    nextOffset,
+    eof: nextOffset >= buf.length,
+  };
+}
+
+/**
+ * `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;
+  tailTokensAfter: number;
+  expectedRemainingRequests: number;
+  cacheWriteReadRatio: number | null;
+}): 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.
+
+  const remaining = Math.max(1, opts.expectedRemainingRequests);
+  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++) {