@mohndoe/pi-atlas 0.1.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# pi-atlas Architecture
+
+## Module structure
+
+```
+src/
+├── index.ts        — Extension entry point. Registers /atlas.
+├── types.ts        — Shared types (DayAgg, StatsSummary, etc.)
+├── parser.ts       — .jsonl → DayAgg[]. Global sessionProjectMap for cost attribution.
+├── compute.ts      — summarize(): DayAgg[] × TimeRange → StatsSummary (pure).
+├── cache.ts        — loadAggregate(): try SHA-256-keyed cache, fall back to parse.
+├── format.ts       — Cost/number/date formatters + language detection (EXT_TO_LANG).
+├── colorPalette.ts — chalk color lookups per language and per provider.
+├── components/     — TUI components (Dashboard, SortedTable, cells, BarChart, etc.)
+├── tabs/           — Five tab implementations (Overview, Languages, Models, Projects, Usage).
+└── __tests__/      — Tests mirror src layout.
+```
+
+## Data pipeline
+
+```
+.jsonl files → parseFile() → DayAgg[] (per calendar day)
+                                   ↓
+                             summarize(days, range)
+                                   ↓
+                    StatsSummary × 4 (pre-computed for 1d/7d/30d/All)
+                                   ↓
+                          Tab receives relevant StatsSummary
+```
+
+All four ranges are computed up front (see [ADR-0002](../docs/adr/0002-precomputed-summaries.md)). `StatsSummary` is passed as a `Map<TimeRange, StatsSummary>`; tabs don't re-compute on range changes.
+
+## Component hierarchy
+
+```
+Dashboard (extends BorderBox from @mohndoe/pi-tui-extras)
+├── TabBar                 (←→ navigation)
+├── separator
+├── active tab content      (one of: Overview, Languages, Models, Projects, Usage)
+├── separator
+└── controls hint
+```
+
+- **Dashboard** always renders as a centered overlay popup (50% width, max 80% height).
+- Title bar shows app name (left) + current range label (right). Footer shows update timestamp + controls hint.
+- Tabs extend `Container` (from `@earendil-works/pi-tui`), which implements `Component`.
+- Every tab wraps its content in one or more `BorderBox` instances (from `@mohndoe/pi-tui-extras`).
+- The **SortedTable** (used by Languages, Models, Projects, Usage) delegates cell rendering to `cells.ts` — a factory of `CellComponent` types: `text`, `header` (with sort indicators), `marquee` (auto-scroll), `bar` (horizontal bar).
+
+### Chrome
+
+Dashboard calculates tab content height as: `floor(terminal.rows × 0.8) - chrome rows - 2`. Chrome rows: TabBar + separator + separator + footer = ~4. The exact number is a local constant.
+
+## Key design decisions
+
+**Cost attribution** — cost from an assistant message is attributed to all active projects seen in the current file (see [ADR-0001](../docs/adr/0001-global-session-project-map.md)).
+
+**Pre-computed summaries** — four `StatsSummary` values are computed when the Dashboard opens, making tab switches instant (see [ADR-0002](../docs/adr/0002-precomputed-summaries.md)).
+
+**Session log parsing** — eight JSONL entry types are handled (session, user/assistant/tool-result messages, model change, thinking level change, compaction). Branch summary, custom, custom message, label, and session info entries are skipped.
+
+**Language counting** — lines measured by splitting on `\n`, not character length.
+
+**Cache** — SHA-256 of file paths/sizes/mtimes. Deterministic (sorted paths). Rebuilds silently on corruption.
+
+**RangeSelector** — accepts `RangeOption[]` from caller. Labels: "Today", "Last 7 days", "Last 30 days", "All time". The `r` key cycles through them.

package/docs/adr/0001-global-session-project-map.md

@@ -0,0 +1,9 @@
+# Global mutable sessionProjectMap for cost attribution
+
+Cost attribution to projects uses a module-level `sessionProjectMap: Map<string, string>` in `parser.ts`. When a `session` entry is parsed (containing `cwd`), the session ID is mapped to a project name. Subsequent `assistant` messages in the same file attribute their cost to all active projects in `sessionProjectMap`. The map is reset at the start of each `parseFile()` call.
+
+This keeps cost attribution simple — parse functions don't need to carry a context object through the call chain — at the cost of global mutable state that's invisible to callers of individual `parse*()` functions.
+
+**Trade-off**: Accepting mutable global state in the parser was cleaner than threading a `SessionProjectMap` through every `parse*()` function and returning it alongside every `DayAgg`. The alternative would bundle the map with DayAgg into a `ParseResult { days, sessionMap }` type and thread it through the entire call chain. The current approach keeps function signatures pure-looking `(entry) → DayAgg` while the map is implicitly available.
+
+**Consequences**: Calling `parseSessionEntry()`, `parseUserMessage()`, etc. outside of a `parseFile()` lifecycle (e.g., in unit tests) will not have the expected project mapping. Tests that exercise cost attribution must set up `sessionProjectMap` first or go through `parseFile()`.

