@bongos/core 1.19.842 → 1.19.844

package/modules/lifecycle/task-classifier.js

@@ -163,6 +163,42 @@ function classifyTaskKind(title, description) {
 // /design work-mode (discipline-modes.json) instead of /paint.
 const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator', 'ui', 'unclassified']);
 
+// The disciplines a WRITE may set (task 1002988). 'unclassified' is deliberately
+// absent: it is a triage state, not a craft, and a create that lands one produces
+// a row no craft is accountable for — which is how 1,189 of them accumulated.
+// VALID_DISCIPLINES above stays the READ-side set so existing rows and the
+// ?discipline=unclassified filter keep resolving while the backfill runs.
+// 'ui' stays: ADR 0272 keeps it as a module-contributed discipline, and the owner
+// reconfirmed that on 2026-09-17 when abandoning task 1002987.
+const WRITABLE_DISCIPLINES = new Set(['engineer', 'artist', 'ideator', 'ui']);
+
+// Mirrors the `kind` branch in the create routes: act on the classifier only when
+// it is at least half sure, otherwise treat it as no answer at all.
+const DISCIPLINE_CONFIDENCE_FLOOR = 0.5;
+
+// Resolve the discipline for a task WRITE. Honours an explicit valid value,
+// otherwise INFERS from title + description + touches, and reports failure so the
+// caller can 400 — per the owner decision of 2026-09-17, a bare 400 on a missing
+// discipline was rejected because four live paths (idea capture, idea promotion,
+// adopt-import and the new-instance scaffold) create tasks without one.
+//
+// Shared deliberately: POST /tasks and POST /goals/:id/tasks BOTH carried the
+// `body.discipline ?? 'unclassified'` line, so a fix applied to one of them would
+// have left the other quietly minting the very rows this task exists to remove.
+// Returns { discipline, inferred?, confidence? } or { error, unclassifiable? }.
+function resolveWriteDiscipline({ discipline, title, description, touches } = {}) {
+  if (discipline != null && discipline !== 'unclassified') {
+    return WRITABLE_DISCIPLINES.has(discipline) ? { discipline } : { error: 'bad_discipline' };
+  }
+  // Absent, null, or an explicit 'unclassified' (what modules/ideas/inbox.js sends
+  // on promotion) all mean the same thing: nobody told us, so work it out.
+  const guess = classifyTaskDiscipline(title, description || '', touches);
+  if (guess.confidence >= DISCIPLINE_CONFIDENCE_FLOOR && WRITABLE_DISCIPLINES.has(guess.discipline)) {
+    return { discipline: guess.discipline, inferred: true, confidence: guess.confidence };
+  }
+  return { error: 'bad_discipline', unclassifiable: true };
+}
+
 // Numeric field bounds for task creation (POST /tasks). The single source of
 // truth: the route schema in routes/tasks.js references these so the validator
 // and the claim-time context pack (V4.R04 / sessions-start-knowing) can never
@@ -516,6 +552,9 @@ module.exports = {
   _resetVendorCacheForTests,
   VALID_KINDS,
   VALID_DISCIPLINES,
+  WRITABLE_DISCIPLINES,
+  DISCIPLINE_CONFIDENCE_FLOOR,
+  resolveWriteDiscipline,
   VOTABLE_TASK_STATUSES,
   TASK_FIELD_BOUNDS,
 };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.842",
+  "version": "1.19.844",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.842",
+      "version": "1.19.844",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.842",
+  "version": "1.19.844",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/backfill-disciplines.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// scripts/gds/backfill-disciplines.js — task 1002988: give every role-less task a craft.
+//
+// WHY THIS EXISTS SEPARATELY FROM THE MIGRATION. core_247 narrows
+// tasks_discipline_check to {engineer, artist, ideator, ui} and carries a
+// last-resort `UPDATE ... SET discipline='engineer'` so a fresh install can never
+// be blocked on a human remembering to run a script. But that net is a blunt
+// guess. The real classification is classifyTaskDiscipline() — a JS heuristic over
+// title + description + touches that SQL cannot express — so the good pass runs
+// here, first, and the migration only catches what is left.
+//
+// Run this BEFORE deploying core_247. Order matters: rows this script resolves keep
+// a reasoned craft; rows it does not are parked on 'engineer' by the migration.
+//
+// USAGE
+//   node scripts/gds/backfill-disciplines.js              # dry run — the spot-check list
+//   node scripts/gds/backfill-disciplines.js --apply      # commit the PATCHes
+//   node scripts/gds/backfill-disciplines.js --sample 40  # widen the printed sample
+//
+// The dry run is the default on purpose: the task required a spot-check list for the
+// owner BEFORE anything was applied, and 1,189 rows is not a diff anyone reviews in
+// their head.
+
+'use strict';
+
+const { cliClient, requireSession } = require('./cli-lib');
+const { resolveWriteDiscipline, WRITABLE_DISCIPLINES } = require('../../modules/lifecycle/task-classifier.js');
+
+// Rows whose title marks them as test debris. The classifier already skips these
+// (they are not real work), but they still carry 'unclassified' and therefore still
+// violate the narrowed constraint — so they must be resolved, not skipped, or the
+// migration's net silently becomes the thing that handles 164 rows.
+const SMOKE_RE = /__smoke__/;
+
+// The fallback for anything the heuristic refuses. Stated as a constant with its
+// reasoning rather than inlined, because this value is a GUESS and every report
+// below labels it as one.
+const FALLBACK = 'engineer';
+
+function classify(task) {
+  const resolved = resolveWriteDiscipline({
+    title: task.title, description: task.description, touches: task.touches,
+  });
+  if (resolved.discipline) {
+    return { discipline: resolved.discipline, reasoned: true, confidence: resolved.confidence ?? null };
+  }
+  return { discipline: FALLBACK, reasoned: false, confidence: null };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// PATCH one row, WAITING OUT the per-session rate limit rather than counting it as a
+// failure. The first run of this backfill treated a 429 as a failed row and stopped
+// having written 120 of 1,189 — the limiter was doing its job and the script was
+// reading "slow down" as "no". The server tells us how long to wait; honour it.
+// Re-running is safe either way: the query only returns rows still unclassified.
+async function patchWithBackoff(api, id, discipline, maxAttempts = 6) {
+  for (let attempt = 1; ; attempt += 1) {
+    const res = await api.tasks.patchTasksId({ id, body: { discipline } });
+    if (res.status !== 429 || attempt >= maxAttempts) return res;
+    const retryAfter = Number(res.data?.error?.details?.retry_after_seconds);
+    const waitMs = (Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000;
+    console.log(`    rate limited — waiting ${Math.round(waitMs / 1000)}s (attempt ${attempt}/${maxAttempts - 1})`);
+    await sleep(waitMs + 500);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const sampleIdx = args.indexOf('--sample');
+  const sampleSize = sampleIdx >= 0 ? Number(args[sampleIdx + 1]) || 20 : 20;
+
+  await requireSession();
+  const api = await cliClient();
+
+  const r = await api.tasks.getTasks({ query: { discipline: 'unclassified' } });
+  if (!r.ok) {
+    console.error(`failed to read tasks (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  const tasks = r.data?.tasks || [];
+  if (!tasks.length) {
+    console.log('Nothing to do — no task carries discipline=unclassified.');
+    return;
+  }
+
+  const plan = tasks.map((t) => ({ task: t, ...classify(t), smoke: SMOKE_RE.test(t.title || '') }));
+  const reasoned = plan.filter((p) => p.reasoned);
+  const guessed = plan.filter((p) => !p.reasoned);
+  const byDiscipline = {};
+  for (const p of plan) byDiscipline[p.discipline] = (byDiscipline[p.discipline] || 0) + 1;
+
+  console.log(`\n${apply ? 'Applying' : 'DRY RUN —'} discipline backfill over ${plan.length} role-less task(s)\n`);
+  console.log('  Resolved by the classifier (a reasoned answer):');
+  for (const [d, n] of Object.entries(byDiscipline).sort((a, b) => b[1] - a[1])) {
+    const reasonedN = reasoned.filter((p) => p.discipline === d).length;
+    console.log(`    ${d.padEnd(12)} ${String(reasonedN).padStart(5)}`);
+  }
+  console.log(`\n  BEST GUESS (classifier refused → ${FALLBACK}): ${guessed.length}`);
+  console.log(`    of which __smoke__ test debris:            ${guessed.filter((p) => p.smoke).length}`);
+  console.log('    These are NOT determined answers. A later reader must not treat');
+  console.log('    them as evidence that anyone classified the row (owner decision 2026-09-17).\n');
+
+  console.log(`  Spot-check sample — reasoned (first ${sampleSize}):`);
+  for (const p of reasoned.slice(0, sampleSize)) {
+    console.log(`    ${p.discipline.padEnd(9)} ${p.confidence != null ? `(${p.confidence.toFixed(2)})` : '      '}  ${String(p.task.title).slice(0, 72)}`);
+  }
+  console.log(`\n  Spot-check sample — GUESSED (first ${sampleSize}):`);
+  for (const p of guessed.filter((x) => !x.smoke).slice(0, sampleSize)) {
+    console.log(`    ${p.discipline.padEnd(9)}          ${String(p.task.title).slice(0, 72)}`);
+  }
+
+  if (!apply) {
+    console.log(`\nDry run — nothing was written. Re-run with --apply to commit.\n`);
+    return;
+  }
+
+  let ok = 0;
+  const failures = [];
+  for (const p of plan) {
+    const res = await patchWithBackoff(api, p.task.id, p.discipline);
+    if (res.ok) ok += 1;
+    else failures.push({ id: p.task.id, status: res.status, detail: JSON.stringify(res.data).slice(0, 160) });
+    if (ok % 100 === 0 && res.ok) console.log(`  … ${ok}/${plan.length}`);
+  }
+  console.log(`\nApplied: ${ok}/${plan.length}`);
+  if (failures.length) {
+    console.log(`Failed:  ${failures.length}`);
+    for (const f of failures.slice(0, 20)) console.log(`   #${f.id} → ${f.status} ${f.detail}`);
+    process.exitCode = 1;
+  }
+  // Report the residue against the same query, so the number quoted afterwards is
+  // measured rather than assumed.
+  const after = await api.tasks.getTasks({ query: { discipline: 'unclassified' } });
+  const left = after.ok ? (after.data?.tasks || []).length : null;
+  console.log(`Remaining unclassified: ${left == null ? '(re-read failed)' : left}`);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error(e && e.message ? e.message : e); process.exit(1); });
+}
+
+module.exports = { classify, FALLBACK, SMOKE_RE };

package/scripts/gds/fitness-ratchets.js

@@ -197,14 +197,65 @@ function docMetrics() {
 
 // ---------- knip (CI-only, fail-open on infra) ----------
 
+// WHY A LOCAL knip IS REQUIRED BEFORE SCORING (task 1003987).
+//
+// `npx --no-install` does not only look in THIS project: it walks up the directory
+// tree. A git worktree has no node_modules of its own, so the lookup climbs out and
+// finds the main checkout's copy — the command succeeds, and the number it produces is
+// wrong in a specific, repeatable way.
+//
+// MEASURED, not inferred, on 2026-09-17 against one tree:
+//   main checkout (knip local)   -> 221
+//   worktree      (knip ambient) -> 222, the extra being `binaries: package.json knip`
+// Diffed by name, the exports lists were IDENTICAL (221 both sides). knip was
+// reporting ITSELF as an unlisted binary, because from the worktree's point of view it
+// is not a declared dependency of anything resolvable.
+//
+// So the ratchet failed CLOSED on a phantom: 222 > baseline 221, on a tree whose real
+// findings had not moved. That cost a full elimination pass on task 1003848, where the
+// count was the loudest signal pointing away from the actual defect.
+//
+// This module's contract is fail-OPEN on infrastructure and fail-CLOSED on findings.
+// A count measured through an ambient knip is an infrastructure artefact, not a
+// finding, so it must not be scored at all. CI is unaffected: `npm ci` puts knip in
+// the project's own node_modules, which is exactly what this checks for.
+//
+// The row also offered "compare findings by NAME" as the fuller cure. That is a
+// baseline-format change (one integer today) and is deliberately NOT done here; naming
+// the unresolvable case is the "at minimum" it asked for, and it removes the false
+// failure without pretending the count is now environment-proof.
+function localKnipPath() {
+  for (const rel of ['node_modules/knip/package.json', 'node_modules/.bin/knip']) {
+    const p = path.join(ROOT, rel);
+    try { if (fs.existsSync(p)) return p; } catch { /* unreadable → treat as absent */ }
+  }
+  return null;
+}
+
+// Why the last knip score was skipped, or null when it was scored. Module-scoped so
+// the caller can NAME the cause instead of printing one generic line for every
+// unrelated reason knip might not run.
+let knipSkipReason = null;
+function lastKnipSkipReason() { return knipSkipReason; }
+
 function knipIssueCount() {
+  knipSkipReason = null;
+  if (!localKnipPath()) {
+    // Not "knip is missing" — an ambient one may well run. The point is that its
+    // answer is not comparable to the baseline, which was measured with a local one.
+    knipSkipReason = `no knip in ${path.join(ROOT, 'node_modules')} — `
+      + 'npx would resolve one from outside this tree and report it as an unlisted '
+      + 'binary, scoring one higher than the same code scores in CI (task 1003987)';
+    return null;
+  }
   let raw;
   try {
     raw = execSync('npx --no-install knip --reporter json --no-exit-code', {
       cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
     });
   } catch (e) {
-    if (e && e.stdout) raw = e.stdout.toString(); else return null; // knip unavailable → skip
+    if (e && e.stdout) { raw = e.stdout.toString(); }
+    else { knipSkipReason = `npx knip failed to run in ${ROOT}`; return null; }
   }
   try {
     const j = JSON.parse(raw);
@@ -219,6 +270,7 @@ function knipIssueCount() {
     }
     return files + items;
   } catch {
+    knipSkipReason = 'knip produced output this script could not parse as JSON';
     return null;
   }
 }
@@ -426,7 +478,10 @@ function main() {
   if (knipOnly) {
     const value = knipIssueCount();
     if (value === null) {
-      console.warn('fitness-ratchets: WARN — knip not runnable here (no node_modules / npx failure); failing OPEN.');
+      // Name WHY (task 1003987). "not runnable here" sent readers looking for a
+      // broken install when the real answer was that the number would have been
+      // wrong — a different problem with a different fix.
+      console.warn(`fitness-ratchets: WARN — knip not scored: ${lastKnipSkipReason() || 'knip unavailable'}; failing OPEN.`);
       process.exit(0);
     }
     const { metrics: knipBaselines, error: knipBaselineError } = readBaselines();
@@ -466,6 +521,8 @@ module.exports = {
   consoleCallCount,
   isServerPath,
   knipIssueCount,
+  localKnipPath,
+  lastKnipSkipReason,
   OVERSIZE_LINES,
   WINDOW,
   BASELINE_PATH,

package/scripts/gds/init.js

@@ -763,7 +763,12 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   // 2. starter task(s) — linked to the first goal so /status rolls them up
   let created = 0;
   for (const t of starters) {
-    if (await postTask(t, { kind: t.kind || 'unclassified', discipline: undefined, criterion_ids: [criterionId] })) created++;
+    // task 1002988: `discipline: undefined` used to sit in this extras object, and
+    // because `...extra` spreads AFTER postTask's own `t.discipline || 'engineer'`
+    // it clobbered that default back to nothing — which is why a freshly scaffolded
+    // instance was born with role-less starter tasks. Dropped, so starters inherit
+    // the same default every other seeded task already got.
+    if (await postTask(t, { kind: t.kind || 'unclassified', criterion_ids: [criterionId] })) created++;
   }
   // 3. kickoff steps as tracked tasks
   for (const t of kickoff) {

package/scripts/gds/triage.js

@@ -59,6 +59,7 @@ const readline = require('node:readline');
 const fs = require('node:fs');
 const { cliClient, requireSession } = require('./cli-lib');
 const { resolveDefaultVersion } = require('./version-select.js');
+const { resolveWriteDiscipline } = require('../../modules/lifecycle/task-classifier.js');
 
 function prompt(rl, question) {
   return new Promise((resolve) => rl.question(question, (a) => resolve(a)));
@@ -276,6 +277,12 @@ async function createTask({ versionId, title, description, priority, sourceRef,
     priority: priority ?? null,
     source: 'idea_inbox',
     source_ref: sourceRef ?? null,
+    // task 1002988: the server now refuses a task whose craft it cannot infer, and
+    // a 400 in the middle of an interactive triage loop would cost the operator the
+    // promotion they just decided on. So resolve it here with the SAME function the
+    // server uses, and name a fallback rather than letting the loop break — the
+    // identical trade modules/ideas/inbox.js makes for capture.
+    discipline: resolveWriteDiscipline({ title, description }).discipline || 'engineer',
   };
   if (goalId == null) {
     throw new Error('createTask: goal_id is required — every task belongs to a goal (task 1003598 deleted the catch-all fallback).');

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.842'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.844'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/agents_spend_guard.mjs

@@ -25,8 +25,11 @@ import { validateManifest } from '../src/module-loader/manifest-schema.js';
 import ceilingMod from '../modules/agents/lib/spend-ceiling.js';
 import spawnMod from '../modules/agents/spawn.js';
 
-const { createSpendCeiling, payerFor, monthStartUtc, DEFAULT_CAP_USD } = ceilingMod;
-const { plannedRow } = spawnMod;
+const {
+  createSpendCeiling, payerFor, monthStartUtc, agentCapFor,
+  DEFAULT_CAP_USD, DEFAULT_AGENT_CAP_USD,
+} = ceilingMod;
+const { plannedRow, mirrorCostToLedger, costSourceTag } = spawnMod;
 
 // A registry with one metered module and one ordinary one, so every assertion can
 // show that the guard bites the declaring module and NOTHING else.
@@ -270,3 +273,201 @@ test('the ceiling RECORDS NOTHING — the ledger is the only tally', async () =>
     assert.doesNotMatch(sql, /INSERT|UPDATE|DELETE/i);
   }
 });
+
+// ---------------------------------------------------------------------------
+// 4. the per-AGENT monthly ceiling (task 1002499)
+//
+// Its own section, and its own tests against the same hostile pools section 3
+// uses, DELIBERATELY. checkAgent and check now share sumOrNull, and a shared
+// helper's documented safety property is a claim until each caller is shown to
+// honour it — a refactor that made checkAgent swallow a null would pass every
+// test written only against check.
+// ---------------------------------------------------------------------------
+
+const HISTORIAN = { name: 'historian', spend_cap_usd: null };
+
+test('a per-agent cap is SMALLER than the payer cap — it bounds a definition, not a wallet', () => {
+  assert.ok(DEFAULT_AGENT_CAP_USD < DEFAULT_CAP_USD,
+    'if the per-agent default ever reaches the payer default it stops bounding anything: '
+    + 'one agent could spend the whole instance ceiling, which is the case this exists for');
+  assert.equal(DEFAULT_AGENT_CAP_USD, 5, 'the owner decision of 2026-07-05, recorded on task 1002499');
+});
+
+test('under its cap: allowed, with the arithmetic shown', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  const r = await c.checkAgent(poolOf('1.8000'), HISTORIAN);
+  assert.equal(r.ok, true);
+  assert.equal(r.spentUsd, 1.8);
+  assert.equal(r.capUsd, 5);
+  assert.equal(r.remainingUsd, 3.2);
+  assert.equal(r.reason, null);
+});
+
+test('at or past its cap: refused with its OWN code, never the payer one', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  for (const spent of ['5', '5.0001', '90']) {
+    const r = await c.checkAgent(poolOf(spent), HISTORIAN);
+    assert.equal(r.ok, false, spent);
+    assert.equal(r.reason, 'agent_spend_cap_reached', spent);
+    assert.notEqual(r.reason, 'spend_cap_reached',
+      'the two refusals must stay distinguishable: one says raise the instance cap, '
+      + 'the other says raise THIS agent — and under a project payer the wrong advice '
+      + 'raises a number that was never the constraint');
+    assert.equal(r.remainingUsd, 0, spent);
+  }
+});
+
+test('a definition own cap beats the instance default, in BOTH directions', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  const generous = await c.checkAgent(poolOf('7'), { name: 'a', spend_cap_usd: '20.0000' });
+  assert.equal(generous.ok, true, '$7 spent against its own $20 cap is fine, though it is past the default');
+  assert.equal(generous.capUsd, 20);
+  const stingy = await c.checkAgent(poolOf('2'), { name: 'b', spend_cap_usd: '1.5000' });
+  assert.equal(stingy.ok, false, '$2 spent against its own $1.50 cap is over, though it is under the default');
+  assert.equal(stingy.reason, 'agent_spend_cap_reached');
+});
+
+test('agentCapFor: only a positive number overrides; anything else takes the default', () => {
+  assert.equal(agentCapFor({ spend_cap_usd: '12.5' }, 5), 12.5, 'pg NUMERIC arrives as a string');
+  assert.equal(agentCapFor({ spend_cap_usd: 12.5 }, 5), 12.5);
+  assert.equal(agentCapFor({ spend_cap_usd: null }, 5), 5, 'NULL means use the default, never uncapped');
+  assert.equal(agentCapFor({}, 5), 5, 'a projection that dropped the column must not read as uncapped');
+  for (const bad of [0, -1, 'nonsense', NaN, Infinity]) {
+    assert.equal(agentCapFor({ spend_cap_usd: bad }, 5), 5,
+      String(bad) + ' is not a cap this code wrote (agents_004 CHECK forbids it), so it takes the default');
+  }
+});
+
+test('AN UNREADABLE LEDGER REFUSES HERE TOO — checkAgent does not inherit the fix, it must honour it', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  const throwing = { query: async () => { throw new Error('connection terminated'); } };
+  assert.equal((await c.checkAgent(throwing, HISTORIAN)).reason, 'ledger_unreadable');
+  // The shapes that would coerce to a permissive 0. Each is asserted against
+  // checkAgent specifically, because the whole hazard is a sum that LOOKS fine.
+  for (const rows of [[{ spent: null }], [{ spent: undefined }], [{}], [], [{ spent: 'nonsense' }], [{ spent: '-1' }]]) {
+    const r = await c.checkAgent({ query: async () => ({ rows }) }, HISTORIAN);
+    assert.equal(r.ok, false, JSON.stringify(rows));
+    assert.equal(r.reason, 'ledger_unreadable', JSON.stringify(rows));
+    assert.equal(r.spentUsd, null, 'a refusal that could not read must not claim a sum');
+  }
+  assert.equal((await c.checkAgent(null, HISTORIAN)).reason, 'ledger_unreadable', 'no pool at all');
+});
+
+test('no usable cap and no agent identity both REFUSE — an unbounded agent is the defect wearing a cap name', async () => {
+  for (const cap of [0, -5, NaN, 'nonsense']) {
+    const c = createSpendCeiling({ agentCapUsd: cap, now: () => AT });
+    const r = await c.checkAgent(poolOf('0'), { name: 'x', spend_cap_usd: null });
+    assert.equal(r.ok, false, String(cap));
+    assert.equal(r.reason, 'no_agent_spend_cap_configured', String(cap));
+  }
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  for (const definition of [null, {}, { name: '' }, { name: '   ' }, { name: 42 }]) {
+    const r = await c.checkAgent(poolOf('0'), definition);
+    assert.equal(r.ok, false, JSON.stringify(definition));
+    assert.equal(r.reason, 'no_agent_identity', JSON.stringify(definition));
+  }
+});
+
+test('the agent sum is keyed on agent_name and the calendar month — not definition_id', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  let sql = null; let params = null;
+  await c.checkAgent({ query: async (s, p) => { sql = s; params = p; return { rows: [{ spent: '0' }] }; } }, HISTORIAN);
+  assert.match(sql, /agent_name\s*=\s*\$2/, 'keyed on the NAME');
+  assert.doesNotMatch(sql, /definition_id/,
+    'definition_id is ON DELETE SET NULL, so keying on it would zero an agent month '
+    + 'when its definition is deleted and hand a re-created agent a fresh cap');
+  assert.doesNotMatch(sql, /payer_kind/, 'a per-agent cap spans every payer — that is the point');
+  assert.equal(params[0].toISOString(), '2026-09-01T00:00:00.000Z');
+  assert.equal(params[1], 'historian');
+});
+
+test('checkAgent RECORDS NOTHING either — agents_runs stays the only tally', async () => {
+  const c = createSpendCeiling({ agentCapUsd: 5, now: () => AT });
+  const statements = [];
+  const pool = { query: async (s) => { statements.push(s); return { rows: [{ spent: '1' }] }; } };
+  await c.checkAgent(pool, HISTORIAN);
+  await c.checkAgent(pool, HISTORIAN);
+  assert.equal(statements.length, 2);
+  for (const s of statements) {
+    assert.match(s, /^\s*SELECT/i);
+    assert.doesNotMatch(s, /INSERT|UPDATE|DELETE/i);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 5. the cost mirror (task 1002499) — what makes the fleet-wide brake able to
+//    see agent spend at all
+// ---------------------------------------------------------------------------
+
+const mirrorPort = () => {
+  const rows = [];
+  return { rows, logCost: async (r) => { rows.push(r); return { id: 1 }; } };
+};
+
+test('the source tag is the agent: family the MTD brake matches on', () => {
+  assert.equal(costSourceTag('historian'), 'agent:historian');
+  assert.ok(costSourceTag('x').startsWith('agent:'),
+    'the prefix is a CONTRACT: modules/economy/cost.js widens the autonomous MTD sum to '
+    + 'source LIKE agent:%, so a tag outside the family is spend the brake cannot see');
+});
+
+test('a completed fire mirrors its cost, keyed so a retry cannot double-post', async () => {
+  const economy = mirrorPort();
+  const wrote = await mirrorCostToLedger(
+    { runId: 77, definition: { name: 'historian' }, costUsd: 0.9123, builderId: 25 }, { economy },
+  );
+  assert.equal(wrote, true);
+  assert.equal(economy.rows.length, 1);
+  const row = economy.rows[0];
+  assert.equal(row.amountUsd, 0.9123);
+  assert.equal(row.category, 'api', 'the category the brake filters on, beside the source');
+  assert.equal(row.source, 'agent:historian');
+  assert.equal(row.sourceRef, 'agent-run-77',
+    'logCost is insert-once on (source, source_ref), and the run id is the one value '
+    + 'unique per fire — the alternative to a stable key here is double-counting money');
+  assert.equal(row.builderId, 25, 'who ASKED; the PAYER lives on the agents_runs row');
+});
+
+test('nothing to mirror is not an error, and nothing is written', async () => {
+  for (const args of [
+    { runId: 1, definition: { name: 'a' }, costUsd: 0 },
+    { runId: 1, definition: { name: 'a' }, costUsd: null },
+    { runId: 1, definition: { name: 'a' }, costUsd: -1 },
+    { runId: 1, definition: { name: 'a' }, costUsd: '0.9' },
+    { runId: null, definition: { name: 'a' }, costUsd: 0.9 },
+    { runId: 1, definition: {}, costUsd: 0.9 },
+    { runId: 1, definition: null, costUsd: 0.9 },
+  ]) {
+    const economy = mirrorPort();
+    assert.equal(await mirrorCostToLedger(args, { economy }), false, JSON.stringify(args));
+    assert.equal(economy.rows.length, 0, 'a cost_log row with no fire behind it must not be possible');
+  }
+});
+
+test('the mirror FAILS OPEN and says so — the opposite direction from the ceilings, on purpose', async () => {
+  // The ceilings fail closed because they decide whether to SPEND. This runs after
+  // the money is gone and the agents_runs row is written, so refusing here would
+  // discard a completed fire result to fix a reporting row.
+  const economy = { logCost: async () => { throw new Error('cost_log unreachable'); } };
+  const warnings = [];
+  const log = { warn: (fields, msg) => warnings.push({ fields, msg }) };
+  assert.equal(await mirrorCostToLedger(
+    { runId: 9, definition: { name: 'historian' }, costUsd: 0.9 }, { economy, log },
+  ), false);
+  assert.equal(warnings.length, 1, 'silence would leave the brake under-counting with nothing to notice it');
+  // STRUCTURED, not a formatted string: the run id and the agent are fields an
+  // operator can filter the journal by, which is the point of naming them at all.
+  assert.equal(warnings[0].fields.run_id, 9, 'names the run');
+  assert.equal(warnings[0].fields.agent, 'historian', 'names the agent');
+  assert.match(warnings[0].fields.err, /cost_log unreachable/, 'and what actually went wrong');
+  assert.match(warnings[0].msg, /under-counting/, 'and says what the consequence is');
+});
+
+test('no economy port: no throw, no write — an instance may run agents without economy', async () => {
+  assert.equal(await mirrorCostToLedger(
+    { runId: 1, definition: { name: 'a' }, costUsd: 0.9 }, { economy: null },
+  ), false);
+  assert.equal(await mirrorCostToLedger(
+    { runId: 1, definition: { name: 'a' }, costUsd: 0.9 }, { economy: {} },
+  ), false, 'a port without logCost is the same as no port — ADR 0083 degrades, it does not crash');
+});