pi-pier 0.2.7 → 0.3.1

package/src/session-tail.ts

@@ -1,15 +1,13 @@
 /**
- * Tail parsing for pi session JSONL (pure library, v1.1 result channel).
- *
- * Since v1.1 (DESIGN.md §12), child-agent results come from the child session file
- * rather than pane text, keeping the authoritative machine-readable source free of
- * echo contamination and scrollback blind spots. This module depends only on the
- * empirically observed pi session format (session-format documentation):
+ * Tail parsing for pi session JSONL (pure): child-agent results come from the child session file,
+ * not pane text. Depends only on the pi session format:
  *   line = {type, id, parentId, message:{role, content:[{type:'text',text}...], timestamp, stopReason}}
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { sessionDirCandidates, sessionDirName } from './storage-layout.ts';
+import { piSessionDirCandidates, sessionDirName } from './storage-layout.ts';
+import { isValidSessionId } from './efficiency-store.ts';
+import { COMPACTION_INFLIGHT_TYPE, COMPACTION_SETTLED_TYPE } from './compact-coordinator.ts';
 
 export { sessionDirName };
 
@@ -25,7 +23,6 @@ export interface SessionEntryLike {
   message?: SessionMessageLike | unknown;
   [k: string]: unknown;
 }
-/** Parse line by line tolerantly, skipping malformed or non-JSON records. */
 export function parseSessionEntries(text: string): SessionEntryLike[] {
   const entries: SessionEntryLike[] = [];
   for (const line of (text ?? '').split(/\r?\n/)) {
@@ -35,7 +32,6 @@ export function parseSessionEntries(text: string): SessionEntryLike[] {
       const obj = JSON.parse(t);
       if (obj && typeof obj === 'object') entries.push(obj as SessionEntryLike);
     } catch {
-      /* Skip truncated or malformed records. */
     }
   }
   return entries;
@@ -61,10 +57,8 @@ function textOf(m: SessionMessageLike): string {
     .join('\n')
     .trim();
 }
-/**
- * Return the latest finalized assistant text (stopReason === 'stop'), excluding toolUse intermediates.
- * sinceTs filters out messages that predate the injection point.
- */
+/** Latest finalized assistant text (`stopReason === 'stop'`), excluding toolUse intermediates;
+ * `sinceTs` filters out messages predating the injection point. */
 export function lastAssistantText(
   entries: readonly SessionEntryLike[],
   opts: { sinceTs?: number } = {},
@@ -91,10 +85,29 @@ export function hasAssistantAfter(
   });
 }
 /**
- * Return whether an initiated toolCall still lacks a result after injection (for example,
- * ask_user_question waiting on human input), meaning settlement has not actually completed
- * (v1.3 M8 settlement-race fix). Parallel calls are tracked by depth.
+ * Whether the NEWEST assistant message after `sinceTs` ended its turn: a worker between tool calls
+ * has "an assistant message" but has NOT finished, so announcing it settled loses supervision of
+ * live work. `stopReason === 'toolUse'` means tools were requested; a non-string stopReason (still
+ * streaming / older shapes) counts as "not ended" on purpose.
  */
