@bongos/core 1.19.705 → 1.19.707

package/tests/agent_invoke.mjs

@@ -0,0 +1,566 @@
+// tests/agent_invoke.mjs — the on-demand invocation chain (task 1002491, goal
+// 1000038 Phase 1, criterion `agents-historian-exemplar`).
+//
+// Gates the claim the criterion actually makes: that registry -> validate ->
+// spawn -> ledger runs end to end and yields a CITED answer. Everything is
+// dependency-injected — a fake pool, a fake runner, a fake filesystem — so the
+// whole chain runs with no database, no subprocess and no model call. What is
+// proven here is the DECISIONS: the gate, the citation contract, and what the
+// ledger ends up saying about each outcome.
+//
+// The one thing a fake cannot prove is that a real model returns a citable
+// answer. That was verified separately against the live `claude` CLI and the
+// real historian definition; see the task's ship notes.
+//
+// Run:  node tests/agent_invoke.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const invoke = require('../scripts/gds/agent-invoke.js');
+const { spawnAgent, composePrompt } = require('../modules/agents/spawn.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const MODELS = { main: 'opus', subagentDefault: 'opus', subagentRoutine: 'haiku' };
+
+const HISTORIAN = Object.freeze({
+  id: 7,
+  name: 'historian',
+  title: 'Historian',
+  persona: 'You are the historian of this repository.',
+  trigger_type: 'on-demand',
+  trigger_spec: {},
+  model_tier: 'default',
+  scope_modules: [],
+  scope_paths: [],
+  scope_violation: null,
+  source: 'file',
+  provenance: 'built-in',
+  author_rank: 'archon',
+  source_path: '.claude/agents/historian.md',
+  enabled: true,
+});
+
+// A tree where exactly these paths exist.
+const TREE = new Set(['docs/adr/README.md', 'docs/adr/0016-trust-boundary.md', 'CLAUDE.md']);
+const EXISTS = (p) => TREE.has(p);
+
+// A pool that answers the three reads this chain makes and records every write,
+// so the LEDGER can be asserted on directly (same idiom as tests/agents_spawn.mjs).
+function fakePool({ definition = HISTORIAN, learnings = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/FROM agents_definitions/.test(sql)) {
+        return { rows: definition && definition.name === params[0] ? [definition] : [] };
+      }
+      if (/FROM learnings/.test(sql)) return { rows: learnings };
+      if (/^INSERT INTO agents_runs/.test(sql)) return { rows: [{ id: 99 }] };
+      return { rows: [] };
+    },
+    inserted() {
+      const c = calls.find((x) => /^INSERT INTO agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = c.sql.match(/\(([^)]+)\) VALUES/)[1].split(',').map((s) => s.trim());
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i]]));
+    },
+    updated() {
+      const c = calls.find((x) => /^UPDATE agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = [...c.sql.matchAll(/(\w+) = \$\d+/g)].map((m) => m[1]).filter((k) => k !== 'updated_at');
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i + 1]]));
+    },
+  };
+}
+
+// A runner that replies with whatever the test wants, in the envelope shape
+// runSubagent returns.
+function replyWith(payload, { cost = 0.0123 } = {}) {
+  const seen = {};
+  const run = async ({ prompt, opts }) => {
+    seen.prompt = prompt;
+    seen.opts = opts;
+    return { stdout: typeof payload === 'string' ? payload : JSON.stringify(payload), cost_usd: cost, exit_code: 0 };
+  };
+  run.seen = seen;
+  return run;
+}
+
+const GOOD_ANSWER = {
+  answer: 'The trust boundary is server-enforced.',
+  citations: [{ ref: 'docs/adr/0016-trust-boundary.md', supports: 'the decision of record' }],
+  confidence: 'high',
+};
+
+async function run(overrides = {}, deps = {}) {
+  const pool = deps.pool || fakePool();
+  const runner = deps.runSubagentCached || replyWith(GOOD_ANSWER);
+  const result = await invoke.invokeAgent({
+    name: 'historian', question: 'why is the trust boundary server-side?',
+    requestedByBuilderId: 1000025, requestedByLogin: 'a-builder',
+    ...overrides,
+  }, {
+    pool,
+    exists: EXISTS,
+    corpus: { manifests: [{ dir: 'docs/adr', why: 'decisions of record', files: ['0016-trust-boundary.md'], total: 1, truncated: false }], indexes: [['CLAUDE.md', 'the kernel']] },
+    runSubagentCached: runner,
+    spawnDeps: { brandingModels: MODELS, now: () => 1000 },
+    ...deps,
+  });
+  return { result, pool, runner };
+}
+
+// --- the citation contract (rule 3) -----------------------------------------
+
+await test('a citation resolves only against a file that is really there', () => {
+  assert.equal(invoke.resolveCitation('docs/adr/README.md', { exists: EXISTS }).ok, true);
+  const missing = invoke.resolveCitation('docs/adr/0999-invented.md', { exists: EXISTS });
+  assert.equal(missing.ok, false);
+  assert.match(missing.reason, /no such file/);
+});
+
+await test('an anchor or a line hint is a more precise citation, not an invalid one', () => {
+  assert.equal(invoke.resolveCitation('docs/adr/0016-trust-boundary.md#4', { exists: EXISTS }).ok, true);
+  assert.equal(invoke.resolveCitation('CLAUDE.md:12', { exists: EXISTS }).ok, true);
+  assert.equal(invoke.resolveCitation('CLAUDE.md:12-40', { exists: EXISTS }).ok, true);
+  assert.equal(invoke.citationPath('docs/adr/0016-trust-boundary.md#4'), 'docs/adr/0016-trust-boundary.md');
+});
+
+await test('a citation cannot escape the tree, and is refused before anything is stat-ed', () => {
+  const probes = ['../../../etc/passwd', '/etc/passwd', 'C:\\Windows\\win.ini', 'docs/../../secrets.md'];
+  for (const p of probes) {
+    const r = invoke.resolveCitation(p, { exists: () => true }); // exists says yes to everything
+    assert.equal(r.ok, false, `${p} must be refused even when the matcher would admit it`);
+    assert.match(r.reason, /inside the tree/);
+  }
+});
+
+await test('a learning citation counts only when that learning was actually supplied', () => {
+  const ids = new Set(['41']);
+  assert.equal(invoke.resolveCitation('learning:41', { learningIds: ids }).ok, true);
+  const guessed = invoke.resolveCitation('learning:42', { learningIds: ids });
+  assert.equal(guessed.ok, false);
+  assert.match(guessed.reason, /was supplied/);
+});
+
+await test('no citations at all is uncited, not merely thin', () => {
+  const v = invoke.checkCitations([], { exists: EXISTS });
+  assert.equal(v.ok, false);
+  assert.equal(v.code, 'agent_answer_uncited');
+});
+
+await test('ONE unresolvable citation fails the whole answer — a half-real bibliography is worse than none', () => {
+  const v = invoke.checkCitations([
+    { ref: 'docs/adr/README.md' },
+    { ref: 'docs/adr/0999-invented.md' },
+  ], { exists: EXISTS });
+  assert.equal(v.ok, false);
+  assert.equal(v.code, 'agent_citation_unresolvable');
+  assert.equal(v.invalid.length, 1);
+  assert.match(v.reason, /0999-invented/);
+});
+
+// --- parsing the reply ------------------------------------------------------
+
+await test('the answer is read out of a fenced block, a bare object, or prose around one', () => {
+  const body = JSON.stringify(GOOD_ANSWER);
+  for (const raw of [body, `\`\`\`json\n${body}\n\`\`\``, `Here you go:\n\n${body}\n\nHope that helps.`]) {
+    const a = invoke.parseAnswer(raw);
+    assert.ok(a, 'parsed');
+    assert.equal(a.citations[0].ref, 'docs/adr/0016-trust-boundary.md');
+    assert.equal(a.confidence, 'high');
+  }
+});
+
+await test('the reply is read out of the `claude -p` ENVELOPE, not mistaken for it', () => {
+  // The runner returns { type, result: "<the reply>", total_cost_usd, ... }. That
+  // envelope is itself a valid JSON object with no `answer` in it, so parsing it
+  // directly turns a good run into an unparseable one — which is precisely how
+  // this failed against the first real model call.
+  const envelope = JSON.stringify({
+    type: 'result', total_cost_usd: 1.08, result: `\`\`\`json\n${JSON.stringify(GOOD_ANSWER)}\n\`\`\``,
+  });
+  const a = invoke.parseAnswer(envelope);
+  assert.ok(a, 'the answer is inside env.result');
+  assert.equal(a.citations[0].ref, 'docs/adr/0016-trust-boundary.md');
+  // ...and a reply that IS the answer is never mistaken for an envelope, even if
+  // it happens to carry a `result` key of its own.
+  const direct = invoke.parseAnswer(JSON.stringify({ ...GOOD_ANSWER, result: 'a field of my own' }));
+  assert.equal(direct.answer, GOOD_ANSWER.answer);
+  assert.equal(invoke.unwrapEnvelope('not json at all'), 'not json at all');
+});
+
+await test('a quoted JSON snippet in the answer does not get mistaken for the answer', () => {
+  // An agent whose corpus includes manifests and config quotes JSON all the time.
+  const reply = [
+    'I found this in the manifest:',
+    '```json',
+    '{ "key": "agents", "default": false }',
+    '```',
+    'and here is my answer:',
+    '```json',
+    JSON.stringify(GOOD_ANSWER),
+    '```',
+  ].join('\n');
+  const a = invoke.parseAnswer(reply);
+  assert.ok(a, 'the answer-shaped object wins');
+  assert.equal(a.answer, GOOD_ANSWER.answer);
+});
+
+await test('a bare-string citation list is accepted — the shape is a convenience, the ref is the contract', () => {
+  const a = invoke.parseAnswer(JSON.stringify({ answer: 'x', citations: ['CLAUDE.md'] }));
+  assert.deepEqual(a.citations, [{ ref: 'CLAUDE.md', supports: null }]);
+});
+
+await test('a reply with no answer, or no JSON at all, parses to null rather than throwing', () => {
+  assert.equal(invoke.parseAnswer('I had a think about it and the answer is probably yes.'), null);
+  assert.equal(invoke.parseAnswer(JSON.stringify({ citations: ['CLAUDE.md'] })), null);
+  assert.equal(invoke.parseAnswer(JSON.stringify({ answer: '   ' })), null);
+  assert.equal(invoke.parseAnswer(null), null);
+  assert.equal(invoke.parseAnswer('{ not json'), null);
+});
+
+await test('an unrecognised confidence is dropped, never echoed back as though it were a grade', () => {
+  const a = invoke.parseAnswer(JSON.stringify({ answer: 'x', citations: ['CLAUDE.md'], confidence: 'certain' }));
+  assert.equal(a.confidence, null);
+});
+
+// --- the command line -------------------------------------------------------
+
+await test('an unquoted question is rejoined, not truncated at the first space', () => {
+  const a = invoke.parseArgv(['historian', 'why', 'is', 'the', 'boundary', 'server-side?']);
+  assert.equal(a.error, null);
+  assert.equal(a.name, 'historian');
+  assert.equal(a.question, 'why is the boundary server-side?');
+});
+
+await test('--out takes the next argument out of the question, and --json is not a word of it', () => {
+  const a = invoke.parseArgv(['--json', 'historian', 'why', '--out', 'answer.md', 'not', 'lost']);
+  assert.equal(a.asJson, true);
+  assert.equal(a.outArg, 'answer.md');
+  assert.equal(a.question, 'why not lost');
+});
+
+await test('a bare --out is refused rather than eating the next flag as a filename', () => {
+  assert.equal(invoke.parseArgv(['historian', 'q', '--out']).error, '--out needs a path.');
+  assert.equal(invoke.parseArgv(['historian', 'q', '--out', '--json']).error, '--out needs a path.');
+});
+
+await test('a missing name or a missing question prints usage', () => {
+  assert.equal(invoke.parseArgv([]).error, 'usage');
+  assert.equal(invoke.parseArgv(['historian']).error, 'usage');
+  assert.equal(invoke.parseArgv(['historian', '   ']).error, 'usage');
+});
+
+// --- the corpus constants are a contract, not incidental --------------------
+
+await test('the corpus roots and the learnings bound are pinned', () => {
+  assert.deepEqual(invoke.CORPUS_DIRS.map(([d]) => d), ['docs/adr', 'docs/session-logs']);
+  // docs/adr/README.md must NOT be listed: at ~500KB the Read tool refuses it,
+  // and the ADR manifest is what replaced it.
+  assert.ok(!invoke.INDEX_CANDIDATES.some(([p]) => p === 'docs/adr/README.md'));
+  assert.ok(invoke.INDEX_CANDIDATES.some(([p]) => p === 'CLAUDE.md'));
+  assert.equal(typeof invoke.LEARNINGS_LIMIT, 'number');
+  assert.ok(invoke.LEARNINGS_LIMIT > 0 && invoke.LEARNINGS_LIMIT <= 500);
+  assert.ok(invoke.INDEX_MAX_BYTES > 0);
+});
+
+await test('a padded learning id names the same row as an unpadded one', () => {
+  const { ids } = invoke.renderLearnings([{ id: '0041', title: 't', body_md: '' }]);
+  assert.deepEqual([...ids], ['41']);
+  assert.equal(invoke.resolveCitation('learning:41', { learningIds: ids }).ok, true);
+  assert.equal(invoke.resolveCitation('learning:0041', { learningIds: ids }).ok, true);
+  assert.equal(invoke.resolveCitation('learning:410', { learningIds: ids }).ok, false);
+});
+
+// --- the gate (rule 2) ------------------------------------------------------
+
+await test('the gate refuses a definition that is present but not enabled', () => {
+  const g = invoke.gateFor({ ...HISTORIAN, enabled: false });
+  assert.equal(g.decision, 'no-go');
+  assert.match(g.reason, /not enabled/);
+});
+
+await test('a scope-wall flag is reported as the scope wall, not as "disabled"', () => {
+  // The schema forces a flagged row to enabled=false, so both are true at once —
+  // and the two have completely different fixes, so the reason must distinguish.
+  const g = invoke.gateFor({ ...HISTORIAN, enabled: false, scope_violation: 'scope_paths: reaches a protected surface' });
+  assert.equal(g.decision, 'no-go');
+  assert.match(g.reason, /scope wall/);
+  assert.match(g.reason, /protected surface/);
+});
+
+await test('an event agent cannot be asked a question', () => {
+  const g = invoke.gateFor({ ...HISTORIAN, trigger_type: 'event' });
+  assert.equal(g.decision, 'no-go');
+  assert.match(g.reason, /not 'on-demand'/);
+});
+
+await test('an armed on-demand definition passes', () => {
+  assert.deepEqual(invoke.gateFor(HISTORIAN), { decision: 'go', reason: null });
+});
+
+// --- the demand half of the prompt ------------------------------------------
+
+await test('the demand carries the question, the doors and the citation rule', () => {
+  const d = invoke.buildDemand({
+    question: 'why is the trust boundary server-side?',
+    indexes: [['CLAUDE.md', 'the kernel']],
+    manifests: [{ dir: 'docs/adr', why: 'decisions of record', files: ['0016-trust-boundary.md'], total: 1, truncated: false }],
+    learnings: { text: '', ids: new Set() },
+  });
+  assert.match(d, /why is the trust boundary server-side\?/);
+  assert.match(d, /docs\/adr\/0016-trust-boundary\.md/);
+  assert.match(d, /CLAUDE\.md/);
+  assert.match(d, /checked against/);
+  assert.match(d, /"citations"/);
+  // No learnings supplied ⇒ no learnings block, rather than an empty heading the
+  // agent could read as "there are none on record".
+  assert.doesNotMatch(d, /### Learnings/);
+});
+
+// --- the doors (buildCorpus) ------------------------------------------------
+
+await test('an index that is absent, and one too big for the Read tool, are both dropped', () => {
+  // Both cases are real and both were found by running this against the actual
+  // repo: the generated indexes are gitignored, and docs/adr/README.md is a
+  // tracked 500KB file the Read tool refuses.
+  const sizes = new Map([
+    ['docs/file-map.md', 116037],
+    ['CLAUDE.md', 22565],
+    ['docs/adr/README.md', 512751],
+    // docs/repo-map.md and docs/session-log-index.md: absent
+  ]);
+  const { indexes } = invoke.buildCorpus({
+    listDir: () => [],
+    fileSize: (p) => (sizes.has(p) ? sizes.get(p) : -1),
+  });
+  const listed = indexes.map(([p]) => p);
+  assert.deepEqual(listed, ['docs/file-map.md', 'CLAUDE.md']);
+  assert.ok(!listed.includes('docs/adr/README.md'), 'a door that will not open is worse than no door');
+  assert.ok(!listed.includes('docs/repo-map.md'));
+});
+
+await test('the corpus manifest lists the real filenames, and says so when it had to stop', () => {
+  const many = Array.from({ length: 900 }, (_, i) => `${String(i).padStart(4, '0')}-a-decision.md`);
+  const { manifests } = invoke.buildCorpus({
+    listDir: (d) => (d === 'docs/adr' ? many : []),
+    fileSize: () => -1,
+  });
+  assert.equal(manifests.length, 1, 'an empty corpus dir contributes no manifest at all');
+  const [adr] = manifests;
+  assert.equal(adr.total, 900);
+  assert.equal(adr.files.length, invoke.MANIFEST_MAX_FILES);
+  assert.equal(adr.truncated, true);
+  // A truncated listing must say it is truncated: an agent that reads a partial
+  // list as complete concludes a record is absent when it is merely unlisted.
+  const d = invoke.buildDemand({ question: 'q', manifests, indexes: [] });
+  assert.match(d, /900 file\(s\), of which the first 600 are listed/);
+});
+
+await test('the learnings block and the accepted id set are built together', () => {
+  const { text, ids } = invoke.renderLearnings([
+    { id: 41, title: 'ship-check is not CI', body_md: 'It misses three steps.' },
+    { id: '42', title: 'stash is repo-global', body_md: '' },
+    { id: 'not-an-id', title: 'ignored', body_md: '' },
+  ]);
+  assert.match(text, /learning:41 — ship-check is not CI: It misses three steps\./);
+  assert.match(text, /learning:42 — stash is repo-global/);
+  assert.deepEqual([...ids].sort(), ['41', '42']);
+  // The id that is not an id never reaches the prompt, so it can never be cited.
+  assert.doesNotMatch(text, /not-an-id/);
+});
+
+await test('the learnings block is bounded — asking a question cannot cost more the longer the instance has run', () => {
+  const many = Array.from({ length: 5000 }, (_, i) => ({ id: i + 1, title: 'x'.repeat(80), body_md: 'y'.repeat(600) }));
+  const { text, ids } = invoke.renderLearnings(many);
+  assert.ok(text.length <= 24000, `block is ${text.length} chars`);
+  // And the id set stops where the text does: a learning that was truncated away
+  // must not be quietly citable.
+  assert.ok(ids.size < many.length);
+  assert.ok([...ids].every((id) => text.includes(`learning:${id} `)));
+});
+
+// --- the chain, end to end --------------------------------------------------
+
+await test('a clean invocation returns the answer and its ledger row says ok', async () => {
+  const { result, pool } = await run();
+  assert.equal(result.ok, true);
+  assert.equal(result.answer.answer, 'The trust boundary is server-enforced.');
+  assert.equal(result.runId, 99);
+  assert.equal(result.model, 'opus');
+
+  const ins = pool.inserted();
+  assert.equal(ins.agent_name, 'historian');
+  assert.equal(ins.trigger_type, 'on-demand');
+  assert.equal(ins.gate_decision, 'go');
+  assert.equal(ins.status, 'pending');
+  assert.equal(ins.trigger_ref, 'on-demand:a-builder');
+  assert.equal(ins.requested_by_builder_id, 1000025);
+
+  const upd = pool.updated();
+  assert.equal(upd.status, 'ok');
+  assert.equal(upd.error_code, null);
+  assert.equal(upd.cost_usd, 0.0123);
+});
+
+await test('the persona and the question BOTH reach the model', async () => {
+  const runner = replyWith(GOOD_ANSWER);
+  await run({}, { runSubagentCached: runner });
+  assert.match(runner.seen.prompt, /You are the historian of this repository\./);
+  assert.match(runner.seen.prompt, /why is the trust boundary server-side\?/);
+  // The persona comes first: the agent is told who it is before what it is asked.
+  assert.ok(runner.seen.prompt.indexOf('historian of this repository')
+    < runner.seen.prompt.indexOf('why is the trust boundary'));
+});
+
+await test('an UNCITED answer is a failed run in the ledger, with its cost kept', async () => {
+  const runner = replyWith({ answer: 'Because it just is.', citations: [] });
+  const { result, pool } = await run({}, { runSubagentCached: runner });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'agent_answer_uncited');
+  const upd = pool.updated();
+  assert.equal(upd.status, 'error');
+  assert.equal(upd.error_code, 'agent_answer_uncited');
+  // The money was spent whether or not the answer was usable, and a ledger that
+  // hid that would under-report what agents cost.
+  assert.equal(upd.cost_usd, 0.0123);
+  // A failed run's partial output is not a result (task 1002489).
+  assert.equal(upd.output_ref, null);
+});
+
+await test('a FABRICATED citation fails the run — this is the check that makes "cited" mean something', async () => {
+  const runner = replyWith({
+    answer: 'ADR 0999 settled it.',
+    citations: [{ ref: 'docs/adr/0999-invented.md' }],
+  });
+  const { result, pool } = await run({}, { runSubagentCached: runner });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'agent_citation_unresolvable');
+  assert.match(result.reason, /0999-invented/);
+  assert.equal(pool.updated().error_code, 'agent_citation_unresolvable');
+});
+
+await test('a reply that is not an answer at all is recorded as unparsed, not as silence', async () => {
+  const { result, pool } = await run({}, { runSubagentCached: replyWith('I could not find anything.') });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'agent_answer_unparsed');
+  assert.equal(pool.updated().error_code, 'agent_answer_unparsed');
+});
+
+await test('a DISABLED agent is refused, and the refusal is a row (rule 2)', async () => {
+  const pool = fakePool({ definition: { ...HISTORIAN, enabled: false } });
+  const runner = replyWith(GOOD_ANSWER);
+  const { result } = await run({}, { pool, runSubagentCached: runner });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'agent_refused');
+  assert.match(result.reason, /not enabled/);
+
+  const ins = pool.inserted();
+  assert.equal(ins.gate_decision, 'no-go');
+  assert.equal(ins.status, 'skipped');
+  assert.match(ins.gate_reason, /not enabled/);
+  // A no-go spawned nothing, so it has no model and no cost (schema invariant).
+  assert.equal(ins.model, null);
+  assert.equal(pool.updated(), null, 'a skipped run is terminal — nothing finishes it');
+  assert.equal(runner.seen.prompt, undefined, 'the model was never called');
+});
+
+await test('a flagged agent is refused with the scope wall\'s own words', async () => {
+  const pool = fakePool({
+    definition: { ...HISTORIAN, enabled: false, scope_violation: 'scope_paths: "src/bongos/auth.js" reaches a protected surface' },
+  });
+  const { result } = await run({}, { pool });
+  assert.equal(result.code, 'agent_refused');
+  assert.match(pool.inserted().gate_reason, /reaches a protected surface/);
+});
+
+await test('an UNKNOWN agent writes no ledger row — there is nothing that was refused', async () => {
+  const pool = fakePool({ definition: null });
+  const { result } = await run({ name: 'nobody' }, { pool });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'agent_not_found');
+  assert.equal(result.runId, null);
+  assert.equal(pool.inserted(), null);
+});
+
+await test('the registry is the authority: a file on disk is never consulted', async () => {
+  // The definition the pool hands back is the one that runs, persona included —
+  // there is no read of .claude/agents/ anywhere in the chain (rule 1).
+  const pool = fakePool({ definition: { ...HISTORIAN, persona: 'REGISTRY PERSONA' } });
+  const runner = replyWith(GOOD_ANSWER);
+  await run({}, { pool, runSubagentCached: runner });
+  assert.match(runner.seen.prompt, /REGISTRY PERSONA/);
+  assert.equal(pool.calls.filter((c) => /FROM agents_definitions/.test(c.sql)).length, 1);
+});
+
+await test('learnings the agent was shown are citable; the run degrades rather than fails when the table is unreadable', async () => {
+  const pool = fakePool({ learnings: [{ id: 41, title: 'ship-check is not CI', body_md: 'misses three steps' }] });
+  const runner = replyWith({ answer: 'See the learning.', citations: [{ ref: 'learning:41' }] });
+  const { result } = await run({}, { pool, runSubagentCached: runner });
+  assert.equal(result.ok, true, 'a learning the prompt carried is a valid source');
+  assert.match(runner.seen.prompt, /learning:41 — ship-check is not CI/);
+
+  // And when the read throws, the answer still happens over the file corpus.
+  const broken = fakePool();
+  const original = broken.query.bind(broken);
+  broken.query = async (sql, params) => {
+    if (/FROM learnings/.test(sql)) throw new Error('relation "learnings" does not exist');
+    return original(sql, params);
+  };
+  const warnings = [];
+  const { result: degraded } = await run({}, { pool: broken, warn: (m) => warnings.push(m) });
+  assert.equal(degraded.ok, true);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /learnings unavailable/);
+});
+
+await test('the run is costed and attributed even when the model is slow or free', async () => {
+  const runner = replyWith(GOOD_ANSWER, { cost: 0 });
+  const { result, pool } = await run({}, { runSubagentCached: runner });
+  assert.equal(result.ok, true);
+  assert.equal(pool.updated().cost_usd, 0, 'a $0 cached replay is still a recorded cost, not an absent one');
+});
+
+// --- the spawn seam's half of the join --------------------------------------
+
+await test('composePrompt: an event fire with no input sends exactly the persona it always did', () => {
+  assert.equal(composePrompt({ persona: 'observe and report' }, null), 'observe and report');
+  assert.equal(composePrompt({ persona: 'observe and report' }, '   '), 'observe and report');
+});
+
+await test('composePrompt: on-demand input follows the persona, separated', () => {
+  assert.equal(composePrompt({ persona: 'who you are' }, 'what you are asked'), 'who you are\n\nwhat you are asked');
+});
+
+await test('composePrompt: a definition with no persona still carries the demand', () => {
+  assert.equal(composePrompt({}, 'the question'), 'the question');
+  assert.equal(composePrompt(null, null), '');
+});
+
+await test('spawnAgent carries `input` through to the runner, unchanged', async () => {
+  const calls = [];
+  const pool = {
+    async query(sql) {
+      if (/^INSERT INTO agents_runs/.test(sql)) return { rows: [{ id: 5 }] };
+      return { rows: [] };
+    },
+  };
+  await spawnAgent(
+    { definition: { id: 1, name: 'historian', persona: 'P', model_tier: 'default' }, input: 'Q' },
+    { pool, brandingModels: MODELS, runSubagentCached: async (a) => { calls.push(a.prompt); return { stdout: '', cost_usd: 0 }; } },
+  );
+  assert.deepEqual(calls, ['P\n\nQ']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/agent_invoke_live.mjs

@@ -0,0 +1,111 @@
+// tests/agent_invoke_live.mjs — the end-to-end proof, reproducible (task 1002491).
+//
+// tests/agent_invoke.mjs proves the DECISIONS with a fake pool, a fake runner and
+// a fake tree. It cannot prove the one thing criterion `agents-historian-exemplar`
+// actually claims: that the real historian, given the real corpus, comes back with
+// an answer whose citations are real. Only a real model call can say that, and a
+// real model call costs real money (~$0.90 a question at the time of writing) and
+// needs an authenticated `claude` CLI — so it must never run in CI or in the unit
+// gate, and it is OPT-IN.
+//
+//   AGENT_INVOKE_LIVE=1 node tests/agent_invoke_live.mjs ["<question>"]
+//
+// Skipped and exit 0 otherwise, so `run-unit-tests.js` sweeps it up harmlessly.
+//
+// The POOL is still faked — a builder box has no database, which is also why the
+// script's every edge is injectable. What is real here is the definition (parsed
+// from the committed .claude/agents/historian.md exactly as agents-sync would land
+// it), the corpus (this checkout), the model, and the citation check.
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+if (process.env.AGENT_INVOKE_LIVE !== '1') {
+  console.log('  skip  agent_invoke_live — set AGENT_INVOKE_LIVE=1 to spend ~$1 proving the chain for real');
+  process.exit(0);
+}
+
+const invoke = require('../scripts/gds/agent-invoke.js');
+const agentsSync = require('../scripts/gds/agents-sync.js');
+const grader = require('../modules/grading/grader.js');
+
+// The definition exactly as the deploy-time reconcile would land it, so what runs
+// is the committed file and not a fixture that drifted from it.
+const candidate = agentsSync.parseAgentFile(
+  fs.readFileSync(path.join(ROOT, '.claude/agents/historian.md'), 'utf8'),
+  { name: 'historian' },
+);
+const definition = {
+  id: 1,
+  ...candidate,
+  trigger_spec: {},
+  scope_modules: [],
+  scope_paths: [],
+  scope_violation: null,
+  source: 'file',
+  provenance: 'built-in',
+  // Armed for the duration of this check. Note that a real deploy does NOT land
+  // it armed — see the header of scripts/gds/agent-invoke.js.
+  author_rank: 'archon',
+  enabled: true,
+};
+
+const ledger = [];
+const pool = {
+  async query(sql, params) {
+    if (/FROM agents_definitions/.test(sql)) return { rows: [definition] };
+    // No database on a builder box; the degrade path is exercised for free.
+    if (/FROM learnings/.test(sql)) throw new Error('no database on this box');
+    if (/^INSERT INTO agents_runs/.test(sql)) { ledger.push(['insert', params]); return { rows: [{ id: 1 }] }; }
+    ledger.push(['update', params]);
+    return { rows: [] };
+  },
+};
+
+const question = process.argv.slice(2).join(' ')
+  || 'Why does this project enforce permissions server-side rather than in the client, and what is the rule about editing local files to grant yourself authority?';
+
+console.log(`  Q: ${question}`);
+const started = Date.now();
+const result = await invoke.invokeAgent(
+  { name: 'historian', question, requestedByBuilderId: 1, requestedByLogin: 'live-check' },
+  {
+    pool,
+    runSubagentCached: (a) => grader.runSubagentCached({ ...a, opts: { ...a.opts, timeoutMs: 600000 } }),
+    spawnDeps: { brandingModels: { subagentDefault: 'claude-opus-5', subagentRoutine: 'claude-haiku-4-5-20251001' } },
+    warn: (m) => console.log(`  warn: ${m}`),
+  },
+);
+const secs = Math.round((Date.now() - started) / 1000);
+
+if (!result.ok) {
+  console.error(`  FAIL  ${result.code} — ${result.reason || ''} (${secs}s)`);
+  process.exit(1);
+}
+
+console.log(`\n${result.answer.answer}\n`);
+console.log('  Citations, every one resolved against this checkout:');
+for (const c of result.answer.citations) console.log(`    - ${c.ref}`);
+console.log(`\n  ${secs}s · ${result.model} · $${result.cost_usd} · confidence ${result.answer.confidence}`);
+
+// The claim the criterion makes, asserted rather than eyeballed.
+assert.ok(result.answer.citations.length > 0, 'a cited result');
+for (const c of result.answer.citations) {
+  const p = invoke.citationPath(c.ref);
+  if (/^learning:/.test(c.ref)) continue;
+  assert.ok(fs.existsSync(path.join(ROOT, p)), `${p} exists in the tree`);
+}
+// ...and the ledger said so: one go row, finished ok, with a real cost on it.
+const [insert] = ledger.filter(([k]) => k === 'insert');
+const [update] = ledger.filter(([k]) => k === 'update');
+assert.ok(insert && insert[1].includes('go'), 'the gate said go');
+assert.ok(update && update[1].includes('ok'), 'the run finished ok');
+assert.ok(Number(result.cost_usd) > 0, 'a real fire costs real money and the ledger carries it');
+
+console.log('\n  ok  the historian returned a cited result end-to-end, and the ledger agrees');