@bongos/core 1.19.710 → 1.19.711

package/modules/agents/routes/agents.js

@@ -35,14 +35,62 @@
 // Same idioms as modules/copy-desk/routes/copy-desk.js: doorway-only requires,
 // factory export mounted from module.json `contributes.routes`, res.fail codes.
 
+// ---------------------------------------------------------------------------
+// THE WRITE SURFACE (task 1002493, Phase 2a) was added below the reads above.
+//
+// A Metic+ builder can now create, edit, arm, disarm, delete and fire an agent
+// with no Archon file edit — and ENFORCEMENT IS DB-SIDE, so nothing a caller
+// writes grants anything. The rules it turns on live in ../lib/authoring.js,
+// beside the reasoning for each; the gate a fire passes lives in ../lib/gate.js
+// so the CLI and this route cannot drift apart. Read those two before editing
+// anything here: this file is the HTTP shell around decisions made there.
+//
+// The verbs and their gates:
+//   POST   /agents                  agent.author  create (source='db', never armed)
+//   PATCH  /agents/:name            agent.author  edit IN PLACE — never a second row
+//   DELETE /agents/:name            agent.author  remove a db-authored definition
+//   POST   /agents/:name/enable     agent.arm     arm — the operator act rule 4 reserves
+//   POST   /agents/:name/disable    agent.arm     disarm — and that stops dispatch
+//   POST   /agents/:name/invoke     requireBuilder  fire on demand (202 + run id)
+//   GET    /agent-runs/:id          requireBuilder  what one fire did, and its answer
+//
+// THE WRITES GATE ON AUTHORITY ATOMS, NOT A RANK (ADR 0151 / BV1.R105 — and
+// tests/government_require_permission.mjs fails the build for a modules/*/routes
+// gate that still spells requireRank). Both atoms seed at the Metic floor, so
+// this admits exactly who `requireRank('metic', 'archon')` would have; what it
+// adds is that an instance can delegate them from the Government tab without
+// moving anyone's rank.
+//
+// TWO atoms rather than one, because the two acts differ in consequence.
+// `agent.author` writes a definition; `agent.arm` turns a piece of text into
+// something that spends money and reads the repo — and arming is the only write
+// that works on a committed, file-sourced definition, so that atom IS the act
+// that lets a committed agent run at all.
+//
+// WHY /agent-runs AND NOT /agents/runs/:id. `runs` is a legal agent name
+// (NAME_RE admits it), so nesting the ledger under /agents would put a reserved
+// word in a namespace the validator does not reserve. A sibling path costs one
+// line of prose and closes the question permanently.
+
 'use strict';
 
 const express = require('express');
 const api = require('../../../src/module-api');
 const validate = require('../lib/validate');
+const authoring = require('../lib/authoring');
+const { gateFor } = require('../lib/gate');
+const { createAnswerHold } = require('../lib/answer-hold');
+const { createFireBudget } = require('../lib/fire-budget');
+const { spawnAgent } = require('../spawn');
 
 const log = api.logger('agents');
 
+// ONE instance for the module, deliberately NOT per-router: a ceiling that splits
+// when a second router is built is not a ceiling. The answer hold below is
+// per-router for the opposite reason — it is a delivery buffer, and a split one
+// only means an answer is collected where it was produced.
+const fireBudget = createFireBudget();
+
 // The columns the serializer needs. Spelled out rather than `SELECT *` so that a
 // column added later (an author's email, a raw credential) cannot reach a
 // response by default — the read surface widens only when someone edits this
@@ -104,8 +152,119 @@ function serializeDefinition(row, { includePersona = false } = {}) {
   return out;
 }
 
