pi-pier 0.3.0 → 0.4.1

package/src/slim-frame.ts

@@ -1,39 +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;
@@ -51,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 {
@@ -173,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[] {
@@ -192,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];
@@ -200,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();
 
@@ -214,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;
 }
@@ -301,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();
@@ -329,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();
@@ -338,10 +246,7 @@ 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 (pierOption('PIER_SLIM_FRAME') === '0') return;
@@ -373,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`;

package/src/storage-layout.ts

@@ -1,32 +1,20 @@
 /**
- * Storage path layout (history, session dirs, role dirs).
+ * Storage path layout (history, session dirs, role dirs) — the single owner of the session-dir
+ * encoding, so history-store / session-tail / role-loader cannot drift apart.
  *
- * Why: sessionDirName / historyFilePath / userRolesDir were duplicated across
- * history-store, session-tail, and role-loader. One module owns the encoding
- * so path conventions cannot drift.
- *
- * Writes use a collision-resistant encoding (`a/b` ≠ `a-b`). Reads prefer the
- * new name, then the legacy flattened name, so existing history/session dirs
- * stay reachable. If only the legacy dir exists, writes keep appending there
- * instead of splitting the ledger.
+ * Writes use a collision-resistant encoding (`a/b` ≠ `a-b`); reads try the new name, then the legacy
+ * flattened name, and when only the legacy dir exists writes keep appending there (no split ledger).
  */
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-/**
- * Legacy flattening (`--F--herdr-pi--`).
- * Why kept: `a/b` and `a-b` collide, but on-disk dirs already use this form.
- */
+/** Legacy flattening (`--F--herdr-pi--`): `a/b` and `a-b` collide, but on-disk dirs use this form. */
 export function sessionDirNameLegacy(cwd: string): string {
-  const flat = cwd.replace(/[\\/]/g, '-').replace(/:/g, '-');
-  return `--${flat}--`;
+  return `--${cwd.replace(/[\\/]/g, '-').replace(/:/g, '-')}--`;
 }
 
-/**
- * Collision-resistant session directory name.
- * `%` is escaped first so `/` `\` `:` round-trip: `a/b` → `--a%2Fb--`, `a-b` → `--a-b--`.
- */
+/** Collision-resistant name: `%` is escaped first so `/` `\` `:` round-trip (`a/b` → `--a%2Fb--`). */
 export function sessionDirName(cwd: string): string {
   const encoded = cwd
     .replace(/%/g, '%25')
@@ -36,7 +24,6 @@ export function sessionDirName(cwd: string): string {
   return `--${encoded}--`;
 }
 
-/** New encoding first, then legacy when they differ. */
 export function sessionDirCandidates(cwd: string): readonly string[] {
   const next = sessionDirName(cwd);
   const prev = sessionDirNameLegacy(cwd);
@@ -44,39 +31,26 @@ export function sessionDirCandidates(cwd: string): readonly string[] {
 }
 
 /**
- * pi core's own session-directory encoding, byte-for-byte.
- *
- * Why: `<agentDir>/sessions/` is owned by pi core, which names it
- * `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--` (strip ONE leading separator,
- * then flatten `/` `\` `:` — note it does NOT escape `%` like `sessionDirName` does).
- * Verified on this machine: `/Users/yehaoyu/Documents/pier` →
- * `--Users-yehaoyu-Documents-pier--` (pier's own encodings produce `---Users-…--` and
- * `--%2FUsers…--`, neither of which exists on disk).
+ * pi core's own session-directory encoding, byte-for-byte: strip ONE leading separator, then flatten
+ * `/` `\` `:` — it does NOT escape `%` like `sessionDirName`. `<agentDir>/sessions/` is pi core's
+ * directory, so reading pi sessions must match it exactly.
  */
 export function piCoreSessionDirName(cwd: string): string {
   return `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
 }
 
 /**
- * Candidates for reading pi core's session dirs: pi core's exact name first, then pier's
- * own historical encodings (they may hold stray dirs from earlier versions).
- * Read-only on purpose: writes to `<agentDir>/sessions/` are pi core's business.
+ * pi core's exact name first, then pier's own encodings (they may hold stray dirs from earlier
+ * versions). Read-only: writes to `<agentDir>/sessions/` are pi core's business.
  */
 export function piSessionDirCandidates(cwd: string): readonly string[] {
   return [...new Set([piCoreSessionDirName(cwd), ...sessionDirCandidates(cwd)])];
 }
 
-/**
- * Directory to read/write under `parent`.
- * Existing legacy dirs win over a missing new dir so history is not split.
- */
+/** Directory to read/write under `parent`: an existing legacy dir wins so history is not split. */
 export function preferredSessionDir(parent: string, cwd: string): string {
   const names = sessionDirCandidates(cwd);
-  for (const name of names) {
-    const dir = join(parent, name);
-    if (existsSync(dir)) return dir;
-  }
-  return join(parent, names[0]);
+  return names.map((name) => join(parent, name)).find(existsSync) ?? join(parent, names[0]!);
 }
 
 export function historyFilePath(agentRoot: string, cwd: string): string {
@@ -87,17 +61,14 @@ export function historyFilePathLegacy(agentRoot: string, cwd: string): string {
   return join(agentRoot, 'herdr-pi', 'history', sessionDirNameLegacy(cwd), 'history.jsonl');
 }
 
-/** Dual-read history path: existing ledger (legacy or new) else canonical new file. */
 export function preferredHistoryFile(agentRoot: string, cwd: string): string {
   return join(preferredSessionDir(join(agentRoot, 'herdr-pi', 'history'), cwd), 'history.jsonl');
 }
 
-/** User-global roles directory (`~/.pi/agent/herdr-pi/roles/`). */
 export function userRolesDir(): string {
   return join(homedir(), '.pi', 'agent', 'herdr-pi', 'roles');
 }
 
-/** Workspace-level roles directory (`<base>/.pi-herdr/roles/`). */
 export function workspaceRolesDir(baseDir: string): string {
   return join(baseDir, '.pi-herdr', 'roles');
 }