@bongos/core 1.19.733 → 1.19.735

package/scripts/gds/package-core.js

@@ -59,8 +59,11 @@
 //                    (task 1002218 / audit H3) — deterministic + network-free.
 //   --self-verify-boot   ALSO `npm install <tgz>` into a throwaway consumer + boot /healthz
 //                    (reuses tests/consumer_layout_boot.mjs; needs npm/registry access).
-//   --leak-scan-strict   make the post-build leak scan FATAL on any prior-instance literal
-//                    (default: the scan runs + WARNS; --no-leak-scan skips it). task 1002220 / H6.
+//   --no-leak-scan   THE ONLY ESCAPE from the post-build leak scan: skips it entirely.
+//                    The scan is FAIL-CLOSED by default — an un-allowlisted prior-instance
+//                    literal in the built artifact aborts the build (task 1003870 / H6).
+//   --leak-scan-strict   accepted as an explicit no-op; fatal IS the default since task
+//                    1003870. Kept so CI can state the intent it relies on out loud.
 //   Outputs (nothing is committed — dist/ is gitignored):
 //     dist/bongos-core-<version>/           the redacted core tree (inspectable)
 //     dist/bongos-core-<version>.tgz        the installable unit
@@ -629,6 +632,18 @@ function scanKindOf(pathRel) {
   return 'functional';
 }
 
+// The post-build leak scan's POLICY, split out of main() so a test can plant a literal and prove
+// the build refuses without running a full 2-minute package (task 1003870). Pure: argv in, verdict
+// out. Fail-closed — any un-allowlisted prior-instance literal is fatal unless the operator has
+// explicitly said --no-leak-scan, which skips the scan altogether rather than downgrading it.
+// `--leak-scan-strict` is honoured as a no-op: it named this behaviour before it became default.
+function leakScanVerdict(remainingLiteralHits, argv = process.argv) {
+  if (argv.includes('--no-leak-scan')) return { run: false, fatal: false, reason: 'skipped' };
+  const n = (remainingLiteralHits || []).length;
+  if (n === 0) return { run: true, fatal: false, reason: 'clean' };
+  return { run: true, fatal: true, reason: 'prior-instance-literals' };
+}
+
 // Independent post-build leak scan over the built core file set (task 1002220 / audit H6). Two layers:
 //   • INSTANCE LITERALS — findLeaks() over PRIOR_INSTANCE_LITERALS (+ the public-IP floor) across
 //     EVERY shipped file: brand/owner/history that must not ship in a portable core. This is the
