amicus 1.2.1 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.2.1",
+  "version": "1.3.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,32 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.2.1",
+  "version": "1.3.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/SKILL.md

@@ -291,6 +291,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.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

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 };

package/src/mcp-server.js

@@ -8,7 +8,7 @@ const os = require('os');
 const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
 const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
-const { readProgress } = require('./sidecar/progress');
+const { readProgress, isStalled } = require('./sidecar/progress');
 const { SharedServerManager } = require('./utils/shared-server');
 
 const sharedServer = new SharedServerManager({ logger });
@@ -264,7 +264,14 @@ const handlers = {
     if (metadata.type === 'wave') {
       const legs = (metadata.legs || []).map((legId) => {
         const m = readMetadata(legId, cwd);
-        return { taskId: legId, model: (m && m.model) || null, status: (m && m.status) || 'unknown' };
+        const leg = { taskId: legId, model: (m && m.model) || null, status: (m && m.status) || 'unknown' };
+        try {
+          const p = readProgress(getSessionDir(cwd, legId));
+          leg.messages = p.messages;
+          leg.latestActivity = p.latest;
+          leg.stalled = leg.status === 'running' && isStalled(p.lastActivityMs);
+        } catch { /* no progress yet — leave base fields only */ }
+        return leg;
       });
       const { TERMINAL_STATUSES } = require('./utils/result-schema');
       const done = legs.filter(l => TERMINAL_STATUSES.includes(l.status)).length;
@@ -574,6 +581,27 @@ const handlers = {
     return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
   },
 
+  async amicus_council_tally(input) {
+    try {
+      const { tally } = require('./council/tally');
+      return textResult(JSON.stringify(tally(input)));
+    } catch (err) { return textResult(`council tally failed: ${err.message}`, true); }
+  },
+
+  async amicus_council_stats() {
+    try {
+      const { deriveReliability } = require('./council/ledger');
+      return textResult(JSON.stringify(deriveReliability()));
+    } catch (err) { return textResult(`council stats failed: ${err.message}`, true); }
+  },
+
+  async amicus_verdict(input) {
+    try {
+      const { buildVerdict } = require('./council/verdict');
+      return textResult(JSON.stringify(buildVerdict(input.record, input.decisions || [])));
+    } catch (err) { return textResult(`verdict build failed: ${err.message}`, true); }
+  },
+
   async amicus_setup() {
     try { spawnSidecarProcess(['setup']); } catch (err) {
       return textResult(`Failed to launch setup: ${err.message}`, true);
@@ -592,6 +620,9 @@ const LEGACY_TOOL_ALIASES = {
   amicus_setup: 'sidecar_setup', amicus_abort: 'sidecar_abort',
   amicus_fanout: 'sidecar_fanout',
   amicus_guide: 'sidecar_guide',
+  amicus_council_tally: 'sidecar_council_tally',
+  amicus_council_stats: 'sidecar_council_stats',
+  amicus_verdict: 'sidecar_verdict',
 };
 
 /** Start the MCP server on stdio transport */

package/src/mcp-tools.js

@@ -281,6 +281,62 @@ function getTools() {
       ),
     },
   },
+  {
+    name: 'amicus_council_tally',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    description:
+      'Deterministic council tally over an ASSEMBLED, de-anonymized input ' +
+      '(meta + findings + adjudications + rankings). Peers-only tier cascade ' +
+      '(Confirmed/Contested/Disputed/Singleton) + street-cred. Pure + synchronous: ' +
+      'returns the tally record immediately. No subprocess, no polling. Claude ' +
+      'assembles the input and may override margin tiers afterward.',
+    inputSchema: {
+      meta: z.object({
+        runId: z.string(), runType: z.string().optional(), date: z.string().optional(),
+        models: z.array(z.string()).min(1), chair: z.string().optional(),
+        claudeInCouncil: z.boolean().optional(),
+      }).describe('Run metadata; meta.models lists every reviewed model.'),
+      findings: z.array(z.object({
+        id: z.string(), raiser: z.string(), severity: z.string(), claim: z.string().optional(),
+      })).describe('Run-global findings (ids already A1/B2/C3-prefixed by Claude).'),
+      adjudications: z.array(z.object({
+        judge: z.string(), findingId: z.string(), verdict: z.enum(['agree', 'dispute', 'neutral']),
+      })).describe('One row per (judge × finding).'),
+      rankings: z.array(z.object({
+        judge: z.string(), order: z.array(z.union([z.string(), z.array(z.string())])),
+      })).describe("Each judge's preference order over the reviews (ties = nested array)."),
+      runStats: z.array(z.record(z.any())).optional().describe('Optional per-model run stats (status/duration/usage).'),
+      project: z.string().optional().describe('Optional project directory path.'),
+    },
+  },
+  {
+    name: 'amicus_council_stats',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    description:
+      'Per-model reviewer reliability derived from the append-only council ledger ' +
+      '(avg peers-only street-cred, lifetime confirm/fact-error rates). Read-only; ' +
+      'no inputs required.',
+    inputSchema: {
+      project: z.string().optional().describe('Optional project directory path.'),
+    },
+  },
+  {
+    name: 'amicus_verdict',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    description:
+      "Merge a tally record with Claude's Stage-4 decisions into the verdict " +
+      'object (final tiers after overrides, decisions, applied flags). Pure + ' +
+      'synchronous; returns the verdict — does NOT write it to disk.',
+    inputSchema: {
+      record: z.record(z.any()).describe('A tally() output record (from amicus_council_tally).'),
+      decisions: z.array(z.object({
+        id: z.string(), decision: z.string().optional(), applied: z.boolean().optional(),
+        duplicateOf: z.string().nullable().optional(),
+        tierOverride: z.object({ from: z.string(), to: z.string(), reason: z.string() }).nullable().optional(),
+      })).optional().describe('Stage-4 per-finding decisions (default []).'),
+      project: z.string().optional().describe('Optional project directory path.'),
+    },
+  },
   {
     name: 'amicus_guide',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },

package/src/sidecar/fanout-output.js

@@ -1,5 +1,6 @@
 // src/sidecar/fanout-output.js
 'use strict';
+const { formatCost } = require('../utils/pricing');
 
 /**
  * @module fanout-output
@@ -36,9 +37,11 @@ function formatWaveHuman(wave) {
   lines.push('─'.repeat(40));
   const counts = wave.counts || { complete: '?', total: '?' };
   lines.push(`Wave ${wave.waveId}: ${wave.status} — ${counts.complete}/${counts.total} complete in ${fmtDuration(wave.durationMs)}`);
+  lines.push(`  Wave cost: ${formatCost(wave.usage && wave.usage.cost)}`);
   for (const leg of wave.legs) {
     const label = leg.modelInput || leg.model || leg.taskId;
-    lines.push(`  ${leg.taskId}  ${String(label).padEnd(12)} ${String(leg.status).padEnd(9)} ${fmtDuration(leg.durationMs)}`);
+    lines.push(`  ${leg.taskId}  ${String(label).padEnd(12)} ${String(leg.status).padEnd(9)} ` +
+      `${String(fmtDuration(leg.durationMs)).padEnd(7)} ${formatCost(leg.usage && leg.usage.cost)}`);
   }
   return lines.join('\n');
 }

package/src/sidecar/fanout.js

@@ -109,7 +109,8 @@ function writeWaveMetadata(waveDir, patch) {
 async function runFanout(options) {
   const { buildWaveResult, waveExitCode } = require('../utils/result-schema');
   const { generateTaskId, buildMcpConfig } = require('./start');
-  const { startOpenCodeServer, createHeartbeat, HEARTBEAT_INTERVAL } = require('./session-utils');
+  const { startOpenCodeServer, HEARTBEAT_INTERVAL } = require('./session-utils');
+  const { createWaveHeartbeat } = require('./wave-progress');
   const { buildContext } = require('./context-builder');
   const { buildPrompts } = require('../prompt-builder');
   const { installSignalAbort, markAborted } = require('../utils/session-abort');
@@ -223,7 +224,12 @@ async function runFanout(options) {
   });
 
   // 6. Launch all legs concurrently (runLeg never rejects)
-  const heartbeat = options.quiet ? { stop() {} } : createHeartbeat(HEARTBEAT_INTERVAL);
+  const heartbeat = options.quiet
+    ? { stop() {} }
+    : createWaveHeartbeat(
+        legs.map((leg, i) => ({ label: leg.modelInput || leg.model, dir: legDirs[i] })),
+        HEARTBEAT_INTERVAL
+      );
   const timeoutMs = (options.timeout || 15) * 60 * 1000;
   const reasoning = options.thinking ? { effort: options.thinking } : undefined;
   let legDocs;

package/src/sidecar/progress.js

@@ -87,6 +87,19 @@ function computeLastActivity(mtime) {
   return `${diffHr}h ago`;
 }
 
+/** A leg with no new activity for longer than this (ms) is flagged stalled in rollups. */
+const STALL_MS = 60000;
+
+/**
+ * Is a leg stalled? True only when we have a real idle measurement that exceeds
+ * the threshold; an unknown / just-started leg (null) is never "stalled".
+ * @param {number|null|undefined} lastActivityMs ms since last activity
+ * @returns {boolean}
+ */
+function isStalled(lastActivityMs) {
+  return typeof lastActivityMs === 'number' && lastActivityMs > STALL_MS;
+}
+
 /**
  * Write a progress update to progress.json.
  *
@@ -214,5 +227,7 @@ module.exports = {
   writeProgress,
   extractLatest,
   computeLastActivity,
-  STAGE_LABELS
+  STAGE_LABELS,
+  STALL_MS,
+  isStalled
 };

package/src/sidecar/wave-progress.js

@@ -0,0 +1,80 @@
+// src/sidecar/wave-progress.js
+'use strict';
+
+/**
+ * @module wave-progress
+ * Per-leg live progress rollup for a fan-out wave. Each headless leg already
+ * writes progress.json + conversation.jsonl to its own session dir; this reads
+ * them on a timer and prints ONE terse line per leg to stderr — milestones,
+ * never a token firehose (all three council models flagged firehose noise).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readProgress, isStalled } = require('./progress');
+
+const WAVE_HEARTBEAT_INTERVAL = 15000;
+
+/**
+ * Render one compact status line per leg. Pure: takes already-read leg states.
+ * @param {Array<{label:string, messages:number, latest:string, stage?:string, stalled:boolean}>} legStates
+ * @returns {string}
+ */
+function formatWaveProgress(legStates) {
+  return legStates.map((s) => {
+    const stage = s.stage || 'starting';
+    const flag = s.stalled ? ' ⏳stalled' : '';
+    return `[amicus]   ${String(s.label).padEnd(16)} ${String(stage).padEnd(10)} ` +
+      `${s.messages} msg | ${s.latest}${flag}`;
+  }).join('\n');
+}
+
+/**
+ * Read a single leg's live state from its session dir. Degrades gracefully when
+ * progress.json is absent (a leg that has not started writing yet).
+ * @param {{label:string, dir:string}} leg
+ * @returns {{label:string, messages:number, latest:string, stage?:string, stalled:boolean}}
+ */
+function readLegState(leg) {
+  const progressPath = path.join(leg.dir, 'progress.json');
+  const convPath = path.join(leg.dir, 'conversation.jsonl');
+
+  // Degrade gracefully when neither file has been written yet
+  if (!fs.existsSync(progressPath) && !fs.existsSync(convPath)) {
+    return { label: leg.label, messages: 0, latest: 'starting…', stalled: false };
+  }
+
+  let p;
+  try { p = readProgress(leg.dir); } catch { p = null; }
+  if (!p) { return { label: leg.label, messages: 0, latest: 'starting…', stalled: false }; }
+
+  const state = {
+    label: leg.label,
+    messages: p.messages,
+    latest: p.latest,
+    stalled: isStalled(p.lastActivityMs),
+  };
+  if (p.stage !== undefined) {
+    state.stage = p.stage;
+  }
+  return state;
+}
+
+/**
+ * Start a wave heartbeat that prints a per-leg rollup each tick. Mirrors the
+ * createHeartbeat contract: returns { stop() }.
+ * @param {Array<{label:string, dir:string}>} legs
+ * @param {number} [interval]
+ * @returns {{stop: () => void}}
+ */
+function createWaveHeartbeat(legs, interval = WAVE_HEARTBEAT_INTERVAL) {
+  const startTime = Date.now();
+  const intervalId = setInterval(() => {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    const states = legs.map(readLegState);
+    process.stderr.write(`[amicus] wave ${elapsed}s — ${states.length} legs\n${formatWaveProgress(states)}\n`);
+  }, interval);
+  return { stop() { clearInterval(intervalId); } };
+}
+
+module.exports = { formatWaveProgress, readLegState, createWaveHeartbeat, WAVE_HEARTBEAT_INTERVAL };

package/src/utils/pricing.js

@@ -90,4 +90,19 @@ function sumWaveUsage(legs) {
   return { tokens, cost: { amount: anyAmount ? amount : null, currency: 'USD', source, reportedLegs, estimatedLegs, unpricedLegs } };
 }
 
-module.exports = { emptyUsageTotals, sumPerMessageUsage, lookupPricing, resolveLegCost, resolveUsage, sumWaveUsage };
+/**
+ * Render a resolved cost object for humans. Never invents precision: a null
+ * amount is '—' (or '?' when the source is explicitly 'unknown'); estimated /
+ * mixed costs are marked with '~' so they can't be read as authoritative.
+ * @param {{amount:number|null, source:string}|null|undefined} cost
+ * @returns {string}
+ */
+function formatCost(cost) {
+  if (!cost || cost.amount === null || cost.amount === undefined) {
+    return cost && cost.source === 'unknown' ? '?' : '—';
+  }
+  const dollars = cost.amount < 1 ? `$${cost.amount.toFixed(4)}` : `$${cost.amount.toFixed(2)}`;
+  return (cost.source === 'estimated' || cost.source === 'mixed') ? `~${dollars}` : dollars;
+}
+
+module.exports = { emptyUsageTotals, sumPerMessageUsage, lookupPricing, resolveLegCost, resolveUsage, sumWaveUsage, formatCost };