@mmerterden/multi-agent-pipeline 17.6.0 → 18.0.0

package/pipeline/scripts/cost-analyze.mjs

@@ -0,0 +1,600 @@
+#!/usr/bin/env node
+/**
+ * cost-analyze.mjs  -  what the spend is doing, not just what it was.
+ *
+ * cost-budget-check.mjs answers one question, live, for one run: is THIS task
+ * about to cross its ceiling. It cannot see a second run, yesterday, or a
+ * trend, so the two failures that actually empty a budget go unreported by it:
+ * a slow drift that never trips a per-task ceiling, and one pathological
+ * session that burns a week's worth in an hour while every individual run
+ * stays under its cap.
+ *
+ * Four questions, one series:
+ *   projection  -  at this rate, what does a week / a month / a quarter cost,
+ *                  and when does a stated budget run out
+ *   anomaly     -  which day or session is out of family, by median absolute
+ *                  deviation rather than by mean and standard deviation (one
+ *                  huge day inflates both and then hides itself)
+ *   burn        -  is the last 24h accelerating against the preceding week
+ *   diff        -  two saved snapshots, metric by metric
+ *
+ * WHERE THE NUMBERS COME FROM, and what that makes them worth: the per-run
+ * token accumulators in tracker-state.json are the pipeline's own ledger, but
+ * they are written only when a phase reports them, and on this machine no
+ * tracker carries them at all. The dense series that DOES exist is the host's
+ * own transcripts (~/.claude/projects/<slug>/<session>.jsonl), one usage record
+ * per assistant turn. So this reads those. Consequences, stated rather than
+ * buried: the figures cover everything Claude Code did on this machine, not
+ * only pipeline runs; they are ESTIMATES priced from cost-table.json, not an
+ * invoice; and a host with no such transcripts (Copilot, Codex) reports
+ * UNMEASURED rather than zero, because zero here would read as "you spent
+ * nothing" when it means "I could not see".
+ *
+ * Usage:
+ *   cost-analyze.mjs projection [--days N] [--monthly-usd N]
+ *   cost-analyze.mjs anomaly    [--days N] [--by day|session] [--threshold N]
+ *   cost-analyze.mjs burn       [--factor N]
+ *   cost-analyze.mjs diff       [a.json b.json]
+ *   cost-analyze.mjs --save                    store a snapshot
+ *   cost-analyze.mjs --list                    what is stored
+ *   any subcommand plus --json
+ *
+ * Exit codes:
+ *   0   nothing to report, or UNMEASURED (no series to read)
+ *   10  a finding: an anomaly, an accelerating burn, or a budget that the
+ *       current rate exhausts inside the projection window
+ *   2   usage error
+ */
+
+import {
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { costUsd } from "./_cost.mjs";
+import { runMain } from "../lib/fatal.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const STORE = process.env.COST_SNAPSHOT_STORE || join(homedir(), ".claude", "state", "cost");
+const TRANSCRIPT_ROOT = process.env.COST_TRANSCRIPT_ROOT || join(homedir(), ".claude", "projects");
+
+function die(msg) {
+  process.stderr.write(`cost-analyze: ${msg}\n`);
+  process.exit(2);
+}
+
+// --- argv --------------------------------------------------------------------
+
+// Flags that never take a value. Without this set, `--json projection` made the
+// sub-command the value of --json and left the parser with no sub-command at
+// all - so the natural order of the two words was a usage error.
+const BOOLEAN_FLAGS = new Set(["json", "save", "list"]);
+
+const argv = process.argv.slice(2);
+const positional = [];
+const flags = {};
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (!a.startsWith("--")) {
+    positional.push(a);
+    continue;
+  }
+  const [k, inline] = a.slice(2).split("=");
+  const next = argv[i + 1];
+  if (inline !== undefined) flags[k] = inline;
+  else if (BOOLEAN_FLAGS.has(k)) flags[k] = true;
+  else if (next !== undefined && !next.startsWith("--")) {
+    flags[k] = next;
+    i++;
+  } else flags[k] = true;
+}
+
+const asNumber = (v, fallback) => {
+  if (v === undefined || v === true) return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+// --- pricing -----------------------------------------------------------------
+
+const TABLE = JSON.parse(readFileSync(join(HERE, "cost-table.json"), "utf-8"));
+
+/**
+ * modelId -> rung. The transcripts carry the wire value ("claude-opus-5"); the
+ * price table is keyed by rung. Matching on modelId rather than on the rung
+ * name is what keeps a generation move a one-line data edit, which is the
+ * contract cost-table.json states for itself.
+ */
+const RUNG_BY_MODEL_ID = new Map(
+  Object.entries(TABLE.prices || {}).map(([rung, p]) => [p.modelId, rung]),
+);
+
+function rateFor(modelId) {
+  if (!modelId) return null;
+  const rung = RUNG_BY_MODEL_ID.get(modelId);
+  if (rung) return TABLE.prices[rung];
+  // A dated snapshot id (an alias plus a release date suffix) prices as its
+  // alias - written as a shape rather than as a literal, because
+  // smoke-model-fallback.sh reads every model id in this tree and requires it
+  // to exist in cost-table.json, and an EXAMPLE id is exactly the kind of thing
+  // that would make that gate wrong about what ships. An
+  // id nobody knows prices as nothing and is COUNTED as unpriced rather than
+  // folded in at zero.
+  for (const [id, rung] of RUNG_BY_MODEL_ID) {
+    if (modelId.startsWith(id)) return TABLE.prices[rung];
+  }
+  return null;
+}
+
+/**
+ * Cache WRITES are not a discount, they are a surcharge: Anthropic prices a
+ * 1h cache write above fresh input. cost-table.json carries cacheReadPerMtok
+ * only, so the write rate is derived here at the published 1.25x of input and
+ * labelled as derived - an unpriced component silently dropped would make
+ * every long-context session look cheap, which is the direction that hurts.
+ */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+
+function priceRecord(rate, u) {
+  const fresh = Number(u.input_tokens || 0);
+  const out = Number(u.output_tokens || 0);
+  const cacheRead = Number(u.cache_read_input_tokens || 0);
+  const cacheWrite = Number(u.cache_creation_input_tokens || 0);
+  const base = costUsd(rate, fresh, out, cacheRead);
+  if (base === null) return null;
+  return base + (cacheWrite / 1_000_000) * (rate.inPerMtok || 0) * CACHE_WRITE_MULTIPLIER;
+}
+
+// --- the series --------------------------------------------------------------
+
+function transcriptFiles(sinceMs) {
+  if (!existsSync(TRANSCRIPT_ROOT)) return [];
+  const out = [];
+  for (const slug of readdirSync(TRANSCRIPT_ROOT)) {
+    const dir = join(TRANSCRIPT_ROOT, slug);
+    let entries;
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = join(dir, f);
+      try {
+        // mtime is a cheap pre-filter, not the truth: a file touched today can
+        // hold last month's turns, and every record is date-checked below. It
+        // only skips files that CANNOT contain anything in the window.
+        if (sinceMs && statSync(p).mtimeMs < sinceMs) continue;
+      } catch {
+        continue;
+      }
+      out.push({ path: p, project: slug, session: f.replace(/\.jsonl$/, "") });
+    }
+  }
+  return out;
+}
+
+async function readSeries({ days }) {
+  const sinceMs = days ? Date.now() - days * 86_400_000 : 0;
+  const files = transcriptFiles(sinceMs);
+  const byDay = new Map();
+  const bySession = new Map();
+  const seen = new Set();
+  let records = 0;
+  let unpriced = 0;
+  const unpricedModels = new Set();
+
+  for (const f of files) {
+    let rl;
+    try {
+      rl = createInterface({ input: createReadStream(f.path), crlfDelay: Infinity });
+    } catch {
+      continue;
+    }
+    for await (const line of rl) {
+      if (!line || line.charCodeAt(0) !== 123) continue;
+      let d;
+      try {
+        d = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const msg = d.message;
+      const u = msg?.usage;
+      if (!u) continue;
+      const ts = Date.parse(d.timestamp || "");
+      if (!Number.isFinite(ts)) continue;
+      if (sinceMs && ts < sinceMs) continue;
+      // A retried or resumed turn can appear twice across transcripts; the
+      // message id is the only stable identity, and double counting is the
+      // failure mode a cost report can least afford.
+      const id = msg?.id;
+      if (id) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+      }
+      const rate = rateFor(msg?.model);
+      const usd = rate ? priceRecord(rate, u) : null;
+      if (usd === null) {
+        unpriced++;
+        if (msg?.model) unpricedModels.add(msg.model);
+        continue;
+      }
+      records++;
+      const day = new Date(ts).toISOString().slice(0, 10);
+      byDay.set(day, (byDay.get(day) || 0) + usd);
+      const key = `${f.project}/${f.session}`;
+      const s = bySession.get(key) || { usd: 0, first: ts, last: ts, project: f.project };
+      s.usd += usd;
+      s.first = Math.min(s.first, ts);
+      s.last = Math.max(s.last, ts);
+      bySession.set(key, s);
+    }
+  }
+
+  return {
+    files: files.length,
+    records,
+    unpriced,
+    unpricedModels: [...unpricedModels].sort(),
+    byDay: [...byDay.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)),
+    bySession: [...bySession.entries()].sort((a, b) => b[1].usd - a[1].usd),
+  };
+}
+
+const usd = (n) => `$${n.toFixed(2)}`;
+
+function unmeasured(reason, json) {
+  const payload = { kind: "UNMEASURED", reason };
+  if (json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else process.stdout.write(`UNMEASURED: ${reason}\n`);
+  process.exitCode = 0;
+}
+
+// --- statistics --------------------------------------------------------------
+
+function median(xs) {
+  if (!xs.length) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+/**
+ * Modified z-score (Iglewicz and Hoaglin): 0.6745 * (x - median) / MAD. Mean
+ * and standard deviation cannot be used here, because the single expensive
+ * session this is meant to find is also the observation that inflates both -
+ * it hides itself. The median and the MAD do not move for one outlier.
+ *
+ * MAD is zero whenever more than half the days are identical, which happens
+ * with very few days of data; the published fallback is the mean absolute
+ * deviation scaled by 1.253314. When that is zero too there is no dispersion
+ * at all, and the honest answer is that no anomaly CAN be called.
+ */
+function modifiedZ(xs) {
+  const med = median(xs);
+  const mad = median(xs.map((x) => Math.abs(x - med)));
+  if (mad > 0) return { med, scale: mad / 0.6745, basis: "MAD" };
+  const meanAbs = xs.reduce((a, x) => a + Math.abs(x - med), 0) / (xs.length || 1);
+  if (meanAbs > 0) return { med, scale: meanAbs * 1.253314, basis: "mean absolute deviation" };
+  return { med, scale: 0, basis: "none" };
+}
+
+// --- subcommands -------------------------------------------------------------
+
+async function cmdProjection(json) {
+  const days = asNumber(flags.days, 14);
+  const monthly = asNumber(flags["monthly-usd"], null);
+  const s = await readSeries({ days });
+  if (!s.byDay.length) return unmeasured(`no priced usage records in the last ${days} days`, json);
+
+  const total = s.byDay.reduce((a, [, v]) => a + v, 0);
+  // Divided by the CALENDAR window, not by the number of days that happen to
+  // have data: dividing by active days answers "what does a working day cost",
+  // which then projects a 30-day month as thirty working days and overstates
+  // the month by roughly a third.
+  const perDay = total / days;
+  const observedDays = s.byDay.length;
+  const proj = { 7: perDay * 7, 30: perDay * 30, 90: perDay * 90 };
+  let exhaustDays = null;
+  if (monthly !== null && perDay > 0) exhaustDays = monthly / perDay;
+
+  const finding = exhaustDays !== null && exhaustDays < 30;
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          kind: "projection",
+          windowDays: days,
+          observedDays,
+          totalUsd: Number(total.toFixed(4)),
+          perDayUsd: Number(perDay.toFixed(4)),
+          projectedUsd: {
+            d7: Number(proj[7].toFixed(2)),
+            d30: Number(proj[30].toFixed(2)),
+            d90: Number(proj[90].toFixed(2)),
+          },
+          monthlyBudgetUsd: monthly,
+          budgetExhaustedInDays: exhaustDays === null ? null : Number(exhaustDays.toFixed(1)),
+          unpricedRecords: s.unpriced,
+          unpricedModels: s.unpricedModels,
+          finding,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `son ${days} gun: ${usd(total)} (${observedDays} gunde kayit var) - gunluk ${usd(perDay)}\n` +
+        `  7 gun ${usd(proj[7])} - 30 gun ${usd(proj[30])} - 90 gun ${usd(proj[90])}\n`,
+    );
+    if (monthly === null)
+      process.stdout.write(
+        "  butce tukenme tarihi yok: --monthly-usd verilmedi, bu makinede aylik tavan tanimli degil\n",
+      );
+    else if (exhaustDays === null) process.stdout.write("  harcama yok, tukenme hesaplanamaz\n");
+    else
+      process.stdout.write(
+        `  ${usd(monthly)} aylik tavan bu hizda ${exhaustDays.toFixed(1)} gunde biter\n`,
+      );
+    if (s.unpriced)
+      process.stdout.write(
+        `  ${s.unpriced} kayit fiyatlanamadi (${s.unpricedModels.join(", ") || "model alani yok"}) - toplamin disinda\n`,
+      );
+    // Said every time, not in a footnote somebody reads once: on a subscription
+    // this figure is what the same tokens would have COST at list price, not
+    // what was paid. It is the right number for comparing days to each other
+    // and the wrong number to put in an invoice.
+    process.stdout.write("  (liste fiyatindan tahmin - abonelikte odenen tutar degil)\n");
+  }
+  if (finding) process.exitCode = 10;
+}
+
+async function cmdAnomaly(json) {
+  const days = asNumber(flags.days, 30);
+  const threshold = asNumber(flags.threshold, 3.5);
+  const by = flags.by === "session" ? "session" : "day";
+  const s = await readSeries({ days });
+  const rows =
+    by === "day"
+      ? s.byDay.map(([k, v]) => ({ key: k, usd: v }))
+      : s.bySession.map(([k, v]) => ({ key: k, usd: v.usd }));
+  if (rows.length < 5)
+    return unmeasured(
+      `${rows.length} ${by} of data in the last ${days} days; at least 5 are needed before an outlier means anything`,
+      json,
+    );
+
+  const { med, scale, basis } = modifiedZ(rows.map((r) => r.usd));
+  if (scale === 0)
+    return unmeasured(`every ${by} costs the same (${usd(med)}); no dispersion, no outlier`, json);
+
+  const scored = rows.map((r) => ({ ...r, z: (r.usd - med) / scale })).sort((a, b) => b.z - a.z);
+  const flagged = scored.filter((r) => r.z >= threshold);
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          kind: "anomaly",
+          by,
+          windowDays: days,
+          threshold,
+          basis,
+          medianUsd: Number(med.toFixed(4)),
+          flagged: flagged.map((r) => ({
+            key: r.key,
+            usd: Number(r.usd.toFixed(2)),
+            z: Number(r.z.toFixed(2)),
+          })),
+          top: scored
+            .slice(0, 3)
+            .map((r) => ({ key: r.key, usd: Number(r.usd.toFixed(2)), z: Number(r.z.toFixed(2)) })),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `${rows.length} ${by} - medyan ${usd(med)} - olcek ${basis} - esik z>=${threshold}\n`,
+    );
+    if (!flagged.length) process.stdout.write("  aile disinda kayit yok\n");
+    // Ten lines, then a count. Session spend is heavy-tailed - the median
+    // session is a few cents of question-answering and a real run is three
+    // orders of magnitude above it - so `--by session` legitimately flags
+    // dozens, and forty lines of flags is a list nobody finishes reading.
+    for (const r of flagged.slice(0, 10))
+      process.stdout.write(`  ! ${r.key}  ${usd(r.usd)}  z=${r.z.toFixed(1)}\n`);
+    if (flagged.length > 10)
+      process.stdout.write(`  ... ve ${flagged.length - 10} ${by} daha esigin uzerinde\n`);
+  }
+  if (flagged.length) process.exitCode = 10;
+}
+
+async function cmdBurn(json) {
+  const factor = asNumber(flags.factor, 3);
+  const s = await readSeries({ days: 8 });
+  // TODAY by the calendar, not "the last day that has data". Anchoring on the
+  // latest record meant a machine that spent nothing for five days kept
+  // reporting last Friday's spike as the current burn, with exit 10, every day,
+  // forever - an alarm that cannot turn itself off is one people turn off.
+  const todayKey = new Date().toISOString().slice(0, 10);
+  const todayRow = s.byDay.find(([d]) => d === todayKey);
+  if (!todayRow) return unmeasured(`no priced usage today (${todayKey}); nothing is burning`, json);
+  const priorRows = s.byDay.filter(([d]) => d !== todayKey);
+  if (priorRows.length < 2)
+    return unmeasured(
+      `only ${priorRows.length} prior day(s) of data; acceleration needs something to accelerate against`,
+      json,
+    );
+  // Divided by the prior days that EXIST rather than by a hard-coded 7: with
+  // three days of history, dividing by seven halves the baseline and doubles
+  // every ratio, which is the direction that invents findings.
+  const priorTotal = priorRows.reduce((a, [, v]) => a + v, 0);
+  const priorPerDay = priorTotal / priorRows.length;
+  const today = todayRow;
+  const ratio = priorPerDay > 0 ? today[1] / priorPerDay : null;
+  const finding = ratio !== null && ratio >= factor;
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          kind: "burn",
+          day: today[0],
+          dayUsd: Number(today[1].toFixed(2)),
+          priorPerDayUsd: Number(priorPerDay.toFixed(2)),
+          priorDays: priorRows.length,
+          ratio: ratio === null ? null : Number(ratio.toFixed(2)),
+          factor,
+          finding,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `${today[0]}: ${usd(today[1])} - onceki ${priorRows.length} gun gunluk ortalama ${usd(priorPerDay)}\n`,
+    );
+    if (ratio === null) process.stdout.write("  onceki pencerede harcama yok, oran hesaplanamaz\n");
+    else
+      process.stdout.write(
+        `  ${ratio.toFixed(1)}x ${finding ? `- esik ${factor}x asildi` : "- normal aralik"}\n`,
+      );
+  }
+  if (finding) process.exitCode = 10;
+}
+
+// --- snapshots ---------------------------------------------------------------
+
+function snapshots() {
+  if (!existsSync(STORE)) return [];
+  return readdirSync(STORE)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((f) => join(STORE, f));
+}
+
+async function cmdSave(json) {
+  const days = asNumber(flags.days, 30);
+  const s = await readSeries({ days });
+  const total = s.byDay.reduce((a, [, v]) => a + v, 0);
+  const snap = {
+    savedAt: new Date().toISOString(),
+    windowDays: days,
+    totalUsd: Number(total.toFixed(4)),
+    perDayUsd: Number((total / days).toFixed(4)),
+    observedDays: s.byDay.length,
+    records: s.records,
+    unpriced: s.unpriced,
+    byDay: Object.fromEntries(s.byDay.map(([k, v]) => [k, Number(v.toFixed(4))])),
+  };
+  mkdirSync(STORE, { recursive: true });
+  const path = join(STORE, `${snap.savedAt.replace(/[:.]/g, "-")}.json`);
+  writeFileSync(path, `${JSON.stringify(snap, null, 2)}\n`);
+  if (json) process.stdout.write(`${JSON.stringify({ saved: path, ...snap }, null, 2)}\n`);
+  else
+    process.stdout.write(
+      `kaydedildi: ${path}\n  son ${days} gun ${usd(snap.totalUsd)} - gunluk ${usd(snap.perDayUsd)}\n`,
+    );
+}
+
+function cmdList(json) {
+  const files = snapshots();
+  if (json)
+    process.stdout.write(`${JSON.stringify({ store: STORE, snapshots: files }, null, 2)}\n`);
+  else {
+    process.stdout.write(`${STORE}\n`);
+    if (!files.length) process.stdout.write("  (bos)\n");
+    for (const f of files) {
+      const d = JSON.parse(readFileSync(f, "utf-8"));
+      process.stdout.write(`  ${d.savedAt}  ${usd(d.totalUsd)} / ${d.windowDays} gun\n`);
+    }
+  }
+}
+
+function cmdDiff(json) {
+  // positional[0] is the sub-command. Dropping it matters: with `diff a.json`
+  // the old form took the last two entries, which were "diff" and "a.json",
+  // and died with `snapshot not found: diff`.
+  const paths = positional.slice(1);
+  let a;
+  let b;
+  if (paths.length === 2) [a, b] = paths;
+  else if (paths.length === 0) {
+    const files = snapshots();
+    if (files.length < 2) die("need two snapshots; run --save at least twice");
+    [a, b] = files.slice(-2);
+  } else {
+    die(`diff takes two snapshot paths or none; got ${paths.length}`);
+  }
+  for (const p of [a, b]) if (!existsSync(p)) die(`snapshot not found: ${p}`);
+  const A = JSON.parse(readFileSync(a, "utf-8"));
+  const B = JSON.parse(readFileSync(b, "utf-8"));
+  const delta = B.perDayUsd - A.perDayUsd;
+  const pct = A.perDayUsd > 0 ? (delta / A.perDayUsd) * 100 : null;
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          kind: "diff",
+          from: { path: a, savedAt: A.savedAt, perDayUsd: A.perDayUsd, windowDays: A.windowDays },
+          to: { path: b, savedAt: B.savedAt, perDayUsd: B.perDayUsd, windowDays: B.windowDays },
+          deltaPerDayUsd: Number(delta.toFixed(4)),
+          deltaPct: pct === null ? null : Number(pct.toFixed(1)),
+          comparable: A.windowDays === B.windowDays,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(`${A.savedAt} -> ${B.savedAt}\n`);
+    process.stdout.write(
+      `  gunluk ${usd(A.perDayUsd)} -> ${usd(B.perDayUsd)}  (${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${
+        pct === null ? "" : `, ${pct >= 0 ? "+" : ""}${pct.toFixed(0)}%`
+      })\n`,
+    );
+    if (A.windowDays !== B.windowDays)
+      process.stdout.write(
+        `  ! pencereler farkli (${A.windowDays} / ${B.windowDays} gun) - gunluk oran karsilastirilabilir, toplam degil\n`,
+      );
+  }
+}
+
+// --- main --------------------------------------------------------------------
+
+const json = flags.json === true || flags.json === "true";
+const sub = positional[0];
+
+const run = async () => {
+  if (flags.save) return cmdSave(json);
+  if (flags.list) return cmdList(json);
+  switch (sub) {
+    case "projection":
+      return cmdProjection(json);
+    case "anomaly":
+      return cmdAnomaly(json);
+    case "burn":
+      return cmdBurn(json);
+    case "diff":
+      return cmdDiff(json);
+    default:
+      return die("usage: cost-analyze.mjs projection|anomaly|burn|diff [--json] | --save | --list");
+  }
+};
+
+runMain("cost-analyze", run, { code: 2 });