@@ -942,14 +957,14 @@ function main() {
 
   // Post-build leak scan (task 1002220 / audit H6): independent verification that the BUILT
   // artifact carries no prior-instance identity, + a warn-level secret-shape scan over functional
-  // files. Runs on every build (skip with --no-leak-scan). Prior-instance literals are a WARNING
-  // by default and a hard FAILURE under --leak-scan-strict (the trunk still carries residual
-  // history until task 1002219 sweeps it + task 1002217 adds the fail-closed floor gate). A
-  // secret-shape hit is ALWAYS a non-fatal warning — the R88 functional-verbatim fix is preserved.
+  // files. Runs on every build and is FAIL-CLOSED: an un-allowlisted prior-instance literal aborts
+  // the build. The trunk sweep (task 1003869) cleared the residue those literals used to represent,
+  // so warning instead of failing would only let it creep back (task 1003870). --no-leak-scan is
+  // the sole escape. A secret-shape hit stays a non-fatal warning — those 14 files were each
+  // confirmed a test fixture (task 1003871) and the R88 functional-verbatim fix is preserved.
   if (!process.argv.includes('--no-leak-scan')) {
     const scanFiles = staged.map((s) => ({ path: s.name.startsWith(TAR_ROOT) ? s.name.slice(TAR_ROOT.length) : s.name, content: s.buf }));
     const scan = scanArtifactForLeaks(scanFiles);
-    const strict = process.argv.includes('--leak-scan-strict');
     // Named, reasoned exceptions (task 1003869). A detector must carry the pattern it
     // detects and a "public IPs are flagged" test must be handed a public IP, so those
     // hits are real but not leaks. Each is listed per (file, literal) with its reason in
@@ -966,17 +981,21 @@ function main() {
       for (const e of stale) console.error(`   ${e.path}  [${e.literal}]`);
     }
     scan.literalHits = remaining;
+    const verdict = leakScanVerdict(scan.literalHits);
     if (scan.literalHits.length) {
       const byLit = {};
       for (const h of scan.literalHits) byLit[h.sample] = (byLit[h.sample] || 0) + 1;
       const summary = Object.entries(byLit).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k}×${n}`).join(', ');
       const files = [...new Set(scan.literalHits.map((h) => h.path))];
       console.error('');
-      console.error(`[leak-scan] ${strict ? 'FAILED' : 'WARNING'} — ${scan.literalHits.length} prior-instance literal hit(s) across ${files.length} shipped file(s): ${summary}`);
+      console.error(`[leak-scan] FAILED — ${scan.literalHits.length} prior-instance literal hit(s) across ${files.length} shipped file(s): ${summary}`);
       for (const p of files.slice(0, 30)) console.error(`   ${p}`);
       if (files.length > 30) console.error(`   … +${files.length - 30} more file(s)`);
-      if (strict) { console.error('[leak-scan] --leak-scan-strict: refusing to certify a leaky artifact.'); process.exit(1); }
-      console.error('[leak-scan] non-fatal for now — the trunk sweep (task 1003869) is clearing the residue; it becomes a hard gate when task 1003870 arms publish.yml. Run --leak-scan-strict to enforce today.');
+      console.error('[leak-scan] refusing to certify a leaky artifact. Either remove the literal at SOURCE (check what');
+      console.error('[leak-scan] REGENERATES the file — a generator re-leaks on every run, task 1003911), or, if the hit is');
+      console.error('[leak-scan] a detector carrying its own pattern, add a named (path, class) reason to');
+      console.error('[leak-scan] scripts/gds/leak-scan-allowlist.js. --no-leak-scan skips this gate entirely.');
+      if (verdict.fatal) process.exit(1);
     } else {
       console.error('[leak-scan] ✓ no prior-instance literals in the built artifact.');
     }
@@ -1021,6 +1040,8 @@ module.exports = {
   selfVerify, reproducePinFromTree,
   // task 1002220 (audit H6) — post-build leak scan (prior-instance literals + functional secret shapes)
   scanArtifactForLeaks, PRIOR_INSTANCE_LITERALS,
+  // task 1003870 — the fail-closed verdict the build acts on (pure, so a test can plant a literal)
+  leakScanVerdict,
   // task 1002217 (audit H4) — the fixed neutral floor injected into the doc-redaction + fail-closed gate
   PRIOR_INSTANCE_FLOOR,
 };

package/src/branding.js

@@ -77,6 +77,12 @@ const ENV_OVERRIDES = [
   // that has been strict since it stood up.
   ['ARTIST_GATE', ['project', 'artistGate']],
   ['ARTIST_GATE_SINCE', ['project', 'artistGateSince']],
+  // Who pays when a module spends money for whoever called it (task 1003884) —
+  // none | project | builder. src/modules.js reads it through this pack at config
+  // load and REFUSES to enable a module that declares metered spend while the join
+  // door is `open` and this is `none`. Like its neighbours it is memoized for the
+  // process, which is why the platform restarts the instance to apply a change.
+  ['SPEND_PAYER', ['project', 'spendPayer']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -265,6 +271,13 @@ function clientBranding(b = branding()) {
       // DEFAULT, which for this one key is 'strict' rather than today's behaviour
       // — the owner's ruling, ADR 0241 §4.
       artistGate: b.project?.artistGate || 'strict',
+      // Who pays for metered module spend (task 1003884). Published for the same
+      // read-back reason as its neighbours — and for one of its own: this is the
+      // key that can REFUSE a module, so an owner looking at a module that will
+      // not turn on needs the instance's own answer to "what did it restart
+      // with?", not the platform's record of what they saved. The fallback is the
+      // platform default, which for this key IS today's behaviour.
+      spendPayer: b.project?.spendPayer || 'none',
     },
   };
 }

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.733'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.735'; // 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/src/module-loader/loader.js

@@ -128,6 +128,12 @@ function discoveredRegistry(opts) {
       _dir: dir,
       _provides: manifest.provides || [],
       _consumes: manifest.consumes || [],
+      // The module's own declaration that it METERS money on a caller's behalf
+      // (task 1003884). Projected here because src/modules.js refuses to enable
+      // such a module where anyone can sign up and nobody is on the hook — and a
+      // kernel file may not name a module key (fitness Check 10), so the
+      // declaration has to travel WITH the manifest rather than be looked up.
+      _spend: manifest.spend || {},
     };
   }
   return out;

package/src/module-loader/manifest-schema.js

@@ -39,6 +39,12 @@
 //                                       //   the APEX ROOT — never both (ADR 0218).
 //       "migrations":  true             //   true => modules/<key>/migrations/ exists (or an array of names)
 //     },
+//     "spend": {                        // OPTIONAL. This module METERS money on a caller's behalf
+//       "requiresPayer": true           //   (task 1003884) — its surfaces can spend real money for
+//     },                                //   whoever calls them, so the core must know WHO PAYS before
+//                                       //   it may be enabled where anyone can sign up. src/modules.js
+//                                       //   refuses the enablement when the join door is `open` and no
+//                                       //   payer is configured.
 //     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
 //     "consumes":      ["grade"],       // OPTIONAL. seam ports this module resolves (required capabilities).
 //     "prerequisites": { "modules": ["economy"] },  // OPTIONAL. other modules that must be enabled.
@@ -77,6 +83,16 @@ const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
 //                    optionally a `removeAfter` core version.
 //   orphaned         nobody owns it. Still needs a `note`/`successor` so the
 //                    next reader knows the situation, not just the label.
+// The `spend` block (task 1003884). A module declaring `requiresPayer: true` is
+// saying its surfaces can spend real money on behalf of whoever calls them — so
+// the core refuses to ENABLE it on an instance whose join door is `open` with no
+// configured payer (src/modules.js). Closed key set for the same reason
+// `contributes` and `maintenance` have one: a typo'd "requirespayer" would
+// silently declare NO spend, and that is the direction that costs money.
+// Deliberately NOT exported: the validator and its own error message are the only
+// readers, and an export nothing imports is dead weight the knip ratchet counts.
+const SPEND_KEYS = ['requiresPayer'];
+
 const MAINTENANCE_STATUSES = ['core-maintained', 'maintained', 'deprecated', 'orphaned'];
 const MAINTENANCE_KEYS = ['status', 'since', 'removeAfter', 'successor', 'note'];
 // Statuses that describe a module on its way out — these owe a deprecation path.
@@ -190,6 +206,20 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional spend declaration (task 1003884) ---
+  if ('spend' in obj) {
+    const sp = obj.spend;
+    if (!isObj(sp)) E('spend: must be an object (e.g. { "requiresPayer": true })');
+    else {
+      for (const k of Object.keys(sp)) {
+        if (!SPEND_KEYS.includes(k)) E(`spend.${k}: unknown key (allowed: ${SPEND_KEYS.join(', ')})`);
+      }
+      if ('requiresPayer' in sp && typeof sp.requiresPayer !== 'boolean') {
+        E('spend.requiresPayer: must be a boolean when present');
+      }
+    }
+  }
+
   // --- optional seam declarations ---
   if ('provides' in obj && !isStrArray(obj.provides)) E('provides: must be an array of non-empty strings (port names)');
   if ('consumes' in obj && !isStrArray(obj.consumes)) E('consumes: must be an array of non-empty strings (port names)');

package/src/modules.js

@@ -118,10 +118,75 @@ function coerceBool(v) {
   return undefined;
 }
 
+// WHO PAYS for metered module spend on this instance (task 1003884). Two
+// answers are a payer and the absence of one is not: `project` puts the bill on
+// whoever runs the instance, `builder` on the caller who spent it. Anything else
+// — unset, empty, a typo, a value from a newer core — is NO payer, which is the
+// reading that costs nobody money by accident.
+const PAYERS = Object.freeze(['project', 'builder']);
+
+// Does this registry entry declare that its surfaces spend real money on behalf
+// of whoever calls them? The declaration lives in the module's own module.json
+// (`"spend": { "requiresPayer": true }`) and rides through the loader as `_spend`,
+// because fitness Check 10 forbids the kernel from naming a module key — the
+// guard below has to be true of any module that says this about itself, not of
+// one the resolver has heard of.
+const metersSpend = (entry) => !!(entry && entry._spend && entry._spend.requiresPayer === true);
+
+// The spend guard's own posture. `joinDoorOpen` is "any GitHub account becomes a
+// builder seconds after signing up" — the composed join door, not the
+// `joinability` knob alone (src/bongos/project-door.js).
+const NO_SPEND_RISK = Object.freeze({ joinDoorOpen: false, payer: null });
+
+// WHICH enabled modules must be REFUSED, and why this is a config-load decision.
+//
+// A module that meters spend for its callers is safe in exactly two situations:
+// the people who can call it were let in deliberately (the door is not open), or
+// somebody is on the hook for the bill (a payer is configured, and the module's
+// own per-payer ceiling bounds it). With an OPEN door and NO payer, an account
+// created seconds ago can spend the instance's money with nobody to bill and no
+// cap to stop it — so the enablement itself is refused.
+//
+// AT CONFIG LOAD, NOT AT FIRST CALL. A per-request check would let the module
+// mount, advertise its routes in the manifest, run its migrations and appear
+// enabled everywhere the UI reads `modules.enabled` — and then refuse one caller
+// at a time, which is a broken feature rather than a closed door. Refusing the
+// enablement means the surface never exists.
+//
+// PURE, and exported for direct unit testing: the fail-closed reading of an
+// UNKNOWN posture belongs to loadModules, which is where "unknown" can arise.
+function spendRefusals(resolved, registry, { joinDoorOpen = false, payer = null } = {}) {
+  if (!joinDoorOpen) return [];
+  if (PAYERS.includes(payer)) return [];
+  return Object.keys(resolved).filter((k) => resolved[k] === true && metersSpend(registry[k]));
+}
+
+// The refusal is LOUD. A module silently resolving to off is how an operator
+// spends an afternoon wondering why their routes 404 — and this one is refusing
+// something they explicitly asked for, so it has to say what to do about it.
+// `log` is injectable for the same reason instance-config's legacy-env warning
+// injects it: a test asserts the warning fired, not only that the value resolved.
+function warnSpendRefusal(key, envPrefix, log = console) {
+  log.warn(
+    `[bongos] module "${key}" is enabled in config but was REFUSED: it spends money on behalf of `
+    + `whoever calls it, this project's join door is \`open\` (anyone may sign up), and no payer is `
+    + `configured — so a stranger's spend would have nobody to bill. Set ${envPrefix}_SPEND_PAYER to `
+    + `${PAYERS.join(' or ')} (the platform pushes it from the project's \`spend_payer\` setting), or `
+    + `close the join door. The module stays OFF until then.`,
+  );
+}
+
 // Pure resolver — all inputs injected, so tests drive it with zero I/O.
 // Returns a frozen { <moduleKey>: boolean } covering EVERY registry key, plus a
 // non-enumerable resolution that throws on an unknown module key (typo guard).
