@bongos/core 1.19.357 → 1.19.358

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.357",
-  "core_contract": "1.19.357",
-  "source_commit": "3c8f80201ef2dd9992ceea78af1081b7cd74524d",
+  "core_version": "1.19.358",
+  "core_contract": "1.19.358",
+  "source_commit": "6bfaa149e1894ef5d78af75527e0158d951470c7",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T16:20:35.425Z",
+  "built_at": "2026-08-25T16:32:44.606Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 330,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1511,
+    "functional_verbatim": 1515,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1863,
-  "tree_sha256": "03a3fad69d2b334568f719ebc41a4cdde66d922efaae81ac1857f85baa39f760",
+  "file_count": 1867,
+  "tree_sha256": "bac9c3fc06876d7ba5183bf4a6ace1bdda8e43a3e5f18037d3ebb4e006d7fa7a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2499,6 +2499,21 @@
       "mode": "0000644",
       "sha256": "a379e9f926274559d8c57c9127024463e38b99e3f73962022b9f5d0f4e156a57"
     },
+    {
+      "path": "modules/agents/migrations/agents_001_definitions.sql",
+      "mode": "0000644",
+      "sha256": "a35cb06d31f05acdc9bee40a977346d258acda79174944361710f3733dd69a2f"
+    },
+    {
+      "path": "modules/agents/module.json",
+      "mode": "0000644",
+      "sha256": "055d1a806c40d8153b45bac2518b183874d9a8df7924f00355c86ed50682dd24"
+    },
+    {
+      "path": "modules/agents/spawn.js",
+      "mode": "0000644",
+      "sha256": "657e6a314e9daec8a7a3d17c3eee1ccfc35aaa1390d89fa0dd135d6365c103b1"
+    },
     {
       "path": "modules/autonomy/CLAUDE.md",
       "mode": "0000644",
@@ -4802,12 +4817,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b1353851e7bd50f58b47d0191076eacc249bdca62553d0bb9a6ee767aed9c712"
+      "sha256": "b155c2a0dda8e0bcfbd1efadbc4ef619a25be608f9e29714e7039f24267bcd25"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "632ea5fa7541ae2eb15f7afdc97f5414b65e1cadcf627e03ed7aee1f1443a0c0"
+      "sha256": "1f7444718fbae90aa6d3b0f6c33c6cc1052cf48917a3c1c030f7a9de7806ce53"
     },
     {
       "path": "public-docs/index.html",
@@ -5832,7 +5847,7 @@
     {
       "path": "scripts/gds/publish-manifest.js",
       "mode": "0000644",
-      "sha256": "387a6846692f05c4adee5651a6f45780ec12f24de12621e73014e79ea4c47342"
+      "sha256": "12b3b200c1f60cc8a287d9a3ca2dd28201fda3cc219e83dffb60913c084e0413"
     },
     {
       "path": "scripts/gds/pulse.js",
@@ -6667,7 +6682,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "2376b2c1c18430faa5dc61183b3dace18e5d991515aa508fcb3d739ba9342701"
+      "sha256": "fdd1d69409cf0ac75e9063d0ec0bf742c83aba0cdc9f15935839c9c6998e96af"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6744,6 +6759,11 @@
       "mode": "0000644",
       "sha256": "125edcec8c7d7536365b9675daa1fceb9fe072a30e2a4a68ee2911cd258a8c10"
     },
+    {
+      "path": "tests/agents_spawn.mjs",
+      "mode": "0000644",
+      "sha256": "8cc261471a36e3c447df57b46082997b6a50da3c8ff4b214787ae55ab27cb9ef"
+    },
     {
       "path": "tests/api_cli_flags.mjs",
       "mode": "0000644",
@@ -8657,7 +8677,7 @@
     {
       "path": "tests/publish_manifest.mjs",
       "mode": "0000644",
-      "sha256": "a5e36e0a0d228638c499ccac2559bd947a85735e1a922a32c7c1377c98ed2a60"
+      "sha256": "5eca5f50f200166ce0fd7e40a57e18fffb135139fe558d0dda34064d426814dc"
     },
     {
       "path": "tests/publish_reconciler.mjs",

package/modules/agents/migrations/agents_001_definitions.sql

@@ -0,0 +1,301 @@
+-- agents_001_definitions.sql — the agent registry + the fire ledger.
+--
+-- Two tables for the agents module (goal 1000038, Phase 1):
+--
+--   agents_definitions — the REGISTRY. One row per declarative agent definition,
+--     whether it came from a committed `.claude/agents/*.md` file (source='file',
+--     reconciled at deploy by agents-sync.js) or was authored in the instance
+--     against the DB (source='db'). Files-are-source: the sync upserts file rows
+--     and must never clobber a db row, so `source` is load-bearing, not a label.
+--
+--   agents_runs — the LEDGER. One row per fire: what triggered it, what the gate
+--     decided, what the spawn cost, and where the output went. Every fire is
+--     recorded — ESPECIALLY a refusal, for the same reason autonomy_runs records
+--     a no-go: a gate that silently declines is indistinguishable from a gate
+--     that never ran.
+--
+-- NAMESPACE NOTE (why `agents_definitions`, not `agent_definitions`). Module
+-- objects must carry the module key's own prefix, and this module's key is
+-- `agents` — so the wall is `agents_`, and a singular `agent_definitions` fails
+-- the fitness gate (`scripts/gds/fitness.js` Check 11) rather than being a style
+-- quibble. The plural prefix is the price of the namespace; downstream tasks
+-- (1002488 read routes, 1002489 spawn adapter, 1002490 agents-sync) read
+-- `agents_definitions` / `agents_runs`.
+--
+-- FAIL-CLOSED ENUMS. `trigger_type`, `model_tier`, `source`, `provenance` and the
+-- run's `status` are text + CHECK rather than Postgres enum TYPEs: the constraint
+-- pins today's WIRED vocabulary closed (an unwired trigger name is refused, never
+-- silently accepted — the same rule task 1002487's EVENT_CATALOG enforces in JS),
+-- and widening later is a one-line constraint change in a subsequent agents_*
+-- migration instead of an enum-type migration.
+--
+-- A DEFINITION IS NEVER ARMED BY ACCIDENT. Two invariants below are the DB half
+-- of rules the code also enforces, and they exist because "enabled" is the field
+-- that turns a piece of text into something that spends money and reads the repo:
+--   • a definition that tripped the scope wall CANNOT be enabled — the sync
+--     imports it disabled + flagged (task 1002490), and this constraint means a
+--     later stray UPDATE cannot quietly arm it;
+--   • an enabled definition MUST carry an author_rank — authority comes from the
+--     author's LIVE DB rank (ADR 0016), never from anything written in the file,
+--     so a definition with no known author has no authority to run.
+--
+-- STRUCTURE ONLY, NEVER AGENT OUTPUT. `agents_runs.output_ref` is a POINTER to
+-- where a run's output landed — never the output itself. An agent's output is
+-- model-generated text that is later rendered to whoever reads the ledger, so
+-- storing it inline would make this table a delivery path for whatever the agent
+-- read. Same rule, same reason as `security_tool_scans.findings_summary`.
+--
+-- 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) so its stem never collides across repos.
+-- `scripts/migrate.sh` discovers + applies this only when the agents module is
+-- enabled — and the module ships `default:false` (task 1002485), so on a vanilla
+-- instance this file is correctly skipped. Idempotent: safe to re-run.
+
+BEGIN;
+
+-- ---------------------------------------------------------------------------
+-- agents_definitions — the registry
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS agents_definitions (
+  id                    bigserial PRIMARY KEY,
+
+  -- The agent key. For a file-sourced definition this is the `.claude/agents/`
+  -- filename stem, which is why the format check matches the module-key shape:
+  -- it has to be safe as a filename, a URL path segment, and a CLI argument.
+  name                  text NOT NULL,
+  title                 text,
+  -- The role/system prompt. REQUIRED — task 1002487's validator rejects a
+  -- definition with no persona, and a NOT NULL here means a row that skipped the
+  -- validator still cannot exist without one.
+  persona               text NOT NULL,
+
+  -- What fires it. 'event' consumes the wired event catalog; 'on-demand' is the
+  -- historian-exemplar shape (a builder asks, the agent answers). trigger_spec
+  -- carries the type's parameters — for 'event', at minimum {"event": "..."}.
+  trigger_type          text NOT NULL,
+  trigger_spec          jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  -- Which subagent tier this spawns at. Resolved to a concrete model id at fire
+  -- time from the branding pack's `models` block (task 1002489) — the tier is
+  -- stored, never the model id, so an instance re-pointing its tiers moves every
+  -- agent with it instead of leaving a pinned model behind.
+  --   'default' → models.subagentDefault   'routine' → models.subagentRoutine
+  -- Deliberately NO 'main' tier: an agent is a subagent, never the main session.
+  model_tier            text NOT NULL DEFAULT 'default',
+
+  -- The declared scope wall. scope_modules names module keys the agent may work
+  -- within; scope_paths narrows further. The wall is re-evaluated SERVER-SIDE at
+  -- sync (task 1002490) — a definition scoped onto protected paths lands with
+  -- scope_violation set, which the constraint below makes un-armable.
+  scope_modules         text[] NOT NULL DEFAULT '{}',
+  scope_paths           text[] NOT NULL DEFAULT '{}',
+  scope_violation       text,
+
+  -- Where this row came from, and whether the sync owns it. 'file' rows are
+  -- rewritten from the committed definition on every deploy; 'db' rows are
+  -- instance-authored and must SURVIVE a deploy untouched (task 1002490).
+  source                text NOT NULL,
+  -- 'built-in' (ships with the core) vs 'instance' (authored by this instance).
+  -- Distinct from `source`: a built-in agent is file-sourced, but an instance can
+  -- also commit its own file. Provenance answers "whose agent is this", source
+  -- answers "who may overwrite the row".
+  provenance            text NOT NULL,
+
+  -- The author's LIVE DB rank at the moment the row was written (ADR 0016).
+  -- Never read from the definition file — a file cannot grant authority.
+  author_rank           text,
+  author_builder_id     bigint REFERENCES builders(id) ON DELETE SET NULL,
+
+  -- File provenance, for source='file'. source_sha256 is over the definition's
+  -- bytes so the sync can tell "unchanged" from "edited" without re-parsing, and
+  -- so a row can be traced back to the exact committed text that produced it.
+  source_path           text,
+  source_sha256         text,
+  last_synced_at        timestamptz,
+
+  -- Shipped != enabled, at the row level as well as the module level. A newly
+  -- synced definition lands OFF; arming it is a separate, deliberate act.
+  enabled               boolean NOT NULL DEFAULT false,
+
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  -- One row per agent name. This is what makes the sync an UPSERT rather than an
+  -- append, and what stops two definitions from answering to the same name.
+  CONSTRAINT agents_definitions_name_uniq UNIQUE (name),
+  -- Filename/CLI/URL-safe, and stable: the same shape a module key must take.
+  CONSTRAINT agents_definitions_name_fmt_chk
+    CHECK (name ~ '^[a-z][a-z0-9-]*$' AND length(name) <= 64),
+  -- v1 wires exactly these two trigger types. Anything else is refused here, not
+  -- silently stored and quietly never fired.
+  CONSTRAINT agents_definitions_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand')),
+  CONSTRAINT agents_definitions_trigger_spec_shape_chk
+    CHECK (jsonb_typeof(trigger_spec) = 'object'),
+  -- An event-triggered definition with no event name is a definition that can
+  -- never fire; the catalog membership check itself lives in the validator, which
+  -- can name the offending event in its error.
+  CONSTRAINT agents_definitions_event_needs_name_chk
+    CHECK (trigger_type <> 'event'
+           OR (trigger_spec ? 'event' AND length(trigger_spec ->> 'event') > 0)),
+  CONSTRAINT agents_definitions_model_tier_chk
+    CHECK (model_tier IN ('default', 'routine')),
+  CONSTRAINT agents_definitions_source_chk
+    CHECK (source IN ('file', 'db')),
+  CONSTRAINT agents_definitions_provenance_chk
+    CHECK (provenance IN ('built-in', 'instance')),
+  CONSTRAINT agents_definitions_author_rank_chk
+    CHECK (author_rank IS NULL OR author_rank IN ('xenos', 'thetes', 'metic', 'archon')),
+  -- A file-sourced row must say WHICH file, or the next sync cannot reconcile it.
+  CONSTRAINT agents_definitions_file_needs_path_chk
+    CHECK (source <> 'file' OR source_path IS NOT NULL),
+  -- The two arming invariants (see the header). A flagged definition stays
+  -- disabled; an anonymous definition has no rank to act with, so it stays off.
+  CONSTRAINT agents_definitions_flagged_not_armed_chk
+    CHECK (scope_violation IS NULL OR enabled = false),
+  CONSTRAINT agents_definitions_armed_needs_author_chk
+    CHECK (enabled = false OR author_rank IS NOT NULL),
+  -- Defense in depth with the validator's own caps: a persona is a prompt sent to
+  -- a paid model on every fire, so an unbounded one is both a cost and a blast
+  -- radius. trigger_spec is parameters, never payload.
+  CONSTRAINT agents_definitions_persona_size_chk
+    CHECK (length(persona) <= 32768),
+  CONSTRAINT agents_definitions_trigger_spec_size_chk
+    CHECK (length(trigger_spec::text) <= 8192)
+);
+
+-- "Which definitions fire on event X?" — the dispatch lookup, and the only read
+-- on the hot path. Partial: a disabled definition is never dispatched, so its
+-- rows are dead weight in this index.
+CREATE INDEX IF NOT EXISTS agents_definitions_enabled_trigger_idx
+  ON agents_definitions (trigger_type, (trigger_spec ->> 'event'))
+  WHERE enabled;
+
+-- "What does the sync own?" — agents-sync.js walks file rows to reconcile them
+-- and must never touch the db rows beside them (task 1002490).
+CREATE INDEX IF NOT EXISTS agents_definitions_source_idx
+  ON agents_definitions (source, name);
+
+-- "What tripped the scope wall?" — the review queue for flagged imports. Small
+-- by construction, so partial.
+CREATE INDEX IF NOT EXISTS agents_definitions_flagged_idx
+  ON agents_definitions (updated_at DESC)
+  WHERE scope_violation IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- agents_runs — one row per fire
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS agents_runs (
+  id                    bigserial PRIMARY KEY,
+
+  -- The definition that fired. ON DELETE SET NULL, not CASCADE: the ledger is the
+  -- record of what this instance actually spent and ran, and deleting a
+  -- definition must not erase its history. agent_name is denormalized for exactly
+  -- that case — the run stays attributable after the row it pointed at is gone.
+  definition_id         bigint REFERENCES agents_definitions(id) ON DELETE SET NULL,
+  agent_name            text NOT NULL,
+
+  -- What fired it, as a stable reference rather than prose: the event and its
+  -- subject ('task.shipped:1002486'), or the on-demand caller. Kept as text so a
+  -- trigger can reference a record type this module does not own.
+  trigger_ref           text,
+  trigger_type          text NOT NULL,
+
+  -- The gate's decision for this fire, recorded whether or not anything spawned.
+  -- Same vocabulary as autonomy_runs ('go' | 'no-go') so the two ledgers read the
+  -- same way.
+  gate_decision         text NOT NULL,
+  gate_reason           text,
+
+  -- What became of the run. 'skipped' is the terminal state of a no-go (nothing
+  -- spawned); 'pending' covers a run in flight so a crashed spawn is visible as
+  -- unfinished rather than vanishing.
+  status                text NOT NULL DEFAULT 'pending',
+  error_code            text,
+
+  -- The CONCRETE model the tier resolved to at fire time, so an old row is never
+  -- re-read as though it ran on today's tier mapping.
+  model                 text,
+  -- What the fire actually cost. Spawns route through the grade port, which bills
+  -- into the LLM cost cache (task 1002489); this column is the per-agent view of
+  -- that spend, which is what an instance's ~$/agent/month cap reads.
+  cost_usd              numeric(10, 4),
+  duration_ms           integer,
+
+  -- A POINTER to where the output landed — never the output. See the header.
+  output_ref            text,
+
+  requested_by_builder_id bigint REFERENCES builders(id) ON DELETE SET NULL,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT agents_runs_gate_decision_chk
+    CHECK (gate_decision IN ('go', 'no-go')),
+  CONSTRAINT agents_runs_status_chk
+    CHECK (status IN ('pending', 'ok', 'error', 'skipped')),
+  CONSTRAINT agents_runs_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand')),
+  -- A refusal must never be readable as a run that happened. A no-go spawned
+  -- nothing, so it is terminal-skipped and carries no output — the mirror of
+  -- security_tool_scans' verdict/completion invariant.
+  CONSTRAINT agents_runs_nogo_is_skipped_chk
+    CHECK (gate_decision = 'go' OR (status = 'skipped' AND output_ref IS NULL)),
+  -- ...and it cannot have cost anything, because nothing ran.
+  CONSTRAINT agents_runs_nogo_free_chk
+    CHECK (gate_decision = 'go' OR cost_usd IS NULL OR cost_usd = 0),
+  -- A failed run must say why. Silent failure is the state this ledger exists to
+  -- make impossible.
+  CONSTRAINT agents_runs_error_needs_code_chk
+    CHECK (status <> 'error' OR error_code IS NOT NULL),
+  CONSTRAINT agents_runs_cost_nonneg_chk
+    CHECK (cost_usd IS NULL OR cost_usd >= 0),
+  CONSTRAINT agents_runs_duration_nonneg_chk
+    CHECK (duration_ms IS NULL OR duration_ms >= 0),
+  CONSTRAINT agents_runs_output_ref_len_chk
+    CHECK (output_ref IS NULL OR length(output_ref) <= 2048)
+);
+
+-- "What has this agent done lately?" — the per-agent history, and the read behind
+-- a per-agent spend rollup.
+CREATE INDEX IF NOT EXISTS agents_runs_agent_idx
+  ON agents_runs (agent_name, created_at DESC);
+
+-- "What did this trigger set off?" — walks back from a shipped task (or any other
+-- subject) to the agents that fired on it.
+CREATE INDEX IF NOT EXISTS agents_runs_trigger_ref_idx
+  ON agents_runs (trigger_ref, created_at DESC)
+  WHERE trigger_ref IS NOT NULL;
+
+-- "What did agents cost this month?" — the spend-cap read. Partial: a no-go row
+-- contributes nothing to spend and would only dilute the scan.
+CREATE INDEX IF NOT EXISTS agents_runs_spend_idx
+  ON agents_runs (created_at DESC)
+  WHERE cost_usd IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- updated_at triggers
+-- ---------------------------------------------------------------------------
+-- Both tables ARE mutated after insert (the sync rewrites definitions; a run goes
+-- pending → ok/error and gains its cost + output_ref), so updated_at needs a real
+-- trigger — without one it silently equals created_at forever, and "when did this
+-- definition last change" becomes unanswerable. Idempotent: OR REPLACE + DROP IF
+-- EXISTS on the trigger.
+CREATE OR REPLACE FUNCTION agents_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS agents_definitions_updated_at ON agents_definitions;
+CREATE TRIGGER agents_definitions_updated_at
+  BEFORE UPDATE ON agents_definitions
+  FOR EACH ROW EXECUTE FUNCTION agents_touch_updated_at();
+
+DROP TRIGGER IF EXISTS agents_runs_updated_at ON agents_runs;
+CREATE TRIGGER agents_runs_updated_at
+  BEFORE UPDATE ON agents_runs
+  FOR EACH ROW EXECUTE FUNCTION agents_touch_updated_at();
+
+COMMIT;

package/modules/agents/module.json

@@ -0,0 +1,11 @@
+{
+  "key": "agents",
+  "title": "Agents (declarative agent registry)",
+  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083.",
+  "coreVersion": "^1.19.0",
+  "default": false,
+  "maintenance": { "status": "core-maintained" },
+  "contributes": { "migrations": true },
+  "provides": [],
+  "consumes": ["grade"]
+}

package/modules/agents/spawn.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// modules/agents/spawn.js — the spawn seam (task 1002489, goal 1000038 Phase 1).
+//
+// One fire = resolve the tier to a concrete model, ask the `grade` port to run the
+// subagent, and write exactly one agents_runs row saying what happened. Nothing
+// else. The gate decides WHETHER to fire; this decides HOW and records THAT.
+//
+// THREE CONSTRAINTS THAT ARE NOT NEGOTIABLE HERE, each from the goal's own
+// adversarial critique — a future reader will be tempted by all three:
+//
+//   1. CONSUME grade.runSubagentCached. Not a new `grade.runSubagent` port (the
+//      critique explicitly dropped it), and not a bespoke child_process.spawn. The
+//      port is also what bills every fire into the shared LLM cost cache, so an
+//      agent's spend lands in the same ledger as everything else instead of being
+//      invisible. A bespoke spawn would be free-looking and wrong.
+//
+//   2. REACH IT THROUGH THE DOORWAY, never `require('../grading/…')`. A
+//      module→module require is a hard fitness failure (ADR 0083), and the
+//      resolve-by-name seam is what lets an instance run `agents` with `grading`
+//      disabled — it degrades to a named refusal instead of a boot crash.
+//
+//   3. V1 AGENTS ARE READ-ONLY, and not by policy — by plumbing. grader.js's
+//      runSubagent hardcodes `--tools Read` + bypassPermissions and parametrizes
+//      only model/cwd/timeout. There is no allowlist to widen from here. A
+//      write-capable agent needs a parametrized-capability spawn path in `grading`
+//      first (a PROTECTED_GLOBS edit, Archon-gated), which is deferred to a later
+//      goal. Anything in this file that appears to grant a capability is a bug.
+//
+// THE LEDGER IS WRITTEN EVEN WHEN NOTHING RUNS. A no-go is a row: gate_decision
+// 'no-go', status 'skipped', no output, no cost — the schema enforces all three.
+// The reason is the same one behind every other loud-failure surface in this repo:
+// a refusal that leaves no trace is indistinguishable from a fire that never
+// happened, and "the agent didn't run" then has two causes nobody can tell apart.
+
+const api = require('../../src/module-api');
+
+// 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.
+//
+// An unknown tier resolves to the DEFAULT tier, never to nothing and never to the
+// cheap one. A definition whose tier is somehow outside the vocabulary is a bug in
+// whatever wrote it; silently downgrading its model would make that bug present as
+// mysteriously poor agent output much later, which is far harder to trace than an
+// unexpected line in the cost ledger.
+function resolveModel(tier, brandingModels) {
+  const m = brandingModels || {};
+  const fallback = m.subagentDefault || m.main || null;
+  if (tier === 'routine') return m.subagentRoutine || fallback;
+  return fallback;
+}
+
+// The insert shape for one fire, decided BEFORE anything spawns. Pure, so the
+// schema's invariants can be tested without a database.
+function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null } = {}) {
+  const go = gate.decision === 'go';
+  return {
+    definition_id: definition.id ?? null,
+    agent_name: definition.name || null,
+    trigger_ref: trigger.ref ?? null,
+    trigger_type: trigger.type === 'on-demand' ? 'on-demand' : 'event',
+    gate_decision: go ? 'go' : 'no-go',
+    gate_reason: gate.reason ?? null,
+    // A no-go is TERMINAL. 'pending' would leave a refusal looking like a run
+    // still in flight, and the crash-visibility argument for 'pending' only
+    // applies to something that actually started.
+    status: go ? 'pending' : 'skipped',
+    // Recorded even on a no-go: it is what the fire WOULD have cost, and the
+    // schema permits it. It is the concrete id, never the tier — an old row must
+    // never be re-read through today's tier mapping.
+    model: go ? model : null,
+    requested_by_builder_id: requestedByBuilderId ?? null,
+  };
+}
+
+// How a finished run is recorded. Pure for the same reason.
+function completedRow({ ok, errorCode = null, costUsd = null, durationMs = null, outputRef = null } = {}) {
+  if (ok) {
+    return { status: 'ok', error_code: null, cost_usd: costUsd, duration_ms: durationMs, output_ref: outputRef };
+  }
+  return {
+    status: 'error',
+    // The schema REFUSES an error row with no code, so this can never be null —
+    // 'agent_run_failed' is the honest fallback when the thrower named nothing.
+    error_code: errorCode || 'agent_run_failed',
+    cost_usd: costUsd,
+    duration_ms: durationMs,
+    // A failed run's partial output is not a result. The pointer stays null.
+    output_ref: null,
+  };
+}
+
+async function insertRun(pool, row) {
+  const cols = Object.keys(row);
+  const vals = cols.map((_, i) => `$${i + 1}`);
+  const r = await pool.query(
+    `INSERT INTO agents_runs (${cols.join(', ')}) VALUES (${vals.join(', ')}) RETURNING id`,
+    cols.map((c) => row[c]),
+  );
+  return r.rows[0].id;
+}
+
+async function finishRun(pool, id, patch) {
+  const cols = Object.keys(patch);
+  const set = cols.map((c, i) => `${c} = $${i + 2}`).join(', ');
+  await pool.query(
+    `UPDATE agents_runs SET ${set}, updated_at = now() WHERE id = $1`,
+    [id, ...cols.map((c) => patch[c])],
+  );
+}
+
+// Fire one agent. Never throws: a spawn failure is a ledger row, not an exception
+// into whatever triggered it — an event fabric must not be taken down by one
+// agent's bad day.
+async function spawnAgent({
+  definition, trigger = {}, gate = { decision: 'go' }, requestedByBuilderId = null, cache = null,
+} = {}, deps = {}) {
+  const pool = deps.pool || api.pool;
+  const now = deps.now || (() => Date.now());
+  const brandingModels = deps.brandingModels || (api.branding && api.branding().models) || {};
+  const model = resolveModel(definition && definition.model_tier, brandingModels);
+
+  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId });
+  let runId = null;
+  try {
+    runId = await insertRun(pool, row);
+  } catch (e) {
+    // The ledger write itself failing is the one case with nowhere to record it.
+    // Say so and refuse to spawn: an unledgered fire is exactly what this table
+    // exists to prevent, and spending money we cannot account for is worse than
+    // not firing.
+    return { ok: false, ran: false, runId: null, error_code: 'ledger_write_failed', error: (e && e.message) || String(e) };
+  }
+  if (row.gate_decision !== 'go') {
+    return { ok: true, ran: false, runId, skipped: true, gate_reason: row.gate_reason || null };
+  }
+
+  // Resolved by NAME through the doorway — see constraint 2. resolveOptional so an
+  // instance running `agents` without `grading` gets a named ledger row rather than
+  // a crash at require time.
+  const grade = typeof api.resolveOptional === 'function' ? api.resolveOptional('grade', null) : null;
+  const runner = deps.runSubagentCached
+    || (grade && typeof grade.runSubagentCached === 'function' ? grade.runSubagentCached : null);
+  if (!runner) {
+    await finishRun(pool, runId, completedRow({ ok: false, errorCode: 'grade_port_unavailable' }));
+    return { ok: false, ran: false, runId, error_code: 'grade_port_unavailable' };
+  }
+
+  const started = now();
+  try {
+    const res = await runner({
+      prompt: (definition && definition.persona) || '',
+      // model/cwd/timeout are the ONLY knobs the port takes. No tools, no
+      // permissions — see constraint 3.
+      opts: { model, ...(deps.opts || {}) },
+      cache,
+    });
+    const durationMs = Math.max(0, now() - started);
+    const costUsd = (res && typeof res.cost_usd === 'number' && res.cost_usd >= 0) ? res.cost_usd : null;
+    const ok = !res || res.ok !== false;
+    const patch = completedRow({
+      ok,
+      errorCode: ok ? null : (res && res.error_code) || 'agent_run_failed',
+      costUsd,
+      durationMs,
+      outputRef: ok ? (deps.outputRef || (res && res.output_ref) || null) : null,
+    });
+    await finishRun(pool, runId, patch);
+    return { ok, ran: true, runId, model, cost_usd: costUsd, duration_ms: durationMs };
+  } catch (e) {
+    const durationMs = Math.max(0, now() - started);
+    await finishRun(pool, runId, completedRow({
+      ok: false, errorCode: (e && e.code) || 'agent_spawn_threw', durationMs,
+    })).catch(() => { /* the throw below is the report of last resort */ });
+    return { ok: false, ran: true, runId, error_code: (e && e.code) || 'agent_spawn_threw', error: (e && e.message) || String(e) };
+  }
+}
+
+module.exports = { spawnAgent, resolveModel, plannedRow, completedRow };

