agent-profiler 1.0.0 → 1.0.1

package/README.md

@@ -1,8 +1,32 @@
-# agent-profiler
+# Agent Profiler
 
-Local-first profiling for AI coding agents.
+![Agent Profiler Dashboard](assets/dashboard.png)
 
-`agent-profiler` captures local Cursor and Codex hook events into SQLite so you can inspect recent sessions, setup state, and always-on context overhead without sending data to a remote service.
+**Agent Profiler** is a **local-first** tool for understanding how AI coding agents spend observable effort in your workspace. It records Cursor and Codex hook traffic into **SQLite** so you can review session shape, estimated token usage, tool and shell noise, always-on context weight, and simple efficiency signals—**without sending telemetry to a remote service.**
+
+Today the workflow is intentionally scoped **project-by-project**: you run commands from a repo root, store profiler config and data under **`.agent-profiler/`** beside that project, and inspect sessions with the CLI or the optional dashboard. **A future direction** is to offer a clearer opt-in path to operate primarily from the **home-directory** profile (for example global installs and multi-repo DB layout) when users want that; the current release optimizes for **per-repo isolation** and predictable paths.
+
+On **`agent-profiler init`** in **dev** mode, when the profiler directory resolves to **`<project>/.agent-profiler`**, the tool **appends a `.gitignore` rule** so the local store (including SQLite and synced dashboard assets) is **not committed** by mistake.
+
+## Dashboard (early version)
+
+Run a minimal **localhost-only** web UI over the same database and context audit used by `last`:
+
+```bash
+agent-profiler dashboard
+# open http://127.0.0.1:3737/ — use Refresh to reload metrics
+```
+
+The dashboard (**early version**) surfaces:
+
+- **Observable usage** — estimated input, output, tool/MCP result, and shell output tokens with simple bar proportions
+- **Efficiency score** — heuristic score with a small sparkline over recent keyed sessions (when present)
+- **Session timeline** — chronological strip colored by role (user, assistant, tool, shell, other)
+- **Tool result sizes** — histogram buckets for large tool payloads
+- **Context audit** — estimated tokens for common always-on instruction paths in the repo
+- **Red flags and recommendations** — aligned with the `last` command logic
+
+Static assets are copied into **`.agent-profiler/dashboard/`** when the server starts so the UI stays next to your project data. Expect **rough edges and UI iteration** in future releases.
 
 ## Requirements
 
