@mrclrchtr/supi-review 1.12.1 → 1.14.0

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
 
@@ -71,6 +72,14 @@ The built-in settings UI supports:
 - active-branch session helper: `getActiveBranchEntries()`
 - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
 ## Example
 
 ```ts
@@ -101,3 +110,4 @@ const message = wrapExtensionContext("my-extension", "hello", {
 - `src/config.ts` — shared config loading and writing
 - `src/config-settings.ts` — config-backed settings registration helper
 - `src/settings-ui.ts` — shared settings overlay
+- `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -44,9 +44,11 @@
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
+    "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
+    "./report": "./src/report.ts",
     "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
     "./session": "./src/session.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -13,12 +13,16 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./llm.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -0,0 +1,57 @@
+// Shared footer contribution registry for SuPi extensions.
+//
+// Extensions register pre-styled text chunks with a placement hint
+// ("stats" for the metrics line, "status" for the extension status line).
+// The custom footer in supi-extras (or PI's built-in footer) reads these
+// contributions and renders them alongside the built-in metrics.
+
+import { createRegistry } from "./registry-utils.ts";
+
+/** Where the contribution should appear in the footer. */
+export type FooterPlacement = "stats" | "status";
+
+/** A single footer contribution registered by an extension. */
+export interface FooterContribution {
+  /** Unique key for this contribution. Re-registering with the same key replaces it. */
+  key: string;
+  /** Which footer line this belongs on. */
+  placement: FooterPlacement;
+  /**
+   * Sort order within the placement (lower values render further left). Default: 100.
+   * Priority 0 is reserved for the turn cache-hit part so it stays adjacent to CH.
+   */
+  priority?: number;
+  /** Return the pre-styled text for this contribution. Called on every render. */
+  render: () => string;
+}
+
+const registry = createRegistry<FooterContribution>("footer-contributions");
+
+function sortByPriority(a: FooterContribution, b: FooterContribution): number {
+  return (a.priority ?? 100) - (b.priority ?? 100);
+}
+
+export const footerContributions = {
+  /** Register or replace a footer contribution. */
+  register(contribution: FooterContribution): void {
+    registry.register(contribution.key, contribution);
+  },
+
+  /** Remove a contribution (e.g. on session_shutdown or when disabled). */
+  unregister(key: string): void {
+    registry.unregister(key);
+  },
+
+  /** Get contributions for a specific placement, sorted by priority. */
+  getByPlacement(placement: FooterPlacement): FooterContribution[] {
+    return registry
+      .getAll()
+      .filter((c) => c.placement === placement)
+      .sort(sortByPriority);
+  },
+
+  /** Remove all contributions (primarily for tests). */
+  clear(): void {
+    registry.clear();
+  },
+};

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -13,10 +13,14 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -8,16 +8,38 @@ import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
+/** What the reviewer is currently doing and on what. */
+export interface CurrentFocus {
+  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
+  label: string;
+  /** Context detail (e.g. file path, search pattern, directory). */
+  detail: string;
+}
+
 /** Progress state for widget display, compatible with child-session updates. */
 export interface WidgetProgress {
   /** Number of agent turns completed. */
   turns: number;
   /** Number of tool executions started. */
   toolUses: number;
-  /** Human-readable active tool descriptions. */
-  activities: string[];
   /** Token usage stats, if available. */
-  tokens?: { input: number; output: number; total: number };
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: CurrentFocus;
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
 }
 
 // ── Widget ─────────────────────────────────────────────────────────────────
