tokentrace 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.19.0] - 2026-06-04
+
+### Security
+
+- **The local dashboard now enforces a request perimeter.** All `/api/*` routes
+  go through `middleware.ts`, which rejects requests whose `Host` is not a
+  loopback name (defeating DNS-rebinding that would otherwise let a malicious
+  web page read your local data as "same-origin") and blocks cross-site
+  state-changing requests (defeating CSRF that could silently re-point the
+  scanner, change settings, or wipe imported data). Non-browser clients (CLI,
+  curl) are unaffected.
+- **File-preview endpoints are now contained.** `/api/parser-debug/preview` and
+  `/api/import-profile-preview` previously read any caller-supplied path. They
+  now resolve symlinks and only read files under your home directory, the OS
+  temp directory, or explicitly configured import folders, returning `403` for
+  anything else. This removes an arbitrary-file-read surface.
+- **`tokentrace serve` refuses non-loopback binds by default.** Binding to
+  `0.0.0.0` or a LAN address (via `--hostname` or `TOKENTRACE_HOSTNAME`) now
+  errors with guidance, since the dashboard is unauthenticated. Set
+  `TOKENTRACE_ALLOW_REMOTE=1` to override deliberately.
+- **Security response headers added.** The dashboard now sends a strict
+  same-origin `Content-Security-Policy`, `X-Frame-Options: DENY`,
+  `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, and a
+  restrictive `Permissions-Policy` (anti-clickjacking and anti-sniffing).
+
+## [0.18.1] - 2026-05-28
+
+### Fixed
+
+- **Scheduled scans now coalesce concurrent runs.** `runDueScheduledScan`
+  fires on every overview page load; two overlapping loads (a second tab, a
+  quick refresh, a prefetch) previously both passed the due-check and both
+  called `runScan`, producing duplicate scan runs. A module-scoped in-flight
+  promise guard now coalesces concurrent callers into a single scan within
+  the server process.
+- **`tokentrace repair auto-classify --apply` is now atomic.** The alias
+  writes and cost backfills for a batch run inside a single SQLite
+  transaction, and `backfillAlias` wraps its per-row updates in a transaction
+  too, so a failure partway can no longer leave the local database
+  half-applied with inaccurate reported counts.
+- **`tokentrace query` surfaces range errors cleanly.** Range validation
+  (e.g. `--from` after `--to`, or a preset combined with explicit dates) now
+  prints the validation message plus usage and exits non-zero, instead of
+  letting a raw stack trace escape.
+- **Anomaly z-scores survive JSON.** The flat-window (`mad === 0`) severe
+  branch reported `Infinity`, which `JSON.stringify` turned into `null` and
+  silently dropped the signal. It now reports a finite sentinel z-score.
+- **Stricter query CLI parsing.** Empty `--flag=` values are rejected with a
+  clear "Missing value" message rather than flowing through as empty strings.
+
+### Internal
+
+- **Test suite no longer flakes under parallel load.** CLI/MCP integration
+  tests spawn `bin/tokentrace.js`, which itself spawns `db-migrate` and
+  `db-seed`, fanning out to ~3x the core count in node processes. The Vitest
+  fork pool is now capped at roughly half the available cores with one
+  generous global timeout, removing the scattered per-test timeout overrides.
+- Removed the dead `tailwind.config.ts` left over from the Tailwind 4
+  (CSS-first) migration.
+
 ## [0.18.0] - 2026-05-28
 
 ### Local intelligence

package/app/api/import-profile-preview/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from "next/server";
+import { getAppSettings } from "@/src/db/settings";
 import { readJsonObject } from "@/src/lib/api-json";
 import { buildImportProfilePreview } from "@/src/lib/import-profile-preview";
+import { PathAccessError, pathAccessStatus, resolveReadablePath } from "@/src/lib/path-access";
 
 export const dynamic = "force-dynamic";
 
@@ -11,9 +13,22 @@ export async function POST(request: Request) {
   if (typeof filePath !== "string" || !filePath.trim()) {
     return NextResponse.json({ error: "filePath is required." }, { status: 400 });
   }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = await resolveReadablePath(filePath, {
+      extraRoots: getAppSettings().customFolders
+    });
+  } catch (error) {
+    if (error instanceof PathAccessError) {
+      return NextResponse.json({ error: error.message }, { status: pathAccessStatus(error.code) });
+    }
+    return NextResponse.json({ error: "Preview failed." }, { status: 400 });
+  }
+
   try {
     const preview = await buildImportProfilePreview({
-      filePath: filePath.trim(),
+      filePath: resolvedPath,
       storeRawMessageContent: parsed.body.storeRawMessageContent === true
     });
     return NextResponse.json(preview);

package/app/api/parser-debug/preview/route.ts

@@ -1,7 +1,9 @@
 import fs from "node:fs/promises";
 import { NextResponse } from "next/server";
+import { getAppSettings } from "@/src/db/settings";
 import { adapters } from "@/src/ingestion/adapters";
 import type { FileCandidate, NormalizedInteraction } from "@/src/ingestion/types";
+import { PathAccessError, pathAccessStatus, resolveReadablePath } from "@/src/lib/path-access";
 
 export const dynamic = "force-dynamic";
 
@@ -18,10 +20,10 @@ export async function POST(request: Request) {
     return NextResponse.json({ error: "Request body must be JSON." }, { status: 400 });
   }
 
-  const filePath = typeof body.path === "string" ? body.path.trim() : "";
+  const requestedPath = typeof body.path === "string" ? body.path.trim() : "";
   const parserId = typeof body.parserId === "string" ? body.parserId.trim() : "";
 
-  if (!filePath) {
+  if (!requestedPath) {
     return NextResponse.json({ error: "path is required" }, { status: 400 });
   }
   if (!parserId) {
@@ -36,11 +38,23 @@ export async function POST(request: Request) {
     );
   }
 
+  let filePath: string;
+  try {
+    filePath = await resolveReadablePath(requestedPath, {
+      extraRoots: getAppSettings().customFolders
+    });
+  } catch (error) {
+    if (error instanceof PathAccessError) {
+      return NextResponse.json({ error: error.message }, { status: pathAccessStatus(error.code) });
+    }
+    return NextResponse.json({ error: `file not found: ${requestedPath}` }, { status: 404 });
+  }
+
   let stat;
   try {
     stat = await fs.stat(filePath);
   } catch {
-    return NextResponse.json({ error: `file not found: ${filePath}` }, { status: 404 });
+    return NextResponse.json({ error: `file not found: ${requestedPath}` }, { status: 404 });
   }
 
   const candidate: FileCandidate = {

package/dist/runtime/anomalies.mjs

@@ -846,7 +846,7 @@ function scoreValue(value, window, thresholds) {
     }
     const flatRunLength = window.filter((entry) => entry === baseline).length;
     if (value > 2 * baseline && flatRunLength >= 3) {
-      return { severity: "severe", baseline, zScore: Number.POSITIVE_INFINITY };
+      return { severity: "severe", baseline, zScore: FLAT_RUN_Z };
     }
     return { severity: null, baseline, zScore: 0 };
   }
@@ -907,7 +907,7 @@ function detectAnomalies(points, options2 = {}) {
     summary
   };
 }
-var DEFAULT_WINDOW, DEFAULT_MIN_WINDOW, DEFAULT_THRESHOLDS, MAD_TO_STDDEV, METRICS;
+var DEFAULT_WINDOW, DEFAULT_MIN_WINDOW, DEFAULT_THRESHOLDS, MAD_TO_STDDEV, FLAT_RUN_Z, METRICS;
 var init_anomaly_detection = __esm({
   "src/lib/anomaly-detection.ts"() {
     "use strict";
@@ -915,6 +915,7 @@ var init_anomaly_detection = __esm({
     DEFAULT_MIN_WINDOW = 5;
     DEFAULT_THRESHOLDS = { notable: 3, high: 4.5, severe: 6 };
     MAD_TO_STDDEV = 0.6745;
+    FLAT_RUN_Z = 999;
     METRICS = [
       { metric: "tokens", valueOf: (point) => point.totalTokens },
       { metric: "cost", valueOf: (point) => point.cost }

package/dist/runtime/db-seed.mjs

@@ -1659,7 +1659,6 @@ function recalculateInteractionCosts() {
         currency: interaction.alias_currency ?? "USD"
       } : null;
       const resolvedPrice = aliasPrice ?? directPrice;
-      const resolvedViaAlias = aliasPrice != null;
       const cost = calculateInteractionCost(
         {
           inputTokens: interaction.input_tokens,
@@ -1671,6 +1670,7 @@ function recalculateInteractionCosts() {
         },
         resolvedPrice
       );
+      const resolvedViaAlias = aliasPrice != null && cost.amount != null;
       if (cost.status === "unknown") unknownCostInteractions += 1;
       const metadata = {
         ...existingMetadata,

package/dist/runtime/pricing-refresh.mjs

@@ -940,7 +940,6 @@ function recalculateInteractionCosts() {
         currency: interaction.alias_currency ?? "USD"
       } : null;
       const resolvedPrice = aliasPrice ?? directPrice;
-      const resolvedViaAlias = aliasPrice != null;
       const cost = calculateInteractionCost(
         {
           inputTokens: interaction.input_tokens,
@@ -952,6 +951,7 @@ function recalculateInteractionCosts() {
         },
         resolvedPrice
       );
+      const resolvedViaAlias = aliasPrice != null && cost.amount != null;
       if (cost.status === "unknown") unknownCostInteractions += 1;
       const metadata = {
         ...existingMetadata,

package/dist/runtime/query.mjs

@@ -942,7 +942,11 @@ var SORT = ["asc", "desc"];
 var PRESET = ["today", "7d", "30d", "60d", "90d", "all"];
 function valueOf(arg, next) {
   const eq = arg.indexOf("=");
-  if (eq >= 0) return { value: arg.slice(eq + 1), consumedNext: false };
+  if (eq >= 0) {
+    const value = arg.slice(eq + 1);
+    if (!value) throw new Error(`Missing value for ${arg.slice(0, eq)}`);
+    return { value, consumedNext: false };
+  }
   if (next == null || next.startsWith("-")) {
     throw new Error(`Missing value for ${arg}`);
   }
@@ -1075,7 +1079,14 @@ if (parsed.help) {
   process.exit(0);
 }
 var { runStructuredQuery: runStructuredQuery2 } = await Promise.resolve().then(() => (init_structured_query(), structured_query_exports));
-var result = runStructuredQuery2(parsed.args);
+var result;
+try {
+  result = runStructuredQuery2(parsed.args);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : "Invalid query.");
+  console.error(structuredQueryUsage());
+  process.exit(1);
+}
 if (parsed.json) {
   console.log(JSON.stringify(result, null, 2));
 } else {

package/dist/runtime/repair.mjs

@@ -897,6 +897,12 @@ var init_schema = __esm({
 });
 
 // src/db/client.ts
+var client_exports = {};
+__export(client_exports, {
+  db: () => db,
+  getDatabasePath: () => getDatabasePath,
+  sqlite: () => sqlite
+});
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -910,6 +916,9 @@ function databaseUrlPath(value) {
     return value.slice("file:".length);
   }
 }
+function getDatabasePath() {
+  return dbPath;
+}
 var defaultDbPath, dbPath, sqlite, db;
 var init_client = __esm({
   "src/db/client.ts"() {
@@ -2001,9 +2010,12 @@ function backfillAlias(alias, options2 = {}) {
     const stmt = prepareCached(
       "UPDATE interactions SET cost = ?, cost_estimated = 1 WHERE id = ?"
     );
-    for (const update of updates) {
-      stmt.run(update.cost, update.id);
-    }
+    const writeAll = sqlite.transaction((rows4) => {
+      for (const update of rows4) {
+        stmt.run(update.cost, update.id);
+      }
+    });
+    writeAll(updates);
   }
   return {
     alias,
@@ -2016,6 +2028,7 @@ function backfillAlias(alias, options2 = {}) {
 var init_backfill = __esm({
   "src/lib/model-aliases/backfill.ts"() {
     "use strict";
+    init_client();
     init_prepared();
     init_cost();
   }
@@ -2248,10 +2261,11 @@ if (args[0] === "auto-classify") {
   const workbench2 = buildUnknownCostRepairWorkbench3();
   const result = buildAutoClassifyResult2(workbench2, { minConfidence: options2.minConfidence });
   if (options2.apply) {
-    const [{ upsertAlias: upsertAlias2 }, { backfillAlias: backfillAlias2 }, { prepareCached: prepareCached2 }] = await Promise.all([
+    const [{ upsertAlias: upsertAlias2 }, { backfillAlias: backfillAlias2 }, { prepareCached: prepareCached2 }, { sqlite: sqlite2 }] = await Promise.all([
       Promise.resolve().then(() => (init_store(), store_exports)),
       Promise.resolve().then(() => (init_backfill(), backfill_exports)),
-      Promise.resolve().then(() => (init_prepared(), prepared_exports))
+      Promise.resolve().then(() => (init_prepared(), prepared_exports)),
+      Promise.resolve().then(() => (init_client(), client_exports))
     ]);
     const outcome = {
       dryRun: options2.dryRun,
@@ -2271,18 +2285,18 @@ if (args[0] === "auto-classify") {
       ).get(modelName, providerName, providerName);
       return row2 ?? null;
     };
-    for (const suggestion of result.suggestions) {
+    const processSuggestion = (suggestion) => {
       const c = suggestion.classification;
       if (c.rule === "none" || !c.suggestedModel) {
         outcome.skipped.push({ key: suggestion.key, reason: "No suggested model." });
-        continue;
+        return;
       }
       if (c.rule === "parser-source") {
         outcome.skipped.push({
           key: suggestion.key,
           reason: "parser-source suggestions have no (provider, observed-model) pair; fix the parser instead."
         });
-        continue;
+        return;
       }
       const resolved = resolvePricedModelId(
         c.suggestedProvider ?? suggestion.provider,
@@ -2293,7 +2307,7 @@ if (args[0] === "auto-classify") {
           key: suggestion.key,
           reason: `Could not resolve priced model "${c.suggestedModel}" under provider "${suggestion.provider}".`
         });
-        continue;
+        return;
       }
       if (!options2.dryRun) {
         upsertAlias2({
@@ -2325,6 +2339,14 @@ if (args[0] === "auto-classify") {
         affectedInteractions: backfill.affectedInteractions,
         addedCost: backfill.totalCost
       });
+    };
+    if (options2.dryRun) {
+      for (const suggestion of result.suggestions) processSuggestion(suggestion);
+    } else {
+      const applyBatch = sqlite2.transaction(() => {
+        for (const suggestion of result.suggestions) processSuggestion(suggestion);
+      });
+      applyBatch();
     }
     result.applied = outcome;
   }

package/dist/runtime/reset.mjs

@@ -1659,7 +1659,6 @@ function recalculateInteractionCosts() {
         currency: interaction.alias_currency ?? "USD"
       } : null;
       const resolvedPrice = aliasPrice ?? directPrice;
-      const resolvedViaAlias = aliasPrice != null;
       const cost = calculateInteractionCost(
         {
           inputTokens: interaction.input_tokens,
@@ -1671,6 +1670,7 @@ function recalculateInteractionCosts() {
         },
         resolvedPrice
       );
+      const resolvedViaAlias = aliasPrice != null && cost.amount != null;
       if (cost.status === "unknown") unknownCostInteractions += 1;
       const metadata = {
         ...existingMetadata,

package/dist/runtime/scan.mjs

@@ -4337,7 +4337,6 @@ function recalculateInteractionCosts() {
         currency: interaction.alias_currency ?? "USD"
       } : null;
       const resolvedPrice = aliasPrice ?? directPrice;
-      const resolvedViaAlias = aliasPrice != null;
       const cost = calculateInteractionCost(
         {
           inputTokens: interaction.input_tokens,
@@ -4349,6 +4348,7 @@ function recalculateInteractionCosts() {
         },
         resolvedPrice
       );
+      const resolvedViaAlias = aliasPrice != null && cost.amount != null;
       if (cost.status === "unknown") unknownCostInteractions += 1;
       const metadata = {
         ...existingMetadata,

package/next.config.mjs

@@ -16,17 +16,54 @@ const productionExperimentalConfig =
     ? { ...baseExperimental, serverMinification: false }
     : baseExperimental;
 
+// Defense-in-depth response headers for the local dashboard. The CSP keeps all
+// resource loads same-origin (no third-party script/connect surface), and the
+// frame protections block clickjacking of the unauthenticated UI. 'unsafe-inline'
+// is required because Next.js injects inline bootstrap/hydration scripts and
+// styles; everything else is locked to 'self'.
+const securityHeaders = [
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "Referrer-Policy", value: "no-referrer" },
+  { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=(), interest-cohort=()" },
+  {
+    key: "Content-Security-Policy",
+    value: [
+      "default-src 'self'",
+      "script-src 'self' 'unsafe-inline'",
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' data: blob:",
+      "font-src 'self' data:",
+      "connect-src 'self'",
+      "object-src 'none'",
+      "base-uri 'self'",
+      "form-action 'self'",
+      "frame-ancestors 'none'"
+    ].join("; ")
+  }
+];
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   allowedDevOrigins: ["localhost", "127.0.0.1"],
   devIndicators: false,
   experimental: productionExperimentalConfig,
+  // The published package ships source and runs `next build` on the end user's
+  // machine at first `tokentrace serve`. Production installs omit devDependencies
+  // such as @types/better-sqlite3, so Next's build-time type check cannot pass
+  // there. Type safety is enforced in development and CI via `npm run verify`
+  // (`tsc --noEmit`); this only disables the redundant check during the
+  // user-machine build. Do not remove without making the user-side build
+  // type-check-free another way.
   typescript: {
     ignoreBuildErrors: true
   },
   serverExternalPackages: ["better-sqlite3"],
   outputFileTracingRoot: projectRoot,
-  typedRoutes: false
+  typedRoutes: false,
+  async headers() {
+    return [{ source: "/:path*", headers: securityHeaders }];
+  }
 };
 
 // Bundle analyzer — install @next/bundle-analyzer as an optional devDep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrace",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "mcpName": "io.github.abhiyoheswaran1/tokentrace",
   "description": "Local-first dashboard for AI CLI token, cost, and session analytics.",
   "author": {

package/scripts/query.ts

@@ -17,7 +17,18 @@ if (parsed.help) {
 }
 
 const { runStructuredQuery } = await import("@/src/lib/structured-query");
-const result = runStructuredQuery(parsed.args);
+
+let result: ReturnType<typeof runStructuredQuery>;
+try {
+  // Range/argument validation (e.g. from >= to, preset + from/to together)
+  // lives in runStructuredQuery, so surface those the same clean way as parse
+  // errors instead of letting a raw stack trace escape.
+  result = runStructuredQuery(parsed.args);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : "Invalid query.");
+  console.error(structuredQueryUsage());
+  process.exit(1);
+}
 
 if (parsed.json) {
   console.log(JSON.stringify(result, null, 2));

package/scripts/repair.ts

@@ -49,10 +49,11 @@ if (args[0] === "auto-classify") {
   const result = buildAutoClassifyResult(workbench, { minConfidence: options.minConfidence });
 
   if (options.apply) {
-    const [{ upsertAlias }, { backfillAlias }, { prepareCached }] = await Promise.all([
+    const [{ upsertAlias }, { backfillAlias }, { prepareCached }, { sqlite }] = await Promise.all([
       import("@/src/lib/model-aliases/store"),
       import("@/src/lib/model-aliases/backfill"),
-      import("@/src/db/prepared")
+      import("@/src/db/prepared"),
+      import("@/src/db/client")
     ]);
 
     const outcome: NonNullable<typeof result.applied> = {
@@ -79,18 +80,18 @@ if (args[0] === "auto-classify") {
       return row ?? null;
     };
 
-    for (const suggestion of result.suggestions) {
+    const processSuggestion = (suggestion: (typeof result.suggestions)[number]) => {
       const c = suggestion.classification;
       if (c.rule === "none" || !c.suggestedModel) {
         outcome.skipped.push({ key: suggestion.key, reason: "No suggested model." });
-        continue;
+        return;
       }
       if (c.rule === "parser-source") {
         outcome.skipped.push({
           key: suggestion.key,
           reason: "parser-source suggestions have no (provider, observed-model) pair; fix the parser instead."
         });
-        continue;
+        return;
       }
       const resolved = resolvePricedModelId(
         c.suggestedProvider ?? suggestion.provider,
@@ -101,7 +102,7 @@ if (args[0] === "auto-classify") {
           key: suggestion.key,
           reason: `Could not resolve priced model "${c.suggestedModel}" under provider "${suggestion.provider}".`
         });
-        continue;
+        return;
       }
 
       if (!options.dryRun) {
@@ -136,6 +137,18 @@ if (args[0] === "auto-classify") {
         affectedInteractions: backfill.affectedInteractions,
         addedCost: backfill.totalCost
       });
+    };
+
+    if (options.dryRun) {
+      for (const suggestion of result.suggestions) processSuggestion(suggestion);
+    } else {
+      // Apply the whole batch atomically: every alias + cost backfill commits
+      // together, or none does, so a failure partway can't leave the local
+      // database half-applied with inaccurate reported counts.
+      const applyBatch = sqlite.transaction(() => {
+        for (const suggestion of result.suggestions) processSuggestion(suggestion);
+      });
+      applyBatch();
     }
 
     result.applied = outcome;

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/abhiyoheswaran1/tokentrace",
     "source": "github"
   },
-  "version": "0.18.0",
+  "version": "0.19.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "tokentrace",
-      "version": "0.18.0",
+      "version": "0.19.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/serve.d.ts

@@ -0,0 +1,32 @@
+export interface ServeOptions {
+  help: boolean;
+  hostname: string;
+  port: number | null;
+  openBrowser: boolean;
+}
+
+export interface ResolvedServePort {
+  port: number;
+  fixed: boolean;
+}
+
+export interface ServeContext {
+  appDataDir(): string;
+  nextBin(): string;
+  runtimeEnv(): NodeJS.ProcessEnv;
+}
+
+export function parsePort(value: unknown): number;
+export function parseServeOptions(args: string[], env?: NodeJS.ProcessEnv): ServeOptions;
+export function isLoopbackHostname(hostname: unknown): boolean;
+export function assertHostnameAllowed(
+  hostname: string,
+  env?: Record<string, string | undefined>
+): void;
+export function startupProgress(step: string, detail?: string): void;
+export function formatServeError(
+  error: unknown,
+  options?: { hostname?: string; port?: number | null }
+): string;
+export function resolveServePort(options: ServeOptions): Promise<ResolvedServePort>;
+export function serve(context: ServeContext, args?: string[]): Promise<void>;

package/src/cli/serve.js

@@ -16,6 +16,28 @@ export function parsePort(value) {
   return port;
 }
 
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
+
+export function isLoopbackHostname(hostname) {
+  return LOOPBACK_HOSTNAMES.has(String(hostname ?? "").trim().toLowerCase());
+}
+
+/**
+ * The dashboard ships no authentication, so binding it to anything other than
+ * loopback exposes local AI usage data and the file-preview endpoints to the
+ * network. Refuse non-loopback binds unless the operator explicitly opts in.
+ */
+export function assertHostnameAllowed(hostname, env = process.env) {
+  if (isLoopbackHostname(hostname)) return;
+  if (env.TOKENTRACE_ALLOW_REMOTE === "1") return;
+  throw new Error(
+    `Refusing to bind TokenTrace to non-loopback host "${hostname}". ` +
+      "The dashboard has no authentication, so this would expose your local AI usage data " +
+      "and file-preview endpoints to the network. " +
+      "Re-run with --hostname 127.0.0.1, or set TOKENTRACE_ALLOW_REMOTE=1 to override (not recommended)."
+  );
+}
+
 export function parseServeOptions(args, env = process.env) {
   const options = {
     help: false,
@@ -119,6 +141,7 @@ export async function serve(context, args = []) {
   let child = null;
 
   try {
+    assertHostnameAllowed(hostname);
     let resolvedPort = null;
     if (options.port != null) {
       resolvedPort = await resolveServePort(options);

package/src/lib/anomaly-detection.ts

@@ -42,6 +42,12 @@ const DEFAULT_THRESHOLDS: AnomalyThresholds = { notable: 3, high: 4.5, severe: 6
 // Makes MAD a consistent estimator of stddev under normality.
 const MAD_TO_STDDEV = 0.6745;
 
+// When the trailing window has zero spread (mad === 0) a true modified z-score
+// is undefined/infinite. We still flag a large jump as severe, but report a
+// finite sentinel z-score so the value round-trips through JSON (JSON.stringify
+// serializes Infinity as null, which would silently drop the signal).
+const FLAT_RUN_Z = 999;
+
 function median(values: number[]): number {
   if (values.length === 0) return 0;
   const sorted = values.slice().sort((a, b) => a - b);
@@ -81,7 +87,7 @@ function scoreValue(value: number, window: number[], thresholds: AnomalyThreshol
     }
     const flatRunLength = window.filter((entry) => entry === baseline).length;
     if (value > 2 * baseline && flatRunLength >= 3) {
-      return { severity: "severe", baseline, zScore: Number.POSITIVE_INFINITY };
+      return { severity: "severe", baseline, zScore: FLAT_RUN_Z };
     }
     return { severity: null, baseline, zScore: 0 };
   }

package/src/lib/cost-recalculation.ts

@@ -238,7 +238,6 @@ export function recalculateInteractionCosts(): CostRecalculationResult {
             }
           : null;
       const resolvedPrice = aliasPrice ?? directPrice;
-      const resolvedViaAlias = aliasPrice != null;
 
       const cost = calculateInteractionCost(
         {
@@ -252,6 +251,11 @@ export function recalculateInteractionCosts(): CostRecalculationResult {
         resolvedPrice
       );
 
+      // Only treat the row as alias-resolved if the alias actually produced a
+      // cost. An alias pointing at a model that itself lacks complete pricing
+      // must not be labelled as estimated/alias-sourced with a null amount.
+      const resolvedViaAlias = aliasPrice != null && cost.amount != null;
+
       if (cost.status === "unknown") unknownCostInteractions += 1;
       const metadata = {
         ...existingMetadata,

package/src/lib/model-aliases/backfill.ts

@@ -1,3 +1,4 @@
+import { sqlite } from "@/src/db/client";
 import { prepareCached } from "@/src/db/prepared";
 import { calculateInteractionCost, type PriceConfig } from "@/src/lib/cost";
 
@@ -115,9 +116,14 @@ export function backfillAlias(
     const stmt = prepareCached(
       "UPDATE interactions SET cost = ?, cost_estimated = 1 WHERE id = ?"
     );
-    for (const update of updates) {
-      stmt.run(update.cost, update.id);
-    }
+    // Atomic: either every matched interaction is backfilled or none are, so a
+    // mid-loop failure can't leave the cost column half-updated.
+    const writeAll = sqlite.transaction((rows: Array<{ id: string; cost: number }>) => {
+      for (const update of rows) {
+        stmt.run(update.cost, update.id);
+      }
+    });
+    writeAll(updates);
   }
 
   return {

package/src/lib/path-access.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { expandHome } from "@/src/ingestion/discovery";
+
+/**
+ * Containment for endpoints that read a caller-supplied file path (parser
+ * previews, import-profile previews).
+ *
+ * The dashboard's perimeter (see request-guard) already blocks remote and
+ * cross-site callers, so the only legitimate caller is the user's own browser.
+ * This module is defense-in-depth: even a same-origin request may only read
+ * files under directories that could plausibly hold AI usage logs — the user's
+ * home directory, the OS temp directory, and any explicitly configured import
+ * folders. That keeps the feature usable (CLI logs live under $HOME) while
+ * ensuring the dashboard can never be turned into a reader for `/etc/*`,
+ * `/root/*`, other users' home directories, or files reached via symlink
+ * escapes.
+ */
+
+export type PathAccessErrorCode = "invalid" | "not_found" | "forbidden";
+
+export class PathAccessError extends Error {
+  readonly code: PathAccessErrorCode;
+
+  constructor(code: PathAccessErrorCode, message: string) {
+    super(message);
+    this.name = "PathAccessError";
+    this.code = code;
+  }
+}
+
+/** HTTP status that best matches each failure mode. */
+export function pathAccessStatus(code: PathAccessErrorCode): number {
+  switch (code) {
+    case "invalid":
+      return 400;
+    case "not_found":
+      return 404;
+    case "forbidden":
+      return 403;
+  }
+}
+
+async function realpathOrNull(target: string): Promise<string | null> {
+  try {
+    return await fs.realpath(target);
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve and de-duplicate the directories the dashboard may read from. */
+export async function getAllowedReadRoots(extraRoots: string[] = []): Promise<string[]> {
+  const base = [os.homedir(), os.tmpdir(), ...extraRoots.map((root) => expandHome(root.trim()))];
+  const resolved = await Promise.all(
+    base.filter(Boolean).map((root) => realpathOrNull(path.resolve(root)))
+  );
+  return Array.from(new Set(resolved.filter((root): root is string => Boolean(root))));
+}
+
+function isWithinRoot(target: string, root: string): boolean {
+  if (target === root) return true;
+  const rel = path.relative(root, target);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Validate a caller-supplied path and return its fully resolved (symlink-free)
+ * form. Throws {@link PathAccessError} with a `code` that maps to an HTTP status
+ * via {@link pathAccessStatus}.
+ */
+export async function resolveReadablePath(
+  input: unknown,
+  options: { extraRoots?: string[] } = {}
+): Promise<string> {
+  const expanded = typeof input === "string" ? expandHome(input.trim()) : "";
+  if (!expanded) {
+    throw new PathAccessError("invalid", "A file path is required.");
+  }
+  if (!path.isAbsolute(expanded)) {
+    throw new PathAccessError("invalid", "File path must be absolute.");
+  }
+
+  const real = await realpathOrNull(expanded);
+  if (!real) {
+    throw new PathAccessError("not_found", `File not found: ${expanded}`);
+  }
+
+  const roots = await getAllowedReadRoots(options.extraRoots);
+  if (!roots.some((root) => isWithinRoot(real, root))) {
+    throw new PathAccessError(
+      "forbidden",
+      "Path is outside the allowed import directories (home, temp, and configured folders)."
+    );
+  }
+
+  return real;
+}

package/src/lib/request-guard.ts

@@ -0,0 +1,119 @@
+/**
+ * Perimeter guard for the local dashboard's HTTP surface.
+ *
+ * The dashboard is unauthenticated by design (local-first, single user), so it
+ * relies entirely on *who can reach it* and *who is allowed to drive it*:
+ *
+ *  - Host allowlist: rejects requests whose `Host` header is not a loopback
+ *    name. This defeats DNS-rebinding attacks, where a malicious page rebinds
+ *    its own domain to 127.0.0.1 to turn cross-origin reads into "same-origin"
+ *    ones. A rebound request still carries the attacker's `Host`.
+ *  - Cross-site write protection: rejects state-changing requests that a
+ *    browser reports as cross-site (or that carry a non-loopback `Origin`).
+ *    This defeats CSRF, where a malicious page silently POSTs to the dashboard.
+ *
+ * Non-browser clients (CLI, curl) send neither `Origin` nor `Sec-Fetch-*` and
+ * are allowed through — the threat model is a browser being weaponised by a
+ * third-party site, not the user's own tooling.
+ *
+ * This module is intentionally dependency-free so it can run in the Next.js
+ * middleware (edge) runtime and be unit-tested in isolation.
+ */
+
+export type RequestGuardInput = {
+  method: string;
+  host: string | null | undefined;
+  origin?: string | null;
+  secFetchSite?: string | null;
+};
+
+export type RequestGuardEnv = {
+  TOKENTRACE_ALLOW_REMOTE?: string;
+};
+
+export type RequestGuardResult =
+  | { ok: true }
+  | { ok: false; status: number; error: string };
+
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/** Extract the lowercased hostname from a `Host`/authority value, dropping any port. */
+function hostnameOf(value: string): string {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return "";
+  // Bracketed IPv6 literal, optionally with a port: [::1]:3030
+  if (trimmed.startsWith("[")) {
+    const end = trimmed.indexOf("]");
+    return end === -1 ? trimmed : trimmed.slice(0, end + 1);
+  }
+  // Bare IPv6 (multiple colons) has no port suffix we can strip safely.
+  if (trimmed.split(":").length > 2) return trimmed;
+  const colon = trimmed.indexOf(":");
+  const host = colon === -1 ? trimmed : trimmed.slice(0, colon);
+  // Treat the FQDN trailing-dot form ("localhost.") as the bare name. This only
+  // ever loosens matching toward the canonical name, never across it.
+  return host.endsWith(".") ? host.slice(0, -1) : host;
+}
+
+function isLoopbackAuthority(value: string | null | undefined): boolean {
+  if (!value) return false;
+  return LOOPBACK_HOSTNAMES.has(hostnameOf(value));
+}
+
+function originIsLoopback(origin: string | null | undefined): boolean {
+  if (!origin) return false;
+  try {
+    return LOOPBACK_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function evaluateRequestGuard(
+  input: RequestGuardInput,
+  env: RequestGuardEnv = {}
+): RequestGuardResult {
+  const allowRemote = env.TOKENTRACE_ALLOW_REMOTE === "1";
+
+  if (!allowRemote && !isLoopbackAuthority(input.host)) {
+    return {
+      ok: false,
+      status: 421,
+      error:
+        "Request Host is not a recognised local address. TokenTrace only serves loopback hosts unless TOKENTRACE_ALLOW_REMOTE=1."
+    };
+  }
+
+  const method = input.method.toUpperCase();
+  if (SAFE_METHODS.has(method)) {
+    return { ok: true };
+  }
+
+  if (allowRemote) {
+    return { ok: true };
+  }
+
+  const secFetchSite = input.secFetchSite?.toLowerCase();
+  if (secFetchSite) {
+    if (secFetchSite === "same-origin" || secFetchSite === "none") {
+      return { ok: true };
+    }
+    return {
+      ok: false,
+      status: 403,
+      error: "Cross-site request blocked. TokenTrace only accepts same-origin writes."
+    };
+  }
+
+  // No Sec-Fetch-Site (older browser or non-browser client): fall back to Origin.
+  if (input.origin && !originIsLoopback(input.origin)) {
+    return {
+      ok: false,
+      status: 403,
+      error: "Cross-origin request blocked. TokenTrace only accepts same-origin writes."
+    };
+  }
+
+  return { ok: true };
+}

package/src/lib/scheduled-scan.ts

@@ -10,7 +10,24 @@ function latestScanDate() {
   return row?.scanAt ? new Date(row.scanAt) : null;
 }
 
-export async function runDueScheduledScan(now = new Date()) {
+type ScheduledScanOutcome = Awaited<ReturnType<typeof runScheduledScan>>;
+
+// The dashboard fires runDueScheduledScan() on every overview page load. Two
+// overlapping loads (a second tab, a quick refresh, prefetch) would otherwise
+// both pass the due-check and both call runScan(), producing duplicate scan
+// runs and wasted work. The Next.js server is a single process, so a
+// module-scoped promise guard coalesces concurrent callers into one scan.
+let inFlightScheduledScan: Promise<ScheduledScanOutcome> | null = null;
+
+export function runDueScheduledScan(now = new Date()): Promise<ScheduledScanOutcome> {
+  if (inFlightScheduledScan) return inFlightScheduledScan;
+  inFlightScheduledScan = runScheduledScan(now).finally(() => {
+    inFlightScheduledScan = null;
+  });
+  return inFlightScheduledScan;
+}
+
+async function runScheduledScan(now: Date) {
   const settings = getAppSettings();
   if (!isScanDue(settings.scanSchedule, latestScanDate(), now)) {
     return {

package/src/lib/structured-query-cli.ts

@@ -47,7 +47,11 @@ const PRESET: readonly StructuredQueryRangePreset[] = ["today", "7d", "30d", "60
 
 function valueOf(arg: string, next: string | undefined): { value: string; consumedNext: boolean } {
   const eq = arg.indexOf("=");
-  if (eq >= 0) return { value: arg.slice(eq + 1), consumedNext: false };
+  if (eq >= 0) {
+    const value = arg.slice(eq + 1);
+    if (!value) throw new Error(`Missing value for ${arg.slice(0, eq)}`);
+    return { value, consumedNext: false };
+  }
   if (next == null || next.startsWith("-")) {
     throw new Error(`Missing value for ${arg}`);
   }

package/tsconfig.json

@@ -38,7 +38,6 @@
     ".next/dev/types/**/*.ts"
   ],
   "exclude": [
-    "node_modules",
-    "tailwind.config.ts"
+    "node_modules"
   ]
 }