@cohortapp/agent-sdk 2.3.0

package/lib/budget-guard.mjs

@@ -0,0 +1,279 @@
+/**
+ * lib/budget-guard.mjs — daily spend cap + essential-only mode (WS4).
+ *
+ * Sums today's per-session cost rows from the existing ledger
+ * (`state/cost-tracking/<date>.jsonl`, written by
+ * scripts/cost/track-claude-usage.mjs) and reports where the day sits against
+ * a configured cap. As spend crosses 50 / 75 / 90 %, a single escalating
+ * notice is emitted PER BAND PER DAY (tracked in
+ * `state/cost-tracking/<date>.budget.json` so we never spam). At 100 % the
+ * governor flips to `essentialOnly`: backlog + cadence-escalation work is
+ * DEFERRED, but inbox DMs are still answered (Invariant #1 — never brick; we
+ * degrade, we don't go dark on the user).
+ *
+ * Config knobs (env-overridable; tests inject via deps):
+ *   DAILY_SPEND_CAP_USD     hard cap in USD (default 25)
+ *   DAILY_ITERATION_CAP     optional cap on session count (default 0 = off)
+ *
+ * The window resets at UTC midnight automatically — the ledger + budget files
+ * are date-stamped, so "today" is simply the current UTC date.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins only, injectable clock +
+ * ledger path so tests are hermetic. Never throws on I/O failure: a guard
+ * that can't read the ledger reports band 0 (essentialOnly:false) — degrade
+ * toward keeping work flowing, not toward bricking.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_DAILY_SPEND_CAP_USD = 25;
+export const DEFAULT_DAILY_ITERATION_CAP = 0; // 0 = no session-count cap
+
+/**
+ * Read the daily spend cap from config/recovery.yaml, if present. We extract the
+ * single scalar we need with a targeted regex rather than pulling in a YAML
+ * parser — this keeps the hot-path guard zero-dep and never-throwing (per the
+ * module contract), matching how lib/setup/sections/recovery.mjs line-edits the
+ * same key. Accepts the documented snake_case key under `budget:`
+ * (`daily_spend_cap_usd`) and the camelCase aliases the audit referenced
+ * (`dailySpendUSD` / `dailySpendCapUsd`), at top level or nested. Returns a
+ * finite positive number, or null when the file is absent/unset/malformed.
+ */
+function recoveryYamlCap(deps) {
+  const root =
+    (deps && deps.recoveryConfigPath) ||
+    join(
+      resolve(
+        (deps && deps.agentRoot) ||
+          process.env.AGENT_ROOT ||
+          process.env.AGENT_DIR ||
+          process.cwd()
+      ),
+      "config",
+      "recovery.yaml"
+    );
+  let body;
+  try {
+    if (!existsSync(root)) return null;
+    body = readFileSync(root, "utf-8");
+  } catch {
+    return null;
+  }
+  // Match any of the accepted keys followed by a numeric value (strip an inline
+  // `# comment`). Order is irrelevant; the first matching key wins.
+  const m = body.match(
+    /^\s*(?:daily_spend_cap_usd|dailySpendCapUsd|dailySpendUSD)\s*:\s*([0-9]+(?:\.[0-9]+)?)/m
+  );
+  if (!m) return null;
+  const v = Number(m[1]);
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+
+function cfgSpendCap(deps) {
+  if (deps && Number.isFinite(deps.capUSD)) return deps.capUSD;
+  // Prefer the operator's config/recovery.yaml cap over the env / default so the
+  // documented per-agent override is actually honoured at runtime (recovery C1).
+  const fromYaml = recoveryYamlCap(deps);
+  if (Number.isFinite(fromYaml) && fromYaml > 0) return fromYaml;
+  const env = Number(process.env.DAILY_SPEND_CAP_USD);
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_DAILY_SPEND_CAP_USD;
+}
+function cfgIterationCap(deps) {
+  if (deps && Number.isFinite(deps.iterationCap)) return deps.iterationCap;
+  const env = Number(process.env.DAILY_ITERATION_CAP);
+  return Number.isFinite(env) && env >= 0 ? env : DEFAULT_DAILY_ITERATION_CAP;
+}
+
+// ---------------------------------------------------------------------------
+// Paths + clock
+// ---------------------------------------------------------------------------
+
+function clock(deps) {
+  return deps && typeof deps.now === "function" ? deps.now : Date.now;
+}
+
+function todayUtc(deps) {
+  return new Date(clock(deps)()).toISOString().slice(0, 10);
+}
+
+function ledgerDir(deps) {
+  if (deps && deps.ledgerDir) return resolve(deps.ledgerDir);
+  const root =
+    (deps && deps.agentRoot) ||
+    process.env.AGENT_ROOT ||
+    process.env.AGENT_DIR ||
+    process.cwd();
+  return join(resolve(root), "state", "cost-tracking");
+}
+
+function ledgerFile(deps) {
+  return join(ledgerDir(deps), `${todayUtc(deps)}.jsonl`);
+}
+
+function budgetStateFile(deps) {
+  return join(ledgerDir(deps), `${todayUtc(deps)}.budget.json`);
+}
+
+// ---------------------------------------------------------------------------
+// Banding
+// ---------------------------------------------------------------------------
+
+/** Bands are the integer thresholds we notify at. 0 = below 50 %. */
+export const BANDS = [50, 75, 90, 100];
+
+function bandForPct(pct) {
+  if (pct >= 100) return 100;
+  if (pct >= 90) return 90;
+  if (pct >= 75) return 75;
+  if (pct >= 50) return 50;
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Ledger sum
+// ---------------------------------------------------------------------------
+
+/**
+ * Sum today's spend + session count from the JSONL ledger. Never throws;
+ * malformed lines are skipped, a missing file yields zeroes.
+ */
+function sumToday(deps) {
+  const file = ledgerFile(deps);
+  let spentUSD = 0;
+  let sessions = 0;
+  if (!existsSync(file)) return { spentUSD: 0, sessions: 0 };
+  let body;
+  try { body = readFileSync(file, "utf-8"); } catch { return { spentUSD: 0, sessions: 0 }; }
+  for (const line of body.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    const usd = Number(row.estimated_usd);
+    if (Number.isFinite(usd)) spentUSD += usd;
+    sessions += 1;
+  }
+  return { spentUSD: +spentUSD.toFixed(6), sessions };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the day's budget status.
+ *
+ * @param {object} [deps] { now?, ledgerDir?, agentRoot?, capUSD?, iterationCap? }
+ * @returns {{
+ *   spentUSD:number, capUSD:number, pct:number, band:0|50|75|90|100,
+ *   essentialOnly:boolean, sessions:number, iterationCap:number, date:string
+ * }}
+ */
+export function dailyStatus(deps) {
+  const capUSD = cfgSpendCap(deps);
+  const iterationCap = cfgIterationCap(deps);
+  const { spentUSD, sessions } = sumToday(deps);
+
+  const spendPct = capUSD > 0 ? (spentUSD / capUSD) * 100 : 0;
+  const iterPct = iterationCap > 0 ? (sessions / iterationCap) * 100 : 0;
+  // The binding constraint is whichever is closer to the cap.
+  const pct = Math.max(spendPct, iterPct);
+  const band = bandForPct(pct);
+
+  return {
+    spentUSD,
+    capUSD,
+    pct: +pct.toFixed(2),
+    band,
+    essentialOnly: band >= 100,
+    sessions,
+    iterationCap,
+    date: todayUtc(deps),
+  };
+}
+
+/**
+ * Read the per-day notification ledger ({ notified_bands: number[] }). Never
+ * throws.
+ */
+export function readNotified(deps) {
+  const p = budgetStateFile(deps);
+  if (!existsSync(p)) return { notified_bands: [] };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    const arr = Array.isArray(raw.notified_bands) ? raw.notified_bands.filter((n) => BANDS.includes(n)) : [];
+    return { notified_bands: arr };
+  } catch {
+    return { notified_bands: [] };
+  }
+}
+
+function writeNotified(state, deps) {
+  const p = budgetStateFile(deps);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+    try { renameSync(tmp, p); }
+    catch (err) { try { unlinkSync(tmp); } catch { /* */ } throw err; }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Emit AT MOST ONE notice per band per day. If the current band is above any
+ * not-yet-notified band threshold(s), returns the highest such band as the
+ * notice to surface and records every crossed band as notified (so a jump
+ * from 40 %→95 % notifies once at 90, not three times). When `notify` is
+ * provided it is invoked with a structured payload; otherwise the caller can
+ * use the return value.
+ *
+ * @param {object} [deps] { now?, ledgerDir?, capUSD?, notify? }
+ * @returns {{ notified:boolean, band:0|50|75|90|100, status:object, message?:string }}
+ */
+export function maybeNotify(deps) {
+  const status = dailyStatus(deps);
+  if (status.band === 0) return { notified: false, band: 0, status };
+
+  const { notified_bands } = readNotified(deps);
+  const already = new Set(notified_bands);
+
+  // Every band threshold at or below the current band that hasn't fired yet.
+  const crossed = BANDS.filter((b) => status.band >= b && !already.has(b));
+  if (crossed.length === 0) {
+    return { notified: false, band: status.band, status };
+  }
+
+  // Mark them all notified; surface ONE notice at the highest crossed band.
+  const topBand = crossed[crossed.length - 1];
+  writeNotified({ notified_bands: [...notified_bands, ...crossed].sort((a, b) => a - b) }, deps);
+
+  const message = formatNotice(topBand, status);
+  const notifyFn = deps && typeof deps.notify === "function" ? deps.notify : null;
+  if (notifyFn) {
+    try { notifyFn({ band: topBand, status, message }); } catch { /* notice is best-effort */ }
+  }
+  return { notified: true, band: topBand, status, message };
+}
+
+function formatNotice(band, status) {
+  const usd = status.spentUSD.toFixed(2);
+  const cap = status.capUSD.toFixed(2);
+  if (band >= 100) {
+    return `Daily spend cap reached: $${usd} / $${cap} (${status.pct}%). Entering essential-only mode — inbox replies continue; backlog + scheduled work deferred until UTC midnight.`;
+  }
+  return `Daily spend at ${band}%: $${usd} / $${cap} (${status.pct}%).`;
+}

package/lib/budget-guard.test.mjs

@@ -0,0 +1,291 @@
+/**
+ * budget-guard.test.mjs — node:test coverage for the daily spend cap.
+ *
+ * Hermetic: each test builds an isolated ledger dir with hand-written JSONL
+ * rows and injects a fixed clock + cap so band math is deterministic.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  dailyStatus,
+  maybeNotify,
+  readNotified,
+  BANDS,
+  DEFAULT_DAILY_SPEND_CAP_USD,
+} from "./budget-guard.mjs";
+
+const FIXED = Date.UTC(2026, 5, 9, 12, 0, 0); // 2026-06-09T12:00:00Z
+const DATE = "2026-06-09";
+const clk = () => FIXED;
+
+async function makeLedgerDir() {
+  const dir = join(tmpdir(), `budget-guard-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(dir, { recursive: true });
+  return dir;
+}
+async function rm(dir) { try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* */ } }
+
+/** Write `rows` (array of {estimated_usd}) into today's ledger file. */
+function seedLedger(dir, rows) {
+  const body = rows.map((r) => JSON.stringify({ ts: `${DATE}T10:00:00.000Z`, estimated_usd: r.usd, model: "sonnet", cadence: "x" })).join("\n") + "\n";
+  writeFileSync(join(dir, `${DATE}.jsonl`), body);
+}
+
+// ---------------------------------------------------------------------------
+// banding
+// ---------------------------------------------------------------------------
+
+test("dailyStatus: below 50% is band 0, not essential-only", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedLedger(dir, [{ usd: 4 }]); // $4 of $10 = 40%
+    const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 });
+    assert.equal(s.band, 0);
+    assert.equal(s.essentialOnly, false);
+    assert.equal(s.spentUSD, 4);
+    assert.equal(s.pct, 40);
+  } finally { await rm(dir); }
+});
+
+test("dailyStatus: crossing each threshold lands in the right band", async () => {
+  for (const [usd, expected] of [[5, 50], [7.5, 75], [9, 90], [10, 100], [12, 100]]) {
+    const dir = await makeLedgerDir();
+    try {
+      seedLedger(dir, [{ usd }]);
+      const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 });
+      assert.equal(s.band, expected, `$${usd}/$10 should be band ${expected}, got ${s.band}`);
+    } finally { await rm(dir); }
+  }
+});
+
+test("dailyStatus: empty/missing ledger reports zero spend, band 0", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 });
+    assert.equal(s.spentUSD, 0);
+    assert.equal(s.band, 0);
+    assert.equal(s.essentialOnly, false);
+  } finally { await rm(dir); }
+});
+
+test("dailyStatus uses the default cap when none configured", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedLedger(dir, [{ usd: 1 }]);
+    const s = dailyStatus({ ledgerDir: dir, now: clk });
+    assert.equal(s.capUSD, DEFAULT_DAILY_SPEND_CAP_USD);
+  } finally { await rm(dir); }
+});
+
+test("dailyStatus: iteration cap can be the binding constraint", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    // 10 cheap rows; spend tiny ($1 of $1000 = 0.1%) but 10/10 iterations = 100%.
+    seedLedger(dir, Array.from({ length: 10 }, () => ({ usd: 0.1 })));
+    const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 1000, iterationCap: 10 });
+    assert.equal(s.sessions, 10);
+    assert.equal(s.band, 100, "iteration cap should drive band to 100");
+    assert.equal(s.essentialOnly, true);
+  } finally { await rm(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// essential-only at 100%
+// ---------------------------------------------------------------------------
+
+test("essentialOnly is true only at/after 100%", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedLedger(dir, [{ usd: 9.99 }]);
+    assert.equal(dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 }).essentialOnly, false);
+    seedLedger(dir, [{ usd: 10 }]);
+    assert.equal(dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 }).essentialOnly, true);
+  } finally { await rm(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// one-notice-per-band
+// ---------------------------------------------------------------------------
+
+test("maybeNotify fires once per band and never repeats within the day", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    const notices = [];
+    const notify = (n) => notices.push(n.band);
+
+    // 60% → notify band 50 once.
+    seedLedger(dir, [{ usd: 6 }]);
+    let r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    assert.equal(r.notified, true);
+    assert.equal(r.band, 50);
+
+    // Still 60% → no repeat.
+    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    assert.equal(r.notified, false);
+
+    // Climb to 80% → notify band 75 once.
+    seedLedger(dir, [{ usd: 8 }]);
+    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    assert.equal(r.notified, true);
+    assert.equal(r.band, 75);
+
+    assert.deepEqual(notices, [50, 75]);
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75]);
+  } finally { await rm(dir); }
+});
+
+test("maybeNotify on a big jump notifies once at the highest crossed band", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    const notices = [];
+    // Jump straight from $0 to 95% — should surface ONE notice at band 90,
+    // and record 50/75/90 as all notified so they never re-fire.
+    seedLedger(dir, [{ usd: 9.5 }]);
+    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band) });
+    assert.equal(r.notified, true);
+    assert.equal(r.band, 90);
+    assert.deepEqual(notices, [90], "exactly one notice surfaced");
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75, 90]);
+
+    // A later check at the same level does nothing.
+    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band) });
+    assert.equal(r2.notified, false);
+    assert.deepEqual(notices, [90]);
+  } finally { await rm(dir); }
+});
+
+test("maybeNotify reaching 100% surfaces the essential-only notice once", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    const notices = [];
+    seedLedger(dir, [{ usd: 11 }]); // 110%
+    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n) });
+    assert.equal(r.notified, true);
+    assert.equal(r.band, 100);
+    assert.match(r.message, /essential-only/i);
+    assert.equal(r.status.essentialOnly, true);
+    // All bands recorded; a repeat is a no-op.
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75, 90, 100]);
+    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n) });
+    assert.equal(r2.notified, false);
+    assert.equal(notices.length, 1);
+  } finally { await rm(dir); }
+});
+
+test("BANDS is the canonical 50/75/90/100 ladder", () => {
+  assert.deepEqual(BANDS, [50, 75, 90, 100]);
+});
+
+// ---------------------------------------------------------------------------
+// recovery.yaml cap is honoured (recovery C1)
+// ---------------------------------------------------------------------------
+
+/** Write a config/recovery.yaml under `agentRoot` with the given cap line. */
+async function seedRecoveryYaml(agentRoot, body) {
+  await fsp.mkdir(join(agentRoot, "config"), { recursive: true });
+  writeFileSync(join(agentRoot, "config", "recovery.yaml"), body);
+}
+
+test("dailyStatus reads the cap from config/recovery.yaml when present", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    // agentRoot holds both config/recovery.yaml and the ledger dir.
+    await fsp.mkdir(join(dir, "state", "cost-tracking"), { recursive: true });
+    await seedRecoveryYaml(dir, `budget:\n  daily_spend_cap_usd: 40  # per-agent override\n`);
+    // Ledger lives where ledgerDir() derives it from agentRoot.
+    seedLedger(join(dir, "state", "cost-tracking"), [{ usd: 20 }]);
+    const s = dailyStatus({ agentRoot: dir, now: clk });
+    assert.equal(s.capUSD, 40, "cap should come from recovery.yaml, not the 25 default");
+    assert.equal(s.spentUSD, 20);
+    assert.equal(s.pct, 50, "20/40 = 50%");
+    assert.equal(s.band, 50);
+  } finally { await rm(dir); }
+});
+
+test("recovery.yaml cap takes precedence over DAILY_SPEND_CAP_USD env", async () => {
+  const dir = await makeLedgerDir();
+  const prevEnv = process.env.DAILY_SPEND_CAP_USD;
+  try {
+    process.env.DAILY_SPEND_CAP_USD = "100"; // would be the cap if yaml were ignored
+    await fsp.mkdir(join(dir, "state", "cost-tracking"), { recursive: true });
+    await seedRecoveryYaml(dir, `budget:\n  daily_spend_cap_usd: 10\n`);
+    seedLedger(join(dir, "state", "cost-tracking"), [{ usd: 10 }]);
+    const s = dailyStatus({ agentRoot: dir, now: clk });
+    assert.equal(s.capUSD, 10, "yaml cap must win over the env cap");
+    assert.equal(s.band, 100, "10/10 spent under the yaml cap is 100% (essential-only)");
+    assert.equal(s.essentialOnly, true);
+  } finally {
+    if (prevEnv === undefined) delete process.env.DAILY_SPEND_CAP_USD;
+    else process.env.DAILY_SPEND_CAP_USD = prevEnv;
+    await rm(dir);
+  }
+});
+
+test("an explicit deps.capUSD still overrides the recovery.yaml cap", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    await fsp.mkdir(join(dir, "state", "cost-tracking"), { recursive: true });
+    await seedRecoveryYaml(dir, `budget:\n  daily_spend_cap_usd: 40\n`);
+    seedLedger(join(dir, "state", "cost-tracking"), [{ usd: 5 }]);
+    const s = dailyStatus({ agentRoot: dir, now: clk, capUSD: 10 });
+    assert.equal(s.capUSD, 10, "explicit injected cap wins (test seam preserved)");
+  } finally { await rm(dir); }
+});
+
+test("malformed / capless recovery.yaml falls back to the default cap", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    await fsp.mkdir(join(dir, "state", "cost-tracking"), { recursive: true });
+    await seedRecoveryYaml(dir, `governor:\n  hard_max: 10\n# no budget key here\n`);
+    seedLedger(join(dir, "state", "cost-tracking"), [{ usd: 1 }]);
+    const s = dailyStatus({ agentRoot: dir, now: clk });
+    assert.equal(s.capUSD, DEFAULT_DAILY_SPEND_CAP_USD);
+  } finally { await rm(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// summing REAL ledger rows yields nonzero spend (the $0-forever bug guard)
+// ---------------------------------------------------------------------------
+
+test("summing real cost-ledger rows (with token-derived estimated_usd) yields nonzero spend", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    // Rows shaped exactly like track-claude-usage.mjs#record emits them:
+    // estimated_usd is computed from token counts. A daemon that passed REAL
+    // counts produces nonzero rows; the old --input-tokens 0 bug produced 0.
+    const rows = [
+      // sonnet: (1500/1000*0.003)+(320/1000*0.015) = 0.0045+0.0048 = 0.0093
+      { ts: `${DATE}T10:00:00.000Z`, estimated_usd: 0.0093, model: "sonnet", cadence: "inbox-processor", input_tokens: 1500, output_tokens: 320 },
+      // opus: (5000/1000*0.015)+(900/1000*0.075) = 0.075+0.0675 = 0.1425
+      { ts: `${DATE}T11:00:00.000Z`, estimated_usd: 0.1425, model: "opus", cadence: "backlog-executor", input_tokens: 5000, output_tokens: 900 },
+    ];
+    writeFileSync(join(dir, `${DATE}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
+    const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 25 });
+    assert.ok(s.spentUSD > 0, `expected nonzero spend, got ${s.spentUSD}`);
+    assert.equal(s.spentUSD, +(0.0093 + 0.1425).toFixed(6));
+    assert.equal(s.sessions, 2);
+  } finally { await rm(dir); }
+});
+
+test("a ledger of only zero-token rows sums to $0 (proves the bug is the input, not the guard)", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    // The pre-fix daemon wrote rows with input_tokens=0/output_tokens=0, so
+    // estimated_usd=0 — the guard reported $0 spend forever. This documents that
+    // the guard math is correct; the defect was the caller's fabricated zeros.
+    const rows = [
+      { ts: `${DATE}T10:00:00.000Z`, estimated_usd: 0, model: "sonnet", cadence: "x", input_tokens: 0, output_tokens: 0 },
+      { ts: `${DATE}T11:00:00.000Z`, estimated_usd: 0, model: "sonnet", cadence: "x", input_tokens: 0, output_tokens: 0 },
+    ];
+    writeFileSync(join(dir, `${DATE}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
+    const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 25 });
+    assert.equal(s.spentUSD, 0);
+    assert.equal(s.sessions, 2);
+  } finally { await rm(dir); }
+});