-function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = FALLBACK_ENV_PREFIX, registry = MODULE_REGISTRY } = {}) {
+function resolveModules({
+  neutral = {}, instance = {}, env = {}, envPrefix = FALLBACK_ENV_PREFIX, registry = MODULE_REGISTRY,
+  // The spend guard's inputs (task 1003884). Defaulted to "no risk" so every
+  // caller that does not know about spend resolves exactly as before; loadModules
+  // is the one that reads the real posture, and the one that fails closed when it
+  // cannot.
+  spendGuard = NO_SPEND_RISK, warn = warnSpendRefusal,
+} = {}) {
   // The known-key set + defaults come from the passed registry: callers inject
   // the built-in MODULE_REGISTRY (the default, what the pure unit tests use) or
   // the effective built-in+discovered registry (what loadModules passes). This
@@ -175,6 +240,14 @@ function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = FAL
     const v = key in merged ? coerceBool(merged[key]) : undefined;
     resolved[key] = v === undefined ? registry[key].default : v;
   }
+  // THE SPEND GUARD, applied LAST — after config, after env, after the default.
+  // It is deliberately not another precedence level: a refusal that env could
+  // outrank would be a suggestion, and the whole point is that the one knob an
+  // untrusted-but-cheap deploy would reach for cannot turn it back on.
+  for (const key of spendRefusals(resolved, registry, spendGuard)) {
+    resolved[key] = false;
+    warn(key, envPrefix);
+  }
   return Object.freeze(resolved);
 }
 
