the-high-council 0.6.0

package/src/integrity.js

@@ -0,0 +1,48 @@
+// Prompt-file truncation integrity (v2 plan §10 Phase 2 item 4, DEEPSEEK-2 / GLM-2).
+//
+// Real incident: a 61,000-token NEEDS-<stage>.md was cut off when a driving session
+// tried to read its own prompt back. The session could not see what it was actually
+// being asked. That is a read/write correctness bug, independent of size or cost -
+// this module closes it with a footer marker any generated prompt file carries, and
+// a read-side check that raises a loud warning rather than silently proceeding when
+// the marker is missing or doesn't match the actual content.
+import { createHash } from 'node:crypto';
+
+const FOOTER_RE = /\n<!-- INTEGRITY: lines=(\d+) bytes=(\d+) sha256=([0-9a-f]{12}) -->\n?$/;
+
+export function fingerprint(content) {
+  const lines = content.split('\n').length;
+  const bytes = Buffer.byteLength(content, 'utf8');
+  const sha256 = createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 12);
+  return { lines, bytes, sha256 };
+}
+
+/** Append an integrity footer to `content`, computed over `content` itself (before the footer). */
+export function withIntegrityFooter(content) {
+  const { lines, bytes, sha256 } = fingerprint(content);
+  return `${content}\n<!-- INTEGRITY: lines=${lines} bytes=${bytes} sha256=${sha256} -->\n`;
+}
+
+/**
+ * Verify a file written by withIntegrityFooter(). Returns { ok: true } when the footer
+ * is present and matches the body it's attached to, or { ok: false, warning } naming
+ * exactly what's wrong (missing footer vs. a mismatched count/hash - the second is the
+ * truncation/corruption signature, the first means this file predates the fix or was
+ * never covered by it).
+ */
+export function verifyIntegrityFooter(fileContent) {
+  const match = fileContent.match(FOOTER_RE);
+  if (!match) {
+    return { ok: false, warning: 'no integrity footer found - this file was not written with an integrity marker, or the marker itself was truncated away' };
+  }
+  const [footerLine, expectedLines, expectedBytes, expectedSha] = match;
+  const body = fileContent.slice(0, fileContent.length - footerLine.length);
+  const actual = fingerprint(body);
+  if (String(actual.lines) !== expectedLines || String(actual.bytes) !== expectedBytes || actual.sha256 !== expectedSha) {
+    return {
+      ok: false,
+      warning: `integrity footer does not match this file's actual content - it looks truncated or corrupted (expected lines=${expectedLines} bytes=${expectedBytes} sha256=${expectedSha}, got lines=${actual.lines} bytes=${actual.bytes} sha256=${actual.sha256})`,
+    };
+  }
+  return { ok: true };
+}

package/src/key-redaction.js

