tokenclinic 0.1.1

package/src/audit/audit.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import type { AuditResult, Bucket, CallRecord } from "../types";
+import { cost, isPriced } from "../pricing/table";
+import { classify } from "./classify";
+
+// Approach A — the retroactive audit. Ingest a JSONL of past LLM calls and print
+// the EOB backwards: total spend, the eliminable-class fraction (the bet), and the
+// projected savings had the clinic loop been in place. No code is read, nothing is
+// fixed — it runs entirely on exported logs, so it carries zero autofix or
+// code-exfiltration risk. This is the move that measures the core thesis (Premise 2).
+
+// Where routable work would have run instead — the cheapest tier (Premise 5: bucket 2
+// is re-priced, not eliminated).
+const ROUTABLE_TARGET = "claude-haiku-4-5";
+
+export function parseLog(path: string): CallRecord[] {
+  const raw = readFileSync(path, "utf8");
+  const records: CallRecord[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const r = JSON.parse(trimmed) as CallRecord;
+      if (typeof r.model === "string" && typeof r.inputTokens === "number") records.push(r);
+    } catch {
+      // skip malformed lines — partial logs shouldn't abort the audit
+    }
+  }
+  return records;
+}
+
+export function audit(calls: CallRecord[]): AuditResult {
+  const byBucket: AuditResult["byBucket"] = {
+    eliminable: { count: 0, spend: 0 },
+    routable: { count: 0, spend: 0 },
+    essential: { count: 0, spend: 0 },
+  };
+
+  let spend = 0;
+  let projectedSpend = 0;
+  let estimated = false;
+  let unpriced = 0;
+
+  for (const call of calls) {
+    if (!isPriced(call.model)) unpriced++;
+    const actual = cost(call.model, call.inputTokens, call.outputTokens);
+    const { bucket, estimated: wasGuessed } = classify(call);
+    estimated ||= wasGuessed;
+
+    spend += actual;
+    byBucket[bucket].count++;
+    byBucket[bucket].spend += actual;
+
+    projectedSpend += projectedCost(bucket, call);
+  }
+
+  const eliminableFraction = spend > 0 ? byBucket.eliminable.spend / spend : 0;
+
+  return {
+    calls: calls.length,
+    spend,
+    byBucket,
+    eliminableFraction,
+    projectedSpend,
+    projectedSaved: spend - projectedSpend,
+    estimated,
+    unpriced,
+  };
+}
+
+// What each call would have cost under the clinic loop.
+function projectedCost(bucket: Bucket, call: CallRecord): number {
+  if (bucket === "eliminable") return 0; // killed on-device
+  if (bucket === "routable") return cost(ROUTABLE_TARGET, call.inputTokens, call.outputTokens);
+  return cost(call.model, call.inputTokens, call.outputTokens); // essential — unchanged
+}

package/src/audit/classify.ts

@@ -0,0 +1,56 @@
+import type { Bucket, CallRecord } from "../types";
+
+// Bucket a past call into the two-bucket economics (Premise 5).
+//
+// Authoritative path: if the log carries a `category` (instrumented or concierge
+// tagging), trust it. Heuristic path: otherwise infer from the task text and flag
+// the whole audit as estimated. The heuristic rules are intentionally explicit and
+// printed in the report — the audit's credibility depends on the bucketing being
+// inspectable, not magic.
+
+const CATEGORY_BUCKET: Record<string, Bucket> = {
+  import: "eliminable",
+  lint: "eliminable",
+  type: "eliminable",
+  format: "eliminable",
+  syntax: "eliminable",
+  refactor: "routable",
+  boilerplate: "routable",
+  docs: "routable",
+  test: "routable",
+  architecture: "essential",
+  design: "essential",
+  reasoning: "essential",
+  debug: "essential",
+};
+
+const ELIMINABLE_PATTERNS = [
+  /\bimport\b/i,
+  /\blint\b/i,
+  /eslint|prettier|format/i,
+  /unused/i,
+  /semicolon|\bsyntax\b/i,
+  /\bmissing\b/i,
+  /\btypo\b/i,
+  /type error|type mismatch|not assignable/i,
+];
+
+const ROUTABLE_PATTERNS = [
+  /boilerplate/i,
+  /docstring|\bcomment\b/i,
+  /test stub|scaffold/i,
+  /\brename\b/i,
+  /simple refactor/i,
+];
+
+export function classify(call: CallRecord): { bucket: Bucket; estimated: boolean } {
+  if (call.category) {
+    const mapped = CATEGORY_BUCKET[call.category.toLowerCase()];
+    if (mapped) return { bucket: mapped, estimated: false };
+  }
+
+  const task = call.task ?? "";
+  if (ELIMINABLE_PATTERNS.some((re) => re.test(task))) return { bucket: "eliminable", estimated: true };
+  if (ROUTABLE_PATTERNS.some((re) => re.test(task))) return { bucket: "routable", estimated: true };
+  return { bucket: "essential", estimated: true };
+}

