@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/lib/telemetry/collect.test.mjs

@@ -24,6 +24,11 @@ import {
   parsePowermetrics,
   parseDf,
   collectMachine,
+  collectPowermetrics,
+  powermetricsSamplers,
+  parseSystemProfilerHardware,
+  ramLabel,
+  collectSpend24h,
   _internals,
 } from "./collect.mjs";
 
@@ -200,3 +205,264 @@ test("execFileSafe resolves '' on a throwing exec impl (no reject)", async () =>
   const out = await _internals.execFileSafe(() => { throw new Error("nope"); }, "x", [], 50);
   assert.equal(out, "");
 });
+
+// ---------------------------------------------------------------------------
+// The Fleet telemetry vocabulary — the fields the hq Fleet row reads by name.
+//
+// These four (device / ram / uptimeDays / spend24h) were READ by
+// hq/src/components/fleet/machine.ts#buildFleetMachine and emitted by NOTHING,
+// while four others (loadavg / memUsedPct / cpuPct / diskUsedPct) were emitted
+// here and read by nothing. The intersection in production was EMPTY, so the
+// Fleet view em-dashed every hardware column on the one machine that was
+// genuinely alive. These tests pin the producer half of that contract.
+// ---------------------------------------------------------------------------
+
+const SP_HARDWARE = [
+  "Hardware:",
+  "    Hardware Overview:",
+  "      Model Name: Mac mini",
+  "      Model Identifier: Mac16,11",
+  "      Chip: Apple M4 Pro",
+  "      Total Number of Cores: 12 (8 performance and 4 efficiency)",
+  "      Memory: 24 GB",
+  "",
+].join("\n");
+
+test("collectMachine emits the INVENTORY the Fleet row reads: device, ram, cores", async () => {
+  const m = await collectMachine({
+    os: fakeOs({ totalmem: 24 * 1024 ** 3, freemem: 2e9, cpus: 12 }),
+    execFile: fakeExecFile({ "/usr/sbin/system_profiler": SP_HARDWARE }),
+    powermetrics: false,
+    disk: false,
+    spend: false,
+  });
+  assert.equal(m.device, "Mac mini M4 Pro");
+  assert.equal(m.ram, "24 GB");
+  assert.equal(m.cores, 12);
+});
+
+test("collectMachine falls back to node:os inventory when system_profiler yields nothing", async () => {
+  const m = await collectMachine({
+    os: {
+      loadavg: () => [1, 1, 1],
+      totalmem: () => 24 * 1024 ** 3,
+      freemem: () => 12 * 1024 ** 3,
+      cpus: () => new Array(12).fill({ model: "Apple M4 Pro" }),
+      platform: () => "darwin",
+      uptime: () => 0,
+    },
+    execFile: fakeExecFile({}), // system_profiler returns ""
+    powermetrics: false,
+    disk: false,
+    spend: false,
+  });
+  // Never nothing: node:os alone still proves the chip, the RAM and the cores.
+  assert.equal(m.device, "Apple M4 Pro");
+  assert.equal(m.ram, "24 GB");
+  assert.equal(m.cores, 12);
+});
+
+test("collectMachine emits uptimeDays", async () => {
+  const osImpl = fakeOs({});
+  osImpl.uptime = () => 5756923; // ~66.6 days
+  const m = await collectMachine({
+    os: osImpl, powermetrics: false, disk: false, inventory: false, spend: false,
+  });
+  assert.equal(m.uptimeDays, 66.6);
+});
+
+test("ramLabel renders binary GB the way the spec sheet does", () => {
+  assert.equal(ramLabel(24 * 1024 ** 3), "24 GB");
+  assert.equal(ramLabel(192 * 1024 ** 3), "192 GB");
+  assert.equal(ramLabel(8 * 1024 ** 3), "8 GB");
+  assert.equal(ramLabel(0), "");
+  assert.equal(ramLabel("nonsense"), "");
+});
+
+test("parseSystemProfilerHardware is a tolerant pure parser", () => {
+  assert.deepEqual(parseSystemProfilerHardware(SP_HARDWARE), {
+    device: "Mac mini M4 Pro",
+    ram: "24 GB",
+    cores: 12,
+  });
+  // Partial output degrades field-by-field rather than throwing.
+  assert.deepEqual(parseSystemProfilerHardware("      Memory: 16 GB\n"), { ram: "16 GB" });
+  assert.deepEqual(parseSystemProfilerHardware(""), {});
+  assert.deepEqual(parseSystemProfilerHardware(null), {});
+});
+
+// ---------------------------------------------------------------------------
+// tempC — the sampler bug, and the rule that a failure is never silent
+// ---------------------------------------------------------------------------
+
+test("powermetricsSamplers uses the arm64 spelling — 'smc' is Intel-only", () => {
+  // The shipped constant was "smc,cpu_power" unconditionally. On Apple Silicon
+  // powermetrics rejects that argument list outright and exits non-zero BEFORE
+  // the root check, so the probe was unreachable on every machine in the fleet.
+  assert.equal(powermetricsSamplers("arm64"), "thermal,cpu_power");
+  assert.equal(powermetricsSamplers("x64"), "smc,cpu_power");
+});
+
+test("collectPowermetrics passes the arch-correct sampler to the binary", async () => {
+  const seen = [];
+  const spy = (cmd, args, optsOrCb, maybeCb) => {
+    const cb = typeof optsOrCb === "function" ? optsOrCb : maybeCb;
+    seen.push({ cmd, args });
+    queueMicrotask(() => cb(null, "CPU die temperature: 54.2 C\n", ""));
+    return { on() {} };
+  };
+  const pm = await collectPowermetrics({ execFile: spy, platform: "darwin", arch: "arm64" });
+  assert.equal(pm.tempC, 54.2);
+  assert.equal(pm.source, "powermetrics");
+  const samplerArg = seen[0].args[seen[0].args.indexOf("--samplers") + 1];
+  assert.equal(samplerArg, "thermal,cpu_power");
+  assert.ok(!samplerArg.includes("smc"), "must not send the Intel-only sampler to arm64");
+});
+
+test("collectPowermetrics ALWAYS says why it has no temperature (fail-open, never silent)", async () => {
+  // The unprivileged reality on every seat: the probe yields nothing.
+  const pm = await collectPowermetrics({
+    execFile: fakeExecFile({}), platform: "darwin", arch: "arm64", sudoPowermetrics: false,
+  });
+  assert.equal(pm.tempC, undefined);
+  assert.match(pm.detail, /requires root/);
+  assert.match(pm.detail, /TELEMETRY_SUDO_POWERMETRICS/);
+
+  // A non-darwin host is a DIFFERENT absence and says so.
+  const linux = await collectPowermetrics({ platform: "linux" });
+  assert.match(linux.detail, /platform linux/);
+});
+
+test("collectMachine surfaces the temperature failure as machine.tempDetail", async () => {
+  const m = await collectMachine({
+    os: fakeOs({}),
+    execFile: fakeExecFile({}),
+    platform: "darwin",
+    arch: "arm64",
+    sudoPowermetrics: false,
+    disk: false,
+    inventory: false,
+    spend: false,
+  });
+  assert.equal(m.tempC, undefined);
+  assert.equal(m.tempSource, undefined);
+  assert.match(m.tempDetail, /requires root/);
+  // And the cpuPct it DOES have is labelled as the estimate it is.
+  assert.equal(m.cpuSource, "loadavg");
+});
+
+test("collectPowermetrics tries the opt-in sudo path only when enabled", async () => {
+  const seen = [];
+  const spy = (cmd, args, optsOrCb, maybeCb) => {
+    const cb = typeof optsOrCb === "function" ? optsOrCb : maybeCb;
+    seen.push(cmd);
+    // Only the sudo invocation yields.
+    const out = cmd === "/usr/bin/sudo" ? "CPU die temperature: 61.0 C\n" : "";
+    queueMicrotask(() => cb(null, out, ""));
+    return { on() {} };
+  };
+  const off = await collectPowermetrics({
+    execFile: spy, platform: "darwin", arch: "arm64", sudoPowermetrics: false,
+  });
+  assert.equal(off.tempC, undefined, "must not shell out to sudo unless asked");
+  assert.ok(!seen.includes("/usr/bin/sudo"));
+
+  seen.length = 0;
+  const on = await collectPowermetrics({
+    execFile: spy, platform: "darwin", arch: "arm64", sudoPowermetrics: true,
+  });
+  assert.equal(on.tempC, 61);
+  assert.equal(on.source, "sudo-powermetrics");
+  assert.ok(seen.includes("/usr/bin/sudo"));
+  // `-n` so a machine with no NOPASSWD rule fails instantly instead of hanging
+  // the beat on a password prompt nobody will ever see.
+  const sudoCall = seen.indexOf("/usr/bin/sudo");
+  assert.ok(sudoCall >= 0);
+});
+
+// ---------------------------------------------------------------------------
+// spend24h
+// ---------------------------------------------------------------------------
+
+test("collectSpend24h sums BILLABLE rows in a true rolling 24h window", () => {
+  const root = mkdtempSync(join(tmpdir(), "spend-"));
+  try {
+    const dir = join(root, "state", "cost-tracking");
+    mkdirSync(dir, { recursive: true });
+    const now = Date.parse("2026-08-13T06:00:00Z");
+    const row = (ts, cost) => JSON.stringify({
+      ts, model: "claude-opus-4-5", input_tokens: 10, output_tokens: 5, total_cost_usd: cost,
+    });
+    // Yesterday's file: one row inside the window, one outside it.
+    writeFileSync(join(dir, "2026-08-12.jsonl"), [
+      row("2026-08-12T05:00:00Z", 1.5),  // 25h ago — OUTSIDE
+      row("2026-08-12T07:00:00Z", 2.25), // 23h ago — inside
+    ].join("\n") + "\n");
+    writeFileSync(join(dir, "2026-08-13.jsonl"), [
+      row("2026-08-13T01:00:00Z", 0.75),
+      // A non-LLM attribution row: $0 is a FACT (no model ran), not an absence.
+      JSON.stringify({ ts: "2026-08-13T02:00:00Z", model: null, task_class: "messaging.send", total_cost_usd: null, estimated_usd: 0 }),
+    ].join("\n") + "\n");
+
+    assert.equal(collectSpend24h({ agentRoot: root, now }), 3);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("collectSpend24h: no ledger is UNDEFINED, not a confident zero", () => {
+  assert.equal(collectSpend24h({ agentRoot: "/nonexistent-root-xyz" }), undefined);
+  assert.equal(collectSpend24h({}), undefined);
+});
+
+test("collectSpend24h does not count an UNMEASURED row as free", () => {
+  const root = mkdtempSync(join(tmpdir(), "spend2-"));
+  try {
+    const dir = join(root, "state", "cost-tracking");
+    mkdirSync(dir, { recursive: true });
+    const now = Date.parse("2026-08-13T06:00:00Z");
+    writeFileSync(join(dir, "2026-08-13.jsonl"), [
+      // measurement:"unknown" → billableUsd().usd === null. Skipped, not zeroed.
+      JSON.stringify({ ts: "2026-08-13T01:00:00Z", model: "claude-opus-4-5", measurement: "unknown", input_tokens: null, output_tokens: null, total_cost_usd: null }),
+      JSON.stringify({ ts: "2026-08-13T02:00:00Z", model: "claude-opus-4-5", input_tokens: 1, output_tokens: 1, total_cost_usd: 4.5 }),
+      "{ not json",
+    ].join("\n") + "\n");
+    assert.equal(collectSpend24h({ agentRoot: root, now }), 4.5);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("collectStatus ships the FULL machine vocabulary the Fleet row reads", async () => {
+  const root = mkdtempSync(join(tmpdir(), "vocab-"));
+  try {
+    const osImpl = fakeOs({ totalmem: 24 * 1024 ** 3, freemem: 1e9, loadavg: [1.26, 1.2, 1.08], cpus: 12 });
+    osImpl.uptime = () => 5756923;
+    const status = await collectStatus({
+      agentRoot: root,
+      now: Date.parse("2026-08-13T06:00:00Z"),
+      os: osImpl,
+      arch: "arm64",
+      sudoPowermetrics: false,
+      execFile: fakeExecFile({
+        "/usr/sbin/system_profiler": SP_HARDWARE,
+        "/bin/df": "Filesystem 1024-blocks Used Available Capacity Mounted\n/dev/disk1 100 47 53 47% /\n",
+      }),
+      subAgentsRunning: 0,
+    });
+    const m = status.machine;
+    // The five keys hq reads that this collector used to emit NONE of.
+    assert.equal(m.device, "Mac mini M4 Pro");
+    assert.equal(m.ram, "24 GB");
+    assert.equal(m.uptimeDays, 66.6);
+    assert.equal(typeof m.tempDetail, "string"); // tempC needs root; the REASON ships
+    // The four it emitted that hq used to read NONE of.
+    assert.deepEqual(m.loadavg, [1.26, 1.2, 1.08]);
+    assert.ok(m.memUsedPct > 90);
+    assert.equal(typeof m.cpuPct, "number");
+    assert.equal(m.diskUsedPct, 47);
+    assert.equal(m.cpuSource, "loadavg");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/cost/track-claude-usage.mjs

@@ -10,38 +10,103 @@
  *
  *       node scripts/cost/track-claude-usage.mjs record \
  *         --cadence inbox-processor --model sonnet --duration-ms 12345 \
- *         --input-tokens 1500 --output-tokens 320 --exit 0
+ *         --input-tokens 1500 --output-tokens 320 \
+ *         --cache-read-tokens 553181 --cache-creation-tokens 7800 \
+ *         --total-cost-usd 0.533412 --exit 0
+ *
+ *     A caller that ran a session but could NOT read its usage must say so:
+ *
+ *       node scripts/cost/track-claude-usage.mjs record \
+ *         --cadence inbox --source dispatcher --tokens-unknown no-usage-field
+ *
+ *     That writes measurement:"unknown" with NULL tokens. It must never write
+ *     zeros — see "MEASURED, UNKNOWN, N/A" below.
  *
  *  2. `summarise` — Rollup the last N days into state/dashboards/cost-summary.yaml.
  *     Called daily (cadence: nightly-cost-rollup) and on demand.
  *
  *       node scripts/cost/track-claude-usage.mjs summarise --days 7
  *
- * Token-cost estimation uses a static price table (./pricing.json if present,
- * otherwise sensible defaults). Numbers are estimates — the source of truth
- * for billing is the Anthropic console. Goal here is local observability,
- * not exact accounting.
+ * MEASURED, UNKNOWN, N/A
+ * ----------------------
+ * Every row carries `measurement`. The old behaviour — `Number(flags[x] || 0)`
+ * — turned an ABSENT token flag into a literal 0, so "we didn't measure this
+ * session" and "this session used no tokens" wrote identical rows. The budget
+ * governor summed both as $0 and could never trip. Absent flags now produce
+ * null tokens + measurement:"unknown" + an `unmeasured_reason`, and every
+ * reader (lib/cost/ledger-row.mjs) treats that as UNKNOWN, not free.
+ *
+ * PRICING
+ * -------
+ * `total_cost_usd` from the `claude --output-format json` envelope is the
+ * authoritative figure and is what readers bill against. The local table is a
+ * FALLBACK for when the envelope lacks it. It is cache-tier aware, because on
+ * this workload cache reads are ~99% of prompt tokens: a real row reads
+ * input_tokens:16 / cache_read:553181, and a cache-blind table priced that
+ * session at $0.075 against an actual $0.533. Rates are USD per MILLION tokens
+ * (Anthropic's own unit — the old table was per-1K and had drifted stale);
+ * cache reads bill at 0.1x input and 5-minute cache writes at 1.25x input.
  */
 
 import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { billableUsd, summariseRows } from "../../lib/cost/ledger-row.mjs";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
 const LEDGER_DIR = join(AGENT_DIR, "state/cost-tracking");
 
-// Default pricing (USD per 1K tokens). Update when Anthropic changes prices.
+// Default pricing (USD per MILLION tokens). Update when Anthropic changes
+// prices. cache_read = 0.1x input, cache_write (5m TTL, what the CLI uses) =
+// 1.25x input — derived rather than hand-listed so the ratios can't drift apart.
+const MTOK = 1e6;
+const CACHE_READ_MULTIPLIER = 0.1;
+const CACHE_WRITE_MULTIPLIER = 1.25;
 const DEFAULT_PRICES = {
-  opus:   { input: 0.015,  output: 0.075 },
-  sonnet: { input: 0.003,  output: 0.015 },
-  haiku:  { input: 0.0008, output: 0.004 },
+  opus:   { input: 5, output: 25 },
+  sonnet: { input: 3, output: 15 },
+  haiku:  { input: 1, output: 5 },
 };
 const PRICING_FILE = join(__dirname, "pricing.json");
 function loadPrices() {
   if (!existsSync(PRICING_FILE)) return DEFAULT_PRICES;
-  try { return { ...DEFAULT_PRICES, ...JSON.parse(readFileSync(PRICING_FILE, "utf-8")) }; }
-  catch { return DEFAULT_PRICES; }
+  try {
+    const raw = JSON.parse(readFileSync(PRICING_FILE, "utf-8"));
+    const merged = { ...DEFAULT_PRICES };
+    for (const [model, p] of Object.entries(raw || {})) {
+      if (!p || typeof p !== "object") continue;
+      const input = Number(p.input);
+      const output = Number(p.output);
+      if (!Number.isFinite(input) || !Number.isFinite(output)) continue;
+      // Unit guard: this table was per-1K until the cache-tier fix and an
+      // operator's pricing.json may still be in the old unit. No Claude model
+      // costs under $0.10/MTok, so a sub-0.10 input rate is per-1K — rescale
+      // rather than silently under-price the day by 1000x.
+      const perThousand = input < 0.1;
+      merged[model] = perThousand
+        ? { input: input * 1000, output: output * 1000, unit_rescaled: true }
+        : { input, output };
+    }
+    return merged;
+  } catch { return DEFAULT_PRICES; }
+}
+
+/**
+ * Price a session from token counts. FALLBACK ONLY — readers prefer the CLI's
+ * authoritative total_cost_usd (see lib/cost/ledger-row.mjs). Token semantics
+ * follow the Anthropic usage envelope: `input_tokens` is the UNCACHED remainder,
+ * with cache reads and cache writes counted separately (not a subset of it).
+ */
+function estimateUsd(model, { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }) {
+  const prices = loadPrices()[model] || DEFAULT_PRICES.sonnet;
+  const usd =
+    (inputTokens / MTOK) * prices.input +
+    (outputTokens / MTOK) * prices.output +
+    (cacheReadTokens / MTOK) * prices.input * CACHE_READ_MULTIPLIER +
+    (cacheWriteTokens / MTOK) * prices.input * CACHE_WRITE_MULTIPLIER;
+  return +usd.toFixed(6);
 }
 
 function todayUtc() { return new Date().toISOString().slice(0, 10); }
@@ -59,38 +124,94 @@ function parseFlags(argv) {
   return flags;
 }
 
+/** Read a numeric flag. Returns null when ABSENT — never coerces absence to 0. */
+function numFlag(flags, name) {
+  const raw = flags[name];
+  if (raw == null || raw === "true") return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
 function recordCmd(flags) {
   mkdirSync(LEDGER_DIR, { recursive: true });
+
+  // --tokens-unknown <reason> is the explicit "a session ran, we could not read
+  // its usage" marker. A caller that has no counts MUST pass it; the absence of
+  // token flags alone is also treated as unknown (below) so an un-migrated
+  // caller degrades loudly instead of writing a false $0.
+  const unknownFlag = flags["tokens-unknown"];
+  const inputTokens = numFlag(flags, "input-tokens");
+  const outputTokens = numFlag(flags, "output-tokens");
+  // --non-llm marks an attribution row for work that invoked no model at all
+  // (a message send). $0 is a fact there, not a measurement gap.
+  const nonLlm = flags["non-llm"] != null;
+
+  let measurement = "measured";
+  let unmeasuredReason = null;
+  if (nonLlm) {
+    measurement = "n/a";
+  } else if (unknownFlag != null || (inputTokens === null && outputTokens === null)) {
+    measurement = "unknown";
+    unmeasuredReason =
+      typeof unknownFlag === "string" && unknownFlag !== "true"
+        ? unknownFlag
+        : "caller-passed-no-token-counts";
+  }
+
   const row = {
     ts: new Date().toISOString(),
     cadence: flags.cadence || "unknown",
     source: flags.source || "cadence-consumer",
-    model: (flags.model || "sonnet").toLowerCase(),
-    duration_ms: Number(flags["duration-ms"] || 0),
-    input_tokens: Number(flags["input-tokens"] || 0),
-    output_tokens: Number(flags["output-tokens"] || 0),
+    model: measurement === "n/a" ? null : (flags.model || "sonnet").toLowerCase(),
+    duration_ms: numFlag(flags, "duration-ms") ?? 0,
+    // NULL, not 0, when unmeasured. This single distinction is what lets the
+    // budget governor tell "cheap day" from "blind day".
+    input_tokens: measurement === "measured" ? (inputTokens ?? 0) : (measurement === "n/a" ? 0 : null),
+    output_tokens: measurement === "measured" ? (outputTokens ?? 0) : (measurement === "n/a" ? 0 : null),
     exit_code: Number(flags.exit ?? 0),
+    measurement,
   };
-  // Cache-read tokens (when the CLI reports them) are billed at a discount, but
-  // we record them for observability without folding them into estimated_usd —
-  // the static price table has no cache tier, and budget-guard sums
-  // estimated_usd, so keep that field token-derived and stable.
-  if (flags["cache-read-tokens"] != null) {
-    row.cache_read_input_tokens = Number(flags["cache-read-tokens"] || 0);
-  }
-  const prices = loadPrices()[row.model] || DEFAULT_PRICES.sonnet;
-  row.estimated_usd = +((row.input_tokens / 1000) * prices.input + (row.output_tokens / 1000) * prices.output).toFixed(6);
-  // When the caller has the CLI-reported authoritative cost (total_cost_usd from
-  // `claude --print --output-format json`), store it alongside the estimate for
-  // reconciliation. We deliberately DO NOT use it as estimated_usd: budget-guard
-  // sums estimated_usd, and the shared contract keeps that token-derived.
-  if (flags["total-cost-usd"] != null) {
-    const tc = Number(flags["total-cost-usd"]);
-    if (Number.isFinite(tc) && tc >= 0) row.total_cost_usd = +tc.toFixed(6);
+  if (unmeasuredReason) row.unmeasured_reason = unmeasuredReason;
+  if (flags["decision-id"]) row.decision_id = String(flags["decision-id"]);
+
+  if (measurement === "measured") {
+    // Cache tokens are billed at their own rates (read 0.1x, write 1.25x) and
+    // dominate this workload — record them and PRICE them.
+    const cacheRead = numFlag(flags, "cache-read-tokens") ?? 0;
+    const cacheWrite = numFlag(flags, "cache-creation-tokens") ?? 0;
+    row.cache_read_input_tokens = cacheRead;
+    row.cache_creation_input_tokens = cacheWrite;
+    row.estimated_usd = estimateUsd(row.model, {
+      inputTokens: row.input_tokens,
+      outputTokens: row.output_tokens,
+      cacheReadTokens: cacheRead,
+      cacheWriteTokens: cacheWrite,
+    });
+    // The CLI's own figure. Readers bill against THIS when present: it accounts
+    // for cache tiers, resolved model and account pricing that no local table
+    // tracks. estimated_usd stays alongside it as the reconciliation fallback.
+    const tc = numFlag(flags, "total-cost-usd");
+    if (tc !== null && tc >= 0) row.total_cost_usd = +tc.toFixed(6);
+  } else if (measurement === "n/a") {
+    row.estimated_usd = 0;
+    row.total_cost_usd = 0;
+  } else {
+    // Unmeasured: no cost claim at all. Readers must not read these as free.
+    row.estimated_usd = null;
+    row.total_cost_usd = null;
   }
+
   const file = join(LEDGER_DIR, `${todayUtc()}.jsonl`);
   appendFileSync(file, JSON.stringify(row) + "\n");
-  process.stdout.write(JSON.stringify({ ok: true, file, estimated_usd: row.estimated_usd }) + "\n");
+  const { usd, basis } = billableUsd(row);
+  if (measurement === "unknown") {
+    // Loud on stderr: a caller that cannot measure its own session is a defect,
+    // and this is the only place that observes it at write time.
+    process.stderr.write(
+      `[track-claude-usage] UNMEASURED session recorded (source=${row.source} cadence=${row.cadence} reason=${unmeasuredReason}) — spend for this session is unknown, not zero\n`
+    );
+  }
+  process.stdout.write(JSON.stringify({ ok: true, file, measurement, billable_usd: usd, basis }) + "\n");
 }
 
 function summariseCmd(flags) {
@@ -103,6 +224,7 @@ function summariseCmd(flags) {
   const totals = empty();
   const byModel = {};
   const byCadence = {};
+  const windowRows = [];
   for (const name of readdirSync(LEDGER_DIR)) {
     if (!name.endsWith(".jsonl")) continue;
     let body;
@@ -112,26 +234,63 @@ function summariseCmd(flags) {
       let row;
       try { row = JSON.parse(line); } catch { continue; }
       if (new Date(row.ts).getTime() < cutoff) continue;
-      totals.sessions += 1;
-      totals.input_tokens += row.input_tokens || 0;
-      totals.output_tokens += row.output_tokens || 0;
-      totals.estimated_usd = +(totals.estimated_usd + (row.estimated_usd || 0)).toFixed(6);
-      byModel[row.model] = byModel[row.model] || empty();
-      byModel[row.model].sessions += 1;
-      byModel[row.model].input_tokens += row.input_tokens || 0;
-      byModel[row.model].output_tokens += row.output_tokens || 0;
-      byModel[row.model].estimated_usd = +(byModel[row.model].estimated_usd + (row.estimated_usd || 0)).toFixed(6);
-      byCadence[row.cadence] = byCadence[row.cadence] || empty();
-      byCadence[row.cadence].sessions += 1;
-      byCadence[row.cadence].input_tokens += row.input_tokens || 0;
-      byCadence[row.cadence].output_tokens += row.output_tokens || 0;
-      byCadence[row.cadence].estimated_usd = +(byCadence[row.cadence].estimated_usd + (row.estimated_usd || 0)).toFixed(6);
+      windowRows.push(row);
+      const { usd, basis } = billableUsd(row);
+      // Non-LLM attribution rows are not sessions; unmeasured ones are sessions
+      // whose cost we do not know. Neither may be folded into a spend total as
+      // though it were a measured $0.
+      if (basis === "non_llm" || basis === "invalid") continue;
+      const key = row.model || "unknown";
+      const cad = row.cadence || "unknown";
+      byModel[key] = byModel[key] || empty();
+      byCadence[cad] = byCadence[cad] || empty();
+      for (const bucket of [totals, byModel[key], byCadence[cad]]) {
+        bucket.sessions += 1;
+        if (basis === "unmeasured") { bucket.unmeasured_sessions += 1; continue; }
+        bucket.input_tokens += row.input_tokens || 0;
+        bucket.output_tokens += row.output_tokens || 0;
+        bucket.cache_read_tokens += row.cache_read_input_tokens || row.cache_read_tokens || 0;
+        bucket.billable_usd = +(bucket.billable_usd + usd).toFixed(6);
+        if (basis === "estimated") bucket.estimated_fallback_sessions += 1;
+      }
     }
   }
-  writeSummary({ window_days: days, totals, by_model: byModel, by_cadence: byCadence });
+  // Keep the legacy field name populated so existing dashboards/readers don't
+  // silently read undefined — but it now carries the BILLABLE figure (CLI
+  // authoritative where available), not the cache-blind token estimate.
+  for (const bucket of [totals, ...Object.values(byModel), ...Object.values(byCadence)]) {
+    bucket.estimated_usd = bucket.billable_usd;
+  }
+  const audit = summariseRows(windowRows);
+  writeSummary({
+    window_days: days,
+    totals,
+    by_model: byModel,
+    by_cadence: byCadence,
+    measurement: {
+      measured_sessions: audit.measured,
+      unmeasured_sessions: audit.unmeasured,
+      non_llm_rows: audit.nonLlmRows,
+      authoritative_usd: audit.authoritativeUsd,
+      estimated_fallback_usd: audit.estimatedFallbackUsd,
+      blind: audit.blind,
+      degradations: audit.degradations,
+    },
+  });
 }
 
-function empty() { return { sessions: 0, input_tokens: 0, output_tokens: 0, estimated_usd: 0 }; }
+function empty() {
+  return {
+    sessions: 0,
+    unmeasured_sessions: 0,
+    estimated_fallback_sessions: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_tokens: 0,
+    billable_usd: 0,
+    estimated_usd: 0,
+  };
+}
 
 function writeSummary(payload) {
   const out = {