amicus 1.0.0 → 1.2.0

package/src/cli-handlers-doctor.js

@@ -0,0 +1,173 @@
+// src/cli-handlers-doctor.js
+'use strict';
+
+const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h (mirrors model-catalog DEFAULT_MAX_AGE_MS)
+
+/** Default real helpers; tests override via deps. */
+function realDeps() {
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  return {
+    nodeVersion: process.version,
+    readApiKeys: () => require('./utils/api-key-store').readApiKeys(),
+    getConfigDir: () => require('./utils/config').getConfigDir(),
+    resolveModel: () => require('./utils/config').resolveModel(),
+    readCache: () => require('./utils/model-catalog').readCache(),
+    collectAliasSources: () => require('./utils/alias-audit').collectAliasSources(),
+    findStaleAliases: (s, c) => require('./utils/alias-audit').findStaleAliases(s, c),
+    hasOpencodeBinary: () => {
+      const { ensureNodeModulesBinInPath } = require('./utils/path-setup');
+      ensureNodeModulesBinInPath();
+      const root = path.join(__dirname, '..', 'node_modules');
+      const candidates = process.platform === 'win32'
+        ? [path.join(root, `opencode-windows-${os.arch() === 'arm64' ? 'arm64' : 'x64'}`, 'bin', 'opencode.exe'),
+           path.join(root, `opencode-windows-${os.arch() === 'arm64' ? 'arm64' : 'x64'}-baseline`, 'bin', 'opencode.exe')]
+        : [path.join(root, '.bin', 'opencode')];
+      return candidates.some(p => fs.existsSync(p));
+    },
+    getElectronPath: () => require('./sidecar/interactive').getElectronPath(),
+    discoverClaudeCodeMcps: () => require('./utils/mcp-discovery').discoverClaudeCodeMcps(),
+    discoverCoworkMcps: () => require('./utils/mcp-discovery').discoverCoworkMcps(),
+    skillInstalled: () => {
+      const dir = path.join(os.homedir(), '.claude', 'skills');
+      return fs.existsSync(path.join(dir, 'sidecar', 'SKILL.md'))
+        && fs.existsSync(path.join(dir, 'second-opinion', 'SKILL.md'));
+    },
+  };
+}
+
+/** Run one guarded check; a thrown fn becomes an error line. */
+function guard(id, name, fn) {
+  try { return fn(); }
+  catch (e) { return { id, name, status: 'error', message: e.message, hint: null }; }
+}
+
+/**
+ * Compose the health checks. Never throws.
+ * @param {object} [depsOverride]
+ * @returns {Array<{id,name,status,message,hint}>}
+ */
+function runDoctorChecks(depsOverride = {}) {
+  const d = { ...realDeps(), ...depsOverride };
+  const checks = [];
+
+  checks.push(guard('node', 'Node.js', () => {
+    const major = parseInt(String(d.nodeVersion).replace(/^v/, '').split('.')[0], 10);
+    return major >= 18
+      ? { id: 'node', name: 'Node.js', status: 'ok', message: d.nodeVersion, hint: null }
+      : { id: 'node', name: 'Node.js', status: 'error', message: `${d.nodeVersion} (need >=18)`, hint: 'Install Node 18 or newer from https://nodejs.org' };
+  }));
+
+  checks.push(guard('config-dir', 'Config directory', () => (
+    { id: 'config-dir', name: 'Config directory', status: 'ok', message: d.getConfigDir(), hint: null }
+  )));
+
+  checks.push(guard('keys', 'API keys', () => {
+    const keys = d.readApiKeys();
+    const set = Object.keys(keys).filter(k => keys[k]);
+    return set.length > 0
+      ? { id: 'keys', name: 'API keys', status: 'ok', message: `configured: ${set.join(', ')}`, hint: null }
+      : { id: 'keys', name: 'API keys', status: 'error', message: 'no provider keys configured', hint: 'amicus key <provider> <key>  (or run: amicus setup)' };
+  }));
+
+  checks.push((() => {
+    try {
+      const model = d.resolveModel();
+      return { id: 'default-model', name: 'Default model', status: 'ok', message: model, hint: null };
+    } catch (e) {
+      return { id: 'default-model', name: 'Default model', status: 'error', message: e.message || 'no default model', hint: 'amicus setup' };
+    }
+  })());
+
+  checks.push(guard('catalog', 'Model catalog', () => {
+    const cache = d.readCache();
+    if (!cache || !cache.fetchedAt) {
+      return { id: 'catalog', name: 'Model catalog', status: 'warn', message: 'no cache yet', hint: 'amicus models --refresh' };
+    }
+    const ageMs = Date.now() - cache.fetchedAt;
+    const fresh = ageMs <= MAX_CATALOG_AGE_MS;
+    const hrs = Math.round(ageMs / 3600000);
+    return fresh
+      ? { id: 'catalog', name: 'Model catalog', status: 'ok', message: `${cache.models.length} models, ${hrs}h old`, hint: null }
+      : { id: 'catalog', name: 'Model catalog', status: 'warn', message: `stale (${hrs}h old)`, hint: 'amicus models --refresh' };
+  }));
+
+  checks.push(guard('aliases', 'Model aliases', () => {
+    const cache = d.readCache();
+    const catalog = (cache && cache.models) || [];
+    const stale = d.findStaleAliases(d.collectAliasSources(), catalog);
+    return stale.length === 0
+      ? { id: 'aliases', name: 'Model aliases', status: 'ok', message: catalog.length ? 'all resolve' : 'catalog empty — not checked', hint: null }
+      : { id: 'aliases', name: 'Model aliases', status: 'warn', message: `${stale.length} stale: ${stale.map(s => s.alias).join(', ')}`, hint: 'amicus models --check' };
+  }));
+
+  checks.push(guard('opencode-bin', 'OpenCode binary', () => (
+    d.hasOpencodeBinary()
+      ? { id: 'opencode-bin', name: 'OpenCode binary', status: 'ok', message: 'found', hint: null }
+      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: 'npm install -g amicus' }
+  )));
+
+  checks.push(guard('electron', 'Electron (interactive GUI)', () => (
+    d.getElectronPath()
+      ? { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null }
+      : { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: 'not installed — headless still works', hint: 'npm install -g amicus  (reinstall to add Electron)' }
+  )));
+
+  checks.push(guard('skills', 'Skills installed', () => (
+    d.skillInstalled()
+      ? { id: 'skills', name: 'Skills installed', status: 'ok', message: '~/.claude/skills/{sidecar,second-opinion}', hint: null }
+      : { id: 'skills', name: 'Skills installed', status: 'warn', message: 'one or both skills missing', hint: 'npm install -g amicus  (re-runs the skill install)' }
+  )));
+
+  checks.push(guard('mcp', 'MCP registration', () => {
+    const code = d.discoverClaudeCodeMcps();
+    const cowork = d.discoverCoworkMcps();
+    const inCode = !!(code && code.amicus);
+    const inCowork = !!(cowork && cowork.amicus);
+    // Primary signal: Claude Code MCP registration. Cowork/Desktop is reported as bonus only.
+    if (!inCode) {
+      return { id: 'mcp', name: 'MCP registration', status: 'warn', message: 'not registered in Claude Code', hint: 'npm install -g amicus  (or install the amicus plugin)' };
+    }
+    const extra = inCowork ? ', Cowork/Desktop' : '';
+    return { id: 'mcp', name: 'MCP registration', status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
+  }));
+
+  return checks;
+}
+
+const MARK = { ok: '✓', warn: '⚠', error: '✗' }; // ✓ ⚠ ✗
+
+function renderHuman(checks) {
+  let out = 'amicus doctor\n\n';
+  for (const c of checks) {
+    out += `${MARK[c.status] || '?'} ${c.name}: ${c.message}\n`;
+    if (c.hint && c.status !== 'ok') { out += `    → ${c.hint}\n`; }
+  }
+  const errors = checks.filter(c => c.status === 'error').length;
+  const warns = checks.filter(c => c.status === 'warn').length;
+  out += `\n${errors} error(s), ${warns} warning(s).\n`;
+  return out;
+}
+
+/**
+ * `amicus doctor [--json]`. Injectable `runChecks` for tests.
+ * @param {{_:string[], json?:boolean}} args
+ * @param {(deps?:object)=>Array} [runChecks]
+ * @returns {Promise<number>} exit code
+ */
+async function handleDoctor(args, runChecks = runDoctorChecks) {
+  const useJson = !!args.json;
+  const checks = runChecks();
+  if (useJson) {
+    const { buildDoctorDoc } = require('./utils/result-schema');
+    const VERSION = require('../package.json').version;
+    const doc = buildDoctorDoc({ version: VERSION, timestamp: new Date().toISOString(), checks });
+    process.stdout.write(JSON.stringify(doc, null, 2) + '\n');
+    return doc.ok ? 0 : 1;
+  }
+  process.stdout.write(renderHuman(checks));
+  return checks.some(c => c.status === 'error') ? 1 : 0;
+}
+
+module.exports = { runDoctorChecks, handleDoctor, MAX_CATALOG_AGE_MS };