package/src/bill/eob.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding, EOB } from "../types";
+import { cost, estimateTokens } from "../pricing/table";
+
+// Bill: turn resolved Findings into an Explanation Of Benefits.
+//
+// The savings number is a counterfactual: for each finding, the *naive* approach
+// dumps the whole containing file at a top model to find-and-fix it. The clinic
+// loop instead fixes autofixable findings for $0 and escalates the rest with a
+// tight packet to a routed (often cheaper) model. saved = naive - clinic.
+//
+// Honest caveat: in v1 the per-escalation cost is an estimate (DryRunFixer), so
+// the EOB is flagged estimated. The token counts underlying it are real.
+const NAIVE_MODEL = "claude-opus-4-8"; // naive = throw the whole file at the top model
+const NAIVE_OUTPUT_TOKENS = 300;
+
+export function buildEOB(root: string, findings: Finding[], estimated = true): EOB {
+  const fileTokenCache = new Map<string, number>();
+  const fileTokens = (file: string): number => {
+    let t = fileTokenCache.get(file);
+    if (t === undefined) {
+      try {
+        t = estimateTokens(readFileSync(join(root, file), "utf8"));
+      } catch {
+        t = 0;
+      }
+      fileTokenCache.set(file, t);
+    }
+    return t;
+  };
+
+  const byModel: EOB["byModel"] = {};
+  const bump = (key: string, c: number) => {
+    (byModel[key] ??= { count: 0, cost: 0 }).count++;
+    byModel[key].cost += c;
+  };
+
+  let spend = 0;
+  let naiveCost = 0;
+  let fixedLocally = 0;
+  let escalated = 0;
+  let ignored = 0;
+
+  for (const f of findings) {
+    // Naive baseline: every finding would have cost a full-file pass at the top model.
+    naiveCost += cost(NAIVE_MODEL, fileTokens(f.file), NAIVE_OUTPUT_TOKENS);
+
+    if (f.fixability === "autofix") {
+      fixedLocally++;
+      bump("local", 0);
+      continue;
+    }
+    if (f.fixability === "ignore") {
+      ignored++;
+      continue;
+    }
+
+    escalated++;
+    if (f.resolution) {
+      spend += f.resolution.cost;
+      bump(f.resolution.model, f.resolution.cost);
+    }
+  }
+
+  return {
+    total: findings.length,
+    fixedLocally,
+    escalated,
+    ignored,
+    spend,
+    naiveCost,
+    saved: naiveCost - spend,
+    byModel,
+    estimated,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env bun
+import { resolve, relative } from "node:path";
+import type { Finding, EOB, AuditResult, Bucket } from "./types";
+import { detectDeps } from "./detect/deps";
+import { triage } from "./triage";
+import { partition } from "./diagnose/partition";
+import { assembleScan, toReport } from "./scan";
+import { AnthropicFixer } from "./treat/anthropic";
+import { runApplyLoop } from "./treat/apply";
+import { loadRouting, routedModels } from "./treat/route";
+import { loadPrices } from "./pricing/llmIntel";
+import { cluster } from "./amortize/cluster";
+import { synthesize } from "./amortize/synthesize";
+import { promote } from "./amortize/promote";
+import { buildEOB } from "./bill/eob";
+import { writeHealthRecord } from "./record/health";
+import { parseLog, audit } from "./audit/audit";
+import { c, usd } from "./util";
+
+// ── scan (Approach B): read-only pre-flight, estimated EOB ──────────────────
+async function scan(target: string, json: boolean) {
+  const root = resolve(target);
+  const now = new Date().toISOString();
+
+  loadRouting(root);
+  const prices = await loadPrices(routedModels());
+  const data = await assembleScan(root);
+  const recordDir = writeHealthRecord(root, data.deps, data.findings, data.eob, now);
+
+  if (json) {
+    // The in-harness contract: emit findings + tight packets + recommended
+    // routing for a host agent to act on. No model is called here.
+    console.log(JSON.stringify(toReport(root, prices.source, data), null, 2));
+    return;
+  }
+
+  const where = relative(process.cwd(), root) || ".";
+  console.log(`\n${c.bold("🩺 Token Clinic")} ${c.dim(`— ${where}`)}`);
+  console.log(c.dim(`   ${data.deps.manager} project · ${Object.keys(data.deps.deps).length} deps · ${data.findings.length} findings · prices: ${prices.source}\n`));
+  for (const f of data.findings) printFinding(f);
+  printEOB(data.eob);
+  console.log(c.dim(`  health record → ${relative(process.cwd(), recordDir)}/\n`));
+}
+
+// ── scan --apply (Approach B, live): iterative fix + verify ─────────────────
+async function scanApply(target: string) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.log(`${c.red("scan --apply needs a model")} — set ANTHROPIC_API_KEY, then re-run.`);
+    console.log(c.dim("  (without it, run plain `tokenclinic scan` for the estimated EOB.)"));
+    process.exit(1);
+  }
+
+  const root = resolve(target);
+  const now = new Date().toISOString();
+  loadRouting(root);
+  await loadPrices(routedModels());
+  const deps = detectDeps(root);
+
+  const { before, fixed } = await runApplyLoop(root, new AnthropicFixer());
+
+  for (const f of fixed) {
+    const ok = f.resolution?.verified;
+    console.log(
+      `  ${ok ? c.green("✓") : c.yellow("✗")} ${c.bold(f.rule)} ` +
+        `${c.dim(`${f.file}:${f.line}`)} → ${f.resolution?.model.replace("claude-", "")} ${c.dim(usd(f.resolution?.cost ?? 0))}`,
+    );
+  }
+
+  // EOB: real costs from `fixed`, plus the locally-fixable / ignored buckets from `before`.
+  const reported = [...before.filter((f) => f.fixability !== "needs-llm"), ...fixed];
+  const eob = buildEOB(root, reported, false);
+  const recordDir = writeHealthRecord(root, deps, reported, eob, now);
+
+  const verified = fixed.filter((f) => f.resolution?.verified).length;
+  console.log(`\n${c.bold("🩺 Token Clinic")} ${c.dim(`— applied ${verified}/${fixed.length} fixes verified`)}\n`);
+  printEOB(eob);
+  console.log(c.dim(`  health record → ${relative(process.cwd(), recordDir)}/\n`));
+}
+
+// ── learn (v2): amortize recurring classes into local rules ─────────────────
+const CLUSTER_MIN = 3;
+
+async function learn(target: string) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.log(`${c.red("learn needs a model")} — set ANTHROPIC_API_KEY, then re-run.`);
+    process.exit(1);
+  }
+
+  const root = resolve(target);
+  loadRouting(root);
+  const findings = partition(triage(root));
+  const clusters = cluster(findings, CLUSTER_MIN);
+
+  console.log(`\n${c.bold("🩺 Token Clinic — learn")} ${c.dim(`— ${relative(process.cwd(), root) || "."}`)}`);
+  if (clusters.length === 0) {
+    console.log(c.dim(`   no needs-llm class recurs ≥${CLUSTER_MIN}× — nothing to amortize yet.\n`));
+    return;
+  }
+
+  for (const cl of clusters) {
+    process.stdout.write(`  synthesizing ${c.bold(cl.rule)} ${c.dim(`(${cl.findings.length}×)`)} … `);
+    const rule = await synthesize(root, cl);
+    if (!rule) {
+      console.log(c.yellow("no usable rule returned"));
+      continue;
+    }
+    const p = promote(root, rule);
+    if (p.status === "promoted") {
+      console.log(`${c.green("✓ promoted")} ${c.dim(`→ rules/${rule.id}.json — this class is now $0 forever`)}`);
+    } else {
+      console.log(`${c.yellow("⚠ quarantined")} ${c.dim(rule.id)}`);
+      for (const f of p.failures) console.log(c.dim(`      ${f}`));
+    }
+  }
+  console.log(c.dim(`\n  promoted rules run on every future ${c.bold("scan")} — re-run scan to see the new $0 lane.\n`));
+}
+
+// ── shared rendering ────────────────────────────────────────────────────────
+function printFinding(f: Finding) {
+  const sev = f.severity === "error" ? c.red("●") : c.yellow("●");
+  console.log(`  ${sev} ${c.bold(f.rule)} ${laneTag(f)} ${f.message}`);
+  console.log(`     ${c.dim(`${f.file}:${f.line}`)}`);
+}
+
+function laneTag(f: Finding): string {
+  if (f.fixability === "autofix") return c.green("[local]");
+  if (f.fixability === "ignore") return c.dim("[ignore]");
+  return c.cyan(`[${f.difficulty}→${f.resolution?.model.replace("claude-", "") ?? "?"}]`);
+}
+
+function printEOB(eob: EOB) {
+  const flag = eob.estimated ? c.dim(" (estimated — LLM step stubbed)") : c.dim(" (actual)");
+  console.log(`${c.bold("  Explanation of Benefits")}${flag}`);
+  console.log(c.dim("  ─────────────────────────────────────────"));
+  console.log(`  ${String(eob.total).padStart(3)} findings`);
+  console.log(`  ${c.green(String(eob.fixedLocally).padStart(3))} fixed on-device   ${c.dim("· $0.00")}`);
+  console.log(`  ${c.cyan(String(eob.escalated).padStart(3))} escalated to a model`);
+  for (const [model, m] of Object.entries(eob.byModel)) {
+    if (model === "local") continue;
+    console.log(`      ${c.dim("→")} ${model.padEnd(20)} ${m.count}× ${c.dim(usd(m.cost))}`);
+  }
+  console.log(c.dim("  ─────────────────────────────────────────"));
+  console.log(`  clinic spend   ${c.bold(usd(eob.spend))}`);
+  console.log(`  naive cost     ${c.dim(usd(eob.naiveCost))} ${c.dim("(dump each file at the top model)")}`);
+  console.log(`  ${c.green(c.bold(`saved ~${usd(eob.saved)}`))}  ${c.dim(`(${pct(eob.saved, eob.naiveCost)} cheaper)`)}\n`);
+}
+
+const pct = (saved: number, base: number) => (base > 0 ? `${Math.round((saved / base) * 100)}%` : "0%");
+
+// ── audit (Approach A): retroactive audit over existing call logs ────────────
+async function runAudit(logPath: string | undefined) {
+  if (!logPath) {
+    console.log("usage: tokenclinic audit <logs.jsonl>");
+    process.exit(1);
+  }
+  const calls = parseLog(resolve(logPath));
+  const prices = await loadPrices(calls.map((c) => c.model)); // price against the log's own models
+  reportAudit(relative(process.cwd(), resolve(logPath)), audit(calls), prices.source);
+}
+
+const BUCKET_LABEL: Record<Bucket, (s: string) => string> = {
+  eliminable: c.green,
+  routable: c.cyan,
+  essential: c.dim,
+};
+const BUCKET_NOTE: Record<Bucket, string> = {
+  eliminable: "killed on-device → $0",
+  routable: "re-priced to cheapest tier",
+  essential: "real reasoning → unchanged",
+};
+
+function reportAudit(source: string, a: AuditResult, priceSource: string) {
+  console.log(`\n${c.bold("🩺 Token Clinic — retroactive audit")} ${c.dim(`· ${source}`)}`);
+  const flag = a.estimated ? c.dim(" (estimated — some calls bucketed heuristically)") : "";
+  console.log(c.dim(`   ${a.calls} calls · ${usd(a.spend)} spent · prices: ${priceSource}${flag}\n`));
+  if (a.unpriced > 0) {
+    console.log(c.yellow(`   ⚠ ${a.unpriced} call(s) had no known price — excluded from cost\n`));
+  }
+
+  for (const bucket of ["eliminable", "routable", "essential"] as Bucket[]) {
+    const b = a.byBucket[bucket];
+    const share = a.spend > 0 ? Math.round((b.spend / a.spend) * 100) : 0;
+    const paint = BUCKET_LABEL[bucket];
+    console.log(
+      `  ${paint("●")} ${paint(bucket.padEnd(11))} ${String(b.count).padStart(2)} calls  ` +
+        `${usd(b.spend).padStart(8)}  ${c.dim(`${String(share).padStart(2)}% of spend · ${BUCKET_NOTE[bucket]}`)}`,
+    );
+  }
+
+  const frac = Math.round(a.eliminableFraction * 100);
+  const verdict = frac >= 40 ? c.green("clearly large — build it") : frac < 15 ? c.yellow("clearly small — walk away") : c.yellow("murky — instrument deeper");
+  console.log(c.dim("\n  ─────────────────────────────────────────"));
+  console.log(`  eliminable-class fraction  ${c.bold(`${frac}%`)}  ${c.dim(`(${verdict})`)}`);
+  console.log(`  projected spend            ${c.bold(usd(a.projectedSpend))} ${c.dim("under the clinic loop")}`);
+  console.log(`  ${c.green(c.bold(`would have saved ~${usd(a.projectedSaved)}`))}  ${c.dim(`(${pct(a.projectedSaved, a.spend)} cheaper)`)}\n`);
+}
+
+// ── entry ────────────────────────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+const apply = rest.includes("--apply") || rest.includes("--fix");
+const json = rest.includes("--json");
+const path = rest.find((a) => !a.startsWith("-"));
+
+if (cmd === "scan") {
+  if (apply) await scanApply(path ?? ".");
+  else await scan(path ?? ".", json);
+} else if (cmd === "audit") {
+  await runAudit(path);
+} else if (cmd === "learn") {
+  await learn(path ?? ".");
+} else {
+  console.log(
+    "usage:\n" +
+      "  tokenclinic audit <logs.jsonl>   retroactive audit over past LLM calls\n" +
+      "  tokenclinic scan [path]          read-only pre-flight (estimated EOB)\n" +
+      "  tokenclinic scan [path] --json   machine report for a host agent (no model call)\n" +
+      "  tokenclinic scan [path] --apply  live: fix + verify (needs ANTHROPIC_API_KEY)\n" +
+      "  tokenclinic learn [path]         amortize recurring classes → local rules (needs key)",
+  );
+  process.exit(1);
+}

