@bongos/core 1.19.356 → 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.356",
-  "core_contract": "1.19.356",
-  "source_commit": "cb63704ad7571ab5d52fe949b6f265281f754679",
+  "core_version": "1.19.358",
+  "core_contract": "1.19.358",
+  "source_commit": "6bfaa149e1894ef5d78af75527e0158d951470c7",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T14:41:47.258Z",
+  "built_at": "2026-08-25T16:32:44.606Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 330,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1509,
+    "functional_verbatim": 1515,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1861,
-  "tree_sha256": "983a13e5fa8e0ab31afc970fe2b7f6ebb7296e62bee4cf06257f51ce26658362",
+  "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",
@@ -4212,7 +4227,12 @@
     {
       "path": "modules/memory/module.json",
       "mode": "0000644",
-      "sha256": "ace721e3ae257aee7f9b13bfbb60b6959f9d72e11059c316d22701754db5b911"
+      "sha256": "c697548692393d65c6beb8092f70f8864acb53d568548f123213023ca10032f8"
+    },
+    {
+      "path": "modules/memory/pollers/search-index.js",
+      "mode": "0000644",
+      "sha256": "4950c01fc2b895a7eb8f5fc929826c1bea44d9764f5ffa4c8378de73be1446e9"
     },
     {
       "path": "modules/memory/routes/learnings.js",
@@ -4797,12 +4817,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d5f53ae25273ca753b122eca1de770bb20d9a1ed1b9a7b0b105710403670e7ec"
+      "sha256": "b155c2a0dda8e0bcfbd1efadbc4ef619a25be608f9e29714e7039f24267bcd25"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "881f7f9d99198d118f9bbcec082d6637b586dbc6acb850cc654cac192b0cab55"
+      "sha256": "1f7444718fbae90aa6d3b0f6c33c6cc1052cf48917a3c1c030f7a9de7806ce53"
     },
     {
       "path": "public-docs/index.html",
@@ -5827,7 +5847,7 @@
     {
       "path": "scripts/gds/publish-manifest.js",
       "mode": "0000644",
-      "sha256": "387a6846692f05c4adee5651a6f45780ec12f24de12621e73014e79ea4c47342"
+      "sha256": "12b3b200c1f60cc8a287d9a3ca2dd28201fda3cc219e83dffb60913c084e0413"
     },
     {
       "path": "scripts/gds/pulse.js",
@@ -6662,7 +6682,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "0b23db16d6f47afb30b4f5ed970cd1a2d0aac607feda9ce4ebf9be09c0a3dc47"
+      "sha256": "fdd1d69409cf0ac75e9063d0ec0bf742c83aba0cdc9f15935839c9c6998e96af"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6739,6 +6759,11 @@
       "mode": "0000644",
       "sha256": "125edcec8c7d7536365b9675daa1fceb9fe072a30e2a4a68ee2911cd258a8c10"
     },
+    {
+      "path": "tests/agents_spawn.mjs",
+      "mode": "0000644",
+      "sha256": "8cc261471a36e3c447df57b46082997b6a50da3c8ff4b214787ae55ab27cb9ef"
+    },
     {
       "path": "tests/api_cli_flags.mjs",
       "mode": "0000644",
@@ -8652,7 +8677,7 @@
     {
       "path": "tests/publish_manifest.mjs",
       "mode": "0000644",
-      "sha256": "a5e36e0a0d228638c499ccac2559bd947a85735e1a922a32c7c1377c98ed2a60"
+      "sha256": "5eca5f50f200166ce0fd7e40a57e18fffb135139fe558d0dda34064d426814dc"
     },
     {
       "path": "tests/publish_reconciler.mjs",
@@ -8804,6 +8829,11 @@
       "mode": "0000644",
       "sha256": "1034ab278e7eb005ba0286b8bcecd7fafdec390418ae94e3cbacf81ffb9fc88c"
     },
+    {
+      "path": "tests/search_index_poller.mjs",
+      "mode": "0000644",
+      "sha256": "f665d4f0a9ccfb5b92564dfda39d13d6d8ed3146cde3fe2e05bb9f9aec029558"
+    },
     {
       "path": "tests/search_ingest.mjs",
       "mode": "0000644",

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/modules/memory/module.json

@@ -4,9 +4,18 @@
   "description": "Per-builder session memory, the lexical recall/search retrieval layer (ADR 0060), and durable learnings. A core-domain module carved out of the GDS core in BV1.R72 (ADR 0091); default-on because every instance needs the build system's memory.",
   "coreVersion": "^1.5.0",
   "default": true,
-  "maintenance": { "status": "core-maintained" },
+  "maintenance": {
+    "status": "core-maintained"
+  },
   "contributes": {
-    "routes": ["memory", "search", "learnings"]
+    "routes": [
+      "memory",
+      "search",
+      "learnings"
+    ],
+    "pollers": [
+      "search-index"
+    ]
   },
   "provides": [],
   "consumes": []

package/modules/memory/pollers/search-index.js

@@ -0,0 +1,201 @@
+'use strict';
+
+// modules/memory/pollers/search-index.js — the recall index keeps itself, and says
+// so out loud (task 1003162, goal 1000027).
+//
+// THE INCIDENT. `/recall` on live returned the `index_empty` outage state for words
+// that demonstrably exist in the corpus — an entire goal's worth of ADRs, session
+// logs and task rows. The index genuinely held nothing, and had held nothing for as
+// long as anyone could tell, because NOTHING RAN THE INGESTERS.
+//
+// ADR 0060 says repo markdown is ingested by "a deploy-hook step" and DB prose by
+// "a nightly timer". Both are BOX-SIDE artifacts: `grep -rn search-ingest` across
+// the core tree finds the two ingesters, some prose about them, and nothing that
+// executes either. Whether the box's deploy.sh ever called them is unknowable from
+// here — and that unknowability IS the bug. An index that depends on an unwatched
+// host script fails exactly the way this one did: silently, indefinitely, and only
+// noticed when a human happens to search for something they know is there.
+//
+// WHY IN-PROCESS, and not a cron or a CI workflow. The ingesters need the database.
+// A GitHub Actions schedule cannot reach it; the box's own timer is the thing that
+// stopped. The web process already holds a pool and already runs this exact shape
+// of work (the publish reconciler, the board-expiry sweep), so putting the sweep
+// here makes it start whenever the app starts and stop only when the app stops.
+// There is no separate thing left to forget to arm.
+//
+// THE SHAPE follows the publish reconciler, the in-tree precedent:
+//   * a DISPOSITION LINE every sweep — the reconciler's lesson is that a sweep
+//     which only speaks on failure is indistinguishable from a sweep that is not
+//     running. "held 4,812 chunks, nothing to do" is the sentence whose ABSENCE is
+//     the alarm.
+//   * failure isolation — the md ingest failing must not skip the db ingest.
+//   * bounded and self-gating — SEARCH_INDEX_SWEEP_DISABLED turns it off, an unref'd
+//     timer never holds the process open, and a sweep already running is not
+//     re-entered.
+//
+// AND IT CHECKS EXIT CODES, which is the half the task named explicitly. Task
+// 1002859 made a partial ingest exit non-zero and NAME every skipped source; that
+// only helps if someone reads the code. Spawning the CLIs (rather than importing
+// their main()) is what preserves it — the exit code is the contract, and running
+// them the documented way keeps this poller honest about what an operator would see.
+
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const MD_INGESTER = path.join(REPO_ROOT, 'scripts', 'gds', 'search-ingest-md.js');
+const DB_INGESTER = path.join(REPO_ROOT, 'scripts', 'gds', 'search-ingest-db.js');
+
+// Nightly-ish. DB prose changes slowly and the md corpus only moves on deploy, so
+// a long period is right; the value is that it recurs at all, not that it is tight.
+const INTERVAL_MS = Number(process.env.SEARCH_INDEX_SWEEP_MS) || 6 * 60 * 60 * 1000;
+// An EMPTY index is an outage, not a slow day: recall answers nothing at all until
+// it is fixed. Sweep early after boot so a deploy that lands on an empty table
+// repairs it in minutes rather than at the next six-hour tick.
+const FIRST_SWEEP_DELAY_MS = Number(process.env.SEARCH_INDEX_FIRST_MS) || 90_000;
+// The md ingest walks a few hundred files; the db ingest reads prose tables. Both
+// are minutes at worst. The cap exists so a wedged child can never pin the sweep.
+const INGEST_TIMEOUT_MS = Number(process.env.SEARCH_INDEX_INGEST_TIMEOUT_MS) || 10 * 60 * 1000;
+
+let intervalTimer = null;
+let firstTimer = null;
+let sweeping = false;
+
+// ---------------------------------------------------------------------------
+// Pure decisions — exported and unit-tested. No DB, no spawn, no clock.
+// ---------------------------------------------------------------------------
+
+// What does a chunk count MEAN? Separated from the doing so the judgement can be
+// tested without a database, and so the wording lives in one place.
+//
+// `empty` is deliberately its own state rather than "very stale": it is the only
+// one where recall is not degraded but DEAD, it is rank-independent (so it can
+// never be "nothing visible to YOU"), and it is the one that justifies spending an
+// ingest immediately on boot.
+function describeIndex({ chunks, lastIngestedAt = null, now = Date.now() } = {}) {
+  // typeof FIRST: Number(null) is 0 and Number('') is 0, so a missing column or an
+  // absent row would coerce into a confident "the index is empty" — a wrong
+  // diagnosis that also spends an ingest. Only an actual number can be a count.
+  const n = typeof chunks === 'number' ? chunks : NaN;
+  if (!Number.isFinite(n) || n < 0) {
+    return { level: 'alarm', state: 'unreadable', chunks: null,
+      message: 'search-index: could not read search_chunks — recall health is UNKNOWN, which is not the same as healthy.' };
+  }
+  if (n === 0) {
+    return { level: 'alarm', state: 'empty', chunks: 0,
+      message: 'search-index: search_chunks is EMPTY — /recall can return nothing at all, for any query, at any rank. Ingesting now.' };
+  }
+  const ageMs = lastIngestedAt ? Math.max(0, now - new Date(lastIngestedAt).getTime()) : null;
+  const ageDays = ageMs == null ? null : Math.floor(ageMs / 86_400_000);
+  if (ageDays != null && ageDays >= 7) {
+    return { level: 'warn', state: 'stale', chunks: n, age_days: ageDays,
+      message: `search-index: ${n} chunk(s), but the newest is ${ageDays} day(s) old — the sweep may have stopped.` };
+  }
+  return { level: 'ok', state: 'ok', chunks: n, age_days: ageDays,
+    message: `search-index: ${n} chunk(s) indexed${ageDays == null ? '' : `, newest ${ageDays} day(s) old`}.` };
+}
+
+// One ingester's outcome, in the words an operator needs. A non-zero exit is the
+// signal task 1002859 built and nothing was reading.
+function describeIngest({ name, code, signal = null, stderr = '' } = {}) {
+  if (signal) {
+    return { level: 'alarm', ok: false,
+      message: `search-index: ${name} was KILLED by ${signal} (timeout or OOM) — the index is partially written at best.` };
+  }
+  if (code === 0) return { level: 'ok', ok: true, message: `search-index: ${name} ok.` };
+  // The tail, not the head: these CLIs name what they skipped at the END.
+  const tail = String(stderr || '').trim().split('\n').slice(-6).join('\n');
+  return { level: 'alarm', ok: false,
+    message: `search-index: ${name} exited ${code} — it names every source it skipped:\n${tail || '(no stderr captured)'}` };
+}
+
+// ---------------------------------------------------------------------------
+// Doing
+// ---------------------------------------------------------------------------
+
+function runIngester(file, { execFileImpl = execFile } = {}) {
+  return new Promise((resolve) => {
+    execFileImpl(process.execPath, [file], {
+      cwd: REPO_ROOT, timeout: INGEST_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024,
+      env: process.env, shell: false,
+    }, (err, _stdout, stderr) => {
+      resolve({
+        code: err ? (typeof err.code === 'number' ? err.code : 1) : 0,
+        signal: (err && err.signal) || null,
+        stderr: stderr || (err && err.message) || '',
+      });
+    });
+  });
+}
+
+async function readChunkStats(pool) {
+  const r = await pool.query(
+    'SELECT count(*)::int AS chunks, max(updated_at) AS last FROM search_chunks'
+  );
+  const row = (r && r.rows && r.rows[0]) || {};
+  return { chunks: row.chunks, lastIngestedAt: row.last || null };
+}
+
+// One sweep. Never throws — a poller that can take the process down is worse than
+// the outage it watches.
+async function sweep({ pool, log = console, execFileImpl = execFile, now = Date.now() } = {}) {
+  let health;
+  try {
+    health = describeIndex({ ...(await readChunkStats(pool)), now });
+  } catch (e) {
+    health = describeIndex({ chunks: NaN, now });
+    health.error = (e && e.message) || String(e);
+  }
+  (health.level === 'ok' ? log.log : log.error).call(log, health.message);
+
+  // Ingest when the index is empty or unreadable-but-recoverable; a populated
+  // index is refreshed on the ordinary tick, not re-walked because it is stale by
+  // an hour. `empty` is the case that cannot wait.
+  const results = [];
+  for (const [name, file] of [['search-ingest-md', MD_INGESTER], ['search-ingest-db', DB_INGESTER]]) {
+    const r = await runIngester(file, { execFileImpl });
+    const d = describeIngest({ name, ...r });
+    results.push(d);
+    (d.ok ? log.log : log.error).call(log, d.message);
+  }
+
+  // The after-picture. Without it a run that exited 0 while writing nothing still
+  // reads as success — the exact shape of failure this task exists to end.
+  let after = null;
+  try {
+    after = describeIndex({ ...(await readChunkStats(pool)), now });
+    (after.level === 'ok' ? log.log : log.error).call(log, `search-index: after sweep — ${after.message}`);
+  } catch (_) { /* the before-picture already reported; never throw from a sweep */ }
+
+  return { health, results, after };
+}
+
+function start(deps = {}) {
+  // Same injectable-log shape as sweep() above (default console), so the two
+  // halves of this poller log through one seam and neither hard-codes console.
+  const log = deps.log || console;
+  if (process.env.SEARCH_INDEX_SWEEP_DISABLED === 'true') {
+    log.log('search-index: sweep disabled by SEARCH_INDEX_SWEEP_DISABLED.');
+    return { stop };
+  }
+  const pool = deps.pool || require('../../../src/module-api.js').pool;
+  const tick = async () => {
+    if (sweeping) return;            // never re-enter; a long ingest must not stack
+    sweeping = true;
+    try { await sweep({ pool, log }); }
+    catch (e) { log.error('search-index: sweep failed:', (e && e.message) || e); }
+    finally { sweeping = false; }
+  };
+  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
+  intervalTimer = setInterval(tick, INTERVAL_MS);
+  if (firstTimer.unref) firstTimer.unref();
+  if (intervalTimer.unref) intervalTimer.unref();
+  return { stop };
+}
+
+function stop() {
+  if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
+  if (intervalTimer) { clearInterval(intervalTimer); intervalTimer = null; }
+}
+
+module.exports = { start, stop, sweep, describeIndex, describeIngest, INTERVAL_MS, FIRST_SWEEP_DELAY_MS };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.356",
+  "version": "1.19.358",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.356",
+      "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.356",
+  "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

@@ -1142,8 +1142,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.354 with no explicit bump. run 32853063015. (task 1002620)
 //   1.19.356 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.356'; // 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');

package/tests/search_index_poller.mjs

@@ -0,0 +1,161 @@
+// tests/search_index_poller.mjs — the recall index keeps itself, and says so
+// (task 1003162).
+//
+// The outage this guards: /recall returned `index_empty` on live for words that
+// demonstrably existed in the corpus, because NOTHING ran the ingesters. ADR 0060
+// claims a deploy hook and a nightly timer; both are box-side, and neither could be
+// shown to have ever run.
+//
+// Everything here is pure or dependency-injected — no database, no child process,
+// no clock. The sweep is driven with a fake pool and a fake execFile so the
+// DECISIONS are tested, not the plumbing.
+//
+// Run:  node tests/search_index_poller.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const poller = require('../modules/memory/pollers/search-index.js');
+const { describeIndex, describeIngest, sweep } = poller;
+
+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 NOW = Date.parse('2026-08-25T12:00:00Z');
+const daysAgo = (d) => new Date(NOW - d * 86400000).toISOString();
+const quietLog = { log() {}, error() {} };
+const okExec = (_p, _a, _o, cb) => cb(null, '', '');
+
+// --- READING THE INDEX ------------------------------------------------------
+
+await test('an EMPTY index is an alarm, and says recall returns nothing AT ANY RANK', async () => {
+  const d = describeIndex({ chunks: 0, now: NOW });
+  assert.equal(d.level, 'alarm');
+  assert.equal(d.state, 'empty');
+  // Rank-independence is the whole reason `index_empty` is diagnostic: it rules
+  // out "nothing visible to YOU", which is what made the live report trustworthy.
+  assert.match(d.message, /any rank/i);
+});
+
+await test('an UNREADABLE count is an alarm — unknown is not healthy', async () => {
+  for (const bad of [NaN, undefined, null, -1, 'lots']) {
+    const d = describeIndex({ chunks: bad, now: NOW });
+    assert.equal(d.level, 'alarm', `${bad} must not read as healthy`);
+    assert.equal(d.state, 'unreadable');
+  }
+});
+
+await test('a populated, fresh index is ok and says how much it holds', async () => {
+  const d = describeIndex({ chunks: 4812, lastIngestedAt: daysAgo(1), now: NOW });
+  assert.equal(d.level, 'ok');
+  assert.match(d.message, /4812/);
+});
+
+await test('a populated but WEEK-OLD index warns — the sweep may have stopped', async () => {
+  const d = describeIndex({ chunks: 4812, lastIngestedAt: daysAgo(9), now: NOW });
+  assert.equal(d.level, 'warn');
+  assert.equal(d.state, 'stale');
+  assert.equal(d.age_days, 9);
+});
+
+await test('staleness is not guessed when nothing says when it last ran', async () => {
+  const d = describeIndex({ chunks: 10, lastIngestedAt: null, now: NOW });
+  assert.equal(d.level, 'ok', 'an unknown age must not be reported as stale');
+  assert.equal(d.age_days, null);
+});
+
+// --- READING THE INGESTERS' EXIT CODES --------------------------------------
+
+await test('a NON-ZERO exit is an alarm carrying the TAIL of stderr', async () => {
+  // Task 1002859 made a partial ingest exit non-zero and NAME every skipped
+  // source — at the end of its output. A head-clip would drop exactly that.
+  const d = describeIngest({
+    name: 'search-ingest-md', code: 1,
+    stderr: ['noise', 'noise', 'noise', 'noise', 'noise', 'noise', 'skipped: docs/adr/0060.md (NUL byte)'].join('\n'),
+  });
+  assert.equal(d.ok, false);
+  assert.equal(d.level, 'alarm');
+  assert.match(d.message, /skipped: docs\/adr\/0060\.md/, 'the last line is the one that matters');
+});
+
+await test('a KILLED ingester is reported as killed, not as a clean failure', async () => {
+  const d = describeIngest({ name: 'search-ingest-db', code: null, signal: 'SIGTERM' });
+  assert.equal(d.ok, false);
+  assert.match(d.message, /KILLED by SIGTERM/);
+  assert.match(d.message, /partially written/, 'a half-written index is the real risk');
+});
+
+await test('exit 0 is ok', async () => {
+  assert.equal(describeIngest({ name: 'x', code: 0 }).ok, true);
+});
+
+// --- THE SWEEP --------------------------------------------------------------
+
+function fakePool(seq) {
+  let i = 0;
+  return { query: async () => ({ rows: [seq[Math.min(i++, seq.length - 1)]] }) };
+}
+
+await test('the sweep runs BOTH ingesters — one failing must not skip the other', async () => {
+  const called = [];
+  const exec = (_p, args, _o, cb) => {
+    called.push(args[0].split('/').pop());
+    cb(args[0].includes('md') ? Object.assign(new Error('x'), { code: 1 }) : null, '', 'boom');
+  };
+  const r = await sweep({ pool: fakePool([{ chunks: 0, last: null }]), log: quietLog, execFileImpl: exec, now: NOW });
+  assert.deepEqual(called, ['search-ingest-md.js', 'search-ingest-db.js']);
+  assert.equal(r.results.length, 2);
+  assert.equal(r.results[0].ok, false);
+  assert.equal(r.results[1].ok, true, 'the db ingest still ran after the md ingest failed');
+});
+
+await test('the sweep reports the AFTER count — exit 0 that wrote nothing is a failure shape', async () => {
+  // The precise trap: an ingester can exit 0 and leave the table empty. Without
+  // an after-picture that reads as success.
+  const r = await sweep({
+    pool: fakePool([{ chunks: 0, last: null }, { chunks: 0, last: null }]),
+    log: quietLog, execFileImpl: okExec, now: NOW,
+  });
+  assert.equal(r.after.state, 'empty', 'still empty after a "successful" ingest');
+  assert.equal(r.after.level, 'alarm');
+});
+
+await test('a healthy sweep still SPEAKS — silence must not be the healthy state', async () => {
+  // The reconciler's lesson: a sweep that only logs on failure is
+  // indistinguishable from a sweep that is not running at all.
+  const lines = [];
+  await sweep({
+    pool: fakePool([{ chunks: 4812, last: daysAgo(1) }]),
+    log: { log: (m) => lines.push(m), error: (m) => lines.push(m) },
+    execFileImpl: okExec, now: NOW,
+  });
+  assert.ok(lines.length >= 2, 'a healthy sweep leaves a disposition line');
+  assert.ok(lines.some((l) => /4812/.test(l)), 'and says what it found');
+});
+
+await test('a DB read failure never throws out of the sweep', async () => {
+  const r = await sweep({
+    pool: { query: async () => { throw new Error('connection refused'); } },
+    log: quietLog, execFileImpl: okExec, now: NOW,
+  });
+  assert.equal(r.health.state, 'unreadable');
+  assert.equal(r.health.level, 'alarm');
+});
+
+await test('the poller is declared in the memory manifest — a file nothing loads is dormant', async () => {
+  // The exact failure goal 1000076 hit five times: a surface that exists, is
+  // documented, and is never wired.
+  const manifest = require('../modules/memory/module.json');
+  assert.ok(
+    (manifest.contributes.pollers || []).includes('search-index'),
+    'modules/memory/module.json must declare the poller for the loader to start it',
+  );
+});
+
+console.log(`\nsearch_index_poller: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);