@@ -0,0 +1,97 @@
+// v5 §1 candidate 11: scan task files and chain configs for text shaped like a real API key
+// before it is ever committed or shared. BYOK means the user's own keys are the entire trust
+// boundary - nothing currently stops one from ending up pasted into a task file by accident, and
+// this repo is public.
+//
+// Read-only, offline, no network call. The match location is reported; the matched text itself
+// never is - printing the very thing you're trying to keep out of a shared log defeats the scan.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+// Each pattern names the provider shape it targets and requires enough length/character variety
+// to make a legitimate hex-looking string (a run ID, a git SHA, a content hash) an unlikely
+// match. Deliberately conservative: a missed key is a false negative the user still owns; a
+// false positive on every SHA in every commit message would make the scan noise the maintainer
+// (and every stranger who runs it) learns to ignore.
+const KEY_PATTERNS = [
+  { name: 'OpenAI-style (sk-...)', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+  { name: 'OpenAI project-scoped (sk-proj-...)', re: /\bsk-proj-[A-Za-z0-9_-]{20,}\b/g },
+  { name: 'Anthropic (sk-ant-...)', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  { name: 'Google AI (AIza...)', re: /\bAIza[A-Za-z0-9_-]{30,}\b/g },
+  { name: 'xAI (xai-...)', re: /\bxai-[A-Za-z0-9]{20,}\b/g },
+  { name: 'Groq (gsk_...)', re: /\bgsk_[A-Za-z0-9]{20,}\b/g },
+  { name: 'Mistral (32 hex chars, mistral context only)', re: /\b[a-f0-9]{32}\b/g, contextRe: /mistral/i },
+  { name: 'generic Bearer-token assignment', re: /\b(?:api[_-]?key|authorization|bearer)\s*[:=]\s*["']?[A-Za-z0-9_-]{24,}["']?/gi },
+];
+
+// Run IDs (`2026-09-13T18-01-29-810Z`), git SHAs standing alone, and UUIDs are the legitimate
+// hex-looking content this project's own files are full of - excluding them by shape, not by
+// location, keeps the scan honest across any file it's pointed at.
+const KNOWN_SAFE = [
+  /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/,           // run folder timestamp
+  /^[0-9a-f]{7,8}$/,                                         // a short git SHA
+  /^[0-9a-f]{40}$/,                                          // a full git SHA (never 32 - that's an MD5-shaped length this scan deliberately still treats as key-shaped in provider context)
+];
+
+function isKnownSafe(match) {
+  return KNOWN_SAFE.some(re => re.test(match));
+}
+
+// Scans one file's text, returning `{ line, column, pattern }` for each match - never the
+// matched substring itself.
+export function scanText(text, filename = '') {
+  const hits = [];
+  const lines = text.split('\n');
+  for (const pattern of KEY_PATTERNS) {
+    if (pattern.contextRe && !pattern.contextRe.test(filename) && !pattern.contextRe.test(text)) continue;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      pattern.re.lastIndex = 0;
+      let m;
+      while ((m = pattern.re.exec(line))) {
+        if (isKnownSafe(m[0])) continue;
+        hits.push({ line: i + 1, column: m.index + 1, pattern: pattern.name });
+      }
+    }
+  }
+  return hits;
+}
+
+const SCANNABLE_EXT = new Set(['.md', '.json', '.txt', '.yaml', '.yml', '.js']);
+
+function listFiles(root) {
+  const out = [];
+  const walk = dir => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === 'runs') continue;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (SCANNABLE_EXT.has(extname(e.name))) out.push(p);
+    }
+  };
+  const st = statSync(root, { throwIfNoEntry: false });
+  if (!st) return out;
+  if (st.isDirectory()) walk(root); else out.push(root);
+  return out;
+}
+
+/**
+ * Scan every task file and chain config under `roots` (task files, `chains/`) for key-shaped
+ * text. Returns `{ findings: [{ file, line, column, pattern }], filesScanned }`. Never reads or
+ * returns the matched substring - only its location and which pattern it matched.
+ */
+export function scanArtifacts(roots) {
+  const findings = [];
+  let filesScanned = 0;
+  for (const root of roots) {
+    for (const file of listFiles(root)) {
+      filesScanned++;
+      let text;
+      try { text = readFileSync(file, 'utf8'); } catch { continue; }
+      for (const hit of scanText(text, file)) findings.push({ file, ...hit });
+    }
+  }
+  return { findings, filesScanned };
+}

