@mgiles/perk 2.3.0 → 3.1.0

package/extension/surfaces/surfaces.ts

@@ -1,40 +1,41 @@
 // The perk surfaces module. The one module that owns perk's UI
-// vocabulary per the TUI charter (`docs/design/tui-charter.md` §3–§5): the composed `perk` status
-// slot + widget slot keys, footer identity marks, the §5 glyph + theming vocabulary, the §4 height
-// bounds, the `createPerkStatus` composed-status handle + `setStandingWidget` widget setter, and
-// the pure format helpers the standing surfaces render with. The notify seam itself stays in
-// `report.ts` (re-exported here so "the surfaces module" is surfaces.ts + report.ts for the
-// surfaces guard).
+// vocabulary per the TUI charter (`docs/design/tui-charter.md` §3–§5): the single-value `perk`
+// status slot key, footer identity marks, the §5 glyph + theming vocabulary, the §4 height
+// bounds, the `createPerkStatus` status handle, and the pure format helpers the standing
+// surfaces render with. The notify seam itself stays in `report.ts` (re-exported here so "the
+// surfaces module" is surfaces.ts + report.ts for the surfaces guard).
 //
-// Composed status (charter §6 D2): perk presents ONE footer status under the single
-// `perk` slot — the objective + checkpoints segments composed in fixed charter order (objective
-// first), joined with two spaces. The per-feature status slots (`perk-checkpoints`,
-// `perk-objective`) and the `perk-objective` widget are retired (D8 sanctioned). The perk-owned
-// footer (`perkFooter`/`installPerkFooter` below) lifted this composition; the
-// composed `perk` status slot keeps publishing — it is the RPC-visible surface (setFooter is an
-// RPC no-op). A regression guard enforces this composition.
+// Perk status (charter §6 D2): perk presents ONE footer status under the single
+// `perk` slot — the single-value objective segment (the checkpoint substrate is retired, so
+// there is no composition step). The per-feature status slots and widgets are retired (D8
+// sanctioned). The perk-owned footer (`perkFooter`/`installPerkFooter` below) renders the value
+// directly; the `perk` status slot keeps publishing — it is the RPC-visible surface (setFooter
+// is an RPC no-op).
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ReportDetailSink } from "./report.ts";
 
 // `Key` is keybinding vocabulary (`pi.registerShortcut(Key.ctrlAlt("p"), …)`), not rich UI —
 // re-exported so pi-tui imports stay structurally confined to the surfaces module (the
 // surfacesGuard pi-tui import rule) without allowlisting the shortcut-registering modules.
 export { Key } from "@earendil-works/pi-tui";
 // Re-exports: the notify seam stays in report.ts; surfaces.ts is the one import for UI vocabulary.
-export { type ReportTarget, report, type Severity } from "./report.ts";
+export {
+  attachReportDetailSink,
+  type ReportDetailSink,
+  type ReportTarget,
+  report,
+  type Severity,
+} from "./report.ts";
 
 // --- standing-surface slot keys (charter §2) ---
-// The ONE composed status slot (D2): all perk status segments render under this key.
+// The ONE perk status slot (D2): perk's single status value renders under this key.
 export const STATUS_SLOT_PERK = "perk";
-// NOTE: same string as providers.ts PERK_CHECKPOINTS_PROVIDER_ID but a different concept
-// (UI slot vs provider id) — deliberately NOT merged.
-export const WIDGET_SLOT_CHECKPOINTS = "perk-checkpoints";
 
 // --- footer identity marks (charter §5 / D3: emoji are footer-only identity, 2 cells wide) ---
-export const MARK_CHECKPOINTS = "📋";
 export const MARK_OBJECTIVE = "🎯";
 
-// --- glyph vocabulary (charter §5 / D3) — data only; themed rendering lives in the widget/footer builders below ---
+// --- glyph vocabulary (charter §5 / D3) — charter-law data, pinned by tests ---
 export type GlyphKind = "done" | "current" | "pending" | "warning" | "failure";
 export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> = {
   done: { glyph: "✓", themeColor: "success" },
@@ -44,10 +45,9 @@ export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> =
   failure: { glyph: "✗", themeColor: "error" },
 };
 