package/pipeline/scripts/cost-budget-check.mjs

@@ -13,7 +13,8 @@
  * coding tool; this turns "will this burn my tokens?" into a visible number.
  *
  * Inputs (CLI overrides prefs):
- *   --task-id <id>        Locate $HOME/.claude/logs/multi-agent/<id>/tracker-state.json
+ *   --task-id <id>        Locate the run's tracker-state.json via _run-paths.mjs
+ *                         (both layouts, every id spelling)
  *                         (also tried: <id> without a leading #, task-<id>)
  *   --tracker  <path>     Explicit tracker JSON (skips lookup)
  *   --prefs    <path>     Preferences JSON; reads .global.costBudget
@@ -35,9 +36,9 @@
 
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
-import { homedir } from "os";
 import { fileURLToPath } from "url";
 import { costUsd } from "./_cost.mjs";
+import { resolveRunFile } from "./_run-paths.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -105,16 +106,7 @@ function resolveTracker() {
   }
   const id = flags["task-id"];
   if (!id) die("either --tracker or --task-id is required");
-  const bare = String(id).replace(/^#/, "");
-  const logRoot = join(homedir(), ".claude", "logs", "multi-agent");
-  for (const c of [
-    join(logRoot, String(id), "tracker-state.json"),
-    join(logRoot, bare, "tracker-state.json"),
-    join(logRoot, `task-${bare}`, "tracker-state.json"),
-  ]) {
-    if (existsSync(c)) return c;
-  }
-  return null;
+  return resolveRunFile(id, "tracker-state.json", flags.project);
 }
 
 const trackerPath = resolveTracker();