@@ -25,12 +47,12 @@ export interface WidgetProgress {
 /**
  * TUI progress widget for long-running operations.
  *
- * Shows an animated loader, turn count, tool uses, token count, and any active
- * tool descriptions while the child session or operation is running.
+ * Two-line layout: top line shows the narrative (current focus + file progress),
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
  */
 export class ProgressWidget extends Container {
   private message: string;
-  private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
+  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
   private loader: CancellableLoader;
   private tui: { requestRender(): void };
   private theme: Theme;
@@ -79,30 +101,89 @@ export class ProgressWidget extends Container {
 
   private renderContent(): void {
     this.clear();
+    this.renderTopLine();
+    this.renderBottomLine();
+  }
 
-    const stats: string[] = [];
-    if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
-    if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
-    if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
+  private renderTopLine(): void {
+    const topParts: string[] = [];
 
-    const loaderMessage =
-      stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
+    if (this.progress.currentFocus) {
+      const { label, detail } = this.progress.currentFocus;
+      topParts.push(detail ? `${label}: ${detail}` : label);
+    }
+
+    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
+      const inspected = this.progress.filesInspected ?? 0;
+      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
+    }
 
+    const loaderMessage =
+      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
     this.loader.setMessage(loaderMessage);
     this.addChild(this.loader);
+  }
+
+  private renderBottomLine(): void {
+    const stats: string[] = [];
+
+    this.appendTokenStats(stats);
+
+    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
+      stats.push(formatElapsed(this.progress.elapsedMs));
+    }
 
-    if (this.progress.activities.length > 0) {
-      this.addChild(
-        new Text(this.theme.fg("dim", `  ⎿  ${this.progress.activities.join(", ")}…`), 1, 0),
-      );
+    if (this.progress.turns > 0) {
+      stats.push(`⟳ ${this.progress.turns}`);
     }
+
+    if (this.progress.toolCounts) {
+      const parts = Object.entries(this.progress.toolCounts)
+        .filter(([, count]) => count > 0)
+        .sort(([, a], [, b]) => b - a)
+        .map(([label, count]) => `${count} ${label}`);
+      if (parts.length > 0) stats.push(parts.join(" · "));
+    }
+
+    if (stats.length > 0) {
+      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
+    }
+  }
+
+  private appendTokenStats(stats: string[]): void {
+    const tokens = this.progress.tokens;
+    if (!tokens) return;
+
+    stats.push(`↑ ${formatTokens(tokens.input)}`);
+    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
+      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
+    }
+    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
+      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
+    }
+    stats.push(`↓ ${formatTokens(tokens.output)}`);
   }
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-function formatTokens(count: number): string {
+export function formatTokens(count: number): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
   if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
   return String(count);
 }
+
+export function formatElapsed(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}

package/node_modules/@mrclrchtr/supi-core/src/registry-utils.ts

