@bongos/core 1.19.733 → 1.19.734

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);
+  }
+});

package/tests/agents_write_routes.mjs

@@ -42,7 +42,7 @@ const ARMED = Object.freeze({
   created_at: 'T0', updated_at: 'T0',
 });
 
-function fakePool({ definition = ARMED, runId = 42 } = {}) {
+function fakePool({ definition = ARMED, runId = 42, spentUsd = '0' } = {}) {
   const calls = [];
   return {
     calls,
@@ -60,6 +60,12 @@ function fakePool({ definition = ARMED, runId = 42 } = {}) {
       if (/^\s*INSERT INTO agents_definitions/.test(sql)) return { rows: [{ ...ARMED, name: params[0], enabled: false }] };
       if (/^\s*UPDATE agents_definitions/.test(sql)) return { rows: [{ ...definition, enabled: /enabled = true/.test(sql) }], rowCount: 1 };
       if (/^\s*DELETE FROM agents_definitions/.test(sql)) return { rows: [], rowCount: 1 };
+      // THE SPEND CEILING'S READ (task 1003884), and it must be tested BEFORE the
+      // generic agents_runs branch below — the same anchoring lesson that branch's
+      // own comment records about SELECT vs DELETE. Matched last, the ceiling's
+      // SUM would be answered with a ledger ROW, which has no `spent` column, and
+      // the ceiling would correctly refuse every fire in this file as unreadable.
+      if (/SUM\(cost_usd\)/.test(sql)) return { rows: [{ spent: spentUsd }] };
       if (/FROM agents_runs/.test(sql)) {
         // The ownership filter is params[1]; the fake honours it so the IDOR test
         // exercises the real WHERE clause rather than a stub that ignores it.
@@ -184,6 +190,50 @@ await t('the persona and the caller\'s input BOTH reach the model', async () =>
   assert.match(lastPrompt, /why is it so\?/);
 });
 
+await t('the fire records WHO PAYS beside who asked (task 1003884)', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+  const row = pool.insertedRun();
+  assert.equal(row.requested_by_builder_id, 5, 'who asked');
+  // The neutral pack ships spend_payer 'none', which attributes to the PROJECT —
+  // that is who the money actually comes from, and it is what keeps a closed-door
+  // instance working exactly as it did (ADR 0282).
+  assert.equal(row.payer_kind, 'project', 'who is on the hook');
+  assert.equal(row.payer_builder_id, null);
+});
+
+await t('A PAYER AT THE CAP IS REFUSED 402, and nothing is spawned or ledgered', async () => {
+  // The ceiling is wired ahead of the definition read, so an exhausted payer costs
+  // not even a SELECT. 402 rather than fire-budget's 429 on purpose: "the money is
+  // gone" and "too fast, try later" are different operator problems.
+  const pool = fakePool({ spentUsd: '9999' });
+  api.pool = pool;
+  lastPrompt = null;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+
+  assert.equal(res.out.status, 402);
+  assert.equal(res.out.failed.code, 'spend_cap_reached');
+  assert.equal(res.out.failed.details.reason, 'spend_cap_reached');
+  assert.equal(res.out.failed.details.payer_kind, 'project');
+  assert.equal(pool.insertedRun(), null, 'a refused fire writes no run');
+  assert.equal(lastPrompt, null, 'and calls no model');
+});
+
+await t('AN UNREADABLE LEDGER REFUSES THE FIRE — the ceiling fails closed at the route too', async () => {
+  // The lib-level case is in tests/agents_spend_guard.mjs; this one proves the
+  // route honours it rather than falling through, which is the half that task
+  // 1001393's failed-open brake actually got wrong.
+  api.pool = { async query() { throw new Error('ECONNREFUSED'); } };
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 402);
+  assert.equal(res.out.failed.details.reason, 'ledger_unreadable');
+  assert.equal(res.out.failed.details.spent_usd, null, 'it claims no sum it does not have');
+});
+
 await t('a body key the schema does not name is refused rather than ignored', async () => {
   api.pool = fakePool();
   const res = fakeRes();

package/tests/bump_version.mjs

@@ -171,7 +171,84 @@ test('publish.yml wires the terminator: guard step present, every armed step gat
   assert.ok(PUBLISH_YML.includes('id: relhead'), 'the Already released? guard step exists');
   assert.match(PUBLISH_YML, /isReleaseCommit/, 'the guard delegates to bump-version.js — single source');
   const gates = (PUBLISH_YML.match(/steps\.relhead\.outputs\.release_head == 'false'/g) || []).length;
-  assert.ok(gates >= 7, `every post-guard armed step must carry the gate (setup-node, install, resolve, bump, pack, publish, tag) — found ${gates}`);
+  assert.ok(gates >= 7, `every post-guard armed step must carry the gate (setup-node, install, resolve, bump, pack, publish, record, tag) — found ${gates}`);
+});
+
+// ---- the release ORDER: publish before push (task 1003914) ----
+//
+// The bug this pins: publish.yml used to push the bump commit to main BEFORE
+// packaging and publishing. A failure in either left main permanently declaring
+// a version that never reached npm, and the cascade terminator above then made
+// it unretryable — HEAD was this lane's own release commit, so every following
+// run no-opped and only a fresh work merge moved past the hole. 1.19.716-723
+// were minted and lost that way on 2026-09-13.
+//
+// These are source-order assertions because a workflow's step order IS its
+// source; there is nothing to execute here. They key on the actual COMMANDS,
+// never on prose, so a comment rewrite can't make them pass falsely.
+
+const BRANCH_PUSH = ['git', 'push', 'origin', 'HEAD:main'].join(' ');
+
+test('the bump commit is pushed only AFTER npm publish — the irreversible step goes last', () => {
+  const publishAt = PUBLISH_YML.indexOf('npm publish "$TGZ"');
+  const pushAt = PUBLISH_YML.indexOf(BRANCH_PUSH);
+  assert.ok(publishAt !== -1, 'publish.yml must publish the packaged tarball');
+  assert.ok(pushAt !== -1, 'publish.yml must push the bump commit to main somewhere');
+  assert.ok(
+    publishAt < pushAt,
+    'the push to main must come AFTER npm publish. Pushing first makes a failed publish burn the version number permanently and unretryably (task 1003914).',
+  );
+});
+
+test('the push to main happens exactly once, and not inside the bump step', () => {
+  const pushes = PUBLISH_YML.split(BRANCH_PUSH).length - 1;
+  assert.equal(pushes, 1, `exactly one push of the bump to main — found ${pushes}`);
+  // The bump step runs from `id: bump` up to the next step's `- name:`.
+  const bumpAt = PUBLISH_YML.indexOf('id: bump');
+  assert.ok(bumpAt !== -1, 'the bump step must carry id: bump');
+  const nextStepAt = PUBLISH_YML.indexOf('\n      - name:', bumpAt);
+  const bumpStep = PUBLISH_YML.slice(bumpAt, nextStepAt === -1 ? undefined : nextStepAt);
+  assert.ok(
+    !bumpStep.includes(BRANCH_PUSH),
+    'the bump step must COMMIT only — its push moved to the record step so a pack/publish failure discards a purely local commit',
+  );
+  assert.ok(bumpStep.includes('git commit -m'), 'the bump step still commits locally — package-core stamps the version found AT the ref');
+});
+
+test('an already-published version is success, not a wedge', () => {
+  // Publish-then-failed-push leaves a version on npm with no release commit.
+  // The next run reads it as free (laneReleasedVersions is git-based), bumps to
+  // it, and npm refuses the duplicate. Without this branch that run fails, and
+  // so does every run after it — the lane wedges with no way out but a human.
+  const pubAt = PUBLISH_YML.indexOf('id: pub');
+  assert.ok(pubAt !== -1, 'the publish step must carry id: pub');
+  const pubStep = PUBLISH_YML.slice(pubAt, PUBLISH_YML.indexOf('\n      # PUBLISH VERDICT'));
+  assert.match(
+    pubStep,
+    /cannot publish over\|previously published\|EPUBLISHCONFLICT/,
+    'the publish step must recognise npm refusing a duplicate version',
+  );
+  assert.match(pubStep, /already=true/, 'and must record that it took the already-present branch');
+  assert.match(
+    pubStep,
+    /exit "\$RC"/,
+    'every OTHER publish failure must still fail the step — the tolerance is narrow on purpose',
+  );
+});
+
+test('the record step gates on a bump actually having been made', () => {
+  const recAt = PUBLISH_YML.indexOf('- name: Record the release on main');
+  assert.ok(recAt !== -1, 'the record step exists');
+  const recStep = PUBLISH_YML.slice(recAt, PUBLISH_YML.indexOf('\n      # PUBLISH VERDICT'));
+  assert.match(
+    recStep,
+    /steps\.bump\.outputs\.to != ''/,
+    'nothing to push when no bump was made (taken == false) — the step must skip rather than push an empty HEAD',
+  );
+  assert.ok(
+    !recStep.includes('git rebase'),
+    'no rebase-retry: the tarball was built from the pre-rebase tree, so rebasing would leave source_commit naming a SHA that is not on main',
+  );
 });
 
 // ---------------------------------------------------------------------------