the-high-council 0.6.0

package/src/partial-deliverable.js

@@ -0,0 +1,38 @@
+// Partial-deliverable detection (v2 plan §7.1, GLM-6 primary design with DEEPSEEK-6's
+// schema/required-field validation approach).
+//
+// Same class of bug as the lab-dropout incident this project already fixed: a stage's
+// submitted deliverable is missing a required section, is truncated JSON, or fails
+// structural validation, but the harness marks the stage complete anyway and passes it
+// downstream - a broken foundation that still looks complete, propagating further before
+// anyone notices. This validates a stage's raw output against the same required_sections
+// field the stage contract (§2.2) already declares, reused for free.
+//
+// This is a defense-in-depth check at the disk-persistence boundary in src/cli.js, not a
+// change to chain.js's own control flow - the debate/proposal/reply/blind-panel mechanism
+// is untouched (§11), and this module has no dependency on it.
+import { parseJson } from './chain.js';
+import { requiredSectionsFor, isStructuredStage } from './stage-contract.js';
+
+/**
+ * Check one stage's raw output text against its declared required sections.
+ * Structured (JSON-returning) stages: every required_sections key must be present in the
+ * parsed object. Freeform (text-returning) stages: the text must be non-empty - required
+ * sections there name a single symbolic slot, not literal JSON keys to look up.
+ */
+export function validateDeliverable(stageKind, text) {
+  const required = requiredSectionsFor(stageKind);
+  if (!isStructuredStage(stageKind)) {
+    if (typeof text === 'string' && text.trim().length > 0) return { ok: true };
+    return { ok: false, missing: required, reason: 'empty or missing deliverable text' };
+  }
+  const parsed = parseJson(text);
+  if (!parsed || typeof parsed !== 'object') {
+    return { ok: false, missing: required, reason: 'deliverable is not readable as JSON' };
+  }
+  const missing = required.filter(key => parsed[key] === undefined);
+  if (missing.length) {
+    return { ok: false, missing, reason: `missing required field(s): ${missing.join(', ')}` };
+  }
+  return { ok: true };
+}

package/src/peer-claim.js

