ashlr-plugin 1.36.4

package/servers/_prefetch.ts

@@ -0,0 +1,435 @@
+/**
+ * _prefetch — Predictive prefetch MVP (Q3 supporting pillar).
+ *
+ * When ashlr__read succeeds on file X, we schedule a fire-and-forget
+ * background task that:
+ *   1. Scans X's import statements via lightweight regex (NOT AST) to
+ *      identify neighbour files.
+ *   2. Picks the top-N most-imported neighbours (deduped, frequency-ranked).
+ *   3. Reads each, runs snipCompact, and stores the result in the existing
+ *      _read-cache so the next ashlr__read on any of them is instant.
+ *
+ * Tier gates (enforced at top of schedulePrefetch):
+ *   - free  → return immediately, no work.
+ *   - pro   → maxNeighbors clamped to 3.
+ *   - team  → maxNeighbors clamped to 10.
+ *
+ * Kill switch:
+ *   - ASHLR_PREFETCH=off → return immediately regardless of tier.
+ *
+ * Constraints:
+ *   - NEVER blocks the calling read path. Fire-and-forget via setImmediate.
+ *   - Hard 1.5s wallclock cap; remaining neighbours skipped after the cap.
+ *   - cwd-clamped: never reads outside the project root.
+ *   - Idempotent: re-prefetching a path that's already cached is a no-op.
+ *   - No external deps. Pure stdlib + bun built-ins.
+ */
+
+import { readFile, stat } from "fs/promises";
+import { existsSync, statSync } from "fs";
+import { dirname, isAbsolute, resolve, sep } from "path";
+import {
+  type Message,
+  snipCompact,
+} from "@ashlr/core-efficiency";
+import { getCached, setCached } from "./_read-cache";
+import { clampToCwd } from "./_cwd-clamp";
+import { logEvent } from "./_events";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Hard wallclock cap for the entire background prefetch task. */
+const HARD_BUDGET_MS = 1500;
+
+/** Extensions tried when resolving a relative import without explicit extension. */
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".h", ".hpp"];
+
+/** Directories never followed for import resolution. */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next"]);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type PrefetchTier = "free" | "pro" | "team";
+
+export interface PrefetchOptions {
+  tier: PrefetchTier;
+  /** Caller hint; will be clamped per tier. */
+  maxNeighbors: number;
+  /** Project cwd — used as the resolution + clamp root. */
+  cwd: string;
+}
+
+interface InflightTracker {
+  /** Paths currently being prefetched (so duplicate schedules become no-ops). */
+  inflight: Set<string>;
+}
+
+const tracker: InflightTracker = { inflight: new Set() };
+
+// ---------------------------------------------------------------------------
+// Tier gating
+// ---------------------------------------------------------------------------
+
+/** Resolve the per-tier neighbor cap. Free → 0 (disabled). */
+export function tierCap(tier: PrefetchTier): number {
+  if (tier === "free") return 0;
+  if (tier === "pro") return 3;
+  if (tier === "team") return 10;
+  return 0;
+}
+
+/** ASHLR_PREFETCH kill switch — "off" disables all prefetch work. */
+export function isPrefetchDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env["ASHLR_PREFETCH"];
+  if (raw == null) return false;
+  const v = String(raw).trim().toLowerCase();
+  return v === "off" || v === "0" || v === "false" || v === "no";
+}
+
+// ---------------------------------------------------------------------------
+// Import extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Lightweight regex import extraction. Covers:
+ *   - TS/JS  ES imports: `import X from 'Y'`, `import { X } from 'Y'`
+ *   - TS/JS  `from 'Y'` bare matches (catches re-exports)
+ *   - CommonJS `require('Y')`
+ *   - Python `from X import` and `import X`
+ *   - C/C++ `#include "X"` / `#include <X>`
+ *
+ * Returns frequency-ranked unique specifiers. Multiple matches of the same
+ * specifier are counted once per occurrence (so a file imported twice ranks
+ * higher than a file imported once) but the returned list is deduped.
+ */
+export function extractImports(source: string): string[] {
+  const patterns: RegExp[] = [
+    /import\s+[^'"`;]*?\s+from\s+['"]([^'"]+)['"]/g,
+    /from\s+['"]([^'"]+)['"]/g,
+    /require\(\s*['"]([^'"]+)['"]\s*\)/g,
+    // Python: `from X import …` / `import X[.Y]`
+    /^\s*from\s+([A-Za-z_][\w.]*)\s+import\b/gm,
+    /^\s*import\s+([A-Za-z_][\w.]*)/gm,
+    // C/C++ includes
+    /#include\s+["<]([^">]+)[">]/g,
+  ];
+
+  const counts = new Map<string, number>();
+  for (const re of patterns) {
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(source)) !== null) {
+      const spec = m[1];
+      if (!spec) continue;
+      counts.set(spec, (counts.get(spec) ?? 0) + 1);
+    }
+  }
+
+  // Highest count first; stable secondary by first-seen order.
+  return Array.from(counts.entries())
+    .sort((a, b) => b[1] - a[1])
+    .map(([spec]) => spec);
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve an import specifier to an absolute file path inside `cwd`, or null.
+ *
+ * Strategy (best-effort, no full resolver):
+ *   - Skip bare specifiers (no leading "./" / "../" / "/") — those are
+ *     usually node_modules or stdlib, which we don't want to prefetch.
+ *   - Resolve relative paths against `fromFile`'s directory.
+ *   - Try the path as-is; then with each RESOLVE_EXTENSIONS suffix; then
+ *     as `path/index.<ext>`.
+ *   - Refuse anything under SKIP_DIRS.
+ *   - Final cwd-clamp guards against `../../../etc/passwd` escapes.
+ */
+export function resolveImport(
+  spec: string,
+  fromFile: string,
+  cwd: string,
+): string | null {
+  // Bare specifier (npm pkg / stdlib) — skip; we only prefetch first-party files.
+  if (!spec.startsWith(".") && !spec.startsWith("/")) {
+    // Python dotted module — try as a relative-from-cwd path lookup.
+    if (/^[A-Za-z_][\w.]*$/.test(spec)) {
+      const candidatePy = resolve(cwd, spec.replace(/\./g, sep) + ".py");
+      if (existsSync(candidatePy)) return candidatePy;
+    }
+    return null;
+  }
+
+  const base = isAbsolute(spec) ? spec : resolve(dirname(fromFile), spec);
+
+  const candidates: string[] = [base];
+  for (const ext of RESOLVE_EXTENSIONS) {
+    candidates.push(base + ext);
+  }
+  for (const ext of RESOLVE_EXTENSIONS) {
+    candidates.push(resolve(base, "index" + ext));
+  }
+
+  for (const c of candidates) {
+    if (containsSkipDir(c)) continue;
+    try {
+      const st = statSync(c);
+      if (st.isFile()) {
+        // Clamp to project cwd as the security boundary.
+        const clamp = clampToCwd(c, "ashlr__prefetch");
+        if (!clamp.ok) return null;
+        return clamp.abs;
+      }
+    } catch {
+      // not this candidate; continue
+    }
+  }
+  return null;
+}
+
+function containsSkipDir(p: string): boolean {
+  const parts = p.split(sep);
+  for (const part of parts) {
+    if (SKIP_DIRS.has(part)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Test hook: optional override for readFile so tests can simulate slow I/O.
+ * Production code never sets this.
+ */
+let _readImpl: (p: string) => Promise<string> = (p) => readFile(p, "utf-8");
+export function _setReadImplForTest(fn: ((p: string) => Promise<string>) | null): void {
+  _readImpl = fn ?? ((p) => readFile(p, "utf-8"));
+}
+
+/**
+ * Test hook: drains the inflight set. Tests should call this in afterEach to
+ * isolate idempotency assertions.
+ */
+export function _resetInflightForTest(): void {
+  tracker.inflight.clear();
+}
+
+/**
+ * Schedule a fire-and-forget prefetch starting from `path`.
+ *
+ * IMPORTANT: This function MUST NOT be awaited by the calling read path.
+ * It returns immediately; all real work is deferred via setImmediate.
+ *
+ * Returns a Promise<PrefetchResult> for test instrumentation only; production
+ * callers should ignore the return value.
+ */
+export interface PrefetchResult {
+  scheduled: number;
+  completed: number;
+  durationMs: number;
+  skipped: "kill-switch" | "free-tier" | "idempotent" | "stat-failed" | null;
+}
+
+export function schedulePrefetch(
+  path: string,
+  opts: PrefetchOptions,
+): Promise<PrefetchResult> {
+  // Kill switch — highest priority, before any work.
+  if (isPrefetchDisabled()) {
+    return Promise.resolve({ scheduled: 0, completed: 0, durationMs: 0, skipped: "kill-switch" });
+  }
+
+  // Tier gate — free tier does nothing.
+  const cap = Math.min(opts.maxNeighbors, tierCap(opts.tier));
+  if (cap <= 0) {
+    return Promise.resolve({ scheduled: 0, completed: 0, durationMs: 0, skipped: "free-tier" });
+  }
+
+  // Idempotency: already scheduled for this path → no-op.
+  if (tracker.inflight.has(path)) {
+    return Promise.resolve({ scheduled: 0, completed: 0, durationMs: 0, skipped: "idempotent" });
+  }
+  tracker.inflight.add(path);
+
+  // Defer all real work to the next tick so the caller's read response goes
+  // out first. The returned promise resolves when the background task finishes
+  // (or when the 1.5s budget elapses).
+  return new Promise<PrefetchResult>((resolvePromise) => {
+    setImmediate(() => {
+      const started = Date.now();
+      runPrefetch(path, cap, opts, started)
+        .then((res) => {
+          tracker.inflight.delete(path);
+          resolvePromise(res);
+        })
+        .catch(() => {
+          // Never propagate — prefetch is best-effort.
+          tracker.inflight.delete(path);
+          resolvePromise({
+            scheduled: 0,
+            completed: 0,
+            durationMs: Date.now() - started,
+            skipped: null,
+          });
+        });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+async function runPrefetch(
+  path: string,
+  cap: number,
+  opts: PrefetchOptions,
+  started: number,
+): Promise<PrefetchResult> {
+  const remainingMs = () => HARD_BUDGET_MS - (Date.now() - started);
+
+  // Read the source file (sync stat first to skip non-files cheaply).
+  let stMtime = 0;
+  try {
+    const st = await stat(path);
+    if (!st.isFile()) {
+      return { scheduled: 0, completed: 0, durationMs: Date.now() - started, skipped: "stat-failed" };
+    }
+    stMtime = st.mtimeMs;
+  } catch {
+    return { scheduled: 0, completed: 0, durationMs: Date.now() - started, skipped: "stat-failed" };
+  }
+  void stMtime;
+
+  if (remainingMs() <= 0) {
+    return { scheduled: 0, completed: 0, durationMs: Date.now() - started, skipped: null };
+  }
+
+  let source: string;
+  try {
+    source = await _readImpl(path);
+  } catch {
+    return { scheduled: 0, completed: 0, durationMs: Date.now() - started, skipped: null };
+  }
+
+  // Extract & resolve neighbours.
+  const specs = extractImports(source);
+  const neighbours: string[] = [];
+  for (const spec of specs) {
+    if (neighbours.length >= cap) break;
+    const abs = resolveImport(spec, path, opts.cwd);
+    if (!abs) continue;
+    if (abs === path) continue; // self-import
+    if (neighbours.includes(abs)) continue;
+    neighbours.push(abs);
+  }
+
+  // Fire telemetry: scheduled count up front so we observe it even if the
+  // budget cuts work short.
+  void logEvent("tool_call", {
+    tool: "ashlr__prefetch",
+    reason: "prefetch_scheduled",
+    extra: {
+      neighbors_scheduled: neighbours.length,
+      tier: opts.tier,
+      cap,
+    },
+  });
+
+  let completed = 0;
+  for (const neighbour of neighbours) {
+    if (remainingMs() <= 0) break;
+
+    // Already cached + fresh? Skip — idempotent at the neighbour level.
+    try {
+      const st = statSync(neighbour);
+      const hit = getCached(neighbour);
+      if (hit && hit.mtimeMs === st.mtimeMs) {
+        continue;
+      }
+
+      // Race the read against the remaining budget.
+      const content = await raceWithBudget(_readImpl(neighbour), remainingMs());
+      if (content == null) break;
+
+      // Apply snipCompact via the same Message wrapper read-server uses.
+      const msgs: Message[] = [
+        {
+          role: "user",
+          content: [
+            { type: "tool_result", tool_use_id: "ashlr-prefetch", content },
+          ],
+        },
+      ];
+      const compact = snipCompact(msgs);
+      const block = (compact[0]!.content as { type: string; content: string }[])[0]!;
+      const compactText = (block as { content: string }).content;
+
+      setCached(neighbour, {
+        mtimeMs: st.mtimeMs,
+        result: `(prefetched)\n${compactText}`,
+        sourceBytes: content.length,
+      });
+      completed++;
+    } catch {
+      // Skip this neighbour silently — best-effort.
+      continue;
+    }
+  }
+
+  const durationMs = Date.now() - started;
+  void logEvent("tool_call", {
+    tool: "ashlr__prefetch",
+    reason: "prefetch_hit",
+    extra: {
+      neighbors_scheduled: neighbours.length,
+      neighbors_completed: completed,
+      duration_ms: durationMs,
+      tier: opts.tier,
+      budget_exhausted: remainingMs() <= 0,
+    },
+  });
+
+  return { scheduled: neighbours.length, completed, durationMs, skipped: null };
+}
+
+/**
+ * Race a promise against the remaining wallclock budget. Returns null on
+ * timeout. Used to enforce the 1.5s hard cap when a single neighbour read
+ * stalls (e.g., slow disk, network FS).
+ */
+function raceWithBudget<T>(p: Promise<T>, budgetMs: number): Promise<T | null> {
+  if (budgetMs <= 0) return Promise.resolve(null);
+  return new Promise<T | null>((resolveRace) => {
+    let settled = false;
+    const t = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolveRace(null);
+      }
+    }, budgetMs);
+    p.then(
+      (v) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(t);
+          resolveRace(v);
+        }
+      },
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(t);
+          resolveRace(null);
+        }
+      },
+    );
+  });
+}

package/servers/_pricing.ts

@@ -0,0 +1,256 @@
+/**
+ * _pricing.ts — single source of truth for $/MTok pricing across the plugin.
+ *
+ * Prior state: `servers/efficiency-server.ts` used $3/MTok (sonnet-4.5 input
+ * only); `scripts/savings-dashboard.ts` used a hardcoded $5/MTok "blended"
+ * rate; `scripts/session-greet.ts` had its own copy; `scripts/generate-badge.ts`
+ * duplicated yet another PRICING map. Same token count produced three
+ * different dollar values depending on which surface rendered it.
+ *
+ * This module centralizes the table. Both the efficiency-server renderer
+ * and the dashboard import `pricing()` / `costFor()` here so a token count
+ * maps to exactly one USD value regardless of surface.
+ *
+ * Model selection: read `ASHLR_PRICING_MODEL` env var. Default is
+ * `sonnet-4.5` (Claude Code's default model). Unknown models fall back to
+ * the default rather than throw — pricing must never break rendering.
+ *
+ * Numbers reflect input-token pricing per million tokens, as of 2026-04.
+ * Savings reporting uses the input rate (we're measuring tokens *not sent*
+ * into the model's context window, so the input price is the right
+ * counterfactual).
+ */
+export interface ModelPrice {
+  /** USD per 1M input tokens. */
+  inUsd: number;
+  /** USD per 1M output tokens. */
+  outUsd: number;
+}
+
+/**
+ * Canonical pricing table. Keys are stable short names; aliases map to the
+ * same entry so callers can pass either `sonnet-4.5` or `claude-sonnet-4.5`.
+ */
+export const PRICING_TABLE: Record<string, ModelPrice> = {
+  "sonnet-4.5":  { inUsd: 3.0,  outUsd: 15.0 },
+  "sonnet-4.6":  { inUsd: 2.5,  outUsd: 12.5 },
+  "opus-4":      { inUsd: 15.0, outUsd: 75.0 },
+  "opus-4.7":    { inUsd: 18.0, outUsd: 90.0 },
+  "haiku-4.5":   { inUsd: 0.8,  outUsd: 4.0  },
+  // Local / offline providers — zero inference cost.
+  "onnx":        { inUsd: 0,    outUsd: 0     },
+  "local":       { inUsd: 0,    outUsd: 0     },
+  "none":        { inUsd: 0,    outUsd: 0     },
+};
+
+/**
+ * Default model for pricing when no override is specified. Updated to
+ * sonnet-4.6 (the current Claude Code default as of 2026-04); sonnet-4.5
+ * is retained in the table for back-compat with pinned configs.
+ */
+export const DEFAULT_PRICING_MODEL = "sonnet-4.6";
+
+/**
+ * Resolve the effective model name from the caller-supplied override,
+ * `ASHLR_PRICING_MODEL`, or `CLAUDE_CODE_MODEL` (the env var Claude Code
+ * exports to describe its active model). Returns the resolved name verbatim
+ * so test harnesses can pin it; does NOT validate that the model exists in
+ * the table — that check happens in `pricing()`.
+ */
+
+/** Track whether we've already warned about an unknown model this process. */
+let _unknownModelWarned: string | null = null;
+
+export function pricingModel(override?: string): string {
+  if (override && override.trim().length > 0) return override.trim();
+  const explicit = process.env.ASHLR_PRICING_MODEL;
+  if (explicit && explicit.trim().length > 0) return explicit.trim();
+  // Auto-detect from Claude Code's model env var. Strip the "claude-" prefix
+  // if present so "claude-sonnet-4.6" resolves to "sonnet-4.6".
+  const ccModel = process.env.CLAUDE_CODE_MODEL;
+  if (ccModel && ccModel.trim().length > 0) {
+    const raw = ccModel.trim();
+    const normalized = raw.replace(/^claude-/, "");
+    return normalized;
+  }
+  return DEFAULT_PRICING_MODEL;
+}
+
+/**
+ * Return the price entry for a given model (or the resolved default).
+ * Unknown models log a one-time warning to stderr and fall back to the
+ * default — pricing lookups must never break a rendering path.
+ */
+export function pricing(model?: string): ModelPrice {
+  const name = pricingModel(model);
+  if (PRICING_TABLE[name]) return PRICING_TABLE[name]!;
+  // Unknown model: warn once per process, then use default.
+  if (_unknownModelWarned !== name) {
+    _unknownModelWarned = name;
+    process.stderr.write(`ashlr: unknown model "${name}", defaulting to ${DEFAULT_PRICING_MODEL} pricing\n`);
+  }
+  return PRICING_TABLE[DEFAULT_PRICING_MODEL]!;
+}
+
+/**
+ * Compute the USD cost for a given input-token count at the model's input
+ * rate. Always uses input pricing because savings reporting measures tokens
+ * that would have been *sent into* the model (see module docstring).
+ *
+ * Negative / non-finite inputs clamp to 0 so downstream formatters never
+ * see NaN.
+ */
+export function costFor(tokens: number, model?: string): number {
+  if (!Number.isFinite(tokens) || tokens <= 0) return 0;
+  const p = pricing(model);
+  return (tokens * p.inUsd) / 1_000_000;
+}
+
+/**
+ * Compute the USD cost of an LLM summarization call.
+ *
+ * Pricing per provider:
+ *   anthropic — Haiku 4.5: $0.80/MTok in, $4.00/MTok out (user's own key)
+ *   cloud     — ashlr hosted proxy: same Haiku 4.5 rates (Pro subscription covers it)
+ *   onnx      — local inference: $0 (compute already paid)
+ *   local     — LM Studio / Ollama: $0 (local inference)
+ *   none      — no call made: $0
+ *
+ * Returns exact USD cost (may be fractional; callers format as needed).
+ * Always finite; clamps bad inputs to 0.
+ */
+export function costForLLM(
+  provider: "anthropic" | "cloud" | "onnx" | "local" | "none",
+  inTokens: number,
+  outTokens: number,
+): number {
+  if (provider !== "anthropic" && provider !== "cloud") return 0;
+  const safeIn = Number.isFinite(inTokens) && inTokens > 0 ? inTokens : 0;
+  const safeOut = Number.isFinite(outTokens) && outTokens > 0 ? outTokens : 0;
+  // Haiku 4.5: $0.80/MTok in, $4.00/MTok out
+  return (safeIn * 0.8 + safeOut * 4.0) / 1_000_000;
+}
+
+// ---------------------------------------------------------------------------
+// Summarizer-model detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Map from LLM provider name to the actual model used for summarization.
+ * Used by getActiveSummarizerModel() to return a key resolvable in PRICING_TABLE.
+ */
+const PROVIDER_MODEL_MAP: Record<string, string> = {
+  off:       "none",       // ASHLR_LLM_PROVIDER=off
+  anthropic: "haiku-4.5",  // anthropic.ts hardcodes claude-haiku-4-5-20251001
+  cloud:     "haiku-4.5",  // hosted proxy also uses Haiku
+  onnx:      "onnx",       // local ONNX inference — $0
+  local:     "local",      // LM Studio / Ollama — $0
+  none:      "none",       // no summarization — $0
+};
+
+/**
+ * Detect which summarizer model is actually active based on the
+ * ASHLR_LLM_PROVIDER env var and ASHLR_LLM_URL heuristic.
+ *
+ * Returns a short model key resolvable in PRICING_TABLE (e.g. "haiku-4.5",
+ * "onnx", "local"). Does NOT do a network availability check — purely env-based
+ * so it stays synchronous and safe to call on hot paths.
+ *
+ * Order matches the selectProvider() logic in _llm-providers/index.ts:
+ *   1. ASHLR_LLM_PROVIDER explicit override
+ *   2. ASHLR_LLM_URL set → local
+ *   3. ANTHROPIC_API_KEY or ~/.claude/.credentials.json present → anthropic
+ *   4. Pro token present → cloud
+ *   5. default → none (snipCompact fallback)
+ */
+export function getActiveSummarizerModel(homeOverride?: string): string {
+  const pricingOverride = process.env["ASHLR_PRICING_MODEL"];
+  // If the user explicitly set ASHLR_PRICING_MODEL, honor it as-is (power-user
+  // override path — they want to peg to a specific price regardless of actual
+  // summarizer).
+  if (pricingOverride && pricingOverride.trim().length > 0) {
+    return pricingOverride.trim();
+  }
+
+  const llmProvider = (process.env["ASHLR_LLM_PROVIDER"] ?? "auto").toLowerCase().trim();
+  const mapped = PROVIDER_MODEL_MAP[llmProvider];
+  if (mapped) return mapped;
+
+  // "auto" — mirror selectProvider heuristic without awaiting.
+  if (process.env["ASHLR_LLM_URL"]) return "local";
+
+  // Anthropic key present (either env var or Claude Code credentials file)?
+  if (process.env["ANTHROPIC_API_KEY"]) return "haiku-4.5";
+
+  // Pro token present → cloud proxy (also Haiku).
+  try {
+    const { existsSync, statSync } = require("fs") as typeof import("fs");
+    const { homedir } = require("os") as typeof import("os");
+    const { join } = require("path") as typeof import("path");
+    const home = homeOverride ?? process.env["HOME"] ?? homedir();
+    const tokenPath = join(home, ".ashlr", "pro-token");
+    if (existsSync(tokenPath) && statSync(tokenPath).size > 0) {
+      return "haiku-4.5";
+    }
+  } catch {
+    /* best-effort — fall through to none */
+  }
+
+  return "none";
+}
+
+/**
+ * Return the input price (USD per million tokens) for the active summarizer
+ * model. Suitable for correcting the `$ saved` display to reflect actual
+ * inference costs rather than defaulting to Sonnet rates.
+ *
+ * Falls back to `pricing(override)` when a manual ASHLR_PRICING_MODEL override
+ * is set — preserving backward compat for power users who want Sonnet
+ * counterfactual pricing.
+ */
+export function getInputPriceForModel(model: string): number {
+  const entry = PRICING_TABLE[model];
+  if (entry) return entry.inUsd;
+  // Unknown model: fall back to default pricing table entry.
+  return PRICING_TABLE[DEFAULT_PRICING_MODEL]!.inUsd;
+}
+
+/**
+ * costFor() using the detected summarizer model rather than the main LLM model.
+ *
+ * Use this for `$ saved` displays where the counterfactual is "what would it
+ * have cost to send these tokens through the summarizer model" — not through
+ * the user's primary model (Sonnet/Opus). The summarizer is typically Haiku,
+ * which is ~3-4x cheaper than Sonnet.
+ *
+ * Design intent — DO NOT "fix" the main-model fallback back to $0:
+ *   This function exists specifically to avoid overclaiming against Sonnet
+ *   rates when Haiku is the real summarizer (v1.x change). But when the
+ *   auto-resolver lands on a zero-priced model ("none", "onnx", "local"),
+ *   there IS no summarizer — the user is on the free-tier first-touch path
+ *   (no Anthropic key, no Pro token, no local LLM URL). In that case the
+ *   tokens we saved would have hit the MAIN model, so main-model pricing
+ *   is the correct counterfactual. Showing $0 to those users is the bug
+ *   (status-line "≈$0.00"); falling back to costFor() shows real savings.
+ *
+ * Power-user override: when `ASHLR_PRICING_MODEL` is explicitly set we honor
+ * it verbatim — even if it resolves to a $0-priced model. They asked to peg
+ * to that price and we respect it.
+ */
+export function costForSummarizer(tokens: number, homeOverride?: string): number {
+  if (!Number.isFinite(tokens) || tokens <= 0) return 0;
+  const model = getActiveSummarizerModel(homeOverride);
+  const pricePerM = getInputPriceForModel(model);
+  // If the resolved model carries a $0 price AND the user did NOT explicitly
+  // pin via ASHLR_PRICING_MODEL, fall back to main-model pricing. This is the
+  // free-tier first-touch case where no summarizer is configured — the
+  // counterfactual is the main model, not "free".
+  const explicitPricingOverride = process.env["ASHLR_PRICING_MODEL"];
+  const hasExplicitOverride =
+    explicitPricingOverride !== undefined &&
+    explicitPricingOverride.trim().length > 0;
+  if (pricePerM === 0 && !hasExplicitOverride) {
+    return costFor(tokens);
+  }
+  return (tokens * pricePerM) / 1_000_000;
+}