@roberttlange/agentlens 0.2.3 → 0.3.0

package/node_modules/@agentlens/server/dist/app.test.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { mergeConfig, saveConfig, TraceIndex } from "@agentlens/core";
-import { createServer, extractCursorSessionIdsFromOpenPaths, extractOpenCodeSessionIdsFromLogContent, geminiLogsContainSessionId, geminiProjectHashFromTracePath, geminiProjectHashesFromCwd, geminiProjectKeyFromTracePath, geminiProjectSlugsFromCwd, inferSessionCwd, matchesCurrentUser, parseTmuxClients, resolveDefaultWebDistPath, extractClaudeDebugProcessPid, selectAgentProcessPidsBySessionId, selectPreferredTmuxClient, selectOpenFileProcessPids, selectAgentProjectProcessPids, selectClaudeProjectProcessPids, selectCursorProjectProcessPids, selectGeminiProjectProcessPids, selectPidGroupByNearestTimestamp, } from "./app.js";
+import { buildLiveBatchEnvelope, createServer, extractCursorSessionIdsFromOpenPaths, extractOpenCodeSessionIdsFromLogContent, geminiLogsContainSessionId, geminiProjectHashFromTracePath, geminiProjectHashesFromCwd, geminiProjectKeyFromTracePath, geminiProjectSlugsFromCwd, inferSessionCwd, matchesCurrentUser, parseTmuxClients, resolveDefaultWebDistPath, extractClaudeDebugProcessPid, selectAgentProcessPidsBySessionId, selectPreferredTmuxClient, selectOpenFileProcessPids, selectAgentProjectProcessPids, selectClaudeProjectProcessPids, selectCursorProjectProcessPids, selectGeminiProjectProcessPids, selectPidGroupByNearestTimestamp, runServer, } from "./app.js";
 function buildTraceLog(sessionId, sequence, withToolEvents) {
     const firstTs = new Date(Date.UTC(2026, 1, 11, 10, 0, sequence)).toISOString();
     const secondTs = new Date(Date.UTC(2026, 1, 11, 10, 0, sequence + 1)).toISOString();
@@ -198,6 +198,94 @@ async function buildFixtureWithCustomTrace(traceLog, sessionId) {
     return { configPath, index, sessionId };
 }
 describe("server api", () => {
+    it("coalesces bursty live deltas into one ordered batch envelope", async () => {
+        const original = buildTraceLog("server-session-burst", 1, true);
+        const updated = buildTraceLog("server-session-burst", 4, true);
+        const fixture = await buildFixtureWithCustomTrace(original, "server-session-burst");
+        const [initialSummary] = fixture.index.getSummaries();
+        if (!initialSummary)
+            throw new Error("missing initial summary");
+        await writeFile(path.join(path.dirname(initialSummary.path), path.basename(initialSummary.path)), `${original}\n${updated}`, "utf8");
+        await fixture.index.refresh();
+        const [updatedSummary] = fixture.index.getSummaries();
+        if (!updatedSummary)
+            throw new Error("missing updated summary");
+        const batch = buildLiveBatchEnvelope([
+            {
+                id: "1",
+                type: "trace_updated",
+                version: 1,
+                payload: { summary: { ...initialSummary, eventCount: 3, mtimeMs: initialSummary.mtimeMs + 1 } },
+            },
+            {
+                id: "2",
+                type: "trace_updated",
+                version: 2,
+                payload: { summary: updatedSummary },
+            },
+            {
+                id: "3",
+                type: "events_appended",
+                version: 3,
+                payload: {
+                    id: updatedSummary.id,
+                    appended: 1,
+                    latestEvents: fixture.index.getTracePage(updatedSummary.id, { limit: 1 }).events,
+                },
+            },
+            {
+                id: "4",
+                type: "events_appended",
+                version: 4,
+                payload: {
+                    id: updatedSummary.id,
+                    appended: 2,
+                    latestEvents: fixture.index.getTracePage(updatedSummary.id, { limit: 2 }).events,
+                },
+            },
+            {
+                id: "5",
+                type: "overview_updated",
+                version: 5,
+                payload: { overview: fixture.index.getOverview(), startup: fixture.index.getStartupStatus() },
+            },
+            {
+                id: "6",
+                type: "trace_removed",
+                version: 6,
+                payload: { id: updatedSummary.id },
+            },
+            {
+                id: "7",
+                type: "trace_updated",
+                version: 7,
+                payload: { summary: { ...updatedSummary, mtimeMs: updatedSummary.mtimeMs + 5 } },
+            },
+        ]);
+        expect(batch.type).toBe("batch");
+        expect(batch.payload.events.map((event) => event.type)).toEqual(["trace_updated", "events_appended", "overview_updated"]);
+        const finalTraceUpdate = batch.payload.events[0];
+        expect(finalTraceUpdate?.type).toBe("trace_updated");
+        if (finalTraceUpdate?.type !== "trace_updated") {
+            throw new Error("expected trace_updated envelope");
+        }
+        expect(finalTraceUpdate.payload.summary).toMatchObject({
+            id: updatedSummary.id,
+            eventCount: updatedSummary.eventCount,
+            mtimeMs: updatedSummary.mtimeMs + 5,
+        });
+        const appended = batch.payload.events[1];
+        expect(appended?.type).toBe("events_appended");
+        if (appended?.type !== "events_appended") {
+            throw new Error("expected events_appended envelope");
+        }
+        expect(appended.payload).toMatchObject({
+            id: updatedSummary.id,
+            appended: 3,
+        });
+        expect(appended.payload.latestEvents).toHaveLength(2);
+        expect(batch.payload.events[2]?.type).toBe("overview_updated");
+    });
     it("infers session cwd from both session_meta and session events", async () => {
         const codexDetail = {
             events: [{ rawType: "session_meta", raw: { payload: { cwd: " /tmp/codex " } } }],
@@ -868,8 +956,262 @@ describe("server api", () => {
         expect(payload.activity.days[0]?.bins[1]?.startMs).toBe(Date.UTC(2026, 1, 5, 6, 30, 0));
         await server.close();
     }, 20_000);
-    it("supports year-to-date style activity windows with daily aggregation", async () => {
+    it("accepts metric and color overrides from activity query params", async () => {
+        const fixture = await buildFixtureWithTraceCount(1);
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        const weekResponse = await server.inject({
+            method: "GET",
+            url: "/api/activity/week?end_date=2026-02-11&tz_offset_min=0&day_count=7&slot_min=30&hour_start=6&hour_end=2&metric=output_tokens&color=%2316a34a",
+        });
+        expect(weekResponse.statusCode).toBe(200);
+        const weekPayload = weekResponse.json();
+        expect(weekPayload.activity.presentation).toMatchObject({
+            metric: "output_tokens",
+            color: "#16a34a",
+        });
+        const yearResponse = await server.inject({
+            method: "GET",
+            url: "/api/activity/year?end_date=2026-02-11&tz_offset_min=0&day_count=365&metric=bogus&color=red",
+        });
+        expect(yearResponse.statusCode).toBe(200);
+        const yearPayload = yearResponse.json();
+        expect(yearPayload.activity.presentation).toMatchObject({
+            metric: "sessions",
+            color: "#dc2626",
+        });
+        await server.close();
+    }, 20_000);
+    it("serves output-token heatmap presentation and summed weekly values from config", async () => {
+        const traceLog = [
+            JSON.stringify({
+                timestamp: "2026-02-11T06:00:00.000Z",
+                type: "session_meta",
+                payload: { id: "metric-trace", cwd: "/tmp/proj", cli_version: "0.1.0" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T06:00:00.000Z",
+                type: "turn_context",
+                payload: { model: "gpt-5.3-codex" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T06:00:00.000Z",
+                type: "event_msg",
+                payload: {
+                    type: "token_count",
+                    info: {
+                        total_token_usage: {
+                            input_tokens: 100,
+                            cached_input_tokens: 0,
+                            output_tokens: 60,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 160,
+                        },
+                        last_token_usage: {
+                            input_tokens: 100,
+                            cached_input_tokens: 0,
+                            output_tokens: 60,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 160,
+                        },
+                    },
+                },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T06:30:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "halfway" }] },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T07:00:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "done" }] },
+            }),
+        ].join("\n");
+        const fixture = await buildFixtureWithCustomTrace(traceLog, "metric-trace");
+        const nextConfig = mergeConfig({
+            ...fixture.index.getConfig(),
+            activityHeatmap: {
+                metric: "output_tokens",
+                color: "#16a34a",
+            },
+        });
+        fixture.index.setConfig(nextConfig);
+        await saveConfig(nextConfig, fixture.configPath);
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        const response = await server.inject({
+            method: "GET",
+            url: "/api/activity/week?end_date=2026-02-11&tz_offset_min=0&day_count=1&slot_min=30&hour_start=6&hour_end=8",
+        });
+        expect(response.statusCode).toBe(200);
+        const payload = response.json();
+        const targetDay = payload.activity.days[0];
+        expect(payload.activity.presentation).toMatchObject({
+            metric: "output_tokens",
+            color: "#16a34a",
+        });
+        expect(payload.activity.presentation.palette).toHaveLength(5);
+        expect(targetDay?.bins[0]?.heatmapValue).toBeCloseTo(60, 6);
+        expect(targetDay?.bins[1]?.heatmapValue).toBeCloseTo(0, 6);
+        expect(targetDay?.bins[2]?.heatmapValue).toBeCloseTo(0, 6);
+        await server.close();
+    }, 20_000);
+    it("builds weekly usage summaries from usage timestamps within the selected window", async () => {
+        const traceLog = [
+            JSON.stringify({
+                timestamp: "2026-02-11T06:00:00.000Z",
+                type: "session_meta",
+                payload: { id: "weekly-usage-window", cwd: "/tmp/proj", cli_version: "0.1.0" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T06:00:00.000Z",
+                type: "turn_context",
+                payload: { model: "gpt-5.3-codex" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T06:05:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "within window" }] },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T09:00:00.000Z",
+                type: "event_msg",
+                payload: {
+                    type: "token_count",
+                    info: {
+                        total_token_usage: {
+                            input_tokens: 120,
+                            cached_input_tokens: 30,
+                            output_tokens: 50,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 200,
+                        },
+                        last_token_usage: {
+                            input_tokens: 120,
+                            cached_input_tokens: 30,
+                            output_tokens: 50,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 200,
+                        },
+                    },
+                },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-12T06:00:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "next day" }] },
+            }),
+        ].join("\n");
+        const fixture = await buildFixtureWithCustomTrace(traceLog, "weekly-usage-window");
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        const response = await server.inject({
+            method: "GET",
+            url: "/api/activity/week?end_date=2026-02-12&tz_offset_min=0&day_count=2&slot_min=30&hour_start=6&hour_end=8",
+        });
+        expect(response.statusCode).toBe(200);
+        const payload = response.json();
+        const codexRow = payload.activity.usageSummary.rows.find((row) => row.agent === "codex");
+        expect(codexRow).toEqual(expect.objectContaining({
+            inputTokens: 0,
+            cacheTokens: 0,
+            outputTokens: 0,
+        }));
+        await server.close();
+    }, 20_000);
+    it("serves compact yearly activity from the earliest active day in the selected year", async () => {
         const fixture = await buildFixtureWithTraceCount(3);
+        const detailSpy = vi.spyOn(fixture.index, "getSessionDetail");
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        const response = await server.inject({
+            method: "GET",
+            url: "/api/activity/year?end_date=2026-02-22&tz_offset_min=0&day_count=53",
+        });
+        expect(response.statusCode).toBe(200);
+        const payload = response.json();
+        expect(payload.activity.startDateLocal).toBe("2026-02-11");
+        expect(payload.activity.endDateLocal).toBe("2026-02-22");
+        expect(payload.activity.dayCount).toBe(12);
+        expect(payload.activity.days).toHaveLength(12);
+        expect(payload.activity.days[0]?.dateLocal).toBe("2026-02-11");
+        expect(payload.activity.days[11]?.dateLocal).toBe("2026-02-22");
+        expect(payload.activity.days.every((day) => day.bins === undefined)).toBe(true);
+        expect(payload.activity.days.some((day) => day.totalEventCount > 0)).toBe(true);
+        expect(payload.activity.usageSummary.totals.totalUniqueSessions).toBe(3);
+        expect(detailSpy).not.toHaveBeenCalled();
+        detailSpy.mockRestore();
+        await server.close();
+    }, 20_000);
+    it("serves cost heatmap presentation and summed yearly values from config", async () => {
+        const traceLog = [
+            JSON.stringify({
+                timestamp: "2026-02-11T07:00:00.000Z",
+                type: "session_meta",
+                payload: { id: "cost-trace", cwd: "/tmp/proj", cli_version: "0.1.0" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T07:00:00.000Z",
+                type: "turn_context",
+                payload: { model: "gpt-5.3-codex" },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T07:00:00.000Z",
+                type: "event_msg",
+                payload: {
+                    type: "token_count",
+                    info: {
+                        total_token_usage: {
+                            input_tokens: 40,
+                            cached_input_tokens: 0,
+                            output_tokens: 60,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 100,
+                        },
+                        last_token_usage: {
+                            input_tokens: 40,
+                            cached_input_tokens: 0,
+                            output_tokens: 60,
+                            reasoning_output_tokens: 0,
+                            total_tokens: 100,
+                        },
+                    },
+                },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-11T19:00:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "day one" }] },
+            }),
+            JSON.stringify({
+                timestamp: "2026-02-12T19:00:00.000Z",
+                type: "response_item",
+                payload: { type: "message", role: "assistant", content: [{ type: "output_text", text: "day two" }] },
+            }),
+        ].join("\n");
+        const fixture = await buildFixtureWithCustomTrace(traceLog, "cost-trace");
+        const nextConfig = mergeConfig({
+            ...fixture.index.getConfig(),
+            activityHeatmap: {
+                metric: "total_cost_usd",
+                color: "#2563eb",
+            },
+        });
+        fixture.index.setConfig(nextConfig);
+        await saveConfig(nextConfig, fixture.configPath);
         const server = await createServer({
             traceIndex: fixture.index,
             configPath: fixture.configPath,
@@ -877,17 +1219,103 @@ describe("server api", () => {
         });
         const response = await server.inject({
             method: "GET",
-            url: "/api/activity/week?end_date=2026-02-22&tz_offset_min=0&day_count=53&slot_min=30&hour_start=7&hour_end=7",
+            url: "/api/activity/year?end_date=2026-02-12&tz_offset_min=0&day_count=365",
         });
         expect(response.statusCode).toBe(200);
         const payload = response.json();
-        expect(payload.activity.dayCount).toBe(53);
-        expect(payload.activity.days).toHaveLength(53);
-        expect(payload.activity.days[0]?.dateLocal).toBe("2026-01-01");
-        expect(payload.activity.days[52]?.dateLocal).toBe("2026-02-22");
-        expect(payload.activity.days.every((day) => day.bins.length === 48)).toBe(true);
+        expect(payload.activity.presentation).toMatchObject({
+            metric: "total_cost_usd",
+            color: "#2563eb",
+        });
+        const firstDayCost = payload.activity.days[0]?.heatmapValue ?? 0;
+        const secondDayCost = payload.activity.days[1]?.heatmapValue ?? 0;
+        expect(firstDayCost).toBeCloseTo(0.0001, 6);
+        expect(secondDayCost).toBeCloseTo(0, 6);
         await server.close();
     }, 20_000);