package/src/cli-handlers-run.js

@@ -0,0 +1,196 @@
+/**
+ * CLI Run Handlers (WS-2 extraction)
+ *
+ * Extracted from bin/amicus.js to keep the CLI entry point under the 300-line
+ * size gate and to make handlers unit-testable without running main().
+ *
+ * Contains: handleStart, handleFanout, handleRead
+ * Remaining inline in bin/amicus.js: handleList, handleResume, handleContinue
+ */
+
+'use strict';
+
+const { validateStartArgs } = require('./cli');
+const { validateTaskId } = require('./utils/validators');
+const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+
+/**
+ * Handle 'sidecar start' command
+ * Spec Reference: §4.1
+ */
+async function handleStart(args) {
+  const useJson = !!args.json;
+
+  // F4: --prompt-file support (XOR --prompt) and --json gating
+  if (args.prompt !== undefined || args['prompt-file'] !== undefined) {
+    const { resolvePromptSource } = require('./utils/prompt-source');
+    const promptRes = resolvePromptSource(args);
+    if (promptRes.error) { process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error })); }
+    args.prompt = promptRes.prompt;
+  }
+  if (args.json && !args['no-ui']) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --json requires --no-ui' }));
+  }
+
+  const mc = args['max-cost'];
+  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
+  }
+
+  const { model, alias } = resolveModelFromArgs(args);
+  args.model = model;
+  args.model = await validateFallbackModel(args, alias);
+
+  // Normalize agent: --agent takes precedence, otherwise use --mode
+  args.agent = args.agent || args.mode;
+
+  const validation = validateStartArgs(args);
+  if (!validation.valid) {
+    process.exit(failJson(useJson, { code: validation.code || ERROR_CODES.BAD_ARGS, message: validation.error }));
+  }
+
+  // Budget gate for solo start
+  if (!args['no-cost-gate']) {
+    const { lookupPricing } = require('./utils/pricing');
+    const { checkBudget, formatBudgetError } = require('./sidecar/budget');
+    const { loadConfig } = require('./utils/config');
+    const cfg = loadConfig() || {};
+    const soloLeg = { modelInput: alias || args.model, model: args.model, pricing: lookupPricing(args.model) };
+    const promptChars = (args.prompt && String(args.prompt).length) || 0;
+    const budget = checkBudget([soloLeg], { maxCostPerMtok: cfg.maxCostPerMtok, maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost, promptChars });
+    if (!budget.ok) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BUDGET_EXCEEDED, message: 'Error: budget gate refused the run', hint: formatBudgetError(budget) }));
+    }
+  }
+
+  const { startSidecar } = require('./index');
+
+  return await startSidecar({
+    taskId: args['task-id'],
+    model: args.model,
+    prompt: args.prompt,
+    sessionId: args['session-id'],
+    cwd: args.cwd,
+    contextTurns: args['context-turns'],
+    contextSince: args['context-since'],
+    contextMaxTokens: args['context-max-tokens'],
+    noUi: args['no-ui'],
+    timeout: args.timeout,
+    agent: args.agent,
+    mcp: args.mcp,
+    mcpConfig: args['mcp-config'],
+    thinking: args.thinking,
+    summaryLength: args['summary-length'],
+    client: args.client,
+    sessionDir: args['session-dir'],
+    foldShortcut: args['fold-shortcut'],
+    opencodePort: args['opencode-port'],
+    noMcp: args['no-mcp'],
+    excludeMcp: args['exclude-mcp'],
+    coworkProcess: args['cowork-process'],
+    position: args.position,
+    json: !!args.json,
+    modelInput: alias || null,
+  });
+}
+
+/**
+ * Handle 'amicus fanout' command (F4).
+ * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
+ * 130/143 when the wave was signal-aborted.
+ */
+async function handleFanout(args) {
+  const useJson = !!args.json;
+
+  const { resolvePromptSource } = require('./utils/prompt-source');
+  const promptRes = resolvePromptSource(args);
+  if (promptRes.error) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error }));
+  }
+  if (typeof args.models !== 'string' || !args.models.trim()) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs)' }));
+  }
+  if (args['wave-id']) {
+    const check = validateTaskId(String(args['wave-id']));
+    if (!check.valid) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
+    }
+  }
+  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --agent chat is interactive-only; fanout is headless' }));
+  }
+  if (args.timeout !== undefined && args.timeout <= 0) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --timeout must be a positive number' }));
+  }
+  const mc = args['max-cost'];
+  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
+  }
+  const { parseModelsList } = require('./sidecar/fanout');
+  if (parseModelsList(args.models).length === 0) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models must contain at least one non-empty entry' }));
+  }
+
+  // Direct require — the src/index.js public re-export is added later (Task 13)
+  const { runFanout } = require('./sidecar/fanout');
+  const { loadConfig } = require('./utils/config');
+  const cfg = loadConfig() || {};
+  const { exitCode } = await runFanout({
+    models: args.models,
+    prompt: promptRes.prompt,
+    promptMeta: promptRes.promptMeta,
+    waveId: args['wave-id'],
+    project: args.cwd || process.cwd(),
+    agent: args.agent || args.mode,
+    thinking: args.thinking,
+    timeout: args.timeout,
+    summaryLength: args['summary-length'],
+    includeContext: !args['no-context'],
+    sessionId: args['session-id'],
+    contextTurns: args['context-turns'],
+    contextSince: args['context-since'],
+    contextMaxTokens: args['context-max-tokens'],
+    mcp: args.mcp,
+    mcpConfig: args['mcp-config'],
+    noMcp: args['no-mcp'],
+    excludeMcp: args['exclude-mcp'],
+    noValidateModel: args['no-validate-model'],
+    json: !!args.json,
+    client: args.client,
+    maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,
+    noCostGate: !!args['no-cost-gate'],
+    maxCostPerMtok: cfg.maxCostPerMtok,
+  });
+  return exitCode;
+}
+
+/**
+ * Handle 'sidecar read' command
+ * Spec Reference: §4.5
+ */
+async function handleRead(args) {
+  const useJson = !!args.json;
+  const taskId = args._[1];
+
+  if (!taskId) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: 'Error: task_id is required for read' }));
+  }
+
+  const taskIdCheck = validateTaskId(taskId);
+  if (!taskIdCheck.valid) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: taskIdCheck.error }));
+  }
+
+  const { readSidecar } = require('./index');
+
+  await readSidecar({
+    taskId,
+    conversation: args.conversation,
+    metadata: args.metadata,
+    json: args.json,
+    project: args.cwd
+  });
+}
+
+module.exports = { handleStart, handleFanout, handleRead };

