@bongos/core 1.17.0

package/tests/context_pack.mjs

@@ -0,0 +1,240 @@
+// tests/context_pack.mjs
+//
+// V4.R04 / #942 — the claim-time "you are here" context pack. Criterion
+// sessions-start-knowing. The June 2026 corpus showed sessions re-discovering
+// their worktree root (the #1 wrong-path class, 84 hits) and guessing task
+// field enums (the BAD_KIND / P2 guess-and-retry class). The pack pushes that
+// up front. These tests pin the pure core with injected git/which/platform so
+// there is NO real git, filesystem, or network dependency — and they prove the
+// enums come straight from the live validators (not a hand-maintained copy).
+//
+// Run:  node tests/context_pack.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  apiContract,
+  resolveWorktreeRoot,
+  osFacts,
+  normalizeClaims,
+  buildContextPack,
+  formatClaims,
+  formatOs,
+  formatContextPack,
+  formatContextPackCompact,
+} = require('../scripts/gds/context-pack.js');
+// The live validators — the pack MUST mirror these, or it would teach builders
+// the wrong enum (the whole point of "generated from the live validators").
+const { VALID_KINDS, VALID_DISCIPLINES, TASK_FIELD_BOUNDS } =
+  require('../modules/lifecycle/task-classifier.js');
+// The route validator (POST /tasks) — pure, so we can prove an out-of-range
+// priority is caught here (clean 400) instead of reaching the DB CHECK (#1233).
+const { validate, VALIDATION_REASONS } =
+  require('../src/bongos/routes/_helpers.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- apiContract: generated from the live validators -----------------------
+t('apiContract: kinds match VALID_KINDS exactly, minus the unclassified fallback', () => {
+  const expected = [...VALID_KINDS].filter((k) => k !== 'unclassified');
+  assert.deepEqual(apiContract().task_kinds, expected);
+});
+
+t('apiContract: disciplines match VALID_DISCIPLINES minus unclassified', () => {
+  const expected = [...VALID_DISCIPLINES].filter((d) => d !== 'unclassified');
+  assert.deepEqual(apiContract().disciplines, expected);
+});
+
+t('apiContract: unclassified is never advertised as a pickable value', () => {
+  const c = apiContract();
+  assert.ok(!c.task_kinds.includes('unclassified'));
+  assert.ok(!c.disciplines.includes('unclassified'));
+});
+
+t('apiContract: numeric bounds are the shared TASK_FIELD_BOUNDS (single source)', () => {
+  const c = apiContract();
+  assert.deepEqual(c.priority, TASK_FIELD_BOUNDS.priority);
+  assert.deepEqual(c.manual_degree, TASK_FIELD_BOUNDS.manual_degree);
+});
+
+t('apiContract: priority bound mirrors the DB CHECK (1–5), not the old lax 0–100 (#1233)', () => {
+  // tasks_priority_check is `priority BETWEEN 1 AND 5` (migrations/003_pms.sql).
+  // The validator MUST match it, or an in-validator-but-out-of-DB value (e.g. 40)
+  // passes the 400 gate and dies on the INSERT with an opaque create_failed.
+  assert.equal(TASK_FIELD_BOUNDS.priority.min, 1);
+  assert.equal(TASK_FIELD_BOUNDS.priority.max, 5);
+  // The human-facing convention label still rides along for the context pack.
+  assert.deepEqual(TASK_FIELD_BOUNDS.priority.convention, { min: 1, max: 5, label: 'P1–P5 planning tiers' });
+});
+
+// The POST /tasks priority schema, wired exactly as routes/tasks.js wires it.
+const priorityRule = {
+  priority: { type: 'integer', min: TASK_FIELD_BOUNDS.priority.min, max: TASK_FIELD_BOUNDS.priority.max },
+};
+t('POST /tasks validator: an in-range priority (1..5) is accepted', () => {
+  for (const p of [1, 3, 5]) assert.equal(validate({ priority: p }, priorityRule), null, `priority ${p}`);
+});
+t('POST /tasks validator: priority 6 is a clean 400 (above_max), NOT a DB create_failed (#1233)', () => {
+  const r = validate({ priority: 6 }, priorityRule);
+  assert.ok(r, 'priority 6 must be rejected at the validator');
+  assert.equal(r.error, 'validation_failed');
+  assert.deepEqual(r.details, [{ field: 'priority', reason: VALIDATION_REASONS.ABOVE_MAX, limit: 5 }]);
+});
+t('POST /tasks validator: priority 0 is rejected at the validator (below_min)', () => {
+  const r = validate({ priority: 0 }, priorityRule);
+  assert.ok(r);
+  assert.equal(r.details[0].reason, VALIDATION_REASONS.BELOW_MIN);
+});
+
+t('apiContract: api_prefix is /api/bongos', () => {
+  assert.equal(apiContract().api_prefix, '/api/bongos');
+});
+
+// ---- resolveWorktreeRoot: git toplevel, fail-open to cwd -------------------
+t('resolveWorktreeRoot: uses git toplevel when available', () => {
+  const r = resolveWorktreeRoot({ runGit: () => '/work/tree\n', cwd: '/somewhere/else' });
+  assert.equal(r.root, '/work/tree');
+  assert.equal(r.degraded, false);
+});
+
+t('resolveWorktreeRoot: git throwing falls back to cwd, flags degraded (never throws)', () => {
+  const r = resolveWorktreeRoot({ runGit: () => { throw new Error('not a git repo'); }, cwd: '/here' });
+  assert.equal(r.root, '/here');
+  assert.equal(r.degraded, true);
+});
+
+t('resolveWorktreeRoot: empty git output also degrades to cwd', () => {
+  const r = resolveWorktreeRoot({ runGit: () => '  \n', cwd: '/here' });
+  assert.equal(r.root, '/here');
+  assert.equal(r.degraded, true);
+});
+
+// ---- osFacts: timeout/psql presence, mac flag ------------------------------
+function fakeWhich(present) {
+  // present: { timeout?: path, psql?: path } — absent keys throw (command missing)
+  return (cmd) => {
+    if (present[cmd]) return present[cmd] + '\n';
+    throw new Error(`which: ${cmd} not found`);
+  };
+}
+
+t('osFacts: macOS with no timeout is detected (the documented footgun)', () => {
+  const f = osFacts({ platform: 'darwin', runWhich: fakeWhich({ psql: '/opt/homebrew/bin/psql' }) });
+  assert.equal(f.isMac, true);
+  assert.equal(f.timeoutPath, null);
+  assert.equal(f.psqlPath, '/opt/homebrew/bin/psql');
+});
+
+t('osFacts: linux with timeout + psql present', () => {
+  const f = osFacts({ platform: 'linux', runWhich: fakeWhich({ timeout: '/usr/bin/timeout', psql: '/usr/bin/psql' }) });
+  assert.equal(f.isMac, false);
+  assert.equal(f.timeoutPath, '/usr/bin/timeout');
+  assert.equal(f.psqlPath, '/usr/bin/psql');
+});
+
+t('osFacts: missing psql surfaces as null, not a throw', () => {
+  const f = osFacts({ platform: 'linux', runWhich: fakeWhich({}) });
+  assert.equal(f.psqlPath, null);
+  assert.equal(f.timeoutPath, null);
+});
+
+// ---- normalizeClaims: mark the just-claimed task ---------------------------
+t('normalizeClaims: marks the current task and tolerates string/number id mismatch', () => {
+  const rows = normalizeClaims(
+    [{ task_id: 942, title: 'A' }, { task_id: 1187, title: 'B' }],
+    '942' // currentTaskId arrives as a string from the route response
+  );
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].current, true);
+  assert.equal(rows[1].current, false);
+});
+
+t('normalizeClaims: non-array input degrades to []', () => {
+  assert.deepEqual(normalizeClaims(undefined, 1), []);
+  assert.deepEqual(normalizeClaims(null, 1), []);
+});
+
+// ---- buildContextPack: assembles the whole thing ---------------------------
+t('buildContextPack: composes worktree + claims + api + os from injected runners', () => {
+  const pack = buildContextPack({
+    activeClaims: [{ task_id: 942, title: 'context pack' }],
+    currentTaskId: 942,
+    cwd: '/fallback',
+    platform: 'linux',
+    runGit: () => '/work/tree\n',
+    runWhich: fakeWhich({ timeout: '/usr/bin/timeout', psql: '/usr/bin/psql' }),
+  });
+  assert.equal(pack.worktree.root, '/work/tree');
+  assert.equal(pack.claims[0].current, true);
+  assert.equal(pack.api.api_prefix, '/api/bongos');
+  assert.equal(pack.os.platform, 'linux');
+});
+
+// ---- formatting ------------------------------------------------------------
+t('formatClaims: empty vs held, with the (this one) marker', () => {
+  assert.equal(formatClaims([]), '(none held)');
+  assert.equal(
+    formatClaims([{ id: 942, current: true }, { id: 1187, current: false }]),
+    '#942 (this one), #1187'
+  );
+});
+
+t('formatOs: names the macOS no-timeout case in prose', () => {
+  const line = formatOs({ platform: 'darwin', isMac: true, timeoutPath: null, psqlPath: null, nodeVersion: 'v20.0.0' });
+  assert.match(line, /no `timeout`/);
+  assert.match(line, /macOS/);
+  assert.match(line, /psql NOT on PATH/);
+});
+
+t('formatContextPack: includes worktree root, prefix, a real kind, and warns the wrong-tree footgun', () => {
+  const pack = buildContextPack({
+    activeClaims: [{ task_id: 942, title: 'x' }],
+    currentTaskId: 942,
+    cwd: '/fallback',
+    platform: 'linux',
+    runGit: () => '/work/tree\n',
+    runWhich: fakeWhich({ timeout: '/usr/bin/timeout', psql: '/usr/bin/psql' }),
+  });
+  const out = formatContextPack(pack);
+  assert.match(out, /\/work\/tree/);
+  assert.match(out, /\/api\/bongos/);
+  assert.match(out, /feature/);          // a real kind from VALID_KINDS
+  assert.match(out, /not the main checkout/i);
+  assert.ok(!/undefined/.test(out), 'no undefined leaked into the rendered pack');
+});
+
+t('formatContextPack: degraded worktree prints the verify-before-writing warning', () => {
+  const pack = buildContextPack({
+    activeClaims: [],
+    cwd: '/here',
+    platform: 'linux',
+    runGit: () => { throw new Error('no git'); },
+    runWhich: fakeWhich({}),
+  });
+  assert.match(formatContextPack(pack), /git toplevel unreadable/);
+});
+
+t('formatContextPackCompact: two lines, worktree + prefix, no undefined', () => {
+  const pack = buildContextPack({
+    activeClaims: [],
+    cwd: '/fallback',
+    platform: 'linux',
+    runGit: () => '/work/tree\n',
+    runWhich: fakeWhich({}),
+  });
+  const out = formatContextPackCompact(pack);
+  assert.equal(out.split('\n').length, 2);
+  assert.match(out, /\/work\/tree/);
+  assert.match(out, /\/api\/bongos/);
+  assert.ok(!/undefined/.test(out));
+});
+
+console.log(`\ncontext_pack: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/cost.mjs

@@ -0,0 +1,94 @@
+// tests/cost.mjs — System 1 / task 1346: the audit's new dimensions (by_source,
+// cache_read share, per-system eliminated_usd) + the savings-without-baseline
+// tripwire. auditCostAttribution is pure over the costSummary() shape, so this
+// is fully DB-free. (The pre-existing attribution/completeness coverage lives in
+// tests/cost_audit.mjs.) Run: node tests/cost.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { auditCostAttribution, formatAuditReport } = require('../modules/economy/cost-classify.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+const fullSummary = {
+  total_usd: 100,
+  by_category: [{ category: 'api', total_usd: 100 }],
+  by_builder: [{ builder_id: 1, github_login: 'alice', total_usd: 100 }],
+  by_source: [
+    { source: 'session:interactive', total_usd: 82 },
+    { source: 'session:subagent', total_usd: 18 },
+  ],
+  by_tier: { fresh_input_usd: 10, cache_read_usd: 70, cache_write_usd: 5, output_usd: 15, tier_total_usd: 100, cache_read_pct: 70 },
+  savings: {
+    by_system: [{ system: 'system2:compaction', baseline_usd: 50, amount_usd: 20, saved_usd: 30 }],
+    total_baseline_usd: 50, total_amount_usd: 20, total_saved_usd: 30,
+  },
+};
+
+test('audit folds in by_source, cache_read share, and per-system eliminated_usd', () => {
+  const r = auditCostAttribution(fullSummary);
+  assert.equal(r.by_source.length, 2);
+  assert.equal(r.by_source[0].source, 'session:interactive');
+  assert.equal(r.by_source[0].total_usd, 82);
+  assert.equal(r.cache_read_usd, 70);
+  assert.equal(r.cache_read_pct, 70); // the marathon-sink headline
+  assert.equal(r.tier_total_usd, 100);
+  assert.equal(r.eliminated_by_system[0].system, 'system2:compaction');
+  assert.equal(r.eliminated_by_system[0].eliminated_usd, 30);
+  assert.equal(r.total_eliminated_usd, 30);
+  assert.equal(r.ok, true);
+  assert.equal(r.flags.find((f) => f.kind === 'savings_without_baseline'), undefined);
+});
+
+test('derives cache_read_pct when by_tier omits it', () => {
+  const r = auditCostAttribution({
+    total_usd: 100, by_category: [], by_builder: [],
+    by_tier: { cache_read_usd: 40, tier_total_usd: 80 }, // no cache_read_pct
+  });
+  assert.equal(r.cache_read_pct, 50); // 40/80
+});
+
+test('tripwire: a savings entry with no baseline → savings_without_baseline (warn)', () => {
+  const r = auditCostAttribution({
+    total_usd: 10, by_category: [], by_builder: [],
+    savings: { by_system: [{ system: 'phantom', baseline_usd: 0, amount_usd: 0, saved_usd: 0 }], total_saved_usd: 0 },
+  });
+  const flag = r.flags.find((f) => f.kind === 'savings_without_baseline');
+  assert.ok(flag, 'expected savings_without_baseline flag');
+  assert.equal(flag.level, 'warn');
+  assert.equal(r.ok, true); // warn, not a hard fail
+});
+
+test('back-compat: a pre-deploy summary (no by_source/by_tier/savings) → zeros, no throw', () => {
+  const r = auditCostAttribution({
+    total_usd: 50, by_category: [{ category: 'api', total_usd: 50 }],
+    by_builder: [{ builder_id: 1, github_login: 'alice', total_usd: 50 }],
+  });
+  assert.deepEqual(r.by_source, []);
+  assert.equal(r.cache_read_usd, 0);
+  assert.equal(r.cache_read_pct, 0);
+  assert.equal(r.tier_total_usd, 0);
+  assert.deepEqual(r.eliminated_by_system, []);
+  assert.equal(r.total_eliminated_usd, 0);
+  assert.equal(r.flags.find((f) => f.kind === 'savings_without_baseline'), undefined);
+  assert.equal(r.ok, true);
+});
+
+test('formatAuditReport renders the new sections when present, omits when absent', () => {
+  const withDims = formatAuditReport(auditCostAttribution(fullSummary));
+  assert.match(withDims, /by call-site source/);
+  assert.match(withDims, /cache_read tier/);
+  assert.match(withDims, /marathon cost sink/);
+  assert.match(withDims, /system2:compaction/);
+  const withoutDims = formatAuditReport(auditCostAttribution({ total_usd: 0, by_category: [], by_builder: [] }));
+  assert.doesNotMatch(withoutDims, /by call-site source/);
+  assert.doesNotMatch(withoutDims, /cache_read tier/);
+});
+
+console.log(`\ncost (task 1346 dims): ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/cost_audit.mjs

@@ -0,0 +1,122 @@
+// tests/cost_audit.mjs
+//
+// V3.R83 / task #303 — cost-attribution audit (criterion C3). The audit is a
+// PURE function over the costSummary() shape, so it's fully unit-testable with
+// no DB: we feed synthetic summaries and assert the attributed/unattributed
+// split, the owner-less-by-design accounting, and the integrity flags.
+//
+// Run: node --test tests/cost_audit.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { auditCostAttribution } = require('../modules/economy/cost-classify.js');
+
+test('splits attributed vs unattributed spend and counts owner-less categories', () => {
+  const r = auditCostAttribution({
+    total_usd: 100,
+    by_category: [
+      { category: 'infra', total_usd: 40 },
+      { category: 'api', total_usd: 60 },
+    ],
+    by_builder: [
+      { builder_id: 1, github_login: 'alice', total_usd: 30 },
+      { builder_id: null, total_usd: 70 },
+    ],
+  });
+  assert.equal(r.attributed_usd, 30);
+  assert.equal(r.unattributed_usd, 70);
+  assert.equal(r.unattributed_pct, 70);
+  assert.equal(r.ownerless_category_usd, 40); // infra is owner-less by design (category dimension)
+  assert.equal(r.builder_count, 1);
+  assert.equal(r.ok, true);
+  assert.equal(r.flags.length, 0);
+  assert.equal(r.backfill_needed, false); // no orphan → no correction needed
+  assert.ok(Array.isArray(r.write_surfaces) && r.write_surfaces.length >= 1); // code-path enumeration present
+});
+
+test('flags orphan attribution (builder_id with no name) but does not fail', () => {
+  const r = auditCostAttribution({
+    total_usd: 50,
+    by_category: [],
+    by_builder: [
+      { builder_id: 1, github_login: 'alice', total_usd: 30 },
+      { builder_id: 99, github_login: null, display_name: null, total_usd: 20 },
+    ],
+  });
+  assert.equal(r.builder_count, 2);
+  assert.equal(r.flags.length, 1);
+  assert.equal(r.flags[0].kind, 'orphan_attribution');
+  assert.equal(r.flags[0].level, 'warn');
+  assert.equal(r.ok, true); // a warn is not a hard failure
+  assert.equal(r.backfill_needed, true); // orphan attribution → correction needed
+});
+
+test('a builder named only by display_name is not flagged as an orphan', () => {
+  const r = auditCostAttribution({
+    total_usd: 10,
+    by_category: [],
+    by_builder: [{ builder_id: 7, github_login: null, display_name: 'Bob', total_usd: 10 }],
+  });
+  assert.equal(r.flags.length, 0);
+  assert.equal(r.builders[0].named, true);
+});
+
+test('empty / zero-spend summary audits cleanly', () => {
+  const r = auditCostAttribution({ total_usd: 0, by_category: [], by_builder: [] });
+  assert.equal(r.total_usd, 0);
+  assert.equal(r.unattributed_pct, 0); // no divide-by-zero
+  assert.equal(r.ok, true);
+});
+
+test('tolerates a missing by_builder/by_category (defensive against partial payloads)', () => {
+  const r = auditCostAttribution({ total_usd: 5 });
+  assert.equal(r.attributed_usd, 0);
+  assert.equal(r.unattributed_usd, 0);
+  assert.equal(r.ok, true);
+});
+
+// #485 (audit F3): completeness check — detect MISSING api spend, not just
+// mis-attribution. This is the gap that let the original audit return a false
+// all-clear at the #482 baseline ($0.60 api project-wide).
+
+test('completeness: substantial credits + ~$0 api → api_spend_implausibly_low (warn, not fail)', () => {
+  const r = auditCostAttribution({
+    total_usd: 280.62,
+    total_value_credits: 6783, // real shipping has happened
+    by_category: [
+      { category: 'infra', total_usd: 261.19 },
+      { category: 'api', total_usd: 0.6 }, // ...but recorded api spend is essentially nothing
+    ],
+    by_builder: [{ builder_id: null, total_usd: 280.62 }],
+  });
+  const flag = r.flags.find((f) => f.kind === 'api_spend_implausibly_low');
+  assert.ok(flag, 'expected api_spend_implausibly_low flag');
+  assert.equal(flag.level, 'warn');
+  assert.equal(r.ok, true); // warn-level: informational, does not hard-fail
+  assert.equal(r.api_usd, 0.6);
+  assert.equal(r.credits_shipped, 6783);
+});
+
+test('completeness: api spend above floor → no completeness flag (capture working)', () => {
+  const r = auditCostAttribution({
+    total_usd: 300,
+    total_value_credits: 6783,
+    by_category: [{ category: 'api', total_usd: 25 }], // grader+session capture flowing
+    by_builder: [{ builder_id: 1, github_login: 'alice', total_usd: 25 }],
+  });
+  assert.equal(r.flags.find((f) => f.kind === 'api_spend_implausibly_low'), undefined);
+  assert.equal(r.api_usd, 25);
+});
+
+test('completeness: low credits → no completeness flag (not enough activity to judge)', () => {
+  const r = auditCostAttribution({
+    total_usd: 50,
+    total_value_credits: 100, // below the floor — early project, can't conclude
+    by_category: [{ category: 'api', total_usd: 0 }],
+    by_builder: [{ builder_id: null, total_usd: 50 }],
+  });
+  assert.equal(r.flags.find((f) => f.kind === 'api_spend_implausibly_low'), undefined);
+});

package/tests/cost_budget_status.mjs

@@ -0,0 +1,78 @@
+// tests/cost_budget_status.mjs
+//
+// V3.R84 (#302), criterion C3 — the pure cost.classifyCostStatus() that decides
+// ok / warn (>=80%) / over (>=100%) from a builder's MTD spend vs budget. This is
+// the single source of truth behind the /me payload, the CLI session-start ping,
+// the hall banner, and the ship + art-pipeline hard-cap refusal — so the
+// thresholds are pinned here.
+//
+// ADR 0085 removed the project default cap: with no explicit budget set, a
+// builder is UNCAPPED (level always 'ok', budget_mtd_usd null). warn/over only
+// engage for a positive budget an Archon set via PATCH /builders/:id/budget.
+//
+// Run:  node tests/cost_budget_status.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { classifyCostStatus } = require('../modules/economy/cost-classify.js');
+
+let pass = 0, fail = 0;
+const t = (name, fn) => {
+  try { fn(); pass++; console.log(`PASS  ${name}`); }
+  catch (e) { fail++; console.log(`FAIL  ${name}\n      ${e.stack || e.message}`); }
+};
+
+t('under 80% → ok', () => {
+  const s = classifyCostStatus(10, 50);
+  assert.equal(s.level, 'ok');
+  assert.equal(s.pct_used, 20);
+  assert.equal(s.budget_mtd_usd, 50);
+  assert.equal(s.spend_mtd_usd, 10);
+});
+
+t('exactly 80% → warn (soft cap is inclusive)', () => {
+  assert.equal(classifyCostStatus(40, 50).level, 'warn');
+});
+
+t('between 80 and 100 → warn', () => {
+  assert.equal(classifyCostStatus(49.5, 50).level, 'warn');
+});
+
+t('exactly 100% → over (hard cap is inclusive)', () => {
+  assert.equal(classifyCostStatus(50, 50).level, 'over');
+});
+
+t('over budget → over', () => {
+  const s = classifyCostStatus(75, 50);
+  assert.equal(s.level, 'over');
+  assert.equal(s.pct_used, 150);
+});
+
+t('null/absent budget → uncapped (no default cap; ADR 0085)', () => {
+  const s = classifyCostStatus(5, null);
+  assert.equal(s.budget_mtd_usd, null);
+  assert.equal(s.pct_used, 0);
+  assert.equal(s.level, 'ok');
+});
+
+t('large spend but no budget set → still ok (builders are uncapped by default)', () => {
+  const s = classifyCostStatus(100000, null);
+  assert.equal(s.level, 'ok');
+  assert.equal(s.budget_mtd_usd, null);
+});
+
+t('zero/garbage budget → uncapped, never silently bricks (not always-over)', () => {
+  assert.equal(classifyCostStatus(5, 0).level, 'ok');
+  assert.equal(classifyCostStatus(5, 0).budget_mtd_usd, null);
+  assert.equal(classifyCostStatus(5, 'oops').level, 'ok');
+  assert.equal(classifyCostStatus(5, -10).budget_mtd_usd, null);
+});
+
+t('negative spend clamps to 0', () => {
+  assert.equal(classifyCostStatus(-5, 50).spend_mtd_usd, 0);
+});
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/cost_reconcile.mjs

@@ -0,0 +1,102 @@
+// tests/cost_reconcile.mjs — GDS-V4 task 1366. The pure pricing helper behind
+// the server-side session-cost reconciler (src/bongos/llm-pricing.js
+// componentsFromModelUsage). DB-free. Run: node --test tests/cost_reconcile.mjs
+//
+// The reconciler itself (db.reconcileSessionCosts) is DB-bound and lives in the
+// integration-smoke gate; this file pins the DB-free arithmetic it depends on —
+// the 4-tier split, multi-model summation, the unknown-model→opus rule, and the
+// empty/null degenerate.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { componentsFromModelUsage, PRICES } = require('../src/bongos/llm-pricing.js');
+
+const M = 1_000_000;
+const near = (a, b, eps = 1e-6) => Math.abs(a - b) < eps;
+
+test('1366 fixture: opus 1M/1M/10M/1M → $5 / $25 / $5 / $6.25, total $41.25', () => {
+  // Locked opus rates: input 5, output 25, cache_read 0.5, cache_write_5m 6.25
+  // (per Mtok). cache_creation lump is priced at the 5m rate (no breakdown).
+  const out = componentsFromModelUsage({
+    'claude-opus-4-8': { input: M, output: M, cache_read: 10 * M, cache_creation: M },
+  });
+  assert.ok(near(out.fresh_input_usd, 5), `fresh ${out.fresh_input_usd}`);
+  assert.ok(near(out.output_usd, 25), `output ${out.output_usd}`);
+  assert.ok(near(out.cache_read_usd, 5), `cache_read ${out.cache_read_usd}`); // 10M * 0.5/M
+  assert.ok(near(out.cache_write_usd, 6.25), `cache_write ${out.cache_write_usd}`);
+  assert.ok(near(out.total_usd, 41.25), `total ${out.total_usd}`);
+  // Invariant: the four tiers sum to total_usd by construction.
+  const sum = out.fresh_input_usd + out.cache_read_usd + out.cache_write_usd + out.output_usd;
+  assert.ok(near(sum, out.total_usd), `tiers sum ${sum} must equal total ${out.total_usd}`);
+  assert.deepEqual(out.unknown_models, [], 'a known opus id is not flagged unknown');
+});
+
+test('1366 multi-model summation (opus + haiku) folds across all models', () => {
+  // opus: output 1M = $25. haiku: output 1M = $5 (Haiku 4.5). Total output $30.
+  const out = componentsFromModelUsage({
+    'claude-opus-4-8': { output: M },
+    'claude-haiku-4-5': { output: M },
+  });
+  assert.ok(near(out.output_usd, 30), `output ${out.output_usd}`);
+  assert.ok(near(out.fresh_input_usd, 0));
+  assert.ok(near(out.cache_read_usd, 0));
+  assert.ok(near(out.cache_write_usd, 0));
+  assert.ok(near(out.total_usd, 30), `total ${out.total_usd}`);
+  assert.deepEqual(out.unknown_models, []);
+});
+
+test('1366 each tier sums independently across models (haiku cache_read + opus input)', () => {
+  // opus input 1M = $5; haiku cache_read 10M = 10M * 0.1/M = $1.
+  const out = componentsFromModelUsage({
+    'claude-opus-4-8': { input: M },
+    'claude-haiku-4-5': { cache_read: 10 * M },
+  });
+  assert.ok(near(out.fresh_input_usd, 5), `fresh ${out.fresh_input_usd}`);
+  assert.ok(near(out.cache_read_usd, 1), `cache_read ${out.cache_read_usd}`);
+  assert.ok(near(out.total_usd, 6), `total ${out.total_usd}`);
+});
+
+test('1366 unknown model id is priced AS opus AND reported in unknown_models', () => {
+  // An id matching no family → conservatively priced at the opus rate so spend is
+  // never silently $0, and surfaced so it is loud, not hidden.
+  const out = componentsFromModelUsage({
+    'gpt-9-turbo': { output: M },
+  });
+  assert.ok(near(out.output_usd, PRICES.opus.output), `output priced as opus ${out.output_usd}`);
+  assert.ok(near(out.total_usd, 25), `total ${out.total_usd}`);
+  assert.deepEqual(out.unknown_models, ['gpt-9-turbo'], 'unknown id is reported');
+});
+
+test('1366 a known + an unknown model: only the unknown is flagged, both priced', () => {
+  const out = componentsFromModelUsage({
+    'claude-opus-4-8': { output: M },   // $25, known
+    'mystery-model': { output: M },      // $25, priced-as-opus, flagged
+  });
+  assert.ok(near(out.output_usd, 50), `output ${out.output_usd}`);
+  assert.deepEqual(out.unknown_models, ['mystery-model']);
+});
+
+test('1366 empty / null / undefined model_usage → all zeros, no unknowns', () => {
+  for (const mu of [{}, null, undefined]) {
+    const out = componentsFromModelUsage(mu);
+    assert.equal(out.fresh_input_usd, 0);
+    assert.equal(out.cache_read_usd, 0);
+    assert.equal(out.cache_write_usd, 0);
+    assert.equal(out.output_usd, 0);
+    assert.equal(out.total_usd, 0);
+    assert.deepEqual(out.unknown_models, []);
+  }
+});
+
+test('1366 missing per-tier fields default to 0 (partial model_usage)', () => {
+  // Only input present; output/cache_read/cache_creation absent → priced as 0.
+  const out = componentsFromModelUsage({ 'claude-opus-4-8': { input: M } });
+  assert.ok(near(out.fresh_input_usd, 5));
+  assert.equal(out.output_usd, 0);
+  assert.equal(out.cache_read_usd, 0);
+  assert.equal(out.cache_write_usd, 0);
+  assert.ok(near(out.total_usd, 5));
+});