@@ -27,7 +27,7 @@ function getGlobalRegistryMap<T>(name: string): Map<string, T> {
  *
  * @typeParam T - The value type stored in the registry.
  * @param name - Unique registry name (used to construct the `Symbol.for` key).
- * @returns An object with `register`, `getAll`, and `clear` functions.
+ * @returns An object with `register`, `unregister`, `getAll`, and `clear` functions.
  */
 export function createRegistry<T>(name: string) {
   const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
@@ -40,6 +40,13 @@ export function createRegistry<T>(name: string) {
       getMap().set(id, value);
     },
 
+    /**
+     * Remove a registration by id. No-op if not registered.
+     */
+    unregister: (id: string): void => {
+      getMap().delete(id);
+    },
+
     /**
      * Get all registered values in registration order.
      */

package/node_modules/@mrclrchtr/supi-core/src/report.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Minimal theme surface required by the shared report helpers. */
+export type ReportTheme = Pick<Theme, "fg">;
+
+/** Color keys accepted by the report helpers. */
+export type ReportColor = Parameters<Theme["fg"]>[0];
+
+/** Options for rendering a themed key/value report row. */
+export interface KeyValueLineOptions {
+  /** The label shown on the left. */
+  label: string;
+  /** The value shown on the right. */
+  value: string;
+  /** Theme used for color formatting. */
+  theme: ReportTheme;
+  /** Maximum rendered width. */
+  width: number;
+  /** Left indentation in spaces. */
+  indent?: number;
+  /** Theme color applied to the label. Defaults to `"text"`. */
+  labelColor?: ReportColor;
+  /** Theme color applied to the value. Defaults to `"dim"`. */
+  valueColor?: ReportColor;
+  /** Separator placed between label and value. Defaults to `": "`. */
+  separator?: string;
+}
+
+/** Options for rendering a preview-overflow hint. */
+export interface OverflowHintOptions {
+  /** Optional follow-up hint such as `run /supi-context full`. */
+  hint?: string | null;
+  /** Left indentation in spaces. Defaults to `2`. */
+  indent?: number;
+}
+
+/** Ensure a report width never drops below the minimum readable width. */
+export function clampReportWidth(width: number, minWidth = 24): number {
+  return Math.max(minWidth, width);
+}
+
+/** Render a top-level report title line with theme color and truncation. */
+export function formatReportTitle(
+  title: string,
+  theme: ReportTheme,
+  width: number,
+  color: ReportColor = "accent",
+): string {
+  return truncateToWidth(theme.fg(color, title), width);
+}
+
+/**
+ * Render a section header with optional dimmed metadata.
+ *
+ * Example: `Usage by category  42.3k tokens`
+ */
+export function formatSectionHeader(
+  title: string,
+  meta: string | null,
+  theme: ReportTheme,
+  width: number,
+): string {
+  const left = theme.fg("text", title);
+  const content = meta ? `${left}${theme.fg("dim", `  ${meta}`)}` : left;
+  return truncateToWidth(content, width);
+}
+
+/** Render a single dimmed report line with optional left indentation. */
+export function formatDimLine(text: string, theme: ReportTheme, width: number, indent = 0): string {
+  const safeIndent = Math.max(0, indent);
+  return truncateToWidth(`${" ".repeat(safeIndent)}${theme.fg("dim", text)}`, width);
+}
+
+/** Render a dimmed preview-overflow hint such as `… and 3 more — run /foo full`. */
+export function formatOverflowHint(
+  hiddenCount: number,
+  theme: ReportTheme,
+  width: number,
+  options: OverflowHintOptions = {},
+): string {
+  const { hint = null, indent = 2 } = options;
+  const suffix = hint ? ` — ${hint}` : "";
+  return formatDimLine(`… and ${hiddenCount} more${suffix}`, theme, width, indent);
+}
+
+/** Render a single themed `label: value` row with truncation. */
+export function formatKeyValueLine(options: KeyValueLineOptions): string {
+  const {
+    label,
+    value,
+    theme,
+    width,
+    indent = 2,
+    labelColor = "text",
+    valueColor = "dim",
+    separator = ": ",
+  } = options;
+  const safeIndent = Math.max(0, indent);
+
+  return truncateToWidth(
+    `${" ".repeat(safeIndent)}${theme.fg(labelColor, label)}${separator}${theme.fg(valueColor, value)}`,
+    width,
+  );
+}
+
+/**
+ * Wrap a report text block to the available width and optionally prefix each line.
+ *
+ * This is useful for wrapped bullets or explanatory notes that should align
+ * under an existing report indent.
+ */
+export function wrapReportText(
+  text: string,
+  width: number,
+  options: { indent?: string } = {},
+): string[] {
+  const indent = options.indent ?? "";
+  const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indent.length));
+  return indent ? wrapped.map((line) => `${indent}${line}`) : wrapped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "SuPi Review extension — structured code review via /supi-review command",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.12.1"
+    "@mrclrchtr/supi-core": "1.14.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/tool/brief-runner.ts

@@ -84,7 +84,8 @@ function emitBriefProgress(
   invocation: BriefSynthesisInvocation,
 ): void {
   ctx.progress.tokens = buildProgressTokens(() => ctx.session.getSessionStats());
-  invocation.onProgress?.({ ...ctx.progress, activities: [...ctx.progress.activities] });
+  ctx.progress.elapsedMs = Date.now() - ctx.startTime;
+  invocation.onProgress?.(ctx.progress);
 }
 
 function handleAgentEnd(options: {
@@ -145,13 +146,14 @@ export async function runBriefSynthesis(
           break;
         case "tool_execution_start":
           ctx.progress.toolUses++;
-          ctx.progress.activities = [
-            event.toolName === "submit_review_brief" ? "submitting brief" : event.toolName,
-          ];
+          ctx.progress.currentFocus = {
+            label: event.toolName === "submit_review_brief" ? "Submitting brief" : event.toolName,
+            detail: "",
+          };
           emitBriefProgress(ctx, invocation);
           break;
         case "tool_execution_end":
-          ctx.progress.activities = [];
+          ctx.progress.currentFocus = undefined;
           emitBriefProgress(ctx, invocation);
           break;
         case "agent_end": {

package/src/tool/review-debug.ts

@@ -107,7 +107,6 @@ export function buildFailureDebug(input: BuildFailureDebugInput): ReviewFailureD
   return {
     turns: input.progress.turns,
     toolUses: input.progress.toolUses,
-    activities: input.progress.activities.length > 0 ? [...input.progress.activities] : undefined,
     tokens: input.progress.tokens,
     recentEvents: input.recentEvents.length > 0 ? [...input.recentEvents] : undefined,
     lastAssistantText: lastAssistant?.text,

package/src/tool/review-handlers.ts

@@ -38,27 +38,113 @@ export interface RunnerContext {
   timeoutSteered: boolean;
   graceTurnsRemaining: number | undefined;
   debug: { recentEvents: string[] };
+  /** Accumulated per-tool-label execution counts. */
+  toolCounts: Record<string, number>;
+  /** Set of distinct file paths inspected via read_snapshot_diff / read_snapshot_file. */
+  inspectedFiles: Set<string>;
+  /** Timestamp (ms) when the runner started, for elapsed-time display. */
+  startTime: number;
 }
 
 // ---------------------------------------------------------------------------
 // Tool and progress helpers
 // ---------------------------------------------------------------------------
 
-/** Maps tool names to human-readable activity descriptions. */
-function toolNameToActivity(name: string, phase: "start" | "end"): string {
-  if (phase === "end") return "";
+/** Maps tool names to compact display labels for the progress line. */
+function toolNameToLabel(name: string): string {
   const map: Record<string, string> = {
-    read: "reading",
-    grep: "searching",
-    find: "finding files",
-    ls: "listing files",
-    submit_review: "submitting review",
-    read_snapshot_diff: "reading diff",
-    read_snapshot_file: "reading file",
+    read: "reads",
+    grep: "greps",
+    find: "finds",
+    ls: "ls",
+    submit_review: "submits",
+    read_snapshot_diff: "diffs",
+    read_snapshot_file: "file-reads",
   };
   return map[name] ?? name;
 }
 
+/** Maps tool names to focus labels for the progress narrative line. */
+function toolNameToFocusLabel(name: string): string {
+  const map: Record<string, string> = {
+    read: "Reading",
+    grep: "Searching",
+    find: "Finding",
+    ls: "Listing",
+    submit_review: "Submitting review",
+    read_snapshot_diff: "Reading",
+    read_snapshot_file: "Reading",
+  };
+  return map[name] ?? name;
+}
+
+/** Extract the basename from a file path, or return the path unchanged. */
+function extractBasename(file: string): string {
+  const lastSlash = file.lastIndexOf("/");
+  return lastSlash >= 0 ? file.slice(lastSlash + 1) : file;
+}
+
+/** Truncate a focus detail string to a display-friendly length. */
+function truncateFocusDetail(value: string): string {
+  return value.length > 40 ? `${value.slice(0, 40)}…` : value;
+}
+
+/** Extract focus detail from a read-type tool (read, read_snapshot_diff, read_snapshot_file). */
+function tryExtractReadDetail(toolName: string, a: Record<string, unknown>): string | undefined {
+  const file = (a.file ?? a.path) as string | undefined;
+  if (!file) return undefined;
+  const name = extractBasename(file);
+  if (toolName === "read_snapshot_diff") return `${name} (diff)`;
+  if (toolName === "read_snapshot_file") return `${name} (full)`;
+  return name;
+}
+
+/** Extract a human-readable detail string from tool args for the focus display. */
+function tryExtractFocusDetail(toolName: string, args: unknown): string | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const a = args as Record<string, unknown>;
+
+  // submit_review is self-explanatory — no detail needed
+  if (toolName === "submit_review") return undefined;
+
+  // Read-type tools: extract file path, show basename only
+  if (
+    toolName === "read" ||
+    toolName === "read_snapshot_diff" ||
+    toolName === "read_snapshot_file"
+  ) {
+    return tryExtractReadDetail(toolName, a);
+  }
+
+  // grep: show the search pattern
+  if (toolName === "grep") {
+    const pattern = a.pattern as string | undefined;
+    return pattern ? truncateFocusDetail(pattern) : undefined;
+  }
+
+  // find: show the glob / pattern
+  if (toolName === "find") {
+    const pattern = (a.pattern ?? a.glob) as string | undefined;
+    return pattern ? truncateFocusDetail(pattern) : undefined;
+  }
+
+  // ls: show the listing path
+  if (toolName === "ls") {
+    const path = a.path as string | undefined;
+    return path ? truncateFocusDetail(path) : undefined;
+  }
+
+  return undefined;
+}
+
+/** Extract a file path from tool args when the tool is file-inspecting (for inspectedFiles tracking). */
+function tryExtractFileArg(toolName: string, args: unknown): string | undefined {
+  if (toolName !== "read_snapshot_diff" && toolName !== "read_snapshot_file") return undefined;
+  if (typeof args !== "object" || args === null) return undefined;
+  const file = (args as Record<string, unknown>).file;
+  return typeof file === "string" ? file : undefined;
+}
+
 export function createSubmitReviewTool(resultHolder: {
   value: ReviewOutputEvent | undefined;
 }): ReturnType<typeof defineTool> {
@@ -81,7 +167,11 @@ export function createSubmitReviewTool(resultHolder: {
 
 export function emitProgress(ctx: RunnerContext): void {
   ctx.progress.tokens = buildProgressTokens(() => ctx.session.getSessionStats());
-  ctx.invocation.onProgress?.({ ...ctx.progress, activities: [...ctx.progress.activities] });
+  ctx.progress.toolCounts = { ...ctx.toolCounts };
+  ctx.progress.filesInspected = ctx.inspectedFiles.size;
+  ctx.progress.filesTotal = ctx.invocation.snapshot.stats.files;
+  ctx.progress.elapsedMs = Date.now() - ctx.startTime;
+  ctx.invocation.onProgress?.(ctx.progress);
 }
 
 // ---------------------------------------------------------------------------
@@ -90,7 +180,6 @@ export function emitProgress(ctx: RunnerContext): void {
 
 export function handleTurnEnd(ctx: RunnerContext): void {
   ctx.progress.turns++;
-  ctx.progress.activities = [];
 
   if (!ctx.state.settled && ctx.timeoutSteered && ctx.graceTurnsRemaining !== undefined) {
     ctx.graceTurnsRemaining--;
@@ -108,8 +197,19 @@ export function handleToolStart(
   ctx: RunnerContext,
 ): void {
   ctx.progress.toolUses++;
-  const activity = toolNameToActivity(event.toolName, "start");
-  if (activity) ctx.progress.activities.push(activity);
+
+  const label = toolNameToLabel(event.toolName);
+  ctx.toolCounts[label] = (ctx.toolCounts[label] ?? 0) + 1;
+
+  const file = tryExtractFileArg(event.toolName, event.args);
+  if (file) ctx.inspectedFiles.add(file);
+
+  const focusDetail = tryExtractFocusDetail(event.toolName, event.args);
+  ctx.progress.currentFocus = {
+    label: toolNameToFocusLabel(event.toolName),
+    detail: focusDetail ?? "",
+  };
+
   ctx.invocation.onToolActivity?.({ toolName: event.toolName, phase: "start" });
   emitProgress(ctx);
 }
@@ -118,11 +218,7 @@ export function handleToolEnd(
   event: Extract<AgentSessionEvent, { type: "tool_execution_end" }>,
   ctx: RunnerContext,
 ): void {
-  const activity = toolNameToActivity(event.toolName, "start");
-  if (activity) {
-    const index = ctx.progress.activities.indexOf(activity);
-    if (index !== -1) ctx.progress.activities.splice(index, 1);
-  }
+  ctx.progress.currentFocus = undefined;
   ctx.invocation.onToolActivity?.({ toolName: event.toolName, phase: "end" });
   emitProgress(ctx);
 }

package/src/tool/review-runner.ts

@@ -201,6 +201,8 @@ function buildRunnerCtx(runner: ReviewerRunnerState): RunnerContext {
   ctx.timeoutSteered = runner.timeoutSteered;
   ctx.graceTurnsRemaining = runner.graceTurnsRemaining;
   ctx.debug = runner.debug;
+  ctx.toolCounts = {};
+  ctx.inspectedFiles = new Set();
   return ctx;
 }
 
@@ -214,6 +216,7 @@ function syncCtxFromLifecycle(
   ctx.resolve = lcCtx.resolve;
   ctx.cleanup = lcCtx.cleanup;
   ctx.state = lcCtx.state;
+  ctx.startTime = lcCtx.startTime;
   ctx.submitSteered = runner.submitSteered;
   ctx.timeoutSteered = runner.timeoutSteered;
   ctx.graceTurnsRemaining = runner.graceTurnsRemaining;

package/src/tool/runner-helpers.ts

@@ -42,8 +42,18 @@ export function extractAssistantText(content: unknown): string | undefined {
 
 /** Build a truncated string representation of session stats for progress. */
 export function buildProgressTokens(
-  getSessionStats: () => { tokens?: { input?: number; output?: number; total?: number } },
-): { input: number; output: number; total: number } | undefined {
+  getSessionStats: () => {
+    tokens?: {
+      input?: number;
+      output?: number;
+      total?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    };
+  },
+):
+  | { input: number; output: number; total: number; cacheRead?: number; cacheWrite?: number }
+  | undefined {
   try {
     const stats = getSessionStats();
     return stats?.tokens
@@ -51,6 +61,8 @@ export function buildProgressTokens(
           input: stats.tokens.input ?? 0,
           output: stats.tokens.output ?? 0,
           total: stats.tokens.total ?? 0,
+          cacheRead: stats.tokens.cacheRead,
+          cacheWrite: stats.tokens.cacheWrite,
         }
       : undefined;
   } catch {

package/src/tool/session-lifecycle.ts

@@ -27,6 +27,8 @@ export interface LifecycleCtx<TResult> {
    * Useful for custom timers or resources set up by `onTimeout`.
    */
   addTeardown: (fn: () => void) => void;
+  /** Timestamp (ms) when the lifecycle started, for elapsed-time display. */
+  startTime: number;
 }
 
 /** Configuration for `runWithLifecycle`. */
@@ -90,7 +92,6 @@ export function runWithLifecycle<TResult>(
   const progress: ReviewProgress = {
     turns: 0,
     toolUses: 0,
-    activities: [],
     tokens: undefined,
   };
   const state: { settled: boolean; aborting: boolean } = {
@@ -122,6 +123,8 @@ export function runWithLifecycle<TResult>(
     return result;
   };
 
+  const startTime = Date.now();
+
   return new Promise<TResult>((resolve) => {
     const ctx: LifecycleCtx<TResult> = {
       resolve,
@@ -130,6 +133,7 @@ export function runWithLifecycle<TResult>(
       state,
       session,
       addTeardown,
+      startTime,
     };
 
     session.subscribe((event: AgentSessionEvent) => {

package/src/types.ts

@@ -128,11 +128,12 @@ export interface ReviewPacket {
 export interface ReviewFailureDebugInfo {
   turns: number;
   toolUses: number;
-  activities?: string[];
   tokens?: {
     input: number;
     output: number;
     total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
   };
   recentEvents?: string[];
   lastAssistantText?: string;
@@ -200,10 +201,24 @@ export interface ReviewProgress {
   turns: number;
   /** Number of tool executions started. */
   toolUses: number;
-  /** Human-readable active tool descriptions. */
-  activities: string[];
   /** Token usage stats, if available. */
-  tokens?: { input: number; output: number; total: number };
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: { label: string; detail: string };
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
 }
 
 export type BriefSynthesisRunResult =

package/src/ui/format-content.ts

@@ -87,9 +87,6 @@ function appendDebugContent(parts: string[], debug: ReviewFailureDebugInfo | und
   const lines = [
     `- Turns: ${debug.turns}`,
     `- Tool uses: ${debug.toolUses}`,
-    debug.activities && debug.activities.length > 0
-      ? `- Active: ${debug.activities.join(", ")}`
-      : undefined,
     debug.tokens
       ? `- Tokens: ${debug.tokens.input} in / ${debug.tokens.output} out / ${debug.tokens.total} total`
       : undefined,

package/src/ui/renderer.ts

@@ -210,9 +210,6 @@ function renderFailureDebug(
 
   const lines = [
     `Turns: ${debug.turns} · Tool uses: ${debug.toolUses}`,
-    debug.activities && debug.activities.length > 0
-      ? `Active: ${debug.activities.join(", ")}`
-      : undefined,
     debug.tokens
       ? `Tokens: ${debug.tokens.input} in / ${debug.tokens.output} out / ${debug.tokens.total} total`
       : undefined,