package/src/cli-handlers.js

@@ -97,7 +97,7 @@ async function handleAbort(args) {
 
   if (!taskId) {
     console.error('Error: task_id is required for abort');
-    console.error('Usage: sidecar abort <task_id>');
+    console.error('Usage: amicus abort <task_id>');
     process.exit(1);
   }
 
@@ -180,9 +180,74 @@ async function handleMcp() {
   await startMcpServer();
 }
 
+/**
+ * Handle 'amicus key' command
+ * Lists, saves, or removes API keys for a provider without opening the Electron wizard.
+ */
+async function handleKey(args) {
+  const { readApiKeys, readApiKeyHints, saveApiKey, removeApiKey, PROVIDER_ENV_MAP } = require('./utils/api-key-store');
+  const { validateApiKey } = require('./utils/api-key-validation');
+
+  const provider = args._[1];
+  const keyArg = args._[2];
+
+  // List mode: no provider given
+  if (!provider) {
+    const configured = readApiKeys();
+    const hints = readApiKeyHints();
+    const knownProviders = Object.keys(PROVIDER_ENV_MAP);
+    console.log('');
+    console.log('Configured API keys:');
+    for (const p of knownProviders) {
+      const status = configured[p] ? `✓  ${hints[p]}` : '✗  not set';
+      console.log(`  ${p.padEnd(12)} ${status}`);
+    }
+    console.log('');
+    return;
+  }
+
+  // Validate provider
+  if (!PROVIDER_ENV_MAP[provider]) {
+    console.error(`Error: Unknown provider "${provider}". Known providers: ${Object.keys(PROVIDER_ENV_MAP).join(', ')}`);
+    process.exit(1);
+  }
+
+  // Remove mode
+  if (args.remove) {
+    const result = removeApiKey(provider);
+    if (!result.success) {
+      console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`${provider} key removed.`);
+    return;
+  }
+
+  // Save mode: key required
+  if (!keyArg) {
+    console.error(`Error: API key is required. Usage: amicus key ${provider} <apikey>`);
+    process.exit(1);
+  }
+
+  console.log(`Validating ${provider} key...`);
+  const validation = await validateApiKey(provider, keyArg);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+
+  const result = saveApiKey(provider, keyArg);
+  if (!result.success) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`${provider} key validated and saved.`);
+}
+
 module.exports = {
   handleSetup,
   handleAbort,
   handleUpdate,
   handleMcp,
+  handleKey,
 };

