ultracost 0.2.0

package/src/guard.js

@@ -0,0 +1,300 @@
+import { existsSync, readFileSync, readdirSync, lstatSync, writeFileSync } from 'node:fs';
+import { join, extname, sep } from 'node:path';
+import { classifyModel, tierModel } from './policy.js';
+
+export const CODES = {
+  NOOPTS: 'UC001', // agent(x) with no options object
+  MISSING: 'UC002', // options object present but no model key
+  BANNED: 'UC003', // model resolves to a neverUse model (e.g. haiku)
+  INHERIT: 'UC004', // model: 'inherit' while allowInherit is false
+  DYNAMIC: 'UC005' // model/options is a variable; can't verify statically
+};
+
+// agent( as a call — not subagent(, myagent(, or obj.agent(.
+const SPAWN_RE = /(?<![\w.$])agent\s*\(/g;
+
+const MODEL_LITERAL = /\bmodel\s*:\s*(['"`])([\w.\-]+)\1/;
+const MODEL_DYNAMIC = /\bmodel\s*:/;
+const EFFORT_LITERAL = /\beffort\s*:\s*(['"`])(\w+)\1/;
+// A fan-out: the agent() sits inside an open .map/.flatMap/Array.from call, or inside a
+// pipeline(items, ...stages) call (every stage runs once per item) — so its count is a
+// runtime (unknown) multiple of the collection length. parallel([...]) of literal thunks
+// is NOT a fan-out (fixed count); parallel(items.map(...)) is caught by the .map rule.
+const FANOUT_CALLEE = /(?:^|\.)(?:map|flatMap)$/;
+const isFanoutCallee = (name) => FANOUT_CALLEE.test(name) || name === 'Array.from' || name === 'pipeline';
+
+// Spans inside string/template literals and // or /* */ comments. A literal
+// "agent(" there is prose (e.g. a prompt string) and must not count as a call.
+function ignorableRanges(text) {
+  const ranges = [];
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (ch === '/' && next === '/') {
+      const start = i;
+      i += 2;
+      while (i < n && text[i] !== '\n') i++;
+      ranges.push([start, i]);
+    } else if (ch === '/' && next === '*') {
+      const start = i;
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i = Math.min(n, i + 2);
+      ranges.push([start, i]);
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      const start = i;
+      i++;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === ch) { i++; break; }
+        i++;
+      }
+      ranges.push([start, i]);
+    } else {
+      i++;
+    }
+  }
+  return ranges;
+}
+
+function inRanges(ranges, idx) {
+  let lo = 0;
+  let hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const [s, e] = ranges[mid];
+    if (idx < s) hi = mid - 1;
+    else if (idx >= e) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
+function lineCol(text, index) {
+  let line = 1;
+  let last = 0;
+  for (let i = 0; i < index; i++) {
+    if (text[i] === '\n') {
+      line++;
+      last = i + 1;
+    }
+  }
+  return { line, column: index - last + 1 };
+}
+
+function lineText(text, index) {
+  const start = text.lastIndexOf('\n', index) + 1;
+  let end = text.indexOf('\n', index);
+  if (end === -1) end = text.length;
+  return text.slice(start, end).trim();
+}
+
+// From the '(' index, return the argument source up to the matching ')'.
+function captureArgs(text, openIdx) {
+  let depth = 0;
+  let str = null;
+  for (let i = openIdx; i < text.length; i++) {
+    const ch = text[i];
+    const prev = text[i - 1];
+    if (str) {
+      if (ch === str && prev !== '\\') str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      str = ch;
+      continue;
+    }
+    if (ch === '(') depth++;
+    else if (ch === ')') {
+      depth--;
+      if (depth === 0) return { args: text.slice(openIdx + 1, i), end: i };
+    }
+  }
+  return { args: text.slice(openIdx + 1), end: text.length };
+}
+
+// Count every real agent() stage and collect the subset that are problems.
+export function analyze(text, policy, file = '<text>') {
+  const ranges = ignorableRanges(text);
+  const findings = [];
+  let stages = 0;
+  for (const m of text.matchAll(SPAWN_RE)) {
+    if (inRanges(ranges, m.index)) continue;
+    stages++;
+    const openIdx = m.index + m[0].length - 1;
+    const { args } = captureArgs(text, openIdx);
+    const { line, column } = lineCol(text, m.index);
+    const base = { file, line, column, snippet: lineText(text, m.index) };
+
+    const literal = args.match(MODEL_LITERAL);
+    if (literal) {
+      const value = literal[2];
+      const verdict = classifyModel(value, policy);
+      if (verdict === 'banned') {
+        findings.push({ ...base, code: CODES.BANNED, severity: 'error', model: value, message: `stage pins banned model "${value}" (policy.neverUse)` });
+      } else if (verdict === 'inherit') {
+        findings.push({ ...base, code: CODES.INHERIT, severity: 'error', model: value, message: `stage uses model: 'inherit' (allowInherit is false)` });
+      }
+      continue;
+    }
+    if (MODEL_DYNAMIC.test(args)) continue;
+
+    const hasObjectLiteral = /\{[\s\S]*\}/.test(args);
+    const secondArgIsIdentifier = /,\s*[A-Za-z_$][\w$]*\s*$/.test(args.trimEnd());
+    if (hasObjectLiteral) {
+      findings.push({ ...base, code: CODES.MISSING, severity: 'error', message: 'stage options object has no model — will inherit the session model' });
+    } else if (secondArgIsIdentifier) {
+      findings.push({ ...base, code: CODES.DYNAMIC, severity: 'warn', message: 'stage options passed as a variable — cannot verify a model is pinned' });
+    } else {
+      findings.push({ ...base, code: CODES.NOOPTS, severity: 'error', message: 'stage has no options object — add { model: ... } so it does not inherit the session model' });
+    }
+  }
+  return { stages, findings };
+}
+
+export function scanText(text, policy, file = '<text>') {
+  return analyze(text, policy, file).findings;
+}
+
+// Names of call expressions whose '(' is still open at `idx` (string/comment-aware).
+// e.g. inside `files.map(f => agent(...))`, at the agent( the stack holds "files.map".
+function enclosingCalls(text, ranges, idx) {
+  const stack = [];
+  for (let i = 0; i < idx; i++) {
+    if (inRanges(ranges, i)) continue;
+    const ch = text[i];
+    if (ch === '(') {
+      let j = i - 1;
+      while (j >= 0 && /\s/.test(text[j])) j--;
+      const end = j;
+      while (j >= 0 && /[\w$.]/.test(text[j])) j--;
+      stack.push(text.slice(j + 1, end + 1));
+    } else if (ch === ')') {
+      stack.pop();
+    }
+  }
+  return stack;
+}
+
+// Per-stage descriptors for cost estimation: each real agent() stage with its
+// pinned model (or null = inherits session model), pinned effort (or null), and
+// whether it is a fan-out (unknown runtime multiplier).
+export function stageList(text) {
+  const ranges = ignorableRanges(text);
+  const out = [];
+  for (const m of text.matchAll(SPAWN_RE)) {
+    if (inRanges(ranges, m.index)) continue;
+    const openIdx = m.index + m[0].length - 1;
+    const { args } = captureArgs(text, openIdx);
+    const { line } = lineCol(text, m.index);
+    const ml = args.match(MODEL_LITERAL);
+    const el = args.match(EFFORT_LITERAL);
+    const fanout = enclosingCalls(text, ranges, m.index).some(isFanoutCallee);
+    out.push({
+      line,
+      model: ml ? ml[2] : null,
+      dynamicModel: !ml && MODEL_DYNAMIC.test(args),
+      effort: el ? el[2] : null,
+      fanout
+    });
+  }
+  return out;
+}
+
+const SCAN_EXTS = new Set(['.js', '.mjs', '.cjs', '.ts']);
+
+export function collectFiles(target) {
+  if (!existsSync(target)) return [];
+  // lstat (not stat) so a symlink is reported as a symlink rather than its
+  // target — never follow/recurse one (avoids symlink loops blowing the stack,
+  // and stops --fix writing through a link to a file outside the scanned tree).
+  const st = lstatSync(target);
+  if (st.isSymbolicLink()) return [];
+  if (st.isFile()) return [target];
+  if (!st.isDirectory()) return [];
+  const out = [];
+  for (const name of readdirSync(target)) {
+    if (name === 'node_modules' || name.startsWith('.')) continue;
+    const full = join(target, name);
+    const s = lstatSync(full);
+    if (s.isSymbolicLink()) continue;
+    if (s.isDirectory()) out.push(...collectFiles(full));
+    else if (SCAN_EXTS.has(extname(full))) out.push(full);
+  }
+  return out;
+}
+
+// **/workflows/scripts/*.js under base — the ultracode script layout.
+export function collectWorkflowScripts(base) {
+  return collectFiles(base).filter((f) => {
+    const parts = f.split(sep);
+    const n = parts.length;
+    return n >= 3 && parts[n - 2] === 'scripts' && parts[n - 3] === 'workflows';
+  });
+}
+
+export function scan(target, policy) {
+  const files = collectFiles(target);
+  const findings = [];
+  for (const f of files) {
+    findings.push(...scanText(readFileSync(f, 'utf8'), policy, f));
+  }
+  return { findings, files };
+}
+
+export function auditScripts(base, policy) {
+  const files = collectWorkflowScripts(base);
+  const totals = { scripts: files.length, stages: 0, pinned: 0, unpinned: 0, banned: 0, inherit: 0, dynamic: 0 };
+  for (const f of files) {
+    const { stages, findings } = analyze(readFileSync(f, 'utf8'), policy, f);
+    totals.stages += stages;
+    for (const x of findings) {
+      if (x.code === CODES.NOOPTS || x.code === CODES.MISSING) totals.unpinned++;
+      else if (x.code === CODES.BANNED) totals.banned++;
+      else if (x.code === CODES.INHERIT) totals.inherit++;
+      else if (x.code === CODES.DYNAMIC) totals.dynamic++;
+    }
+  }
+  totals.pinned = totals.stages - totals.unpinned - totals.banned - totals.inherit - totals.dynamic;
+  totals.unpinnedRatio = totals.stages ? totals.unpinned / totals.stages : 0;
+  return { base, files, totals };
+}
+
+// Insert the default model on the unambiguous cases, back-to-front so earlier
+// edits don't shift later offsets.
+export function fixText(text, policy) {
+  const model = tierModel(policy.default, policy);
+  const ranges = ignorableRanges(text);
+  const sites = [];
+  for (const m of text.matchAll(SPAWN_RE)) {
+    if (inRanges(ranges, m.index)) continue;
+    const openIdx = m.index + m[0].length - 1;
+    const { args, end } = captureArgs(text, openIdx);
+    if (MODEL_DYNAMIC.test(args)) continue;
+    const objStart = text.indexOf('{', openIdx);
+    if (objStart !== -1 && objStart < end) {
+      sites.push({ type: 'insert', at: objStart + 1 });
+    } else {
+      sites.push({ type: 'append', at: end });
+    }
+  }
+  let out = text;
+  let count = 0;
+  for (const s of sites.sort((a, b) => b.at - a.at)) {
+    if (s.type === 'insert') {
+      out = out.slice(0, s.at) + ` model: '${model}',` + out.slice(s.at);
+    } else {
+      out = out.slice(0, s.at) + `, { model: '${model}' }` + out.slice(s.at);
+    }
+    count++;
+  }
+  return { text: out, count };
+}
+
+export function fixFile(file, policy) {
+  const { text, count } = fixText(readFileSync(file, 'utf8'), policy);
+  if (count) writeFileSync(file, text);
+  return count;
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export { loadPolicy, normalize, classifyModel, tierModel } from './policy.js';
+export { scan, scanText, analyze, stageList, fixText, fixFile, collectFiles, collectWorkflowScripts, auditScripts, CODES } from './guard.js';
+export { estimateText, estimateFile, priceKey } from './estimate.js';
+export { refreshPricing, parsePrices, assertPlausible, writePricingToPolicy, DEFAULT_PRICING_URL } from './pricing.js';
+export { compileRules, replaceBlock, stripBlock } from './rules.js';
+export { install, uninstall, readSettings } from './install.js';
+export * as paths from './paths.js';

package/src/install.js

@@ -0,0 +1,113 @@
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync
+} from 'node:fs';
+import {
+  CLAUDE_DIR, CLAUDE_MD, SETTINGS, ULTRACOST_DIR, POLICY_PATH,
+  HOOK_PATH, HOOK_SRC, DEFAULT_POLICY
+} from './paths.js';
+import { compileRules, replaceBlock, stripBlock } from './rules.js';
+
+// Invoked via `node` so it needs no shebang, +x bit, or PATH entry.
+const HOOK_COMMAND = `node "${HOOK_PATH}"`;
+
+// null = file missing; undefined = present but invalid JSON.
+export function readSettings() {
+  if (!existsSync(SETTINGS)) return null;
+  try {
+    return JSON.parse(readFileSync(SETTINGS, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+const isUltracostHook = (h) => h.hooks?.some((hh) => hh.command?.includes('ultracost'));
+
+function ensureDirs() {
+  for (const d of [CLAUDE_DIR, ULTRACOST_DIR]) {
+    if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  }
+}
+
+function writePolicyFile(force) {
+  if (existsSync(POLICY_PATH) && !force) return 'kept';
+  copyFileSync(DEFAULT_POLICY, POLICY_PATH);
+  return existsSync(POLICY_PATH) ? 'written' : 'failed';
+}
+
+function writeRules(policy) {
+  const block = compileRules(policy);
+  if (!existsSync(CLAUDE_MD)) {
+    writeFileSync(CLAUDE_MD, block + '\n');
+    return 'created';
+  }
+  const existing = readFileSync(CLAUDE_MD, 'utf8');
+  const replaced = replaceBlock(existing, block);
+  if (replaced !== null) {
+    writeFileSync(CLAUDE_MD, replaced);
+    return 'updated';
+  }
+  writeFileSync(CLAUDE_MD, existing.trimEnd() + '\n\n' + block + '\n');
+  return 'appended';
+}
+
+function writeHook() {
+  copyFileSync(HOOK_SRC, HOOK_PATH);
+}
+
+function registerHook() {
+  const settings = readSettings();
+  if (settings === undefined) return 'invalid';
+  const conf = settings ?? {};
+  conf.hooks ??= {};
+  conf.hooks.SessionStart ??= [];
+  if (conf.hooks.SessionStart.some(isUltracostHook)) return 'present';
+  conf.hooks.SessionStart.push({
+    matcher: 'startup|resume|clear|compact',
+    hooks: [{ type: 'command', command: HOOK_COMMAND }]
+  });
+  writeFileSync(SETTINGS, JSON.stringify(conf, null, 2) + '\n');
+  return settings === null ? 'created' : 'registered';
+}
+
+export function install(policy, { force = false } = {}) {
+  ensureDirs();
+  return {
+    policy: writePolicyFile(force),
+    rules: writeRules(policy),
+    hook: (writeHook(), 'installed'),
+    register: registerHook()
+  };
+}
+
+export function uninstall() {
+  const result = { rules: 'absent', hook: 'absent', register: 'absent', policy: 'absent' };
+
+  if (existsSync(CLAUDE_MD)) {
+    const content = readFileSync(CLAUDE_MD, 'utf8');
+    if (content.includes('ultracost:start')) {
+      const stripped = stripBlock(content);
+      if (stripped) writeFileSync(CLAUDE_MD, stripped + '\n');
+      else rmSync(CLAUDE_MD);
+      result.rules = 'removed';
+    }
+  }
+  if (existsSync(HOOK_PATH)) {
+    rmSync(HOOK_PATH);
+    result.hook = 'removed';
+  }
+  const settings = readSettings();
+  if (settings === undefined) {
+    result.register = 'invalid';
+  } else if (settings?.hooks?.SessionStart) {
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter((h) => !isUltracostHook(h));
+    if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+    writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+    result.register = 'removed';
+  }
+  if (existsSync(ULTRACOST_DIR)) {
+    rmSync(ULTRACOST_DIR, { recursive: true, force: true });
+    result.policy = 'removed';
+  }
+  return result;
+}

package/src/log.js

@@ -0,0 +1,18 @@
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const c = {
+  bold: wrap('1'),
+  dim: wrap('2'),
+  red: wrap('31'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  cyan: wrap('36')
+};
+
+export const log = (msg = '') => console.log(msg);
+export const ok = (msg) => log(`${c.green('OK')} ${msg}`);
+export const warn = (msg) => log(`${c.yellow('!!')} ${msg}`);
+export const err = (msg) => log(`${c.red('XX')} ${msg}`);
+export const info = (msg) => log(c.dim(msg));

package/src/paths.js

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HOME = homedir();
+export const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// Claude Code can relocate its config via CLAUDE_CONFIG_DIR; everything below
+// hangs off it. ~/.claude/CLAUDE.md is the canonical global — ~/CLAUDE.md is not.
+export const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR
+  ? resolve(process.env.CLAUDE_CONFIG_DIR)
+  : join(HOME, '.claude');
+export const CLAUDE_MD = join(CLAUDE_DIR, 'CLAUDE.md');
+export const SETTINGS = join(CLAUDE_DIR, 'settings.json');
+export const ULTRACOST_DIR = join(CLAUDE_DIR, 'ultracost');
+export const POLICY_PATH = join(ULTRACOST_DIR, 'policy.json');
+export const PROJECTS_DIR = join(CLAUDE_DIR, 'projects');
+
+export const HOOK_PATH = join(ULTRACOST_DIR, 'reinject.mjs');
+
+export const DEFAULT_POLICY = join(ROOT, 'templates', 'policy.default.json');
+export const HOOK_SRC = join(ROOT, 'templates', 'hooks', 'reinject.mjs');
+
+export const MARKER_START = '<!-- ultracost:start -->';
+export const MARKER_END = '<!-- ultracost:end -->';
+
+export const tilde = (p) => (p.startsWith(HOME) ? p.replace(HOME, '~') : p);

package/src/policy.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { DEFAULT_POLICY, POLICY_PATH } from './paths.js';
+
+// Resolution order: explicit path, installed policy, bundled default.
+export function loadPolicy(explicitPath) {
+  const candidates = [explicitPath, POLICY_PATH, DEFAULT_POLICY].filter(Boolean);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    const raw = readFileSync(p, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(`Policy file is not valid JSON: ${p}\n  ${e.message}`);
+    }
+    return { policy: normalize(parsed), source: p };
+  }
+  throw new Error('No policy found and bundled default is missing.');
+}
+
+export function normalize(input) {
+  const p = { ...input };
+  p.version ??= 1;
+  p.neverUse = (p.neverUse ?? ['haiku']).map((m) => String(m).toLowerCase());
+  p.allowInherit ??= false;
+  p.tiers ??= { opus: { model: 'opus', effort: 'xhigh' }, sonnet: { model: 'sonnet', effort: 'high' } };
+  p.default ??= 'opus';
+  p.tieBreaker ??= p.default;
+  p.alwaysOpus ??= [];
+  p.rules ??= [];
+
+  p.effort ??= {};
+  p.effort.range ??= ['low', 'medium', 'high', 'xhigh'];
+  p.effort.default ??= 'high';
+  p.effort.maxByModel ??= { sonnet: 'high', opus: 'xhigh' };
+  p.effort.byComplexity ??= {
+    low: 'trivial deterministic work: listing/globbing files, simple extraction, formatting, mechanical renames',
+    medium: 'light judgment on a small surface: a single straightforward edit, summarizing one source',
+    high: 'standard coding/analysis: most refactors, per-file review, non-trivial tests',
+    xhigh: 'hard reasoning: cross-file architecture, adversarial review, planning, final synthesis'
+  };
+
+  p.pricing ??= {};
+  p.pricing.opus ??= { input: 5, output: 25 };
+  p.pricing.sonnet ??= { input: 3, output: 15 };
+  p.pricing.haiku ??= { input: 1, output: 5 };
+
+  p.estimation ??= {};
+  p.estimation.tokensPerStage ??= { input: 2000, output: 1200 };
+  p.estimation.effortOutputMultiplier ??= { low: 0.4, medium: 1, high: 1.8, xhigh: 3, max: 4 };
+  p.estimation.assumedFanout ??= 5;
+
+  const errors = [];
+  if (!p.tiers[p.default]) errors.push(`default tier "${p.default}" is not defined in tiers`);
+  for (const r of p.rules) {
+    if (r.tier && !p.tiers[r.tier]) errors.push(`rule references unknown tier "${r.tier}"`);
+  }
+  for (const [name, t] of Object.entries(p.tiers)) {
+    if (!t || typeof t.model !== 'string') errors.push(`tier "${name}" is missing a string "model"`);
+    if (p.neverUse.includes(String(t?.model).toLowerCase())) {
+      errors.push(`tier "${name}" uses model "${t.model}" which is listed in neverUse`);
+    }
+  }
+  if (errors.length) throw new Error('Invalid policy:\n  - ' + errors.join('\n  - '));
+  return p;
+}
+
+// neverUse matches by alias or substring, so "haiku" also bans "claude-haiku-4-5".
+export function classifyModel(value, policy) {
+  const v = String(value).toLowerCase();
+  if (v === 'inherit') return policy.allowInherit ? 'ok' : 'inherit';
+  for (const banned of policy.neverUse) {
+    if (v === banned || v.includes(banned)) return 'banned';
+  }
+  return 'ok';
+}
+
+export function tierModel(tierName, policy) {
+  return policy.tiers[tierName]?.model ?? tierName;
+}

package/src/pricing.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { POLICY_PATH } from './paths.js';
+
+// The .md variant returns the clean markdown rate table; the bare URL is a JS-rendered
+// SPA whose raw HTML does not parse reliably.
+export const DEFAULT_PRICING_URL = 'https://platform.claude.com/docs/en/about-claude/pricing.md';
+const DEFAULT_MODELS = { opus: 'Claude Opus 4.8', sonnet: 'Claude Sonnet 4.6', haiku: 'Claude Haiku 4.5' };
+
+// Defensive bounds on the one outbound request ultracost ever makes.
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_BODY_LENGTH = 2 * 1024 * 1024; // ~2MB of text; the page is a few KB
+
+// Parse per-model {input, output} from the official pricing page text. The standard
+// rate row carries several dollar figures (base input + cache columns + output); the
+// long-context row has only two. Pick, per model, the row with the most figures, then
+// take the first as input and the last as output.
+export function parsePrices(pageText, models = DEFAULT_MODELS) {
+  const out = {};
+  const lines = String(pageText).split('\n');
+  for (const [alias, name] of Object.entries(models)) {
+    let best = null;
+    for (const l of lines) {
+      if (!l.includes(name)) continue;
+      const amounts = [...l.matchAll(/\$\s*([0-9]+(?:\.[0-9]+)?)/g)].map((m) => parseFloat(m[1]));
+      if (!best || amounts.length > best.length) best = amounts;
+    }
+    if (best && best.length >= 2) out[alias] = { input: best[0], output: best[best.length - 1] };
+  }
+  return out;
+}
+
+// Fetch the official pricing page and return an updated pricing block (provenance
+// refreshed). fetchImpl is injectable so tests run offline. Throws on HTTP error or
+// if any model can't be parsed (page format drift) — the caller keeps old prices.
+export async function refreshPricing(policy, { url, fetchImpl = globalThis.fetch } = {}) {
+  const models = policy.pricing?._models || DEFAULT_MODELS;
+  const src = url || policy.pricing?._source || DEFAULT_PRICING_URL;
+  if (typeof fetchImpl !== 'function') throw new Error('no fetch available (need Node >= 24 or an injected fetchImpl)');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let body;
+  try {
+    const res = await fetchImpl(src, { headers: { 'user-agent': 'ultracost-pricing-refresh' }, signal: controller.signal });
+    if (!res.ok) throw new Error(`pricing fetch failed: HTTP ${res.status} from ${src}`);
+    body = await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
+  if (typeof body === 'string' && body.length > MAX_BODY_LENGTH) {
+    throw new Error(`pricing page too large (${body.length} chars > ${MAX_BODY_LENGTH}) from ${src} — refusing to parse`);
+  }
+  const parsed = parsePrices(body, models);
+  const missing = Object.keys(models).filter((a) => !parsed[a]);
+  if (missing.length) throw new Error(`could not parse pricing for: ${missing.join(', ')} from ${src} (page format may have changed)`);
+  assertPlausible(parsed, src);
+  return { ...policy.pricing, _source: src, _asOf: new Date().toISOString().slice(0, 10), _models: models, ...parsed };
+}
+
+// Guard against a bad parse silently overwriting good prices: output must exceed input,
+// input must be positive, and the models must not all be identical (a tell that the
+// parser latched onto unrelated numbers, as a JS-rendered HTML page produces).
+export function assertPlausible(parsed, src = 'source') {
+  const entries = Object.entries(parsed);
+  for (const [alias, p] of entries) {
+    if (!(p.input > 0) || !(p.output > p.input)) {
+      throw new Error(`implausible pricing for ${alias} ($${p.input} in / $${p.output} out) from ${src} — keeping current prices`);
+    }
+  }
+  const sigs = new Set(entries.map(([, p]) => `${p.input}/${p.output}`));
+  if (entries.length > 1 && sigs.size === 1) {
+    throw new Error(`all models parsed to the same price from ${src} — likely a bad parse; keeping current prices`);
+  }
+}
+
+// Write a refreshed pricing block into the installed policy file. Returns the path.
+export function writePricingToPolicy(pricing, policyPath = POLICY_PATH) {
+  if (!existsSync(policyPath)) throw new Error(`no installed policy at ${policyPath} — run "ultracost init" first`);
+  const policy = JSON.parse(readFileSync(policyPath, 'utf8'));
+  policy.pricing = pricing;
+  writeFileSync(policyPath, JSON.stringify(policy, null, 2) + '\n');
+  return policyPath;
+}