+export function lastAssistantTurnEnded(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): boolean {
+  let newest: { ts: number; stopReason: unknown } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (!newest || ts >= newest.ts) newest = { ts, stopReason: m.stopReason };
+  }
+  if (!newest) return false;
+  const sr = newest.stopReason;
+  return typeof sr === 'string' && sr !== 'toolUse' && sr !== 'pending';
+}
+/** Whether an initiated toolCall still lacks a result after injection (e.g. ask_user_question
+ * waiting on a human), meaning settlement has not completed. */
 export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs: number): boolean {
   let depth = 0;
   for (const entry of entries) {
@@ -113,12 +126,62 @@ export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs
   return depth > 0;
 }
 
+/** Derived settlement state of one child session, from the inject point onward. */
+export interface SubSessionState {
+  text: string | null;
+  pendingTool: boolean;
+  activity: boolean;
+  turnEnded: boolean;
+  /** True while the child is inside an OCC compaction cycle: from the inflight marker until an
+   * assistant message follows the settled marker. OCC's intentional abort lands as stopReason
+   * 'error', which the turnEnded check alone would misread as finished. */
+  compacting: boolean;
+}
+
+/**
+ * Whether the transcript currently sits inside an OCC compaction cycle. Last marker wins: inflight
+ * last means the summary request is running; settled last means the cycle is over — unless no
+ * assistant message follows it yet, in which case the worker is still machine-paused (not settled,
+ * not a user takeover). A cancelled cycle sends no continuation, so it is over at the marker.
+ */
+export function compactionBusy(entries: readonly SessionEntryLike[]): boolean {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (!entry || entry.type !== 'custom') continue;
+    const customType = entry.customType;
+    if (customType === COMPACTION_INFLIGHT_TYPE) return true;
+    if (customType === COMPACTION_SETTLED_TYPE) {
+      // A cancel sends no continuation turn, so waiting for one would pin the worker as busy forever.
+      if ((entry.data as { outcome?: unknown } | undefined)?.outcome === 'cancelled') return false;
+      for (let j = i + 1; j < entries.length; j++) {
+        if (messageOf(entries[j])?.role === 'assistant') return false;
+      }
+      return true;
+    }
+  }
+  return false;
+}
 
+/** Closing text is terminal by construction (lastAssistantText requires stopReason 'stop'); an
+ * assistant message alone is not a settlement — the turn must have ENDED. */
+export function deriveSubSessionState(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): SubSessionState {
+  const compacting = compactionBusy(entries);
+  const r = lastAssistantText(entries, { sinceTs });
+  if (r?.text) return { text: r.text, pendingTool: false, activity: true, turnEnded: true, compacting };
+  if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true, turnEnded: false, compacting };
+  if (hasAssistantAfter(entries, sinceTs)) {
+    return { text: null, pendingTool: false, activity: true, turnEnded: lastAssistantTurnEnded(entries, sinceTs), compacting };
+  }
+  return { text: null, pendingTool: false, activity: false, turnEnded: false, compacting };
+}
 