package/src/detect/deps.ts

@@ -0,0 +1,37 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Dependency detection. v1 reads package.json + the lockfile to identify the
+// package manager and installed deps. This is what later drives dep-aware
+// analyzer auto-configuration (enable the react-hooks rules iff react is a dep,
+// etc.) — for v1 we just surface the profile in the report and Health Record.
+
+export interface DepProfile {
+  manager: string;
+  deps: Record<string, string>;
+}
+
+export function detectDeps(root: string): DepProfile {
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) return { manager: "unknown", deps: {} };
+
+  let pkg: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> } = {};
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return { manager: "unknown", deps: {} };
+  }
+
+  const manager = existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb"))
+    ? "bun"
+    : existsSync(join(root, "pnpm-lock.yaml"))
+      ? "pnpm"
+      : existsSync(join(root, "package-lock.json"))
+        ? "npm"
+        : "node";
+
+  return {
+    manager,
+    deps: { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) },
+  };
+}

package/src/diagnose/context.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding, ContextPacket } from "../types";
+import { estimateTokens } from "../pricing/table";
+
+// Build the tight context packet handed to the model — the few lines around the
+// finding, not the whole file. This is the core token-saving move of Diagnose.
+//
+// v1 slices a fixed line radius. v2 swaps this for fff
+// (https://github.com/dmtrKovalenko/fff): fast, frecency-ranked retrieval of the
+// *related* symbols/definitions, not just the physically-adjacent lines.
+const RADIUS = 15;
+
+export function buildContext(root: string, f: Finding): ContextPacket {
+  let lines: string[] = [];
+  try {
+    lines = readFileSync(join(root, f.file), "utf8").split("\n");
+  } catch {
+    return { snippet: "", startLine: f.line, tokensEstimate: 0 };
+  }
+
+  const start = Math.max(0, f.line - 1 - RADIUS);
+  const end = Math.min(lines.length, f.line - 1 + RADIUS + 1);
+  const snippet = lines.slice(start, end).join("\n");
+
+  return { snippet, startLine: start + 1, tokensEstimate: estimateTokens(snippet) };
+}