@@ -220,9 +293,37 @@ function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.e
   // Reuse the branding env prefix so an instance has ONE prefix, not two.
   let envPrefix = FALLBACK_ENV_PREFIX;
   try { envPrefix = require('./branding').branding().envPrefix || envPrefix; } catch { /* fail-to-default */ }
+  // THE SPEND POSTURE, read once per load (task 1003884): is this project's
+  // composed join door `open`, and has the owner said who pays?
+  //
+  // `effectiveJoinDoor() === 'open'` is LITERALLY the expression openEnrollmentEnabled
+  // is defined as (src/bongos/auth-admission.js), read from the composer rather than
+  // through the gate so this file does not pull in the whole sign-in stack. That
+  // identity is the point: the guard and the gate that actually admits strangers
+  // cannot answer one stranger differently, which is the same argument task 1003579
+  // made when it moved the gate onto the composed door.
+  //
+  // WHAT THE CATCH COVERS, stated precisely rather than generously. A pack that
+  // fails to PARSE never reaches here — effectiveJoinDoor swallows that itself and
+  // resolves the default door, `apply`, which is closed. That is not a fail-open
+  // hole: the real admission gate reads the same broken pack and refuses the same
+  // self-enrolment, so a door this guard reads as closed IS closed. The catch is
+  // for the harder failure — the require itself throwing, in tooling that has no
+  // such file — and THERE the default is the dangerous reading rather than the
+  // convenient one, because the thing being guarded is money leaving the account.
+  // The blast radius of being wrong is one module resolving OFF, and since every
+  // module defaults to off, an instance that never enabled one notices nothing.
+  let spendGuard = { joinDoorOpen: true, payer: null };
+  try {
+    // Both are KERNEL files (fitness Check 12), required lazily for the same
+    // reason branding is just above: require-time must never crash tooling.
+    const { effectiveJoinDoor } = require('./bongos/project-door'); // eslint-disable-line global-require
+    const project = require('./branding').branding().project || {}; // eslint-disable-line global-require
+    spendGuard = { joinDoorOpen: effectiveJoinDoor() === 'open', payer: project.spendPayer || null };
+  } catch { /* unreadable posture — the fail-closed default above stands */ }
   // Resolve against the EFFECTIVE registry (built-in + discovered) so a config
   // flag for a discovered module is honored. No-op until a module exists.