package/package-lock.json

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

package/package.json

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

package/scripts/gds/publish-manifest.js

@@ -68,6 +68,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/dev-box/',
   'modules/discord/',
   'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
+  'modules/agents/',         // the declarative agent registry + spawn seam (goal 1000038) — CORE: its own manifest declares maintenance.status 'core-maintained', and it consumes the core `grade` port, so a released core without it cannot run the MAS machinery the methodology describes. default:false — shipped is not enabled (ADR 0083), exactly like provisioning + platform-identity below. Omitted at module-creation time (tasks 1002485/1002486): the omission was invisible until tests/agents_spawn.mjs became the first PUBLISHABLE file to import it and the R89 boundary guard caught it (task 1002489).
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
   'config/branding.neutral.json',

package/src/module-api.js

@@ -1144,8 +1144,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.355 with no explicit bump. run 32861072779. (task 1002620)
 //   1.19.357 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.356 with no explicit bump. run 32871335939. (task 1002620)
+//   1.19.358 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.357 with no explicit bump. run 32872551850. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.357'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.358'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // 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_spawn.mjs

@@ -0,0 +1,190 @@
+// tests/agents_spawn.mjs — the spawn seam (task 1002489, goal 1000038).
+//
+// Gates two criteria: agents-spawn-via-grade-port and agents-model-tier-default.
+//
+// Everything is dependency-injected — a fake pool, a fake runner, a fake clock. No
+// database, no subprocess, no model call. What is proven here is the DECISIONS: the
+// tier mapping, the ledger's shape, and the refusals.
+//
+// Run:  node tests/agents_spawn.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { spawnAgent, resolveModel, plannedRow, completedRow } = require('../modules/agents/spawn.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const MODELS = { main: 'opus', subagentDefault: 'opus', subagentRoutine: 'haiku' };
+const DEF = { id: 7, name: 'historian', model_tier: 'default', persona: 'observe and report' };
+
+// A pool that records every statement, so the LEDGER can be asserted on directly.
+function fakePool() {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/^INSERT INTO agents_runs/.test(sql)) return { rows: [{ id: 42 }] };
+      return { rows: [] };
+    },
+    inserted() {
+      const c = calls.find((x) => /^INSERT INTO agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = c.sql.match(/\(([^)]+)\) VALUES/)[1].split(',').map((s) => s.trim());
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i]]));
+    },
+    updated() {
+      const c = calls.find((x) => /^UPDATE agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = [...c.sql.matchAll(/(\w+) = \$\d+/g)].map((m) => m[1]).filter((k) => k !== 'updated_at');
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i + 1]]));
+    },
+  };
+}
+
+// --- THE TIER MAPPING (criterion agents-model-tier-default) -----------------
+
+await test('tier resolves through BRANDING, not a constant in the module', () => {
+  assert.equal(resolveModel('default', MODELS), 'opus');
+  assert.equal(resolveModel('routine', MODELS), 'haiku');
+  // An instance that retunes its tiers must move the agents with it.
+  assert.equal(resolveModel('routine', { subagentDefault: 'sonnet', subagentRoutine: 'sonnet' }), 'sonnet');
+});
+
+await test('an UNKNOWN tier falls back to DEFAULT, never to the cheap tier', () => {
+  // Silently downgrading a malformed definition presents much later as
+  // mysteriously poor agent output — far harder to trace than an unexpected
+  // cost line. Fail toward capability.
+  for (const bad of ['cheap', '', null, undefined, 'ROUTINE']) {
+    assert.equal(resolveModel(bad, MODELS), 'opus', `${bad} must not resolve to the routine tier`);
+  }
+});
+
+await test('a missing branding map yields null rather than inventing a model id', () => {
+  assert.equal(resolveModel('default', {}), null);
+});
+
+// --- THE LEDGER SHAPE -------------------------------------------------------
+
+await test('a no-go is TERMINAL: skipped, no model, no output, no cost', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'no-go', reason: 'autonomy off' }, model: 'opus' });
+  assert.equal(row.gate_decision, 'no-go');
+  assert.equal(row.status, 'skipped', "'pending' would read as a run still in flight");
+  assert.equal(row.model, null, 'nothing ran, so no model was used');
+  assert.equal(row.gate_reason, 'autonomy off');
+});
+
+await test('a go starts PENDING so a crashed spawn is visible as unfinished', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'go' }, model: 'opus' });
+  assert.equal(row.status, 'pending');
+  assert.equal(row.model, 'opus', 'the CONCRETE model, so an old row is never re-read through a new tier map');
+});
+
+await test('the run stays attributable when the definition is gone', () => {
+  const row = plannedRow({ definition: DEF, gate: { decision: 'go' } });
+  assert.equal(row.agent_name, 'historian', 'denormalized name survives ON DELETE SET NULL');
+});
+
+await test('an errored run ALWAYS carries a code — the schema refuses otherwise', () => {
+  const c = completedRow({ ok: false });
+  assert.equal(c.status, 'error');
+  assert.ok(c.error_code, 'never null, even when the thrower named nothing');
+  assert.equal(c.output_ref, null, "a failed run's partial output is not a result");
+});
+
+// --- SPAWNING (criterion agents-spawn-via-grade-port) -----------------------
+
+await test('a go spawns through the injected grade port and completes the row', async () => {
+  const pool = fakePool();
+  let seen = null;
+  const r = await spawnAgent(
+    { definition: DEF, trigger: { type: 'event', ref: 'task.shipped:1' }, gate: { decision: 'go' } },
+    { pool, brandingModels: MODELS, now: (() => { let t = 1000; return () => (t += 250); })(),
+      runSubagentCached: async (a) => { seen = a; return { ok: true, cost_usd: 0.42, output_ref: 'grade:9' }; } },
+  );
+  assert.equal(r.ok, true);
+  assert.equal(r.ran, true);
+  assert.equal(seen.opts.model, 'opus', 'the resolved model reaches the port');
+  assert.equal(pool.updated().status, 'ok');
+  assert.equal(Number(pool.updated().cost_usd), 0.42, 'spend lands in the ledger');
+});
+
+await test('the port receives NO tool or permission knobs — v1 agents are read-only', async () => {
+  // Not policy: grader.js hardcodes `--tools Read`. Anything here that looked
+  // like granting a capability would be a bug, so assert the absence.
+  let seen = null;
+  await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool: fakePool(), brandingModels: MODELS,
+    runSubagentCached: async (a) => { seen = a; return { ok: true }; },
+  });
+  for (const forbidden of ['tools', 'allowedTools', 'permissions', 'permissionMode', 'bypassPermissions']) {
+    assert.ok(!(forbidden in seen.opts), `opts must not carry ${forbidden}`);
+  }
+});
+
+await test('a NO-GO spawns nothing at all', async () => {
+  const pool = fakePool();
+  let ran = false;
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'no-go', reason: 'capped' } }, {
+    pool, brandingModels: MODELS, runSubagentCached: async () => { ran = true; return { ok: true }; },
+  });
+  assert.equal(ran, false, 'a refusal must not reach the model');
+  assert.equal(r.ran, false);
+  assert.equal(r.skipped, true);
+  assert.equal(pool.updated(), null, 'terminal at insert — nothing to complete');
+  assert.equal(pool.inserted().status, 'skipped');
+});
+
+await test('a refusal is still LEDGERED — an untraced no-go is unexplainable later', async () => {
+  const pool = fakePool();
+  await spawnAgent({ definition: DEF, gate: { decision: 'no-go', reason: 'autonomy gate closed' } },
+    { pool, brandingModels: MODELS });
+  const row = pool.inserted();
+  assert.ok(row, 'the row exists even though nothing ran');
+  assert.equal(row.gate_reason, 'autonomy gate closed', 'and says why');
+});
+
+await test('a missing grade port is a named ledger row, not a crash', async () => {
+  // An instance may run `agents` with `grading` disabled. resolveOptional is what
+  // makes that a refusal instead of a boot-time require failure.
+  const pool = fakePool();
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } },
+    { pool, brandingModels: MODELS, runSubagentCached: null });
+  assert.equal(r.ok, false);
+  assert.equal(r.error_code, 'grade_port_unavailable');
+  assert.equal(pool.updated().status, 'error');
+  assert.equal(pool.updated().error_code, 'grade_port_unavailable');
+});
+
+await test('a throwing subagent is recorded, and never propagates', async () => {
+  // An event fabric must not be taken down by one agent's bad day.
+  const pool = fakePool();
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool, brandingModels: MODELS,
+    runSubagentCached: async () => { throw Object.assign(new Error('boom'), { code: 'timeout' }); },
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.error_code, 'timeout');
+  assert.equal(pool.updated().status, 'error');
+});
+
+await test('an unledgerable fire does NOT spawn — unaccounted spend is worse', async () => {
+  let ran = false;
+  const r = await spawnAgent({ definition: DEF, gate: { decision: 'go' } }, {
+    pool: { query: async () => { throw new Error('db down'); } },
+    brandingModels: MODELS,
+    runSubagentCached: async () => { ran = true; return { ok: true }; },
+  });
+  assert.equal(ran, false, 'money must never be spent with nowhere to record it');
+  assert.equal(r.error_code, 'ledger_write_failed');
+});
+
+console.log(`\nagents_spawn: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/publish_manifest.mjs

@@ -204,16 +204,14 @@ t('every PROTECTED_GLOB is either topology-excluded or publishable (the methodol
 // Modules deliberately not published, on the record. An entry here is a decision
 // someone made, not a gap someone forgot — and every entry needs the task or idea that
 // records the decision, so this can never become a quiet parking lot.
-const KNOWN_UNPUBLISHED_MODULES = new Map([
-  // Same gap as copy-desk, found by the guard below the moment it was written. LATENT
-  // rather than live only because agents is default:false — the day a released instance
-  // enables it, the loader MODULE_NOT_FOUNDs, which is exactly what the provisioning
-  // (task 2135) and platform-identity (task 1002235) allowlist entries exist to prevent.
-  // Left for goal 1000038 rather than fixed here: deciding what the published core
-  // contains for the agents module is that goal's call, not a drive-by from a copy-desk
-  // task. Filed as idea 1000797 with the one-line fix.
-  ['agents', 'idea 1000797'],
-]);
+// Currently EMPTY, and that is the healthy state — every module on disk is either
+// allowlisted or denied on the record. The one entry it ever held ('agents', idea
+// 1000797) was retired by task 1002489: the copy-desk task that found the gap
+// deliberately left the call to goal 1000038, and task 1002489 IS that goal, so it
+// made it — agents is core-maintained, so it joined PUBLISH_ALLOWLIST rather than a
+// deny list. Keep the map (and the two guards below): the next module added without
+// a publish decision is caught the same way this one was.
+const KNOWN_UNPUBLISHED_MODULES = new Map([]);
 
 t('every module on disk is either publishable or deliberately unpublished (a new module cannot be silently invisible)', () => {
   const modulesDir = path.join(ROOT, 'modules');