package/pipeline/scripts/council-view.mjs

@@ -21,6 +21,7 @@
 // Exit codes: 0 rendered, 2 nothing to render (no review iterations), 64 usage.
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const argv = process.argv.slice(2);
 const JSON_OUT = argv.includes("--json");
@@ -141,4 +142,4 @@ function main() {
   process.stdout.write(lines.join("\n"));
 }
 
-main();
+runMain("council-view", main);

package/pipeline/scripts/crush-json.mjs

@@ -53,6 +53,7 @@
  */
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const argv = process.argv.slice(2);
 const STATS = argv.includes("--stats");
@@ -280,4 +281,4 @@ function main() {
   return emit(out, "crushed");
 }
 
-main();
+runMain("crush-json", main);

package/pipeline/scripts/diff-explain.mjs

@@ -31,9 +31,8 @@
  */
 
 import { readFileSync, existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
 import { execFileSync } from "child_process";
+import { resolveRunFile, taskIdVariants, logsRoot } from "./_run-paths.mjs";
 
 const argv = process.argv.slice(2);
 const flags = {};
@@ -71,14 +70,12 @@ Output:
 }
 
 function resolveStateByTaskId(id) {
-  const bare = String(id).replace(/^#/, "");
-  const logRoot = join(homedir(), ".claude", "logs", "multi-agent");
-  const candidates = [...new Set([String(id), bare, `task-${bare}`])].map((d) =>
-    join(logRoot, d, "agent-state.json"),
-  );
-  const found = candidates.find((p) => existsSync(p));
+  const found = resolveRunFile(id, "agent-state.json", flags.project);
   if (!found)
-    die(`no agent-state.json for task ${id} under ${logRoot} (tried ${candidates.join(", ")})`);
+    die(
+      `no agent-state.json for task ${id} under ${logsRoot()} ` +
+        `(tried ${taskIdVariants(id).join(", ")} in both layouts)`,
+    );
   return found;
 }