-/** Newest `limit` session files under cwd's session dir (new encoding, then legacy). */
+/** Newest `limit` session files under cwd's session dir (pi core's name first, then pier's old encodings). */
 export function listSessionFiles(cwd: string, agentDir: string, limit = 4): string[] {
   const files: Array<{ file: string; mtime: number }> = [];
-  for (const name of sessionDirCandidates(cwd)) {
+  for (const name of piSessionDirCandidates(cwd)) {
     const dir = path.join(agentDir, name);
     let names: string[];
     try {
@@ -140,13 +203,11 @@ export function listSessionFiles(cwd: string, agentDir: string, limit = 4): stri
   return files.slice(0, limit).map((f) => f.file);
 }
 
-/**
- * Locate a session file by id (`<ts>_<id>.jsonl`).
- * Searches the new encoding dir first, then the legacy flattened dir.
- */
+/** Locate a session file by id (`<ts>_<id>.jsonl`): pi core's directory name first, then pier's
+ * legacy flattened dirs. */
 export function sessionFileById(cwd: string, agentDir: string, id: string): string | null {
   const suffix = `_${id}.jsonl`;
-  for (const name of sessionDirCandidates(cwd)) {
+  for (const name of piSessionDirCandidates(cwd)) {
     const dir = path.join(agentDir, name);
     let names: string[];
     try {
@@ -161,6 +222,24 @@ export function sessionFileById(cwd: string, agentDir: string, id: string): stri
   return null;
 }
 
+/**
+ * Normalize a session path or id to the bare id used across herdr-pi state (`<timestamp>_<uuid>.jsonl`
+ * → `<uuid>`; `sub-session.jsonl` stays whole). Only pi's real transcript prefix is stripped, so
+ * arbitrary ids like PI_SESSION_FILE=sess_idx_prune survive untouched. Same-normalization comparisons
+ * (own session vs candidate paths) must go through here.
+ */
+export function bareSessionId(raw: string): string {
+  const base = raw.replaceAll('\\', '/').split('/').pop()!.replace(/\.jsonl$/, '');
+  const stripped = base.replace(/^\d{4}-\d{2}-\d{2}T[\d-]+Z_/, '');
+  return isValidSessionId(stripped) ? stripped : base;
+}
+
+/** Herdr reports session ids and paths interchangeably: accept a `.jsonl` path as-is, else map the id. */
+export function resolveSessionFileValue(cwd: string, agentDir: string, value: string | null | undefined): string | null {
+  if (!value) return null;
+  return /\.jsonl$/i.test(value) ? value : sessionFileById(cwd, agentDir, value);
+}
+
 export function readSessionFile(file: string): SessionEntryLike[] | null {
   try {
     return parseSessionEntries(fs.readFileSync(file, 'utf8'));

package/src/settle-wake-core.ts

@@ -1,16 +1,8 @@
 /**
- * Pure core for the settled-wake decision (prevents wake storms; evidenced by session 01a03bf0).
- *
- * Evidence chain: ESC abort → agent_settled → D96 "background subagents still running" notice
- * → sendUserMessage(followUp) (always starts a new run while idle) → master restarts → user presses ESC again → …
- * After 30 aborts, ESC never breaks the cycle; only Ctrl+C stops the process.
- * Natural settlement also forms a self-triggering loop: settle → notice → new run → settle → notice …
- *
- * Rules:
- *  - Abort suppression: when the previous assistant stopReason === 'aborted', this settled event injects no
- *    wake-up message (the user explicitly stopped it; settlement-buffered content waits for the next natural turn);
- *  - D96 deduplication: notify once for a given running paneId set; any set change (new subagent/settlement) resets it;
- *  - D96 cooldown: repeat a notice for the same set only after REPEAT_NOTICE_MS (otherwise the unchanged set is noise).
+ * Settled-wake decision (prevents wake storms): a settle wake that injects messages creates a
+ * self-triggering loop (settle → notice → new run → settle → …) that even ESC cannot break, so an
+ * aborted previous turn injects nothing and a running set is announced once, re-announced only after
+ * D96_REPEAT_NOTICE_MS or when the set changes.
  */
 
 export const ABORT_STOP_REASON = 'aborted';
@@ -19,37 +11,78 @@ export const ABORT_STOP_REASON = 'aborted';
 export const D96_REPEAT_NOTICE_MS = 10 * 60_000;
 
 export interface SettleWakeInput {
-  /** stopReason of the last assistant turn before this settlement (unknown = null, treated as natural completion). */
+  /** stopReason of the last assistant turn (null = treated as natural completion). */
   lastStopReason: string | null;
-  /** Background subagents still running (empty means none). */
+  /** True when abort was triggered intentionally by internal mechanisms like OCC. */
+  intentionalAbort?: boolean;
   running: ReadonlyArray<{ paneId: string }>;
-  /** Set key recorded for the previous D96 notice (none = null). */
   lastNoticeKey: string | null;
-  /** Timestamp of the previous D96 notice (epoch ms). */
   lastNoticeAt: number;
   now: number;
+  /**
+   * A compaction abort is already selected. turn_start clears intentionalAbort before agent_settled
+   * reads it, so this is the durable signal: do not inject a running-sub notice that compaction will abort.
+   */
+  compactionPending?: boolean;
 }
 
 export interface SettleWakePlan {
   /** false means this settlement stays silent and emits no wake-up message. */
   wake: boolean;
-  /** Whether to inject the D96 "still running" notice. */
+  /**
+   * Hand the settlement to the compaction coordinator. An OCC abort is silent (no wake) yet is the
+   * very settlement the selected compaction waits for; only a foreign (ESC) abort skips it.
+   */
+  compact: boolean;
   notice: boolean;
-  /** New set key (updated when notifying; empty running set → null). */
+  /** New set key; empty running set → null. */
   noticeKey: string | null;
   noticeAt: number;
 }
 
 export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
-  if (input.lastStopReason === ABORT_STOP_REASON) {
-    return { wake: false, notice: false, noticeKey: input.lastNoticeKey, noticeAt: input.lastNoticeAt };
+  if (input.compactionPending) {
+    return {
+      wake: false,
+      compact: true,
+      notice: false,
+      noticeKey: input.lastNoticeKey,
+      noticeAt: input.lastNoticeAt,
+    };
+  }
+  if (input.intentionalAbort || input.lastStopReason === ABORT_STOP_REASON) {
+    return {
+      wake: false,
+      compact: input.intentionalAbort === true,
+      notice: false,
+      noticeKey: input.lastNoticeKey,
+      noticeAt: input.lastNoticeAt,
+    };
   }
   const key = input.running.length === 0 ? null : input.running.map((s) => s.paneId).sort().join(',');
   if (key === null) {
-    return { wake: true, notice: false, noticeKey: null, noticeAt: input.lastNoticeAt };
+    return { wake: true, compact: true, notice: false, noticeKey: null, noticeAt: input.lastNoticeAt };
   }
   const newSet = key !== input.lastNoticeKey;
   const cooled = input.now - input.lastNoticeAt >= D96_REPEAT_NOTICE_MS;
   const notice = newSet || cooled;
-  return { wake: true, notice, noticeKey: key, noticeAt: notice ? input.now : input.lastNoticeAt };
+  return { wake: true, compact: true, notice, noticeKey: key, noticeAt: notice ? input.now : input.lastNoticeAt };
+}
+
+/**
+ * Whether a just-settled run may answer its pending machine request (the pipe settle fast-path).
+ * An OCC intentional abort and a still-running compaction both mean the continuation turn is
+ * coming: answering now reports "finished, no closing message" for live work and — worse —
+ * consumes the one-shot request plus the parent's claim latch, so the real closing message can
+ * never be delivered (observed: a worker mid-compaction announced finished; its final report
+ * never reached the parent). A user abort ('aborted') likewise settles a run that may re-run.
+ */
+export function shouldPushSettleReply(input: {
+  intentionalAbort?: boolean;
+  compactionInFlight?: boolean;
+  lastStopReason: string | null;
+}): boolean {
+  return !input.intentionalAbort
+    && !input.compactionInFlight
+    && input.lastStopReason !== ABORT_STOP_REASON;
 }

package/src/slim-frame.ts

@@ -1,38 +1,25 @@
 /**
- * D97 slim frame: when a pane is too narrow or short for the minimum usable TUI,
- * cover it with a non-capturing overlay. Content is three-tier: full TUI (overlay
- * hidden), an activity-anchored todo window when ≥3 rows fit, else the pane title.
+ * D97 slim frame: a pane too narrow/short for the minimum usable TUI gets a non-capturing overlay
+ * instead of a continuously repainting one — full TUI when it fits, an activity-anchored todo
+ * window when ≥3 rows fit, else the pane title. Content updates only on todo/status reports, so
+ * streaming thinking tokens can never reach it and the alt-screen diff produces no PTY output.
  *
- * Why (observed by the user): after the heat view compresses an unfocused pane, streaming worker thinking
- * continuously repaints the entire screen in the narrow pane, causing flicker. The static frame updates only on
- * todo_write/status reports (sharing arguments and source with formatPaneTitle), so thinking tokens cannot reach it;
- * alt-screen row-level diffing then produces zero PTY output and physically eliminates the flicker.
+ * Requires fullscreen TUI mode (buildLaunchParts injects it): the composite layer sits above the
+ * document, so only the alt-screen path can be covered. Registered only inside a herdr pane
+ * (PIER_SLIM_FRAME=0 opts out), as a process-local singleton whose overlay stays resident —
+ * `done()` is never called, so the pending promise is swallowed and never awaited.
  *
- * Prerequisite: worker/master run with --tui-mode fullscreen (injected by default by buildLaunchParts).
- * The regular main-screen full dump path (tui-main-screen firstChanged < viewportTop → full redraw) cannot be
- * covered by the overlay: composite is above the document, while the dump is inside the document.
- *
- * Registration gate: only inside a herdr pane (index.ts checks the environment), because covering an interactive
- * normal terminal window would be hazardous. Clicking a narrow herdr pane focuses it and the heat view expands it;
- * the visible predicate re-evaluates on every frame as SIGWINCH arrives, so the frame disappears automatically and
- * the real TUI remains underneath (agent/session/widget execution never stops).
- *
- * Lifecycle: one process-local singleton, registered once on session_start (not resume); the overlay stays resident
- * (done() is never called, leaving the Promise pending, swallowing rejection, and never awaiting it). If switching
- * pi sessions removes the overlay (resetExtensionUI), the static frame naturally exits without affecting the main
- * flow. PI_HERDR_SLIM_FRAME=0 is the escape hatch.
- * Resize watchdog (D98): the component owns a SIGWINCH listener plus a 1s size poll that call tui.requestRender() on
- * any PTY size change. Why: long-running sessions stop re-rendering on resize (observed in herdr — an idle master
- * shrunk by heat reflow froze on a stale clipped frame: no todo, no title), so pi's own resize wiring cannot be relied
- * on; columns/rows are read live per render, so one render is the whole fix. Stopped in dispose().
+ * Resize watchdog (D98): a SIGWINCH listener plus a 1 s poll, since long-running sessions stop
+ * re-rendering on resize; sizes are read live per render, both stop in dispose().
  */
 
 import { isArchived } from './stale-core.ts';
 import type { TodoItem } from './vocab.ts';
 import { anchorTodoRange, formatTodoSummary, renderTodoGroups } from './todo-window.ts';
+import { pierOption } from './pier-options.ts';
+import { styledWidth, wrapStyled } from './ansi-text.ts';
 
-/** Minimum usable TUI dimensions (pi interactive-mode layout: editor 3 rows + footer 1 + transcript ≥3 + spacing).
- * Below either threshold the pane cannot display a readable TUI, so the overlay covers it. */
+/** Minimum usable TUI dimensions (pi interactive-mode layout: editor 3 rows + footer 1 + transcript ≥3 + spacing). */
 
 export const SLIM_MIN_COLS = 24;
 export const SLIM_MIN_ROWS = 12;
@@ -50,107 +37,37 @@ export function isSlimFrame(cols: number, rows: number): boolean {
   return cols < SLIM_MIN_COLS || rows < SLIM_MIN_ROWS;
 }
 
-/* ── Width-aware wrapping (conservative East Asian width; ambiguous glyphs such as ▶○■✓ count as 1, affecting only break positions) ── */
-
-function isWide(cp: number): boolean {
-  return (
-    (cp >= 0x1100 && cp <= 0x115f) // Hangul compatibility jamo
-    || (cp >= 0x2e80 && cp <= 0xa4cf) // CJK radicals through Yi (including kana)
-    || (cp >= 0xac00 && cp <= 0xd7a3) // Hangul syllables
-    || (cp >= 0xf900 && cp <= 0xfaff) // CJK compatibility ideographs
-    || (cp >= 0xfe30 && cp <= 0xfe4f) // CJK compatibility forms
-    || (cp >= 0xff00 && cp <= 0xff60) // Fullwidth forms
-    || (cp >= 0xffe0 && cp <= 0xffe6)
-  );
-}
-
-export function displayWidth(s: string): number {
-  let w = 0;
-  for (const ch of s) w += isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
-  return w;
-}
-
-/**
- * Wrap at visible width: prefer word breaks (retreat to the last space instead of cutting an English phrase);
- * CJK text without spaces hard-wraps naturally. Consume the space at the break point.
- */
-export function wrapByWidth(text: string, width: number): string[] {
-  const w = Math.max(1, Math.floor(width));
-  const lines: string[] = [];
-  let line = '';
-  let lineW = 0;
-  const push = () => {
-    lines.push(line);
-    line = '';
-    lineW = 0;
-  };
-  for (const ch of text) {
-    const cw = isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
-    if (lineW + cw > w) {
-      const lastSpace = line.lastIndexOf(' ');
-      if (lastSpace > 0) {
-        lines.push(line.slice(0, lastSpace));
-        line = line.slice(lastSpace + 1) + ch;
-        lineW = displayWidth(line);
-      } else {
-        push();
-        line = ch;
-        lineW = cw;
-      }
-    } else {
-      line += ch;
-      lineW += cw;
-    }
-  }
-  if (line !== '' || lines.length === 0) lines.push(line);
-  return lines;
-}
-
-/**
- * Frame lines: wrap the title, center it vertically, and clamp to rows. Pad every line to full visible width:
- * row-wise overlay compositing would let the TUI underneath show through blank lines (leaking flicker),
- * while full-width spaces make the freeze genuinely opaque. Without a title, center one `·` (alive, no plan).
- */
+/** Frame lines: wrap the title, center it vertically, clamp to rows. Every line is padded to the
+ *  full visible width — row-wise compositing would otherwise let the TUI underneath show through
+ *  blank lines and leak the flicker this frame exists to hide. No title → one centered `·`. */
 export function frameLines(
   text: string,
   opts: { width: number; rows: number; colorize?: (s: string) => string },
 ): string[] {
   const width = Math.max(1, Math.floor(opts.width));
   const rows = Math.max(1, Math.floor(opts.rows));
-  const colorize = opts.colorize ?? ((s: string) => s);
-  const pad = (s: string) => s + ' '.repeat(Math.max(0, width - displayWidth(s)));
-
-  const body = text.trim()
-    ? wrapByWidth(text.trim(), width).slice(0, rows)
-    : ['·'];
-  const top = Math.max(0, Math.floor((rows - body.length) / 2));
-  const out: string[] = [];
-  for (let i = 0; i < rows; i++) {
-    const idx = i - top;
-    out.push(idx >= 0 && idx < body.length ? pad(colorize(body[idx])) : ' '.repeat(width));
-  }
-  return out;
+  const body = text.trim() ? wrapStyled(text.trim(), width).slice(0, rows) : ['·'];
+  return padFrame(body, { width, rows, colorize: opts.colorize ?? ((s: string) => s), vAlign: 'center' });
 }
 
 function padFrame(
   content: readonly string[],
   opts: { width: number; rows: number; colorize: (s: string) => string; vAlign: 'center' | 'top' },
 ): string[] {
-  const width = Math.max(1, Math.floor(opts.width));
-  const rows = Math.max(1, Math.floor(opts.rows));
-  const pad = (s: string) => s + ' '.repeat(Math.max(0, width - displayWidth(s)));
+  const { width, rows } = opts;
   const body = content.slice(0, rows);
   const top = opts.vAlign === 'center' ? Math.max(0, Math.floor((rows - body.length) / 2)) : 0;
   const out: string[] = [];
   for (let i = 0; i < rows; i++) {
     const idx = i - top;
-    out.push(idx >= 0 && idx < body.length ? pad(opts.colorize(body[idx])) : ' '.repeat(width));
+    const line = idx >= 0 && idx < body.length ? opts.colorize(body[idx]) : '';
+    out.push(line + ' '.repeat(Math.max(0, width - styledWidth(line))));
   }
   return out;
 }
 
 function wrapTodoBody(items: readonly TodoItem[], width: number): string[] {
-  return renderTodoGroups(items).flatMap((line) => wrapByWidth(line, width));
+  return renderTodoGroups(items).flatMap((line) => wrapStyled(line, width));
 }
 
 function itemsEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
@@ -172,10 +89,6 @@ export interface SlimFrameInput {
   now?: number;
 }
 
-/**
- * Choose overlay content: todo window when the pane can show ≥3 wrapped rows at ≥16 cols;
- * otherwise the pane title (or SLIM_EMPTY_COPY when the list is empty).
- */
 export function slimContentLines(
   input: SlimFrameInput & { width: number; rows: number; colorize?: (s: string) => string },
 ): string[] {
@@ -191,7 +104,7 @@ export function slimContentLines(
   if (items.length === 0) return titleFrame();
   if (isArchived(items, input.lastWriteAt ?? null, input.now ?? Date.now())) return titleFrame();
 
-  const header = wrapByWidth(formatTodoSummary(items), width);
+  const header = wrapStyled(formatTodoSummary(items), width);
   const fullBody = wrapTodoBody(items, width);
   if (header.length + fullBody.length <= rows) {
     const packed = [...header, ...fullBody];
@@ -199,7 +112,7 @@ export function slimContentLines(
     return padFrame(packed, { width, rows, colorize, vAlign: 'top' });
   }
 
-  const footerProbe = wrapByWidth('   +99 hidden (99✓) · /todos', width);
+  const footerProbe = wrapStyled('   +99 hidden (99✓) · /todos', width);
   const itemBudget = rows - header.length - footerProbe.length;
   if (itemBudget < 1) return titleFrame();
 
@@ -213,14 +126,12 @@ export function slimContentLines(
 
   const hidden = items.filter((_, i) => i < start || i >= end);
   const hiddenCompleted = hidden.filter((it) => it.status === 'completed').length;
-  const footer = wrapByWidth(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos`, width);
+  const footer = wrapStyled(`   +${hidden.length} hidden (${hiddenCompleted}✓) · /todos`, width);
   const packed = [...header, ...body, ...footer];
   if (packed.length < SLIM_TODO_MIN_ROWS) return titleFrame();
   return padFrame(packed, { width, rows, colorize, vAlign: 'top' });
 }
 
-/* ── Overlay component plus registration/update (process-local singleton) ─────────────────────────── */
-
 interface FrameTui {
   requestRender(): void;
 }
@@ -300,7 +211,6 @@ class SlimFrameComponent {
     this.tui.requestRender();
   };
 
-  /** Start the D98 watchdog (idempotent). SIGWINCH covers the delivered signal; the poll covers lost ones. */
   startResizeWatchdog(): void {
     if (this.poll) return;
     const size = this.viewportSize();
@@ -328,7 +238,6 @@ class SlimFrameComponent {
   }
 }
 
-
 /** Test injection point (reset module state); dispose first so an undisposed component's watchdog cannot leak. */
 export function resetForTest(): void {
   active?.dispose();
@@ -337,13 +246,10 @@ export function resetForTest(): void {
 
 let active: SlimFrameComponent | null = null;
 
-/**
- * Register the static-frame overlay (idempotent: once per process). eventCtx is the pi lifecycle event context
- * (the session_start ctx, sourced from the same place as the todo widget's widgetUi).
- */
+/** Register the static-frame overlay (idempotent, once per process) from the session_start ctx. */
 export function registerSlimFrame(eventCtx: unknown): void {
   if (active) return;
-  if (process.env.PI_HERDR_SLIM_FRAME === '0') return;
+  if (pierOption('PIER_SLIM_FRAME') === '0') return;
   const ui = eventCtx !== null && typeof eventCtx === 'object' && 'ui' in eventCtx
     ? eventCtx.ui
     : null;
@@ -353,8 +259,9 @@ export function registerSlimFrame(eventCtx: unknown): void {
   try {
     // overlay: true keeps the floating layer from clearing the screen (pi ctx.ui.custom replaces the editor area by default, so cover it explicitly);
     // nonCapturing leaves the keyboard with the editor (typing in a focused narrow pane remains possible, and the expanded heat view hides the frame).
+    if (!custom) throw new Error('pi ui.custom unavailable');
     const pending = custom(
-      (tui, theme) => {
+      (tui: FrameTui, theme: { fg(color: string, text: string): string }) => {
         const comp = new SlimFrameComponent(tui, (s) => theme.fg('accent', s));
         comp.startResizeWatchdog();
         active = comp;
@@ -371,14 +278,12 @@ export function registerSlimFrame(eventCtx: unknown): void {
         },
       },
     );
-    // Never call done(), leaving the Promise pending so the overlay stays resident; swallow rejection and never await it.
     Promise.resolve(pending).catch(() => {});
   } catch {
     /* Silently degrade on pi versions without overlay support. */
   }
 }
 
-/** Update overlay snapshot. Title remains the fallback; items drive the todo window. */
 export function updateSlimFrame(input: SlimFrameInput): void {
   active?.setSnapshot(input.title ?? '', input.items ?? [], input.lastWriteAt ?? null);
 }

package/src/stale-core.ts

@@ -1,50 +1,43 @@
 /**
- * Pure core for todo staleness (anti-freeze behavior, evidenced by session 01a03253).
+ * Anti-freeze core: a fully completed list that new work never updates must stop impersonating
+ * current state.
  *
- * Evidence: a fully completed list (3✓) froze for 16h / 37 turns while the model continued new work but made no
- * todo_write calls; rereading the dead list every read hook falsely endorsed "nothing to track," and the title
- * rendered dead counts at full weight. This module reduces whether a list still reflects reality to pure functions
- * consumed in three places:
- *  - stale (A): open==0 with ≥ STALE_TURNS turns since the last write → the read hook injects a rate-limited,
- *    capped stale warning;
- *  - archived (B): open==0 with wall-clock age ≥ STALE_CLOCK_MS since the last write → treat it as absent
- *    (injection/projection no longer rereads details; entries remain queryable through /todos; session JSONL stays authoritative);
- *  - title (D): when archived, pane/sidebar renders `✓N done <age>` instead of impersonating current state.
+ *  - stale (A): open==0 and ≥ STALE_TURNS turns since the last write → the read hook injects a
+ *    rate-limited, capped warning;
+ *  - archived (B): open==0 and age ≥ STALE_CLOCK_MS → the list is treated as absent;
+ *  - title (D): an archived list renders `✓N done <age>` instead of impersonating current state.
  *
- * A list with open items (pending/in_progress/blocked) is never stale: agent_settled continues to cover unfinished
- * work. When lastWriteAt is unknown (old sessions lack timestamps), conservatively do not archive on the clock axis;
- * the turns axis remains unaffected.
+ * A list with open items is never stale — agent_settled covers unfinished work. Unknown
+ * lastWriteAt (old sessions) conservatively suppresses the clock axis; turns is unaffected.
  */
 import { countTodos, type TodoItem } from './vocab.ts';
 
-/** A: turn-based expiry threshold (user turns counted from the last todo write). */
+/** A: turn-based expiry threshold, counted from the last todo write. */
 export const STALE_TURNS = 6;
 
-/** B: wall-clock archive threshold (age of the last write for a completed list). */
+/** B: age of the last write above which a completed list is archived. */
 export const STALE_CLOCK_MS = 60 * 60 * 1000;
 
-/** A: maximum stale warnings injected during one stalled period (prevent spin noise; archived changes to archive-notice cadence). */
+/** A: cap on stale warnings injected during one stalled period. */
 export const STALE_NOTICE_MAX = 3;
 
 export type StalenessKind = 'fresh' | 'stale' | 'archived';
 
 export interface Staleness {
   kind: StalenessKind;
-  /** open = pending + in_progress + blocked (abandoned does not count as unfinished). */
+  /** open = pending + in_progress + blocked (abandoned is not unfinished). */
   open: number;
-  /** now - lastWriteAt; unknown lastWriteAt → null. */
   ageMs: number | null;
 }
 
-/** Count open items: stale/archived apply only to fully completed (or fully abandoned) lists with open==0. */
 export function openTodos(items: readonly TodoItem[]): number {
-  const c = countTodos(items as TodoItem[]);
+  const c = countTodos(items);
   return c.pending + c.inProgress + c.blocked;
 }
 
 /**
- * Determine staleness (two conditions: turns → stale; wall clock → archived, with the clock taking precedence).
- * Empty list → fresh (a separate guard owns empty-list handling); null lastWriteAt → never stale (conservative).
+ * Clock (archived) takes precedence over turns (stale). Empty list → fresh (a separate guard owns
+ * empty-list handling); null lastWriteAt → never stale.
  */
 export function evaluateStaleness(opts: {
   items: readonly TodoItem[];
@@ -61,7 +54,7 @@ export function evaluateStaleness(opts: {
   return st;
 }
 
-/** For title/mirror paths without turn information: only evaluate wall-clock archive status. */
+/** Title/mirror paths have no turn information: only the wall-clock archive axis. */
 export function isArchived(
   items: readonly TodoItem[],
   lastWriteAt: number | null,
@@ -70,7 +63,7 @@ export function isArchived(
   return evaluateStaleness({ items, lastWriteAt, turnsSinceWrite: null, now }).kind === 'archived';
 }
 
-/** Age display: <60m → `Nm`; <48h → `Nh` (floor); otherwise `Nd`. */
+/** <60m → `Nm`; <48h → `Nh` (floor); otherwise `Nd`. */
 export function formatAge(ms: number): string {
   if (ms < 60 * 60_000) return `${Math.max(1, Math.floor(ms / 60_000))}m`;
   if (ms < 48 * 3_600_000) return `${Math.floor(ms / 3_600_000)}h`;