@@ -47,6 +71,11 @@ agent-profiler last
 agent-profiler audit context
 ```
 
+### Hook approval and restarts
+
+- **Codex**: Hooks must be **approved** before they run—confirm when prompted or enable them in the **Codex plugin settings**.
+- **Cursor**: **Restart Cursor** after `init` so hook configuration reliably takes effect.
+
 ## `npx` vs `--mode prod`
 
 - `npx agent-profiler ...` is great for one-off inspection commands.
@@ -59,6 +88,7 @@ agent-profiler audit context
 - `agent-profiler hook <source> <eventName>`: ingest one hook payload from stdin
 - `agent-profiler status`: inspect local setup and ingest state
 - `agent-profiler last`: summarize the most recent observed session
+- `agent-profiler dashboard`: serve the local dashboard (SQLite + context audit)
 - `agent-profiler audit context`: estimate always-on context token footprint
 
 ## Releases

package/dist/adapters/cursor.js

@@ -62,7 +62,11 @@ function extractObservableText(payload) {
     const toolResponse = stringifyJsonish(payload.tool_response ?? payload.toolResponse ?? payload.result);
     if (toolResponse)
         return toolResponse;
-    const toolInput = stringifyJsonish(payload.tool_input ?? payload.toolInput ?? payload.input ?? payload.args ?? payload.arguments);
+    const toolInput = stringifyJsonish(payload.tool_input ??
+        payload.toolInput ??
+        payload.input ??
+        payload.args ??
+        payload.arguments);
     if (toolInput)
         return toolInput;
     return JSON.stringify(payload);

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { getAuditContextReport, runAuditContext, } from "./commands/auditContext.js";
 import { runHook } from "./commands/hook.js";
+import { runDashboard } from "./commands/dashboard.js";
 import { runInit } from "./commands/init.js";
 import { getLastReport, runLast } from "./commands/last.js";
 import { getStatusReport, runStatus } from "./commands/status.js";
@@ -75,6 +76,28 @@ program
     }
     runStatus(options.mode);
 });
+program
+    .command("dashboard")
+    .description("Serve a local dashboard (SQLite + context audit). Copies UI into .agent-profiler/dashboard/.")
+    .option("--host <host>", "Bind address", "127.0.0.1")
+    .option("--port <port>", "HTTP port", "3737")
+    .action((opts) => {
+    const port = parseInt(opts.port ?? "3737", 10);
+    if (!Number.isFinite(port) || port < 1 || port > 65535) {
+        console.error(`Invalid port: ${opts.port}`);
+        process.exitCode = 1;
+        return;
+    }
+    const host = opts.host ?? "127.0.0.1";
+    try {
+        runDashboard({ host, port });
+    }
+    catch (error) {
+        console.error("Failed to start dashboard.");
+        console.error(error);
+        process.exitCode = 1;
+    }
+});
 program
     .command("last")
     .description("Generate a report for the most recent observed session.")

package/dist/commands/dashboard.js

@@ -0,0 +1,17 @@
+import { createDashboardServer, listenDashboardServer, resolvePackagedDashboardDir, resolveProjectDashboardDir, syncDashboardAssets, } from "../core/dashboardServer.js";
+export function runDashboard(options) {
+    const cwd = process.cwd();
+    const packaged = resolvePackagedDashboardDir();
+    const target = resolveProjectDashboardDir(cwd);
+    syncDashboardAssets(packaged, target);
+    const server = createDashboardServer({
+        host: options.host,
+        port: options.port,
+        staticRoot: target,
+        cwd,
+    });
+    void listenDashboardServer(server, options.host, options.port).then(({ url }) => {
+        console.log(`Agent Profiler dashboard: ${url}`);
+        console.log("Press Ctrl+C to stop.");
+    });
+}

package/dist/commands/init.js

@@ -3,6 +3,26 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { openDb, resolveUsableDbPath } from "../core/db.js";
 import { getHomeProfileDir, getLocalProfileDir } from "../core/profile.js";
+const GITIGNORE_MARKER = "# Agent Profiler local store";
+const GITIGNORE_ENTRY = ".agent-profiler/";
+function ensureProfilerGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    const block = `${GITIGNORE_MARKER}\n${GITIGNORE_ENTRY}\n`;
+    let existing = "";
+    try {
+        existing = fs.readFileSync(gitignorePath, "utf8");
+    }
+    catch {
+        fs.writeFileSync(gitignorePath, block, "utf8");
+        return;
+    }
+    const lines = existing.split(/\r?\n/);
+    const hasEntry = lines.some((line) => line.trim() === GITIGNORE_ENTRY || line.trim() === ".agent-profiler");
+    if (hasEntry)
+        return;
+    const suffix = existing.endsWith("\n") || existing.length === 0 ? "" : "\n";
+    fs.appendFileSync(gitignorePath, `${suffix}\n${block}`, "utf8");
+}
 const CURSOR_EVENTS = [
     "beforeSubmitPrompt",
     "afterAgentResponse",
@@ -190,6 +210,12 @@ export function runInit(source, mode = "dev") {
     const resolvedDbPath = resolveUsableDbPath(configuredDbPath);
     const db = openDb(resolvedDbPath);
     db.close();
+    if (mode === "dev") {
+        const localProfiler = path.resolve(getLocalProfileDir(process.cwd()));
+        if (path.resolve(profilerDir) === localProfiler) {
+            ensureProfilerGitignore(process.cwd());
+        }
+    }
     let hooksPath = "";
     let configPath = path.join(profilerDir, "config.json");
     let usedFallbackConfigPath = false;

package/dist/commands/last.js

@@ -1,201 +1,13 @@
-import { getDefaultDbPath, getEventsForLatestSession, openDb } from "../core/db.js";
-import { runContextAudit } from "../core/contextAudit.js";
-function parsePayload(rawPayload) {
-    try {
-        const parsed = JSON.parse(rawPayload);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
-    }
-    catch {
-        // ignore malformed payloads
-    }
-    return {};
-}
-function formatTokens(value) {
-    return `~${new Intl.NumberFormat("en-US").format(value)} tokens`;
-}
+import { getDefaultDbPath, getEventsForLatestSession, openDb, } from "../core/db.js";
+import { analyzeSession, formatTokens, LARGEST_EVENTS_LIMIT, } from "../core/sessionAnalytics.js";
 function formatDuration(mins) {
     return mins < 1 ? "<1 minute" : `${mins} minute${mins === 1 ? "" : "s"}`;
 }
-function normalizeSnippet(value) {
-    return value.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 160);
-}
-const LARGEST_EVENTS_LIMIT = 10;
 export function getLastReport() {
     const db = openDb(getDefaultDbPath());
     const events = getEventsForLatestSession(db);
     db.close();
-    if (events.length === 0) {
-        return null;
-    }
-    const first = events[0];
-    const last = events[events.length - 1];
-    const start = new Date(first.createdAt).getTime();
-    const end = new Date(last.createdAt).getTime();
-    const durationMinutes = Math.max(0, Math.round((end - start) / 60000));
-    let input = 0;
-    let output = 0;
-    let total = 0;
-    let shellOutput = 0;
-    let toolResults = 0;
-    const turnIds = new Set();
-    let fileEdits = 0;
-    let shellCalls = 0;
-    let toolCalls = 0;
-    const fileEditCounts = new Map();
-    const redFlags = [];
-    let recommendations = [];
-    const shellFailureBuckets = new Map();
-    for (const event of events) {
-        input += event.estimatedInputTokens;
-        output += event.estimatedOutputTokens;
-        total += event.estimatedTotalTokens;
-        if (event.turnId)
-            turnIds.add(event.turnId);
-        if (event.role === "file_edit") {
-            fileEdits += 1;
-            const payload = parsePayload(event.rawPayload);
-            const file = (payload.filePath ?? payload.path ?? payload.relativePath);
-            if (file) {
-                fileEditCounts.set(file, (fileEditCounts.get(file) ?? 0) + 1);
-            }
-        }
-        if (event.role === "shell_command")
-            shellCalls += 1;
-        if (event.role === "shell_output") {
-            shellCalls += 1;
-            shellOutput += event.estimatedTotalTokens;
-            const payload = parsePayload(event.rawPayload);
-            const command = typeof payload.command === "string" ? payload.command : null;
-            const stderr = typeof payload.stderr === "string" ? payload.stderr : "";
-            const stdout = typeof payload.stdout === "string" ? payload.stdout : "";
-            const outputSnippet = normalizeSnippet(stderr || stdout);
-            const looksFailed = outputSnippet.includes("error") ||
-                outputSnippet.includes("failed") ||
-                outputSnippet.includes("exception") ||
-                outputSnippet.includes("traceback");
-            if (command && looksFailed) {
-                const key = `${normalizeSnippet(command)}|${outputSnippet}`;
-                const prev = shellFailureBuckets.get(key) ?? { runs: 0, tokenTotal: 0 };
-                shellFailureBuckets.set(key, {
-                    runs: prev.runs + 1,
-                    tokenTotal: prev.tokenTotal + event.estimatedTotalTokens,
-                });
-            }
-        }
-        if (event.role === "tool_call")
-            toolCalls += 1;
-        if (event.role === "tool_result" || event.role === "tool_failure")
-            toolResults += event.estimatedTotalTokens;
-    }
-    let score = 100;
-    const topChurn = [...fileEditCounts.entries()].sort((a, b) => b[1] - a[1])[0];
-    if (topChurn && topChurn[1] >= 5) {
-        redFlags.push({
-            severity: "HIGH",
-            title: "same-file churn",
-            detail: `${topChurn[0]} was edited ${topChurn[1]} times.`,
-            recommendation: "Add a focused repo rule or skill note for this file's recurring failure pattern.",
-            penalty: 15,
-        });
-    }
-    if (shellOutput > 4000) {
-        redFlags.push({
-            severity: "HIGH",
-            title: "shell output noise",
-            detail: `Shell output produced ${formatTokens(shellOutput)} in this session.`,
-            recommendation: "Capture key test/build failures once, then summarize repeated output.",
-            penalty: 12,
-        });
-    }
-    if (toolResults > 4000) {
-        redFlags.push({
-            severity: "MEDIUM",
-            title: "large tool result",
-            detail: `Tool results produced ${formatTokens(toolResults)} in this session.`,
-            recommendation: "Request narrower tool queries and summarize oversized tool responses.",
-            penalty: 10,
-        });
-    }
-    const worstFailureLoop = [...shellFailureBuckets.entries()].sort((a, b) => b[1].runs - a[1].runs || b[1].tokenTotal - a[1].tokenTotal)[0];
-    if (worstFailureLoop && worstFailureLoop[1].runs >= 3) {
-        redFlags.push({
-            severity: "HIGH",
-            title: "thrashing loop",
-            detail: `A similar failing shell command looped ${worstFailureLoop[1].runs} times (${formatTokens(worstFailureLoop[1].tokenTotal)}).`,
-            recommendation: "Pause after repeated failures, capture one root error, then adjust strategy.",
-            penalty: 14,
-        });
-    }
-    const largestPrompt = events
-        .filter((e) => e.role === "user_prompt")
-        .reduce((max, cur) => Math.max(max, cur.estimatedTotalTokens), 0);
-    if (largestPrompt > 8000) {
-        redFlags.push({
-            severity: "MEDIUM",
-            title: "oversized prompt",
-            detail: `Largest prompt was ${formatTokens(largestPrompt)}.`,
-            recommendation: "Split goals into smaller requests and load reference docs on demand.",
-            penalty: 8,
-        });
-    }
-    if (total > 12000 && fileEdits === 0) {
-        redFlags.push({
-            severity: "MEDIUM",
-            title: "low-signal session",
-            detail: `High observable usage (${formatTokens(total)}) with no file edits.`,
-            recommendation: "Push for earlier implementation checkpoints instead of extended analysis.",
-            penalty: 10,
-        });
-    }
-    const contextAudit = runContextAudit(process.cwd());
-    if (contextAudit.totalEstimatedTokens > 6000) {
-        redFlags.push({
-            severity: "MEDIUM",
-            title: "context bloat",
-            detail: `Always-on instruction files estimate ${formatTokens(contextAudit.totalEstimatedTokens)}.`,
-            recommendation: "Move large static references into on-demand skills or targeted commands.",
-            penalty: 10,
-        });
-    }
-    for (const flag of redFlags)
-        score -= flag.penalty;
-    score = Math.max(0, score);
-    recommendations = [...new Set(redFlags.map((r) => r.recommendation))];
-    if (recommendations.length === 0) {
-        recommendations = [
-            "No major waste pattern detected. Keep prompts scoped and continue tracking trends.",
-        ];
-    }
-    const largestEvents = [...events]
-        .sort((a, b) => b.estimatedTotalTokens - a.estimatedTotalTokens)
-        .slice(0, LARGEST_EVENTS_LIMIT)
-        .map((e) => ({
-        role: e.role,
-        sourceEvent: e.sourceEvent,
-        estimatedTotalTokens: e.estimatedTotalTokens,
-    }));
-    return {
-        source: first.source,
-        repo: first.repoPath ?? process.cwd(),
-        durationMinutes,
-        usage: { input, output, toolResults, shellOutput, total },
-        sessionShape: {
-            turns: turnIds.size,
-            fileEdits,
-            shellCalls,
-            toolCalls,
-        },
-        largestEvents,
-        efficiencyScore: score,
-        redFlags: redFlags.map((flag) => ({
-            severity: flag.severity,
-            title: flag.title,
-            detail: flag.detail,
-        })),
-        recommendations,
-    };
+    return analyzeSession(events, { contextAuditRoot: process.cwd() });
 }
 export function runLast() {
     const report = getLastReport();

package/dist/core/dashboardServer.js

@@ -0,0 +1,294 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getDefaultDbPath, getEventsForLegacyRepoWindow, getEventsForSession, getLatestSessionDescriptor, getLegacyRepoTimeline, getSessionTimeline, listRecentSessions, openDb, } from "./db.js";
+import { analyzeSession } from "./sessionAnalytics.js";
+import { runContextAudit } from "./contextAudit.js";
+import { getLocalProfileDir } from "./profile.js";
+/** Bump when bundled dashboard assets change so consumers pick up updates. */
+export const DASHBOARD_ASSETS_VERSION = "2";
+/**
+ * Built CLI reads `dist/dashboard/` (flat). `tsx src/...` resolves under `src/core/`, where sources live in
+ * `src/dashboard/public/` — prefer whichever layout contains `index.html`.
+ */
+export function resolvePackagedDashboardDir() {
+    const coreDir = path.dirname(fileURLToPath(import.meta.url));
+    const dashboardRoot = path.join(coreDir, "..", "dashboard");
+    const nestedPublic = path.join(dashboardRoot, "public");
+    if (fs.existsSync(path.join(dashboardRoot, "index.html"))) {
+        return dashboardRoot;
+    }
+    if (fs.existsSync(path.join(nestedPublic, "index.html"))) {
+        return nestedPublic;
+    }
+    return dashboardRoot;
+}
+export function resolveProjectDashboardDir(cwd = process.cwd()) {
+    return path.join(getLocalProfileDir(cwd), "dashboard");
+}
+export function syncDashboardAssets(packageDashboardDir, targetDir) {
+    if (!fs.existsSync(packageDashboardDir)) {
+        throw new Error(`Dashboard assets missing at ${packageDashboardDir}. Run npm run build.`);
+    }
+    if (!fs.existsSync(path.join(packageDashboardDir, "index.html"))) {
+        throw new Error(`Dashboard assets incomplete at ${packageDashboardDir} (missing index.html). Run npm run build.`);
+    }
+    fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+    if (fs.existsSync(targetDir)) {
+        fs.rmSync(targetDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.cpSync(packageDashboardDir, targetDir, { recursive: true, force: true });
+    fs.writeFileSync(path.join(targetDir, ".agent-profiler-dashboard-version"), `${DASHBOARD_ASSETS_VERSION}\n`, "utf8");
+}
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".png": "image/png",
+    ".woff2": "font/woff2",
+};
+function safeJoinStatic(root, requestPath) {
+    const trimmed = requestPath.replace(/^\/+/, "") || "index.html";
+    const segments = trimmed.split("/").filter((s) => s.length > 0 && s !== ".");
+    if (segments.some((s) => s === ".."))
+        return null;
+    const rootNorm = path.normalize(path.resolve(root));
+    const resolved = path.normalize(path.resolve(rootNorm, ...segments));
+    const rel = path.relative(rootNorm, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    return resolved;
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+    });
+    res.end(payload);
+}
+function readQuery(url) {
+    const out = {};
+    url.searchParams.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}
+function resolveLatestEvents(db) {
+    const desc = getLatestSessionDescriptor(db);
+    if (!desc)
+        return [];
+    if (desc.sessionId && desc.sessionId.trim().length > 0) {
+        return getEventsForSession(db, desc.source, desc.sessionId);
+    }
+    return getEventsForLegacyRepoWindow(db, desc.source, desc.repoPath);
+}
+function resolveSessionEvents(db, source, sessionId, repoPath, legacy) {
+    if (legacy || !sessionId || sessionId.trim() === "") {
+        return getEventsForLegacyRepoWindow(db, source, repoPath ?? null);
+    }
+    return getEventsForSession(db, source, sessionId);
+}
+/** Defaults to latest session when `source` omitted from query. */
+function resolveSessionQueryParams(db, q) {
+    let source = q.source ?? "";
+    let sessionId = q.sessionId;
+    let repoPath = q.repoPath !== undefined
+        ? q.repoPath.length > 0
+            ? q.repoPath
+            : null
+        : undefined;
+    let legacy = q.legacy === "1" || q.legacy === "true";
+    if (!source) {
+        const desc = getLatestSessionDescriptor(db);
+        if (!desc)
+            return null;
+        source = desc.source;
+        sessionId = desc.sessionId ?? undefined;
+        repoPath = desc.repoPath ?? null;
+        legacy = !sessionId || sessionId.trim() === "";
+    }
+    else if ((legacy || !sessionId || sessionId.trim() === "") &&
+        repoPath === undefined) {
+        const desc = getLatestSessionDescriptor(db);
+        if (desc && desc.source === source) {
+            repoPath = desc.repoPath ?? null;
+        }
+    }
+    return {
+        source,
+        sessionId,
+        repoPath: repoPath ?? null,
+        legacy,
+    };
+}
+function toolHistogramFromEvents(events) {
+    const sizes = events
+        .filter((e) => e.role === "tool_result" || e.role === "tool_failure")
+        .map((e) => e.estimatedTotalTokens);
+    const buckets = [
+        { label: "0–2k", min: 0, max: 2000 },
+        { label: "2k–10k", min: 2001, max: 10000 },
+        { label: "10k–50k", min: 10001, max: 50000 },
+        { label: "50k+", min: 50001, max: Infinity },
+    ];
+    const counts = buckets.map((b) => ({ bucket: b.label, count: 0 }));
+    for (const t of sizes) {
+        const idx = buckets.findIndex((b) => t >= b.min && t <= b.max);
+        if (idx >= 0)
+            counts[idx].count += 1;
+    }
+    return counts;
+}
+export function createDashboardServer(options) {
+    const { staticRoot, cwd } = options;
+    const server = http.createServer((req, res) => {
+        const urlRaw = req.url ?? "/";
+        let pathname = urlRaw;
+        try {
+            const u = new URL(urlRaw, `http://${req.headers.host ?? "localhost"}`);
+            pathname = u.pathname;
+            const url = u;
+            if (pathname.startsWith("/api/")) {
+                const dbPath = getDefaultDbPath();
+                let db;
+                try {
+                    db = openDb(dbPath);
+                }
+                catch (e) {
+                    sendJson(res, 500, { error: String(e) });
+                    return;
+                }
+                try {
+                    if (pathname === "/api/overview") {
+                        const events = resolveLatestEvents(db);
+                        const report = analyzeSession(events, { contextAuditRoot: cwd });
+                        const desc = getLatestSessionDescriptor(db);
+                        sendJson(res, 200, {
+                            databasePath: dbPath,
+                            descriptor: desc,
+                            report,
+                        });
+                        return;
+                    }
+                    if (pathname === "/api/session/report") {
+                        const resolved = resolveSessionQueryParams(db, readQuery(url));
+                        if (!resolved) {
+                            sendJson(res, 200, { report: null });
+                            return;
+                        }
+                        const events = resolveSessionEvents(db, resolved.source, resolved.sessionId, resolved.repoPath, resolved.legacy);
+                        const report = analyzeSession(events, { contextAuditRoot: cwd });
+                        sendJson(res, 200, { report });
+                        return;
+                    }
+                    if (pathname === "/api/sessions") {
+                        const q = readQuery(url);
+                        const limit = Math.min(100, Math.max(1, parseInt(q.limit ?? "20", 10) || 20));
+                        const rows = listRecentSessions(db, limit);
+                        sendJson(res, 200, { sessions: rows });
+                        return;
+                    }
+                    if (pathname === "/api/session/timeline") {
+                        const q = readQuery(url);
+                        const resolved = resolveSessionQueryParams(db, q);
+                        if (!resolved) {
+                            sendJson(res, 200, { timeline: [] });
+                            return;
+                        }
+                        const { source, sessionId, repoPath, legacy } = resolved;
+                        const timeline = legacy || !sessionId || sessionId.trim() === ""
+                            ? getLegacyRepoTimeline(db, source, repoPath)
+                            : getSessionTimeline(db, source, sessionId);
+                        sendJson(res, 200, { timeline });
+                        return;
+                    }
+                    if (pathname === "/api/tool-histogram") {
+                        const q = readQuery(url);
+                        const resolved = resolveSessionQueryParams(db, q);
+                        if (!resolved) {
+                            sendJson(res, 200, { histogram: [] });
+                            return;
+                        }
+                        const { source, sessionId, repoPath, legacy } = resolved;
+                        const events = resolveSessionEvents(db, source, sessionId, repoPath, legacy);
+                        sendJson(res, 200, { histogram: toolHistogramFromEvents(events) });
+                        return;
+                    }
+                    if (pathname === "/api/context-audit") {
+                        sendJson(res, 200, runContextAudit(cwd));
+                        return;
+                    }
+                    if (pathname === "/api/score-history") {
+                        const q = readQuery(url);
+                        const limit = Math.min(50, Math.max(1, parseInt(q.limit ?? "15", 10) || 15));
+                        const sessions = listRecentSessions(db, limit);
+                        const points = [];
+                        for (const s of sessions) {
+                            const ev = getEventsForSession(db, s.source, s.sessionId);
+                            const report = analyzeSession(ev, { contextAuditRoot: cwd });
+                            if (report) {
+                                points.push({
+                                    endedAt: s.endedAt,
+                                    efficiencyScore: report.efficiencyScore,
+                                    sessionId: s.sessionId,
+                                });
+                            }
+                        }
+                        points.sort((a, b) => a.endedAt.localeCompare(b.endedAt));
+                        sendJson(res, 200, { points });
+                        return;
+                    }
+                    sendJson(res, 404, { error: "not found" });
+                }
+                finally {
+                    db.close();
+                }
+                return;
+            }
+            const filePath = safeJoinStatic(staticRoot, pathname);
+            if (!filePath) {
+                res.writeHead(403).end();
+                return;
+            }
+            let diskPath = filePath;
+            if (fs.existsSync(diskPath) && fs.statSync(diskPath).isDirectory()) {
+                diskPath = path.join(diskPath, "index.html");
+            }
+            if (!fs.existsSync(diskPath) || !fs.statSync(diskPath).isFile()) {
+                res.writeHead(404).end("Not found");
+                return;
+            }
+            const ext = path.extname(diskPath).toLowerCase();
+            const type = MIME[ext] ?? "application/octet-stream";
+            const stream = fs.createReadStream(diskPath);
+            res.writeHead(200, {
+                "Content-Type": type,
+                // Local dashboard: always revalidate so fixes to app.js/CSS show up without fighting browser cache.
+                "Cache-Control": "no-store",
+            });
+            stream.pipe(res);
+        }
+        catch {
+            res.writeHead(400).end();
+        }
+    });
+    return server;
+}
+export function listenDashboardServer(server, host, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const resolvedPort = typeof addr === "object" && addr !== null && "port" in addr
+                ? addr.port
+                : port;
+            resolve({ url: `http://${host}:${resolvedPort}` });
+        });
+    });
+}