@bongos/core 1.19.843 → 1.19.844

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.843",
-  "core_contract": "1.19.843",
-  "source_commit": "7c57c44f66a63fda88681f46ac67857f8c8ed1e7",
+  "core_version": "1.19.844",
+  "core_contract": "1.19.844",
+  "source_commit": "980c92b65de8a99f2772b86fb7f69e365eed4dc6",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T18:30:58.977Z",
+  "built_at": "2026-09-17T18:59:26.454Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 495,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2270,
+    "functional_verbatim": 2272,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2791,
-  "tree_sha256": "9f6bfba9532caa1edab6600efaf86e006add511e45378f5cf2ccf8ad81d81231",
+  "file_count": 2793,
+  "tree_sha256": "af2219bd2cdea4b5ebb159bd2cc60e9d015182c15121196f16e1cbb9b4ac7bf5",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2577,7 +2577,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e2083366af3229b576d6d034f1d2e1c6e7e4fa61fba384ba0d0fca9b7911087f"
+      "sha256": "185ae1211c5c546bf5d0a57acd5c97ad56b4e98133ba2aceded36bf2cc95c4ca"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3712,7 +3712,7 @@
     {
       "path": "modules/agents/lib/spend-ceiling.js",
       "mode": "0000644",
-      "sha256": "97bfcea1cd580df4765bff92a1b26f56bfe467501bfd1c566ff7df9ec4ac746b"
+      "sha256": "1144ee9be9cb3df57e876a868529ddbf78864fac1fdabc90ed2e010bd8d376a8"
     },
     {
       "path": "modules/agents/lib/validate.js",
@@ -3734,6 +3734,11 @@
       "mode": "0000644",
       "sha256": "7a9763f90da032c81aa0b1a8461a2e13b58d9f529c1b857b048648feeadc6fdd"
     },