+// PURE. One ledger row → the wire shape. `output_ref` is served as the pointer
+// it is; the answer, when one is still being held, arrives beside it under its
+// own key so nobody can mistake the row for the place the text lives.
+function serializeRun(row, { answer = null } = {}) {
+  if (!row) return null;
+  return {
+    id: String(row.id),
+    agent: row.agent_name,
+    trigger: { type: row.trigger_type, ref: row.trigger_ref || null },
+    gate: { decision: row.gate_decision, reason: row.gate_reason || null },
+    status: row.status,
+    error_code: row.error_code || null,
+    model: row.model || null,
+    cost_usd: row.cost_usd === null || row.cost_usd === undefined ? null : Number(row.cost_usd),
+    duration_ms: row.duration_ms === null || row.duration_ms === undefined ? null : Number(row.duration_ms),
+    output_ref: row.output_ref || null,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    // null means one of three histories with one remedy: never held, expired, or
+    // evicted. The row above is where a caller finds out which.
+    answer,
+  };
+}
+
+// The scope context every write is judged against, read the way every other
+// enforcer reads it: the module roster and the protected-surface registry, both
+// synchronously from the checkout, no DB and no HTTP (ADR 0043). Resolved per
+// request rather than cached so a registry edit takes effect on the next write
+// instead of at the next restart — the same no-caching property the rank check
+// has, and for the same reason.
+function scopeContext() {
+  const scopeMap = api.moduleScopeMap;
+  const permissionPaths = api.permissionPathCheck;
+  return {
+    allowedModules: scopeMap.moduleKeys(),
+    protectedModules: scopeMap.protectedModules(),
+    isProtectedPath: (p) => permissionPaths.surfaceFor(p) !== null,
+  };
+}
+
+// The body a caller may send. Bounds mirror the schema's CHECKs, and `strict`
+// turns a key the schema does not name into a 400 — so `author_rank` in a body
+// is a loud refusal rather than a silent drop (authoring rule 1).
+function writeSchema({ nameRequired }) {
+  return {
+    name: { required: nameRequired, type: 'string', maxLength: validate.NAME_MAX, minLength: 1 },
+    title: { type: 'string', maxLength: api.LIMITS.TITLE },
+    persona: { required: nameRequired, type: 'string', maxLength: 32768, minLength: 1 },
+    trigger_type: { required: nameRequired, type: 'string', maxLength: 32 },
+    trigger_spec: { type: 'object' },
+    model_tier: { type: 'string', maxLength: 32 },
+    scope_modules: { type: 'array', itemsType: 'string', maxItems: 64 },
+    scope_paths: { type: 'array', itemsType: 'string', maxItems: 64 },
+  };
+}
+
+// Refuse a body that names a server-owned field, BY NAME and with the reason.
+// Runs before the schema check so the answer is "you may not set author_rank and
+// here is why", not "unknown_field".
+function refusedServerOwned(req, res) {
+  const forbidden = authoring.forbiddenFields(req.body);
+  if (forbidden.length === 0) return false;
+  res.fail('server_owned_field', { status: 400, message: `these fields are decided server-side: ${forbidden.map((f) => `${f.field} (${f.reason})`).join('; ')}` });
+  return true;
+}
+
+// Validate a whole candidate against the author's LIVE rank, then apply the
+// stricter DB-authoring wall on top (authoring rule 3). Returns the normalized
+// row, or responds and returns null.
+function validatedOrRejected(candidate, req, res) {
+  const ctx = scopeContext();
+  const verdict = validate.validateAgentDefinition(candidate, {
+    // Rule 2: the rank is the caller's LIVE rank, so a declaration can never
+    // exceed the authority behind it.
+    authorRank: req.builder.rank,
+    allowedModules: ctx.allowedModules,
+    protectedModules: ctx.protectedModules,
+    isProtectedPath: ctx.isProtectedPath,
+  });
+  if (!verdict.ok) {
+    res.fail('agent_definition_invalid', { status: 400, message: verdict.errors.map((e) => e.message).join(' · ') });
+    return null;
+  }
+  const hits = authoring.protectedScopeHits(verdict.value, ctx);
+  if (hits.protected) {
+    const named = [...hits.modules, ...hits.paths].map((s) => JSON.stringify(s)).join(', ');
+    res.fail('scope_reaches_protected_surface', {
+      status: 403,
+      message: `scope: ${named} reaches a protected surface. A definition authored over HTTP may not, at any rank — a committed one reaches the registry through a branch, a grader panel and CI, and this one reaches it through a single call. Commit it to .claude/agents/ instead.`,
+    });
+    return null;
+  }
+  return verdict.value;
+}
+
+// Fire an agent without waiting for it. Returns the run id as soon as the ledger
+// row exists, plus the promise that settles when the fire does — see the
+// onLedgered note in ../spawn.js for why the route does not insert its own row.
+function fireInBackground(args, deps) {
+  let announce;
+  const ledgered = new Promise((resolve) => { announce = resolve; });
+  const done = spawnAgent(args, { ...deps, onLedgered: (id) => announce(id) });
+  // A ledger write that FAILED never calls onLedgered, so the await above would
+  // hang forever without this. Resolving twice is a no-op.
+  done.then((fired) => announce(fired.runId ?? null), () => announce(null));
+  return { ledgered, done };
+}
+
 module.exports = function agentsRoutes() {
   const router = express.Router();
+  // Per-router, so a test gets a fresh counter and two mounted instances never
+  // hand each other's answers out.
+  const hold = createAnswerHold();
 
   // GET /agents — the whole registry. Unpaginated on purpose: agents are
   // instance CONFIGURATION reconciled from committed files, so the row count is
@@ -169,9 +328,344 @@ module.exports = function agentsRoutes() {
     }
   });
 
