@bongos/core 1.19.836 → 1.19.838

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

@@ -0,0 +1,737 @@
+'use strict';
+
+// modules/agents/pollers/event-router.js — the EVENT half of the agents module
+// (task 1002494, goal 1000095 / BONGOS-V2).
+//
+// `POST /agents/:name/invoke` fires an agent because a builder asked. This fires
+// one because something HAPPENED: the lifecycle emits `task.shipped`, and every
+// enabled definition whose `trigger_spec` names that event and whose declared
+// `touches[]` filter covers what shipped gets one fire. It is the counterpart of
+// gate.js — that file answers "may this be asked?", this one answers "should
+// this be told?" — and it is the thing task 1002495's roster (review-lens,
+// doc-link-keeper, dep-security-watch) needs in order to exist at all.
+//
+// It is filed under pollers/ because that is the loader's only boot hook for a
+// module (src/module-loader/loader.js startModulePollers → `contributes.pollers`,
+// declared in module.json). It owns no timer: `start()` subscribes and `stop()`
+// unsubscribes. A "poller" here means "something the module runs in the web
+// process", not "something on a clock".
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// FOUR PROPERTIES, EACH FROM THE TASK'S OWN BRIEF, AND EACH LOAD-BEARING.
+//
+// 1. THE CHEAP FILTER RUNS FIRST — NEVER PAY FOR A SPAWN TO DISCOVER
+//    IRRELEVANCE. Nothing spawns until the definition's declared `touches[]`
+//    globs have been matched against what the shipped task actually touched. A
+//    fire is ~$0.90 and 60-120 seconds; a glob match is microseconds and no I/O.
+//    The order below is strictly cheapest-first for that reason: the indexed
+//    definition read, then the glob filter, then the loop guard, then the sink
+//    check, then the fan-out cap, then the spend ceiling, and only then a model.
+//
+//    A PRE-FILTER MISS IS NOT LEDGERED, and that is a deliberate departure from
+//    the module's "every refusal is a row" rule. A miss is SELECTION, not
+//    refusal — the same category as the partial dispatch index skipping a
+//    disabled row, which also writes nothing. Ledgering it would put one row per
+//    non-matching agent on every ship forever and bury the refusals that matter.
+//    Everything downstream of the filter — the loop guard, an unwired sink, the
+//    fan-out cap, the spend ceiling — IS ledgered as a no-go, because each of
+//    those stops a fire that was otherwise going to happen.
+//
+// 2. THE DEPTH GUARD, OR AGENTS TRIGGER EACH OTHER FOREVER. An agent's finding
+//    is filed through `ideas.capture`; an idea becomes a task; a task ships; a
+//    ship is `task.shipped`. That is a closed loop, and without a guard it is an
+//    unbounded one that spends real money going round. So: a ship that is itself
+//    ATTRIBUTED to an `agents_runs` row fires nothing. Attribution is read off
+//    the ledger's own `output_ref` — the pointer a fire writes when its finding
+//    lands — never off a heuristic about the task's title or author.
+//
+//    It FAILS CLOSED: an unreadable ledger, a missing task row, a throwing
+//    query all read as "attributed", i.e. do not fire. "I could not check
+//    whether this is a loop" must never resolve to "go ahead"; that is the exact
+//    failure lib/spend-ceiling.js's header dissects at length (task 1001393).
+//
+// 3. THE SINK IS CHECKED BEFORE THE SPAWN, NOT AFTER. A finding delivered
+//    nowhere is a fire nobody can read and money nobody got anything for, so an
+//    unwired or unavailable sink refuses BEFORE the model runs — property 1
+//    applied to the other end of the pipe. SINK_CATALOG is the WIRED set, not
+//    the imaginable set, exactly as validate.js's EVENT_CATALOG is — every
+//    entry is backed by a port that exists, and one that is wired but absent on
+//    this instance refuses by name rather than silently.
+//
+// 4. IT CAN NEVER BLOCK, SLOW, OR FAIL A SHIP. `seams.emitAsync` AWAITS each
+//    listener (src/module-seams.js), and the HTTP ship handler awaits the emit —
+//    so a listener that awaited a 120-second fire would hold the shipping
+//    builder's request open for two minutes. The subscribed handler is therefore
+//    SYNCHRONOUS and returns undefined: it kicks the fan-out off detached and
+//    returns instantly. Every error inside is caught and logged. Only the
+//    DB-gated Grader gates landing; agents are observe-only, and this file must
+//    not become a second gate by accident or by latency.
+
+const api = require('../../../src/module-api');
+const { spawnAgent } = require('../spawn');
+const { createSpendCeiling, payerFor } = require('../lib/spend-ceiling');
+
+const log = api.logger('agents');
+
+// The event this router dispatches. One constant rather than a literal in three
+// places, and a member of validate.js's EVENT_CATALOG by construction — a
+// definition naming an event nothing dispatches is refused at validation, so
+// this string and that catalog entry are two halves of one wiring.
+const EVENT = 'task.shipped';
+
+// ONE instance for the module, for the reason lib/fire-budget.js's header gives:
+// a ceiling that splits when a second caller builds its own is not a ceiling.
+// The routes file holds its own for the on-demand path; this is the event path's,
+// and they read the same ledger, so the CAP is one number either way.
+const spendCeiling = createSpendCeiling();
+
+// How many agents ONE event may fire. The on-demand path is bounded by
+// lib/fire-budget.js — a sliding window per BUILDER — and an event fire has no
+// builder, so that ceiling cannot apply to it (lib/spend-ceiling.js's payerFor
+// says so in as many words: "an event fire has no caller"). That leaves the
+// monthly spend ceiling as the only bound, and its header names its own blind
+// spot: fires already in flight are invisible to it, so the overshoot is
+// "concurrent-fires × ~$0.90" and "what bounds the concurrent count is
+// fire-budget". On this path nothing did. This is that missing half — a blast
+// radius per event, not an accounting, and the same shape for the same reason.
+const DEFAULT_FANOUT_MAX = 5;
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+const FANOUT_MAX = envInt('BONGOS_AGENTS_EVENT_FANOUT_MAX', DEFAULT_FANOUT_MAX);
+
+// The columns one fire needs. Spelled out rather than SELECT *, for the reason
+// routes/agents.js gives about its own COLUMNS list: a column added later must
+// not reach a model prompt just because it exists. Only what a fire reads: `id` + `name` for the ledger, `persona` for
+// the prompt, `trigger_spec` for the filter and the sink, `model_tier` for the
+// spawn. Deliberately NOT `scope_violation` — a flagged definition is forced
+// `enabled = false` by agents_definitions_flagged_not_armed_chk, so the WHERE
+// clause below already excludes it and a second check here would only be a
+// second place to get it wrong.
+const DEF_COLUMNS = `
+  id, name, persona, trigger_type, trigger_spec, model_tier
+`;
+
+// ---------------------------------------------------------------------------
+// THE PRE-FILTER (pure)
+// ---------------------------------------------------------------------------
+
+// The declared filter, read off `trigger_spec`. `touches` is the documented
+// spelling; `touches_globs` is accepted as the same thing because the field is
+// named after the task column it matches against and both spellings have been
+// written down in the goal's own prose. Anything that is not an array of
+// non-empty strings is treated as ABSENT rather than as an error: a malformed
+// filter must not silently narrow to "matches nothing", which would disarm an
+// armed agent with no trace. It widens to "no filter declared", which is visible
+// in the registry and in this file's log line.
+function declaredGlobs(definition) {
+  const spec = definition && definition.trigger_spec;
+  if (!spec || typeof spec !== 'object') return [];
+  const raw = Array.isArray(spec.touches) ? spec.touches
+    : Array.isArray(spec.touches_globs) ? spec.touches_globs
+      : [];
+  return raw.filter((g) => typeof g === 'string' && g.trim() !== '');
+}
+
+/**
+ * Does this definition's declared filter cover what the task touched? PURE.
+ *
+ * NO DECLARED FILTER ⇒ FIRES ON EVERY SHIP. An absent filter is a definition
+ * that declared no narrowing, and inventing one for it would make an armed
+ * agent inert for reasons nothing records. Arming a universal agent is a
+ * deliberate act by a Metic+ author (the `agent.arm` atom), it is visible in
+ * `GET /agents`, and its cost is bounded by the fan-out cap and the spend
+ * ceiling — which is the honest place for that bound to live.
+ *
+ * A DECLARED FILTER AGAINST AN EMPTY `touches[]` ⇒ NO FIRE. A task that declared
+ * no blast radius offers no evidence that it is in the agent's scope, and this
+ * is the path where "no evidence" must read as "do not spend" — the cheap-filter
+ * rule of property 1. `touches[]` is advisory on a task (ADR 0049), so this is
+ * the right direction of error: a missed fire costs nothing and shows up as an
+ * agent that stayed quiet; a paid fire on an unrelated ship costs ~$0.90 and
+ * shows up as noise in the inbox.
+ *
+ * @param {object} definition  the agents_definitions row.
+ * @param {string[]} taskTouches  the shipped task's touches[].
+ * @param {(globs: string[]) => (file: string) => boolean} compile  the matcher
+ *        factory, injected so this stays pure and testable with no core require.
+ * @returns {{match: boolean, reason: string}}
+ */
+function matchesTouches(definition, taskTouches, compile) {
+  const globs = declaredGlobs(definition);
+  if (globs.length === 0) return { match: true, reason: 'no_filter_declared' };
+  const paths = (Array.isArray(taskTouches) ? taskTouches : []).filter(
+    (p) => typeof p === 'string' && p.trim() !== '',
+  );
+  if (paths.length === 0) return { match: false, reason: 'task_declared_no_touches' };
+  let matcher;
+  try {
+    matcher = compile(globs);
+  } catch (_) {
+    // A filter that cannot be compiled is a filter nobody can trust. Refuse the
+    // fire rather than fall back to matching everything, which would turn a typo
+    // in one definition into a paid fire on every ship.
+    return { match: false, reason: 'filter_uncompilable' };
+  }
+  for (const p of paths) {
+    let hit = false;
+    try { hit = matcher(p) === true; } catch (_) { hit = false; }
+    if (hit) return { match: true, reason: 'touches_match' };
+  }
+  return { match: false, reason: 'no_touches_overlap' };
+}
+
+/**
+ * Split the candidate definitions into the ones that fire and the ones the
+ * pre-filter dropped. PURE — the whole selection decision, testable with no
+ * database, no model and no server.
+ */
+function selectFiring(definitions, taskTouches, compile) {
+  const firing = [];
+  const filtered = [];
+  for (const d of definitions || []) {
+    const verdict = matchesTouches(d, taskTouches, compile);
+    (verdict.match ? firing : filtered).push({ definition: d, reason: verdict.reason });
+  }
+  return { firing, filtered };
+}
+
+// ---------------------------------------------------------------------------
+// THE DEPTH GUARD
+// ---------------------------------------------------------------------------
+
+// The `output_ref` spellings that would mean "an agent produced this". PURE.
+//
+// Two refs, because a finding reaches a task by two hops and the guard has to
+// cover both ends:
+//   `task:<id>`  — a fire whose output landed as this task directly.
+//   `idea:<id>`  — a fire whose finding landed as an idea; `/idea-triage` later
+//                  promoted it, and the promotion stamps `tasks.source` as
+//                  'idea-<id>' (that is how every promoted task on this instance
+//                  is spelled). So the idea id is recoverable from the task row
+//                  with no cross-module table read — this module may not go
+//                  reading `idea_inbox`, and does not have to.
+function depthRefsFor(taskRow) {
+  const refs = [];
+  const id = taskRow && taskRow.id;
+  if (id !== null && id !== undefined && String(id) !== '') refs.push(`task:${id}`);
+  const source = taskRow && typeof taskRow.source === 'string' ? taskRow.source : '';
+  const m = source.match(/^idea-(\d+)$/);
+  if (m) refs.push(`idea:${m[1]}`);
+  return refs;
+}
+
+/**
+ * Is this ship attributable to an agent fire? FAILS CLOSED — an unanswerable
+ * question returns `true`, i.e. "do not fire".
+ *
+ * @returns {{attributed: boolean, reason: string|null}}
+ */
+async function isAgentAttributed(pool, taskRow) {
+  const refs = depthRefsFor(taskRow);
+  if (refs.length === 0) {
+    // No id to ask about. Not knowing which task shipped is not a reason to
+    // spend; it is a reason to stop.
+    return { attributed: true, reason: 'the shipped task could not be identified, so the loop guard could not be evaluated' };
+  }
+  if (!pool || typeof pool.query !== 'function') {
+    return { attributed: true, reason: 'the agents_runs ledger was unreadable, so the loop guard could not be evaluated' };
+  }
+  try {
+    const { rows } = await pool.query(
+      `SELECT id, agent_name FROM agents_runs
+        WHERE output_ref = ANY($1::text[])
+        LIMIT 1`,
+      [refs],
+    );
+    if (rows && rows.length) {
+      return {
+        attributed: true,
+        reason: `this ship is attributed to agent run ${rows[0].id} (${rows[0].agent_name}) — firing on an agent's own output is the loop this guard exists to stop`,
+      };
+    }
+    return { attributed: false, reason: null };
+  } catch (_) {
+    return { attributed: true, reason: 'the agents_runs ledger read threw, so the loop guard could not be evaluated' };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// THE SINKS
+// ---------------------------------------------------------------------------
+
+// WIRED, not imaginable — the same rule and the same reason as validate.js's
+// EVENT_CATALOG: a definition naming a sink nothing delivers to looks armed and
+// can never report, which is the worst of both readings. Both entries below are
+// backed by a port that exists; a name with no port behind it does not belong
+// here, and `resolveSink` refuses one that is wired but absent on this instance.
+//
+// The two differ in KIND, not just destination, and a definition picks by what
+// it wants done with the finding:
+//
+//   `ideas.capture`  the finding enters the BACKLOG as an inbox row a human
+//                    triages. Filed with no `vector`, so routing.js leaves it an
+//                    idea and never a claimable task.
+//   `discord`        the finding is ANNOUNCED and nothing more. Discord is a
+//                    one-way mirror and never authority (ADR 0033), which is
+//                    also why this sink cannot feed the loop the depth guard
+//                    watches: a message becomes no record here, so there is
+//                    nothing for a later ship to be attributed to.
+const SINK_CATALOG = Object.freeze({
+  'ideas.capture': Object.freeze({ port: 'ideas.capture', deliver: deliverToInbox }),
+  discord: Object.freeze({ port: 'discord.post', deliver: deliverToDiscord }),
+});
+
+const DEFAULT_SINK = 'ideas.capture';
+
+// Which sink did this definition declare? PURE. Absent ⇒ the default, because a
+// finding with nowhere to go is the one outcome worth ruling out by construction.
+function sinkNameFor(definition) {
+  const spec = definition && definition.trigger_spec;
+  const raw = spec && typeof spec === 'object' ? spec.sink : null;
+  return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : DEFAULT_SINK;
+}
+
+/**
+ * Resolve the declared sink to something that can actually take a finding, or
+ * say why not. Called BEFORE the spawn — property 3.
+ *
+ * @returns {{ok: true, name: string, deliver: Function} | {ok: false, name: string, reason: string}}
+ */
+function resolveSink(definition, deps = {}) {
+  const name = sinkNameFor(definition);
+  const entry = SINK_CATALOG[name];
+  if (!entry) {
+    return {
+      ok: false,
+      name,
+      reason: `sink '${name}' is not wired — this instance delivers findings to: ${Object.keys(SINK_CATALOG).join(', ')}. Refused before spawning rather than after: a finding nobody receives is money spent for nothing.`,
+    };
+  }
+  const resolveOptional = deps.resolveOptional
+    || (typeof api.resolveOptional === 'function' ? api.resolveOptional.bind(api) : null);
+  const port = resolveOptional ? resolveOptional(entry.port, null) : null;
+  if (typeof port !== 'function') {
+    return {
+      ok: false,
+      name,
+      reason: `sink '${name}' is wired but the '${entry.port}' port is not available on this instance (the module providing it is disabled) — refused before spawning.`,
+    };
+  }
+  return { ok: true, name, deliver: port, entry };
+}
+
+// Everything a sink is handed is UNTRUSTED TEXT, from two directions at once:
+// `task.title` is builder-authored and can arrive from the idea inbox, and the
+// finding is raw model output generated from a repo the agent read. Both are
+// bounded and stripped of control characters HERE, once, so neither sink has to
+// remember to — and so nothing that reaches a rendering surface can carry an
+// ANSI escape, a NUL, or an unbounded blob. This is a floor, not an escaping
+// layer: HTML escaping belongs to whatever renders the row, and this file makes
+// no claim about it.
+const TITLE_MAX = 180;
+const BODY_MAX = 8000;
+
+function clean(value, max) {
+  // Scanned by CODE POINT rather than matched by a regex character class: the
+  // class would have to spell control characters as escape sequences, and a
+  // source file that spells them is one editor away from CONTAINING them —
+  // which is how this file first shipped as a binary blob git would not diff.
+  // Tab and newline survive; everything else below 0x20, plus DEL, becomes a
+  // space.
+  const s = String(value == null ? '' : value);
+  let out = '';
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    const control = (c < 0x20 && c !== 0x0a && c !== 0x09) || c === 0x7f;
+    out += control ? ' ' : ch;
+  }
+  return out.trim().slice(0, max);
+}
+
+// The two lines every finding carries, whichever sink takes it: WHO said it,
+// WHAT it was looking at, and WHEN. Composed once so the two deliveries cannot
+// describe the same fire differently.
+function findingParts({ definition, task, text }) {
+  return {
+    title: clean(`${definition.name}: ${task.title || `task ${task.id}`}`, TITLE_MAX),
+    provenance: `Reported by the \`${definition.name}\` agent on \`${EVENT}\` for task ${task.id}.`,
+    body: clean(text, BODY_MAX),
+  };
+}
+
+// The BACKLOG sink. NO `vector` IS PASSED, and that is the observe-only property
+// in one argument: modules/ideas/routing.js routes a capture into a real task
+// only for a filing vector on its own allowlist, so an absent vector is
+// UNTRUSTED and the finding stays an inbox row for a human to triage. An agent
+// may report, and may not manufacture claimable work — the same posture as the
+// read-only spawn, enforced at the other end of the pipe.
+//
+// Returns the POINTER, never the text: `agents_runs.output_ref` is a pointer by
+// schema contract (see the migration's header), and `idea:<id>` is the spelling
+// the depth guard reads back.
+async function deliverToInbox(deliver, parts) {
+  const idea = await deliver({
+    title: parts.title,
+    bodyMd: `${parts.provenance}\n\n${parts.body}`,
+    capturedBy: null,
+  });
+  const id = idea && idea.id;
+  return id !== null && id !== undefined ? `idea:${id}` : null;
+}
+
+// The ANNOUNCE sink. Discord is a one-way mirror and never authority (ADR 0033).
+//
+// THE CHANNEL IS DECIDED HERE, NEVER BY THE DEFINITION. An agent that could name
+// its own channel could choose where it is heard, and the one choice that
+// actually matters is the security one: a finding about a SECURITY-SENSITIVE
+// ship must not advertise the shape of an unpatched exploit on a channel the
+// whole guild reads. So this mirrors ship-broadcast.chooseBroadcastTargets' rule
+// verbatim, including its fail-closed arm — a `security_sensitive` that is not a
+// definite boolean SUPPRESSES the post rather than guessing, because "we could
+// not tell whether this was a security fix" must never resolve to "post it
+// publicly".
+function discordChannelFor(task) {
+  const sec = task && task.security_sensitive;
+  if (sec === true) return 'security_ship_feed';
+  if (sec === false) return 'ship_feed';
+  return null;
+}
+
+async function deliverToDiscord(deliver, parts, { task }) {
+  const channel = discordChannelFor(task);
+  if (!channel) return null;
+  const res = await deliver({
+    channel,
+    text: `${parts.title}\n${parts.provenance}\n${parts.body}`,
+  });
+  // A post that did not happen is not a pointer. `discord.post` answers
+  // `{posted:false}` when the operator configured no webhook for the channel,
+  // and recording a pointer to a message that does not exist would be a lie the
+  // ledger cannot be talked out of later.
+  return res && res.posted === true ? `discord:${channel}:${task.id}` : null;
+}
+
+// Deliver one finding through whichever sink resolved, and return the POINTER to
+// where it landed.
+async function deliverFinding(sink, { definition, task, text }) {
+  const parts = findingParts({ definition, task, text });
+  const deliver = sink.entry && typeof sink.entry.deliver === 'function' ? sink.entry.deliver : deliverToInbox;
+  return deliver(sink.deliver, parts, { task, definition });
+}
+
+// ---------------------------------------------------------------------------
+// THE FAN-OUT
+// ---------------------------------------------------------------------------
+
+// The deps spawnAgent is handed. The POOL is threaded explicitly rather than
+// left to spawnAgent's `api.pool` fallback, so a caller that injected a fake pool
+// for the reads above does not silently get the real one for the ledger writes —
+// a test that half-injects is a test that writes rows into a live database.
+function spawnDepsFrom(deps = {}) {
+  const extra = deps.spawnDeps || {};
+  return deps.pool && !extra.pool ? { ...extra, pool: deps.pool } : { ...extra };
+}
+
+// Record a fire that is NOT going to happen, using the same spawn seam the real
+// ones use. spawnAgent writes the no-go row and returns without spawning, so
+// this is a database round trip and never a model call — and routing it through
+// spawnAgent rather than an INSERT here is what keeps ONE ledger contract in
+// ONE place (the second copy is how two ledgers start disagreeing).
+async function ledgerNoGo(deps, { definition, taskId, reason, spendPayer }) {
+  try {
+    return await spawnAgent({
+      definition,
+      trigger: { type: 'event', ref: `${EVENT}:${taskId}` },
+      gate: { decision: 'no-go', reason },
+      requestedByBuilderId: null,
+      spendPayer,
+    }, spawnDepsFrom(deps));
+  } catch (err) {
+    // spawnAgent does not throw, but this whole file's contract is that nothing
+    // reaches the emitter. A ledger write that failed is logged, not raised.
+    log.error({ err, agent: definition && definition.name }, 'agents/event-router: no-go ledger write failed');
+    return null;
+  }
+}
+
+/**
+ * The whole reaction to one shipped task. Exported and awaitable so a test can
+ * drive it end to end; the subscribed handler never awaits it (property 4).
+ *
+ * Returns a REPORT rather than throwing — the same shape the cascade runner
+ * returns for the same reason (ADR 0242): a reaction that could fail the thing
+ * it reacted to would smuggle a gate in through the back door.
+ */
+async function fanOut(payload, deps = {}) {
+  const report = {
+    task_id: null, considered: 0, filtered: 0, fired: 0, skipped: 0, reason: null,
+  };
+  const pool = deps.pool || api.pool;
+  const compile = deps.compileGlobMatcher
+    || ((globs) => api.permissionPathCheck.compileGlobMatcher(globs));
+  const spendPayer = deps.spendPayer !== undefined ? deps.spendPayer : projectSpendPayer();
+
+  const taskId = payload && payload.id !== undefined && payload.id !== null ? String(payload.id) : null;
+  report.task_id = taskId;
+  if (!taskId) { report.reason = 'no_task_id'; return report; }
+
+  // (a) THE DEFINITION READ, FIRST AND CHEAPEST. It rides the partial dispatch
+  // index agents_001 built for exactly this query (`WHERE enabled`), and on the
+  // overwhelmingly common instance — agents shipped, nothing armed — it returns
+  // zero rows and the whole reaction ends here, having read no task, spent
+  // nothing and written nothing.
+  let definitions = [];
+  try {
+    const { rows } = await pool.query(
+      `SELECT ${DEF_COLUMNS} FROM agents_definitions
+        WHERE enabled AND trigger_type = 'event' AND trigger_spec ->> 'event' = $1
+        ORDER BY id`,
+      [EVENT],
+    );
+    definitions = rows || [];
+  } catch (err) {
+    // Nothing is armed as far as we can tell, so nothing fires and nothing is
+    // ledgered — there is no definition to attribute a row to.
+    log.error({ err, task_id: taskId }, 'agents/event-router: definition read failed; no agent fired');
+    report.reason = 'definitions_unreadable';
+    return report;
+  }
+  report.considered = definitions.length;
+  if (definitions.length === 0) { report.reason = 'no_armed_event_agents'; return report; }
+
+  // (b) THE TASK ROW. The `task.shipped` payload is db-ship.js's RETURNING
+  // projection — id, title, status, shipped_at, shipped_by, security_sensitive,
+  // value_summary, credits_reward, kind — and it carries NEITHER `touches` nor
+  // `source`, which are exactly the two fields the pre-filter and the loop guard
+  // read. So this re-reads them rather than trusting a projection that was never
+  // built for this consumer. Widening the emit instead would have coupled the
+  // lifecycle module's ship shape to this module's needs.
+  let task = null;
+  try {
+    const { rows } = await pool.query(
+      `SELECT id, title, touches, source, security_sensitive FROM tasks WHERE id = $1`, [taskId],
+    );
+    task = rows && rows[0] ? rows[0] : null;
+  } catch (_) { task = null; }
+  if (!task) {
+    // FAIL CLOSED. With no touches[] the pre-filter cannot run, and firing every
+    // armed agent on an unreadable task is the expensive direction of that
+    // error. Ledgered, unlike a filter miss: these fires WOULD have happened.
+    const reason = 'the shipped task row could not be read, so the touches[] pre-filter could not run — refused rather than firing every armed agent blind';
+    for (const d of definitions) await ledgerNoGo(deps, { definition: d, taskId, reason, spendPayer });
+    report.skipped = definitions.length;
+    report.reason = 'task_unreadable';
+    return report;
+  }
+
+  // (c) THE CHEAP FILTER — property 1. No I/O, no ledger rows for the misses.
+  const { firing, filtered } = selectFiring(definitions, task.touches, compile);
+  report.filtered = filtered.length;
+  if (firing.length === 0) { report.reason = 'no_agent_matched_touches'; return report; }
+
+  // (d) THE DEPTH GUARD — property 2.
+  const depth = await isAgentAttributed(pool, task);
+  if (depth.attributed) {
+    for (const f of firing) {
+      await ledgerNoGo(deps, { definition: f.definition, taskId, reason: depth.reason, spendPayer });
+    }
+    report.skipped = firing.length;
+    report.reason = 'depth_guard';
+    return report;
+  }
+
+  // (e) THE SINK CHECK — property 3, before any spawn.
+  const deliverable = [];
+  for (const f of firing) {
+    const sink = resolveSink(f.definition, deps);
+    if (!sink.ok) {
+      await ledgerNoGo(deps, { definition: f.definition, taskId, reason: sink.reason, spendPayer });
+      report.skipped += 1;
+      continue;
+    }
+    deliverable.push({ definition: f.definition, sink });
+  }
+  if (deliverable.length === 0) { report.reason = 'no_deliverable_sink'; return report; }
+
+  // (f) THE FAN-OUT CAP. Ordered by id, so which agents survive a cap is stable
+  // and reviewable rather than whatever the planner happened to return first.
+  const admitted = deliverable.slice(0, FANOUT_MAX);
+  for (const over of deliverable.slice(FANOUT_MAX)) {
+    await ledgerNoGo(deps, {
+      definition: over.definition,
+      taskId,
+      reason: `one event may fire at most ${FANOUT_MAX} agents (BONGOS_AGENTS_EVENT_FANOUT_MAX) and ${deliverable.length} matched — a blast radius per event, since an event fire has no builder for the per-builder rate ceiling to bound`,
+      spendPayer,
+    });
+    report.skipped += 1;
+  }
+
+  // (g) THE SPEND CEILING, once for the whole fan-out. Per PAYER, and an event
+  // fire's payer is always the project (lib/spend-ceiling.js payerFor). It fails
+  // closed, including on an unreadable ledger.
+  const payer = payerFor(spendPayer, null);
+  const ceiling = deps.spendCeiling || spendCeiling;
+  const room = await ceiling.check(pool, payer);
+  if (!room.ok) {
+    const reason = room.reason === 'spend_cap_reached'
+      ? `agent spend for this ${payer.payer_kind} has reached its $${room.capUsd} monthly cap`
+      : `the agent spend ceiling could not be established (${room.reason}) — a ceiling that cannot be read must not be assumed`;
+    for (const a of admitted) {
+      await ledgerNoGo(deps, { definition: a.definition, taskId, reason, spendPayer });
+    }
+    report.skipped += admitted.length;
+    report.reason = 'spend_ceiling';
+    return report;
+  }
+
+  // (h) FIRE. Sequentially, so N agents on one ship are N model calls in a row
+  // rather than N at once — the spend ceiling's own blind spot is fires already
+  // in flight, and serialising is what keeps that blind spot one fire wide.
+  for (const a of admitted) {
+    const fired = await fireOne(a, { task, taskId, spendPayer }, deps);
+    if (fired && fired.ran) report.fired += 1; else report.skipped += 1;
+  }
+  report.reason = 'fired';
+  return report;
+}
+
+// One fire, plus the delivery of whatever it said.
+//
+// The delivery happens INSIDE the wrapped runner, so the pointer it produces is
+// written by the SAME `finishRun` update that records the run's cost and
+// duration. Doing it after `spawnAgent` returned would mean a second UPDATE and
+// a window in which the ledger says a fire succeeded and names nowhere its
+// finding went — which is the window the depth guard reads across.
+async function fireOne({ definition, sink }, { task, taskId, spendPayer }, deps = {}) {
+  let outputRef = null;
+  let deliveryError = null;
+
+  const runner = async (args) => {
+    const resolveOptional = deps.resolveOptional
+      || (typeof api.resolveOptional === 'function' ? api.resolveOptional.bind(api) : null);
+    const grade = resolveOptional ? resolveOptional('grade', null) : null;
+    const run = deps.runSubagentCached
+      || (grade && typeof grade.runSubagentCached === 'function' ? grade.runSubagentCached.bind(grade) : null);
+    if (!run) throw Object.assign(new Error('grade port unavailable'), { code: 'grade_port_unavailable' });
+    const out = await run(args);
+    if (out && out.ok === false) return out;
+    const text = out && typeof out.stdout === 'string' ? out.stdout.trim() : '';
+    // A fire that found nothing to say is a SUCCESS with no pointer, not a
+    // failure. An observe-and-report agent reporting "nothing here" is the
+    // outcome most of its fires should have, and filing an empty idea for each
+    // one would make the inbox the noise this module is supposed to reduce.
+    if (!text) return out;
+    try {
+      outputRef = await deliverFinding(sink, { definition, task, text });
+    } catch (err) {
+      // The fire ran and cost money; the finding reached nobody. That is an
+      // ERROR row, not an ok one — a finding that silently evaporated is
+      // indistinguishable from an agent that found nothing, and those two must
+      // never look the same. The cost is still recorded either way.
+      deliveryError = err;
+      log.error({ err, agent: definition.name, task_id: taskId }, 'agents/event-router: sink delivery failed');
+      return { ...out, ok: false, error_code: 'sink_delivery_failed' };
+    }
+    return out;
+  };
+
+  const result = await spawnAgent({
+    definition,
+    trigger: { type: 'event', ref: `${EVENT}:${taskId}` },
+    gate: { decision: 'go' },
+    requestedByBuilderId: null,
+    spendPayer,
+  }, {
+    ...spawnDepsFrom(deps),
+    runSubagentCached: runner,
+    // Read by spawnAgent AFTER the runner resolved, so the pointer the delivery
+    // above produced is the one that lands on the row. A getter rather than a
+    // value for exactly that reason: the value does not exist yet at call time.
+    get outputRef() { return outputRef; },
+  });
+
+  if (deliveryError) log.warn({ agent: definition.name, run_id: result && result.runId }, 'agents/event-router: fire recorded as error because its finding could not be delivered');
+  return result;
+}
+
+// The project's `spend_payer` policy, read the way routes/agents.js reads it and
+// for the same reason — branding already memoizes for the process, so a second
+// cache here would only be a way for the two to disagree.
+function projectSpendPayer() {
+  try {
+    const pack = api.branding ? api.branding() : null;
+    return (pack && pack.project && pack.project.spendPayer) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// THE SUBSCRIPTION
+// ---------------------------------------------------------------------------
+
+let _off = null;
+
+// THE HANDLER IS SYNCHRONOUS ON PURPOSE — property 4. `emitAsync` awaits what a
+// listener returns, and the ship route awaits the emit, so returning a promise
+// here would hold a shipping builder's HTTP request open for the length of a
+// model call. It returns undefined, and the fan-out runs detached behind it.
+function onShipped(task) {
+  try {
+    const p = fanOut(task);
+    if (p && typeof p.catch === 'function') {
+      p.catch((err) => log.error({ err }, 'agents/event-router: fan-out rejected'));
+    }
+  } catch (err) {
+    // fanOut is written not to throw synchronously; this is the belt to that
+    // brace. A reactor must never break the actor.
+    log.error({ err }, 'agents/event-router: fan-out threw');
+  }
+  return undefined;
+}
+
+// off→on replacement rather than an unconditional subscribe, the same idiom
+// modules/discord/routes/discord.js uses: a test (or a re-boot of the loader in
+// one process) must not accumulate duplicate listeners, which would double every
+// fire and every bill.
+function start() {
+  if (_off) return;
+  _off = api.on(EVENT, onShipped);
+  log.info(
+    `[agents/event-router] listening on ${EVENT} — up to ${FANOUT_MAX} agents per event, sinks: ${Object.keys(SINK_CATALOG).join(', ')}`,
+  );
+}
+
+function stop() {
+  if (_off) { try { _off(); } catch (_) { /* already gone */ } }
+  _off = null;
+}
+
+module.exports = {
+  start,
+  stop,
+  // Exported for tests + introspection. The pure half (declaredGlobs,
+  // matchesTouches, selectFiring, depthRefsFor, sinkNameFor) is the whole
+  // selection decision and needs no database, no model and no server to prove.
+  fanOut,
+  onShipped,
+  declaredGlobs,
+  matchesTouches,
+  selectFiring,
+  depthRefsFor,
+  isAgentAttributed,
+  sinkNameFor,
+  resolveSink,
+  deliverFinding,
+  EVENT,
+  SINK_CATALOG,
+  DEFAULT_SINK,
+  FANOUT_MAX,
+  DEFAULT_FANOUT_MAX,
+};