package/src/diagnose/partition.ts

@@ -0,0 +1,37 @@
+import type { Finding, Fixability, DifficultyClass } from "../types";
+
+// Partition: decide, per finding, whether it can be fixed on-device for $0, or
+// must escalate to a model — and if so, how hard the fix is (which routes it to
+// a model tier in Treat).
+//
+// v1 uses a small hand-curated map of TS error codes. v2 replaces the static
+// maps with the generated-rule engine: a recurring needs-llm class gets
+// synthesized into an autofix rule, after which it lands in AUTOFIX for free.
+
+// Unused declarations — safely removable by a deterministic codemod. $0.
+const AUTOFIX = new Set(["TS6133", "TS6138", "TS6192", "TS6196", "TS6198"]);
+
+// Localized, low-ambiguity fixes (missing import, typo, simple syntax).
+const MECHANICAL = new Set(["TS2304", "TS2307", "TS2552", "TS1005", "TS1109", "TS1003"]);
+
+export function partition(findings: Finding[]): Finding[] {
+  for (const f of findings) {
+    // Findings from a promoted (amortized) rule are already a $0 on-device check —
+    // keep them in the autofix lane; don't reclassify by the TS-code maps.
+    if (f.source.startsWith("ast-grep:")) {
+      f.difficulty = "mechanical";
+      continue;
+    }
+    const { fixability, difficulty } = classify(f.rule);
+    f.fixability = fixability;
+    f.difficulty = difficulty;
+  }
+  return findings;
+}
+
+function classify(rule: string): { fixability: Fixability; difficulty: DifficultyClass } {
+  if (AUTOFIX.has(rule)) return { fixability: "autofix", difficulty: "mechanical" };
+  if (MECHANICAL.has(rule)) return { fixability: "needs-llm", difficulty: "mechanical" };
+  // Everything else from a type checker is, by default, a semantic fix.
+  return { fixability: "needs-llm", difficulty: "semantic" };
+}