+  // POST /agents — author a definition against the DB, no file edit.
+  //
+  // It lands DISARMED, always. Creating and arming are separate acts with
+  // separate audit lines, and a create that armed would let one call both invent
+  // an agent and switch it on — the same reasoning agents-sync rule 4 applies to
+  // a commit, applied to an HTTP request.
+  router.post('/agents', api.requireBuilder, api.requirePermission('agent.author'), async (req, res) => {
+    if (refusedServerOwned(req, res)) return undefined;
+    if (api.validateOrRespond(req, res, writeSchema({ nameRequired: true }), { strict: true })) return undefined;
+    const value = validatedOrRejected(req.body, req, res);
+    if (!value) return undefined;
+    try {
+      const { rows } = await api.pool.query(
+        `INSERT INTO agents_definitions
+           (name, title, persona, trigger_type, trigger_spec, model_tier,
+            scope_modules, scope_paths, source, provenance, author_rank,
+            author_builder_id, enabled)
+         VALUES ($1,$2,$3,$4,$5::jsonb,$6,$7,$8,'db','instance',$9,$10,false)
+         RETURNING ${COLUMNS}, persona`,
+        [value.name, value.title, value.persona, value.trigger_type,
+          JSON.stringify(value.trigger_spec), value.model_tier,
+          value.scope_modules, value.scope_paths, req.builder.rank, req.builder.id]
+      );
+      return res.status(201).json({ ok: true, agent: serializeDefinition(rows[0], { includePersona: true }) });
+    } catch (err) {
+      // agents_definitions_name_uniq. A name collision is the caller's answer,
+      // not a server error — and it is the whole reason PATCH exists.
+      if (err && err.code === '23505') {
+        return res.fail('agent_name_taken', { status: 409, message: `an agent named ${JSON.stringify(req.body.name)} already exists — PATCH it instead of creating a second one` });
+      }
+      log.error({ err }, 'POST /agents failed');
+      if (!res.headersSent) return res.fail('agent_create_failed', 500);
+      return undefined;
+    }
+  });
+
+  // PATCH /agents/:name — edit IN PLACE. One row per name, before and after.
+  //
+  // The patch is merged over the stored row and the WHOLE definition is
+  // re-validated (authoring.mergeForValidation says why), against the EDITOR's
+  // live rank — which re-stamps author_rank downward if a lower-ranked builder
+  // edits, and re-runs the scope wall against that new rank.
+  router.patch('/agents/:name', api.requireBuilder, api.requirePermission('agent.author'), async (req, res) => {
+    const name = String(req.params.name || '');
+    if (!validate.NAME_RE.test(name) || name.length > validate.NAME_MAX) return res.fail('invalid_agent_name', 400);
+    if (refusedServerOwned(req, res)) return undefined;
+    // A rename would make the URL and the row disagree about which agent this
+    // is, and `name` is the identity every other surface keys on.
+    if (Object.prototype.hasOwnProperty.call(req.body || {}, 'name')) {
+      return res.fail('agent_rename_unsupported', { status: 400, message: 'the name is the identity — delete and recreate rather than renaming' });
+    }
+    if (api.validateOrRespond(req, res, writeSchema({ nameRequired: false }), { strict: true })) return undefined;
+    try {
+      const { rows: existing } = await api.pool.query(
+        `SELECT ${COLUMNS}, persona FROM agents_definitions WHERE name = $1`, [name]
+      );
+      if (!existing.length) return res.fail('agent_not_found', 404);
+      const writable = authoring.writableByApi(existing[0]);
+      if (!writable.ok) return res.fail('agent_owned_by_file', { status: 409, message: writable.reason });
+
+      const merged = authoring.mergeForValidation(existing[0], req.body);
+      merged.name = name;
+      const value = validatedOrRejected(merged, req, res);
+      if (!value) return undefined;
+
+      const { rows } = await api.pool.query(
+        `UPDATE agents_definitions SET
+           title = $2, persona = $3, trigger_type = $4, trigger_spec = $5::jsonb,
+           model_tier = $6, scope_modules = $7, scope_paths = $8,
+           author_rank = $9, author_builder_id = $10, updated_at = now()
+         WHERE name = $1 AND source = 'db'
+         RETURNING ${COLUMNS}, persona`,
+        [name, value.title, value.persona, value.trigger_type,
+          JSON.stringify(value.trigger_spec), value.model_tier,
+          value.scope_modules, value.scope_paths, req.builder.rank, req.builder.id]
+      );
+      // `AND source = 'db'` repeats the check above as a STRUCTURAL guard: a row
+      // that turned file-sourced between the read and the write is not
+      // overwritten by the race either. Same shape as agents-sync's own upsert.
+      if (!rows.length) return res.fail('agent_owned_by_file', { status: 409, message: 'this definition became file-owned while the edit was in flight' });
+      return res.json({ ok: true, agent: serializeDefinition(rows[0], { includePersona: true }) });
+    } catch (err) {
+      log.error({ err, name }, 'PATCH /agents/:name failed');
+      if (!res.headersSent) return res.fail('agent_update_failed', 500);
+      return undefined;
+    }
+  });
+
+  // DELETE /agents/:name — only a db-authored definition, and only ever one.
+  //
+  // The LEDGER is untouched: agents_runs.definition_id is ON DELETE SET NULL and
+  // carries a denormalized agent_name, so what this agent spent and did survives
+  // the definition it pointed at (the schema header says why).
+  router.delete('/agents/:name', api.requireBuilder, api.requirePermission('agent.author'), async (req, res) => {
+    const name = String(req.params.name || '');
+    if (!validate.NAME_RE.test(name) || name.length > validate.NAME_MAX) return res.fail('invalid_agent_name', 400);
+    try {
+      const { rows: existing } = await api.pool.query(
+        'SELECT name, source, source_path FROM agents_definitions WHERE name = $1', [name]
+      );
+      if (!existing.length) return res.fail('agent_not_found', 404);
+      const writable = authoring.writableByApi(existing[0]);
+      if (!writable.ok) return res.fail('agent_owned_by_file', { status: 409, message: writable.reason });
+      const { rowCount } = await api.pool.query(
+        "DELETE FROM agents_definitions WHERE name = $1 AND source = 'db'", [name]
+      );
+      if (!rowCount) return res.fail('agent_owned_by_file', { status: 409, message: 'this definition became file-owned while the delete was in flight' });
+      return res.json({ ok: true, deleted: name });
+    } catch (err) {
+      log.error({ err, name }, 'DELETE /agents/:name failed');
+      if (!res.headersSent) return res.fail('agent_delete_failed', 500);
+      return undefined;
+    }
+  });
+
+  // POST /agents/:name/enable — THE OPERATOR ACT.
+  //
+  // This is the one write that works on a FILE-sourced definition, and it is the
+  // whole reason a committed agent can ever run: agents-sync deliberately never
+  // arms anything (its rule 4), and carries an operator's `enabled` forward
+  // untouched on every later deploy. So arming here is durable, and landing a
+  // commit still cannot arm anything.
+  //
+  // Two refusals it cannot talk its way past, both enforced by the schema as
+  // well as here: a flagged definition stays disarmed, and a definition with no
+  // author_rank has no authority to act with.
+  router.post('/agents/:name/enable', api.requireBuilder, api.requirePermission('agent.arm'), async (req, res) => {
+    const name = String(req.params.name || '');
+    if (!validate.NAME_RE.test(name) || name.length > validate.NAME_MAX) return res.fail('invalid_agent_name', 400);
+    try {
+      const { rows: existing } = await api.pool.query(
+        `SELECT ${COLUMNS} FROM agents_definitions WHERE name = $1`, [name]
+      );
+      if (!existing.length) return res.fail('agent_not_found', 404);
+      const row = existing[0];
+      if (row.scope_violation) {
+        return res.fail('agent_scope_flagged', { status: 409, message: `this definition tripped the scope wall and cannot be armed: ${row.scope_violation}` });
+      }
+      if (!row.author_rank) {
+        return res.fail('agent_has_no_author', { status: 409, message: 'this definition carries no author_rank, so it has no authority to act with — authority comes from a live rank, never from the definition (ADR 0016)' });
+      }
+      const { rows } = await api.pool.query(
+        `UPDATE agents_definitions SET enabled = true, updated_at = now()
+          WHERE name = $1 AND scope_violation IS NULL AND author_rank IS NOT NULL
+          RETURNING ${COLUMNS}`,
+        [name]
+      );
+      if (!rows.length) return res.fail('agent_not_armable', { status: 409, message: 'the definition stopped being armable while the request was in flight' });
+      return res.json({ ok: true, agent: serializeDefinition(rows[0]) });
+    } catch (err) {
+      log.error({ err, name }, 'POST /agents/:name/enable failed');
+      if (!res.headersSent) return res.fail('agent_enable_failed', 500);
+      return undefined;
+    }
+  });
+
+  // POST /agents/:name/disable — and THIS is what stops dispatch.
+  //
+  // Two halves, because there are two ways an agent fires. The event dispatch
+  // index is partial (`WHERE enabled`), so an event agent switched off stops
+  // being selected at all; an on-demand agent has no selection step, so gate.js
+  // refuses it at invoke. Off means off on both paths, which is the property
+  // this route exists to give an operator.
+  router.post('/agents/:name/disable', api.requireBuilder, api.requirePermission('agent.arm'), async (req, res) => {
+    const name = String(req.params.name || '');
+    if (!validate.NAME_RE.test(name) || name.length > validate.NAME_MAX) return res.fail('invalid_agent_name', 400);
+    try {
+      const { rows } = await api.pool.query(
+        `UPDATE agents_definitions SET enabled = false, updated_at = now()
+          WHERE name = $1 RETURNING ${COLUMNS}`,
+        [name]
+      );
+      if (!rows.length) return res.fail('agent_not_found', 404);
+      return res.json({ ok: true, agent: serializeDefinition(rows[0]) });
+    } catch (err) {
+      log.error({ err, name }, 'POST /agents/:name/disable failed');
+      if (!res.headersSent) return res.fail('agent_disable_failed', 500);
+      return undefined;
+    }
+  });
+
+  // POST /agents/:name/invoke — fire an on-demand agent. 202, never 200.
+  //
+  // A fire takes 60-120 seconds and costs about a dollar, which is past the edge
+  // proxy's patience — so the ledger row IS the response and the run continues
+  // behind it. Collect the answer from GET /agent-runs/:id.
+  //
+  // SELF-GATED at requireBuilder, deliberately, matching the reads: which agents
+  // exist at all is an operator decision, and a v1 agent is hard-read-only.
+  //
+  // The thing that reasoning does NOT bound is SPEND, so a per-builder ceiling
+  // does (../lib/fire-budget.js). It is a blast radius, not a budget: the real
+  // accounting is agents_runs.cost_usd through the shared LLM cost cache.
+  router.post('/agents/:name/invoke', api.requireBuilder, async (req, res) => {
+    const name = String(req.params.name || '');
+    if (!validate.NAME_RE.test(name) || name.length > validate.NAME_MAX) return res.fail('invalid_agent_name', 400);
+    if (api.validateOrRespond(req, res, { input: { type: 'string', maxLength: 8192 } }, { strict: true })) return undefined;
+
+    // THE SPEND CEILING, before anything is read or written. A fire costs real
+    // money and an async 202 means the caller does not even wait for it, so the
+    // loop this bounds is cheap to write and expensive to run. Per BUILDER, not
+    // per IP — see ../lib/fire-budget.js for why, and for why this is a blast
+    // radius and not an accounting.
+    const budget = fireBudget.check(req.builder.id);
+    if (!budget.ok) {
+      if (budget.retryAfterSeconds > 0) res.set('Retry-After', String(budget.retryAfterSeconds));
+      return res.fail('rate_limited', {
+        status: 429,
+        message: `agent fires are capped at ${fireBudget.limit} per builder per ${Math.round(fireBudget.windowMs / 60000)} minutes — each one spends real money`,
+        details: { scope: 'agent-fire', retry_after_seconds: budget.retryAfterSeconds },
+      });
+    }
+    try {
+      const { rows } = await api.pool.query(
+        `SELECT ${COLUMNS}, persona FROM agents_definitions WHERE name = $1`, [name]
+      );
+      if (!rows.length) return res.fail('agent_not_found', 404);
+      const definition = rows[0];
+      const gate = gateFor(definition);
+      const trigger = { type: 'on-demand', ref: `on-demand:${req.builder.github_login || req.builder.id}` };
+
+      // A REFUSAL IS A LEDGER ROW. spawnAgent writes the no-go and returns
+      // without spawning, so this await is a database round trip, not a model
+      // call — the reason it can stay synchronous while the go path cannot.
+      if (gate.decision !== 'go') {
+        const skipped = await spawnAgent({
+          definition, trigger, gate, requestedByBuilderId: req.builder.id,
+        }, {});
+        return res.fail('agent_refused', {
+          status: 409,
+          message: gate.reason,
+          // The run id is the point: the refusal is ON THE RECORD, and this is
+          // how the caller reads the row that says so.
+          details: { run_id: skipped.runId ? String(skipped.runId) : null },
+        });
+      }
+
+      let captured = null;
+      const { ledgered, done } = fireInBackground({
+        definition,
+        input: req.body && req.body.input ? String(req.body.input) : null,
+        trigger,
+        gate,
+        requestedByBuilderId: req.builder.id,
+      }, {
+        // Wrap the port's runner to keep the reply, which spawnAgent does not
+        // return — it records what a fire DID, not what it said.
+        runSubagentCached: async (args) => {
+          const grade = api.resolveOptional ? api.resolveOptional('grade', null) : null;
+          if (!grade || typeof grade.runSubagentCached !== 'function') {
+            // Let spawnAgent's own grade_port_unavailable path handle it.
+            throw Object.assign(new Error('grade port unavailable'), { code: 'grade_port_unavailable' });
+          }
+          const out = await grade.runSubagentCached(args);
+          captured = out && typeof out.stdout === 'string' ? out.stdout : null;
+          return out;
+        },
+      });
+
+      // The rejection arm is NOT dead code, though spawnAgent's doc-comment says
+      // it never throws. That guarantee covers the FIRE — everything inside its
+      // try — and the work before it (resolving the tier through branding) is
+      // outside. This promise is detached from the request, so an unhandled
+      // rejection there is a process-level crash under Node's default, taking
+      // every other in-flight request with it.
+      done.then((fired) => {
+        if (fired && fired.ok && fired.runId && captured) hold.put(fired.runId, captured);
+      }, (err) => { log.error({ err, name }, 'agent fire rejected'); });
+
+      const runId = await ledgered;
+      if (runId === null) return res.fail('agent_ledger_write_failed', { status: 500, message: 'the fire was refused because it could not be recorded — an unledgered fire is the one thing this table exists to prevent' });
+      return res.status(202).json({
+        ok: true,
+        run_id: String(runId),
+        poll: `/agent-runs/${runId}`,
+        message: 'the agent is running; collect the answer from the poll URL',
+      });
+    } catch (err) {
+      log.error({ err, name }, 'POST /agents/:name/invoke failed');
+      if (!res.headersSent) return res.fail('agent_invoke_failed', 500);
+      return undefined;
+    }
+  });
+
+  // GET /agent-runs/:id — COLLECT THE ANSWER TO A FIRE YOU STARTED.
+  //
+  // OWN RUNS ONLY, enforced in the WHERE clause rather than after the read. The
+  // id is a sequential integer primary key, so without this any authenticated
+  // builder could walk the ledger and read another builder's held answer — text
+  // generated from THEIR free-text question, out of a repo the agent read — plus
+  // the github_login in `trigger_ref`. That is the textbook IDOR, and it is worse
+  // here than the usual shape because the interesting field is model output
+  // derived from someone else's prompt.
+  //
+  // Filtering in SQL, not in JS, is deliberate: a post-read comparison is one
+  // early `return` away from leaking, and it would still have handed the row to
+  // `hold.take()` on the way past.
+  //
+  // A run with a NULL requester (an event-triggered fire — nobody asked for it)
+  // is therefore readable by nobody here, which is correct for a route whose job
+  // is "collect MY answer". An operator's view of the whole ledger is a different
+  // surface with a different gate, and it is not built: when it is, it belongs
+  // behind `agent.arm`, not behind a widening of this route.
+  //
+  // See ../lib/answer-hold.js for why the text is held and not stored.
+  router.get('/agent-runs/:id', api.requireBuilder, async (req, res) => {
+    // parseId RESPONDS on a bad id and returns null, so returning here is the
+    // whole handling. No fallback: a defensive `Number(...)` path that skipped
+    // the respond would leave the request hanging instead of answering 400.
+    const id = api.parseId(req, res, { param: 'id', positiveInt: true });
+    if (id === null) return undefined;
+    try {
+      const { rows } = await api.pool.query(
+        `SELECT id, agent_name, trigger_ref, trigger_type, gate_decision, gate_reason,
+                status, error_code, model, cost_usd, duration_ms, output_ref,
+                created_at, updated_at
+           FROM agents_runs WHERE id = $1 AND requested_by_builder_id = $2`,
+        [id, req.builder.id]
+      );
+      // 404, not 403: a run that is not yours is not a run you get to learn
+      // exists. Distinguishing the two would make the id space enumerable again,
+      // one bit at a time.
+      if (!rows.length) return res.fail('agent_run_not_found', 404);
+      return res.json({ ok: true, run: serializeRun(rows[0], { answer: hold.take(id) }) });
+    } catch (err) {
+      log.error({ err, id }, 'GET /agent-runs/:id failed');
+      if (!res.headersSent) return res.fail('agent_run_read_failed', 500);
+      return undefined;
+    }
+  });
+
   return router;
 };
 
 // Exported for the unit tests, which drive the projection with fabricated rows
 // rather than standing up Postgres.
 module.exports.serializeDefinition = serializeDefinition;