package/src/cli.js

@@ -110,7 +110,9 @@ function isBooleanFlag(key) {
      'help',
      'api-keys',
      'validate-model',
-     'no-validate-model'
+     'no-validate-model',
+     'remove',               // used by 'key' command only; other handlers ignore it
+     'no-cost-gate',         // disable the budget gate for this run
    ];
   return booleanFlags.includes(key);
 }
@@ -119,6 +121,9 @@ function isBooleanFlag(key) {
  * Parse a value to the appropriate type
  */
 function parseValue(key, value) {
+  // max-cost is a float (dollars), not an integer
+  if (key === 'max-cost') { return parseFloat(value); }
+
   // Numeric options
   const numericOptions = ['context-turns', 'context-max-tokens', 'timeout', 'opencode-port'];
    if (numericOptions.includes(key)) {
@@ -157,7 +162,7 @@ function validateStartArgs(args) {
 
   // Validate model format if model is present (model is resolved externally via resolveModel)
   if (args.model && !isValidModelFormat(args.model)) {
-    return { valid: false, error: 'Error: --model must be in format provider/model (e.g., google/gemini-2.5-flash) or openrouter/provider/model' };
+    return { valid: false, code: 'BAD_MODEL', error: 'Error: --model must be in format provider/model (e.g., google/gemini-2.5-flash) or openrouter/provider/model' };
   }
 
   // Validate cwd path exists (if provided)
@@ -298,10 +303,17 @@ Commands:
   continue    New session building on previous
   read        Output session summary/conversation
   models      List/search the model catalog, refresh it, audit aliases
+  council tally <input.json> [--json]   Tally council findings → tiers/street-cred
+  council stats [--json]                Reviewer-reliability from the ledger
+  doctor      Check your setup: keys, catalog, binary, skills, MCP (--json)
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
     --add-alias <name=model> Add a model alias without the full wizard
+  key         Manage API keys from the command line
+    <provider> <apikey>      Validate and save a key
+    <provider> --remove      Remove a saved key
+    (no args)                List all configured providers
   update      Update to latest version
   mcp         Start MCP server (stdio transport)
 
@@ -347,6 +359,8 @@ Options for 'fanout':
                                with --prompt. Also works with 'start'.
   --wave-id <id>               Explicit wave ID (leg IDs become <id>-1..N)
   --json                       Emit the wave result as stable JSON on stdout
+  --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
+  --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure

package/src/council/findings.js

@@ -0,0 +1,48 @@
+// src/council/findings.js
+'use strict';
+
+const SEVERITIES = ['blocker', 'major', 'minor', 'nit'];
+const REQUIRED = ['claim', 'location', 'rationale'];
+
+/** Extract the LAST ```json fenced block's body, or null. */
+function lastJsonBlock(text) {
+  const re = /```json\s*\n([\s\S]*?)```/g;
+  let m, last = null;
+  while ((m = re.exec(text)) !== null) { last = m[1]; }
+  return last;
+}
+
+/**
+ * Validate a Stage-1 reviewer's fenced findings JSON.
+ * @param {string} jsonText full review text (prose + fenced block)
+ * @returns {{ok:boolean, findings:Array, errors:Array<{code:string,detail:string}>}}
+ */
+function validateFindings(jsonText) {
+  const errors = [];
+  const body = lastJsonBlock(jsonText || '');
+  if (body === null) {
+    return { ok: false, findings: [], errors: [{ code: 'NO_FENCED_BLOCK', detail: 'no ```json block found' }] };
+  }
+  let parsed;
+  try { parsed = JSON.parse(body); }
+  catch (e) { return { ok: false, findings: [], errors: [{ code: 'NOT_PARSEABLE', detail: e.message }] }; }
+
+  const findings = Array.isArray(parsed.findings) ? parsed.findings : [];
+  if (findings.length === 0) {
+    errors.push({ code: 'EMPTY_FINDINGS', detail: 'findings is missing or empty' });
+  }
+  const seen = new Set();
+  findings.forEach((f, i) => {
+    if (seen.has(f.id)) { errors.push({ code: 'DUPLICATE_ID', detail: `id ${f.id} repeats` }); }
+    seen.add(f.id);
+    if (f.id !== i + 1) { errors.push({ code: 'NON_SEQUENTIAL_ID', detail: `expected id ${i + 1}, got ${f.id}` }); }
+    if (!SEVERITIES.includes(f.severity)) { errors.push({ code: 'BAD_SEVERITY', detail: `bad severity '${f.severity}' on id ${f.id}` }); }
+    for (const k of REQUIRED) {
+      if (typeof f[k] !== 'string' || f[k].trim() === '') { errors.push({ code: 'MISSING_FIELD', detail: `missing ${k} on id ${f.id}` }); }
+    }
+  });
+
+  return { ok: errors.length === 0, findings: errors.length === 0 ? findings : [], errors };
+}
+
+module.exports = { validateFindings, SEVERITIES };

package/src/council/ledger.js

@@ -0,0 +1,82 @@
+// src/council/ledger.js
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('../utils/config');
+
+const LEDGER_SCHEMA_VERSION = 1;
+const LEDGER_FILE = 'council-ledger.jsonl';
+
+function countSeverity(findings) {
+  const c = { blocker: 0, major: 0, minor: 0, nit: 0 };
+  for (const f of findings) { if (c[f.severity] !== undefined) { c[f.severity] += 1; } }
+  return c;
+}
+
+/** One model-level row per council model. Rates are over RAW raised findings. */
+function buildLedgerRows(record) {
+  const { meta, findings, streetCred, runStats, judged } = record;
+  const sc = new Map(streetCred.map(s => [s.model, s]));
+  const rs = new Map(runStats.map(r => [r.model, r]));
+  return meta.models.map(model => {
+    const raised = findings.filter(f => f.raiser === model);
+    const s = sc.get(model) || {};
+    const r = rs.get(model) || {};
+    const denom = raised.length;
+    return {
+      schemaVersion: LEDGER_SCHEMA_VERSION,
+      runId: meta.runId, date: meta.date, runType: meta.runType, model,
+      role: r.role || 'council', wasChair: !!r.wasChair, judged: judged === true,
+      streetCredWithSelf: judged ? (s.withSelf ?? null) : null,
+      streetCredPeersOnly: judged ? (s.peersOnly ?? null) : null,
+      findingsRaised: denom,
+      bySeverity: countSeverity(raised),
+      confirmRate: judged && denom ? raised.filter(f => f.tier === 'Confirmed').length / denom : null,
+      factErrorRate: judged && denom ? raised.filter(f => f.tier === 'Disputed').length / denom : null,
+      conformance: r.conformance || 'clean',
+    };
+  });
+}
+
+function appendRun(record, opts = {}) {
+  const dir = opts.dir || getConfigDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, LEDGER_FILE);
+  const rows = buildLedgerRows(record);
+  for (const row of rows) { fs.appendFileSync(file, JSON.stringify(row) + '\n'); }
+  return rows;
+}
+
+function readRows(dir) {
+  const file = path.join(dir, LEDGER_FILE);
+  if (!fs.existsSync(file)) { return []; }
+  return fs.readFileSync(file, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean)
+    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+function avg(nums) { return nums.length ? nums.reduce((s, x) => s + x, 0) / nums.length : null; }
+
+/** Aggregate the ledger per model. peersOnly nulls excluded; lowN flags < 3 runs. */
+function deriveReliability(opts = {}) {
+  const dir = opts.dir || getConfigDir();
+  const byModel = new Map();
+  for (const row of readRows(dir)) {
+    if (!byModel.has(row.model)) { byModel.set(row.model, []); }
+    byModel.get(row.model).push(row);
+  }
+  return [...byModel.entries()].map(([model, rows]) => {
+    const peers = rows.map(r => r.streetCredPeersOnly).filter(v => typeof v === 'number');
+    const confirms = rows.map(r => r.confirmRate).filter(v => typeof v === 'number');
+    const facts = rows.map(r => r.factErrorRate).filter(v => typeof v === 'number');
+    const conformance = rows.reduce((acc, r) => { acc[r.conformance] = (acc[r.conformance] || 0) + 1; return acc; }, {});
+    return {
+      model, runs: rows.length, lowN: rows.length < 3,
+      avgStreetCredPeersOnly: avg(peers),
+      lifetimeConfirmRate: avg(confirms),
+      lifetimeFactErrorRate: avg(facts),
+      conformance,
+    };
+  });
+}
+
+module.exports = { buildLedgerRows, appendRun, deriveReliability, LEDGER_FILE, LEDGER_SCHEMA_VERSION };