@bongos/core 1.19.705 → 1.19.707

package/scripts/gds/agent-invoke.js

@@ -0,0 +1,711 @@
+#!/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]
+
+'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. Decides whether this definition may be invoked on demand, and gives
+ * the reason in the same breath — rule 2 needs the reason as much as the verdict,
+ * because the reason is the whole content of the ledger row a refusal writes.
+ *
+ * PURE: takes the registry row, returns `{ decision, reason }`.
+ */
+function gateFor(row) {
+  if (!row) return { decision: 'no-go', reason: 'no such agent in the registry' };
+  if (row.trigger_type !== 'on-demand') {
+    return {
+      decision: 'no-go',
+      reason: `trigger_type is '${row.trigger_type}', not 'on-demand' — this agent is dispatched by an event, not asked a question`,
+    };
+  }
+  // Checked before `enabled` even though the schema's flagged_not_armed CHECK
+  // makes a flagged row necessarily disabled: the two states have the same
+  // verdict and completely different fixes, and the reason is what the caller
+  // acts on.
+  if (isNonEmptyString(row.scope_violation)) {
+    return { decision: 'no-go', reason: `disarmed by the scope wall: ${row.scope_violation}` };
+  }
+  if (row.enabled !== true) {
+    return { decision: 'no-go', reason: 'the definition is present in the registry but not enabled' };
+  }
+  return { decision: 'go', reason: null };
+}
+
+// ---- 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/gds/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/gds/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/gds/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;
+  });
+}