+    it("builds yearly activity without reparsing cold traces", async () => {
+        const root = await mkdtemp(path.join(os.tmpdir(), "agentlens-server-year-cold-"));
+        const codexRoot = path.join(root, ".codex", "sessions", "2026", "02", "11");
+        await mkdir(codexRoot, { recursive: true });
+        for (const [index, filename] of ["rollout-a.jsonl", "rollout-b.jsonl", "rollout-c.jsonl"].entries()) {
+            await writeFile(path.join(codexRoot, filename), [
+                JSON.stringify({
+                    timestamp: `2026-02-11T10:00:0${index}.000Z`,
+                    type: "session_meta",
+                    payload: { id: `server-cold-${index}`, cwd: "/tmp/project", cli_version: "0.1.0" },
+                }),
+                JSON.stringify({
+                    timestamp: `2026-02-11T10:05:0${index}.000Z`,
+                    type: "response_item",
+                    payload: {
+                        type: "message",
+                        role: "assistant",
+                        content: [{ type: "output_text", text: `trace-${index}` }],
+                    },
+                }),
+            ].join("\n") + "\n", "utf8");
+        }
+        const config = mergeConfig({
+            retention: {
+                strategy: "aggressive_recency",
+                hotTraceCount: 1,
+                warmTraceCount: 0,
+                maxResidentEventsPerHotTrace: 1000,
+                maxResidentEventsPerWarmTrace: 50,
+                detailLoadMode: "lazy_from_disk",
+            },
+            sessionLogDirectories: [],
+            sources: {
+                codex_home: {
+                    name: "codex_home",
+                    enabled: true,
+                    roots: [path.join(root, ".codex", "sessions")],
+                    includeGlobs: ["**/*.jsonl"],
+                    excludeGlobs: [],
+                    maxDepth: 8,
+                    agentHint: "codex",
+                },
+                claude_projects: {
+                    name: "claude_projects",
+                    enabled: false,
+                    roots: [],
+                    includeGlobs: ["**/*.jsonl"],
+                    excludeGlobs: [],
+                    maxDepth: 8,
+                    agentHint: "claude",
+                },
+                claude_history: {
+                    name: "claude_history",
+                    enabled: false,
+                    roots: [],
+                    includeGlobs: ["history.jsonl"],
+                    excludeGlobs: [],
+                    maxDepth: 8,
+                    agentHint: "claude",
+                },
+            },
+        });
+        const configPath = path.join(root, "config.toml");
+        await saveConfig(config, configPath);
+        const index = new TraceIndex(config);
+        await index.start();
+        expect(index.getSummaries()[2]?.residentTier).not.toBe("hot");
+        const internal = index;
+        const parseFileSyncSpy = vi.spyOn(internal.parserRegistry, "parseFileSync");
+        const server = await createServer({
+            traceIndex: index,
+            configPath,
+            enableStatic: false,
+        });
+        const response = await server.inject({
+            method: "GET",
+            url: "/api/activity/year?end_date=2026-02-11&tz_offset_min=0&day_count=365",
+        });
+        expect(response.statusCode).toBe(200);
+        expect(parseFileSyncSpy).not.toHaveBeenCalled();
+        await server.close();
+        index.stop();
+    }, 20_000);
     it("returns validation errors for invalid activity day query params", async () => {
         const fixture = await buildFixtureWithTraceCount(1);
         const server = await createServer({
@@ -1002,6 +1430,239 @@ describe("server api", () => {
         expect(byStart.get(Date.UTC(2026, 1, 11, 13, 0, 0))).toBe(1);
         await server.close();
     }, 20_000);
+    it("listens before trace index startup resolves", async () => {
+        const fixture = await buildFixture();
+        let releaseStart = () => { };
+        const startDeferred = new Promise((resolve) => {
+            releaseStart = resolve;
+        });
+        let startupState = {
+            phase: "bootstrapping",
+            inspectorReady: false,
+            fullReady: false,
+            isPartial: false,
+            discoveredTraceCount: 0,
+            hydratedTraceCount: 0,
+            startupError: "",
+        };
+        const startSpy = vi.spyOn(fixture.index, "start").mockImplementation(async () => {
+            await startDeferred;
+            startupState = {
+                phase: "ready",
+                inspectorReady: true,
+                fullReady: true,
+                isPartial: false,
+                discoveredTraceCount: 1,
+                hydratedTraceCount: 1,
+                startupError: "",
+            };
+        });
+        const startupSpy = vi.spyOn(fixture.index, "getStartupStatus").mockImplementation(() => startupState);
+        const server = await runServer({
+            host: "127.0.0.1",
+            port: 0,
+            configPath: fixture.configPath,
+            enableStatic: false,
+            traceIndex: fixture.index,
+        });
+        try {
+            expect(startSpy).toHaveBeenCalledOnce();
+            const health = await server.inject({ method: "GET", url: "/api/healthz" });
+            expect(health.statusCode).toBe(200);
+            expect(health.json()).toEqual({ ok: true });
+            const notReady = await server.inject({ method: "GET", url: "/api/readyz" });
+            expect(notReady.statusCode).toBe(503);
+            expect(notReady.json()).toEqual({ ok: false, ready: false, startup: startupState });
+            releaseStart();
+            await startDeferred;
+            const ready = await server.inject({ method: "GET", url: "/api/readyz" });
+            expect(ready.statusCode).toBe(200);
+            expect(ready.json()).toEqual({ ok: true, ready: true, startup: startupState });
+        }
+        finally {
+            fixture.index.stop();
+            await server.close();
+            startSpy.mockRestore();
+            startupSpy.mockRestore();
+        }
+    });
+    it("surfaces trace index startup failures through readiness endpoint", async () => {
+        const fixture = await buildFixture();
+        const startSpy = vi.spyOn(fixture.index, "start").mockRejectedValue(new Error("boom on startup"));
+        const startupState = {
+            phase: "failed",
+            inspectorReady: false,
+            fullReady: false,
+            isPartial: false,
+            discoveredTraceCount: 0,
+            hydratedTraceCount: 0,
+            startupError: "boom on startup",
+        };
+        const startupSpy = vi.spyOn(fixture.index, "getStartupStatus").mockReturnValue(startupState);
+        const server = await runServer({
+            host: "127.0.0.1",
+            port: 0,
+            configPath: fixture.configPath,
+            enableStatic: false,
+            traceIndex: fixture.index,
+        });
+        try {
+            expect(startSpy).toHaveBeenCalledOnce();
+            await new Promise((resolve) => setTimeout(resolve, 25));
+            const ready = await server.inject({ method: "GET", url: "/api/readyz" });
+            expect(ready.statusCode).toBe(503);
+            expect(ready.json()).toEqual({
+                ok: false,
+                ready: false,
+                startup: startupState,
+                startupError: "boom on startup",
+            });
+        }
+        finally {
+            fixture.index.stop();
+            await server.close();
+            startSpy.mockRestore();
+            startupSpy.mockRestore();
+        }
+    });
+    it("serves partial overview and warming activity while background hydration continues", async () => {
+        const fixture = await buildFixture();
+        const startupState = {
+            phase: "hydrating",
+            inspectorReady: true,
+            fullReady: false,
+            isPartial: true,
+            discoveredTraceCount: 240,
+            hydratedTraceCount: 120,
+            startupError: "",
+        };
+        const startupSpy = vi.spyOn(fixture.index, "getStartupStatus").mockReturnValue(startupState);
+        const dayProgress = {
+            ready: false,
+            relevantDiscoveredCount: 240,
+            relevantHydratedCount: 120,
+            percent: 50,
+        };
+        const progressSpy = vi.spyOn(fixture.index, "getHydrationProgress").mockReturnValue(dayProgress);
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        try {
+            const ready = await server.inject({ method: "GET", url: "/api/readyz" });
+            expect(ready.statusCode).toBe(200);
+            expect(ready.json()).toEqual({ ok: true, ready: true, startup: startupState });
+            const overview = await server.inject({ method: "GET", url: "/api/overview" });
+            expect(overview.statusCode).toBe(200);
+            expect(overview.json()).toMatchObject({
+                overview: expect.any(Object),
+                startup: startupState,
+            });
+            const day = await server.inject({
+                method: "GET",
+                url: "/api/activity/day?date=2026-02-11&tz_offset_min=0&bin_min=5&break_min=10",
+            });
+            expect(day.statusCode).toBe(503);
+            expect(day.json()).toEqual({
+                warming: true,
+                progress: dayProgress,
+            });
+            const year = await server.inject({
+                method: "GET",
+                url: "/api/activity/year?end_date=2026-02-11&tz_offset_min=0&day_count=365",
+            });
+            expect(year.statusCode).toBe(503);
+            expect(year.json()).toEqual({
+                warming: true,
+                progress: dayProgress,
+            });
+        }
+        finally {
+            progressSpy.mockRestore();
+            startupSpy.mockRestore();
+            fixture.index.stop();
+            await server.close();
+        }
+    });
+    it("keeps activity warming until inspector bootstrap metadata is ready", async () => {
+        const fixture = await buildFixture();
+        const startupState = {
+            phase: "bootstrapping",
+            inspectorReady: false,
+            fullReady: false,
+            isPartial: false,
+            discoveredTraceCount: 0,
+            hydratedTraceCount: 0,
+            startupError: "",
+        };
+        const startupSpy = vi.spyOn(fixture.index, "getStartupStatus").mockReturnValue(startupState);
+        const progressSpy = vi.spyOn(fixture.index, "getHydrationProgress").mockReturnValue({
+            ready: true,
+            relevantDiscoveredCount: 12,
+            relevantHydratedCount: 12,
+            percent: 100,
+        });
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        try {
+            const day = await server.inject({
+                method: "GET",
+                url: "/api/activity/day?date=2026-02-11&tz_offset_min=0&bin_min=5&break_min=10",
+            });
+            expect(day.statusCode).toBe(503);
+            expect(day.json()).toEqual({
+                warming: true,
+                progress: {
+                    ready: false,
+                    relevantDiscoveredCount: 0,
+                    relevantHydratedCount: 0,
+                    percent: 0,
+                },
+            });
+        }
+        finally {
+            progressSpy.mockRestore();
+            startupSpy.mockRestore();
+            fixture.index.stop();
+            await server.close();
+        }
+    });
+    it("allows day activity to load before slower year hydration completes", async () => {
+        const fixture = await buildFixture();
+        const progressSpy = vi.spyOn(fixture.index, "getHydrationProgress").mockImplementation((windowStartMs) => windowStartMs >= Date.UTC(2026, 1, 11, 7, 0, 0)
+            ? { ready: true, relevantDiscoveredCount: 12, relevantHydratedCount: 12, percent: 100 }
+            : { ready: false, relevantDiscoveredCount: 240, relevantHydratedCount: 120, percent: 50 });
+        const server = await createServer({
+            traceIndex: fixture.index,
+            configPath: fixture.configPath,
+            enableStatic: false,
+        });
+        try {
+            const day = await server.inject({
+                method: "GET",
+                url: "/api/activity/day?date=2026-02-11&tz_offset_min=0&bin_min=5&break_min=10",
+            });
+            expect(day.statusCode).toBe(200);
+            const year = await server.inject({
+                method: "GET",
+                url: "/api/activity/year?end_date=2026-02-11&tz_offset_min=0&day_count=365",
+            });
+            expect(year.statusCode).toBe(503);
+            expect(year.json()).toEqual({
+                warming: true,
+                progress: { ready: false, relevantDiscoveredCount: 240, relevantHydratedCount: 120, percent: 50 },
+            });
+        }
+        finally {
+            progressSpy.mockRestore();
+            fixture.index.stop();
+            await server.close();
+        }
+    });
     it("serves overview, trace listing, trace details, stop/open controls, and config updates", async () => {
         const fixture = await buildFixture();
         const stopTraceSession = vi.fn();