package/src/pricing/llmIntel.ts

@@ -0,0 +1,41 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getModelInfo, type LLMIntelConfigInput } from "@basisoasis/llm-intel";
+import { setPrice } from "./table";
+import { toOpenRouterId, perMillion } from "./normalize";
+
+// Warm-up: resolve the given model ids against llm-intel (the OpenRouter catalog)
+// once at command start and populate the price book. Keeps the hot path sync —
+// cost() never awaits. Fully non-fatal: offline or unknown ids just fall through
+// to the committed snapshot, so the read-only path keeps working with no network.
+
+export interface PriceLoad {
+  loaded: number;
+  source: "llm-intel" | "snapshot";
+}
+
+const OPTS: LLMIntelConfigInput = {
+  provider: "openrouter",
+  cacheDir: join(tmpdir(), "tokenclinic-llm-intel"),
+  cacheTtl: 24 * 60 * 60 * 1000, // 24h
+};
+
+export async function loadPrices(ids: string[]): Promise<PriceLoad> {
+  let loaded = 0;
+  for (const id of [...new Set(ids)]) {
+    try {
+      const res = await getModelInfo(toOpenRouterId(id), OPTS);
+      const pricing = res?.data?.pricing;
+      if (!pricing) continue;
+      const inputPerM = perMillion(pricing.input.amount, pricing.input.unit);
+      const outputPerM = perMillion(pricing.output.amount, pricing.output.unit);
+      if (inputPerM !== null && outputPerM !== null) {
+        setPrice(id, { inputPerM, outputPerM });
+        loaded++;
+      }
+    } catch {
+      // offline, rate-limited, or unknown id — snapshot covers it
+    }
+  }
+  return { loaded, source: loaded > 0 ? "llm-intel" : "snapshot" };
+}

