@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/agent-invoke.js

@@ -1,689 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/agent-invoke.js — ask an on-demand agent a question, on the record
-// (task 1002491, goal 1000038 Phase 1, criterion `agents-historian-exemplar`).
-//
-// WHY. Phase 1 built four things that only meet each other at runtime: a registry
-// reconciled from files (agents-sync), a pure validator, a spawn seam, and a
-// ledger. Each has its own tests and none of them proves the chain. This is the
-// one caller that runs all four in sequence against real data, so "the framework
-// works" stops being an inference from four green suites.
-//
-// FIVE RULES, each of which is a way this could quietly become a lie:
-//
-//  1. THE REGISTRY IS THE AUTHORITY, NEVER THE FILE. This reads
-//     agents_definitions and nothing under .claude/agents/. A committed file is
-//     an INPUT to the registry (agents-sync owns that edge, and deliberately
-//     never arms anything); reading the file here would hand every committer a
-//     way to invoke a definition the instance never admitted — precisely the
-//     hole rule 2 of agents-sync closes one layer up.
-//
-//  2. A REFUSAL IS A LEDGER ROW. A disabled, flagged or wrong-triggered agent
-//     gets a no-go row with a reason, not a bare exit. Same argument as
-//     autonomy_runs and agents_runs' own no-go invariant: a gate that declines
-//     silently is indistinguishable from a gate that never ran, and "the agent
-//     didn't answer" then has two causes nobody can tell apart.
-//
-//  3. THE CITATION CONTRACT IS ENFORCED, NOT REQUESTED. Every citation is
-//     resolved against the working tree (or the learnings actually supplied)
-//     BEFORE the run is recorded as ok. An answer whose sources do not exist is
-//     recorded as an error and printed as a refusal. Asking a model to cite and
-//     then not checking produces something worse than an uncited answer: an
-//     uncheckable one that looks checked. The check runs INSIDE the spawn, so
-//     the ledger's verdict is the real verdict.
-//
-//     WHAT IT IS NOT: a sandbox. This checks what the agent CLAIMS it read, not
-//     what it could read. The actual capability boundary is elsewhere and is not
-//     touched by this file — grader-subagent.js spawns with `--tools Read` and a
-//     fixed cwd, which is what makes a v1 agent observe-and-report (spawn.js
-//     constraint 3). Do not read a passing citation check as containment.
-//
-//  4. THE ANSWER IS NEVER STORED IN THE LEDGER. `output_ref` is a pointer, by
-//     the schema's own rule — model-generated prose rendered to whoever reads
-//     the ledger would make agents_runs a delivery path for whatever the agent
-//     read. With no --out the answer goes to the caller's terminal and the
-//     pointer is honestly null, rather than a fabricated one.
-//
-//  5. IDENTITY COMES FROM THE LIVE SESSION, never a flag. The caller is resolved
-//     through /me with their own CLI token (ADR 0016). There is no --as: a fire
-//     nobody is attributable for is exactly what the ledger exists to prevent.
-//
-//     THERE IS NO RANK FLOOR ON TOP OF THAT, and that is a decision rather than
-//     an omission. Any authenticated builder may ask an armed agent a question,
-//     matching the read routes' posture (task 1002488): this is a read of the
-//     instance's own record by the people who build it. Two things bound it —
-//     WHICH agents exist at all is an operator decision (`enabled`), and a v1
-//     agent is hard-read-only. What is NOT bounded is spend: a fire costs real
-//     money (~$0.90 for a historian question at the time of writing), and the
-//     only thing standing between a builder and a loop of them is that they
-//     have to type it. THE FLOOR TO ADD, WHEN IT IS ADDED, BELONGS HERE — and
-//     it becomes necessary the moment an agent is either write-capable or
-//     cheap enough to fire from something other than a keyboard.
-//
-// WHERE IT RUNS. Wherever the database is, like agents-sync.js — the registry
-// read and the ledger write are both pool-side. The model call is local, through
-// the `grade` port's runSubagentCached, which is fixed read-only (`--tools Read`)
-// and bills into the shared LLM cost cache. So the agent can open files in the
-// checkout and can change none of them.
-//
-// THE HISTORIAN ARRIVES DISARMED, AND THAT IS A SPLIT, NOT AN OVERSIGHT. Out of
-// the box `agent-invoke historian` refuses with `agent_refused` until an operator
-// enables the row. Two separate things cause that, and the first cannot be argued
-// away:
-//
-//   - STRUCTURAL. agents_definitions_armed_needs_author_chk refuses to arm a row
-//     whose author_rank is NULL, and stampableAuthorRank derives that rank from
-//     the file's last committer resolved against `builders`. On any instance but
-//     the one the core is developed in, the core's committer is not a builder in
-//     that DB — so the rank is NULL and a BUILT-IN row cannot be armed at all.
-//     Fixing that means deciding what authority a core-authored definition
-//     carries, then writing a migration.
-//   - POLICY. agents-sync rule 4 separately refuses to let a commit arm anything
-//     (task 1002490), which is stricter than the original criteria (idea 1000527,
-//     goal 1000038 #6) — those only require a SCOPE-refused definition to import
-//     disarmed.
-//
-// Both are the owner's call, so they are blocker 1000145 and task 1003862 rather
-// than a decision taken here. The refusal names the reason so nobody has to
-// rediscover it.
-//
-// Run:  node scripts/gds/agent-invoke.js <agent> "<question>" [--out <path>] [--json]
-
+// scripts/gds/agent-invoke.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/agent-invoke.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-
-// ---- pure core -------------------------------------------------------------
-
-// THE AGENT HAS `Read` AND NOTHING ELSE — no Glob, no Grep. So without a list of
-// doors it can only guess at filenames, and a guessed filename is the first step
-// toward a fabricated citation. Two kinds of door are supplied.
-//
-// First, the directory MANIFESTS: the actual filenames under each corpus root.
-// This repo names its records to be read as an index — `0016-trust-boundary-
-// server-enforced-permissions.md`, `2026-09-11-c3b-session-rename.md` — so the
-// listing IS a table of contents, at roughly 70 bytes per entry.
-const CORPUS_DIRS = Object.freeze([
-  ['docs/adr', 'architecture decisions — the decision of record on anything one covers'],
-  ['docs/session-logs', 'one file per session: what was attempted, and what actually happened'],
-]);
-
-// Second, the small prose indexes, WHEN THEY ARE THERE AND SMALL ENOUGH TO OPEN.
-// Both conditions bite in practice and both were found by running this for real:
-// docs/repo-map.md and docs/session-log-index.md are generated and gitignored, so
-// a fresh checkout has neither; docs/adr/README.md is a tracked 500KB file that
-// the Read tool refuses outright. A door that does not open is worse than no door
-// — it costs a tool call and teaches the agent that the index list is unreliable.
-// The ADR manifest above is what replaces that README here.
-const INDEX_CANDIDATES = Object.freeze([
-  ['docs/session-log-index.md', 'every session log, newest first'],
-  ['docs/repo-map.md', 'the generated symbol skeleton — where a function lives'],
-  ['docs/file-map.md', 'the repo tree'],
-  ['CLAUDE.md', 'the methodology kernel the project runs on today'],
-]);
-
-// The Read tool refuses a file past its own size ceiling; this sits under it so a
-// listed index is one the agent can actually open.
-const INDEX_MAX_BYTES = 200000;
-// A manifest is a table of contents, not a corpus dump. Past this the listing
-// stops and says so, rather than silently truncating into a prompt the agent
-// reads as complete.
-const MANIFEST_MAX_FILES = 600;
-
-// How many learnings travel in the prompt, and how much of each. They are the one
-// corpus the agent cannot reach with Read — they live in a table — so they are
-// carried inline or not at all. Bounded because this is a paid prompt on every
-// fire, and an unbounded table would make the cost of asking a question depend on
-// how long the instance has been running.
-const LEARNINGS_LIMIT = 120;
-const LEARNING_BODY_MAX = 400;
-const LEARNINGS_BLOCK_MAX = 24000;
-
-// A citation to a learning, which has no path to resolve.
-const LEARNING_REF_RE = /^learning:(\d+)$/;
-
-// One spelling for a learning id on both sides of the check. Ids are bigints, so
-// this strips leading zeros by string rather than through Number, which would
-// lose precision above 2^53 — the table will not get there, but a silent
-// precision cliff in an identity comparison is not worth the two saved
-// characters.
-function normalizeLearningId(id) {
-  const digits = String(id).replace(/^0+(?=\d)/, '');
-  return /^\d+$/.test(digits) ? digits : null;
-}
-
-function isNonEmptyString(v) {
-  return typeof v === 'string' && v.trim().length > 0;
-}
-
-// Strip the human affordances people (and models) append to a path citation: a
-// heading anchor or a line hint. `docs/adr/0043-x.md#4` and `src/bongos/auth.js:12`
-// both name a real file, and refusing them would train the agent to cite less
-// precisely rather than more.
-function citationPath(ref) {
-  return String(ref).split('#')[0].replace(/:\d+(?:-\d+)?$/, '').trim();
-}
-
-// The same tree-escape rule the scope validator applies, and for the same reason:
-// a citation is a path this tool is about to stat, so `..`, an absolute path and a
-// Windows drive letter are all refused before anything touches the filesystem.
-function isInsideTree(p) {
-  if (!isNonEmptyString(p)) return false;
-  if (p.startsWith('/') || p.startsWith('\\')) return false;
-  if (/^[a-zA-Z]:/.test(p)) return false;
-  return !p.split(/[\\/]/).includes('..');
-}
-
-/**
- * Resolve one citation. PURE — `exists` and `learningIds` are supplied, so the
- * whole contract is testable with no filesystem and no database.
- *
- * @returns {{ok: boolean, ref: string, kind: string, reason: string|null}}
- */
-function resolveCitation(ref, { exists = () => false, learningIds = new Set() } = {}) {
-  if (!isNonEmptyString(ref)) {
-    return { ok: false, ref: String(ref), kind: 'unknown', reason: 'a citation must be a non-empty string' };
-  }
-  const trimmed = ref.trim();
-  const learning = LEARNING_REF_RE.exec(trimmed);
-  if (learning) {
-    // Only a learning that was actually PUT IN THIS PROMPT counts. An id the
-    // agent never saw is a guess at a primary key, which is the same failure as
-    // a guessed filename wearing a different prefix.
-    // Compared as a NUMBER, not as the string the model typed: `learning:007`
-    // names the same row as `learning:7`, and refusing the padded spelling would
-    // fail an answer for a formatting choice rather than for a fabrication.
-    return learningIds.has(normalizeLearningId(learning[1]))
-      ? { ok: true, ref: trimmed, kind: 'learning', reason: null }
-      : { ok: false, ref: trimmed, kind: 'learning', reason: 'no learning with that id was supplied to this run' };
-  }
-  const p = citationPath(trimmed);
-  if (!isInsideTree(p)) {
-    return { ok: false, ref: trimmed, kind: 'path', reason: 'a citation must be a repo-relative path inside the tree' };
-  }
-  return exists(p)
-    ? { ok: true, ref: trimmed, kind: 'path', reason: null }
-    : { ok: false, ref: trimmed, kind: 'path', reason: 'no such file in the working tree' };
-}
-
-/**
- * Check a whole answer's citations. Rule 3 made concrete, and STRICT on purpose:
- * one unresolvable citation fails the answer rather than being dropped from it.
- * A part-fabricated bibliography is worse than none — the reader has no way to
- * tell which half was checked, so the real ones lend their credibility to the
- * invented ones.
- */
-function checkCitations(citations, ctx = {}) {
-  const list = Array.isArray(citations) ? citations : [];
-  const resolved = list.map((c) => resolveCitation(
-    c && typeof c === 'object' ? c.ref : c,
-    ctx,
-  ));
-  const invalid = resolved.filter((r) => !r.ok);
-  if (resolved.length === 0) {
-    return { ok: false, code: 'agent_answer_uncited', resolved, invalid, reason: 'the answer carried no citations' };
-  }
-  if (invalid.length > 0) {
-    return {
-      ok: false,
-      code: 'agent_citation_unresolvable',
-      resolved,
-      invalid,
-      reason: invalid.map((r) => `${r.ref} (${r.reason})`).join('; '),
-    };
-  }
-  return { ok: true, code: null, resolved, invalid, reason: null };
-}
-
-// The runner hands back the `claude -p --output-format json` ENVELOPE, not the
-// assistant's reply: `{ type, result: "<what the agent actually said>",
-// total_cost_usd, ... }`. Unwrap it first, or the JSON extractor below happily
-// parses the envelope — which is a perfectly good object with no `answer` in it,
-// so a working run reads as an unparseable one. That is exactly how this failed
-// the first time it met a real model.
-//
-// Guarded on the absence of `answer` so a reply that IS the answer and happens to
-// carry a `result` key is not mistaken for an envelope.
-function unwrapEnvelope(raw) {
-  const text = typeof raw === 'string' ? raw : '';
-  try {
-    const env = JSON.parse(text);
-    if (env && typeof env === 'object' && !Array.isArray(env)
-      && typeof env.result === 'string' && !('answer' in env)) return env.result;
-  } catch (_) { /* not an envelope — the reply is already the reply */ }
-  return text;
-}
-
-// Pull the one JSON object out of a model reply. Deliberately local rather than
-// borrowed from the grader: this is ten lines, and requiring the grading module
-// for them would put a module→module-shaped dependency in the pure half of a
-// script whose whole point is that its decisions are testable in isolation.
-function extractJsonObject(raw) {
-  const text = typeof raw === 'string' ? raw : '';
-  // EVERY fenced block, then the whole text. A single non-greedy match would take
-  // the first fence, which is wrong the moment the reply opens with a fenced
-  // example or a snippet of the file it read — and the whole-text fallback is
-  // wrong whenever the answer's own markdown contains braces.
-  const fenced = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)].map((m) => m[1]);
-  const candidates = [...fenced, text].filter(Boolean);
-  const found = [];
-  for (const c of candidates) {
-    const start = c.indexOf('{');
-    const end = c.lastIndexOf('}');
-    if (start < 0 || end <= start) continue;
-    try {
-      const parsed = JSON.parse(c.slice(start, end + 1));
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) found.push(parsed);
-    } catch (_) { /* try the next candidate */ }
-  }
-  // The ANSWER-shaped object wins over merely the first one. A reply that quotes a
-  // JSON snippet out of a file it read — entirely normal for an agent whose corpus
-  // includes config and manifests — would otherwise hand back the quotation.
-  return found.find((o) => typeof o.answer === 'string') || found[0] || null;
-}
-
-/**
- * Model reply → the answer shape, or null. Never throws.
- */
-function parseAnswer(raw) {
-  const obj = extractJsonObject(unwrapEnvelope(raw));
-  if (!obj) return null;
-  if (!isNonEmptyString(obj.answer)) return null;
-  const citations = Array.isArray(obj.citations) ? obj.citations : [];
-  return {
-    answer: obj.answer.trim(),
-    citations: citations
-      .map((c) => (typeof c === 'string' ? { ref: c, supports: null } : c))
-      .filter((c) => c && typeof c === 'object')
-      .map((c) => ({ ref: isNonEmptyString(c.ref) ? c.ref.trim() : '', supports: isNonEmptyString(c.supports) ? c.supports.trim() : null })),
-    confidence: ['high', 'medium', 'low'].includes(obj.confidence) ? obj.confidence : null,
-  };
-}
-
-// The learnings block, bounded. Returns the prompt text and the id set the
-// citation check will accept — the two must be built together, or the agent can
-// be blamed for citing something it was shown.
-function renderLearnings(rows) {
-  const ids = new Set();
-  const lines = [];
-  let budget = LEARNINGS_BLOCK_MAX;
-  for (const r of Array.isArray(rows) ? rows : []) {
-    const id = normalizeLearningId(r && r.id);
-    if (id === null) continue;
-    const body = String((r && r.body_md) || '').replace(/\s+/g, ' ').trim().slice(0, LEARNING_BODY_MAX);
-    const line = `- learning:${id} — ${String((r && r.title) || '(untitled)').trim()}${body ? `: ${body}` : ''}`;
-    if (line.length > budget) break;
-    budget -= line.length;
-    ids.add(id);
-    lines.push(line);
-  }
-  return { text: lines.join('\n'), ids };
-}
-
-/**
- * The demand half of the prompt: everything that is true of THIS invocation and
- * nothing that is true of the agent. The persona is the other half, and
- * spawn.composePrompt is what joins them — see rule 1 there.
- *
- * PURE: indexes and learnings are passed in.
- */
-function buildDemand({ question, indexes = [], manifests = [], learnings = { text: '', ids: new Set() } }) {
-  const parts = [];
-  parts.push('---');
-  parts.push('## You are answering one question, and every claim must be cited.');
-  parts.push('');
-  parts.push('Your working directory is the repository root. You have exactly one tool:');
-  parts.push('`Read`. There is no search — every door is listed below, and everything not');
-  parts.push('listed you reach by following a link out of something that is.');
-  for (const m of manifests) {
-    parts.push('');
-    parts.push(`### \`${m.dir}/\` — ${m.why}`);
-    parts.push(`${m.total} file(s)${m.truncated ? `, of which the first ${m.files.length} are listed` : ''}. Read one by its full path, e.g. \`${m.dir}/${m.files[0] || 'name.md'}\`.`);
-    parts.push('');
-    parts.push('```');
-    parts.push(m.files.join('\n'));
-    parts.push('```');
-  }
-  if (indexes.length > 0) {
-    parts.push('');
-    parts.push('### Other indexes present in this checkout');
-    for (const [p, why] of indexes) parts.push(`- \`${p}\` — ${why}`);
-  }
-  if (learnings.text) {
-    parts.push('');
-    parts.push('### Learnings');
-    parts.push('These live in a table, not a file, so they are reproduced here in full. Cite one');
-    parts.push('as `learning:<id>`. They are the only citations that are not paths.');
-    parts.push('');
-    parts.push(learnings.text);
-  }
-  parts.push('');
-  parts.push('### Rules');
-  parts.push('1. Read before you answer. Do not answer from memory of this codebase.');
-  parts.push('2. Every substantive claim carries a citation: a repo-relative path to a file');
-  parts.push('   you actually opened, or a `learning:<id>` from the block above.');
-  parts.push('3. Never cite something you did not open. **Every citation is checked against');
-  parts.push('   the working tree before this answer is accepted, and one that does not');
-  parts.push('   resolve fails the whole run** — a half-invented bibliography is worse than');
-  parts.push('   no answer, because the reader cannot tell which half was real.');
-  parts.push('4. If the record does not answer the question, say so and cite what you DID');
-  parts.push('   read. A cited "the record is silent" is a correct answer.');
-  parts.push('');
-  parts.push('### Question');
-  parts.push('');
-  parts.push(String(question || '').trim());
-  parts.push('');
-  parts.push('### Reply with exactly one JSON object and nothing else');
-  parts.push('');
-  parts.push('```json');
-  parts.push('{');
-  parts.push('  "answer": "<markdown — the answer itself>",');
-  parts.push('  "citations": [{ "ref": "docs/adr/0016-trust-boundary-server-enforced-permissions.md", "supports": "<what this source establishes>" }],');
-  parts.push('  "confidence": "high" | "medium" | "low"');
-  parts.push('}');
-  parts.push('```');
-  return parts.join('\n');
-}
-
-/**
- * The doors, resolved against a real checkout. PURE over its two injected
- * readers, so a test can describe a tree without building one.
- *
- * @param {object} io
- * @param {(dir: string) => string[]} io.listDir   markdown filenames in a corpus dir ([] if absent)
- * @param {(p: string) => number} io.fileSize      bytes, or -1 when the file is not there
- */
-function buildCorpus({ listDir, fileSize }) {
-  const manifests = [];
-  for (const [dir, why] of CORPUS_DIRS) {
-    const all = listDir(dir);
-    if (!all || all.length === 0) continue;
-    const files = all.slice(0, MANIFEST_MAX_FILES);
-    manifests.push({ dir, why, files, total: all.length, truncated: all.length > files.length });
-  }
-  const indexes = INDEX_CANDIDATES.filter(([p]) => {
-    const size = fileSize(p);
-    return size >= 0 && size <= INDEX_MAX_BYTES;
-  });
-  return { manifests, indexes };
-}
-
-function defaultListDir(dir) {
-  try {
-    return fs.readdirSync(path.join(REPO_ROOT, dir)).filter((f) => f.endsWith('.md')).sort();
-  } catch (_) { return []; }
-}
-
-function defaultFileSize(p) {
-  try { return fs.statSync(path.join(REPO_ROOT, p)).size; } catch (_) { return -1; }
-}
-
-/**
- * argv -> what the facade needs, or an error. PURE, because the alternative is a
- * command line nothing tests: the question is a FREE-FORM positional that must
- * survive being typed unquoted, and `--out`'s value must not be swallowed into
- * it.
- *
- * @returns {{name, question, outArg, asJson, error: (string|null)}}
- */
-function parseArgv(argv = []) {
-  const args = argv.map(String);
-  const asJson = args.includes('--json');
-  const outIdx = args.indexOf('--out');
-  const outArg = outIdx >= 0 ? (args[outIdx + 1] ?? null) : null;
-  const bad = { name: null, question: '', outArg, asJson };
-  if (outIdx >= 0 && (outArg === null || outArg.startsWith('--'))) {
-    return { ...bad, outArg: null, error: '--out needs a path.' };
-  }
-  const positional = args.filter((a, i) => !a.startsWith('--') && !(outIdx >= 0 && i === outIdx + 1));
-  const [name, ...rest] = positional;
-  // Everything after the name IS the question, rejoined — so an unquoted
-  // sentence works the way anyone typing it would expect.
-  const question = rest.join(' ').trim();
-  if (!name || !question) return { ...bad, error: 'usage' };
-  return { name, question, outArg, asJson, error: null };
-}
-
-// THE GATE lives in the module, not here: the same question is asked by
-// POST /agents/:name/invoke on the other side of the trust boundary, and a gate
-// with two implementations has two behaviours the day one is edited. Required
-// directly from a script the way agents-sync requires the validator.
-const { gateFor } = require('../../modules/agents/lib/gate.js');
-
-// ---- the chain -------------------------------------------------------------
-
-const DEFINITION_COLUMNS = `
-  id, name, title, persona, trigger_type, trigger_spec, model_tier,
-  scope_modules, scope_paths, scope_violation, source, provenance,
-  author_rank, source_path, enabled
-`;
-
-async function loadDefinition(pool, name) {
-  const { rows } = await pool.query(
-    `SELECT ${DEFINITION_COLUMNS} FROM agents_definitions WHERE name = $1`,
-    [name],
-  );
-  return rows[0] || null;
-}
-
-// Best-effort: an instance with no learnings, or a learnings table this caller
-// cannot read, gets a smaller corpus and a warning. Failing the invocation would
-// trade a complete answer for no answer, and the citation contract still holds
-// over whatever WAS supplied — an id that never arrived is refused by the same
-// check either way.
-async function loadLearnings(pool, { warn = () => {} } = {}) {
-  try {
-    const { rows } = await pool.query(
-      'SELECT id, title, body_md FROM learnings ORDER BY created_at DESC LIMIT $1',
-      [LEARNINGS_LIMIT],
-    );
-    return rows;
-  } catch (err) {
-    warn(`learnings unavailable (${(err && err.message) || err}) — answering from the file corpus alone`);
-    return [];
-  }
-}
-
-/**
- * Registry -> validate -> spawn -> ledger, once. Every edge is injectable, so the
- * whole chain runs in tests against a fake pool and a fake runner.
- *
- * @returns {{ok: boolean, code: string|null, runId: (number|null), answer: object|null, ...}}
- */
-async function invokeAgent({ name, question, requestedByBuilderId = null, requestedByLogin = null, outputRef = null }, deps = {}) {
-  const pool = deps.pool;
-  const exists = deps.exists || ((p) => fs.existsSync(path.join(REPO_ROOT, p)));
-  const corpus = deps.corpus || buildCorpus({
-    listDir: deps.listDir || defaultListDir,
-    fileSize: deps.fileSize || defaultFileSize,
-  });
-  const spawn = deps.spawnAgent || require('../../modules/agents/spawn.js').spawnAgent;
-  const warn = deps.warn || (() => {});
-
-  const row = await loadDefinition(pool, name);
-  // The one refusal that writes NO ledger row: agents_runs.agent_name is NOT NULL
-  // and its whole purpose is to record what a KNOWN agent did. A row for a name
-  // that was never a definition would be a log line pretending to be a ledger
-  // entry, and would let a typo loop inflate the table.
-  if (!row) return { ok: false, code: 'agent_not_found', runId: null, answer: null, row: null };
-
-  const gate = gateFor(row);
-  // task 1002489's ledger contract: a no-go still inserts (status 'skipped', no
-  // cost, no output). spawnAgent does that and returns without spawning.
-  if (gate.decision !== 'go') {
-    const skipped = await spawn({
-      definition: row,
-      trigger: { type: 'on-demand', ref: requestedByLogin ? `on-demand:${requestedByLogin}` : null },
-      gate,
-      requestedByBuilderId,
-    }, { pool, ...(deps.spawnDeps || {}) });
-    return { ok: false, code: 'agent_refused', reason: gate.reason, runId: skipped.runId, answer: null, row };
-  }
-
-  const learnings = renderLearnings(await loadLearnings(pool, { warn }));
-  const demand = buildDemand({ question, indexes: corpus.indexes, manifests: corpus.manifests, learnings });
-
-  // THE CITATION CHECK RUNS INSIDE THE SPAWN (rule 3). Wrapping the runner rather
-  // than inspecting the result afterwards is what makes the ledger honest: the
-  // verdict spawnAgent records IS the checked verdict, so an uncited answer is
-  // stored as an error with its cost, never as an `ok` run someone later has to
-  // re-judge from prose that was never kept.
-  let verdict = null;
-  const runner = async (args) => {
-    const res = await (deps.runSubagentCached || realRunner())(args);
-    const parsed = parseAnswer(res && res.stdout);
-    if (!parsed) {
-      verdict = { ok: false, code: 'agent_answer_unparsed', answer: null, citations: null, raw: (res && res.stdout) || '' };
-      return { ...res, ok: false, error_code: 'agent_answer_unparsed' };
-    }
-    const cites = checkCitations(parsed.citations, { exists, learningIds: learnings.ids });
-    verdict = { ok: cites.ok, code: cites.code, answer: parsed, citations: cites, raw: (res && res.stdout) || '' };
-    if (!cites.ok) return { ...res, ok: false, error_code: cites.code };
-    return res;
-  };
-
-  const fired = await spawn({
-    definition: row,
-    input: demand,
-    trigger: { type: 'on-demand', ref: requestedByLogin ? `on-demand:${requestedByLogin}` : null },
-    gate,
-    requestedByBuilderId,
-  }, { pool, runSubagentCached: runner, outputRef, opts: { cwd: REPO_ROOT }, ...(deps.spawnDeps || {}) });
-
-  if (!fired.ok) {
-    return {
-      ok: false,
-      // A spawn that never reached the model (no grade port, a ledger write that
-      // failed) has its own code; one that reached it and came back uncheckable
-      // carries the verdict's.
-      code: (verdict && verdict.code) || fired.error_code || 'agent_run_failed',
-      reason: verdict && verdict.citations ? verdict.citations.reason : (fired.error || null),
-      runId: fired.runId,
-      answer: verdict ? verdict.answer : null,
-      cost_usd: fired.cost_usd ?? null,
-      row,
-    };
-  }
-  return {
-    ok: true,
-    code: null,
-    runId: fired.runId,
-    answer: verdict.answer,
-    citations: verdict.citations.resolved,
-    model: fired.model,
-    cost_usd: fired.cost_usd ?? null,
-    duration_ms: fired.duration_ms ?? null,
-    row,
-  };
-}
-
-// Resolved lazily so the pure half of this file — and every test over it — never
-// pulls in the grading module or its subprocess machinery.
-function realRunner() {
-  const grader = require('../../modules/grading/grader.js');
-  return grader.runSubagentCached;
-}
-
-module.exports = {
-  invokeAgent,
-  parseArgv,
-  gateFor,
-  buildCorpus,
-  buildDemand,
-  parseAnswer,
-  resolveCitation,
-  checkCitations,
-  renderLearnings,
-  citationPath,
-  extractJsonObject,
-  unwrapEnvelope,
-  INDEX_CANDIDATES,
-  CORPUS_DIRS,
-  INDEX_MAX_BYTES,
-  MANIFEST_MAX_FILES,
-  LEARNINGS_LIMIT,
-};
-
-// ---- facade ----------------------------------------------------------------
-
-function usage() {
-  console.error('Usage: node scripts/gds/agent-invoke.js <agent> "<question>" [--out <path>] [--json]');
-  console.error('  <agent>      the agent name as it appears in the registry (GET /api/bongos/agents)');
-  console.error('  --out <path> write the answer to a file and record it as the run\'s output_ref');
-  console.error('  --json       print the whole result as JSON instead of prose');
-}
-
-async function main() {
-  const cliArgs = parseArgv(process.argv.slice(2));
-  if (cliArgs.error === 'usage') { usage(); return 2; }
-  if (cliArgs.error) { console.error(`agent-invoke: ${cliArgs.error}`); return 2; }
-  const { name, question, outArg, asJson } = cliArgs;
-
-  // Rule 5. requireSession exits with its own guidance when there is no session.
-  const cli = require('./cli-lib');
-  await cli.requireSession();
-  const me = await cli.apiCall('GET', '/api/bongos/me');
-  const builder = (me && me.data && me.data.builder) || null;
-  if (!builder || !builder.id) {
-    console.error('agent-invoke: could not resolve who you are from /me — a fire has to be attributable.');
-    return 1;
-  }
-
-  const { pool } = require('../../src/bongos/pool');
-  const outputRef = outArg
-    ? path.relative(REPO_ROOT, path.resolve(process.cwd(), outArg)).split(path.sep).join('/')
-    : null;
-
-  const result = await invokeAgent({
-    name,
-    question,
-    requestedByBuilderId: builder.id,
-    requestedByLogin: builder.github_login || null,
-    outputRef,
-  }, { warn: (m) => console.error(`agent-invoke: ${m}`) });
-
-  if (result.ok && outArg) {
-    fs.writeFileSync(path.resolve(process.cwd(), outArg), `${result.answer.answer}\n`, 'utf8');
-  }
-
-  if (asJson) {
-    console.log(JSON.stringify(result.ok
-      ? { ok: true, run_id: result.runId, model: result.model, cost_usd: result.cost_usd, answer: result.answer }
-      : { ok: false, code: result.code, reason: result.reason || null, run_id: result.runId }, null, 2));
-    return result.ok ? 0 : 1;
-  }
-
-  if (!result.ok) {
-    console.error(`\n  ${name}: ${result.code}`);
-    if (result.reason) console.error(`  ${result.reason}`);
-    if (result.code === 'agent_not_found') {
-      console.error('  Nothing by that name is in the registry. `node scripts/gds/api.js GET /api/bongos/agents` lists it.');
-    }
-    if (result.code === 'agent_refused' && /not enabled/.test(result.reason || '')) {
-      console.error('  Definitions land in the registry DISABLED by design: agents-sync reconciles');
-      console.error('  .claude/agents/*.md at deploy and never arms one, because a committed file');
-      console.error('  cannot grant authority (task 1002490 rule 4). Arming is an operator act.');
-    }
-    if (result.runId) console.error(`  Recorded as agents_runs #${result.runId}.`);
-    return 1;
-  }
-
-  console.log(`\n${result.answer.answer}\n`);
-  console.log('Sources:');
-  for (const c of result.answer.citations) {
-    console.log(`  - ${c.ref}${c.supports ? ` — ${c.supports}` : ''}`);
-  }
-  const cost = typeof result.cost_usd === 'number' ? `$${result.cost_usd.toFixed(4)}` : 'uncosted';
-  console.log(`\n  ${name} · ${result.model} · ${cost} · confidence ${result.answer.confidence || 'unstated'} · agents_runs #${result.runId}`);
-  if (outArg) console.log(`  answer written to ${outArg}`);
-  return 0;
-}
-
-if (require.main === module) {
-  main().then((code) => { process.exitCode = code; }).catch((err) => {
-    console.error(`agent-invoke: ${(err && err.message) || err}`);
-    process.exitCode = 1;
-  });
-}
+require('../bongos/forwarder.js').forward(module, 'agent-invoke.js');