@bongos/core 1.19.842 → 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.842",
-  "core_contract": "1.19.842",
-  "source_commit": "ffa8d1ce17675d5981142ca6588ef641d0893058",
+  "core_version": "1.19.844",
+  "core_contract": "1.19.844",
+  "source_commit": "980c92b65de8a99f2772b86fb7f69e365eed4dc6",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T18:21:47.399Z",
+  "built_at": "2026-09-17T18:59:26.454Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 495,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2266,
+    "functional_verbatim": 2272,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2787,
-  "tree_sha256": "204ee5631e422b90ff1d79a7fde81706ca492bea501801a162421ebd04f6bfdb",
+  "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": "033de93b8ea7781edf94b6b1146741c2bde76443ecf7b6c8b1bf47d8919d6bab"
+      "sha256": "185ae1211c5c546bf5d0a57acd5c97ad56b4e98133ba2aceded36bf2cc95c4ca"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3679,6 +3679,11 @@
       "mode": "0000644",
       "sha256": "0481e0b8205c707ed002f404c801d3f2059b2b0e0fcfa9bc436968f6665a296f"
     },
+    {
+      "path": "migrations/core_247_discipline_required.sql",
+      "mode": "0000644",
+      "sha256": "e8d3e3f764b61ea559df7f997758e639f8778ee24da4293908e9d45ca30a425b"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -3707,7 +3712,7 @@
     {
       "path": "modules/agents/lib/spend-ceiling.js",
       "mode": "0000644",
-      "sha256": "97bfcea1cd580df4765bff92a1b26f56bfe467501bfd1c566ff7df9ec4ac746b"
+      "sha256": "1144ee9be9cb3df57e876a868529ddbf78864fac1fdabc90ed2e010bd8d376a8"
     },
     {
       "path": "modules/agents/lib/validate.js",
@@ -3729,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",
@@ -3737,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",
@@ -3882,7 +3892,7 @@
     {
       "path": "modules/copy-desk/routes/copy-desk.js",
       "mode": "0000644",
-      "sha256": "63ed245f47d15758ef0926a489ad1fc7ef56d8539e836ed9e319e09b99a4a38e"
+      "sha256": "4839f077aee504947a3bada77fd9c3df882f9005f571ed2e2367b615c111b76b"
     },
     {
       "path": "modules/copy-desk/tests/copy_flags.mjs",
@@ -4292,7 +4302,7 @@
     {
       "path": "modules/economy/cost-classify.js",
       "mode": "0000644",
-      "sha256": "22b0b50ae46850a8d0a9de40eeced47df6edc671eada63529d48a1486aea4d75"
+      "sha256": "fefd4908bd22aa3b747a7c8b4146e5a7e53731fe92612db105ea3512ae34300c"
     },
     {
       "path": "modules/economy/cost-summary-shape.js",
@@ -4302,7 +4312,7 @@
     {
       "path": "modules/economy/cost.js",
       "mode": "0000644",
-      "sha256": "01bc7725fe16388971fd4def2544d0de9af6b3a522973df7ef86386737933d40"
+      "sha256": "6cc28fe57bb50b6c3f4b7d4485838427fa5f12b5a79848f0358fdaa2874f6c1e"
     },
     {
       "path": "modules/economy/credits.js",
@@ -4332,7 +4342,7 @@
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
-      "sha256": "e026156d1578bc6c0ce43a197575601e9663e608819d8c92ca713e17ecbf0b3d"
+      "sha256": "c4245b1b7c361eb44e0034f19227e208b956e9eb9ac03924e22b3017dd4a343a"
     },
     {
       "path": "modules/economy/routes/cost.js",
@@ -4952,7 +4962,7 @@
     {
       "path": "modules/hall-ui/public/goals.states.json",
       "mode": "0000644",
-      "sha256": "8e955be7fb6aef55b6aac0c586b27963f032bab9bec743b56a5987b6276cc8d3"
+      "sha256": "14aefbb8b94ebc3df68744052f465b63ceaf3361f98a94972781ae01bc616735"
     },
     {
       "path": "modules/hall-ui/public/government.css",
@@ -5032,7 +5042,7 @@
     {
       "path": "modules/hall-ui/public/idea.states.json",
       "mode": "0000644",
-      "sha256": "4b8ea0bb4eac805b8d85556830104b07b2b0612ba1b8337bab6fb7368a887995"
+      "sha256": "2299490186e19f2369069562dc8ba8dd837a2e89bfa94c7797f350cc653659c9"
     },
     {
       "path": "modules/hall-ui/public/ideas.css",
@@ -5052,7 +5062,7 @@
     {
       "path": "modules/hall-ui/public/ideas.states.json",
       "mode": "0000644",
-      "sha256": "f75230d5d770d4780b7c9fb28c40c8f44a91354e61f3d0a9a6281c90904a80c8"
+      "sha256": "889041e8bcff6e7fa53f6bd09d0bed670e6b58cd68cda2ff7147a1a253e33e8d"
     },
     {
       "path": "modules/hall-ui/public/index.html",
@@ -5062,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",
@@ -5112,7 +5122,7 @@
     {
       "path": "modules/hall-ui/public/pair.states.json",
       "mode": "0000644",
-      "sha256": "10d19605f074dedd85634fe1ed2eb06f06189e90778b1ce7d87d7b369ba428c6"
+      "sha256": "3c48d1588f8512f0f9a0d5774acdf88c9a761e6b9f5f3da2d544a32bc06b4ab8"
     },
     {
       "path": "modules/hall-ui/public/palette.js",
@@ -5342,7 +5352,7 @@
     {
       "path": "modules/hall-ui/public/settings.states.json",
       "mode": "0000644",
-      "sha256": "02c0591b014806e991478c720658b0e74129e2e8c1ffcdd8e3384c681201a295"
+      "sha256": "2d9f55bb007891b5d5b4511d7f29a20d01477a8395c84c259a42a7e6157aced9"
     },
     {
       "path": "modules/hall-ui/public/shell.js",
@@ -5407,7 +5417,7 @@
     {
       "path": "modules/hall-ui/public/task.states.json",
       "mode": "0000644",
-      "sha256": "fb7112aff3834f88305e9705335dd6b0527cc1cea8f4a1b7d5842b377437da9e"
+      "sha256": "1be94e892012740aae899aa28425f4be9c94a5ae777c8c77e5e1b787791f5ec9"
     },
     {
       "path": "modules/hall-ui/public/triumph.wav",
@@ -5452,7 +5462,7 @@
     {
       "path": "modules/hall-ui/public/work.states.json",
       "mode": "0000644",
-      "sha256": "929512f085f138f93170f643dbd68615dfbf6d5fcd5f0bf1abf30a081154b536"
+      "sha256": "786373b132587480ff58452286f950d246eae430f7531f0ccf4d01f290fdc435"
     },
     {
       "path": "modules/ideas/CLAUDE.md",
@@ -5477,7 +5487,7 @@
     {
       "path": "modules/ideas/inbox.js",
       "mode": "0000644",
-      "sha256": "683e2234893c9814c2ecec490099c140e273e764e993707bb1cc4c5c9d1baed3"
+      "sha256": "ff6c0346215d1b88309c4c9360cd60c59299b21b45e27cce09c4b748bf3411e1"
     },
     {
       "path": "modules/ideas/migrations/ideas_001_grades.sql",
@@ -5657,7 +5667,7 @@
     {
       "path": "modules/lifecycle/db-tasks.js",
       "mode": "0000644",
-      "sha256": "87b075187493e8026f99912dceb7195d09564bfe3f969f344141661c60ef6558"
+      "sha256": "5d17541d837a06903be832814a74218c9fee8b9119dd870c88273743be5a5efa"
     },
     {
       "path": "modules/lifecycle/db-versions.js",
@@ -5752,7 +5762,7 @@
     {
       "path": "modules/lifecycle/lifecycle.js",
       "mode": "0000644",
-      "sha256": "bdc23f748853a4a39ae416f731052bd29e4fe5788684cb83a166243d9240a364"
+      "sha256": "41ef55efff7f334ee8b19490f03944ca25f22454c718dfb81445539bc6a77aa4"
     },
     {
       "path": "modules/lifecycle/merge-lock.js",
@@ -5877,7 +5887,7 @@
     {
       "path": "modules/lifecycle/routes/goals.js",
       "mode": "0000644",
-      "sha256": "eb3137c30f6471aa0900f98f0fa45752808609e4e1e99f9ecb1f6df0d3e7c5ab"
+      "sha256": "17f7c0ccfc87eec24c662bf8d5599223562e773430802cd054b27a3ddadab46e"
     },
     {
       "path": "modules/lifecycle/routes/help-requests.js",
@@ -5922,7 +5932,7 @@
     {
       "path": "modules/lifecycle/routes/task-write-routes.js",
       "mode": "0000644",
-      "sha256": "9cff3bcd27467dc413aa975cd20262b47e8595a50a845d93b557a24828719bbf"
+      "sha256": "bb172485d8d5f84d96cdb611b0d57cd5f69ee768bdceddeb1eea42dc3f5676c1"
     },
     {
       "path": "modules/lifecycle/routes/tasks.js",
@@ -5962,7 +5972,7 @@
     {
       "path": "modules/lifecycle/task-classifier.js",
       "mode": "0000644",
-      "sha256": "9299590b71b194087174ff0212dc70f5f28fbafd5678923c81a3db13c6b78db5"
+      "sha256": "39047afd6440d589cee978887ce4b5fa285b00d55ed2b023546fce41e59bdc9c"
     },
     {
       "path": "modules/lifecycle/task-list-limits.js",
@@ -7892,12 +7902,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "21b80f9aba47da61edcb4a374ad4aad35f2e5c563cccb1daae278b6d892d0255"
+      "sha256": "a6133e7d6f098080ea0b2d2d21d3bbf35c90a716dc20a4436a68c74c6416da84"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "61f48c57b02632310e7ba92115fdc6939efe7967f2ee7542fa7b12834f8af6c2"
+      "sha256": "65a0092e9c2f20b87c7de5d89e552e005820a70cc5c00fb228d904363d842b22"
     },
     {
       "path": "public-docs/index.html",
@@ -8064,6 +8074,11 @@
       "mode": "0000644",
       "sha256": "9c03bf914c4a1a6f5d9936bb5542a4e3952873de65b0518254808bfbd1901b40"
     },
+    {
+      "path": "scripts/gds/backfill-disciplines.js",
+      "mode": "0000644",
+      "sha256": "cc9bd2d437e6a7d6eb2b48504cc7d7c44a674403a0d00625a0526719825f88d2"
+    },
     {
       "path": "scripts/gds/backfill-session-earnings.js",
       "mode": "0000644",
@@ -8432,7 +8447,7 @@
     {
       "path": "scripts/gds/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "b3f4092fffd30e50cb145b524beeed5d483132f52e77e37a7ab9c18bbf300bc7"
+      "sha256": "178d2cfb91c97c107d60cc3895ba1b3eff74c45d383646e7a64621d018c21b47"
     },
     {
       "path": "scripts/gds/fitness.js",
@@ -8577,7 +8592,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "9f0b3c283caf637ff6e3b514a417ae3e42572b323a14c83cd89beda270c49c37"
+      "sha256": "e1fbe45a7619cd5000b5bb34c80bbd63c2591dcc78a64188870847e5da049448"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9367,7 +9382,7 @@
     {
       "path": "scripts/gds/triage.js",
       "mode": "0000644",
-      "sha256": "de0673313c1eb5e052f993138cd2d5686f9c1de1f9acd00f8a5fca73ed361db2"
+      "sha256": "a4af12591b829f9b89a5768858e8a2ba02a44d7e7ebd848e945e77f95fc55da7"
     },
     {
       "path": "scripts/gds/turn-end-sound.js",
@@ -9827,7 +9842,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "84e310a550189d0d3d86f825cc04d61d81e0c0dc78428056661357a1a5076e74"
+      "sha256": "a97295bdd0b3f0fe6b6c903b910a2512e7fffcc4a98f6d2844096cbc6015d7a7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9987,7 +10002,7 @@
     {
       "path": "tests/agents_spend_guard.mjs",
       "mode": "0000644",
-      "sha256": "8bed5bc6e737f17038b3fba4f5c73a0478b0dd581b506e5a0bbd31754ff8a758"
+      "sha256": "dde31247e6cb995487e21f78d5b44bfb24bc087bd7736c5a130ed4d8822d0cb7"
     },
     {
       "path": "tests/agents_sync.mjs",
@@ -11679,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",
@@ -11989,6 +12009,11 @@
       "mode": "0000644",
       "sha256": "416d413757a13fbddb5841ea8a2c503077d7e6067bc1c58ce1f4d416b8d8487f"
     },
+    {
+      "path": "tests/knip_ratchet_ambient.mjs",
+      "mode": "0000644",
+      "sha256": "b48d7f46c4518ef7da8e252d8009edd25ec5771f7be320f889f437762af72b54"
+    },
     {
       "path": "tests/known_failing_ratchet.mjs",
       "mode": "0000644",
@@ -12862,7 +12887,7 @@
     {
       "path": "tests/rank_floor_wiring.mjs",
       "mode": "0000644",
-      "sha256": "f81f559b5428497b2246580c7921ecd1ba5a2f1034cf29eb5e5c21b04675f216"
+      "sha256": "973fc0768bd52f3e25c98306c21cc6a9c6268daae033e1329c68620a847bc0a9"
     },
     {
       "path": "tests/rank_gate.mjs",
@@ -12972,7 +12997,7 @@
     {
       "path": "tests/reward_gate.mjs",
       "mode": "0000644",
-      "sha256": "1ed242c879472dd872c1327c8e7c91de61886dcb108ece3fa455ae6be4b4e025"
+      "sha256": "0cd9f335da162c3562c099a2dbe4375b009f5a8a8321f4ef84b7a577be816bdc"
     },
     {
       "path": "tests/reward_mode_cost_plus_only.mjs",
@@ -13619,6 +13644,11 @@
       "mode": "0000644",
       "sha256": "0bc0d93696b5ce80fb4307b7991bff640316e46fd6fcdebf0ba5a62397ffbe8f"
     },
+    {
+      "path": "tests/task_discipline_required.mjs",
+      "mode": "0000644",
+      "sha256": "2fda6816614259699227a21f97b81d816f20fdd654c861e24a282c1d178ddff4"
+    },
     {
       "path": "tests/task_field_bounds_match_db.mjs",
       "mode": "0000644",
@@ -13637,7 +13667,7 @@
     {
       "path": "tests/task_goal_required.mjs",
       "mode": "0000644",
-      "sha256": "04e7a36f7c2f5a94f847fcb4b77f017f6399fc96041cdaee1123c9a6fecb3d5d"
+      "sha256": "073581d9a97095666ee2ed7ebb0a6b280f3e8ea1efc53015c2f77eb5d08c4975"
     },
     {
       "path": "tests/task_lib.mjs",

package/docs/module-api-changelog.md

@@ -2158,5 +2158,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.840 with no explicit bump. run 35257419225. (task 1002620)
   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 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/migrations/core_247_discipline_required.sql

@@ -0,0 +1,58 @@
+-- core_247_discipline_required.sql — task 1002988: every task row carries a craft.
+--
+-- `unclassified` is a triage state, not a craft. It was the DEFAULT on every create
+-- vector, so it accumulated: 1,189 rows on this instance as of 2026-09-17 (1,025
+-- real + 164 __smoke__ test rows), of which only 208 were live work. A row nobody's
+-- craft owns is a row nobody picks up.
+--
+-- THE ACCEPTED SET IS FOUR, NOT THREE. The task was written on 2026-08-16 naming
+-- {engineer, artist, ideator}. ADR 0272 (2026-09-09) postdates it and KEEPS `ui` as
+-- a module-contributed discipline, and the owner reconfirmed that on 2026-09-17 when
+-- abandoning the sibling task 1002987 ("Delete the ui role across the platform") for
+-- exactly this reason. Narrowing to three would break 50+ live `ui` rows and
+-- contradict a live ADR, so migration 176's `ui` entry survives untouched here.
+--
+-- WHY THE BACKFILL IS IN THE MIGRATION. The good classification is done by
+-- scripts/gds/backfill-disciplines.js, which runs the real JS heuristic
+-- (classifyTaskDiscipline) and cannot be expressed in SQL. But a migration that
+-- assumes a script was run by hand is a migration that breaks the next fresh
+-- install, the next instance, and any checkout where nobody remembered. So the
+-- UPDATE below is the LAST-RESORT NET, not the plan: it catches whatever the script
+-- left (or everything, if the script never ran) and parks it on 'engineer' — the
+-- value ~99% of confidently-classified rows resolve to.
+--
+-- That fallback is a GUESS and is recorded as one. The owner chose it on 2026-09-17
+-- over the alternative (backfill live work only, leave history alone), accepting
+-- that the ~273 rows the classifier refuses get a best guess rather than a known
+-- answer. Do not read a post-migration `discipline` on an old row as evidence that
+-- anyone determined it.
+--
+-- Idempotent: safe to re-run. The UPDATE matches nothing on a second pass, and the
+-- constraint is dropped before being re-added (the pattern of migrations 086/176).
+-- Forward-safe: the column is unchanged and the previous release wrote only values
+-- this constraint still accepts, EXCEPT 'unclassified' — a rolled-back deploy whose
+-- code still defaults to 'unclassified' would have its INSERTs rejected. That is the
+-- intended behaviour (it is the hole being closed), and it is why the application
+-- side of this task resolves the discipline at db-tasks.createTask, the single
+-- chokepoint every create vector passes through, rather than only at the two routes.
+
+BEGIN;
+
+-- 1. The last-resort net (see header). Everything the classifier could call should
+--    already have been PATCHed by backfill-disciplines.js before this runs.
+UPDATE tasks SET discipline = 'engineer' WHERE discipline = 'unclassified' OR discipline IS NULL;
+
+-- 2. Narrow the accepted set: drop 'unclassified', keep 'ui' (ADR 0272).
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_discipline_check;
+ALTER TABLE tasks ADD CONSTRAINT tasks_discipline_check
+  CHECK (discipline IN ('engineer', 'artist', 'ideator', 'ui'));
+
+-- builders.preferred_disciplines already excludes 'unclassified' (migration 176 —
+-- "Never carries 'unclassified' — that's a task state, not an interest area"), so it
+-- needs no change here. Named rather than silently skipped, so the next reader does
+-- not have to re-check.
+
+INSERT INTO schema_migrations (version) VALUES ('core_247_discipline_required')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

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