package/src/pricing/normalize.ts

@@ -0,0 +1,35 @@
+// Model-id normalization between TokenClinic's bare ids and llm-intel's
+// OpenRouter-style `provider/model` ids — and unit conversion to $/1M tokens.
+
+const BARE_TO_OPENROUTER: Record<string, string> = {
+  "claude-opus-4-8": "anthropic/claude-opus-4-8",
+  "claude-sonnet-4-6": "anthropic/claude-sonnet-4-6",
+  "claude-haiku-4-5": "anthropic/claude-haiku-4-5",
+};
+
+// A bare Anthropic id → its OpenRouter id. Anything already provider-prefixed
+// (`openai/…`, `google/…`, or an explicit `anthropic/…`) is passed through, so
+// other providers work without special-casing.
+export function toOpenRouterId(id: string): string {
+  if (id.includes("/")) return id;
+  return BARE_TO_OPENROUTER[id] ?? `anthropic/${id}`;
+}
+
+// llm-intel reports an amount + a unit; normalize everything to $/1M tokens.
+// Non-token units (per_image / per_request) aren't token pricing → null.
+export function perMillion(amount: unknown, unit: string): number | null {
+  const n = Number(amount && typeof amount === "object" ? String(amount) : amount);
+  if (!Number.isFinite(n)) return null;
+  switch (unit) {
+    case "per_million_tokens":
+      return n;
+    case "per_thousand_tokens":
+      return n * 1_000;
+    case "per_token":
+      return n * 1_000_000;
+    case "free":
+      return 0;
+    default:
+      return null;
+  }
+}