package/docs/adr/0002-precomputed-summaries.md

@@ -0,0 +1,9 @@
+# Pre-computed StatsSummary for all time ranges
+
+The Dashboard constructor computes `StatsSummary` for all four time ranges (1d, 7d, 30d, All) upfront, then passes the full array to every tab. Tabs read from the summary corresponding to the currently selected range.
+
+This means every tab switch is instant — no computation needed — at the cost of holding four summaries in memory simultaneously (each ~tens of KB for a typical user). The alternative would compute summaries lazily on tab switch or range change, keeping only the current range's summary in memory.
+
+**Trade-off**: For a typical user with hundreds of DayAgg entries, the memory overhead of four summaries is negligible (JSON-serialized cache is typically <500 KB). The latency benefit is real: tab switches happen in a single render cycle with no async work. The only scenario where lazy evaluation would help is an extremely large session history (>10k days), which is unlikely given pi's typical usage.
+
+**Consequences**: The Dashboard constructor accepts `StatsSummary[]` (length 4) rather than `DayAgg[]`. Adding a new time range requires building a fifth summary. The summaries are recomputed only when the Dashboard is reconstructed (i.e., on range change via `buildTabs()`).

package/docs/agents/domain.md

@@ -0,0 +1,42 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in
+- **`node_modules/@earendil-works/pi-tui/README.md`** — pi-tui framework docs (Component interface, built-in components, rendering pipeline). Always read before designing or modifying TUI components.
+- **`node_modules/@earendil-works/pi-tui/dist/index.d.ts`** — pi-tui type declarations for exact API signatures.
+- **`node_modules/@earendil-works/pi-coding-agent/docs/session-format.md`** — pi session JSONL format: all entry types (SessionHeader, MessageEntry, CompactionEntry, etc.), AgentMessage roles (user/assistant/toolResult), Usage/cost structure, content blocks. Critical reference for parser code — the project's own types.ts mirrors this.
+- **`node_modules/@earendil-works/pi-coding-agent/docs/tui.md`** — pi-specific TUI docs: `ctx.ui.custom()`, component registration, focusable components.
+- **`node_modules/@earendil-works/pi-coding-agent/docs/extensions.md`** — pi extension API: `registerCommand()`, `ExtensionAPI`, `ExtensionCommandContext`, theme type, extension lifecycle.
+- **`node_modules/@earendil-works/pi-coding-agent/docs/sessions.md`** — pi session storage overview (file layout under `~/.pi/agent/sessions/`).
+- **`node_modules/@earendil-works/pi-coding-agent/docs/index.md`** — full doc index; read any other pages as needed.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-global-session-project-map.md
+│   └── 0002-precomputed-summaries.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0002 (pre-computed summaries) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,14 @@
+# Triage Labels
+
+| mattpocock/skills role | Our label | Meaning |
+|------------------------|-----------|---------|
+| *(pre-triage)* | `considering` | Initial state for new issues and PRDs |
+| `needs-triage` | `needs-triage` | Maintainer needs to evaluate |
+| `needs-info` | `needs-info` | Waiting on reporter for more information |
+| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
+| `ready-for-human` | `ready-for-human` | Requires human implementation |
+| `wontfix` | `wontfix` | Will not be actioned |
+
+New issues and PRDs are created with `considering`. A maintainer moves them to `needs-triage` after initial review.
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mohndoe/pi-atlas",
+  "version": "0.1.1",
+  "description": "Pi extension providing an atlas of agent activity — costs, languages, models, projects, and tools from session logs.",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/MohnDoe/pi-atlas#readme",
+  "bugs": {
+    "url": "https://github.com/MohnDoe/pi-atlas/issues"
+  },
+  "license": "MIT",
+  "author": "Kevin P. <@mohndoe>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohnDoe/pi-atlas.git"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "type": "module",
+  "module": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@mohndoe/pi-tui-extras": "^0.1.4",
+    "chalk": "^5.6.2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.74.0 <0.77.0",
+    "@earendil-works/pi-ai": ">=0.74.0 <0.77.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0 <0.77.0",
+    "@earendil-works/pi-tui": ">=0.74.0 <0.77.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-tui": ">=0.74.0 <0.77.0",
+    "typescript": "^5"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/__tests__/cache.test.ts