-// --- height bounds (charter §4 / D1/D8) — enforced by the report() notify budget and the footer/widget builders ---
+// --- height bounds (charter §4 / D1/D8) — enforced by the report() notify budget and the footer builder ---
 export const NOTIFY_MAX_LINES = 1;
 export const FOOTER_MAX_LINES = 1;
-export const CHECKPOINTS_WIDGET_MAX_LINES = 4;
 
 // --- the standing-surface setter -----------------------------------------------------------------
 
@@ -61,48 +61,18 @@ export interface ThemeLike {
 }
 
 /**
- * A standing-widget component factory in pi's `setWidget` factory shape: invoked with the live
- * `(tui, theme)`, returns a component whose `render(width)` computes themed lines **per call**
- * (the D10 stateless-render pattern — never cache themed strings). NOTE: pi's RPC mode drops
- * factory widgets (only string[] forwards) — an accepted trade-off recorded in contracts.md.
- */
-export type StandingWidgetFactory = (
-  tui: unknown,
-  theme: ThemeLike,
-) => { render(width: number): string[]; invalidate(): void };
-
-/**
- * The minimal headless-aware surface the standing setters need. `ExtensionContext` satisfies it;
- * tests fake it (the same minimal-structural-interface recipe as report.ts's `ReportTarget` — see
+ * The minimal headless-aware surface the status handle needs — the `perk` status slot is the one
+ * standing surface it serves. `ExtensionContext` satisfies it; tests fake it (the same
+ * minimal-structural-interface recipe as report.ts's `ReportTarget` — see
  * `docs/learned/pi/extension-seams.md`).
  */
 export interface StandingTarget {
   hasUI: boolean;
   ui: {
     setStatus(slot: string, value: string | undefined): void;
-    setWidget(
-      slot: string,
-      value: string[] | StandingWidgetFactory | undefined,
-      options?: { placement?: "aboveEditor" | "belowEditor" },
-    ): void;
   };
 }
 