-  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry() });
+  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry(), spendGuard });
 }
 
 // Resolved singleton for app code; lazy so require-time never crashes tooling.
@@ -282,6 +383,10 @@ module.exports = {
   effectiveRegistry,
   knownModules,
   CORE_DISCIPLINES,
+  PAYERS,
+  metersSpend,
+  spendRefusals,
+  warnSpendRefusal,
   resolveModules,
   loadModules,
   modules,

package/tests/agents_spend_guard.mjs

@@ -0,0 +1,272 @@
+// tests/agents_spend_guard.mjs — the spend guard and the per-payer spend ceiling
+// (task 1003884).
+//
+// Two independent walls, tested apart because they fail in different directions:
+//
+//   1. the CONFIG-LOAD guard (src/modules.js) — a module that declares it meters
+//      money for its callers is not ENABLED at all on an instance whose join door
+//      is `open` with no payer configured;
+//   2. the per-payer MONTHLY CEILING (modules/agents/lib/spend-ceiling.js) — a
+//      payer who has spent their month cannot fire, and so, deliberately, cannot
+//      anyone whose ceiling could not be established.
+//
+// The second is where task 1001393's defect is pinned: that spend brake read
+// month-to-date spend from a database it could not reach and FAILED OPEN, so it
+// never tripped. Several cases below exist only to assert this one fails closed.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+// Imported BY NAME rather than destructured off a default import: knip cannot
+// follow a name through `import mod from '...'` + `const { x } = mod`, so the
+// guard's tested exports would read as dead code and the ratchet would block the
+// merge on a file whose every export is genuinely used right here.
+import { resolveModules, spendRefusals, metersSpend, PAYERS, warnSpendRefusal } from '../src/modules.js';
+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;
+
+// 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.
+const REG = {
+  metered: { default: false, contributes: {}, _spend: { requiresPayer: true } },
+  plain: { default: false, contributes: {} },
+};
+const BOTH_ON = { modules: { metered: true, plain: true } };
+const silent = () => {};
+const resolve = (spendGuard, extra = {}) =>
+  resolveModules({ instance: BOTH_ON, registry: REG, spendGuard, warn: silent, ...extra });
+
+// ---------------------------------------------------------------------------
+// 1. the config-load guard
+// ---------------------------------------------------------------------------
+
+test('an OPEN join door with NO payer refuses the metered module — and only that one', () => {
+  const m = resolve({ joinDoorOpen: true, payer: null });
+  assert.equal(m.metered, false, 'anyone can sign up and nobody is on the hook — it must not mount');
+  assert.equal(m.plain, true, 'a module that never said it spends money is untouched');
+});
+
+test('a CLOSED join door leaves it enabled: the people who can call it were let in deliberately', () => {
+  assert.equal(resolve({ joinDoorOpen: false, payer: null }).metered, true);
+});
+
+test('an open door WITH a payer leaves it enabled — somebody is on the hook, and the ceiling bounds them', () => {
+  for (const payer of PAYERS) {
+    assert.equal(resolve({ joinDoorOpen: true, payer }).metered, true, payer);
+  }
+});
+
+test('anything that is not one of the two payer words is NO payer', () => {
+  // The direction that matters: a typo, a stale value, or a word a newer core
+  // understands must never read as "somebody is paying".
+  for (const bad of ['Project', 'BUILDER', 'none', '', ' project', 'owner', null, undefined, 0, true]) {
+    assert.equal(resolve({ joinDoorOpen: true, payer: bad }).metered, false, JSON.stringify(bad));
+  }
+});
+
+test('the refusal outranks the env override — it is a wall, not another precedence level', () => {
+  // <PREFIX>_MODULE_METERED=1 is the highest-precedence way to turn a module on,
+  // and it is exactly the knob a cheap deploy reaches for. It must not lift this.
+  const m = resolveModules({
+    instance: { modules: { metered: false } },
+    env: { BONGOS_MODULE_METERED: '1' },
+    envPrefix: 'BONGOS',
+    registry: REG,
+    spendGuard: { joinDoorOpen: true, payer: null },
+    warn: silent,
+  });
+  assert.equal(m.metered, false, 'env cannot buy its way past the guard');
+});
+
+test('the refusal is LOUD: it names the module, the two payer words and the env var that lifts it', () => {
+  const said = [];
+  resolveModules({
+    instance: BOTH_ON, registry: REG, envPrefix: 'MERCURY',
+    spendGuard: { joinDoorOpen: true, payer: null },
+    warn: (key, prefix) => said.push([key, prefix]),
+  });
+  assert.deepEqual(said, [['metered', 'MERCURY']], 'exactly the refused module, under this pack\'s prefix');
+
+  // And the default warner writes something an operator can act on, under the
+  // instance's OWN prefix rather than a hardcoded one.
+  const lines = [];
+  warnSpendRefusal('metered', 'MERCURY', { warn: (s) => lines.push(s) });
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /metered/);
+  assert.match(lines[0], /MERCURY_SPEND_PAYER/, 'names the variable, under the right prefix');
+  for (const p of PAYERS) assert.match(lines[0], new RegExp(p), `names the ${p} payer`);
+});
+
+test('callers that know nothing about spend resolve exactly as before', () => {
+  // Every existing call site passes no spendGuard. The default must change nothing
+  // — the fail-closed reading belongs to loadModules, where "unknown" can arise.
+  assert.equal(resolveModules({ instance: BOTH_ON, registry: REG }).metered, true);
+});
+
+test('metersSpend reads the module\'s own declaration, and only a literal true', () => {
+  assert.equal(metersSpend({ _spend: { requiresPayer: true } }), true);
+  for (const bad of [undefined, null, {}, { _spend: {} }, { _spend: { requiresPayer: 'true' } }, { _spend: { requiresPayer: 1 } }]) {
+    assert.equal(metersSpend(bad), false, JSON.stringify(bad));
+  }
+});
+
+test('spendRefusals never names a module that was already off', () => {
+  const off = { metered: false, plain: false };
+  assert.deepEqual(spendRefusals(off, REG, { joinDoorOpen: true, payer: null }), []);
+});
+
+test('the manifest declaration is a CLOSED key set — a typo must not read as "no spend"', () => {
+  const base = { key: 'x', title: 't', description: 'd', coreVersion: '^1.0.0', contributes: {} };
+  assert.equal(validateManifest({ ...base, spend: { requiresPayer: true } }).valid, true);
+  assert.equal(validateManifest({ ...base, spend: { requirespayer: true } }).valid, false,
+    'a misspelled key silently declaring NO spend is the direction that costs money');
+  assert.equal(validateManifest({ ...base, spend: { requiresPayer: 'yes' } }).valid, false);
+  assert.equal(validateManifest({ ...base, spend: true }).valid, false);
+});
+
+test('the agents module actually declares it — the guard guards something', () => {
+  // The whole chain is inert if the manifest never says so, and that failure is
+  // invisible: everything still resolves, nothing is ever refused.
+  const manifest = JSON.parse(readFileSync(new URL('../modules/agents/module.json', import.meta.url), 'utf8'));
+  assert.equal(manifest.spend && manifest.spend.requiresPayer, true);
+  assert.equal(manifest.default, false, 'and it still ships disabled');
+});
+
+// ---------------------------------------------------------------------------
+// 2. who pays for one fire
+// ---------------------------------------------------------------------------
+
+test('payerFor: `builder` bills the caller, everything else bills the project', () => {
+  assert.deepEqual(payerFor('builder', 7), { payer_kind: 'builder', payer_builder_id: 7 });
+  assert.deepEqual(payerFor('project', 7), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor('none', 7), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor(null, 7), { payer_kind: 'project', payer_builder_id: null });
+});
+
+test('an event fire has no caller, so it can only be the project — never nobody', () => {
+  // Nobody asked for it, so there is nobody to bill; falling to "no payer" would
+  // make the event path the one unbounded route through the ceiling.
+  assert.deepEqual(payerFor('builder', null), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor('builder', undefined), { payer_kind: 'project', payer_builder_id: null });
+});
+
+test('every ledger row carries a payer — including a no-go, which cost nothing', () => {
+  const go = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'go' }, requestedByBuilderId: 4, spendPayer: 'builder' });
+  assert.equal(go.payer_kind, 'builder');
+  assert.equal(go.payer_builder_id, 4);
+
+  const nogo = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'no-go', reason: 'x' }, requestedByBuilderId: 4, spendPayer: 'builder' });
+  assert.equal(nogo.status, 'skipped');
+  assert.equal(nogo.payer_kind, 'builder', 'a refusal is still a fire somebody would have been billed for');
+});
+
+test('who ASKED and who PAYS are different columns, and differ under a project payer', () => {
+  const row = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'go' }, requestedByBuilderId: 9, spendPayer: 'project' });
+  assert.equal(row.requested_by_builder_id, 9);
+  assert.equal(row.payer_kind, 'project');
+  assert.equal(row.payer_builder_id, null, 'the project pays; the asker is recorded but not billed');
+});
+
+// ---------------------------------------------------------------------------
+// 3. the per-payer monthly ceiling — every branch fails CLOSED
+// ---------------------------------------------------------------------------
+
+const poolOf = (spent) => ({ query: async () => ({ rows: [{ spent }] }) });
+const AT = Date.UTC(2026, 8, 13, 12, 0, 0); // 2026-09-13
+const PROJECT = { payer_kind: 'project', payer_builder_id: null };
+
+test('under the cap: allowed, with the arithmetic shown', () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  return c.check(poolOf('4.5000'), PROJECT).then((r) => {
+    assert.equal(r.ok, true);
+    assert.equal(r.spentUsd, 4.5);
+    assert.equal(r.remainingUsd, 20.5);
+    assert.equal(r.reason, null);
+  });
+});
+
+test('at or past the cap: refused, and the refusal says which', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  for (const spent of ['25', '25.0001', '900']) {
+    const r = await c.check(poolOf(spent), PROJECT);
+    assert.equal(r.ok, false, spent);
+    assert.equal(r.reason, 'spend_cap_reached', spent);
+    assert.equal(r.remainingUsd, 0, spent);
+  }
+});
+
+test('AN UNREADABLE LEDGER REFUSES — the exact defect task 1001393 was filed about', async () => {
+  // That brake read month-to-date spend from a DB it could not reach and fell
+  // through to "go ahead". "I cannot tell what has been spent" is the moment a
+  // ceiling matters most.
+  const throws = { query: async () => { throw new Error('ECONNREFUSED'); } };
+  const r = await createSpendCeiling({ capUsd: 25, now: () => AT }).check(throws, PROJECT);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'ledger_unreadable');
+  assert.equal(r.spentUsd, null, 'it must not claim a sum it does not have');
+});
+
+test('a missing pool, and a sum that is not a number, are the same "I do not know"', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  assert.equal((await c.check(null, PROJECT)).reason, 'ledger_unreadable');
+  assert.equal((await c.check({}, PROJECT)).reason, 'ledger_unreadable');
+  for (const junk of ['abc', null, undefined, -1]) {
+    assert.equal((await c.check(poolOf(junk), PROJECT)).ok, false, JSON.stringify(junk));
+  }
+});
+
+test('NO CAP IS NOT AN INFINITE CAP — an unbounded ceiling is the defect wearing a cap\'s name', async () => {
+  for (const cap of [0, -5, Number.NaN, Number.POSITIVE_INFINITY, null, 'lots']) {
+    const r = await createSpendCeiling({ capUsd: cap, now: () => AT }).check(poolOf('0'), PROJECT);
+    assert.equal(r.ok, false, String(cap));
+    assert.equal(r.reason, 'no_spend_cap_configured', String(cap));
+  }
+});
+
+test('no payer to bill: refused, matching fire-budget\'s reading of an unidentified caller', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  for (const p of [null, undefined, {}, { payer_kind: 'nobody' }, { payer_kind: 'builder', payer_builder_id: null }]) {
+    const r = await c.check(poolOf('0'), p);
+    assert.equal(r.ok, false, JSON.stringify(p));
+    assert.equal(r.reason, 'no_payer', JSON.stringify(p));
+  }
+});
+
+test('the window is the calendar month, and the sum is scoped to THIS payer', async () => {
+  let captured = null;
+  const spy = { query: async (_sql, params) => { captured = params; return { rows: [{ spent: '1' }] }; } };
+  await createSpendCeiling({ capUsd: 25, now: () => AT })
+    .check(spy, { payer_kind: 'builder', payer_builder_id: 12 });
+  assert.deepEqual(captured[0], new Date(Date.UTC(2026, 8, 1)), 'since the 1st, UTC');
+  assert.equal(captured[1], 'builder');
+  assert.equal(captured[2], 12, 'one builder\'s month, not every builder\'s');
+});
+
+test('monthStartUtc is the 1st at midnight UTC, including on the 1st itself', () => {
+  assert.deepEqual(monthStartUtc(Date.UTC(2026, 0, 31, 23, 59)), new Date(Date.UTC(2026, 0, 1)));
+  assert.deepEqual(monthStartUtc(Date.UTC(2026, 0, 1, 0, 0)), new Date(Date.UTC(2026, 0, 1)));
+});
+
+test('the default cap is a real, small, finite number — a default is what an unthinking instance gets', () => {
+  assert.ok(Number.isFinite(DEFAULT_CAP_USD) && DEFAULT_CAP_USD > 0);
+  assert.ok(DEFAULT_CAP_USD <= 100, 'generous defaults are how an unbounded bill arrives');
+});
+
+test('the ceiling RECORDS NOTHING — the ledger is the only tally', async () => {
+  // fire-budget.check deliberately records the fire it admits. This one must not:
+  // a second tally is the "two disagreeing answers to what did agents cost" that
+  // fire-budget's own header refuses to become.
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  const writes = [];
+  const pool = { query: async (sql) => { writes.push(sql); return { rows: [{ spent: '1' }] }; } };
+  await c.check(pool, PROJECT);
+  await c.check(pool, PROJECT);
+  assert.equal(writes.length, 2, 'two reads');
+  for (const sql of writes) {
+    assert.match(sql, /^\s*SELECT/i, 'reads only');
+    assert.doesNotMatch(sql, /INSERT|UPDATE|DELETE/i);
+  }
+});