@@ -0,0 +1,98 @@
+// Peer-session dispatch (v3 plan §1, GLM-1 accepted, MISTRAL-1 cut - see PLAN.md's Scope
+// ledger). Nine real runs were driven by handing an external stage to an already-running peer
+// Claude Code session, not to a subagent - the harness had no record of this at all. A claim
+// file, `runs/<id>/<stage>.claim.json`, is written by whoever intends to answer a stage, before
+// it writes `<stage>.md`:
+//
+//   { "claimed_by": "cnc-harness-a7", "claimed_at": "2026-09-13T12:46:10.000Z" }
+//
+// `claimed_by` is a self-declared string, nothing more - this is BYOK, local-disk software with
+// no identity infrastructure, and this module does not invent one. It buys staleness detection
+// (a claim with no answer, older than a timeout) and contested-claim detection (two different
+// claimants before an answer lands), never "who is right" - the harness cannot verify that, so
+// it only makes the collision visible.
+//
+// File-based only, no subprocess spawning, no network call, no ledger: this module reads and
+// writes exactly one JSON file per stage, inside the run folder it already belongs to.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 4 * 60 * 60 * 1000; // 4 hours - operator-tunable via the options arg,
+// matching how MAX_USD_PER_RUN is a plain value the caller resolves before calling in, not a
+// second config file this module reads for itself.
+
+function claimPath(dir, stage) {
+  return join(dir, `${stage}.claim.json`);
+}
+
+function answerPath(dir, stage) {
+  return join(dir, `${stage}.md`);
+}
+
+function readClaim(dir, stage) {
+  const p = claimPath(dir, stage);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * Write a claim for a stage, the whole mechanism for declaring one (same posture as
+ * AMENDMENTS.md, §2: writing it is the entire path). Called by whoever intends to answer the
+ * stage, before it writes `<stage>.md`.
+ *
+ * If a claim already exists for this stage, its `claimed_by` differs from this one, and no
+ * answer has landed yet, this is a contested claim: the harness cannot decide which claimant is
+ * "correct", so the original claim's `claimed_by`/`claimed_at` are kept as the record of first
+ * claim and the new claimant is appended to `contested_by`, rather than silently overwritten -
+ * the same posture as `duplicate_answer` below for the answer file itself. Otherwise (no
+ * existing claim, the same claimant re-claiming, or the stage already has an answer - a fresh
+ * work cycle) this simply (re)writes the claim.
+ */
+export function writeClaim(dir, stage, claimedBy, { now = () => new Date() } = {}) {
+  const existing = readClaim(dir, stage);
+  const hasAnswer = existsSync(answerPath(dir, stage));
+  let claim;
+  if (existing && existing.claimed_by !== claimedBy && !hasAnswer) {
+    const contested_by = [...(existing.contested_by || []), claimedBy];
+    claim = { ...existing, contested_by };
+  } else {
+    claim = { claimed_by: claimedBy, claimed_at: now().toISOString() };
+  }
+  writeFileSync(claimPath(dir, stage), JSON.stringify(claim, null, 2));
+  return claim;
+}
+
+export function readClaimFor(dir, stage) {
+  return readClaim(dir, stage);
+}
+
+/**
+ * Staleness and contest detection for one stage's claim.
+ *
+ * - No claim at all: no warning.
+ * - The claim was contested (see `writeClaim`) and no `<stage>.md` exists yet: `contested_claim`.
+ * - A claim exists, no `<stage>.md` yet, and `claimed_at` is older than `timeoutMs`:
+ *   `stalled_claim` - safe for a third party to pick the stage up.
+ * - A claim exists and `<stage>.md` already exists: no warning (the claim did its job).
+ *
+ * Returns `null` (no warning) or `{ type, stage, ... }`.
+ */
+export function checkClaimStaleness(dir, stage, { now = () => new Date(), timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const claim = readClaim(dir, stage);
+  if (!claim) return null;
+  const hasAnswer = existsSync(answerPath(dir, stage));
+
+  if (claim.contested_by?.length && !hasAnswer) {
+    return { type: 'contested_claim', stage, claimed_by: claim.claimed_by, contested_by: claim.contested_by };
+  }
+
+  if (hasAnswer) return null;
+
+  const claimedAt = Date.parse(claim.claimed_at);
+  if (Number.isNaN(claimedAt)) return null; // an unparsable claimed_at is not this check's job to flag
+  const ageMs = now().getTime() - claimedAt;
+  if (ageMs > timeoutMs) {
+    return { type: 'stalled_claim', stage, claimed_by: claim.claimed_by, claimed_at: claim.claimed_at, ageMs };
+  }
+  return null;
+}

package/src/personas.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+
+// v6 §6: public naming. The shipped default persona set - five historical/
+// public-domain figures, chosen so a public MIT repo carrying the author's
+// real name and a German Impressum never ships a third-party trademark. An
+// operator may replace the whole set (never edit this file to do it - see
+// loadPersonas()).
+//
+// Persona names are referenced only through this module in every
+// prompt-assembly path - never hard-coded elsewhere (src/roles.js included).
+// Wording below is a first pass, pending author review, same as §1's LENSES
+// instruction text.
+export const DEFAULT_PERSONAS = Object.freeze({
+  moses: Object.freeze({ name: 'Moses', voice: 'Speaks in plain, weighty directives. States the rule first, the reason second.' }),
+  noah: Object.freeze({ name: 'Noah', voice: 'Methodical and provisioning-minded. Asks what happens if this is wrong before asking what happens if it is right.' }),
+  matthew: Object.freeze({ name: 'Matthew', voice: 'A record-keeper\'s voice. Cites exactly what was said and by whom before drawing a conclusion.' }),
+  'van-gogh': Object.freeze({ name: 'Van Gogh', voice: 'Sees the whole composition before the detail. Argues from what the piece is trying to be, not just what is wrong with one brushstroke.' }),
+  parzival: Object.freeze({ name: 'Parzival', voice: 'Asks the question everyone else assumed was already answered.' }),
+});
+
+// Takes any path - .council/ (see .gitignore) is only a suggested location,
+// not enforced. Putting your own persona file somewhere else is fine, but
+// gitignore won't protect it there; that's on you to keep out of git add.
+const ENV_PERSONAS_FILE = 'COUNCIL_PERSONAS_FILE';
+
+/**
+ * The persona set to use: an operator-supplied file (path argument, or the
+ * COUNCIL_PERSONAS_FILE env var) REPLACES the whole default set, matching
+ * §6 ("an operator may replace the whole set"). No file configured, or the
+ * file can't be read, falls back to DEFAULT_PERSONAS - never throws.
+ */
+export function loadPersonas({ personasFile, readFile = defaultReadFile } = {}) {
+  const path = personasFile ?? process.env[ENV_PERSONAS_FILE];
+  if (!path) return DEFAULT_PERSONAS;
+  try {
+    const parsed = JSON.parse(readFile(path));
+    return parsed && typeof parsed === 'object' ? parsed : DEFAULT_PERSONAS;
+  } catch {
+    return DEFAULT_PERSONAS;
+  }
+}
+
+function defaultReadFile(path) {
+  return readFileSync(path, 'utf8');
+}
+
+/**
+ * Resolve a `role.persona` key (§1) against a persona set. Returns null for
+ * an unknown key rather than throwing - validating that null and raising a
+ * config error is §1's job (MISTRAL-2's validation rule), not this module's.
+ */
+export function resolvePersona(key, personas = DEFAULT_PERSONAS) {
+  return personas?.[key] ?? null;
+}

package/src/preflight.js

@@ -0,0 +1,84 @@
+// Static pre-flight contract/criteria check (v2 plan §6, GLM-5 primary design,
+// amended by DEEPSEEK-5/QWEN-3/MISTRAL-5 to warn rather than hard-fail).
+//
+// Before any stage of a run executes - before a single metered API call - compare the
+// chain's own hard-required deliverable structure against the request/task text for
+// keyword-level contradiction signals. Warn loudly, name both sides, never block the run.
+//
+// What this catches: the exact class of conflict this project has already hit once - a
+// chain requiring an appended "Scope ledger" section (src/roles.js's proposal-mode build
+// prompt) against text demanding a standalone, publication-ready document with no internal
+// process record - using recognisable trigger words.
+//
+// What this deliberately misses, stated plainly: a rephrasing of the same semantic conflict
+// without these exact words (e.g. "must be readable with no other file open") will not
+// trigger any warning. This is a heuristic, not a guarantee, and this module does not claim
+// otherwise - see test_preflight_known_misses_semantic_conflicts, which pins that the miss is
+// known and accepted, not an oversight to "helpfully" patch into a false sense of completeness.
+// A semantic/LLM-based check that would catch the missed case is an explicit non-goal (§11):
+// it would add an API call and non-determinism to every run's start.
+export const TRIGGER_KEYWORDS = ['standalone', 'without a', 'no appended', 'publication-ready', 'self-contained'];
+
+/**
+ * Sections this chain's own build-stage prompt hard-requires in the deliverable, derived
+ * from chain config flags. The only current instance in this codebase: config.proposals
+ * mode requires the builder to end the deliverable with a "Scope ledger" section
+ * (src/roles.js proposerUser/proposalsSystem's "The plan must end with a section titled
+ * 'Scope ledger'" instruction). Extend this list if a future chain feature adds another
+ * hard-required section to a prompt in src/roles.js - keep it in sync with that file, not
+ * invented separately.
+ */
+export function requiredDeliverableSections(chainConfig) {
+  const sections = [];
+  if (chainConfig?.proposals) sections.push('Scope ledger');
+  return sections;
+}
+
+/**
+ * Compare a chain's required sections against arbitrary text (the request/task text -
+ * the only text available before any API call, since acceptance criteria themselves are
+ * usually generated by a paid stage). Returns a list of warnings, never throws and never
+ * signals "block this run" - callers decide what to do with the list, but the harness
+ * itself only ever logs and proceeds.
+ */
+export function preflightCheck(chainConfig, text) {
+  const sections = requiredDeliverableSections(chainConfig);
+  const lower = (text || '').toLowerCase();
+  const warnings = [];
+  for (const section of sections) {
+    for (const keyword of TRIGGER_KEYWORDS) {
+      if (lower.includes(keyword.toLowerCase())) {
+        warnings.push({
+          section,
+          keyword,
+          message: `Possible contract/criteria conflict: chain requires section '${section}'; criteria text contains '${keyword}', which may conflict. This is a heuristic check and may miss cases where the conflict is phrased differently. Proceeding - review manually if unsure.`,
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
+// v3 §3 (artifact inlining, ~/Projects/relay/tasks/thcmcp-v3-draft-fixed.md). Real incident:
+// a task that only summarised a specific JSON rubric file, rather than inlining it, led every
+// critic lab to invent plausible-but-nonexistent identifiers against it - only the external
+// build seat, which could read the real file, caught it. This check warns (never blocks, same
+// posture as preflightCheck above) when a task names a path it never fences verbatim elsewhere
+// in its own text, so the operator can paste the real content before any labs see the task.
+const PATH_PATTERN = /\b[\w.-]+\.[a-zA-Z]{1,6}\b/g;
+
+export function checkArtifactReferences(text) {
+  const body = text || '';
+  const fenced = [...body.matchAll(/```[\s\S]*?```/g)].map(m => m[0]).join('\n');
+  const candidates = new Set([...body.matchAll(PATH_PATTERN)].map(m => m[0]));
+  const warnings = [];
+  for (const path of candidates) {
+    if (!fenced.includes(path)) {
+      warnings.push({
+        path,
+        message: `Possible missing artifact: the task names '${path}' but never fences its content verbatim anywhere in the task text. A lab reading only the task may invent plausible-but-nonexistent content for it. This is a heuristic check and may miss a path phrased unusually. Proceeding - inline the real file if this run is about it.`,
+      });
+    }
+  }
+  return warnings;
+}

package/src/pricing.json

@@ -0,0 +1,120 @@
+{
+  "_note": "USD per 1,000,000 tokens. List prices change often - re-check each lab's pricing page before quoting these to anyone. Verified against public pricing pages as of 2026-09-06; treat as estimates, not invoices.",
+  "anthropic/claude-opus-5": {
+    "in": 15.0,
+    "out": 75.0
+  },
+  "anthropic/claude-sonnet-5": {
+    "in": 3.0,
+    "out": 15.0
+  },
+  "anthropic/claude-haiku-4-5-20251001": {
+    "in": 1.0,
+    "out": 5.0
+  },
+  "openai/gpt-5": {
+    "in": 1.25,
+    "out": 10.0
+  },
+  "openai/gpt-5-mini": {
+    "in": 0.25,
+    "out": 2.0
+  },
+  "google/gemini-2.5-pro": {
+    "in": 1.25,
+    "out": 10.0
+  },
+  "google/gemini-2.5-flash": {
+    "in": 0.3,
+    "out": 2.5
+  },
+  "xai/grok-4": {
+    "in": 3.0,
+    "out": 15.0
+  },
+  "mistral/mistral-large-latest": {
+    "in": 2.0,
+    "out": 6.0
+  },
+  "deepseek/deepseek-chat": {
+    "in": 0.27,
+    "out": 1.1
+  },
+  "groq/llama-3.3-70b-versatile": {
+    "in": 0.59,
+    "out": 0.79
+  },
+  "together/Qwen/Qwen3.5-9B": {
+    "in": 0.1,
+    "out": 0.15
+  },
+  "mistral/mistral-small-latest": {
+    "in": 0.1,
+    "out": 0.3
+  },
+  "openai/gpt-5-nano": {
+    "in": 0.05,
+    "out": 0.4
+  },
+  "together/meta-llama/Llama-3.3-70B-Instruct-Turbo": {
+    "in": 0.88,
+    "out": 0.88
+  },
+  "deepseek/deepseek-reasoner": {
+    "in": 0.55,
+    "out": 2.19
+  },
+  "cohere/command-r7b-12-2024": {
+    "in": 0.0375,
+    "out": 0.15
+  },
+  "openrouter/meta-llama/llama-3.3-70b-instruct": {
+    "in": 0.1,
+    "out": 0.32
+  },
+  "together/deepseek-ai/DeepSeek-V3.1": {
+    "in": 0.6,
+    "out": 1.7
+  },
+  "google/gemini-3.6-flash": {
+    "in": 0.75,
+    "out": 3.75
+  },
+  "zai/glm-4.7-flash": {
+    "in": 0.0,
+    "out": 0.0
+  },
+  "together/deepseek-ai/DeepSeek-V4-Flash-0731": {
+    "in": 0.14,
+    "out": 0.28
+  },
+  "openrouter/qwen/qwen3.5-plus-20260420": {
+    "in": 0.3,
+    "out": 1.8
+  },
+  "openrouter/z-ai/glm-5.3-flash": {
+    "in": 0.07,
+    "out": 0.25
+  },
+  "openrouter/mistralai/mistral-large-2512": {
+    "in": 0.5,
+    "out": 1.5
+  },
+  "openrouter/minimax/minimax-m3": {
+    "in": 0.3,
+    "out": 1.2
+  },
+  "openrouter/deepseek/deepseek-v3.2": {
+    "in": 0.27,
+    "out": 0.4
+  },
+  "openrouter/moonshotai/kimi-k3": {
+    "in": 2.5,
+    "out": 14.0
+  },
+  "_test_note": "mock/* entries below are test fixtures, not real prices. The mock provider calls nothing; these exist only so the per-run spend cap can be exercised offline, since an unpriced seat cannot be capped.",
+  "mock/mock-priced": {
+    "in": 1000.0,
+    "out": 1000.0
+  }
+}

package/src/providers.js

@@ -0,0 +1,268 @@
+// Provider adapters. One shape in, one shape out.
+//
+//   call({ model, system, messages, maxTokens, temperature })
+//     -> { text, usage: { input, output }, provider, model }
+//
+// Anthropic uses its own Messages API. Everything else here speaks the
+// OpenAI chat-completions shape, which is why they share one adapter.
+
+const OPENAI_COMPAT = {
+  openai:   { base: 'https://api.openai.com/v1',                 key: 'OPENAI_API_KEY' },
+  google:   { base: 'https://generativelanguage.googleapis.com/v1beta/openai', key: 'GOOGLE_API_KEY' },
+  xai:      { base: 'https://api.x.ai/v1',                       key: 'XAI_API_KEY' },
+  mistral:  { base: 'https://api.mistral.ai/v1',                 key: 'MISTRAL_API_KEY' },
+  deepseek: { base: 'https://api.deepseek.com/v1',               key: 'DEEPSEEK_API_KEY' },
+  groq:     { base: 'https://api.groq.com/openai/v1',            key: 'GROQ_API_KEY' },
+  cohere:   { base: 'https://api.cohere.ai/compatibility/v1',    key: 'COHERE_API_KEY' },
+  openrouter: { base: 'https://openrouter.ai/api/v1',            key: 'OPENROUTER_API_KEY' },
+  together: { base: 'https://api.together.xyz/v1',               key: 'TOGETHER_API_KEY' },
+  zai:      { base: 'https://api.z.ai/api/paas/v4',               key: 'ZAI_API_KEY' },
+};
+
+const ANTHROPIC = { base: 'https://api.anthropic.com/v1', key: 'ANTHROPIC_API_KEY' };
+
+// An offline provider used to test the chain's plumbing without spending
+// anything. It fakes a builder and a critic well enough to exercise every
+// branch, including the early stop.
+async function callMock({ model, system, messages, maxTokens }) {
+  const user = messages.map(m => m.content).join('\n');
+  // A critic whose reply can't be parsed - stands in for a real reply cut
+  // off at the token cap. Exercises the abstention path offline.
+  if (model === 'mock-unreadable') {
+    await new Promise(r => setTimeout(r, 10));
+    return { text: 'Looks fine to me. (no JSON)', usage: { input: 10, output: 8 }, provider: 'mock', model };
+  }
+  // A critic whose provider errored out mid-generation with no content at all - stands in for
+  // GLM 5.3 Flash burning its whole token budget on thinking (usage.thinking === usage.output)
+  // and returning finish_reason: "error" (GP judging run 2026-09-10T20-01-59-545Z). Exercises the
+  // classifyUnreadable "stop: error" branch offline, distinct from the truncation/malformed-JSON
+  // cases mock-unreadable covers.
+  if (model === 'mock-provider-error') {
+    await new Promise(r => setTimeout(r, 10));
+    return { text: '', usage: { input: 10, output: 20, thinking: 20, stop: 'error' }, provider: 'mock', model };
+  }
+  if (system.startsWith('You are a proposer')) {
+    await new Promise(r => setTimeout(r, 10));
+    const text = model === 'mock-proposer-empty'
+      ? 'I have nothing to add.'
+      // v5 §1 candidate 10: a seat that returns more proposals than a
+      // chain's opt-in max_proposals_per_seat cap, to exercise the fold-down
+      // path offline. Four proposals, distinct titles so a merge test can
+      // tell which ones survived.
+      : model === 'mock-proposer-quad'
+      ? JSON.stringify({ proposals: [1, 2, 3, 4].map(n => (
+          { title: `Part ${n} from ${model}`, serves: 'the format criterion', what: 'A mock part.', why: 'Exercises the ledger.', how: 'mock.js', acceptance_test: 'It appears in the ledger.' }))})
+      : JSON.stringify({ proposals: [
+          { title: `Part from ${model}`, serves: 'the format criterion', what: 'A mock part.', why: 'Exercises the ledger.', how: 'mock.js', acceptance_test: 'It appears in the ledger.' },
+        ]});
+    return { text, usage: { input: 20, output: 30 }, provider: 'mock', model };
+  }
+  // v5 §1 candidate 10: the fold-down prompt itself. Keeps the first `cap`
+  // of the seat's own numbered proposals - enough to exercise the wiring
+  // offline without needing real judgement.
+  if (system.startsWith('You are folding your own proposals down')) {
+    await new Promise(r => setTimeout(r, 10));
+    const capMatch = user.match(/cap of (\d+)/);
+    const cap = capMatch ? Number(capMatch[1]) : 1;
+    const n = (user.match(/^## \d+$/gm) || []).length;
+    const kept = Array.from({ length: Math.min(cap, n) }, (_, i) => i + 1);
+    return { text: JSON.stringify({ kept, merged_because: 'mock: folded to the cap' }), usage: { input: 20, output: 10 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You are one lab on a planning panel. Every lab proposed')) {
+    await new Promise(r => setTimeout(r, 10));
+    const others = [...user.matchAll(/^## ([A-Z]-\d+) \(by Lab [A-Z]\)/gm)].map(m => m[1]);
+    const mineIdx = user.indexOf('# The other labs');
+    const theirs = others.filter(id => user.indexOf(`## ${id} `) > mineIdx);
+    const posts = theirs.map((id, i) => ({ on: id, stance: i % 2 ? 'support' : 'object', text: i % 2 ? 'Fine as written.' : 'Quote: "mock.js" - no such file exists.' }));
+    return { text: JSON.stringify({ posts, revisions: [] }), usage: { input: 30, output: 30 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You are one lab on a planning panel, answering')) {
+    await new Promise(r => setTimeout(r, 10));
+    const ids = [...user.matchAll(/^## ([A-Z]-\d+) \(by/gm)].map(m => m[1]);
+    const replies = ids.map((id, i) => i === 0 ? { id, action: 'amend', text: 'Fair.', how: 'mock.js (amended)' } : { id, action: 'keep', text: 'The file is created by the plan.' });
+    return { text: JSON.stringify({ replies }), usage: { input: 30, output: 20 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You write the handoff file')) {
+    await new Promise(r => setTimeout(r, 10));
+    return { text: 'MOCK HANDOFF\n\nRead the plan. Start with "begin".', usage: { input: 30, output: 10 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You read a request and ask the questions')) {
+    await new Promise(r => setTimeout(r, 10));
+    return { text: JSON.stringify({ questions: [
+      { question: 'Is the artifact for humans or machines?', why: 'Changes the format entirely.', default: 'Humans.' },
+      { question: 'One page or several?', why: 'Changes the structure.', default: 'One page.' },
+    ]}), usage: { input: 20, output: 40 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You are the judge')) {
+    await new Promise(r => setTimeout(r, 10));
+    const n = (user.match(/^## \d+$/gm) || []).length;
+    return { text: JSON.stringify({ picks: n ? [1] : [], dropped_because: 'mock: duplicates' }), usage: { input: 20, output: 10 }, provider: 'mock', model };
+  }
+  if (system.startsWith('You write the skeleton')) {
+    await new Promise(r => setTimeout(r, 10));
+    return { text: 'MOCK SKELETON\n- system A\n- system B', usage: { input: 20, output: 10 }, provider: 'mock', model };
+  }
+  const isReviser = system.startsWith('You are the builder in a multi-model review chain,\nrevising');
+  const isCritic = !isReviser && system.startsWith('You are an independent critic');
+  const isCriteria = system.includes('turn a request into acceptance criteria');
+  let text;
+  if (isCriteria) {
+    text = JSON.stringify({ criteria: [
+      'The deliverable is the artifact itself, not a plan for one.',
+      'It states the assumptions it was written under.',
+      'It adds no scope the request did not ask for.',
+    ]});
+  } else if (isCritic) {
+    // The scripted critic fails the first draft and passes the revision, so a
+    // test run exercises the revise path and then the early stop.
+    // `mock-critic-holdout` never passes, so a panel seated with it always ends
+    // on a real holdout - the branch where a run ships with an objection on the
+    // record rather than a unanimous sign-off.
+    const revised = model !== 'mock-critic-holdout' && user.includes('REVISED MOCK DELIVERABLE');
+    text = JSON.stringify(revised
+      ? { meets: true, criteria: [], failures: [], verdict_line: 'All criteria met.' }
+      : { meets: false, criteria: [], failures: [{ criterion: 'It states the assumptions it was written under.', problem: 'No assumptions section.', fix: 'Add one.' }], verdict_line: 'One criterion failed.' });
+  } else {
+    const ids = [...user.matchAll(/^## ([A-Z0-9-]+-\d+) \((?:from|[a-z0-9-]+\))/gm)].map(m => m[1]);
+    const ledger = ids.length ? `\n\n## Scope ledger\n${ids.map((id, i) => `${id} - ${i === 0 ? 'accepted - section 1' : 'cut - duplicate of the first'}`).join('\n')}` : '';
+    // test/chain.test.js's §5 dispute-record fixture: a reviser reply ending in one or more
+    // "DECLINED: <reason>" trailer lines, as src/roles.js's reviser system prompt now instructs
+    // for an objection the reviser judges not to be a real defect. Gated on a marker in the
+    // request text so every other mock-provider test (which never sets it) is unaffected.
+    const declineTrailer = isReviser && user.includes('TRIGGER_DECLINED_TEST')
+      ? '\n\nDECLINED: the critic quoted no evidence for this claim.\nDECLINED: this is a matter of taste, not a defect.'
+      : '';
+    text = `${isReviser ? 'REVISED ' : ''}MOCK DELIVERABLE for model ${model}\n\nBody text.${isReviser ? '\n\nAssumptions: none.' : ''}${ledger}${declineTrailer}`;
+  }
+  await new Promise(r => setTimeout(r, 10));
+  return { text, usage: { input: Math.ceil(user.length / 4), output: Math.ceil(text.length / 4) }, provider: 'mock', model };
+}
+
+export function keyFor(provider) {
+  if (provider === 'mock' || provider === 'external') return provider;
+  const spec = provider === 'anthropic' ? ANTHROPIC : OPENAI_COMPAT[provider];
+  if (!spec) throw new Error(`Unknown provider: ${provider}`);
+  return process.env[spec.key] || null;
+}
+
+export function providerNames() {
+  return ['anthropic', ...Object.keys(OPENAI_COMPAT)];
+}
+
+// The env var NAME a provider's key lives in - never the value. `council
+// doctor` uses this to report which keys are present without ever reading
+// (or printing) what they contain.
+export function envKeyName(provider) {
+  if (provider === 'mock' || provider === 'external') return null;
+  const spec = provider === 'anthropic' ? ANTHROPIC : OPENAI_COMPAT[provider];
+  if (!spec) throw new Error(`Unknown provider: ${provider}`);
+  return spec.key;
+}
+
+async function withRetry(fn, { tries = 3, label = '' } = {}) {
+  let last;
+  for (let i = 0; i < tries; i++) {
+    try { return await fn(); }
+    catch (err) {
+      last = err;
+      // Do not burn retries on a request that will never succeed.
+      if (err.status && err.status !== 429 && err.status < 500) throw err;
+      const wait = 1500 * Math.pow(2, i);
+      process.stderr.write(`  retry ${i + 1}/${tries} ${label}: ${err.message} (waiting ${wait}ms)\n`);
+      await new Promise(r => setTimeout(r, wait));
+    }
+  }
+  throw last;
+}
+
+async function post(url, headers, body, label) {
+  return withRetry(async () => {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const detail = (await res.text()).slice(0, 600);
+      const err = new Error(`HTTP ${res.status} ${detail}`);
+      err.status = res.status;
+      throw err;
+    }
+    return res.json();
+  }, { label });
+}
+
+async function callAnthropic({ model, system, messages, maxTokens, temperature, extra }) {
+  const key = keyFor('anthropic');
+  if (!key) throw new Error('ANTHROPIC_API_KEY not set');
+  const json = await post(
+    `${ANTHROPIC.base}/messages`,
+    { 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+    {
+      model,
+      system,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+      max_tokens: maxTokens,
+      ...(temperature === undefined ? {} : { temperature }),
+      // e.g. { thinking: { type: 'disabled' } } - Claude 5's thinking is
+      // adaptive by default, counts against max_tokens, and is not text.
+      ...(extra || {}),
+    },
+    `anthropic/${model}`
+  );
+  const text = (json.content || [])
+    .filter(b => b.type === 'text')
+    .map(b => b.text)
+    .join('');
+  return {
+    text,
+    usage: {
+      input: json.usage?.input_tokens ?? 0,
+      output: json.usage?.output_tokens ?? 0,
+      thinking: json.usage?.output_tokens_details?.thinking_tokens ?? 0,
+      stop: json.stop_reason ?? null,
+    },
+    provider: 'anthropic',
+    model,
+  };
+}
+
+async function callOpenAICompat(provider, { model, system, messages, maxTokens, temperature, extra }) {
+  const spec = OPENAI_COMPAT[provider];
+  const key = keyFor(provider);
+  if (!key) throw new Error(`${spec.key} not set`);
+  const json = await post(
+    `${spec.base}/chat/completions`,
+    { authorization: `Bearer ${key}` },
+    {
+      model,
+      messages: [{ role: 'system', content: system }, ...messages],
+      max_completion_tokens: maxTokens,
+      ...(temperature === undefined ? {} : { temperature }),
+      // Per-seat escape hatch for a provider's own non-standard fields (e.g.
+      // Qwen3.5's chat_template_kwargs.enable_thinking on Together). Kept
+      // generic rather than provider-specific branching in this adapter.
+      ...(extra || {}),
+    },
+    `${provider}/${model}`
+  );
+  return {
+    text: json.choices?.[0]?.message?.content ?? '',
+    usage: {
+      input: json.usage?.prompt_tokens ?? 0,
+      output: json.usage?.completion_tokens ?? 0,
+      thinking: json.usage?.completion_tokens_details?.reasoning_tokens ?? 0,
+      stop: json.choices?.[0]?.finish_reason ?? null,
+    },
+    provider,
+    model,
+  };
+}
+
+export async function call(provider, opts) {
+  if (provider === 'mock') return callMock(opts);
+  if (provider === 'external') throw new Error('external seats are answered by writing <label>.md into the run folder, never called');
+  if (provider === 'anthropic') return callAnthropic(opts);
+  if (OPENAI_COMPAT[provider]) return callOpenAICompat(provider, opts);
+  throw new Error(`Unknown provider: ${provider}`);
+}