package/src/pricing/table.ts

@@ -0,0 +1,50 @@
+// Pricing intelligence.
+//
+// A cost resolves in this order:
+//   1. the live price book — populated at command start from llm-intel
+//      (the OpenRouter catalog; any provider's model prices for free)
+//   2. a committed offline SNAPSHOT — so read-only `scan` never *requires*
+//      network and the routed Anthropic models are always priced
+//   3. unknown → null (cost 0, surfaced separately; never a fabricated number)
+//
+// See ./llmIntel.ts for the warm-up and ./normalize.ts for id/unit handling.
+
+export interface ModelPrice {
+  inputPerM: number;
+  outputPerM: number;
+}
+
+// Offline fallback (USD per 1M tokens). Overridden by llm-intel when reachable.
+const SNAPSHOT: Record<string, ModelPrice> = {
+  "claude-haiku-4-5": { inputPerM: 1.0, outputPerM: 5.0 },
+  "claude-sonnet-4-6": { inputPerM: 3.0, outputPerM: 15.0 },
+  "claude-opus-4-8": { inputPerM: 5.0, outputPerM: 25.0 },
+};
+
+const book = new Map<string, ModelPrice>();
+
+export function setPrice(id: string, p: ModelPrice): void {
+  book.set(id, p);
+}
+
+export function resetPrices(): void {
+  book.clear();
+}
+
+export function priceOf(id: string): ModelPrice | null {
+  return book.get(id) ?? SNAPSHOT[id] ?? null;
+}
+
+export function isPriced(id: string): boolean {
+  return priceOf(id) !== null;
+}
+
+export function cost(model: string, tokensIn: number, tokensOut: number): number {
+  const p = priceOf(model);
+  if (!p) return 0; // unknown model — callers surface this via isPriced(), don't invent a price
+  return (tokensIn / 1e6) * p.inputPerM + (tokensOut / 1e6) * p.outputPerM;
+}
+
+// Rough token estimate for the read-only path. chars/4 — replaced by exact usage
+// counts on `--apply`.
+export const estimateTokens = (text: string) => Math.ceil(text.length / 4);