amicus 1.2.1 → 1.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": { "name": "Christian Wagner" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-28
+
+### Added
+- **Free OpenRouter council**: a new `amicus setup` option (readline wizard + Electron Models step)
+  that stands up a zero-cost council of free `:free` OpenRouter models, saved as a first-class
+  `councils` config primitive. Run it with `amicus fanout --council free` or the `amicus_fanout` MCP
+  `council` param; the second-opinion skill reads `councils.free`. Free-model picks are detected
+  live from the catalog (the `:free` suffix is authoritative), seeded under collision-safe `free-*`
+  aliases, and a delisted member degrades gracefully (dropped with a warning) instead of failing the
+  wave. Needs only an `OPENROUTER_API_KEY`; the wizard discloses the free-tier caveats (rate limits,
+  variable quality, the OpenRouter data-sharing prerequisite). `config.default` is left untouched.
+
+## [1.3.0] - 2026-06-24
+
+Making the mature council/fan-out engine legible: live per-leg progress, cost
+surfaced in human output, the deterministic council spine reachable over MCP,
+and a shareable verdict/disagreement report. Every change is presentation over
+data the engine already records — no schema change.
+
+### Added
+- **Live per-leg fan-out progress**: a running `amicus fanout` now prints a per-leg rollup on each
+  heartbeat — every model's stage, message count, and latest action — instead of a generic "still
+  running". `amicus_status` reports per-leg `latestActivity` plus a `stalled` flag, so you can see
+  at a glance which model is working, which is quiet, and which is wedged.
+- **Cost in human output**: the `amicus fanout` / `amicus read` human view now shows a per-leg `$`
+  cost cell and a `Wave cost:` total, and `amicus council tally` shows a run cost line. Each figure
+  is tagged by source (reported, `~` estimated, `?` unknown) so it can never be mistaken for an
+  authoritative number it isn't — surfaced straight from the existing usage telemetry.
+- **Council over MCP**: three new MCP tools — `amicus_council_tally`, `amicus_council_stats`, and
+  `amicus_verdict` — expose the deterministic council spine (peers-only tier cascade, street-cred,
+  the reliability ledger, and verdict merge) to Claude directly, with no Bash round-trip.
+- **`amicus council report`**: render a shareable disagreement + verdict report from a
+  `verdict.json` — the adjudication matrix (finding × judge), peers-only street-cred, findings
+  grouped by tier (Disputed first), and per-model + wave cost — as Markdown (`--md`, default) or a
+  self-contained HTML page (`--html`). Pass `--wave <wave.json>` to fold in the wave-level cost
+  total. The council skill's Stage-5 step now drives this renderer instead of hand-assembling the
+  report.
+
 ## [1.2.1] - 2026-06-24
 
 ### Fixed

package/README.md

@@ -152,6 +152,16 @@ Then the council waits for your confirmation.
 
 The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**.
 
+**Free council (zero-cost).** Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
+
+Run it anywhere a council runs:
+
+```bash
+amicus fanout --council free --prompt "Review this design"
+```
+
+The `amicus_fanout` MCP tool takes the same `council` parameter, and the `second-opinion` skill reads `councils.free` automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are **rate-limited and quality-variable**, and some return 404 unless you enable data-sharing at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy).
+
 ---
 
 ## The parallel window