@@ -0,0 +1,388 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  computeSignature,
+  getCacheTimestamp,
+  loadAggregate,
+  readCache,
+  writeCache,
+} from "../cache";
+import { emptyDay } from "../parser";
+import { type DayAgg } from "../types";
+
+describe("computeSignature", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `pi-atlas-test-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty string for empty directory", async () => {
+    const sig = await computeSignature(tmpDir);
+    expect(sig).toBe("");
+  });
+
+  it("returns a non-empty hash for a directory with files", async () => {
+    await writeFile(join(tmpDir, "a.jsonl"), "line1\n");
+    await writeFile(join(tmpDir, "b.jsonl"), "line2\n");
+
+    const sig1 = await computeSignature(tmpDir);
+    expect(sig1).toBeTruthy();
+    expect(sig1.length).toBeGreaterThan(0);
+
+    // Same directory, same signature
+    const sig2 = await computeSignature(tmpDir);
+    expect(sig2).toBe(sig1);
+  });
+
+  it("changes when a file is modified", async () => {
+    await writeFile(join(tmpDir, "a.jsonl"), "original\n");
+    const sig1 = await computeSignature(tmpDir);
+
+    await writeFile(join(tmpDir, "a.jsonl"), "modified\n");
+    const sig2 = await computeSignature(tmpDir);
+
+    expect(sig2).not.toBe(sig1);
+  });
+
+  it("changes when a file is added", async () => {
+    await writeFile(join(tmpDir, "a.jsonl"), "data\n");
+    const sig1 = await computeSignature(tmpDir);
+
+    await writeFile(join(tmpDir, "b.jsonl"), "more\n");
+    const sig2 = await computeSignature(tmpDir);
+
+    expect(sig2).not.toBe(sig1);
+  });
+
+  it("scans subdirectories", async () => {
+    const subDir = join(tmpDir, "project-a");
+    await mkdir(subDir);
+    await writeFile(join(subDir, "s1.jsonl"), "data\n");
+
+    const sig = await computeSignature(tmpDir);
+    expect(sig).toBeTruthy();
+    expect(sig.length).toBeGreaterThan(0);
+  });
+
+  it("ignores non-.jsonl files", async () => {
+    await writeFile(join(tmpDir, "README.md"), "docs\n");
+    const sig = await computeSignature(tmpDir);
+    expect(sig).toBe("");
+  });
+});
+
+describe("cache read/write", () => {
+  let tmpDir: string;
+  let cachePath: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `pi-atlas-cache-test-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+    cachePath = join(tmpDir, "cache.json");
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes and reads cache", async () => {
+    const d = emptyDay("2026-06-08");
+    d.cost = 1.5;
+    d.sessionIds = new Set(["s1"]);
+    const days: DayAgg[] = [d];
+    await writeCache(cachePath, "sig-abc", days);
+
+    const payload = await readCache(cachePath);
+    expect(payload).toBeDefined();
+    expect(payload!.signature).toBe("sig-abc");
+    expect(payload!.days).toHaveLength(1);
+    expect(payload!.days[0]!.date).toBe("2026-06-08");
+    expect(payload!.days[0]!.cost).toBe(1.5);
+    // Sets are serialized as arrays
+    expect(payload!.days[0]!.sessionIds).toEqual(["s1"]);
+  });
+
+  it("returns null for missing cache file", async () => {
+    const payload = await readCache("/nonexistent/path/cache.json");
+    expect(payload).toBeNull();
+  });
+
+  it("returns null for corrupt cache", async () => {
+    await writeFile(cachePath, "not-json");
+    const payload = await readCache(cachePath);
+    expect(payload).toBeNull();
+  });
+
+  it("returns generatedAt from valid cache", async () => {
+    const d = emptyDay("2026-06-08");
+    await writeCache(cachePath, "sig-abc", [d]);
+    const ts = await getCacheTimestamp(cachePath);
+    expect(ts).not.toBeNull();
+    // generatedAt is an ISO string
+    expect(new Date(ts!).toISOString()).toBe(ts as string);
+  });
+
+  it("returns null for missing cache", async () => {
+    const ts = await getCacheTimestamp("/nonexistent/cache.json");
+    expect(ts).toBeNull();
+  });
+
+  it("returns null for corrupt cache", async () => {
+    await writeFile(cachePath, "not-json");
+    const ts = await getCacheTimestamp(cachePath);
+    expect(ts).toBeNull();
+  });
+
+  it("serializes and deserializes modelToProvider Map", async () => {
+    const d = emptyDay("2026-06-08");
+    d.modelToProvider.set("claude-sonnet-4", "anthropic");
+    d.modelToProvider.set("gpt-4o", "openai");
+    const days: DayAgg[] = [d];
+    await writeCache(cachePath, "sig-mtp", days);
+
+    // Read raw cache JSON — modelToProvider should not be empty {}
+    const payload = await readCache(cachePath);
+    expect(payload).toBeDefined();
+    expect(payload!.days).toHaveLength(1);
+    expect(payload!.days[0]!.modelToProvider).toEqual({
+      "claude-sonnet-4": "anthropic",
+      "gpt-4o": "openai",
+    });
+
+    // Load via loadAggregate round-trip (needs a session dir with .jsonl for valid sig)
+    const sesDir = join(tmpDir, "sessions");
+    await mkdir(sesDir, { recursive: true });
+    await writeFile(
+      join(sesDir, "dummy.jsonl"),
+      JSON.stringify({
+        type: "session",
+        version: 3,
+        id: "s1",
+        timestamp: "2026-06-08T10:00:00.000Z",
+        cwd: "/p",
+      }) + "\n",
+    );
+    const sig = await computeSignature(sesDir);
+    await writeFile(
+      cachePath,
+      JSON.stringify({
+        signature: sig,
+        generatedAt: new Date().toISOString(),
+        days: [
+          {
+            date: "2026-06-08",
+            cost: 0,
+            inTok: 0,
+            outTok: 0,
+            crTok: 0,
+            cwTok: 0,
+            userMsgs: 0,
+            asstMsgs: 0,
+            toolResults: 0,
+            sessionIds: [],
+            langLines: {},
+            langEdits: {},
+            modelCost: {},
+            modelCount: {},
+            providerCost: {},
+            providerCount: {},
+            modelToProvider: { "claude-sonnet-4": "anthropic", "gpt-4o": "openai" },
+            projectCost: {},
+            projectSessions: {},
+            toolCount: {},
+          },
+        ],
+      }),
+    );
+    const loaded = await loadAggregate(cachePath, sesDir);
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0]!.modelToProvider.get("claude-sonnet-4")).toBe("anthropic");
+    expect(loaded[0]!.modelToProvider.get("gpt-4o")).toBe("openai");
+    expect(loaded[0]!.modelToProvider.size).toBe(2);
+  });
+});
+
+describe("loadAggregate", () => {
+  let tmpDir: string;
+  let sessionsDir: string;
+  let cachePath: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `pi-atlas-load-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+    sessionsDir = join(tmpDir, "sessions");
+    await mkdir(sessionsDir, { recursive: true });
+    cachePath = join(tmpDir, "cache.json");
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array for empty sessions dir", async () => {
+    const days = await loadAggregate(cachePath, sessionsDir);
+    expect(days).toEqual([]);
+  });
+
+  it("parses session files and returns DayAgg array", async () => {
+    const subDir = join(sessionsDir, "proj-a");
+    await mkdir(subDir);
+    await writeFile(
+      join(subDir, "s1.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s1",
+          timestamp: "2026-06-08T10:00:00.000Z",
+          cwd: "/home/doe/proj-a",
+        }),
+        JSON.stringify({
+          type: "message",
+          id: "m1",
+          parentId: "p",
+          timestamp: "2026-06-08T10:01:00.000Z",
+          message: { role: "user", content: [{ type: "text", text: "hi" }] },
+        }),
+      ].join("\n"),
+    );
+
+    const days = await loadAggregate(cachePath, sessionsDir);
+    expect(days).toHaveLength(1);
+    expect(days[0]!.date).toBe("2026-06-08");
+    expect(days[0]!.userMsgs).toBe(1);
+  });
+
+  it("caches results and reuses them", async () => {
+    const subDir = join(sessionsDir, "proj-a");
+    await mkdir(subDir);
+    await writeFile(
+      join(subDir, "s1.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s1",
+          timestamp: "2026-06-08T10:00:00.000Z",
+          cwd: "/home/doe/proj-a",
+        }),
+      ].join("\n"),
+    );
+
+    const days1 = await loadAggregate(cachePath, sessionsDir);
+    expect(days1).toHaveLength(1);
+
+    // Second call should use cache
+    const days2 = await loadAggregate(cachePath, sessionsDir);
+    expect(days2).toHaveLength(1);
+  });
+
+  it("invalidates cache when session files change", async () => {
+    const subDir = join(sessionsDir, "proj-a");
+    await mkdir(subDir);
+    await writeFile(
+      join(subDir, "s1.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s1",
+          timestamp: "2026-06-08T10:00:00.000Z",
+          cwd: "/home/doe/proj-a",
+        }),
+      ].join("\n"),
+    );
+
+    await loadAggregate(cachePath, sessionsDir);
+
+    // Add a new file
+    await writeFile(
+      join(subDir, "s2.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s2",
+          timestamp: "2026-06-09T10:00:00.000Z",
+          cwd: "/home/doe/proj-b",
+        }),
+      ].join("\n"),
+    );
+
+    const days = await loadAggregate(cachePath, sessionsDir);
+    expect(days).toHaveLength(2); // two days now
+  });
+
+  it("logs corrupt line count to stderr", async () => {
+    const subDir = join(sessionsDir, "proj-a");
+    await mkdir(subDir);
+    await writeFile(
+      join(subDir, "mixed.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s1",
+          timestamp: "2026-06-08T10:00:00.000Z",
+          cwd: "/home/doe/proj-a",
+        }),
+        "not valid json",
+        "also broken {",
+        JSON.stringify({
+          type: "message",
+          id: "m1",
+          parentId: "p",
+          timestamp: "2026-06-08T10:01:00.000Z",
+          message: { role: "user", content: [{ type: "text", text: "hi" }] },
+        }),
+      ].join("\n"),
+    );
+
+    const errors: string[] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.join(" "));
+    });
+
+    try {
+      await loadAggregate(cachePath, sessionsDir, true);
+
+      expect(errors.length).toBeGreaterThan(0);
+      const warning = errors.find((e) => e.includes("corrupt"));
+      expect(warning).toBeDefined();
+      expect(warning).toContain("2"); // 2 corrupt lines
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it("calls onProgress during parsing", async () => {
+    const subDir = join(sessionsDir, "proj-a");
+    await mkdir(subDir);
+    await writeFile(
+      join(subDir, "s1.jsonl"),
+      [
+        JSON.stringify({
+          type: "session",
+          version: 3,
+          id: "s1",
+          timestamp: "2026-06-08T10:00:00.000Z",
+          cwd: "/home/doe/proj-a",
+        }),
+      ].join("\n"),
+    );
+
+    const progress: number[] = [];
+    await loadAggregate(cachePath, sessionsDir, false, (p) => progress.push(p));
+
+    // Should have reported some progress
+    expect(progress.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/components.fixtures.ts

@@ -0,0 +1,54 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { ColorPalette } from "../colorPalette";
+import { type RangeOption, RangeSelector } from "../components/RangeSelector";
+
+/**
+ * Pass-through mock theme for tests. All styling methods return text unchanged.
+ * Matches the pattern from rpiv-mono test-utils.
+ */
+export function makeTheme(overrides: Partial<Theme> = {}): Theme {
+  return {
+    fg: (_color, text) => text,
+    bg: (_color, text) => text,
+    bold: (text) => text,
+    italic: (text) => text,
+    underline: (text) => text,
+    inverse: (text) => text,
+    strikethrough: (text) => text,
+    ...overrides,
+  } as Theme;
+}
+
+export function testPalette(): ColorPalette {
+  return new ColorPalette({});
+}
+
+/**
+ * Mock TUI for tests. Only requestRender() is implemented as a no-op.
+ * All other TUI methods are left undefined - they're never called in tests
+ * that exercise MarqueeText or SortedTable marquee behavior.
+ */
+export function makeMockTUI(): TUI {
+  return {
+    requestRender() {},
+    terminal: {
+      get rows() {
+        return 24;
+      },
+      get columns() {
+        return 80;
+      },
+    },
+  } as TUI;
+}
+
+export function makeRangeSelector(theme: Theme): RangeSelector {
+  const rangeOptions: RangeOption[] = [
+    { label: "Today", value: "1d" },
+    { label: "Last 7 days", value: "7d" },
+    { label: "Last 30 days", value: "30d" },
+    { label: "All time", value: "All" },
+  ];
+  return new RangeSelector(theme, rangeOptions, rangeOptions.length - 1);
+}