-/** Set (or clear, with undefined) a standing widget slot; no-op headless. */
-export function setStandingWidget(
-  target: StandingTarget,
-  slot: string,
-  widget: string[] | StandingWidgetFactory | undefined,
-  options?: { placement?: "aboveEditor" | "belowEditor" },
-): void {
-  if (!target.hasUI) return;
-  if (options?.placement) {
-    target.ui.setWidget(slot, widget, { placement: options.placement });
-  } else {
-    target.ui.setWidget(slot, widget);
-  }
-}
-
 // --- the working-message seam (vendored `whimsical`; charter §6 permitted text-only) ------------
 
 /**
@@ -128,61 +98,44 @@ export function setWorkingMessage(target: WorkingMessageTarget, message?: string
   target.ui.setWorkingMessage(message);
 }
 
-// --- the composed perk status (charter D2) --------------------------------------------
-
-/** A named segment of the composed `perk` status. Order is fixed by `PERK_SEGMENT_ORDER` (D2). */
-export type PerkSegmentKey = "objective" | "checkpoints";
-
-/** The charter D2 segment order: objective first, checkpoints second — never insertion order. */
-export const PERK_SEGMENT_ORDER = ["objective", "checkpoints"] as const;
-
-/** The two-space segment separator: `🎯 251 · 12.3k tok · 5m  📋 3/7 · ▸4`. */
-const PERK_SEGMENT_SEPARATOR = "  ";
+// --- the perk status (charter D2) --------------------------------------------
 
 /**
- * The composed-status handle: each controller publishes its segment text through `set`, and the
- * handle recomposes + republishes the single `perk` status slot. The footer reads
- * segments back via `get` and repaints via `subscribe` — the slot's `setStatus` dual-publish is
- * deliberate (RPC clients see the slot; setFooter is an RPC no-op).
+ * The single-value status handle: the objective publisher sets the one value through `set`, and
+ * the handle republishes the single `perk` status slot. The footer reads the value back via `get`
+ * and repaints via `subscribe` — the slot's `setStatus` dual-publish is deliberate (RPC clients
+ * see the slot; setFooter is an RPC no-op).
  */
 export interface PerkStatusHandle {
-  /** Set (or clear, with undefined) one segment; recomposes the slot. No-op headless. */
-  set(target: StandingTarget, segment: PerkSegmentKey, text: string | undefined): void;
-  /** The current text of one segment (undefined when unset). */
-  get(segment: PerkSegmentKey): string | undefined;
+  /** Set (or clear, with undefined) the one value; publishes the slot. No-op headless. */
+  set(target: StandingTarget, text: string | undefined): void;
+  /** The current text (undefined when unset). */
+  get(): string | undefined;
   /**
-   * Subscribe to recompositions: the listener fires after every headful `set` (headless `set`
+   * Subscribe to publishes: the listener fires after every headful `set` (headless `set`
    * calls are full no-ops, so nothing fires). Returns an unsubscribe.
    */
   subscribe(listener: () => void): () => void;
 }
 
 /**
- * Create the composed `perk` status handle (one per extension instance — created in index.ts and
- * passed to the controllers; no hidden module state). Headless calls are full no-ops (never touch
- * the segment map, so headless-era text can't resurrect in a later headful render). The composed
- * line is the ordered present segments joined with two spaces; an empty composition clears the
- * slot. No width handling: pi's footer truncates the joined status line itself.
+ * Create the single-value `perk` status handle (one per extension instance — created in index.ts
+ * and passed to the objective publisher; no hidden module state). Headless calls are full no-ops
+ * (never record the text, so headless-era text can't resurrect in a later headful render).
+ * `undefined` clears the slot. No width handling: pi's footer truncates the status line itself.
  */
 export function createPerkStatus(): PerkStatusHandle {
-  const segments = new Map<PerkSegmentKey, string>();
+  let value: string | undefined;
   const listeners = new Set<() => void>();
   return {
-    set(target, segment, text) {
+    set(target, text) {
       if (!target.hasUI) return;
-      if (text === undefined) {
-        segments.delete(segment);
-      } else {
-        segments.set(segment, text);
-      }
-      const composed = PERK_SEGMENT_ORDER.filter((key) => segments.has(key))
-        .map((key) => segments.get(key) as string)
-        .join(PERK_SEGMENT_SEPARATOR);
-      target.ui.setStatus(STATUS_SLOT_PERK, composed === "" ? undefined : composed);
+      value = text;
+      target.ui.setStatus(STATUS_SLOT_PERK, text);
       for (const listener of listeners) listener();
     },
-    get(segment) {
-      return segments.get(segment);
+    get() {
+      return value;
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -194,18 +147,16 @@ export function createPerkStatus(): PerkStatusHandle {
 // --- the perk-owned footer (charter D2) -----------------------------------------------
 
 /**
- * The raw material for one composed footer line. Left group (charter order 1–3): `identity`,
- * `objective`, `checkpoints` — the segments render verbatim (they carry their own 🎯/📋 marks).
+ * The raw material for one composed footer line. Left group (charter order 1–2): `identity`,
+ * `objective` — the segment renders verbatim (it carries its own 🎯 mark).
  * Right group (charter order 4, 5, +context, 6): `branch`, `model`, `thinking`, `cache`,
  * `context`, `guests` — right-aligned, non-segment system text dim-themed.
  */
 export interface FooterParts {
   /** e.g. `perk v0.0.1` — standing identity (D7), dim. */
   identity: string;
-  /** The 🎯 objective segment, verbatim (`handle.get("objective")`). */
+  /** The 🎯 objective segment, verbatim (`handle.get()`). */
   objective?: string;
-  /** The 📋 checkpoints segment, verbatim (`handle.get("checkpoints")`). */
-  checkpoints?: string;
   /** Git branch (dim); omitted when not in a repo. */
   branch?: string;
   /** Model id (dim); omitted when no model. */
@@ -231,28 +182,45 @@ export interface UsageEntryLike {
     role?: string;
     usage?: { input: number; cacheRead: number; cacheWrite: number };
   };
+  /** Entry-level usage on `branch_summary`/`compaction` entries (pi 0.81.0 usage accounting). */
+  usage?: { input: number; cacheRead: number; cacheWrite: number };
 }
 
 /**
  * The prompt-cache-hit rate of the latest usage-bearing assistant message, as a percentage —
- * an exact local mirror of pi's default-footer `CH` computation (pi's cache-stats helpers are
- * unexported; the `sanitizeGuestStatus` reimplementation precedent). Includes pi's display gate:
- * returns `null` unless the session shows cache activity (total cacheRead or cacheWrite > 0) AND
- * the latest usage-bearing assistant message has prompt tokens > 0 (a trailing zero-prompt-token
- * assistant message resets the rate, exactly like pi's `undefined`).
+ * an exact local mirror of pi 0.84.1's default-footer `CH` computation (pi's cache-stats helpers
+ * are unexported; the `sanitizeGuestStatus` reimplementation precedent). Includes pi's display
+ * gate: returns `null` unless the session shows cache activity — total cacheRead or cacheWrite
+ * > 0 summed over assistant messages, `toolResult` messages carrying `usage`, and
+ * `branch_summary`/`compaction` entries' entry-level `usage` — AND the latest usage-bearing
+ * assistant message has prompt tokens > 0 (a trailing zero-prompt-token assistant message resets
+ * the rate, exactly like pi's `undefined`). The CH VALUE always comes from the latest
+ * usage-bearing assistant message; the non-assistant entries only widen the activity gate.
  */
 export function latestCacheHitRate(entries: readonly UsageEntryLike[]): number | null {
   let totalCacheRead = 0;
   let totalCacheWrite = 0;
   let latest: number | null = null;
   for (const entry of entries) {
-    if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
-    const usage = entry.message.usage;
-    if (usage === undefined) continue;
-    totalCacheRead += usage.cacheRead;
-    totalCacheWrite += usage.cacheWrite;
-    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
-    latest = promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : null;
+    if (entry.type === "message" && entry.message?.role === "assistant") {
+      const usage = entry.message.usage;
+      if (usage === undefined) continue;
+      totalCacheRead += usage.cacheRead;
+      totalCacheWrite += usage.cacheWrite;
+      const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+      latest = promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : null;
+    } else if (entry.type === "message" && entry.message?.role === "toolResult") {
+      const usage = entry.message.usage;
+      if (usage === undefined) continue;
+      totalCacheRead += usage.cacheRead;
+      totalCacheWrite += usage.cacheWrite;
+    } else if (
+      (entry.type === "branch_summary" || entry.type === "compaction") &&
+      entry.usage !== undefined
+    ) {
+      totalCacheRead += entry.usage.cacheRead;
+      totalCacheWrite += entry.usage.cacheWrite;
+    }
   }
   if (totalCacheRead <= 0 && totalCacheWrite <= 0) return null;
   return latest;
@@ -279,11 +247,11 @@ function formatContextSegment(
 }
 
 /**
- * Compose THE one footer line (FOOTER_MAX_LINES = 1): left group = identity + objective +
- * checkpoints (two-space-joined, charter order); right group = branch + model + context + guests
+ * Compose THE one footer line (FOOTER_MAX_LINES = 1): left group = identity + objective
+ * (two-space-joined, charter order); right group = branch + model + context + guests
  * (two-space-joined), right-aligned with ≥2 spaces of padding. When the line exceeds `width`,
  * whole segments drop in the extended D9 order — guests (rightmost-first) → thinking → model →
- * branch → cache → context → checkpoints; `identity` and `objective` are NEVER dropped — then
+ * branch → cache → context; `identity` and `objective` are NEVER dropped — then
  * `truncateToWidth` as the last resort (ANSI- and 2-cell-emoji-aware).
  */
 export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: number): string {
@@ -294,12 +262,10 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     branch: true,
     cache: true,
     context: true,
-    checkpoints: true,
   };
   const compose = (): string => {
     const left = [theme.fg("dim", parts.identity)];
     if (parts.objective !== undefined) left.push(parts.objective);
-    if (keep.checkpoints && parts.checkpoints !== undefined) left.push(parts.checkpoints);
     const right: string[] = [];
     if (keep.branch && parts.branch !== undefined) right.push(theme.fg("dim", parts.branch));
     if (keep.model && parts.model !== undefined) right.push(theme.fg("dim", parts.model));
@@ -309,9 +275,9 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
       right.push(formatContextSegment(parts.context, theme));
     }
     for (const guest of keep.guests) right.push(theme.fg("dim", guest));
-    const leftText = left.join(PERK_SEGMENT_SEPARATOR);
+    const leftText = left.join("  ");
     if (right.length === 0) return leftText;
-    const rightText = right.join(PERK_SEGMENT_SEPARATOR);
+    const rightText = right.join("  ");
     const padding = Math.max(2, width - visibleWidth(leftText) - visibleWidth(rightText));
     return `${leftText}${" ".repeat(padding)}${rightText}`;
   };
@@ -323,7 +289,6 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     else if (keep.branch) keep.branch = false;
     else if (keep.cache) keep.cache = false;
     else if (keep.context) keep.context = false;
-    else if (keep.checkpoints) keep.checkpoints = false;
     else break; // identity + objective only — nothing left to drop
     line = compose();
   }
@@ -364,10 +329,16 @@ export type PerkFooterFactory = (
 /**
  * The perk-owned footer factory (charter D2): replaces pi's default footer wholesale with one
  * line in the intended split layout. `render` gathers everything live per call (D10 stateless
- * render): segments via the handle, branch/guests via `footerData` (excluding perk's own
- * `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the segments
+ * render): the objective value via the handle, branch/guests via `footerData` (excluding perk's
+ * own `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the value
  * directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
- * every handle recompose and on branch change; `dispose` detaches both.
+ * every handle recompose and on branch change; `dispose` detaches both. Lifecycle (pi ≥ 0.84,
+ * verified at 0.84.1): `setExtensionFooter` disposes a replaced factory's component, and pi's
+ * `resetExtensionUI` restores the built-in footer (disposing this one) on /reload and before
+ * session replacement — so installing a fresh factory per headful `session_start` leaks nothing.
+ *
+ * Two DELIBERATE divergences from pi's default footer remain: no `(auto)` context suffix
+ * (auto-compact state is not extension-readable) and no cost/`(sub)` segment (charter scope).
  */
 export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
   return (tui, theme, footerData) => {
@@ -382,8 +353,7 @@ export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
         const rate = deps.getCacheHitRate();
         const parts: FooterParts = {
           identity: deps.identity,
-          objective: deps.status.get("objective"),
-          checkpoints: deps.status.get("checkpoints"),
+          objective: deps.status.get(),
           branch: footerData.getGitBranch() ?? undefined,
           model: deps.getModelId() ?? undefined,
           thinking: deps.getThinkingLevel() ?? undefined,
@@ -404,7 +374,10 @@ export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
   };
 }
 
-/** Install the perk-owned footer (sole-owner law, D2); no-op headless. */
+/**
+ * Install the perk-owned footer (sole-owner law, D2); no-op headless. Safe to call on every
+ * headful `session_start`: pi ≥ 0.84 disposes the replaced factory (see `perkFooter`).
+ */
 export function installPerkFooter(
   target: { hasUI: boolean; ui: { setFooter(factory: PerkFooterFactory | undefined): void } },
   deps: PerkFooterDeps,
@@ -413,107 +386,15 @@ export function installPerkFooter(
   target.ui.setFooter(perkFooter(deps));
 }
 
-// --- format helpers (relocated from checkpoints.ts / objective.ts, verbatim) --------------------
-// Structural parameter types (not CheckpointState/CheckpointStep imports) keep surfaces.ts
-// dependency-free and avoid an import cycle with the surface controllers.
-
-export interface ProgressStep {
-  step: number;
-  text: string;
-  completed: boolean;
-}
-
-export interface ProgressState {
-  steps: ProgressStep[];
-  /** The in-progress step number, or `null`. */
-  current: number | null;
-}
-
-/** The `done/total` checkpoint progress summary (with `· ▸n` when a step is current). */
-export function progressLine(state: ProgressState): string {
-  const done = state.steps.filter((s) => s.completed).length;
-  const base = `${done}/${state.steps.length}`;
-  return state.current != null ? `${base} · ▸${state.current}` : base;
-}
-
-/** The `GLYPHS` kind for a step: done if completed, current if it IS the current step, else pending. */
-export function stepGlyphKind(state: ProgressState, s: ProgressStep): GlyphKind {
-  if (s.completed) return "done";
-  if (s.step === state.current) return "current";
-  return "pending";
-}
-
-/** A windowed progress item: a visible step, or an elision marker for the hidden steps. */
-export type ProgressWindowItem =
-  | { kind: "step"; step: ProgressStep }
-  | { kind: "elision"; hidden: number; side: "earlier" | "later" };
-
-/**
- * The D1 sliding window: at most `cap` step items (elision markers extra). For `n ≤ cap` all
- * steps show with no markers. Otherwise the window anchors on the current step (`current == null`
- * ⟹ all complete ⟹ anchor at the end) sitting second when possible — one earlier step above,
- * the rest below — with `… +N earlier` / `… +N later` markers for the hidden steps.
- */
-export function windowProgress(state: ProgressState, cap: number): ProgressWindowItem[] {
-  const n = state.steps.length;
-  if (n <= cap) return state.steps.map((step) => ({ kind: "step", step }));
-  const anchorIdx =
-    state.current != null
-      ? Math.max(
-          state.steps.findIndex((s) => s.step === state.current),
-          0,
-        )
-      : n - 1;
-  const start = Math.min(Math.max(anchorIdx - 1, 0), n - cap);
-  const items: ProgressWindowItem[] = [];
-  if (start > 0) items.push({ kind: "elision", hidden: start, side: "earlier" });
-  for (const step of state.steps.slice(start, start + cap)) items.push({ kind: "step", step });
-  const later = n - start - cap;
-  if (later > 0) items.push({ kind: "elision", hidden: later, side: "later" });
-  return items;
-}
-
-/**
- * The themed checkpoints-widget lines (charter D1/D3/D9/D10): the `windowProgress` window mapped
- * to `✓/▸/○ <n>. <text>` lines colored per the §5 table (completed text muted, elision markers
- * dim), every line width-truncated via pi-tui's `truncateToWidth` (ANSI- and wide-glyph-aware).
- * Pure per call — call it inside a component's `render()` so theming stays live (D10).
- */
-export function renderProgressLines(
-  state: ProgressState,
-  theme: ThemeLike,
-  width: number,
-): string[] {
-  return windowProgress(state, CHECKPOINTS_WIDGET_MAX_LINES).map((item) => {
-    if (item.kind === "elision") {
-      return truncateToWidth(theme.fg("dim", `… +${item.hidden} ${item.side}`), width);
-    }
-    return renderStepLine(state, item.step, theme, width);
-  });
-}
-
-/**
- * ONE themed per-step line (`✓/▸/○ <n>. <text>`, §5 colors, D9-truncated) — shared by the
- * checkpoints widget (`renderProgressLines`, windowed) and the checkpoint transcript marker's
- * expanded view (all steps, unwindowed), so the two surfaces render steps identically.
- */
-function renderStepLine(
-  state: ProgressState,
-  step: ProgressStep,
-  theme: ThemeLike,
-  width: number,
-): string {
-  const kind = stepGlyphKind(state, step);
-  const glyph = theme.fg(GLYPHS[kind].themeColor, GLYPHS[kind].glyph);
-  const text = `${step.step}. ${step.text}`;
-  const line = `${glyph} ${kind === "done" ? theme.fg("muted", text) : text}`;
-  return truncateToWidth(line, width);
-}
+// --- format helpers --------------------------------------------------------------------------
 
+/** Pi 0.84.1's default-footer `formatTokens` tiers, mirrored exactly (`200000` → `200k`). */
 function formatTokens(tokens: number): string {
   if (tokens < 1000) return `${tokens}`;
-  // Whole-k values render bare (`200k`, matching pi's footer); fractional keep one decimal.
-  return `${(tokens / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+  if (tokens < 10_000) return `${(tokens / 1000).toFixed(1)}k`;
+  if (tokens < 1_000_000) return `${Math.round(tokens / 1000)}k`;
+  if (tokens < 10_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  return `${Math.round(tokens / 1_000_000)}M`;
 }
 
 function formatElapsed(ms: number): string {
@@ -525,17 +406,31 @@ function formatElapsed(ms: number): string {
   return `${hr}h${min % 60}m`;
 }
 
-/** A compact one-line budget summary (e.g. `12.3k tok · 5m`). */
+/** A compact one-line budget summary (e.g. `12k tok · 5m`, `1.2M tok · 2h5m` past 1M). */
 export function formatBudgetLine(args: { tokens: number; elapsedMs: number }): string {
   return `${formatTokens(args.tokens)} tok · ${formatElapsed(args.elapsedMs)}`;
 }
 
-// --- the transcript markers — display-only entry renderers ---------------------------------------
-// The audit §2.3 verdict (docs/design/pi-adoption-audit.md): perk's four display-only custom-entry
-// families render as durable one-line transcript markers. Renderer BODIES live here (a transcript
-// renderer IS a rich-UI surface the surfaces module owns); registration is wiring at the feature
-// modules via the `registerTranscriptRenderer` seam below. Renderers are an interactive-TUI-only
-// concern (never invoked in json/RPC mode), so registration is inert-safe everywhere.
+// --- display-only transcript entry renderers -----------------------------------------------------
+// The audit §2.3 verdict (docs/design/pi-adoption-audit.md): perk's custom-entry families are
+// display-only. Most render as durable one-line transition markers; report detail is the generic
+// full-diagnostic family and always renders every logical row. Renderer BODIES live here (a
+// transcript renderer IS a rich-UI surface the surfaces module owns); registration is wiring at the
+// feature modules via the `registerTranscriptRenderer` seam below. Renderers are an
+// interactive-TUI-only concern (never invoked in json/RPC mode), so registration is inert-safe
+// everywhere.
+
+/** The generic display-only transcript entry carrying complete multiline warm-command reports. */
+export const REPORT_DETAIL_TYPE = "perk:report-detail";
+
+export interface ReportDetailEntryHost {
+  appendEntry(customType: string, data?: unknown): void;
+}
+
+/** Create the sink attached to each warm-command context by `registerPerkCommand`. */
+export function createReportDetailSink(host: ReportDetailEntryHost): ReportDetailSink {
+  return (text, severity) => host.appendEntry(REPORT_DETAIL_TYPE, { text, severity });
+}
 
 /** Structural slice of pi's `CustomEntry` — the only field the marker renderers read. */
 export interface TranscriptEntryLike {
@@ -585,15 +480,13 @@ export function registerTranscriptRenderer(
 
 /**
  * Charter budget: a COLLAPSED transcript marker is exactly one line. The expanded view is
- * human-requested scrollback and renders its full detail unbounded (all checkpoint steps, the
- * whole btw answer).
+ * human-requested scrollback and renders its full detail unbounded (the whole btw answer).
  */
 export const TRANSCRIPT_MARKER_MAX_LINES = 1;
 
 /**
  * The collapsed-marker grammar: the `report()` transition grammar `perk: <scope> — <message>`,
- * dim, D9-truncated. Emoji stay footer-only (D3); themed §5 glyphs appear only in expanded
- * checkpoint step lines.
+ * dim, D9-truncated. Emoji stay footer-only (D3).
  */
 function markerLine(scope: string, message: string, theme: ThemeLike, width: number): string {
   return truncateToWidth(theme.fg("dim", `perk: ${scope} — ${message}`), width);
@@ -605,44 +498,103 @@ function asRecord(value: unknown): Record<string, unknown> | null {
   return value as Record<string, unknown>;
 }
 
-/** Decode `{ steps }` from a `perk:checkpoint` entry: a non-empty array of valid steps, or null. */
-function decodeCheckpointSteps(data: unknown): ProgressStep[] | null {
-  const record = asRecord(data);
+function asPlainRecord(value: unknown): Record<string, unknown> | null {
+  const record = asRecord(value);
   if (record === null) return null;
-  const steps = record.steps;
-  if (!Array.isArray(steps) || steps.length === 0) return null;
-  const decoded: ProgressStep[] = [];
-  for (const raw of steps) {
-    const step = asRecord(raw);
-    if (step === null) return null;
-    if (
-      typeof step.step !== "number" ||
-      typeof step.text !== "string" ||
-      typeof step.completed !== "boolean"
-    ) {
-      return null;
+  const prototype = Object.getPrototypeOf(record);
+  if (prototype !== Object.prototype && prototype !== null) return null;
+  return record;
+}
+
+function skipControlString(text: string, start: number, osc: boolean): number {
+  let index = start;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if ((osc && code === 0x07) || code === 0x9c) return index + 1;
+    if (code === 0x1b && text.charCodeAt(index + 1) === 0x5c) return index + 2;
+    index += 1;
+  }
+  return index;
+}
+
+function skipControlSequence(text: string, start: number): number {
+  let index = start;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    index += 1;
+    if (code >= 0x40 && code <= 0x7e) break;
+  }
+  return index;
+}
+
+/** Strip terminal controls from the display projection; the persisted report text stays exact. */
+function stripTerminalControls(text: string): string {
+  let clean = "";
+  let index = 0;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if (code === 0x1b) {
+      const next = text.charCodeAt(index + 1);
+      if (next === 0x5b) {
+        index = skipControlSequence(text, index + 2);
+      } else if (next === 0x5d) {
+        index = skipControlString(text, index + 2, true);
+      } else if (next === 0x50 || next === 0x58 || next === 0x5e || next === 0x5f) {
+        index = skipControlString(text, index + 2, false);
+      } else {
+        index += 1;
+        while (index < text.length) {
+          const part = text.charCodeAt(index);
+          if (part < 0x20 || part > 0x2f) break;
+          index += 1;
+        }
+        const final = text.charCodeAt(index);
+        if (final >= 0x30 && final <= 0x7e) index += 1;
+      }
+      continue;
+    }
+    if (code === 0x9b) {
+      index = skipControlSequence(text, index + 1);
+      continue;
+    }
+    if (code === 0x9d) {
+      index = skipControlString(text, index + 1, true);
+      continue;
     }
-    decoded.push({ step: step.step, text: step.text, completed: step.completed });
+    if (code === 0x90 || code === 0x98 || code === 0x9e || code === 0x9f) {
+      index = skipControlString(text, index + 1, false);
+      continue;
+    }
+    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+      index += 1;
+      continue;
+    }
+    clean += text[index];
+    index += 1;
   }
-  return decoded;
+  return clean;
 }
 
 /**
- * `perk:checkpoint` marker. Collapsed: `perk: checkpoints — <done/total>`. Expanded: that line +
- * one §5 glyph line per step — ALL steps, unwindowed (scrollback is human-requested, so the
- * `CHECKPOINTS_WIDGET_MAX_LINES` standing budget does not apply). `current` is derived state that
- * lives in checkpoints.ts; a historical marker renders with `current: null` (bare `done/total`,
- * no `▸` step) — which keeps surfaces.ts free of checkpoint imports.
+ * `perk:report-detail` full diagnostic renderer. Unlike collapsed transition markers, report detail
+ * always renders every logical row; the expanded flag does not alter it. The first row carries the
+ * live severity color and continuation rows are dim. Blank rows remain blank.
  */
-export const checkpointEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
-  const steps = decodeCheckpointSteps(entry.data);
-  if (steps === null) return undefined;
-  const state: ProgressState = { steps, current: null };
+export const reportDetailEntryRenderer: TranscriptRenderer = (entry, _options, theme) => {
+  const data = asPlainRecord(entry.data);
+  if (data === null) return undefined;
+  const text = data.text;
+  const severity = data.severity;
+  if (typeof text !== "string" || text.trim().length === 0) return undefined;
+  if (severity !== "info" && severity !== "warning" && severity !== "error") return undefined;
   return {
     render(width) {
-      const collapsed = markerLine("checkpoints", progressLine(state), theme, width);
-      if (!options.expanded) return [collapsed];
-      return [collapsed, ...steps.map((step) => renderStepLine(state, step, theme, width))];
+      return text.split(/\r\n|\n|\r/).map((line, index) => {
+        const safeLine = stripTerminalControls(line);
+        if (safeLine.length === 0) return "";
+        const color = index === 0 && severity !== "info" ? severity : "dim";
+        return truncateToWidth(theme.fg(color, safeLine), width);
+      });
     },
   };
 };
@@ -769,17 +721,3 @@ export const btwThreadResetEntryRenderer: TranscriptRenderer = (entry, options,
     },
   };
 };
-
-/**
- * The coarse prose-plan widget line (relocated verbatim from checkpoints.ts's inline factory —
- * its only pi-tui usage): one dim, D9-truncated line naming the active plan with no `## Steps`
- * checklist.
- */
-export function renderCoarsePlanLines(planId: string, theme: ThemeLike, width: number): string[] {
-  return [
-    truncateToWidth(
-      theme.fg("dim", `Plan #${planId}: prose plan — no \`## Steps\` checklist`),
-      width,
-    ),
-  ];
-}