+module.exports.serializeRun = serializeRun;
+// The module-level ceiling, exported so a test can reset it between cases —
+// a singleton otherwise carries one case's spend into the next.
+module.exports.fireBudget = fireBudget;

package/modules/agents/spawn.js

@@ -146,6 +146,18 @@ async function spawnAgent({
   let runId = null;
   try {
     runId = await insertRun(pool, row);
+    // deps.onLedgered — "the row exists; here is its id", fired the moment the
+    // ledger write lands and long before the fire finishes (task 1002493).
+    //
+    // A synchronous caller does not need this; POST /agents/:name/invoke does,
+    // because it answers 202 with the run id while the spawn runs on behind it,
+    // and the alternative was for the route to insert its own row — a second
+    // copy of the ledger contract, which is exactly how two ledgers start
+    // disagreeing. Swallowed on throw: a caller's bookkeeping must never abort a
+    // fire that is already recorded.
+    if (typeof deps.onLedgered === 'function') {
+      try { deps.onLedgered(runId); } catch (_) { /* the caller's problem, not this fire's */ }
+    }
   } 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

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -99,11 +99,27 @@ function createClient(opts = {}) {
       // GET /achievements — rank: any-builder — GET /achievements
       getAchievements: (args) => request("GET", "/achievements", { hasBody: false }, args),
     },
+    "agentRuns": {
+      // GET /agent-runs/{id} — rank: any-builder — GET /agent-runs/:id
+      getAgentRunsId: (args) => request("GET", "/agent-runs/{id}", { hasBody: false }, args),
+    },
     "agents": {
       // GET /agents — rank: any-builder — GET /agents
       getAgents: (args) => request("GET", "/agents", { hasBody: false }, args),
+      // POST /agents — rank: metic+archon — POST /agents
+      postAgents: (args) => request("POST", "/agents", { hasBody: true }, args),
+      // DELETE /agents/{name} — rank: metic+archon — DELETE /agents/:name
+      deleteAgentsName: (args) => request("DELETE", "/agents/{name}", { hasBody: false }, args),
       // GET /agents/{name} — rank: any-builder — GET /agents/:name
       getAgentsName: (args) => request("GET", "/agents/{name}", { hasBody: false }, args),
+      // PATCH /agents/{name} — rank: metic+archon — PATCH /agents/:name
+      patchAgentsName: (args) => request("PATCH", "/agents/{name}", { hasBody: true }, args),
+      // POST /agents/{name}/disable — rank: metic+archon — POST /agents/:name/disable
+      postAgentsNameDisable: (args) => request("POST", "/agents/{name}/disable", { hasBody: true }, args),
+      // POST /agents/{name}/enable — rank: metic+archon — POST /agents/:name/enable
+      postAgentsNameEnable: (args) => request("POST", "/agents/{name}/enable", { hasBody: true }, args),
+      // POST /agents/{name}/invoke — rank: any-builder — POST /agents/:name/invoke
+      postAgentsNameInvoke: (args) => request("POST", "/agents/{name}/invoke", { hasBody: true }, args),
     },
     "analytics": {
       // GET /analytics/builder/{id} — rank: any-builder — GET /analytics/builder/:id

package/modules/government/catalog.js

@@ -180,6 +180,16 @@ const PERMISSIONS = [
   { key: 'backup.manage', system: false, floor: 'metic', guards: 'GET /backup/status, POST /backup/trigger' },
   { key: 'source.clone.local', system: false, floor: 'metic', guards: 'Metic+ local clone / collaborator invite (ADR 0035)' },
   { key: 'box.source.full', system: false, floor: 'metic', guards: 'GET /box/source-access → full (vs starter); boxScopeForRank' },
+  // Agent authoring, split in two because the two acts differ in consequence
+  // (task 1002493). Authoring writes a definition; ARMING is what turns a piece
+  // of text into something that spends money and reads the repo, and it is the
+  // only write that works on a committed, file-sourced definition — agents-sync
+  // deliberately never arms anything, so this atom IS the act that lets a
+  // committed agent run. Separate keys let an instance delegate the first
+  // without the second. Metic by the module.enable analogue: configuring what
+  // the instance runs, not deciding who holds authority.
+  { key: 'agent.author', system: false, floor: 'metic', guards: 'POST /agents, PATCH|DELETE /agents/:name' },
+  { key: 'agent.arm', system: false, floor: 'metic', guards: 'POST /agents/:name/{enable,disable}' },
 
   // ── delegated archon→metic by ADR 0157 (owner decision, 2026-08-05) ───────────
   //

package/modules/government/migrations/government_013_agent_atoms.sql

@@ -0,0 +1,66 @@
+-- government_013_agent_atoms.sql — grant the two new agent-authoring atoms to the
+-- Metic and Archon rank-roles (task 1002493, goal 1000038 Phase 2a).
+--
+-- The agents module's WRITE surface landed in this task: create, edit, delete,
+-- arm, disarm. BV1.R105 says a modules/*/routes gate is a permission atom and
+-- never a rank — tests/government_require_permission.mjs fails the build on a new
+-- `requireRank`, and the two files still spelling it that way are documented
+-- holdouts rather than a pattern to copy. So the routes gate on:
+--
+--   agent.author  — POST /agents, PATCH|DELETE /agents/:name
+--   agent.arm     — POST /agents/:name/{enable,disable}
+--
+-- TWO KEYS, NOT ONE, because the acts differ in consequence. Authoring writes a
+-- definition; ARMING is what turns a piece of text into something that spends
+-- money and reads the repo, and it is the only write that works on a committed,
+-- file-sourced definition — agents-sync deliberately never arms anything (its
+-- rule 4), so `agent.arm` IS the act that lets a committed agent run at all.
+-- Separate keys let an instance delegate the first without the second.
+--
+-- FLOOR `metic` for both, by the `module.enable` analogue: this is configuring
+-- what the instance RUNS, not deciding who holds authority. Two things bound it.
+-- A v1 agent is fixed read-only by plumbing rather than by policy (spawn.js
+-- constraint 3 — the grade port hardcodes `--tools Read`), so holding these
+-- cannot produce a write principal. And a definition authored over HTTP may not
+-- declare a scope reaching any protected surface AT ALL, at any rank
+-- (modules/agents/lib/authoring.js rule 3) — stricter than the validator's own
+-- Metic floor, because a committed definition reaches the registry through a
+-- branch, a grader panel and CI while this one reaches it through a single call.
+--
+-- BRAND-NEW keys: no rank holds them yet, so BOTH rungs the floor implies are
+-- granted here. RANK_SEED is a cumulative superset — floor `metic` means
+-- {metic, archon} — and the drift guard (tests/government_seed.mjs) compares the
+-- UNION of the run-once seed plus every later grant migration against that
+-- floor-derived seed, per rank. Minting the catalog rows WITHOUT this migration
+-- is exactly what that guard caught on this task.
+--
+-- Target table is `government_rank_permissions` with a `rank_key` column — NOT
+-- the pre-rename `governance_role_permissions`/`role_key` the `governance_*`
+-- migrations write to (government_001_rename_from_governance dropped those with
+-- no compatibility shim). Copy government_009_mingle_manage.sql, not a
+-- governance_* file.
+--
+-- Additive only: two new permission keys granted to two ranks; nothing is
+-- revoked. Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- One block PER RANK, in the government_004 shape: the drift guard scans for
+-- `SELECT '<rank>', unnest(ARRAY[…])` literally, so a combined
+-- `unnest(ARRAY['metic','archon']), 'key'` form parses as zero grants and reds it.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'agent.author',
+  'agent.arm'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'agent.author',
+  'agent.arm'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;