@@ -246,7 +256,8 @@ amicus fanout --models gemini,deepseek,gpt --prompt "Review this design" --json
 
 Fanout runs one **headless wave**: every leg gets the **same** prompt (this is the shared-prompt model the council's review stages are built on). When all legs are terminal it prints **one** JSON wave document on stdout.
 
-- `--models <a,b,c>` — comma-separated aliases or `provider/model` IDs (required).
+- `--models <a,b,c>` — comma-separated aliases or `provider/model` IDs (required, unless `--council`).
+- `--council <name>` — run a saved council (e.g. `free`) instead of `--models`; mutually exclusive with `--models`.
 - `--prompt <text>` / `--prompt-file <path>` — the shared briefing. `--prompt-file` avoids the ~32 KB Windows argument cap and is mutually exclusive with `--prompt`.
 - `--wave-id <id>` — set the wave ID explicitly (leg IDs become `<id>-1..N`).
 - `--json` — emit the wave document.

package/electron/ipc-setup.js

@@ -97,7 +97,8 @@ function registerSetupHandlers(getMainWindow) {
 
   // Read-modify-write: never rewrite an alias the renderer didn't send.
   // aliasWrites values: string = set, null = delete. First run seeds live.
-  ipcMain.handle('sidecar:save-config', async (_event, defaultModel, aliasWrites) => {
+  // councilPicks (optional): when length >= 2, seeds the free council via seedFreeCouncil.
+  ipcMain.handle('sidecar:save-config', async (_event, defaultModel, aliasWrites, councilPicks) => {
     try {
       const { loadConfig, saveConfig } = require('../src/utils/config');
       let cfg = loadConfig();
@@ -119,6 +120,9 @@ function registerSetupHandlers(getMainWindow) {
         }
       }
       saveConfig(cfg);
+      if (Array.isArray(councilPicks) && councilPicks.length >= 2) {
+        require('../src/sidecar/setup').seedFreeCouncil(councilPicks);
+      }
       return { success: true };
     } catch (err) {
       logger.error('save-config handler error', { error: err.message });
@@ -192,6 +196,19 @@ function registerSetupHandlers(getMainWindow) {
       return { models: [], fetchedAt: null };
     }
   });
+
+  // Free OpenRouter council: returns all free models from the catalog,
+  // marking those in the vendor-diverse suggested set with suggested:true.
+  ipcMain.handle('sidecar:fetch-free-models', async () => {
+    try {
+      const { getCatalog } = require('../src/utils/model-catalog');
+      const { listFreeModels, suggestFreeCouncil } = require('../src/utils/free-models');
+      const catalog = await getCatalog();
+      const free = listFreeModels(catalog);
+      const suggested = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
+      return free.map(r => ({ id: r.id, suggested: suggested.has(r.id) }));
+    } catch (_err) { return []; }
+  });
 }
 
 module.exports = { registerSetupHandlers };

package/electron/preload-setup.js

@@ -22,7 +22,8 @@ contextBridge.exposeInMainWorld('sidecarSetup', {
       'sidecar:get-api-keys',
       'sidecar:fetch-models',
       'sidecar:get-catalog',
-      'sidecar:refresh-catalog'
+      'sidecar:refresh-catalog',
+      'sidecar:fetch-free-models'
     ];
     if (!allowedChannels.includes(channel)) {
       throw new Error(`IPC channel not allowed: ${channel}`);

package/electron/setup-ui-council.js

@@ -0,0 +1,77 @@
+/**
+ * Setup UI — Free OpenRouter council picker (mounted on the Models step).
+ * Collapsible section: a checkbox list of free models fetched via IPC. Gated
+ * on the OpenRouter key (recomputed on Step-2 entry by the orchestrator).
+ * window.collectCouncilPicks() returns the checked ids for the save payload.
+ */
+'use strict';
+
+function buildCouncilSectionHTML() {
+  return `<div id="free-council-section" class="council-section">
+      <label class="council-toggle"><input type="checkbox" id="free-council-toggle">
+        <span>Set up a free OpenRouter council (zero-cost)</span></label>
+      <div id="free-council-body" style="display:none">
+        <div id="free-council-meta" class="search-meta"></div>
+        <div id="free-council-results" class="council-results"></div>
+        <div class="council-note">Free tier: rate-limited &amp; quality-variable; some models need
+          data-sharing enabled at openrouter.ai/settings/privacy.</div>
+      </div>
+    </div>`;
+}
+
+function buildCouncilScript() {
+  return `
+  (function() {
+    var toggle = document.getElementById('free-council-toggle');
+    var body = document.getElementById('free-council-body');
+    var results = document.getElementById('free-council-results');
+    var meta = document.getElementById('free-council-meta');
+    var loaded = false;
+
+    function hasOpenRouterKey() { return !!(window.configuredKeys && window.configuredKeys.openrouter); }
+
+    window.refreshCouncilGating = function() {
+      if (!toggle) { return; }
+      var ok = hasOpenRouterKey();
+      toggle.disabled = !ok;
+      if (meta && !ok) { meta.textContent = 'Add an OpenRouter API key (step 1) to enable a free council.'; }
+      else if (meta && !loaded) { meta.textContent = ''; }
+    };
+
+    async function loadFree() {
+      if (loaded) { return; }
+      try {
+        var rows = await window.sidecarSetup.invoke('sidecar:fetch-free-models');
+        loaded = true;
+        results.innerHTML = '';
+        (rows || []).forEach(function(r, i) {
+          var id = 'fc-' + i;
+          var row = document.createElement('label');
+          row.className = 'council-row';
+          var cb = document.createElement('input');
+          cb.type = 'checkbox'; cb.value = r.id; cb.id = id; cb.checked = !!r.suggested;
+          var span = document.createElement('span'); span.textContent = r.id;
+          row.appendChild(cb); row.appendChild(span);
+          results.appendChild(row);
+        });
+        if (meta) { meta.textContent = (rows || []).length + ' free models'; }
+      } catch (_e) { if (meta) { meta.textContent = 'Could not load free models.'; } }
+    }
+
+    if (toggle) {
+      toggle.addEventListener('change', function() {
+        body.style.display = toggle.checked ? '' : 'none';
+        if (toggle.checked) { loadFree(); }
+      });
+    }
+
+    window.collectCouncilPicks = function() {
+      if (!toggle || !toggle.checked) { return []; }
+      return Array.prototype.slice.call(results.querySelectorAll('input[type=checkbox]:checked'))
+        .map(function(cb) { return cb.value; });
+    };
+  })();
+  `;
+}
+
+module.exports = { buildCouncilSectionHTML, buildCouncilScript };

package/electron/setup-ui.js

@@ -5,6 +5,7 @@ const { buildAliasEditorHTML } = require('./setup-ui-aliases');
 const { buildWizardCSS } = require('./setup-ui-styles');
 const { buildKeysScript } = require('./setup-ui-keys-script');
 const { buildAliasScript } = require('./setup-ui-alias-script');
+const { buildCouncilSectionHTML, buildCouncilScript } = require('./setup-ui-council');
 const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
@@ -36,7 +37,7 @@ function buildSetupHTML(options = {}) {
   <div class="progress-bar"><div class="progress-step active" id="step-1"><span class="progress-dot">1</span><span>API Keys</span></div><div class="progress-connector"></div><div class="progress-step" id="step-2"><span class="progress-dot">2</span><span>Models</span></div><div class="progress-connector"></div><div class="progress-step" id="step-3"><span class="progress-dot">3</span><span>Routing</span></div><div class="progress-connector"></div><div class="progress-step" id="step-4"><span class="progress-dot">4</span><span>Review</span></div></div>
   <div class="content">
     <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}</div>
-    <div class="wizard-step" id="wizard-step-2">${modelHtml}</div>
+    <div class="wizard-step" id="wizard-step-2">${modelHtml}${buildCouncilSectionHTML()}</div>
     <div class="wizard-step" id="wizard-step-3">${aliasHtml}</div>
     <div class="wizard-step" id="wizard-step-4">
       <div class="step-content">
@@ -57,6 +58,7 @@ ${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultA
 function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson) {
   const keysJs = buildKeysScript();
   const aliasJs = buildAliasScript();
+  const councilJs = buildCouncilScript();
   return `<script>
   window.onerror = function(msg, src, line, col, err) { console.error('WIZARD ERROR:', msg, 'at', src, line, col, err); };
   window.onunhandledrejection = function(e) { console.error('WIZARD UNHANDLED REJECTION:', e.reason); };
@@ -91,6 +93,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
           }
         });
         if (data.hints) { keyHints = data.hints; }
+        window.configuredKeys = configuredKeys;
+        window.refreshCouncilGating && window.refreshCouncilGating();
         updateNextState();
         if (data.imported && data.imported.length > 0) {
           var notice = document.getElementById('import-notice');
@@ -171,7 +175,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     nextBtn.style.display = step < 4 ? '' : 'none';
     finishBtn.style.display = step === 4 ? '' : 'none';
     if (step === 4) { buildReview(); }
-    if (step === 2) { updateRoutingPills(); ensureCatalogLoaded(); }
+    if (step === 2) { updateRoutingPills(); ensureCatalogLoaded(); window.refreshCouncilGating && window.refreshCouncilGating(); }
     if (step === 3) {
       updateAliasRoutes();
       if (!window.availableModels) { fetchAvailableModels(); }
@@ -383,7 +387,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
           if (routeId) { aliasWrites[mc.alias] = routeId; }
         }
       }
-      await window.sidecarSetup.invoke('sidecar:save-config', dm, aliasWrites);
+      await window.sidecarSetup.invoke('sidecar:save-config', dm, aliasWrites, (window.collectCouncilPicks && window.collectCouncilPicks()) || []);
       var kc = Object.values(configuredKeys).filter(function(v) { return v; }).length;
       await window.sidecarSetup.invoke('sidecar:setup-done', dm, kc);
     } catch (_e) { finishBtn.disabled = false; finishBtn.textContent = 'Finish'; }
@@ -512,6 +516,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   ${aliasJs}
 
   ${keysJs}
+
+  ${councilJs}
 </script>`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
     "claude",

package/skills/second-opinion/MODEL-NOTES.md

@@ -79,6 +79,12 @@ This section keeps only per-model **qualitative quirks** and **structural-confor
 - **gpt** — thorough but verbose; peers have dinged it for volume-over-judgment. Self-ranked its own review #1 in the 2026-06-04 run → the peers-only street-cred rule (now enforced by `tally`) mitigates this. Conforms cleanly. Accessible via OpenRouter.
 - **gemini** — fast, very large context; tends toward absolute severity labels ("blocker" inflation vs peers). Conforms cleanly; watch for preamble narration — instruct it to emit the JSON block verbatim after the prose.
 
+## Free-tier models (OpenRouter `:free`)
+- Heavily rate-limited (shared daily pool); a 3-leg parallel wave + cross-review can 429 mid-run.
+- Quality-variable; weaker at strict structured (findings JSON) output.
+- Some `:free` models 404 unless the account enables data-sharing at openrouter.ai/settings/privacy.
+- No reliability history — chair selection can't use `council stats`; pick the strongest free model and disclose lower confidence.
+
 ## Cost guardrail
 - The budget gate enforces this in code: a per-$/Mtok threshold (ON by default)
   refuses o3/o3-pro-class models before a wave launches. This replaces the old

package/skills/second-opinion/SKILL.md

@@ -56,6 +56,22 @@ in this run is written here. Use its absolute path in all `--prompt-file` argume
 
 **Pick the council.** Default: **3 models from different families (non-Claude)**. Recommend them ranked by fit, consulting both the reviewer-reliability data from `amicus council stats` (the authoritative quantitative source — runs, avg peers-only street-cred, confirm-rate, fact-error rate) and the qualitative quirks in `MODEL-NOTES.md`. State the estimated cost. The estimate is the budget gate's pre-flight figure (per-$/Mtok pricing from the cached catalog; direct-provider legs without catalog pricing are disclosed as "cost unknown"). State it as an estimate, not a guarantee. **Disclose the run shape up front** before asking for confirmation — e.g.:
 
+**Free council (zero-cost).** If the user asks for a "free council" / "zero-cost council",
+read `councils.free` from `~/.config/amicus/config.json` and run
+`amicus fanout --council free --prompt-file <briefing>`. Free-tier handling:
+- Cost ≈ $0 — skip the paid-run cost framing (the budget gate is a no-op at zero price).
+- No reliability history: free models have no `amicus council stats` / `MODEL-NOTES` record,
+  so don't rank on street-cred. Pick the most capable free model as chair and state lower confidence.
+- Weak structured output: small free models are less reliable at the strict findings JSON; expect
+  more `validateFindings` repair-loop hits.
+- Throttled/truncated legs: a mid-stream 429 can yield a leg marked `complete` with a truncated,
+  unparseable review. When a free-council leg is `complete` but `validateFindings` returns
+  `NO_FENCED_BLOCK`/`NOT_PARSEABLE`, treat it as suspect/throttled — don't burn the repair loop on the
+  same throttled model; disclose it and apply the ≥2-reviews-survive wave-degrade rule.
+- Prerequisite: free models require enabling data-sharing in OpenRouter privacy settings
+  (openrouter.ai/settings/privacy) or legs 404 at run time — catalog validation cannot catch this.
+  State this up front.
+
 > This run uses 3 council models across 2 fanout waves + 1 chair call (~7 model runs), ~10 min.
 
 Then **wait for confirmation**. Never launch without it. The budget gate enforces the cost guardrail in code: by default it refuses any leg whose price exceeds the per-$/Mtok threshold (the o3/o3-pro guard). To run an intentionally expensive model the user explicitly asked for by name, pass `--no-cost-gate`; to raise only the total ceiling, pass `--max-cost <$>`.
@@ -291,6 +307,13 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
   — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
   invent a figure. Add a wave **total cost** row from the wave document's
   `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`; never invent a value.
+  - **Renderer:** once `verdict.json` is written, generate the human report with
+    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md`
+    (use `--html` for a self-contained, shareable page). This emits the
+    adjudication matrix (finding × judge), the peers-only street-cred table, the
+    findings-by-tier groupings (Disputed-first), and the per-model + wave cost —
+    deterministic data only. Prefer it over hand-assembling the matrix; reserve
+    prose for the chair's synthesis and the decision log.
 
 Tell the user exactly which files were written and where.
 

package/src/cli-handlers-council.js

@@ -3,7 +3,9 @@
 const fs = require('fs');
 const { tally } = require('./council/tally');
 const { deriveReliability } = require('./council/ledger');
+const { sumWaveUsage, formatCost } = require('./utils/pricing');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { buildReport } = require('./council/report');
 
 function runTally(inputPath, useJson) {
   if (!inputPath) {
@@ -34,8 +36,10 @@ function runStats(useJson) {
 
 function renderRecord(r) {
   const t = r.tierCounts;
+  const cost = sumWaveUsage(r.runStats || []).cost;
   return `Council tally (${r.meta.runId})\n` +
-    `  Confirmed ${t.Confirmed}  Contested ${t.Contested}  Singleton ${t.Singleton}  Disputed ${t.Disputed}\n`;
+    `  Confirmed ${t.Confirmed}  Contested ${t.Contested}  Singleton ${t.Singleton}  Disputed ${t.Disputed}\n` +
+    `  Cost: ${formatCost(cost)}\n`;
 }
 function renderStats(agg) {
   if (!agg.length) { return 'No council runs recorded yet.\n'; }
@@ -46,14 +50,45 @@ function renderStats(agg) {
 }
 function fmt(v) { return (v === null || v === undefined) ? '  —  ' : v.toFixed(2); }
 
+function runReport(args, useJson) {
+  const verdictPath = args._[2];
+  if (!verdictPath) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council report needs a <verdict.json> path',
+      hint: 'amicus council report <verdict.json> [--wave <wave.json>] [--md|--html]' });
+  }
+  let verdict;
+  try { verdict = JSON.parse(fs.readFileSync(verdictPath, 'utf-8')); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read ${verdictPath}: ${e.message}`,
+      hint: 'pass a valid verdict.json (from the council flow / amicus_verdict)' });
+  }
+  let wave = null;
+  if (args.wave) {
+    try { wave = JSON.parse(fs.readFileSync(args.wave, 'utf-8')); }
+    catch (e) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read --wave ${args.wave}: ${e.message}`,
+        hint: 'pass a valid wave.json or omit --wave' });
+    }
+  }
+  let report;
+  try { report = buildReport({ verdict, wave }, { format: args.html ? 'html' : 'md' }); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot render report: ${e.message}`,
+      hint: 'verdict.json needs findings[], streetCred[], runStats[], tierCounts' });
+  }
+  process.stdout.write(report.endsWith('\n') ? report : report + '\n');
+  return 0;
+}
+
 /** @param {{_:string[], json?:boolean}} args @returns {Promise<number>} */
 async function handleCouncil(args) {
   const sub = args._[1];
   const useJson = !!args.json;
   if (sub === 'tally') { return runTally(args._[2], useJson); }
   if (sub === 'stats') { return runStats(useJson); }
+  if (sub === 'report') { return runReport(args, useJson); }
   return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-    message: `unknown council subcommand '${sub || ''}'`, hint: 'amicus council tally|stats' });