+    {
+      "path": "modules/agents/migrations/agents_004_spend_cap.sql",
+      "mode": "0000644",
+      "sha256": "31a5ac35536cecd264bc989907f4cf094e050db0b8de85e7e3e7831cf7c25a9d"
+    },
     {
       "path": "modules/agents/module.json",
       "mode": "0000644",
@@ -3742,17 +3747,17 @@
     {
       "path": "modules/agents/pollers/event-router.js",
       "mode": "0000644",
-      "sha256": "de64902d694acfc7d32aaf4d8629921f64cf851d600deb077a278b528d34c57d"
+      "sha256": "ddd903f3702a3dd14e714dcf352e7c69f4bfbce5206e71892142aa8a81d44cde"
     },
     {
       "path": "modules/agents/routes/agents.js",
       "mode": "0000644",
-      "sha256": "8bfdaf26077e1bc005b6b2b764e0912ac7e5becb373a8a4371cb3cd6fa7c163f"
+      "sha256": "a5d80d87486e8c6e928fe4ac563643ceb5255df14fd89e7e20194e2d8196b301"
     },
     {
       "path": "modules/agents/spawn.js",
       "mode": "0000644",
-      "sha256": "6d656333f03de1c7e1f798101dc7fcc6ddcf595b9dcb0001a110682f7e6e91f8"
+      "sha256": "4e5e9ac97bd443d4091d8a6e4e246e080a2fe67793a77f4c4139b19019e37005"
     },
     {
       "path": "modules/autonomy/CLAUDE.md",
@@ -4297,7 +4302,7 @@
     {
       "path": "modules/economy/cost-classify.js",
       "mode": "0000644",
-      "sha256": "22b0b50ae46850a8d0a9de40eeced47df6edc671eada63529d48a1486aea4d75"
+      "sha256": "fefd4908bd22aa3b747a7c8b4146e5a7e53731fe92612db105ea3512ae34300c"
     },
     {
       "path": "modules/economy/cost-summary-shape.js",
@@ -4307,7 +4312,7 @@
     {
       "path": "modules/economy/cost.js",
       "mode": "0000644",
-      "sha256": "01bc7725fe16388971fd4def2544d0de9af6b3a522973df7ef86386737933d40"
+      "sha256": "6cc28fe57bb50b6c3f4b7d4485838427fa5f12b5a79848f0358fdaa2874f6c1e"
     },
     {
       "path": "modules/economy/credits.js",
@@ -4337,7 +4342,7 @@
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
-      "sha256": "e026156d1578bc6c0ce43a197575601e9663e608819d8c92ca713e17ecbf0b3d"
+      "sha256": "c4245b1b7c361eb44e0034f19227e208b956e9eb9ac03924e22b3017dd4a343a"
     },
     {
       "path": "modules/economy/routes/cost.js",
@@ -4957,7 +4962,7 @@
     {
       "path": "modules/hall-ui/public/goals.states.json",
       "mode": "0000644",
-      "sha256": "8e955be7fb6aef55b6aac0c586b27963f032bab9bec743b56a5987b6276cc8d3"
+      "sha256": "14aefbb8b94ebc3df68744052f465b63ceaf3361f98a94972781ae01bc616735"
     },
     {
       "path": "modules/hall-ui/public/government.css",
@@ -5037,7 +5042,7 @@
     {
       "path": "modules/hall-ui/public/idea.states.json",
       "mode": "0000644",
-      "sha256": "4b8ea0bb4eac805b8d85556830104b07b2b0612ba1b8337bab6fb7368a887995"
+      "sha256": "2299490186e19f2369069562dc8ba8dd837a2e89bfa94c7797f350cc653659c9"
     },
     {
       "path": "modules/hall-ui/public/ideas.css",
@@ -5057,7 +5062,7 @@
     {
       "path": "modules/hall-ui/public/ideas.states.json",
       "mode": "0000644",
-      "sha256": "f75230d5d770d4780b7c9fb28c40c8f44a91354e61f3d0a9a6281c90904a80c8"
+      "sha256": "889041e8bcff6e7fa53f6bd09d0bed670e6b58cd68cda2ff7147a1a253e33e8d"
     },
     {
       "path": "modules/hall-ui/public/index.html",
@@ -5067,7 +5072,7 @@
     {
       "path": "modules/hall-ui/public/index.states.json",
       "mode": "0000644",
-      "sha256": "ac0bd95920b845d11ba24bf3e75ac169c13820861ad73776a6b174a5386e8b5f"
+      "sha256": "74b6c43bb12a85e7d944069548c3e3a5de54f37267bbdc179157e1b164101399"
     },
     {
       "path": "modules/hall-ui/public/md-reader.js",
@@ -5117,7 +5122,7 @@
     {
       "path": "modules/hall-ui/public/pair.states.json",
       "mode": "0000644",
-      "sha256": "10d19605f074dedd85634fe1ed2eb06f06189e90778b1ce7d87d7b369ba428c6"
+      "sha256": "3c48d1588f8512f0f9a0d5774acdf88c9a761e6b9f5f3da2d544a32bc06b4ab8"
     },
     {
       "path": "modules/hall-ui/public/palette.js",
@@ -5347,7 +5352,7 @@
     {
       "path": "modules/hall-ui/public/settings.states.json",
       "mode": "0000644",
-      "sha256": "02c0591b014806e991478c720658b0e74129e2e8c1ffcdd8e3384c681201a295"
+      "sha256": "2d9f55bb007891b5d5b4511d7f29a20d01477a8395c84c259a42a7e6157aced9"
     },
     {
       "path": "modules/hall-ui/public/shell.js",
@@ -5412,7 +5417,7 @@
     {
       "path": "modules/hall-ui/public/task.states.json",
       "mode": "0000644",
-      "sha256": "fb7112aff3834f88305e9705335dd6b0527cc1cea8f4a1b7d5842b377437da9e"
+      "sha256": "1be94e892012740aae899aa28425f4be9c94a5ae777c8c77e5e1b787791f5ec9"
     },
     {
       "path": "modules/hall-ui/public/triumph.wav",
@@ -5457,7 +5462,7 @@
     {
       "path": "modules/hall-ui/public/work.states.json",
       "mode": "0000644",
-      "sha256": "929512f085f138f93170f643dbd68615dfbf6d5fcd5f0bf1abf30a081154b536"
+      "sha256": "786373b132587480ff58452286f950d246eae430f7531f0ccf4d01f290fdc435"
     },
     {
       "path": "modules/ideas/CLAUDE.md",
@@ -7897,12 +7902,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "090497aae4ab83f6ab3f821417ece5fcc50b86a09e026b3e4644aa660333d191"
+      "sha256": "a6133e7d6f098080ea0b2d2d21d3bbf35c90a716dc20a4436a68c74c6416da84"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e7d47a1c39751137250a2cc087fb288d3c349b44d8faebc38f70e841f6475560"
+      "sha256": "65a0092e9c2f20b87c7de5d89e552e005820a70cc5c00fb228d904363d842b22"
     },
     {
       "path": "public-docs/index.html",
@@ -9837,7 +9842,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a24a8e5c67584fff7c871ad60afaa3bc9f81a2c77189629597dd4fd63cd43c31"
+      "sha256": "a97295bdd0b3f0fe6b6c903b910a2512e7fffcc4a98f6d2844096cbc6015d7a7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9997,7 +10002,7 @@
     {
       "path": "tests/agents_spend_guard.mjs",
       "mode": "0000644",
-      "sha256": "8bed5bc6e737f17038b3fba4f5c73a0478b0dd581b506e5a0bbd31754ff8a758"
+      "sha256": "dde31247e6cb995487e21f78d5b44bfb24bc087bd7736c5a130ed4d8822d0cb7"
     },
     {
       "path": "tests/agents_sync.mjs",
@@ -11689,6 +11694,11 @@
       "mode": "0000644",
       "sha256": "82bf1cc68150c247c108308d360d6408511f31a7af11d5e7a4721e7ea282f2bb"
     },
+    {
+      "path": "tests/hall_states_regex_escapes.mjs",
+      "mode": "0000644",
+      "sha256": "906786d9728fd1d94449674422401ef1b53a460d5c84998565b1ebeab5e47c7a"
+    },
     {
       "path": "tests/hall_studio_world.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2159,6 +2159,8 @@ is load-bearing: the script throws rather than guess if it is missing, and
   1.19.842 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.841 with no explicit bump. run 35258288930. (task 1002620)
   1.19.843 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
-        landed since 1.19.842 with no explicit bump. run 35259228465. (task 1002620)
+        landed since 1.19.842 with no explicit bump. run 35259608793. (task 1002620)
+  1.19.844 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.843 with no explicit bump. run 35262101669. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/agents/lib/spend-ceiling.js

@@ -59,6 +59,18 @@
 // be saved by a generous default.
 const DEFAULT_CAP_USD = 25;
 
+// The PER-AGENT default (task 1002499, owner decision 2026-07-05: ~$5/month per
+// agent under the ~$30/month global brake). Deliberately much smaller than the
+// per-payer cap above, because it bounds a different thing: that one bounds the
+// WALLET, this one bounds ONE DEFINITION. Under a single project payer the two
+// were the same number, which meant a runaway agent could eat the whole instance
+// ceiling and every other agent would then be refused for a bill it did not run
+// up. At the historian exemplar's ~$0.90 a fire, $5 is about five fires a month —
+// enough for a routine that answers a few times a week, and not enough for a loop.
+// A definition sets its own with agents_definitions.spend_cap_usd; an instance
+// moves every unset one with BONGOS_AGENT_SPEND_CAP_USD.
+const DEFAULT_AGENT_CAP_USD = 5;
+
 // Calendar month, UTC. It matches the window agents_001's spend index was built
 // for ("What did agents cost this month?") and the $/month cap fire-budget's
 // header defers to — and a calendar month is the unit a bill arrives in, which is
@@ -96,12 +108,116 @@ function payerFor(spendPayer, requestedByBuilderId) {
   return { payer_kind: 'project', payer_builder_id: null };
 }
 
+// Read one SUM(cost_usd) and return a TRUSTWORTHY number, or null for "I don't
+// know". Shared by the two ceilings below so the fail-closed reading of a ledger
+// is written once — but note that sharing it is not itself the guarantee: the
+// tests exercise BOTH ceilings against a throwing pool, a NULL sum and a garbage
+// sum independently, because a helper's documented safety property is a claim
+// until each caller is shown to honour it.
+//
+// Every "I don't know" collapses to null here, and every caller turns null into a
+// REFUSAL. The one thing this must never do is return 0 for an absent value —
+// Number(null) is 0, and a zero reads as "has spent nothing", which is the
+// fail-OPEN direction wearing a plausible number. That is the whole of task
+// 1001393, so the absence is rejected before it can be coerced.
+async function sumOrNull(pool, sql, params) {
+  if (!pool || typeof pool.query !== 'function') return null;
+  let raw;
+  try {
+    const { rows } = await pool.query(sql, params);
+    raw = rows && rows[0] ? rows[0].spent : undefined;
+  } catch (_) {
+    // THE 1001393 CASE. An unreadable ledger is the one this file exists for.
+    return null;
+  }
+  if (raw === null || raw === undefined) return null;
+  // NUMERIC comes back as a string from pg, so this catches a genuinely
+  // unparseable value, not the ordinary one.
+  const n = Number(raw);
+  return (Number.isFinite(n) && n >= 0) ? n : null;
+}
+
+// Summed BY PAYER, so a builder-paid instance gives each builder their own month
+// and a project-paid one sums the instance. Rows written before agents_002 carry
+// no payer_kind and match neither, which is the conservative direction: nobody is
+// charged for spend that was not attributed to them.
+const PAYER_SPEND_SQL = `SELECT COALESCE(SUM(cost_usd), 0) AS spent
+     FROM agents_runs
+    WHERE cost_usd IS NOT NULL
+      AND created_at >= $1
+      AND payer_kind = $2
+      AND payer_builder_id IS NOT DISTINCT FROM $3`;
+
+// Summed BY AGENT NAME, across every payer. The name is the identity that
+// survives a definition being re-synced, disabled or re-authored — agents_001
+// built agents_runs_agent_idx (agent_name, created_at DESC) for exactly this
+// read. Deliberately NOT keyed on definition_id: that column is ON DELETE SET
+// NULL, so deleting a definition would zero its month and hand a fresh cap to a
+// re-created agent of the same name.
+const AGENT_SPEND_SQL = `SELECT COALESCE(SUM(cost_usd), 0) AS spent
+     FROM agents_runs
+    WHERE cost_usd IS NOT NULL
+      AND created_at >= $1
+      AND agent_name = $2`;
+
+// The per-agent cap for one definition: its own spend_cap_usd (agents_004) when it
+// declares one, else the instance default. A stored cap is schema-guaranteed
+// positive, so anything else in that column is a row this code did not write and
+// gets the default rather than a guess.
+function agentCapFor(definition, fallback) {
+  const raw = definition && definition.spend_cap_usd;
+  if (raw === null || raw === undefined) return fallback;
+  const n = Number(raw);
+  return (Number.isFinite(n) && n > 0) ? n : fallback;
+}
+
 function createSpendCeiling({
   capUsd = envNumber('BONGOS_AGENTS_SPEND_CAP_USD', DEFAULT_CAP_USD),
+  agentCapUsd = envNumber('BONGOS_AGENT_SPEND_CAP_USD', DEFAULT_AGENT_CAP_USD),
   now = () => Date.now(),
 } = {}) {
   return {
     capUsd,
+    agentCapUsd,
+
+    /**
+     * May THIS AGENT spend right now? (task 1002499)
+     *
+     * The sibling of check() below, and deliberately a separate call rather than
+     * a wider one: they refuse for different reasons and an operator must be able
+     * to tell "this instance's money is gone" from "this one agent has had its
+     * share". Both run on every fire, cheapest first.
+     *
+     * Records nothing, for the same reason check() does not: agents_runs is the
+     * accounting, and a ceiling that kept its own tally would be a second,
+     * disagreeing answer to what agents cost.
+     *
+     * Fails closed on every unhappy path, exactly like check(): no usable cap, no
+     * agent name, an unreadable ledger, or the cap already spent. The KNOWN
+     * OVERSHOOT in this file's header applies here too — a fire in flight carries
+     * cost_usd NULL and is invisible to this read.
+     *
+     * @returns {{ok: boolean, spentUsd: number|null, capUsd: number, remainingUsd: number, reason: string|null}}
+     */
+    async checkAgent(pool, definition) {
+      const cap = agentCapFor(definition, Number(agentCapUsd));
+      const deny = (reason) => ({ ok: false, spentUsd: null, capUsd: cap, remainingUsd: 0, reason });
+
+      if (!Number.isFinite(cap) || cap <= 0) return deny('no_agent_spend_cap_configured');
+      const name = definition && definition.name;
+      // An unnamed definition cannot be summed, so its month is unknowable — the
+      // same "I don't know" a throwing ledger gives, and it gets the same answer.
+      if (typeof name !== 'string' || !name.trim()) return deny('no_agent_identity');
+
+      const spent = await sumOrNull(pool, AGENT_SPEND_SQL, [monthStartUtc(now()), name]);
+      if (spent === null) return deny('ledger_unreadable');
+
+      const remaining = cap - spent;
+      if (remaining <= 0) {
+        return { ok: false, spentUsd: spent, capUsd: cap, remainingUsd: 0, reason: 'agent_spend_cap_reached' };
+      }
+      return { ok: true, spentUsd: spent, capUsd: cap, remainingUsd: remaining, reason: null };
+    },
 
     /**
      * May this payer spend right now?
@@ -121,42 +237,12 @@ function createSpendCeiling({
       if (kind !== 'project' && kind !== 'builder') return deny('no_payer');
       const builderId = payer.payer_builder_id ?? null;
       if (kind === 'builder' && builderId === null) return deny('no_payer');
-      if (!pool || typeof pool.query !== 'function') return deny('ledger_unreadable');
-
-      const since = monthStartUtc(now());
-      let spent;
-      try {
-        // Summed BY PAYER, so a builder-paid instance gives each builder their own
-        // month and a project-paid one sums the instance. Rows written before
-        // agents_002 carry no payer_kind and match neither, which is the
-        // conservative direction: nobody is charged for spend that was not
-        // attributed to them.
-        const { rows } = await pool.query(
-          `SELECT COALESCE(SUM(cost_usd), 0) AS spent
-             FROM agents_runs
-            WHERE cost_usd IS NOT NULL
-              AND created_at >= $1
-              AND payer_kind = $2
-              AND payer_builder_id IS NOT DISTINCT FROM $3`,
-          [since, kind, builderId],
-        );
-        const raw = rows && rows[0] ? rows[0].spent : undefined;
-        // NOT `Number(raw)` alone. Number(null) is 0, so a sum that came back as
-        // SQL NULL — a shape COALESCE should make impossible, and would therefore
-        // only appear if this query or that table changed under us — would read
-        // as "this payer has spent nothing" and admit the fire. That is the
-        // fail-OPEN direction wearing a plausible number, which is the whole
-        // failure mode task 1001393 was filed about, so an absent value is
-        // rejected BEFORE it can be coerced into a permissive one.
-        spent = (raw === null || raw === undefined) ? Number.NaN : Number(raw);
-      } catch (_) {
-        // THE 1001393 CASE. An unreadable ledger is the one this file exists for.
-        return deny('ledger_unreadable');
-      }
-      // A sum that is not a number is the same "I don't know" as a throw, and gets
-      // the same answer. NUMERIC comes back as a string from pg, so this catches a
-      // genuinely unparseable value, not the ordinary one.
-      if (!Number.isFinite(spent) || spent < 0) return deny('ledger_unreadable');
+
+      // sumOrNull carries the fail-closed reading (a missing pool, a throw, a NULL
+      // sum and an unparseable sum all become null) — see its header for why an
+      // absent value must never be coerced to 0.
+      const spent = await sumOrNull(pool, PAYER_SPEND_SQL, [monthStartUtc(now()), kind, builderId]);
+      if (spent === null) return deny('ledger_unreadable');
 
       const remaining = cap - spent;
       if (remaining <= 0) {
@@ -167,4 +253,7 @@ function createSpendCeiling({
   };
 }
 
-module.exports = { createSpendCeiling, payerFor, monthStartUtc, DEFAULT_CAP_USD };
+module.exports = {
+  createSpendCeiling, payerFor, monthStartUtc, agentCapFor,
+  DEFAULT_CAP_USD, DEFAULT_AGENT_CAP_USD,
+};

package/modules/agents/migrations/agents_004_spend_cap.sql

@@ -0,0 +1,53 @@
+-- agents_004_spend_cap.sql — the PER-AGENT monthly spend cap (task 1002499).
+--
+-- agents_002 recorded who PAYS for a fire, and modules/agents/lib/spend-ceiling.js
+-- bounds what a payer may spend in a month. Both ask "how much has this WALLET
+-- spent", and neither can answer "how much has this AGENT spent" — so under a
+-- single project payer one runaway definition consumes the whole instance ceiling
+-- and every other agent is refused for a bill it did not run up. The owner's
+-- decision (2026-07-05, recorded on task 1002499) is ~$5/month per agent, layered
+-- under the ~$30/month global autonomy brake: a per-agent cap bounds the blast
+-- radius of ONE bad definition, and the global brake bounds the fleet.
+--
+-- NULL MEANS "USE THE INSTANCE DEFAULT", NOT "UNCAPPED". The default lives in
+-- lib/spend-ceiling.js (BONGOS_AGENT_SPEND_CAP_USD, default $5) so a definition
+-- that never thought about money still has a ceiling, and an instance can move
+-- every unset agent with one env var. Storing the default on each row instead
+-- would freeze today's number into every definition ever synced — the same trap
+-- agents_002's header names for deriving payer_kind, in the other direction.
+-- Nothing may read this column as "no cap": the CHECK below forbids a zero or a
+-- negative, so the only two states are a positive number and "ask the default".
+--
+-- WHY NO NEW INDEX. The read this backs — SUM(cost_usd) for one agent this month
+-- — is already served by agents_runs_agent_idx (agent_name, created_at DESC),
+-- which agents_001 created with the comment "the read behind a per-agent spend
+-- rollup". This migration is the rollup that index was built for.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5). Idempotent: safe to re-run.
+
+BEGIN;
+
+-- The per-agent monthly ceiling in USD. NULL = fall back to the instance default.
+-- numeric(10,4) mirrors agents_runs.cost_usd, so a cap and the spend it bounds are
+-- the same kind of number and a comparison cannot lose a fraction of a cent.
+ALTER TABLE agents_definitions ADD COLUMN IF NOT EXISTS spend_cap_usd numeric(10, 4);
+
+DO $$
+BEGIN
+  -- A stored cap must be a real ceiling. Zero would read as "this agent may never
+  -- fire", which is what `enabled = false` already says and says better; a
+  -- negative is meaningless. Both are refused at the schema rather than left for
+  -- the guard to interpret, because a guard that has to decide what 0 means is a
+  -- guard with two possible answers.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_definitions_spend_cap_positive_chk') THEN
+    ALTER TABLE agents_definitions ADD CONSTRAINT agents_definitions_spend_cap_positive_chk
+      CHECK (spend_cap_usd IS NULL OR spend_cap_usd > 0);
+  END IF;
+END $$;
+
+COMMENT ON COLUMN agents_definitions.spend_cap_usd IS
+  'Per-agent monthly spend ceiling in USD (task 1002499). NULL = use the instance default from lib/spend-ceiling.js (BONGOS_AGENT_SPEND_CAP_USD, default $5). Never "uncapped" — a positive value is the only storable cap.';
+
+COMMIT;

package/modules/agents/pollers/event-router.js

@@ -113,8 +113,13 @@ const FANOUT_MAX = envInt('BONGOS_AGENTS_EVENT_FANOUT_MAX', DEFAULT_FANOUT_MAX);
 // `enabled = false` by agents_definitions_flagged_not_armed_chk, so the WHERE
 // clause below already excludes it and a second check here would only be a
 // second place to get it wrong.
+// `spend_cap_usd` joins the list for step (g2) — the per-agent ceiling reads the
+// definition's own cap (task 1002499). It has to be selected here or every agent
+// silently takes the instance default, which is the quiet-wrong-answer shape this
+// spelled-out list otherwise protects against: a cap set on a definition would be
+// stored, shown by the API, and ignored by the only code that enforces it.
 const DEF_COLUMNS = `
-  id, name, persona, trigger_type, trigger_spec, model_tier
+  id, name, persona, trigger_type, trigger_spec, model_tier, spend_cap_usd
 `;
 
 // ---------------------------------------------------------------------------
@@ -590,10 +595,32 @@ async function fanOut(payload, deps = {}) {
     return report;
   }
 
+  // (g2) THE PER-AGENT CEILING (task 1002499), once PER AGENT rather than once
+  // for the fan-out. That is the whole difference from (g) above: the payer
+  // ceiling asks a question about the wallet, so one answer covers every agent
+  // sharing it, while this one asks about each definition and so has as many
+  // answers as there are agents. An agent over its share is skipped with its own
+  // ledger row; its siblings still fire, which is the behaviour a per-agent cap
+  // exists to produce — one runaway definition must not silence the fleet.
+  const stillAdmitted = [];
+  for (const a of admitted) {
+    const agentRoom = await ceiling.checkAgent(pool, a.definition);
+    if (agentRoom.ok) { stillAdmitted.push(a); continue; }
+    const reason = agentRoom.reason === 'agent_spend_cap_reached'
+      ? `agent '${a.definition && a.definition.name}' has reached its $${agentRoom.capUsd} monthly cap — the instance still has room, but this agent has spent its share`
+      : `this agent's spend ceiling could not be established (${agentRoom.reason}) — a ceiling that cannot be read must not be assumed`;
+    await ledgerNoGo(deps, { definition: a.definition, taskId, reason, spendPayer });
+    report.skipped += 1;
+  }
+  if (!stillAdmitted.length) {
+    report.reason = 'agent_spend_ceiling';
+    return report;
+  }
+
   // (h) FIRE. Sequentially, so N agents on one ship are N model calls in a row
   // rather than N at once — the spend ceiling's own blind spot is fires already
   // in flight, and serialising is what keeps that blind spot one fire wide.
-  for (const a of admitted) {
+  for (const a of stillAdmitted) {
     const fired = await fireOne(a, { task, taskId, spendPayer }, deps);
     if (fired && fired.ran) report.fired += 1; else report.skipped += 1;
   }

package/modules/agents/routes/agents.js

@@ -122,7 +122,7 @@ const COLUMNS = `
   id, name, title, trigger_type, trigger_spec, model_tier,
   scope_modules, scope_paths, scope_violation,
   source, provenance, author_rank,
-  source_path, last_synced_at, enabled, created_at, updated_at
+  source_path, last_synced_at, enabled, spend_cap_usd, created_at, updated_at
 `;
 
 // PURE. Row → wire shape, so the projection is unit-testable without a database.
@@ -168,6 +168,14 @@ function serializeDefinition(row, { includePersona = false } = {}) {
     // is the one disarm the registry can explain; anything else is simply off.
     disarmed_reason: row.enabled === true ? null : (row.scope_violation ? 'scope_violation' : null),
     last_synced_at: row.last_synced_at || null,
+    // The agent's own monthly ceiling (task 1002499), or null when it takes the
+    // instance default. Served as a NUMBER, not the pg NUMERIC string, so a caller
+    // comparing it against a spend does not silently compare strings. Null here
+    // never means "uncapped" — agents_004's CHECK makes a positive value the only
+    // storable cap, and an unset one resolves to BONGOS_AGENT_SPEND_CAP_USD.
+    spend_cap_usd: row.spend_cap_usd === null || row.spend_cap_usd === undefined
+      ? null
+      : Number(row.spend_cap_usd),
     created_at: row.created_at,
     updated_at: row.updated_at,
   };
@@ -605,6 +613,35 @@ module.exports = function agentsRoutes() {
       );
       if (!rows.length) return res.fail('agent_not_found', 404);
       const definition = rows[0];
+
+      // THE PER-AGENT CEILING (task 1002499), after the payer's and before the
+      // gate. It cannot run any earlier: it needs the definition, both for its own
+      // spend_cap_usd and for the name it sums by.
+      //
+      // A THIRD refusal with a THIRD code, for the same reason the first two are
+      // separate: 429 says "too fast", `spend_cap_reached` says "this wallet's
+      // month is gone", and this one says "this wallet has room, but THIS AGENT
+      // has had its share". Collapsing them would tell an operator staring at a
+      // refused fire to go raise the wrong number — and under a single project
+      // payer the wrong number is the one that refuses every OTHER agent too.
+      const agentRoom = await spendCeiling.checkAgent(api.pool, definition);
+      if (!agentRoom.ok) {
+        return res.fail('agent_spend_cap_reached', {
+          status: 402,
+          message: agentRoom.reason === 'agent_spend_cap_reached'
+            ? `agent '${definition.name}' has reached its $${agentRoom.capUsd} monthly cap — the instance still has room, but this agent has spent its share`
+            : `this fire is refused because the agent's spend ceiling could not be established (${agentRoom.reason}) — a ceiling that cannot be read must not be assumed`,
+          details: {
+            scope: 'agent-spend-per-agent',
+            reason: agentRoom.reason,
+            agent: definition.name,
+            cap_usd: agentRoom.capUsd,
+            // null whenever the refusal was a failure to READ, never a claimed sum.
+            spent_usd: agentRoom.spentUsd,
+          },
+        });
+      }
+
       const gate = gateFor(definition);
       const trigger = { type: 'on-demand', ref: `on-demand:${req.builder.github_login || req.builder.id}` };
 

package/modules/agents/spawn.js

@@ -36,6 +36,11 @@
 const api = require('../../src/module-api');
 const { payerFor } = require('./lib/spend-ceiling');
 
+// Namespaced + structured, like the module's other two log sites (routes/agents.js,
+// pollers/event-router.js). A bare console.warn here would be the module's only
+// unstructured line, and the fitness console ratchet counts it.
+const log = api.logger('agents');
+
 // tier → concrete model id. The mapping is BRANDING, not a constant here: an
 // instance retunes its own tiers, and the DB constraint already limits the
 // vocabulary to these two.
@@ -139,6 +144,68 @@ async function insertRun(pool, row) {
   return r.rows[0].id;
 }
 
+// The cost_log SOURCE TAG for one agent's spend (task 1002499). The `agent:`
+// family is what modules/economy/cost.js's autonomous MTD brake matches on, beside
+// `cron:`, so the prefix is a contract and not a label — see that function's header.
+// The name is already schema-constrained to ^[a-z][a-z0-9-]*$ (agents_001), so
+// nothing here has to sanitise it, but the tag is built in ONE place so a future
+// rename cannot leave the brake matching a prefix nobody writes any more.
+function costSourceTag(agentName) {
+  return `agent:${agentName}`;
+}
+
+// Mirror one completed fire's cost into cost_log, so the project-wide brake can
+// see it (task 1002499).
+//
+// WHY A MIRROR AND NOT A MOVE. agents_runs.cost_usd stays the ACCOUNTING — it is
+// what the per-payer and per-agent ceilings sum, it carries the payer, and it is
+// the row the schema's invariants are written about. cost_log is the project-wide
+// ROLL-UP: the autonomy spend-brake and the cost dashboard's by_source breakdown
+// both read it, and neither knows agents_runs exists. Before this, agent spend
+// appeared in exactly one of those two places, which is why the brake was blind
+// to it. The mirror is a projection of the ledger, never a second ledger: it is
+// written once, after the cost is final, keyed so a retry cannot double-post.
+//
+// IDEMPOTENT BY CONSTRUCTION. logCost is insert-once on (source, source_ref), and
+// source_ref is the run id — the one value that is unique per fire and already
+// exists. A re-run of this function for the same fire is a no-op at the database,
+// not a second row, which matters because the alternative to a stable key here is
+// double-counting money.
+//
+// BEST-EFFORT, DELIBERATELY. A fire that ran and was ledgered in agents_runs has
+// already happened and already cost money; failing it now because the roll-up
+// could not be written would discard a completed fire's result to fix a reporting
+// row. The direction of that trade is the opposite of the ceilings' — they fail
+// CLOSED because they decide whether to spend, this fails OPEN because the spend
+// is already past. What it must never do is stay silent: an unwritten mirror
+// means the brake is under-counting, so the failure is logged with the run id.
+async function mirrorCostToLedger({ runId, definition, costUsd, builderId = null }, deps = {}) {
+  if (!(typeof costUsd === 'number' && costUsd > 0)) return false;
+  const name = definition && definition.name;
+  if (!runId || typeof name !== 'string' || !name) return false;
+  const economy = deps.economy
+    || (typeof api.resolveOptional === 'function' ? api.resolveOptional('reward', null) : null);
+  if (!economy || typeof economy.logCost !== 'function') return false;
+  try {
+    await economy.logCost({
+      amountUsd: costUsd,
+      category: 'api',
+      source: costSourceTag(name),
+      sourceRef: `agent-run-${runId}`,
+      // Who ASKED, when anyone did. Not who PAYS — payer_kind lives on the
+      // agents_runs row and is that question's answer; cost_log's builder_id is
+      // per-builder attribution, and an event fire legitimately has neither.
+      builderId,
+      description: `agent ${name} — fire ${runId}`.slice(0, 1000),
+    });
+    return true;
+  } catch (e) {
+    (deps.log || log).warn({ run_id: runId, agent: name, err: (e && e.message) || String(e) },
+      'cost mirror failed — agents_runs still has the cost, but the autonomous MTD brake is under-counting by it');
+    return false;
+  }
+}
+
 async function finishRun(pool, id, patch) {
   const cols = Object.keys(patch);
   const set = cols.map((c, i) => `${c} = $${i + 2}`).join(', ');
@@ -218,6 +285,11 @@ async function spawnAgent({
       outputRef: ok ? (deps.outputRef || (res && res.output_ref) || null) : null,
     });
     await finishRun(pool, runId, patch);
+    // AFTER the ledger write, never before: the mirror projects a cost that is
+    // already recorded, so a row in cost_log with no agents_runs row behind it
+    // must not be possible. A failed or zero-cost fire mirrors nothing — the
+    // guard is inside mirrorCostToLedger so both call shapes share it.
+    await mirrorCostToLedger({ runId, definition, costUsd, builderId: requestedByBuilderId }, deps);
     return { ok, ran: true, runId, model, cost_usd: costUsd, duration_ms: durationMs };
   } catch (e) {
     const durationMs = Math.max(0, now() - started);
@@ -228,4 +300,4 @@ async function spawnAgent({
   }
 }
 
-module.exports = { spawnAgent, resolveModel, plannedRow, completedRow, composePrompt };
+module.exports = { spawnAgent, resolveModel, plannedRow, completedRow, composePrompt, mirrorCostToLedger, costSourceTag };

package/modules/economy/cost-classify.js

@@ -46,6 +46,17 @@ const COST_WRITE_SURFACES = [
     file: 'scripts/gds/session-cost.js',
     builder_id: 'the authed builder; category=api, source_ref=<session-id>, task_id=null. Idempotent per session.',
   },
+  {
+    // task 1002499: an agent fire mirrors its cost here so the autonomous MTD
+    // spend-brake can see it. agents_runs.cost_usd stays the accounting; this is
+    // the project-wide roll-up, written once per fire after the cost is final and
+    // keyed source_ref=agent-run-<id> so a retry cannot double-post. It reaches
+    // logCost through the economy PORT (ADR 0083) — still one writer, which is the
+    // property this list exists to state.
+    surface: 'modules/agents/spawn.js (fire mirror) → reward port → db.logCost() (source=agent:<name>)',
+    file: 'modules/agents/spawn.js',
+    builder_id: 'whoever REQUESTED the fire, or null for an event fire, which nobody asked for. Not the PAYER — that is payer_kind on the agents_runs row, a different question.',
+  },
   {
     surface: 'migrations / direct DB',
     file: '—',

package/modules/economy/cost.js

@@ -55,16 +55,34 @@ async function getBuilderCostStatus(builderId) {
   return classifyCostStatus(row.spend_mtd_usd, row.budget_usd);
 }
 
-// System 3 (task 1351): project-wide AUTONOMOUS api spend month-to-date — the
-// `cron:%`-sourced rows (System 1 / task 1344 tags cron-launched sessions). The
+// System 3 (task 1351): project-wide AUTONOMOUS api spend month-to-date. The
 // autonomy precheck's hard spend-brake compares this against a ceiling so a
 // runaway autonomous fleet self-throttles. Returns a plain number (USD).
+//
+// TWO SOURCE FAMILIES, because there are two ways this project spends money with
+// nobody watching (task 1002499):
+//   cron:%   — cron-launched SESSIONS (System 1 / task 1344).
+//   agent:%  — agent fires (modules/agents). Each one is a `claude -p` the server
+//              spawns on its own, and POST /agents/:name/invoke answers 202
+//              without waiting, so the caller is not present for the spend either.
+//
+// The agent family was the hole this closes. Agent fires recorded their cost in
+// `agents_runs.cost_usd` and nowhere else, so the brake — which reads cost_log —
+// could not see a dollar of it: the per-payer and per-agent ceilings in
+// modules/agents/lib/spend-ceiling.js bounded each wallet and each definition,
+// while the fleet-wide brake they sit under was measuring only half the fleet.
+//
+// THE PREFIX MATCH IS THE CONTRACT, not a convenience. `agent:<name>` is written
+// by exactly one place (the mirror in modules/agents/spawn.js) and the shape is
+// asserted there, so widening the brake to a family rather than a list means a
+// new agent is inside the ceiling the day it is authored, with nothing to
+// remember to add here.
 async function autonomousApiSpendMtd() {
   const { rows } = await pool.query(
     `SELECT COALESCE(SUM(amount_usd), 0) AS usd
        FROM cost_log
       WHERE category = 'api'
-        AND source LIKE 'cron:%'
+        AND (source LIKE 'cron:%' OR source LIKE 'agent:%')
         AND recorded_at >= date_trunc('month', now())`
   );
   return Number(rows[0]?.usd) || 0;

package/modules/economy/reward.js

@@ -67,6 +67,13 @@ module.exports = {
   setBuilderMonthlyBudget: (...a) => cost.setBuilderMonthlyBudget(...a),
   reconcileSessionCosts: (...a) => cost.reconcileSessionCosts(...a),
   autonomousApiSpendMtd: (...a) => cost.autonomousApiSpendMtd(...a),
+  // The one WRITE the agents module needs (task 1002499). cost_log is economy's
+  // table and modules may only cross the wall through a port (ADR 0083 / 0093 §2),
+  // so an agent fire mirrors its cost through here rather than by importing cost.js
+  // or writing the INSERT itself. It is the same logCost every other writer uses —
+  // not an agent-shaped variant — so there is still exactly one writer, which is
+  // the property modules/economy/cost-classify.js's COST_WRITE_SURFACES enumerates.
+  logCost: (...a) => cost.logCost(...a),
   leaderboard: (...a) => credits.leaderboard(...a),
   getLeaderboardWithAchievements: (...a) => achievements.getLeaderboardWithAchievements(...a),
   listAchievements: (...a) => achievements.listAchievements(...a),

package/modules/hall-ui/public/goals.states.json

@@ -18,8 +18,8 @@
   ],
   "ignoreConsole": [
     "/api/(gds|bongos)/",
-    "\b401\b",
-    "\b404\b",
+    "\\b401\\b",
+    "\\b404\\b",
     "Unauthorized",
     "Not Found",
     "load failed"

package/modules/hall-ui/public/idea.states.json

@@ -5,7 +5,7 @@
   "stub": { "prefix": "/builders/" },
   "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
   "states": {
     "record": { "auth": true, "actions": [["wait", 600]], "expect": { "visible": ["#idea-body", "#idea-h"] } },
     "missing": { "auth": true, "url": "/idea/999999", "actions": [["wait", 600]], "expect": { "visible": ["#idea-h"] } }

package/modules/hall-ui/public/ideas.states.json

@@ -6,7 +6,7 @@
   "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/"],
   "_console": "The 501 is the harness, not the page: the meter re-scores through POST /inbox/score on every keystroke and scripts/hall-preview/server.js answers every write with preview_readonly by design. Declared rather than hidden.",
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "\b501\b", "Unauthorized", "Not Found", "Not Implemented", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "\\b501\\b", "Unauthorized", "Not Found", "Not Implemented", "load failed"],
   "states": {
     "compose": { "auth": true, "actions": [["wait", 700]], "expect": { "visible": ["#fi-form", "#fi-fields", "#fi-queue"] } },
     "develop": { "auth": true, "url": "/ideas?develop=1000884", "actions": [["wait", 700]], "expect": { "visible": ["#fi-develop"] } }

package/modules/hall-ui/public/index.states.json

@@ -6,7 +6,7 @@
   "modeQuery": false,
   "_feeds": "As work.states.json: the kit's stub is not the hall's feed set, so Home renders its skeletons and empty states here. The populated dashboard is the hall-preview harness.",
   "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/me/", "/api/(gds|bongos)/tasks", "/api/(gds|bongos)/claims", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox", "/api/(gds|bongos)/live", "/api/(gds|bongos)/analytics/", "/api/(gds|bongos)/achievements", "/api/(gds|bongos)/versions", "/api/(gds|bongos)/leaderboard"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
   "_1003441": "The `leaderboard` state left with the view: the Roll is the /roster page now and #leaderboard REDIRECTS there, so there is no #view-leaderboard on this page to make visible. The redirect is proven in tests/hall_nav.mjs (it asserts location.replace('/roster') fires on the index and nowhere else) rather than by a render state, because a state whose page navigates away measures the destination, not this page. `standing-karma` replaces the coverage: task 2178 made each Standing rail section addressable and none had a measured state.",
   "states": {
     "home": { "auth": true, "expect": { "visible": ["#view-home"], "hidden": ["#view-standing"] } },

package/modules/hall-ui/public/pair.states.json

@@ -5,7 +5,7 @@
   "stub": { "prefix": "/builders/" },
   "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
   "states": {
     "request": { "auth": true, "url": "/pair?code=K7QD-4M2X", "actions": [["wait", 700]], "expect": { "visible": ["#pair-h1", "#pair-approve-btn"] } },
     "nocode": { "auth": true, "actions": [["wait", 700]], "expect": { "visible": ["#pair-h1", "#pair-scroll .pair-status--err"] } }

package/modules/hall-ui/public/settings.states.json

@@ -5,7 +5,7 @@
   "stub": { "prefix": "/builders/" },
   "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/", "/downloads/devbox/"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "/downloads/devbox/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed", "Password field"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "/downloads/devbox/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed", "Password field"],
   "states": {
     "account": { "auth": true, "actions": [["wait", 900]], "expect": { "visible": ["#settings-h1", "#display-name-input", "#craft-chips", "#privacy-rows"] } },
     "access": { "auth": true, "url": "/settings#access", "actions": [["wait", 900]], "expect": { "visible": ["#cli-reissue-btn", "#sessions-list", "#artkey-card"] } },

package/modules/hall-ui/public/task.states.json

@@ -5,7 +5,7 @@
   "stub": { "prefix": "/builders/" },
   "modeQuery": false,
   "ignoreRequests": ["/api/(gds|bongos)/"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
   "states": {
     "record": { "auth": true, "actions": [["wait", 600]], "expect": { "visible": ["#task-body", "#task-grade", "#task-sessions", "#copy-prompt-btn"] } },
     "from-goal": { "auth": true, "url": "/task/2166?from=%2Fgoals%23%2Fgoal%2F1000081", "actions": [["wait", 600]], "expect": { "visible": ["#task-back", "#copy-prompt-btn"], "attr": [["#task-back", "href", "/goals#/goal/1000081"]] } },

package/modules/hall-ui/public/work.states.json

@@ -6,7 +6,7 @@
   "modeQuery": false,
   "_feeds": "The kit's stub carries a small fixture set, not the hall's task feeds, so the board renders its EMPTY and SKELETON states here — which is the point: an empty queue is a state the floors must hold in. The feed 404s are declared, never hidden.",
   "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/me/", "/api/(gds|bongos)/tasks", "/api/(gds|bongos)/claims", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox/", "/api/(gds|bongos)/versions"],
-  "ignoreConsole": ["/api/(gds|bongos)/", "\b401\b", "\b404\b", "Unauthorized", "Not Found", "load failed"],
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
   "states": {
     "ready": { "auth": true, "expect": { "visible": ["#claim-scroll"], "hidden": ["#wip-scroll", "#backlog-scroll", "#history-scroll"] } },
     "in-progress": { "auth": true, "url": "/builders/work#in-progress", "actions": [["wait", 400]], "expect": { "visible": ["#wip-scroll"] } },

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.843",
+  "version": "1.19.844",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.843",
+      "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.843",
+  "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/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.843'; // 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');
+});

package/tests/hall_states_regex_escapes.mjs

@@ -0,0 +1,98 @@
+// tests/hall_states_regex_escapes.mjs — a states file's ignore lists are REGEX
+// SOURCES, so a JSON escape that produces a control character is a silently dead
+// pattern (task 1003638).
+//
+// THE DEFECT. `modules/ui-design/kit/lib.js` does:
+//
+//     const con = ignoreConsole.map((s) => new RegExp(s));
+//
+// so every entry is a regex source. In JSON, `"\b"` is the escape for BACKSPACE
+// (U+0008) — not the two characters a regex needs for a word boundary. Eight states
+// files wrote `"\b401\b"` where they meant `"\\b401\\b"`, compiling a pattern that
+// matches a literal backspace beside "401". Console text never contains one, so the
+// declared noise suppression did nothing and nothing ever said so.
+//
+// MEASURED across modules/hall-ui/public/*.states.json on 2026-09-17: 8 files, 17
+// entries — goals, idea, ideas, index, pair, settings, task, work. (The row that
+// filed this named only `work`, and listed `task`, `idea` and `ideas` among the
+// HEALTHY files; all three were broken. The fix followed the computed list.)
+//
+// Run:  node --test tests/hall_states_regex_escapes.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIR = path.join(REPO_ROOT, 'modules/hall-ui/public');
+const REGEX_LISTS = ['ignoreConsole', 'ignoreRequests', 'ignoreControls'];
+const CONTROL = /[\x00-\x1f]/;
+
+const files = readdirSync(DIR).filter((n) => n.endsWith('.states.json'));
+
+test('there are states files to check — an empty sweep must not read as a pass', () => {
+  assert.ok(files.length > 10, `expected the hall states files, found ${files.length}`);
+});
+
+test('no ignore-list entry contains a control character', () => {
+  const offenders = [];
+  for (const name of files) {
+    const json = JSON.parse(readFileSync(path.join(DIR, name), 'utf8'));
+    for (const key of REGEX_LISTS) {
+      if (!Array.isArray(json[key])) continue;
+      for (const entry of json[key]) {
+        if (CONTROL.test(entry)) {
+          const codes = [...entry].map((c) => c.charCodeAt(0)).filter((n) => n < 32)
+            .map((n) => `U+${n.toString(16).padStart(4, '0')}`).join(',');
+          offenders.push(`${name} ${key}: ${JSON.stringify(entry)} (${codes})`);
+        }
+      }
+    }
+  }
+  assert.deepEqual(offenders, [],
+    `a JSON escape produced a control character in a regex source — almost certainly \\b meant as a word boundary:\n  ${offenders.join('\n  ')}`);
+});
+
+test('every ignore-list entry compiles as a regex', () => {
+  // lib.js calls new RegExp(s) with no try/catch, so an uncompilable entry is a
+  // crash in the walk rather than a dead pattern.
+  const bad = [];
+  for (const name of files) {
+    const json = JSON.parse(readFileSync(path.join(DIR, name), 'utf8'));
+    for (const key of REGEX_LISTS) {
+      if (!Array.isArray(json[key])) continue;
+      for (const entry of json[key]) {
+        try { new RegExp(entry); } catch (e) { bad.push(`${name} ${key}: ${JSON.stringify(entry)} — ${e.message}`); }
+      }
+    }
+  }
+  assert.deepEqual(bad, [], `uncompilable regex source:\n  ${bad.join('\n  ')}`);
+});
+
+test('the word-boundary patterns actually match a real console line', () => {
+  // The behavioural half: shape alone would still pass if someone "fixed" the control
+  // character by deleting it (leaving "401", which over-matches, e.g. "1401ms").
+  const line = 'Failed to load resource: the server responded with a status of 404 (Not Found)';
+  const work = JSON.parse(readFileSync(path.join(DIR, 'work.states.json'), 'utf8'));
+  const matched = work.ignoreConsole.some((s) => new RegExp(s).test(line));
+  assert.equal(matched, true, 'the declared 404 suppression must match a real 404 console line');
+
+  // And the boundary must still be a boundary — not a bare number.
+  const boundary = work.ignoreConsole.find((s) => s.includes('404'));
+  assert.ok(boundary, 'a 404 entry must exist');
+  assert.equal(new RegExp(boundary).test('elapsed 1404ms'), false,
+    'the pattern must not match a 404 embedded in a longer number — that is what the word boundary is for');
+});
+
+test('the broken form is genuinely inert — this is what the bug cost', () => {
+  // Pins WHY it was invisible: the old value silently matched nothing rather than
+  // erroring, so every gate stayed green while the suppression did nothing.
+  const broken = '\x08404\x08';
+  const line = 'Failed to load resource: the server responded with a status of 404 (Not Found)';
+  assert.equal(new RegExp(broken).test(line), false,
+    'the backspace form matches nothing — silent, which is why it survived');
+  assert.doesNotThrow(() => new RegExp(broken),
+    'and it compiles, so nothing ever complained');
+});