@pi-unipi/info-screen 2.2.1 → 2.4.0

package/README.md

@@ -76,8 +76,8 @@ Settings in pi `settings.json`:
 {
   "unipi": {
     "infoScreen": {
-      "showOnBoot": true,
-      "bootTimeoutMs": 8000,
+      "bootMode": "auto-close",
+      "bootTimeoutMs": 2000,
       "groups": {
         "modules": { "show": true },
         "ralph": { "show": true },
@@ -91,8 +91,8 @@ Settings in pi `settings.json`:
 
 | Setting | Default | What It Does |
 |---------|---------|--------------|
-| `showOnBoot` | true | Show dashboard when session starts |
-| `bootTimeoutMs` | 8000 | How long to wait for modules before showing |
+| `bootMode` | `"auto-close"` | `"on"` keeps the dashboard up until dismissed, `"auto-close"` closes it after `bootTimeoutMs`, `"off"` never shows it |
+| `bootTimeoutMs` | 2000 | Auto-close delay, in ms. Any keypress cancels it. Ignored unless `bootMode` is `"auto-close"` |
 | `groups.{id}.show` | true | Toggle group visibility |
 | `groupOrder` | priority sort | Custom group ordering |
 

package/config.ts

@@ -5,11 +5,11 @@
  * under the "unipi.info" key.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-import type { InfoScreenSettings, GroupSettings } from "./types.js";
-import { DEFAULT_SETTINGS } from "./types.js";
+import type { InfoScreenSettings, GroupSettings, BootMode } from "./types.js";
+import { DEFAULT_SETTINGS, BOOT_MODES } from "./types.js";
 
 /** Settings path */
 const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
@@ -44,9 +44,11 @@ function readSettingsFile(): Record<string, unknown> {
  * Write the full settings file.
  */
 function writeSettingsFile(data: Record<string, unknown>): void {
-  const dir = require("node:path").dirname(SETTINGS_PATH);
+  // These were require() calls in an ESM module, which throws under Node's
+  // module-format detection as soon as the directory is missing.
+  const dir = dirname(SETTINGS_PATH);
   if (!existsSync(dir)) {
-    require("node:fs").mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true });
   }
   writeFileSync(SETTINGS_PATH, JSON.stringify(data, null, 2) + "\n", "utf-8");
 }
@@ -68,7 +70,7 @@ export function getInfoSettings(): InfoScreenSettings {
   const info = unipi.info as Record<string, unknown>;
 
   cachedSettings = {
-    showOnBoot: typeof info.showOnBoot === "boolean" ? info.showOnBoot : DEFAULT_SETTINGS.showOnBoot,
+    bootMode: parseBootMode(info),
     bootTimeoutMs: typeof info.bootTimeoutMs === "number" ? info.bootTimeoutMs : DEFAULT_SETTINGS.bootTimeoutMs,
     groups: isRecord(info.groups) ? parseGroupSettings(info.groups) : {},
   };
@@ -76,6 +78,24 @@ export function getInfoSettings(): InfoScreenSettings {
   return cachedSettings;
 }
 
+/**
+ * Resolve the boot mode, migrating the legacy `showOnBoot` boolean.
+ *
+ * `showOnBoot: false` maps to "off". `showOnBoot: true` maps to "on" rather
+ * than the new "auto-close" default, so an existing config keeps behaving the
+ * way its owner configured it.
+ */
+function parseBootMode(info: Record<string, unknown>): BootMode {
+  const raw = info.bootMode;
+  if (typeof raw === "string" && (BOOT_MODES as string[]).includes(raw)) {
+    return raw as BootMode;
+  }
+  if (typeof info.showOnBoot === "boolean") {
+    return info.showOnBoot ? "on" : "off";
+  }
+  return DEFAULT_SETTINGS.bootMode;
+}
+
 /**
  * Parse group settings from raw object.
  */
@@ -118,7 +138,7 @@ export function saveInfoSettings(settings: InfoScreenSettings): void {
   }
 
   (file[SETTINGS_KEY] as Record<string, unknown>).info = {
-    showOnBoot: settings.showOnBoot,
+    bootMode: settings.bootMode,
     bootTimeoutMs: settings.bootTimeoutMs,
     groups: settings.groups,
   };

package/core-groups.ts

@@ -9,8 +9,9 @@ import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getPiVersion } from "@pi-unipi/core";
 import { infoRegistry } from "./registry.js";
-import { parseUsageStats, formatTokens, formatCost } from "./usage-parser.js";
+import { parseUsageStatsAsync, formatTokens, formatCost } from "./usage-parser.js";
 import type { InfoGroup } from "./types.js";
 
 /**
@@ -27,43 +28,6 @@ function getPackageVersion(packageDir: string): string {
   }
 }
 
-/**
- * Get pi version from its package.json.
- */
-function getPiVersion(): string {
-  // Try to find pi's package.json in various locations
-  const possiblePaths = [
-    // Global npm install
-    join(homedir(), ".local", "share", "mise", "installs", "node", "24.14.1", "lib", "node_modules", "@earendil-works", "pi-coding-agent", "package.json"),
-    // Alternative locations
-    join(homedir(), ".local", "share", "mise", "installs", "node", "lib", "node_modules", "@earendil-works", "pi-coding-agent", "package.json"),
-  ];
-
-  for (const pkgPath of possiblePaths) {
-    try {
-      if (existsSync(pkgPath)) {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-        return pkg?.version ?? "unknown";
-      }
-    } catch {
-      // Continue to next path
-    }
-  }
-
-  // Fallback: try to run pi --version
-  try {
-    const { execSync } = require("node:child_process");
-    const version = execSync("pi --version 2>/dev/null", { encoding: "utf-8" }).trim();
-    // Extract version number from output like "pi v0.42.4"
-    const match = version.match(/v([\d.]+)/);
-    if (match) return match[1];
-  } catch {
-    // Ignore
-  }
-
-  return "unknown";
-}
-
 /**
  * Discover loaded extensions by scanning filesystem.
  */
@@ -433,7 +397,9 @@ export function registerCoreGroups(): void {
       ],
     },
     dataProvider: async () => {
-      const stats = parseUsageStats();
+      // Async variant yields to the event loop between files, so a cold parse
+      // cannot block keystrokes or the initial paint.
+      const stats = await parseUsageStatsAsync();
 
       // Find top model for each period
       const findTopModel = (modelStats: Record<string, { tokens: number; cost: number; sessions: number }> | undefined) => {

package/index.ts

@@ -34,6 +34,10 @@ export default function (pi: ExtensionAPI) {
   // Start load tracking
   startLoadTracking();
 
+  // Whether an info overlay is currently on screen. Module announcements only
+  // trigger a re-fetch when something is actually displaying the result.
+  let overlayVisible = false;
+
   // Debounced MODULE_READY handling — batch module announcements
   // to prevent layout shift from rapid per-module cache invalidation.
   let moduleReadyBatch: Array<{ name: string; version: string; tools?: string[]; loadTimeMs?: number }> = [];
@@ -60,14 +64,18 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Single cache invalidation for all modules
+    // Single cache invalidation for all modules.
+    //
+    // Only re-fetch while an overlay is actually on screen. Otherwise this
+    // ran every module announcement even with the dashboard disabled,
+    // doing work nobody would see.
     infoRegistry.invalidateCache("overview");
-    infoRegistry.getGroupData("overview");
+    if (hasTools) infoRegistry.invalidateCache("tools");
 
-    if (hasTools) {
-      infoRegistry.invalidateCache("tools");
-      infoRegistry.getGroupData("tools");
-    }
+    if (!overlayVisible) return;
+
+    infoRegistry.getGroupData("overview");
+    if (hasTools) infoRegistry.getGroupData("tools");
   }
 
   // Listen for module announcements — track and trigger reactive updates
@@ -107,16 +115,22 @@ export default function (pi: ExtensionAPI) {
    * Cache-first: opens with whatever data is cached (even empty).
    * Background: each group fetches independently, overlay re-renders reactively.
    */
-  function showOverlay(ctx: ExtensionContext): void {
+  function showOverlay(ctx: ExtensionContext, autoCloseMs?: number): void {
     ctx.ui.custom<void>(
       (tui, theme, _keybindings, done) => {
         const overlay = new InfoOverlay();
         overlay.setTheme(theme);
+        overlayVisible = true;
         overlay.onClose = () => {
+          overlayVisible = false;
           overlay.destroy();
           done();
         };
         overlay.requestRender = () => tui.requestRender();
+        // Boot dashboard dismisses itself; any keypress cancels the timer.
+        if (autoCloseMs && autoCloseMs > 0) {
+          overlay.startBootTimer(autoCloseMs);
+        }
         return {
           render: (w: number) => overlay.render(w),
           invalidate: () => overlay.invalidate(),
@@ -142,9 +156,10 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (event, ctx) => {
     const settings = getInfoSettings();
 
-    if (settings.showOnBoot && event.reason === "startup") {
-      // Open immediately — cache-first, no waiting
-      showOverlay(ctx);
+    if (settings.bootMode !== "off" && event.reason === "startup") {
+      // Open immediately — cache-first, no waiting. In "auto-close" mode the
+      // overlay dismisses itself after bootTimeoutMs; any keypress cancels it.
+      showOverlay(ctx, settings.bootMode === "auto-close" ? settings.bootTimeoutMs : 0);
     }
 
     finishLoadTracking();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
   "type": "module",
   "main": "index.ts",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.2.0"
+    "@pi-unipi/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/settings/settings-tui.ts

@@ -9,7 +9,8 @@ import type { Component } from "@earendil-works/pi-tui";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { infoRegistry } from "../registry.js";
 import { getInfoSettings, saveInfoSettings, getGroupSettings, setGroupSettings } from "../config.js";
-import type { InfoScreenSettings, GroupSettings } from "../types.js";
+import type { InfoScreenSettings, GroupSettings, BootMode } from "../types.js";
+import { BOOT_MODES } from "../types.js";
 
 /** ANSI escape codes */
 const ansi = {
@@ -28,6 +29,13 @@ const ansi = {
 const TOGGLE_ON = `${ansi.green}●${ansi.reset}`;
 const TOGGLE_OFF = `${ansi.dim}○${ansi.reset}`;
 
+/** How each boot mode is presented in the settings list. */
+const BOOT_MODE_LABELS: Record<BootMode, string> = {
+  "on": `${ansi.green}● On${ansi.reset}`,
+  "auto-close": `${ansi.cyan}◐ Auto-close${ansi.reset}`,
+  "off": `${ansi.dim}○ Off${ansi.reset}`,
+};
+
 /**
  * Settings overlay component.
  */
@@ -36,7 +44,11 @@ export class SettingsOverlay implements Component {
   private groups: Array<{ id: string; name: string; icon: string }>;
   private selectedIndex = 0;
   /** Index of the "Show on boot" toggle row (above the group list). */
-  private static readonly BOOT_TOGGLE_INDEX = 0;
+  /** Row 0 cycles the boot mode; row 1 edits the auto-close delay. */
+  private static readonly BOOT_MODE_INDEX = 0;
+  private static readonly BOOT_TIMEOUT_INDEX = 1;
+  /** Number of settings rows rendered above the group list. */
+  private static readonly HEADER_ROWS = 2;
   private savedGroupIndex = 0; // Saved position before entering stats mode
   private mode: "groups" | "stats" = "groups";
   private selectedGroupId: string | null = null;
@@ -83,39 +95,54 @@ export class SettingsOverlay implements Component {
    * Handle input in groups mode.
    */
   private handleGroupsInput(data: string): void {
-    const lastIndex = this.groups.length; // boot toggle is index 0, groups occupy 1..length
+    const H = SettingsOverlay.HEADER_ROWS;
+    const rowCount = this.groups.length + H; // header rows, then groups
+    const onBootMode = this.selectedIndex === SettingsOverlay.BOOT_MODE_INDEX;
+    const onBootTimeout = this.selectedIndex === SettingsOverlay.BOOT_TIMEOUT_INDEX;
     switch (data) {
       case "\x1b[A": // Up
       case "k":
-        this.selectedIndex = (this.selectedIndex - 1 + (lastIndex + 1)) % (lastIndex + 1);
+        this.selectedIndex = (this.selectedIndex - 1 + rowCount) % rowCount;
         break;
       case "\x1b[B": // Down
       case "j":
-        this.selectedIndex = (this.selectedIndex + 1) % (lastIndex + 1);
+        this.selectedIndex = (this.selectedIndex + 1) % rowCount;
         break;
-      case " ": // Space - toggle
-        if (this.selectedIndex === SettingsOverlay.BOOT_TOGGLE_INDEX) {
-          this.toggleShowOnBoot();
+      case " ": // Space - toggle / cycle
+        if (onBootMode) {
+          this.cycleBootMode();
+        } else if (onBootTimeout) {
+          this.adjustBootTimeout(500);
         } else {
-          this.toggleGroupVisibility(this.groups[this.selectedIndex - 1].id);
+          this.toggleGroupVisibility(this.groups[this.selectedIndex - H].id);
         }
         break;
       case "\r": // Enter - enter stats mode
       case "\x1b[C": // Right - enter stats mode
       case "l":
-        if (this.selectedIndex === SettingsOverlay.BOOT_TOGGLE_INDEX) {
-          this.toggleShowOnBoot();
+        if (onBootMode) {
+          this.cycleBootMode();
+        } else if (onBootTimeout) {
+          this.adjustBootTimeout(500);
         } else {
-          this.enterStatsMode(this.groups[this.selectedIndex - 1].id);
+          this.enterStatsMode(this.groups[this.selectedIndex - H].id);
+        }
+        break;
+      case "\x1b[D": // Left - cycle back / decrease
+      case "h":
+        if (onBootMode) {
+          this.cycleBootMode(-1);
+        } else if (onBootTimeout) {
+          this.adjustBootTimeout(-500);
         }
         break;
       case "J": // Shift+J - move group down
-        if (this.selectedIndex > SettingsOverlay.BOOT_TOGGLE_INDEX) {
+        if (this.selectedIndex >= H) {
           this.moveGroupDown();
         }
         break;
       case "K": // Shift+K - move group up
-        if (this.selectedIndex > SettingsOverlay.BOOT_TOGGLE_INDEX) {
+        if (this.selectedIndex >= H) {
           this.moveGroupUp();
         }
         break;
@@ -195,11 +222,23 @@ export class SettingsOverlay implements Component {
     this.settings.groups[groupId] = groupSettings;
   }
 
+  /** Cycle the boot mode: on → auto-close → off → on. */
+  private cycleBootMode(step = 1): void {
+    const current = BOOT_MODES.indexOf(this.settings.bootMode);
+    const next = (current + step + BOOT_MODES.length) % BOOT_MODES.length;
+    this.settings.bootMode = BOOT_MODES[next]!;
+    saveInfoSettings(this.settings);
+  }
+
   /**
-   * Toggle the "show on boot" setting.
+   * Adjust the auto-close delay in 500ms steps.
+   *
+   * Clamped to a sane range: below 500ms the dashboard would vanish before it
+   * could be read, and beyond 30s "auto-close" stops meaning anything.
    */
-  private toggleShowOnBoot(): void {
-    this.settings.showOnBoot = !this.settings.showOnBoot;
+  private adjustBootTimeout(deltaMs: number): void {
+    const next = this.settings.bootTimeoutMs + deltaMs;
+    this.settings.bootTimeoutMs = Math.min(30_000, Math.max(500, next));
     saveInfoSettings(this.settings);
   }
 
@@ -217,8 +256,9 @@ export class SettingsOverlay implements Component {
    * Move selected group up in order.
    */
   private moveGroupUp(): void {
-    if (this.selectedIndex <= SettingsOverlay.BOOT_TOGGLE_INDEX + 1) return;
-    const i = this.selectedIndex - 1; // map back to groups array index
+    // Already the first group; nothing above it but the settings rows.
+    if (this.selectedIndex <= SettingsOverlay.HEADER_ROWS) return;
+    const i = this.selectedIndex - SettingsOverlay.HEADER_ROWS;
     // Swap with previous
     const temp = this.groups[i]!;
     this.groups[i] = this.groups[i - 1]!;
@@ -231,8 +271,9 @@ export class SettingsOverlay implements Component {
    * Move selected group down in order.
    */
   private moveGroupDown(): void {
-    if (this.selectedIndex >= this.groups.length) return; // boot toggle occupies 0, groups 1..length
-    const i = this.selectedIndex - 1; // map back to groups array index
+    // Header rows occupy 0..HEADER_ROWS-1; groups follow.
+    if (this.selectedIndex >= this.groups.length + SettingsOverlay.HEADER_ROWS - 1) return;
+    const i = this.selectedIndex - SettingsOverlay.HEADER_ROWS;
     // Swap with next
     const temp = this.groups[i]!;
     this.groups[i] = this.groups[i + 1]!;
@@ -283,16 +324,30 @@ export class SettingsOverlay implements Component {
     lines.push(`${ansi.dim}│${ansi.reset}${this.padToWidth(this.renderCentered(`${ansi.bold}⚙️  Info Screen Settings${ansi.reset}`, innerWidth), innerWidth)}${ansi.dim}│${ansi.reset}`);
     lines.push(`${ansi.dim}├${"─".repeat(innerWidth)}┤${ansi.reset}`);
 
-    // Group list
-    // Boot toggle row (index 0)
+    // Boot mode row (index 0)
     {
-      const isSelected = SettingsOverlay.BOOT_TOGGLE_INDEX === this.selectedIndex;
-      const isEnabled = this.settings.showOnBoot;
-      const toggle = isEnabled ? TOGGLE_ON : TOGGLE_OFF;
+      const isSelected = SettingsOverlay.BOOT_MODE_INDEX === this.selectedIndex;
       const indicator = isSelected ? `${ansi.cyan}▸${ansi.reset}` : " ";
-      let line = `  ${indicator} ${toggle} 🚀 Show on boot`;
+      const label = BOOT_MODE_LABELS[this.settings.bootMode];
+      let line = `  ${indicator} 🚀 Show on boot   ${ansi.bold}${label}${ansi.reset}`;
       if (isSelected) {
-        line += `  ${ansi.dim}→ toggle${ansi.reset}`;
+        line += `  ${ansi.dim}←/→ change${ansi.reset}`;
+      }
+      lines.push(`${ansi.dim}│${ansi.reset}${this.padToWidth(line, innerWidth)}${ansi.dim}│${ansi.reset}`);
+    }
+
+    // Auto-close delay row (index 1) — only meaningful in auto-close mode.
+    {
+      const isSelected = SettingsOverlay.BOOT_TIMEOUT_INDEX === this.selectedIndex;
+      const active = this.settings.bootMode === "auto-close";
+      const indicator = isSelected ? `${ansi.cyan}▸${ansi.reset}` : " ";
+      const seconds = `${(this.settings.bootTimeoutMs / 1000).toFixed(1)}s`;
+      const value = active ? `${ansi.bold}${seconds}${ansi.reset}` : `${ansi.dim}${seconds}${ansi.reset}`;
+      let line = active
+        ? `  ${indicator} ⏱️  Auto-close after ${value}`
+        : `  ${indicator} ${ansi.dim}⏱️  Auto-close after${ansi.reset} ${value}`;
+      if (isSelected && active) {
+        line += `  ${ansi.dim}←/→ ±0.5s${ansi.reset}`;
       }
       lines.push(`${ansi.dim}│${ansi.reset}${this.padToWidth(line, innerWidth)}${ansi.dim}│${ansi.reset}`);
     }
@@ -300,8 +355,8 @@ export class SettingsOverlay implements Component {
 
     for (let i = 0; i < this.groups.length; i++) {
       const group = this.groups[i];
-      // index 0 is the boot toggle; groups start at row index 1
-      const rowIndex = i + 1;
+      // Header rows occupy 0..HEADER_ROWS-1; groups follow.
+      const rowIndex = i + SettingsOverlay.HEADER_ROWS;
       const isSelected = rowIndex === this.selectedIndex;
       const groupSettings = getGroupSettings(group.id);
       const isEnabled = groupSettings.show;
@@ -324,7 +379,7 @@ export class SettingsOverlay implements Component {
 
     // Footer
     lines.push(`${ansi.dim}├${"─".repeat(innerWidth)}┤${ansi.reset}`);
-    lines.push(`${ansi.dim}│${ansi.reset}${this.padToWidth(this.renderCentered(`${ansi.dim}↑↓ select  Space toggle  Enter/→ stats  J/K reorder  q close${ansi.reset}`, innerWidth), innerWidth)}${ansi.dim}│${ansi.reset}`);
+    lines.push(`${ansi.dim}│${ansi.reset}${this.padToWidth(this.renderCentered(`${ansi.dim}↑↓ select  ←→ change  Space toggle  Enter stats  J/K reorder  q close${ansi.reset}`, innerWidth), innerWidth)}${ansi.dim}│${ansi.reset}`);
     lines.push(`${ansi.dim}╰${"─".repeat(innerWidth)}╯${ansi.reset}`);
 
     return lines;

package/tui/info-overlay.ts

@@ -15,6 +15,14 @@ import { getInfoSettings } from "../config.js";
 import type { InfoGroup, GroupData } from "../types.js";
 import { boxInnerWidth } from "@pi-unipi/core";
 
+/**
+ * How long to wait before warming the non-visible tabs.
+ *
+ * Long enough that startup and the first paint finish first, short enough that
+ * a tab switch a second later is already warm.
+ */
+const PREFETCH_DELAY_MS = 1500;
+
 /** Tab color palette */
 const TAB_FG: Array<"accent" | "success" | "warning" | "error"> = [
   "accent",
@@ -48,6 +56,10 @@ export class InfoOverlay implements Component {
   private lastGlobalUpdate = 0;
   private unsubscribers: Array<() => void> = [];
   private _destroyed = false;
+  /** Groups whose fetch has already been kicked off (lazy-load bookkeeping). */
+  private fetched = new Set<string>();
+  private prefetchTimer: ReturnType<typeof setTimeout> | null = null;
+  private bootTimer: ReturnType<typeof setTimeout> | null = null;
 
   onClose?: () => void;
   requestRender?: () => void;
@@ -89,31 +101,55 @@ export class InfoOverlay implements Component {
       })
     );
 
-    // Start background fetch for all groups (non-blocking)
-    this.fetchAllBackground();
+    // Fetch the visible tab now; everything else waits for idle.
+    this.fetchActiveGroup();
+    this.schedulePrefetch();
+  }
+
+  /** Fetch one group, tracking its loading state. Safe to call repeatedly. */
+  private fetchGroup(groupId: string): void {
+    if (this._destroyed) return;
+    if (this.fetched.has(groupId)) return;
+    this.fetched.add(groupId);
+    infoRegistry.getGroupData(groupId).then(() => {
+      this.groupLoading.set(groupId, false);
+    }).catch(() => {
+      this.groupLoading.set(groupId, false);
+    });
   }
 
   /**
-   * Fetch all groups in background. Each resolves independently.
+   * Fetch the currently visible group.
    *
-   * Each fetch is deferred to a macrotask (setTimeout 0) so the constructor
-   * returns immediately. Without this, getGroupData() runs each group's
-   * dataProvider synchronously up to its first `await` before yielding —
-   * heavy providers (usage stats parse 1GB+ of session files, memory scans)
-   * blocked the session_start handler for seconds.
+   * Deferred to a macrotask because an async dataProvider still runs
+   * synchronously up to its first `await`; calling it inline would put that
+   * work back on the constructor's caller (session_start).
    */
-  private fetchAllBackground(): void {
-    for (const group of this.groups) {
-      // Defer each fetch to a macrotask so the overlay constructs instantly.
-      setTimeout(() => {
-        if (this._destroyed) return;
-        infoRegistry.getGroupData(group.id).then(() => {
-          this.groupLoading.set(group.id, false);
-        }).catch(() => {
-          this.groupLoading.set(group.id, false);
-        });
-      }, 0);
-    }
+  private fetchActiveGroup(): void {
+    const group = this.groups[this.activeTabIndex];
+    if (!group) return;
+    setTimeout(() => this.fetchGroup(group.id), 0);
+  }
+
+  /**
+   * Warm the remaining tabs once the app is idle.
+   *
+   * Fetching every group up front cost seconds of startup for panels the user
+   * may never open. Prefetching after a delay keeps tab switches instant
+   * without paying for them before the first prompt is ready.
+   */
+  private schedulePrefetch(): void {
+    if (this.prefetchTimer) return;
+    this.prefetchTimer = setTimeout(() => {
+      this.prefetchTimer = null;
+      if (this._destroyed) return;
+      for (const group of this.groups) {
+        if (group.id === this.groups[this.activeTabIndex]?.id) continue;
+        this.fetchGroup(group.id);
+      }
+    }, PREFETCH_DELAY_MS);
+    // Never hold the process open just to warm a panel.
+    this.prefetchTimer.unref?.();
   }
 
   /**
@@ -127,29 +163,30 @@ export class InfoOverlay implements Component {
       this.applyOrder();
     }
 
-    // Ensure every group has real (non-empty) data.
-    // Registration notifications inject `{}` to trigger re-sync; we must
-    // not treat that as fetched data or the stats render as "—".
+    // Adopt any data the registry already has. Registration notifications
+    // inject `{}` to trigger a re-sync; that is not real data and must not be
+    // treated as fetched, or the stats render as "—".
+    //
+    // Groups are NOT fetched here: doing so would defeat lazy loading, since
+    // syncGroups() runs on every render. Fetches are driven by tab visibility
+    // (fetchActiveGroup) and the idle prefetch instead.
     for (const group of this.groups) {
       const existing = this.groupData.get(group.id);
       const hasRealData = existing && Object.keys(existing).length > 0;
-      if (!hasRealData) {
-        const cached = infoRegistry.getCachedData(group.id);
-        if (cached && Object.keys(cached).length > 0) {
-          this.groupData.set(group.id, cached);
-        } else if (!this.groupLoading.get(group.id)) {
-          this.groupLoading.set(group.id, true);
-          infoRegistry.getGroupData(group.id).then((data) => {
-            this.groupData.set(group.id, data);
-            this.groupLoading.set(group.id, false);
-            this.lastGlobalUpdate = Date.now();
-            this.requestRender?.();
-          }).catch(() => {
-            this.groupLoading.set(group.id, false);
-          });
-        }
+      if (hasRealData) continue;
+
+      const cached = infoRegistry.getCachedData(group.id);
+      if (cached && Object.keys(cached).length > 0) {
+        this.groupData.set(group.id, cached);
       }
     }
+
+    // A late-arriving group may now be the visible one, and the prefetch pass
+    // may have already run — make sure the active tab still gets its data.
+    if (hadNewGroups) {
+      this.fetchActiveGroup();
+      this.schedulePrefetch();
+    }
   }
 
   private applyOrder(): void {
@@ -169,23 +206,59 @@ export class InfoOverlay implements Component {
    */
   destroy(): void {
     this._destroyed = true;
+    this.cancelBootTimer();
+    if (this.prefetchTimer) {
+      clearTimeout(this.prefetchTimer);
+      this.prefetchTimer = null;
+    }
     for (const unsub of this.unsubscribers) {
       unsub();
     }
     this.unsubscribers = [];
   }
 
+  /** Stop the boot auto-close timer, if one is pending. */
+  private cancelBootTimer(): void {
+    if (this.bootTimer) {
+      clearTimeout(this.bootTimer);
+      this.bootTimer = null;
+    }
+  }
+
+  /**
+   * Auto-close the overlay after `ms`, unless the user interacts first.
+   *
+   * Used when the overlay is shown on boot: the dashboard is informational, so
+   * it should get out of the way on its own rather than requiring a keypress.
+   */
+  startBootTimer(ms: number): void {
+    this.cancelBootTimer();
+    if (!Number.isFinite(ms) || ms <= 0) return;
+    this.bootTimer = setTimeout(() => {
+      this.bootTimer = null;
+      if (this._destroyed) return;
+      this.destroy();
+      this.onClose?.();
+    }, ms);
+    this.bootTimer.unref?.();
+  }
+
   invalidate(): void {
     this.syncGroups();
   }
 
   handleInput(data: string): void {
+    // Any keypress means the user is driving; stop the boot auto-close.
+    this.cancelBootTimer();
+
     if (data === "\x1b[C" || data === "l") {
       this.activeTabIndex = (this.activeTabIndex + 1) % this.groups.length;
       this.scrollOffset = 0;
+      this.fetchActiveGroup();
     } else if (data === "\x1b[D" || data === "h") {
       this.activeTabIndex = (this.activeTabIndex - 1 + this.groups.length) % this.groups.length;
       this.scrollOffset = 0;
+      this.fetchActiveGroup();
     } else if (data === "\x1b[B" || data === "j") {
       this.scrollOffset++;
     } else if (data === "\x1b[A" || data === "k") {
@@ -211,12 +284,15 @@ export class InfoOverlay implements Component {
     if (!group) return;
     this.groupLoading.set(group.id, true);
     this.requestRender?.();
+    // Explicit refresh must bypass the lazy-load guard.
+    this.fetched.add(group.id);
     infoRegistry.refreshGroup(group.id);
   }
 
   private refreshAll(): void {
     for (const group of this.groups) {
       this.groupLoading.set(group.id, true);
+      this.fetched.add(group.id);
     }
     this.requestRender?.();
     infoRegistry.refreshAll();

package/types.ts

@@ -47,11 +47,26 @@ export interface InfoGroup {
   dataProvider: () => Promise<GroupData>;
 }
 
+/** How the dashboard behaves at startup. */
+export type BootMode = "on" | "off" | "auto-close";
+
+/** All valid boot modes, in the order the settings UI cycles them. */
+export const BOOT_MODES: BootMode[] = ["on", "auto-close", "off"];
+
 /** Settings for info-screen in settings.json */
 export interface InfoScreenSettings {
-  /** Whether to show dashboard on boot */
-  showOnBoot: boolean;
-  /** Timeout in ms waiting for modules at boot */
+  /**
+   * What the dashboard does at startup:
+   *  - "on":         show it and leave it up until dismissed (q/Esc)
+   *  - "off":        do not show it at all (no data is fetched)
+   *  - "auto-close": show it, then close after `bootTimeoutMs`
+   */
+  bootMode: BootMode;
+  /**
+   * How long the boot dashboard stays up in "auto-close" mode, in ms.
+   * Any keypress cancels the timer and keeps the overlay open.
+   * Does not apply to the overlay opened via /unipi:info.
+   */
   bootTimeoutMs: number;
   /** Per-group settings */
   groups: Record<string, GroupSettings>;
@@ -69,8 +84,8 @@ export interface GroupSettings {
 
 /** Default settings */
 export const DEFAULT_SETTINGS: InfoScreenSettings = {
-  showOnBoot: true,
-  bootTimeoutMs: 8000,
+  bootMode: "auto-close",
+  bootTimeoutMs: 2000,
   groups: {},
   groupOrder: [],
 };

package/usage-parser.ts

@@ -5,8 +5,8 @@
  * Reference: tmustier/pi-extensions/usage-extension
  */
 
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
-import { join, basename } from "node:path";
+import { readdirSync, readFileSync, statSync, existsSync, mkdirSync, writeFileSync, renameSync, openSync, readSync, closeSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
 import { homedir } from "node:os";
 
 /** Usage data for a single message */
@@ -54,6 +54,75 @@ interface PeriodBounds {
   end: Date;
 }
 
+/**
+ * A single usage record, stored in the cache in compact tuple form.
+ *
+ * [timestamp, hashTokens, countedTokens, cost, modelIndex, counted]
+ *
+ * `hashTokens` is input+output+cacheRead+cacheWrite and exists ONLY to rebuild
+ * the dedup key. `countedTokens` is input+output+cacheWrite, which is what the
+ * totals actually sum (cacheRead is deliberately excluded).
+ *
+ * `counted` (1/0) mirrors the original `input > 0 || output > 0 || cost > 0`
+ * check. It must be stored separately because the original claims the dedup
+ * hash BEFORE applying that filter — so a zero-usage message still suppresses
+ * a later duplicate. Collapsing the two would change the totals.
+ */
+type UsageRecord = [number, number, number, number, number, number];
+
+/** Per-file cache entry, invalidated on mtime or size change. */
+interface CachedFile {
+  mtimeMs: number;
+  size: number;
+  records: UsageRecord[];
+}
+
+interface UsageCacheFile {
+  version: number;
+  /** Interned model names; records store an index into this array. */
+  models: string[];
+  files: Record<string, CachedFile>;
+}
+
+/**
+ * Bump when the record layout or parsing semantics change, so stale caches
+ * from an older build are discarded rather than silently reused.
+ */
+const CACHE_VERSION = 1;
+
+function getCachePath(): string {
+  const base = process.env.UNIPI_DIR || join(homedir(), ".unipi");
+  return join(base, "cache", "usage-stats.json");
+}
+
+function readCache(): UsageCacheFile {
+  const empty: UsageCacheFile = { version: CACHE_VERSION, models: [], files: {} };
+  try {
+    const path = getCachePath();
+    if (!existsSync(path)) return empty;
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as UsageCacheFile;
+    if (!parsed || parsed.version !== CACHE_VERSION) return empty;
+    if (!Array.isArray(parsed.models) || typeof parsed.files !== "object") return empty;
+    return parsed;
+  } catch {
+    // Corrupt or unreadable cache: rebuild from scratch.
+    return empty;
+  }
+}
+
+function writeCache(cache: UsageCacheFile): void {
+  try {
+    const path = getCachePath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Write-then-rename so a crash mid-write cannot leave a torn cache behind.
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache), "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // A cache we cannot persist is a performance loss, not a correctness one.
+  }
+}
+
 /**
  * Get the sessions directory path.
  */
@@ -95,71 +164,95 @@ function getPeriodBounds(): { today: PeriodBounds; week: PeriodBounds; month: Pe
 
 
 /**
- * Parse a JSONL session file and extract usage data.
- * Matches tmustier's parsing logic.
+ * Read a file line-by-line without materializing it in memory.
+ *
+ * Session files reach 200MB+, so readFileSync would allocate the whole file
+ * (and its split() array) just to scan it once. Reads in 1MB chunks and keeps
+ * only the trailing partial line between chunks.
  */
-function parseSessionFile(
-  filePath: string,
-  seenHashes: Set<string>
-): Array<{ usage: MessageUsage; model: string; timestamp: number }> {
-  const results: Array<{ usage: MessageUsage; model: string; timestamp: number }> = [];
-
+function forEachLine(filePath: string, onLine: (line: string) => void): void {
+  const CHUNK = 1024 * 1024;
+  let fd: number | undefined;
   try {
-    const content = readFileSync(filePath, "utf-8");
-    const lines = content.trim().split("\n");
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (!line.trim()) continue;
-
-      try {
-        const entry = JSON.parse(line);
-
-        // Match tmustier's parsing: check entry.type === "message" and entry.message?.role === "assistant"
-        if (entry.type === "message" && entry.message?.role === "assistant") {
-          const msg = entry.message;
-          if (msg.usage && msg.provider && msg.model) {
-            const input = msg.usage.input || 0;
-            const output = msg.usage.output || 0;
-            const cacheRead = msg.usage.cacheRead || 0;
-            const cacheWrite = msg.usage.cacheWrite || 0;
-            const cost = msg.usage.cost?.total || 0;
-
-            // Get timestamp
-            const fallbackTs = entry.timestamp ? new Date(entry.timestamp).getTime() : 0;
-            const timestamp = msg.timestamp || (Number.isNaN(fallbackTs) ? 0 : fallbackTs);
-
-            // Deduplicate copied history across branched session files
-            const totalTokens = input + output + cacheRead + cacheWrite;
-            const hash = `${timestamp}:${totalTokens}`;
-            if (seenHashes.has(hash)) continue;
-            seenHashes.add(hash);
-
-            // Only include if we have valid data
-            if (input > 0 || output > 0 || cost > 0) {
-              results.push({
-                usage: {
-                  input,
-                  output,
-                  cacheRead,
-                  cacheWrite,
-                  cost: { total: cost },
-                },
-                model: msg.model,
-                timestamp,
-              });
-            }
-          }
-        }
-      } catch {
-        // Skip malformed lines
+    fd = openSync(filePath, "r");
+    const buf = Buffer.allocUnsafe(CHUNK);
+    let carry = "";
+    for (;;) {
+      const bytes = readSync(fd, buf, 0, CHUNK, null);
+      if (bytes <= 0) break;
+      // latin1 would corrupt multi-byte UTF-8 split across a chunk boundary;
+      // toString("utf8") on a Buffer slice handles the common case, and any
+      // partial sequence lands in `carry` and is completed by the next chunk.
+      const text = carry + buf.toString("utf8", 0, bytes);
+      let start = 0;
+      for (;;) {
+        const nl = text.indexOf("\n", start);
+        if (nl === -1) break;
+        onLine(text.slice(start, nl));
+        start = nl + 1;
       }
+      carry = text.slice(start);
     }
+    if (carry.length > 0) onLine(carry);
   } catch {
     // Skip unreadable files
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* already closed */ }
+    }
   }
+}
+
+/**
+ * Extract the compact usage records from one session file.
+ *
+ * Deliberately does NOT deduplicate: dedup is cross-file and order-dependent,
+ * so it must happen at aggregation time. Caching raw per-file records keeps
+ * each entry independent and lets any single file be re-parsed in isolation.
+ */
+function extractRecords(filePath: string, modelIndex: Map<string, number>, models: string[]): UsageRecord[] {
+  const records: UsageRecord[] = [];
+
+  forEachLine(filePath, (line) => {
+    if (!line || !line.trim()) return;
+    let entry: any;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return; // Skip malformed lines
+    }
+
+    if (entry.type !== "message" || entry.message?.role !== "assistant") return;
+    const msg = entry.message;
+    if (!msg.usage || !msg.provider || !msg.model) return;
 
-  return results;
+    const input = msg.usage.input || 0;
+    const output = msg.usage.output || 0;
+    const cacheRead = msg.usage.cacheRead || 0;
+    const cacheWrite = msg.usage.cacheWrite || 0;
+    const cost = msg.usage.cost?.total || 0;
+
+    const fallbackTs = entry.timestamp ? new Date(entry.timestamp).getTime() : 0;
+    const timestamp = msg.timestamp || (Number.isNaN(fallbackTs) ? 0 : fallbackTs);
+
+    let idx = modelIndex.get(msg.model);
+    if (idx === undefined) {
+      idx = models.length;
+      models.push(msg.model);
+      modelIndex.set(msg.model, idx);
+    }
+
+    records.push([
+      timestamp,
+      input + output + cacheRead + cacheWrite, // dedup key component
+      input + output + cacheWrite,             // counted tokens (excludes cacheRead)
+      cost,
+      idx,
+      input > 0 || output > 0 || cost > 0 ? 1 : 0,
+    ]);
+  });
+
+  return records;
 }
 
 /**
@@ -186,8 +279,30 @@ function collectSessionFiles(dir: string, files: string[]): void {
  * Matches tmustier's parsing logic.
  */
 export function parseUsageStats(): UsageStats {
-  const sessionsDir = getSessionsDir();
-  const stats: UsageStats = {
+  const { stats } = collectStats(null);
+  return stats;
+}
+
+/**
+ * Async variant that yields to the event loop while parsing.
+ *
+ * A cold parse is several seconds of pure CPU. Running it synchronously starves
+ * the event loop, so keystrokes queue up and the UI cannot repaint. Deferring
+ * the *start* (setTimeout) does not help — the block must be broken up.
+ * `yieldEvery` files, control returns to the loop.
+ */
+export async function parseUsageStatsAsync(): Promise<UsageStats> {
+  const yielder = async (): Promise<void> => {
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  };
+  const { stats, pending } = collectStats(yielder);
+  if (pending) await pending;
+  return stats;
+}
+
+/** Empty stats accumulator. */
+function emptyStats(): UsageStats {
+  return {
     tokens: { today: 0, week: 0, month: 0, allTime: 0 },
     cost: { today: 0, week: 0, month: 0, allTime: 0 },
     byModel: {},
@@ -197,93 +312,168 @@ export function parseUsageStats(): UsageStats {
     sessionCount: 0,
     messageCount: 0,
   };
+}
 
-  if (!existsSync(sessionsDir)) return stats;
-
-  const periods = getPeriodBounds();
-  const seenHashes = new Set<string>();
+/**
+ * Shared implementation for the sync and async entry points.
+ *
+ * When `yielder` is null the whole scan runs synchronously and `stats` is fully
+ * populated on return. When provided, the returned `stats` object is filled in
+ * as `pending` progresses, and the caller must await it.
+ */
+function collectStats(
+  yielder: (() => Promise<void>) | null,
+): { stats: UsageStats; pending: Promise<void> | null } {
+  const stats = emptyStats();
+  const sessionsDir = getSessionsDir();
+  if (!existsSync(sessionsDir)) return { stats, pending: null };
 
-  // Collect all session files recursively
   const sessionFiles: string[] = [];
   collectSessionFiles(sessionsDir, sessionFiles);
   sessionFiles.sort();
 
-  for (const filePath of sessionFiles) {
-    const messages = parseSessionFile(filePath, seenHashes);
+  const cache = readCache();
+  const models = cache.models.slice();
+  const modelIndex = new Map<string, number>();
+  models.forEach((name, i) => modelIndex.set(name, i));
 
-    if (messages.length === 0) continue;
+  const nextFiles: Record<string, CachedFile> = {};
+  let cacheDirty = false;
 
-    stats.sessionCount++;
-    stats.messageCount += messages.length;
+  // Statting 600 files costs ~1ms, so the mtime+size gate is essentially free
+  // compared to re-reading gigabytes of immutable history.
+  const work: Array<{ path: string; cached: CachedFile | null }> = [];
+  for (const filePath of sessionFiles) {
+    let mtimeMs = 0;
+    let size = 0;
+    try {
+      const st = statSync(filePath);
+      mtimeMs = st.mtimeMs;
+      size = st.size;
+    } catch {
+      continue; // Vanished between listing and statting.
+    }
 
-    for (const msg of messages) {
-      // Match tmustier's token calculation: input + output + cacheWrite (not cacheRead)
-      const totalTokens = msg.usage.input + msg.usage.output + msg.usage.cacheWrite;
+    const hit = cache.files[filePath];
+    if (hit && hit.mtimeMs === mtimeMs && hit.size === size) {
+      nextFiles[filePath] = hit;
+      work.push({ path: filePath, cached: hit });
+    } else {
+      cacheDirty = true;
+      work.push({ path: filePath, cached: null });
+      nextFiles[filePath] = { mtimeMs, size, records: [] };
+    }
+  }
 
-      // All time
-      stats.tokens.allTime += totalTokens;
-      stats.cost.allTime += msg.usage.cost.total;
+  // A file disappearing means the old cache had entries we must drop.
+  if (Object.keys(nextFiles).length !== Object.keys(cache.files).length) cacheDirty = true;
 
-      // Today
-      if (msg.timestamp >= periods.today.start.getTime()) {
-        stats.tokens.today += totalTokens;
-        stats.cost.today += msg.usage.cost.total;
-      }
+  const seenHashes = new Set<string>();
+  const periods = getPeriodBounds();
+  const todayStart = periods.today.start.getTime();
+  const weekStart = periods.week.start.getTime();
+  const monthStart = periods.month.start.getTime();
+
+  const bump = (
+    bucket: Record<string, { tokens: number; cost: number; sessions: number }>,
+    model: string,
+    tokens: number,
+    cost: number,
+  ) => {
+    let entry = bucket[model];
+    if (!entry) {
+      entry = { tokens: 0, cost: 0, sessions: 0 };
+      bucket[model] = entry;
+    }
+    entry.tokens += tokens;
+    entry.cost += cost;
+    entry.sessions++;
+  };
 
-      // This week
-      if (msg.timestamp >= periods.week.start.getTime()) {
-        stats.tokens.week += totalTokens;
-        stats.cost.week += msg.usage.cost.total;
+  const aggregate = (records: UsageRecord[]): void => {
+    let counted = 0;
+    for (const rec of records) {
+      const [timestamp, hashTokens, countedTokens, cost, modelIdx, isCounted] = rec;
+
+      // Dedup key is claimed even for records that are not counted, matching
+      // the original ordering (hash added before the validity check).
+      const hash = `${timestamp}:${hashTokens}`;
+      if (seenHashes.has(hash)) continue;
+      seenHashes.add(hash);
+      if (!isCounted) continue;
+
+      counted++;
+      const model = models[modelIdx] ?? "unknown";
+
+      stats.tokens.allTime += countedTokens;
+      stats.cost.allTime += cost;
+      bump(stats.byModel, model, countedTokens, cost);
+
+      if (timestamp >= todayStart) {
+        stats.tokens.today += countedTokens;
+        stats.cost.today += cost;
+        bump(stats.byModelToday, model, countedTokens, cost);
       }
-
-      // This month
-      if (msg.timestamp >= periods.month.start.getTime()) {
-        stats.tokens.month += totalTokens;
-        stats.cost.month += msg.usage.cost.total;
+      if (timestamp >= weekStart) {
+        stats.tokens.week += countedTokens;
+        stats.cost.week += cost;
+        bump(stats.byModelWeek, model, countedTokens, cost);
       }
-
-      // By model (all time)
-      const model = msg.model;
-      if (!stats.byModel[model]) {
-        stats.byModel[model] = { tokens: 0, cost: 0, sessions: 0 };
-      }
-      stats.byModel[model].tokens += totalTokens;
-      stats.byModel[model].cost += msg.usage.cost.total;
-      stats.byModel[model].sessions++;
-
-      // By model (today)
-      if (msg.timestamp >= periods.today.start.getTime()) {
-        if (!stats.byModelToday[model]) {
-          stats.byModelToday[model] = { tokens: 0, cost: 0, sessions: 0 };
-        }
-        stats.byModelToday[model].tokens += totalTokens;
-        stats.byModelToday[model].cost += msg.usage.cost.total;
-        stats.byModelToday[model].sessions++;
+      if (timestamp >= monthStart) {
+        stats.tokens.month += countedTokens;
+        stats.cost.month += cost;
+        bump(stats.byModelMonth, model, countedTokens, cost);
       }
+    }
 
-      // By model (this week)
-      if (msg.timestamp >= periods.week.start.getTime()) {
-        if (!stats.byModelWeek[model]) {
-          stats.byModelWeek[model] = { tokens: 0, cost: 0, sessions: 0 };
-        }
-        stats.byModelWeek[model].tokens += totalTokens;
-        stats.byModelWeek[model].cost += msg.usage.cost.total;
-        stats.byModelWeek[model].sessions++;
-      }
+    if (counted > 0) {
+      stats.sessionCount++;
+      stats.messageCount += counted;
+    }
+  };
 
-      // By model (this month)
-      if (msg.timestamp >= periods.month.start.getTime()) {
-        if (!stats.byModelMonth[model]) {
-          stats.byModelMonth[model] = { tokens: 0, cost: 0, sessions: 0 };
-        }
-        stats.byModelMonth[model].tokens += totalTokens;
-        stats.byModelMonth[model].cost += msg.usage.cost.total;
-        stats.byModelMonth[model].sessions++;
-      }
+  const finish = (): void => {
+    if (cacheDirty) {
+      writeCache({ version: CACHE_VERSION, models, files: nextFiles });
+    }
+  };
+
+  const YIELD_EVERY = 25;
+
+  if (!yielder) {
+    for (const item of work) {
+      const records = item.cached
+        ? item.cached.records
+        : (nextFiles[item.path].records = extractRecords(item.path, modelIndex, models));
+      aggregate(records);
     }
+    finish();
+    return { stats, pending: null };
   }
 
-  return stats;
+  const pending = (async () => {
+    let sinceYield = 0;
+    for (const item of work) {
+      let records: UsageRecord[];
+      if (item.cached) {
+        records = item.cached.records;
+      } else {
+        records = extractRecords(item.path, modelIndex, models);
+        nextFiles[item.path].records = records;
+        // Only re-parsed files are expensive; cache hits are near-free, so
+        // yielding is gated on real work to avoid pointless loop turns.
+        sinceYield++;
+      }
+      aggregate(records);
+      if (sinceYield >= YIELD_EVERY) {
+        sinceYield = 0;
+        await yielder();
+      }
+    }
+    finish();
+  })();
+
+  return { stats, pending };
 }
 
 /**