+    message: `unknown council subcommand '${sub || ''}'`, hint: 'amicus council tally|stats|report' });
 }
 
 module.exports = { handleCouncil };

package/src/cli-handlers-run.js

@@ -108,8 +108,30 @@ async function handleFanout(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)' }));
+  // Council preset: expand a saved council into args.models (mutually exclusive with --models).
+  const hasModels = typeof args.models === 'string' && args.models.trim();
+  const hasCouncil = args.council !== undefined && args.council !== false;
+  if (hasModels && hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pass exactly one of --models / --council, not both' }));
+  }
+  if (!hasModels && !hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs), or use --council <name>' }));
+  }
+  if (hasCouncil) {
+    if (typeof args.council !== 'string' || !args.council.trim()) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --council requires a council name (e.g. --council free)' }));
+    }
+    const { resolveCouncilMembers } = require('./utils/config');
+    const { readCache } = require('./utils/model-catalog');
+    const catalog = (readCache() || {}).models || [];
+    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
+    if (expanded.error) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }));
+    }
+    if (expanded.dropped && expanded.dropped.length && !useJson) {
+      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
+    }
+    args.models = expanded.models.join(',');
   }
   if (args['wave-id']) {
     const check = validateTaskId(String(args['wave-id']));

package/src/cli.js

@@ -113,6 +113,8 @@ function isBooleanFlag(key) {
      'no-validate-model',
      'remove',               // used by 'key' command only; other handlers ignore it
      'no-cost-gate',         // disable the budget gate for this run
+     'html',                 // council report: emit a self-contained HTML page
+     'md',                   // council report: emit Markdown (default)
    ];
   return booleanFlags.includes(key);
 }