package/src/mcp/server.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// The High Council as an MCP server: Claude Code (or any MCP client) as command and
+// control of the harness. Stdio transport, no network. Tools mirror the CLI:
+// start a run, watch it, read what it produced, grade a draft panel-only,
+// price a chain. Runs are spawned detached so a long run outlives the tool
+// call; the client polls with run_status.
+//
+//   claude mcp add high-council -- npx -y the-high-council
+//   from a clone: claude mcp add high-council -- node /absolute/path/to/src/mcp/server.js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { spawn, execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, existsSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSections, flatten, parseLedger, words } from '../ui/parse.js';
+import { spendReport, costToday } from '../spend.js';
+import { stageKindOf, buildStageContract, renderStagePromptBundle } from '../stage-contract.js';
+import { verifyIntegrityFooter } from '../integrity.js';
+import { generateResumeBrief } from '../resume-brief.js';
+import { verdictStats } from '../verdict-stats.js';
+import { checkClaimStaleness } from '../peer-claim.js';
+import { submitStageAnswer } from '../stage-submission.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// Same split as the CLI: `pkg` ships with the package (chains/, the CLI
+// itself), `work` belongs to the user. An MCP client launches this server with
+// the user's project as cwd, so task files and run output land where they can
+// find them rather than inside node_modules. In a clone the two are identical.
+const pkg = resolve(here, '../..');
+const work = process.cwd();
+const runsDir = join(work, 'runs');
+const cli = join(pkg, 'src', 'cli.js');
+
+const text = s => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 2) }] });
+const safeRun = id => /^[0-9TZ-]+$/.test(id) && existsSync(join(runsDir, id));
+const readJson = p => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+// What a run has spent and what it has left. Source of truth is report.json
+// once the run finished; while it is still running (or was stopped short)
+// the per-stage <label>.usage.json files are the only record, so they are
+// summed directly.
+function budgetOf(dir, report) {
+  const stopped = readJson(join(dir, 'STOPPED-budget.json'));
+  let spent = report?.totals?.usd;
+  if (spent === undefined || spent === null) {
+    spent = !existsSync(dir) ? 0 : readdirSync(dir)
+      .filter(f => f.endsWith('.usage.json'))
+      .reduce((sum, f) => sum + (readJson(join(dir, f))?.usd ?? 0), 0);
+  }
+  const cap = report?.maxUsd ?? stopped?.capUsd ?? readJson(join(dir, 'run.json'))?.maxUsd ?? null;
+  return {
+    spentUsd: spent,
+    capUsd: cap,
+    remainingUsd: cap === null || cap === undefined ? null : Math.max(0, cap - spent),
+    stoppedByCap: stopped ? { stage: stopped.stoppedAt, seat: stopped.seat, projectedStageUsd: stopped.projectedStageUsd } : null,
+  };
+}
+
+function runSummary(id) {
+  const dir = join(runsDir, id);
+  const report = readJson(join(dir, 'report.json'));
+  const log = existsSync(join(dir, 'run.log')) ? readFileSync(join(dir, 'run.log'), 'utf8') : '';
+  const last = log.trim().split('\n').slice(-3).join(' | ');
+  const alive = isAlive(id);
+  const budget = budgetOf(dir, report);
+  return {
+    id,
+    chain: report?.chain || (log.match(/^chain: (\S+)/m) || [])[1] || null,
+    task: report?.task || (log.match(/^task: +(\S+)/m) || [])[1] || null,
+    state: report ? (report.passed ? 'done: every lab signed off' : 'done: open objections')
+      : budget.stoppedByCap ? `stopped: per-run spend cap reached before stage ${budget.stoppedByCap.stage} - resume with a higher --max-usd`
+      : waiting(dir) ? `paused: waiting for external stage ${waiting(dir)}`
+      : alive ? 'running'
+      : 'stopped without a report (crashed, killed, or paused and answered but not resumed)',
+    usd: report?.totals?.usd ?? null,
+    budget,
+    signoff: report?.signoff ?? null,
+    scoreboard: report?.scoreboard?.labs ?? null,
+    waitingFor: existsSync(dir) ? readdirSync(dir).filter(f => f.startsWith('NEEDS-')).map(f => f.slice(6, -3)).filter(l => !existsSync(join(dir, `${l}.md`))) : [],
+    files: existsSync(dir) ? readdirSync(dir).filter(f => !f.endsWith('.usage.json')).sort() : [],
+    lastLogLines: last,
+  };
+}
+
+function waiting(dir) {
+  if (!existsSync(dir)) return null;
+  const w = readdirSync(dir).filter(f => f.startsWith('NEEDS-')).map(f => f.slice(6, -3)).filter(l => !existsSync(join(dir, `${l}.md`)));
+  return w[0] || null;
+}
+
+function isAlive(id) {
+  try {
+    const out = execFileSync('pgrep', ['-af', 'src/cli.js'], { encoding: 'utf8' });
+    // The run id is not on the command line; match by the newest cli process
+    // whose run.log is this run's. Cheap approximation: any cli.js alive and
+    // this run has no report yet.
+    return out.trim().length > 0 && !existsSync(join(runsDir, id, 'report.json'));
+  } catch { return false; }
+}
+
+const server = new McpServer({ name: 'the-high-council', version: '0.3.0' });
+
+server.tool('list_chains', 'Chains available to run, with their description and worst-case price from a dry run.', {}, async () => {
+  const chains = readdirSync(join(pkg, 'chains')).filter(f => f.endsWith('.json')).map(f => {
+    const c = readJson(join(pkg, 'chains', f));
+    return { name: c.name, description: c.description, maxRounds: c.maxRounds, signoff: c.signoff || 'first', proposals: !!c.proposals, debate: !!c.debate, handoff: !!c.handoff };
+  });
+  return text(chains);
+});
+
+server.tool('dry_run', 'Price a chain without calling any model.', { chain: z.string() }, async ({ chain }) => {
+  const out = execFileSync('node', [cli, '--chain', chain, '--dry-run'], { encoding: 'utf8', cwd: work });
+  return text(out);
+});
+
+server.tool('start_run', 'Start a harness run in the background. Returns the run id to poll with run_status. task is a path relative to your working directory (tasks/x.md) or absolute; context is optional (context/war-of-love). draft + from_run + rounds=1 makes a panel-only grading pass.', {
+  chain: z.string(),
+  task: z.string(),
+  context: z.string().optional(),
+  draft: z.string().optional().describe('path to a draft to review instead of building one'),
+  from_run: z.string().optional().describe('reuse this earlier run\'s criteria'),
+  rounds: z.number().int().min(1).max(5).optional(),
+  max_usd: z.number().min(0).optional().describe('per-run spend ceiling in USD. Defaults to MAX_USD_PER_RUN or $5. Pass 0 for no ceiling. The run stops cleanly before any stage that could breach it, and resumes with a higher ceiling.'),
+}, async ({ chain, task, context, draft, from_run, rounds, max_usd }) => {
+  const args = [cli, '--chain', chain, '--task', resolve(work, task)];
+  if (context) args.push('--context', resolve(work, context));
+  if (draft) args.push('--draft', resolve(work, draft));
+  if (from_run) args.push('--from-run', resolve(work, from_run));
+  if (rounds) args.push('--rounds', String(rounds));
+  if (max_usd !== undefined) args.push('--max-usd', max_usd === 0 ? 'none' : String(max_usd));
+  mkdirSync(runsDir, { recursive: true });
+  const before = new Set(readdirSync(runsDir));
+  const logPath = join(work, `council-${Date.now()}.log`);
+  const fd = (await import('node:fs')).openSync(logPath, 'a');
+  const child = spawn('node', args.slice(0), { cwd: work, detached: true, stdio: ['ignore', fd, fd] });
+  child.unref();
+  // The run creates its folder within a second or two; find it.
+  let id = null;
+  for (let i = 0; i < 20 && !id; i++) {
+    await new Promise(r => setTimeout(r, 250));
+    id = readdirSync(runsDir).find(d => !before.has(d)) || null;
+  }
+  return text({ started: true, pid: child.pid, run: id, log: logPath, note: id ? 'poll run_status(run)' : 'run folder not seen yet; call list_runs shortly' });
+});
+
+server.tool('external_prompt', 'When a run is paused at an external seat: the exact system and user prompt that stage needs answered. Answer with submit_stage.', { run: z.string() }, async ({ run }) => {
+  if (!safeRun(run)) return text({ error: 'no such run' });
+  const dir = join(runsDir, run);
+  const label = waiting(dir);
+  if (!label) return text({ error: 'this run is not waiting for an external stage', state: runSummary(run).state });
+  const prompt = readFileSync(join(dir, `NEEDS-${label}.md`), 'utf8');
+  // v2 plan §10 Phase 2 item 4: a large prompt file silently truncated by a read is the
+  // exact failure this project already suffered once - a session that could not see its
+  // own prompt. Never hand that content back looking fine when it isn't.
+  const check = verifyIntegrityFooter(prompt);
+  // v3 plan §1: a claim's staleness/contest status alongside the prompt this tool already
+  // returns - no new tool call needed to see whether this stage is stalled or contested.
+  const claimWarning = checkClaimStaleness(dir, label);
+  return text({ run, stage: label, prompt, answerWith: `submit_stage(run, "${label}", <text>)`, ...(check.ok ? {} : { integrity_warning: check.warning }), claim: claimWarning || { type: 'none' } });
+});
+
+// v2 plan §3 (~/Projects/relay/runs/2026-09-11T12-19-34-184Z/deliverable.md). A driving
+// session with other work sharing its context can hand this one file's path to a fresh
+// subagent instead of authoring the external stage inline itself - see docs/dispatch-pattern.md.
+// Deliberately does NOT inline the stage's own system/user prompt (that is what NEEDS-<stage>.md
+// already holds, and can be tens of thousands of tokens - the arbitrage this project protects,
+// not a bug); it is referenced by path so the bundle itself stays small enough for a fresh
+// subagent's own context to hold comfortably, and reads it in full only if it chooses to delegate.
+server.tool('prepare_stage_prompt', 'For a run paused at an external seat: write stage_prompt.md, a self-contained bundle a fresh subagent can act on with zero prior context, so a driving session can dispatch the stage instead of authoring it inline. Fork a subagent, give it only this file\'s path; take its returned deliverable back to submit_stage.', { run: z.string() }, async ({ run }) => {
+  if (!safeRun(run)) return text({ error: 'no such run' });
+  const dir = join(runsDir, run);
+  const label = waiting(dir);
+  if (!label) return text({ error: 'this run is not waiting for an external stage', state: runSummary(run).state });
+  const runMeta = readJson(join(dir, 'run.json'));
+  const chainConfig = runMeta ? readJson(join(pkg, 'chains', `${runMeta.chain}.json`)) : null;
+  const kind = stageKindOf(label);
+  if (!chainConfig || !kind) return text({ error: 'could not resolve this stage to a known stage kind - the chain config or stage label is not one prepare_stage_prompt recognises', label });
+  const contract = buildStageContract(chainConfig, kind);
+  const taskText = runMeta?.task && existsSync(runMeta.task) ? readFileSync(runMeta.task, 'utf8') : '(task file not found on disk - see run.json for its original path)';
+  const needsPath = join(dir, `NEEDS-${label}.md`);
+  const boardPath = join(dir, 'BOARD.md');
+  const references = [needsPath, ...(existsSync(boardPath) ? [boardPath] : []), ...(runMeta?.context ? [runMeta.context] : [])];
+  const bundle = renderStagePromptBundle({ contract, taskText, chainName: runMeta?.chain, label, run, references });
+  writeFileSync(join(dir, 'stage_prompt.md'), bundle);
+  return text({ written: join(dir, 'stage_prompt.md'), stage: label, dispatch: 'Fork a subagent and give it only this file\'s path - not its contents inline.' });
+});
+
+server.tool('submit_stage', 'Write the answer for an external stage into the run folder, then resume the run in the background. The stage must be the one external_prompt reported. claimed_by is optional (v3 §1): a self-declared peer-session name, recorded as this stage\'s claim; every check here is warn-only and never blocks the write, so a caller that omits it sees exactly today\'s behavior.', { run: z.string(), stage: z.string().regex(/^[a-z0-9-]+$/), content: z.string(), claimed_by: z.string().optional().describe('self-declared peer-session name, recorded as this stage\'s claim before the answer is written') }, async ({ run, stage, content, claimed_by }) => {
+  if (!safeRun(run)) return text({ error: 'no such run' });
+  const dir = join(runsDir, run);
+  // A stage this run never paused for is still rejected outright - that is not one of §1's
+  // three warn-only checks, it is the pre-existing safety check this tool already had. What
+  // changes for §1 is narrower: a stage that WAS an external pause point, and already has an
+  // answer on disk (a late/duplicate submission), is no longer rejected here - it falls through
+  // to the duplicate_answer warning below instead, so neither answer is silently lost.
+  const wasExternalStage = existsSync(join(dir, `NEEDS-${stage}.md`));
+  const alreadyAnswered = existsSync(join(dir, `${stage}.md`));
+  if (!wasExternalStage || (!alreadyAnswered && waiting(dir) !== stage)) {
+    return text({ error: `run is not waiting for "${stage}"`, waitingFor: waiting(dir) });
+  }
+
+  // v3 plan §1: three warn-only checks, all evaluated before the answer file is accepted as
+  // final - none of them reject the write, none change submit_stage's existing required
+  // arguments or return shape for a caller that omits claimed_by. Factored into
+  // src/stage-submission.js so it's testable without the MCP transport (test/peer-claim.test.js).
+  const runMeta = readJson(join(dir, 'run.json'));
+  const chainConfig = runMeta ? readJson(join(pkg, 'chains', `${runMeta.chain}.json`)) : null;
+  const { warnings, writtenFile, isDuplicate } = submitStageAnswer(dir, stage, content, { claimedBy: claimed_by, chainConfig });
+
+  if (isDuplicate) {
+    return text({ written: `${stage}.late.md`, words: words(content), warnings, note: `"${stage}.md" already existed and was left untouched; this submission was kept as "${stage}.late.md" for a human or driving session to resolve.` });
+  }
+  return text({ written: `${stage}.md`, words: words(content), ...(warnings.length ? { warnings } : {}), ...(await resume(run)) });
+});
+
+server.tool('resume_run', 'Resume a paused run after its external stage was answered (submit_stage does this for you), or a run stopped by the spend cap (pass a higher max_usd). Completed stages replay from disk and cost nothing.', { run: z.string(), max_usd: z.number().min(0).optional().describe('raise the per-run ceiling for the rest of this run. 0 removes it.') }, async ({ run, max_usd }) => {
+  if (!safeRun(run)) return text({ error: 'no such run' });
+  return text(await resume(run, max_usd));
+});
+
+async function resume(run, maxUsd) {
+  const logPath = join(work, `council-${Date.now()}.log`);
+  const fs = await import('node:fs');
+  const fd = fs.openSync(logPath, 'a');
+  const resumeArgs = [cli, '--resume', join('runs', run)];
+  if (maxUsd !== undefined) resumeArgs.push('--max-usd', maxUsd === 0 ? 'none' : String(maxUsd));
+  const child = spawn('node', resumeArgs, { cwd: work, detached: true, stdio: ['ignore', fd, fd] });
+  child.unref();
+  return { resumed: true, run, pid: child.pid, log: logPath, note: 'poll run_status(run); it may pause again at the next external stage' };
+}
+
+server.tool('spend_report', 'What every run has cost across a window of days, not just one run. Derived from the run folders on disk - nothing is recorded anywhere else and nothing leaves this machine. Use this to answer "what have I spent today" before starting another run.', {
+  days: z.number().min(0.1).max(365).optional().describe('how far back to look, in days. Defaults to 1.'),
+}, async ({ days = 1 }) => {
+  const r = spendReport(runsDir, { days });
+  // v2 plan §8, narrowed per DECISIONS.md: session_cost_today, by local calendar day with
+  // a per-model breakdown, additive on this existing tool rather than a new one or a ledger.
+  const today = costToday(runsDir);
+  return text({
+    since: r.since.toISOString(),
+    days,
+    totalUsd: r.totalUsd,
+    runs: r.runs.map(x => ({ id: x.id, chain: x.chain, usd: x.usd, state: x.state })),
+    count: r.count,
+    ...(r.unreadable ? { unreadableRunFolders: r.unreadable } : {}),
+    ...(r.note ? { note: r.note } : {}),
+    session_cost_today: { totalUsd: today.totalUsd, count: today.count, perModel: today.perModel },
+    source: 'derived from runs/ on disk; no ledger is kept and nothing is transmitted',
+  });
+});
+
+server.tool('verdict_stats', 'How the debate mechanism itself is doing, per chain and per lab, across a window of days: sign-off rate, mean rounds to sign-off, objections raised, withdrawals vs accepted proposals, dropouts, unparseable replies, shape-only critique rounds (rounds spent entirely on document shape rather than substance), per-lab independence skew (novel-objection rate, solo-signoff rate, a low-independence flag), mean cost and wall time per run, and the largest prompt file per stage type. Derived from report.json and *.usage.json on disk - nothing is recorded anywhere else and nothing leaves this machine. Descriptive only: never reweights a panel or changes a verdict.', {
+  days: z.number().min(0.1).max(3650).optional().describe('how far back to look, in days. Defaults to 30.'),
+}, async ({ days = 30 }) => {
+  const r = verdictStats(runsDir, { days });
+  return text({
+    since: r.since.toISOString(),
+    days,
+    runsSeen: r.runsSeen,
+    chains: r.chains,
+    labs: r.labs,
+    largestPrompts: r.largestPrompts,
+    ...(r.unreadable ? { unreadableRunFolders: r.unreadable } : {}),
+    ...(r.note ? { note: r.note } : {}),
+    source: 'derived from runs/ on disk; no ledger is kept and nothing is transmitted',
+  });
+});
+
+server.tool('list_runs', 'Runs on disk, newest first, with state and cost.', { limit: z.number().int().min(1).max(100).optional() }, async ({ limit = 15 }) => {
+  if (!existsSync(runsDir)) return text([]);
+  const ids = readdirSync(runsDir).filter(d => statSync(join(runsDir, d)).isDirectory()).sort().reverse().slice(0, limit);
+  return text(ids.map(runSummary));
+});
+
+server.tool('run_status', 'State of one run: stage reached, panel verdicts, scoreboard, files produced, cost. Pass brief=true for a short, regenerated-on-demand resume brief instead - what a returning session with fresh context needs to re-enter the run.', { run: z.string(), brief: z.boolean().optional() }, async ({ run, brief }) => {
+  if (!safeRun(run)) return text({ error: 'no such run' });
+  if (brief) {
+    // v2 plan §5: always regenerated from run.json + files on disk, never itself
+    // authoritative, so RESUME.md can never become a stale source of truth.
+    const dir = join(runsDir, run);
+    const runMeta = readJson(join(dir, 'run.json'));
+    const chainConfig = runMeta ? readJson(join(pkg, 'chains', `${runMeta.chain}.json`)) : null;
+    const rb = generateResumeBrief({ runId: run, dir, runMeta, chainConfig });
+    writeFileSync(join(dir, 'RESUME.md'), rb);
+    return text(rb);
+  }
+  const s = runSummary(run);
+  const log = readFileSync(join(runsDir, run, 'run.log'), 'utf8');
+  s.keyLines = log.split('\n').filter(l => /^(Stage:|Round|  [a-z0-9-]+\/.*: (SIGNED OFF|\d+ failure)|    FAILED:|  board:|  .*post\(s\)|panel:|verdict:|labs:|cost:|Error)/.test(l)).slice(-40);
+  return text(s);
+});
+
+server.tool('read_run_file', 'Read a file from a run folder (deliverable.md, BOARD.md, HANDOFF.md, proposals.md, build.md, revise-1.md, panel-1-<lab>.md, run.log, report.json).', { run: z.string(), file: z.string() }, async ({ run, file }) => {
+  if (!safeRun(run) || !/^[A-Za-z0-9._-]+$/.test(file)) return text({ error: 'no such run or bad file name' });
+  const p = join(runsDir, run, file);
+  if (!existsSync(p)) return text({ error: 'no such file', files: readdirSync(join(runsDir, run)) });
+  return text(readFileSync(p, 'utf8'));
+});
+
+server.tool('plan_outline', 'Section tree of a run\'s deliverable (or any markdown file) with word counts and the build-volume heuristic, plus the scope ledger if present.', { run: z.string().optional(), file: z.string().optional().describe('absolute path to a markdown file, instead of a run') }, async ({ run, file }) => {
+  let md;
+  if (file) md = readFileSync(resolve(file), 'utf8');
+  else if (run && safeRun(run)) md = readFileSync(join(runsDir, run, 'deliverable.md'), 'utf8');
+  else return text({ error: 'give run or file' });
+  const tree = parseSections(md);
+  const rows = flatten(tree).map(s => ({ path: s.path, words: s.words, volume: s.volume.score, files: s.volume.files.length, scripts: s.volume.scripts.length }));
+  return text({ words: words(md), sections: rows, ledger: parseLedger(md) });
+});
+
+server.tool('write_task', 'Write or overwrite a task file under tasks/ (the request the harness plans against).', { name: z.string().regex(/^[a-z0-9-]+$/), content: z.string() }, async ({ name, content }) => {
+  const p = join(work, 'tasks', `${name}.md`);
+  writeFileSync(p, content);
+  return text({ written: p, words: words(content) });
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/name-lint.js

@@ -0,0 +1,186 @@
+// v6 §6: the public-naming lint. Scans the whole repository for name
+// patterns from a forbidden-name blocklist and fails loudly if any appear
+// anywhere in the shipped tree.
+//
+// The engineering problem this module exists to solve: the lint needs to
+// know the forbidden names to check for them, but the whole point is that a
+// public MIT repo must never carry those names itself - not even hashed
+// alongside a "these are forbidden" comment, since a hash next to a plain
+// list of five approved names is still a place a real name could get pasted
+// by accident. So this module ships knowing NOTHING about any specific
+// third-party name. It is a generic scanner over SHA-256 hashes of
+// lowercase, whitespace-normalized candidate name spans:
+//
+//   - DEFAULT_FORBIDDEN_HASHES here is empty. This repo's own author has an
+//     internal, third-party-derived naming shorthand (Dune character names,
+//     per the plan this module was built from) - that list is never typed
+//     into this file, this repo, or any session's output. It lives only in
+//     the author's own local, gitignored config (see loadForbiddenHashes()).
+//   - An operator adds their own forbidden set - their own trademark risks,
+//     not just this author's - by pointing COUNCIL_FORBIDDEN_NAMES_FILE (or
+//     the `forbiddenNamesFile` option) at a local JSON file of plain-text
+//     names. This module hashes them at load time; only the hash ever
+//     participates in a comparison after that point.
+//   - Without an operator-local file, the scan runs against the (empty)
+//     default set and finds nothing - which is honest: there is nothing to
+//     check against until an operator supplies their own list. The lint
+//     test in this repo's own suite exists to prove the MECHANISM works
+//     (via synthetic, clearly-fictional test names, never real ones), not
+//     to prove any specific name is absent - that guarantee is only as good
+//     as whatever forbidden list is actually loaded when it runs.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+export const DEFAULT_FORBIDDEN_HASHES = Object.freeze([]);
+// COUNCIL_FORBIDDEN_NAMES_FILE takes any path you give it - nothing here
+// enforces that it lives under .council/. That directory is only a
+// convention this repo's .gitignore happens to cover; if you point this at
+// a path outside it, gitignore gives you no protection and it's on you not
+// to `git add` it (bug-audit finding, 2026-09-13 - noted so it isn't
+// mistaken for an enforced guarantee).
+const ENV_FORBIDDEN_FILE = 'COUNCIL_FORBIDDEN_NAMES_FILE';
+
+// Generated, vendored, or binary content - never shipped source a reader
+// browses, and in runs/'s case, real user data this project's own rules
+// already keep out of the repo. `.git` and `node_modules` are structural.
+// Every entry here is also gitignored (see .gitignore), so a real checkout
+// never has anything to skip in the first place - this list only matters
+// for a working tree with local, uncommitted output sitting in it.
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'runs', '.council']);
+// Extensions worth reading as text. Anything else (images, fonts, lockfiles'
+// noise) is skipped rather than mis-decoded.
+const TEXT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.json', '.md', '.html', '.txt', '.yml', '.yaml', '.sh']);
+
+export function hashName(name) {
+  // NFC-normalize before hashing: an accented name typed in decomposed form
+  // (NFD) must hash identically to the same name in precomposed form (NFC),
+  // or a forbidden name could slip past the check purely by which Unicode
+  // form happened to get pasted in (bug-audit finding, 2026-09-13).
+  return createHash('sha256').update(String(name).trim().toLowerCase().normalize('NFC')).digest('hex');
+}
+
+/**
+ * The forbidden-hash set to scan against: DEFAULT_FORBIDDEN_HASHES (empty,
+ * see module comment) plus any names in an operator-local file, hashed here
+ * so the plain text never leaves this function. A missing or unreadable
+ * file degrades to the default set - never throws, matching this project's
+ * existing degrade-not-throw convention (spend.js, verdict-stats.js).
+ */
+export function loadForbiddenHashes({ forbiddenNamesFile, readFile = defaultReadFile } = {}) {
+  const path = forbiddenNamesFile ?? process.env[ENV_FORBIDDEN_FILE];
+  const hashes = new Set(DEFAULT_FORBIDDEN_HASHES);
+  if (!path) return hashes;
+  try {
+    const names = JSON.parse(readFile(path));
+    if (Array.isArray(names)) for (const n of names) hashes.add(hashName(n));
+  } catch { /* no local list, or it's unreadable - scan with the default set */ }
+  return hashes;
+}
+
+function defaultReadFile(path) {
+  return readFileSync(path, 'utf8');
+}
+
+function walk(dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) { walk(full, out); continue; }
+    if (entry.isFile() && TEXT_EXTENSIONS.has(extname(entry.name))) out.push(full);
+  }
+  return out;
+}
+
+// One Unicode letter/hyphen word per match, with the line it starts on.
+// \p{L} rather than A-Za-z (bug-audit finding, 2026-09-13): a name
+// containing a diacritic must still tokenize as one word, not fragment at
+// the accented character. No apostrophe in the class: a name sitting inside
+// a JS/JSON string literal ('Zorblax Prime') or Markdown text would
+// otherwise absorb the closing quote into the last word ("Prime'"),
+// silently breaking the hash match against the clean name. The rare loss
+// (an apostrophe-containing name like "O'Brien" splits into two spans) is a
+// smaller price than every quoted occurrence failing to match at all.
+const WORD_RE = /\p{L}[\p{L}-]*/gu;
+
+function wordsWithLines(text) {
+  const words = [];
+  let line = 1;
+  let lastIndex = 0;
+  for (const m of text.matchAll(WORD_RE)) {
+    line += countNewlines(text, lastIndex, m.index);
+    lastIndex = m.index;
+    words.push({ word: m[0], line });
+  }
+  return words;
+}
+
+function countNewlines(text, from, to) {
+  let n = 0;
+  for (let i = from; i < to; i++) if (text[i] === '\n') n++;
+  return n;
+}
+
+// Candidate name spans: every run of 1-3 consecutive words (so a two-word
+// name like an approved persona's own "Van Gogh" pattern, or a two-word
+// forbidden name, is checked as a unit, not only word-by-word) plus every
+// single word on its own - spans deliberately cross line boundaries (a
+// two-word name split by a Markdown line-wrap must still be caught; bug-
+// audit finding, 2026-09-13), reported under the line the span STARTS on.
+// Over-generous on purpose - a scanner that only checked single words, or
+// only within one line, could miss a real name; false positives cost
+// nothing here since the comparison is against a specific hash set, not a
+// heuristic.
+function candidateSpans(words) {
+  const spans = [];
+  for (let i = 0; i < words.length; i++) {
+    spans.push({ span: words[i].word, line: words[i].line });
+    if (i + 1 < words.length) spans.push({ span: `${words[i].word} ${words[i + 1].word}`, line: words[i].line });
+    if (i + 2 < words.length) spans.push({ span: `${words[i].word} ${words[i + 1].word} ${words[i + 2].word}`, line: words[i].line });
+  }
+  return spans;
+}
+
+/**
+ * Scan every text file under `root` (recursing into every subdirectory -
+ * src/mcp/, src/ui/, docs/, chains/, tasks/, test/, all of it, not a
+ * hand-picked subset, per the exact regression a prior version of this
+ * lint hit) for any candidate name span whose hash is in `forbiddenHashes`
+ * - in file CONTENT and in every file/directory NAME on the path (a
+ * forbidden name used as a code-name for a file would otherwise never be
+ * flagged; bug-audit finding, 2026-09-13). Returns findings; never throws
+ * on an unreadable file or directory.
+ */
+export function scanForForbiddenNames(root, forbiddenHashes) {
+  const hashes = forbiddenHashes instanceof Set ? forbiddenHashes : new Set(forbiddenHashes || []);
+  const findings = [];
+  if (!hashes.size) return { findings, filesScanned: 0 };
+
+  const files = walk(root);
+  for (const file of files) {
+    // kebab-case/snake_case filenames are the common real-world shape for a
+    // code-name-as-filename - "-"/"_" split into separate words here (unlike
+    // prose content, where a hyphen usually joins one compound word) so
+    // "zorblax-prime.js" tokenizes as "zorblax", "prime", not one fused word.
+    const pathText = file.slice(root.length).replace(/[-_]/g, ' ');
+    for (const { span } of candidateSpans(wordsWithLines(pathText))) {
+      if (hashes.has(hashName(span))) {
+        findings.push({ file, line: null, span, where: 'path' });
+      }
+    }
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { continue; }
+    for (const { span, line } of candidateSpans(wordsWithLines(text))) {
+      if (hashes.has(hashName(span))) {
+        // Unlike the key-redaction scan (candidate 11), the matched text
+        // here is not a secret - it's a name already sitting in plain
+        // sight in the file being scanned, so naming it in the finding
+        // makes the failure fixable rather than a guessing game.
+        findings.push({ file, line, span, where: 'content' });
+      }
+    }
+  }
+  return { findings, filesScanned: files.length };
+}