@@ -305,6 +307,7 @@ Commands:
   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
+  council report <verdict.json> [--wave <wave.json>] [--md|--html]   Disagreement+verdict report
   doctor      Check your setup: keys, catalog, binary, skills, MCP (--json)
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
@@ -353,6 +356,7 @@ Options for 'start':
 
 Options for 'fanout':
   --models <a,b,c>             Required. Comma-separated aliases or provider/model IDs
+  --council <name>             Run a saved council instead of --models (e.g. free). Mutually exclusive with --models
   --prompt <text>              Task briefing (or use --prompt-file)
   --prompt-file <path>         Read the briefing from a UTF-8 file (avoids the
                                ~32KB Windows argument cap). Mutually exclusive

package/src/council/report-html.js

@@ -0,0 +1,71 @@
+// src/council/report-html.js
+'use strict';
+
+/**
+ * @module council/report-html
+ * Self-contained HTML renderer for the council report (inline CSS, no server,
+ * tier-colored rows). Consumes the neutral model from council/report.js.
+ */
+
+const { formatCost } = require('../utils/pricing');
+const { TIER_ORDER, SYMBOL } = require('./report');
+
+const TIER_COLOR = { Disputed: '#fde2e1', Contested: '#fef3c7', Confirmed: '#dcfce7', Singleton: '#e5e7eb' };
+
+function esc(s) {
+  return String(s === null || s === undefined ? '' : s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function num(v) { return (v === null || v === undefined) ? '—' : v.toFixed(2); }
+function dur(ms) { return (ms === null || ms === undefined) ? '—' : `${Math.round(ms / 1000)}s`; }
+
+function renderHtml(m) {
+  const h = m.header;
+  const judgeHead = m.judges.map(j => `<th>${esc(j)}</th>`).join('');
+  const matrixRows = m.findings.map((f) => {
+    const cells = m.judges.map((j) => {
+      const v = f.byJudge[j];
+      return `<td class="c">${v ? SYMBOL[v] : ''}${j === f.raiser ? '<sup>*</sup>' : ''}</td>`;
+    }).join('');
+    return `<tr style="background:${TIER_COLOR[f.tier] || '#fff'}">` +
+      `<td>${esc(f.id)}</td><td>${esc(f.severity)}</td><td>${esc(f.raiser)}</td>${cells}` +
+      `<td>${esc(f.tier)}</td><td>${esc(f.decision || '')}</td></tr>`;
+  }).join('');
+  const credRows = m.streetCred.map(s =>
+    `<tr><td>${esc(s.model)}</td><td>${num(s.peersOnly)}</td><td>${num(s.withSelf)}</td></tr>`).join('');
+  const tierRows = TIER_ORDER.map(t =>
+    `<tr><td>${t}</td><td>${m.tierCounts[t]}</td></tr>`).join('');
+  const costRows = m.cost.rows.map(r =>
+    `<tr><td>${esc(r.model)}</td><td>${esc(r.status)}</td><td>${dur(r.durationMs)}</td>` +
+    `<td>${esc(formatCost(r.cost))}</td></tr>`).join('');
+  const meta = [h.date, h.chair ? `chair: ${h.chair}` : null, `council: ${h.council.join(', ')}`,
+    h.claudeInCouncil ? 'Claude in council' : null].filter(Boolean).map(esc).join(' · ');
+
+  return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8">
+<title>Council Report — ${esc(h.runId)}</title>
+<style>
+  body { font: 14px/1.5 system-ui, sans-serif; max-width: 1000px; margin: 2rem auto; padding: 0 1rem; color: #1f2937; }
+  h1 { font-size: 1.5rem; } h2 { margin-top: 2rem; border-bottom: 1px solid #e5e7eb; padding-bottom: .25rem; }
+  table { border-collapse: collapse; width: 100%; margin: .5rem 0; }
+  th, td { border: 1px solid #e5e7eb; padding: .35rem .5rem; text-align: left; }
+  th { background: #f9fafb; } td.c { text-align: center; } .meta { color: #6b7280; }
+  .legend { color: #6b7280; font-size: .85rem; }
+</style></head><body>
+<h1>Council Report — ${esc(h.runType)} (${esc(h.runId)})</h1>
+<p class="meta">${meta}</p>
+<h2>Verdict summary</h2>
+<table><tr><th>Tier</th><th>Count</th></tr>${tierRows}</table>
+<h2>Adjudication matrix</h2>
+<table><tr><th>Finding</th><th>Sev</th><th>Raiser</th>${judgeHead}<th>Tier</th><th>Decision</th></tr>${matrixRows}</table>
+<p class="legend">✓ agree · ✗ dispute · – neutral · <sup>*</sup> raiser's own vote</p>
+<h2>Street-cred <span class="meta">(peers-only; lower = better)</span></h2>
+<table><tr><th>Model</th><th>peers-only</th><th>with-self</th></tr>${credRows}</table>
+<h2>Cost</h2>
+<table><tr><th>Model</th><th>Status</th><th>Duration</th><th>Cost</th></tr>${costRows}
+<tr><td><strong>Wave total</strong></td><td></td><td></td><td>${esc(formatCost(m.cost.total))}</td></tr></table>
+</body></html>
+`;
+}
+
+module.exports = { renderHtml };

package/src/council/report.js

@@ -0,0 +1,113 @@
+// src/council/report.js
+'use strict';
+
+/**
+ * @module council/report
+ * Pure verdict/disagreement report renderer (the differentiator). Reads a
+ * verdict.json (+ optional wave.json for the cost total) and produces a single
+ * self-contained Markdown or HTML string. Renders deterministic data only — no
+ * scoring, anonymization, or synthesis (that stays in Claude).
+ */
+
+const { formatCost, sumWaveUsage } = require('../utils/pricing');
+
+const TIER_ORDER = ['Disputed', 'Contested', 'Confirmed', 'Singleton'];
+const SYMBOL = { agree: '✓', dispute: '✗', neutral: '–' };
+
+/** Build a neutral, render-agnostic model from a verdict (+ optional wave). */
+function toModel(verdict, wave) {
+  if (!verdict || !Array.isArray(verdict.findings)) {
+    throw new Error('verdict.json must have a findings[] array');
+  }
+  const judges = verdict.council || [];
+  const findings = verdict.findings.map((f) => {
+    const byJudge = {};
+    for (const j of judges) { byJudge[j] = null; }
+    for (const adj of (f.adjudications || [])) { byJudge[adj.judge] = adj.verdict; }
+    return {
+      id: f.id, severity: f.severity, raiser: f.raiser, tier: f.tier,
+      basis: f.basis || { a: 0, d: 0, n: 0 }, decision: f.decision || null,
+      applied: f.applied === true, byJudge,
+    };
+  });
+  const runStats = verdict.runStats || [];
+  const costRows = runStats.map(r => ({
+    model: r.model, status: r.status, durationMs: r.durationMs,
+    cost: r.usage && r.usage.cost ? r.usage.cost : null,
+  }));
+  const total = (wave && wave.usage && wave.usage.cost) ? wave.usage.cost : sumWaveUsage(runStats).cost;
+  return {
+    header: {
+      runType: verdict.runType || 'review', runId: verdict.runId, date: verdict.date,
+      chair: verdict.chair, council: judges, claudeInCouncil: verdict.claudeInCouncil === true,
+    },
+    tierCounts: verdict.tierCounts || { Confirmed: 0, Contested: 0, Singleton: 0, Disputed: 0 },
+    judges, findings,
+    streetCred: verdict.streetCred || [],
+    cost: { rows: costRows, total },
+  };
+}
+
+function fmtNum(v) { return (v === null || v === undefined) ? '—' : v.toFixed(2); }
+function fmtDur(ms) { return (ms === null || ms === undefined) ? '—' : `${Math.round(ms / 1000)}s`; }
+
+function renderMd(m) {
+  const h = m.header;
+  const out = [];
+  out.push(`# Council Report — ${h.runType} (${h.runId})`);
+  const meta = [h.date, h.chair ? `chair: ${h.chair}` : null, `council: ${h.council.join(', ')}`,
+    h.claudeInCouncil ? 'Claude in council' : null].filter(Boolean).join(' · ');
+  out.push(`\n_${meta}_\n`);
+
+  out.push('## Verdict summary\n');
+  out.push('| Tier | Count |\n|---|---|');
+  for (const t of TIER_ORDER) { out.push(`| ${t} | ${m.tierCounts[t]} |`); }
+
+  out.push('\n## Adjudication matrix\n');
+  out.push(`| Finding | Sev | Raiser | ${m.judges.join(' | ')} | Tier | Decision |`);
+  out.push(`|---|---|---|${m.judges.map(() => '---').join('|')}|---|---|`);
+  for (const f of m.findings) {
+    const cells = m.judges.map((j) => {
+      const v = f.byJudge[j];
+      return (v ? SYMBOL[v] : ' ') + (j === f.raiser ? '*' : '');
+    });
+    out.push(`| ${f.id} | ${f.severity} | ${f.raiser} | ${cells.join(' | ')} | ${f.tier} | ${f.decision || ''} |`);
+  }
+  out.push('\n_Legend: ✓ agree · ✗ dispute · – neutral · `*` raiser\'s own vote_\n');
+
+  out.push('## Street-cred (peers-only; lower = better)\n');
+  out.push('| Model | peers-only | with-self |\n|---|---|---|');
+  for (const s of m.streetCred) { out.push(`| ${s.model} | ${fmtNum(s.peersOnly)} | ${fmtNum(s.withSelf)} |`); }
+
+  out.push('\n## Findings by tier\n');
+  for (const t of TIER_ORDER) {
+    const group = m.findings.filter(f => f.tier === t);
+    if (!group.length) { continue; }
+    out.push(`### ${t}`);
+    for (const f of group) {
+      const dec = f.decision ? ` — ${f.decision}${f.applied ? ' (applied)' : ''}` : '';
+      out.push(`- **${f.id}** (${f.severity}, raiser ${f.raiser}) — a${f.basis.a}/d${f.basis.d}/n${f.basis.n}${dec}`);
+    }
+    out.push('');
+  }
+
+  out.push('## Cost\n');
+  out.push('| Model | Status | Duration | Cost |\n|---|---|---|---|');
+  for (const r of m.cost.rows) { out.push(`| ${r.model} | ${r.status} | ${fmtDur(r.durationMs)} | ${formatCost(r.cost)} |`); }
+  out.push(`| **Wave total** | | | ${formatCost(m.cost.total)} |`);
+
+  return out.join('\n') + '\n';
+}
+
+/**
+ * @param {{verdict:object, wave?:object, tallyRecord?:object}} sources
+ * @param {{format:'md'|'html'}} opts
+ * @returns {string}
+ */
+function buildReport(sources, opts = {}) {
+  const model = toModel(sources.verdict, sources.wave);
+  if (opts.format === 'html') { return require('./report-html').renderHtml(model); }
+  return renderMd(model);
+}
+
+module.exports = { buildReport, toModel, TIER_ORDER, SYMBOL };