amicus 1.9.0 → 2.0.0

package/src/cli-handlers-council.js

@@ -6,6 +6,13 @@ const { deriveReliability, appendRun } = require('./council/ledger');
 const { sumWaveUsage, formatCost } = require('./utils/pricing');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { buildReport } = require('./council/report');
+const { validateFindings } = require('./council/findings');
+const { buildVerdict, writeVerdictAtomic } = require('./council/verdict');
+const {
+  runSave: runCouncilSave,
+  runList: runCouncilList,
+  runShow: runCouncilShow,
+} = require('./council/presets-cli');
 
 function runTally(inputPath, useJson, opts = {}) {
   if (!inputPath) {
@@ -87,6 +94,93 @@ function runReport(args, useJson) {
   return 0;
 }
 
+/**
+ * `amicus council validate <file>` — thin wrapper over `validateFindings`
+ * (src/council/findings.js). Tri-state outcome, distinct from the usual
+ * two-state (0/1) CLI convention:
+ *   exit 0  ok:true              — findings block is well-formed
+ *   exit 2  ok:false             — findings block parsed as a *result*, but
+ *                                  validation failed (a distinct, scriptable
+ *                                  outcome — mirrors the repo's exit-2
+ *                                  "completed-with-failure" convention)
+ *   exit 1  BAD_ARGS envelope    — missing/unreadable input file
+ */
+function runValidate(filePath, useJson) {
+  if (!filePath) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council validate needs a <file> path',
+      hint: 'amicus council validate <file> [--json]' });
+  }
+  let text;
+  try { text = fs.readFileSync(filePath, 'utf-8'); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read ${filePath}: ${e.message}`,
+      hint: 'pass a Stage-1 reviewer output file (prose + trailing ```json findings block)' });
+  }
+  const result = validateFindings(text);
+  process.stdout.write(useJson ? JSON.stringify(result, null, 2) + '\n' : renderValidate(result));
+  return result.ok ? 0 : 2;
+}
+
+function renderValidate(result) {
+  if (result.ok) {
+    const hist = {};
+    for (const f of result.findings) { hist[f.severity] = (hist[f.severity] || 0) + 1; }
+    const parts = Object.keys(hist).map(sev => `${sev} ${hist[sev]}`).join(', ');
+    const n = result.findings.length;
+    return `OK — ${n} finding${n === 1 ? '' : 's'}${parts ? ` (${parts})` : ''}\n`;
+  }
+  return 'INVALID\n' + result.errors.map(e => `  ${e.code}: ${e.detail}`).join('\n') + '\n';
+}
+
+/**
+ * `amicus council verdict <tally.json> --decisions <decisions.json> [-o|--out <out.json>]`
+ * Thin wrapper over `buildVerdict` + `writeVerdictAtomic` (src/council/verdict.js).
+ * `--decisions` is optional (buildVerdict defaults decisions to []). Writes to
+ * `-o`/`--out` (default `./verdict.json`) via the atomic tmp+rename convention.
+ */
+function runVerdict(args, useJson) {
+  const tallyPath = args._[2];
+  if (!tallyPath) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council verdict needs a <tally.json> path',
+      hint: 'amicus council verdict <tally.json> [--decisions <decisions.json>] [-o|--out <out.json>]' });
+  }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(tallyPath, 'utf-8')); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read ${tallyPath}: ${e.message}`,
+      hint: 'pass a valid tally.json (from `amicus council tally` / amicus_council_tally)' });
+  }
+  let decisions = [];
+  const decisionsPath = args.decisions;
+  if (decisionsPath) {
+    try { decisions = JSON.parse(fs.readFileSync(decisionsPath, 'utf-8')); }
+    catch (e) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot read --decisions ${decisionsPath}: ${e.message}`,
+        hint: 'pass a valid decisions.json array or omit --decisions' });
+    }
+  }
+  const outPath = args.out || './verdict.json';
+  let verdict;
+  try { verdict = buildVerdict(record, decisions); }
+  catch (e) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `cannot build verdict: ${e.message}`,
+      hint: 'either tally.json needs meta, findings[], streetCred[], runStats, tierCounts, or decisions.json must be a JSON array of {id, decision, …} objects' });
+  }
+  writeVerdictAtomic(outPath, verdict);
+  process.stdout.write(useJson ? JSON.stringify(verdict, null, 2) + '\n' : renderVerdict(verdict, outPath));
+  return 0;
+}
+
+function renderVerdict(v, outPath) {
+  const counts = {};
+  for (const f of v.findings) {
+    const key = f.decision || 'undecided';
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  const parts = Object.keys(counts).map(k => `${k} ${counts[k]}`).join('  ');
+  return `Verdict (schema v${v.schemaVersion}, ${v.runId}) → ${outPath}\n  ${parts}\n`;
+}
+
 /** @param {{_:string[], json?:boolean}} args @returns {Promise<number>} */
 async function handleCouncil(args) {
   const sub = args._[1];
@@ -94,8 +188,14 @@ async function handleCouncil(args) {
   if (sub === 'tally') { return runTally(args._[2], useJson, { append: !args['no-ledger'] }); }
   if (sub === 'stats') { return runStats(useJson); }
   if (sub === 'report') { return runReport(args, useJson); }
+  if (sub === 'validate') { return runValidate(args._[2], useJson); }
+  if (sub === 'verdict') { return runVerdict(args, useJson); }
+  if (sub === 'save') { return runCouncilSave(args._[2], args.models, useJson); }
+  if (sub === 'list') { return runCouncilList(useJson); }
+  if (sub === 'show') { return runCouncilShow(args._[2], useJson); }
   return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-    message: `unknown council subcommand '${sub || ''}'`, hint: 'amicus council tally|stats|report' });
+    message: `unknown council subcommand '${sub || ''}'`,
+    hint: 'amicus council tally|stats|report|validate|verdict|save|list|show' });
 }
 
 module.exports = { handleCouncil };

package/src/cli-handlers-doctor.js

@@ -48,8 +48,13 @@ function realDeps() {
       return fs.existsSync(path.join(dir, 'sidecar', 'SKILL.md'))
         && fs.existsSync(path.join(dir, 'second-opinion', 'SKILL.md'));
     },
+    now: () => Date.now(),
+    listSessionIndexTmpFiles: () => tmpSweep.listSessionIndexTmpFiles(), // B15
+    unlinkSessionIndexTmp: (n) => tmpSweep.unlinkSessionIndexTmp(n),
   };
 }
+// B15: sweep logic in utils/session-index-tmp-sweep.js (mirrors mcp-legacy's split).
+const tmpSweep = require('./utils/session-index-tmp-sweep');
 
 /** Run one guarded check; a thrown fn becomes an error line. */
 function guard(id, name, fn) {
@@ -224,6 +229,8 @@ async function runDoctorChecks(depsOverride = {}) {
     return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
   }));
 
+  checks.push(guard('sessions-index-tmp', 'Session index tmp files', () => tmpSweep.evaluateSessionIndexTmpSweep(d)));
+
   // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
   checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
     const values = d.readApiKeyValues() || {};

package/src/cli-handlers-run.js

@@ -68,9 +68,9 @@ async function handleStart(args) {
     }
   }
 
-  const { startSidecar } = require('./index');
+  const { startAmicus } = require('./index');
 
-  return await startSidecar({
+  return await startAmicus({
     taskId: args['task-id'],
     model: args.model,
     prompt: args.prompt,
@@ -212,9 +212,9 @@ async function handleRead(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: taskIdCheck.error }));
   }
 
-  const { readSidecar } = require('./index');
+  const { readAmicus } = require('./index');
 
-  await readSidecar({
+  await readAmicus({
     taskId,
     conversation: args.conversation,
     metadata: args.metadata,

package/src/cli-handlers-spend.js

@@ -0,0 +1,198 @@
+// src/cli-handlers-spend.js
+'use strict';
+
+/**
+ * `amicus spend` — cross-run cost rollup over spend-ledger.jsonl (B24).
+ * Mirrors cli-handlers-doctor.js's injectable-deps shape (a `depsOverride`
+ * parameter tests can use to stub I/O/network) and cli-handlers-council.js's
+ * command-file split (kept its own file to stay well under the size gate).
+ *
+ * buildSpendDoc() lives HERE rather than in src/utils/result-schema.js: that
+ * module is at its 300-line size-gate ceiling (filled by a parallel lane in
+ * this same phase), so this module defines its own doc builder using the
+ * SAME schemaVersion convention (result-schema's SCHEMA_VERSION, imported —
+ * not a forked/independent counter) rather than adding to a full file. If
+ * result-schema.js is ever split/slimmed, buildSpendDoc is the one to fold
+ * back in alongside buildCatalogDoc/buildDoctorDoc.
+ */
+
+const { readSpendRows } = require('./utils/spend-ledger');
+const { formatCost } = require('./utils/pricing');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+
+const CREDIT_CHECK_TIMEOUT_MS = 5000;
+
+/** @param {string} since e.g. '7d' @returns {number|null} whole days, or null if unparseable */
+function parseSinceDays(since) {
+  if (typeof since !== 'string') { return null; }
+  const m = since.trim().match(/^(\d+)d$/i);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+function emptyTokens() {
+  return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+function addTokens(into, tokens) {
+  if (!tokens) { return; }
+  for (const k of Object.keys(into)) { into[k] += tokens[k] || 0; }
+}
+
+/**
+ * Aggregate ledger rows into a total + per-model rollup, most-expensive-first.
+ * A row with a null cost.amount contributes 0 to totals but is still counted
+ * in `runs` and its source bucket — visibility into "how many runs are
+ * unpriced" matters as much as the dollar figure.
+ * @param {Array<object>} rows
+ */
+function aggregateSpend(rows) {
+  const total = { amount: 0, tokens: emptyTokens(), runs: rows.length, sourceMix: { reported: 0, estimated: 0, unknown: 0 } };
+  const byModelMap = new Map();
+  for (const r of rows) {
+    const model = r.model || 'unknown';
+    if (!byModelMap.has(model)) {
+      byModelMap.set(model, { model, amount: 0, tokens: emptyTokens(), runs: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } });
+    }
+    const bucket = byModelMap.get(model);
+    bucket.runs += 1;
+    addTokens(bucket.tokens, r.tokens);
+    addTokens(total.tokens, r.tokens);
+    const cost = r.cost || {};
+    const amount = typeof cost.amount === 'number' ? cost.amount : 0;
+    bucket.amount += amount;
+    total.amount += amount;
+    // Any source string outside {reported,estimated} buckets as unknown —
+    // covers 'unknown', a missing/malformed cost block, or a future source.
+    const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
+    bucket.sourceMix[src] += 1;
+    total.sourceMix[src] += 1;
+  }
+  const byModel = [...byModelMap.values()].sort((a, b) => b.amount - a.amount);
+  return { total, byModel };
+}
+
+/**
+ * Build the `--json` spend document. schemaVersion reuses result-schema's
+ * SCHEMA_VERSION (not a forked counter) — see module docblock for why this
+ * builder lives here instead of alongside buildCatalogDoc/buildDoctorDoc.
+ * @param {{total:object, byModel:Array, windowDays:number|null, credit:object|null}} opts
+ */
+function buildSpendDoc({ total, byModel, windowDays, credit }) {
+  const { SCHEMA_VERSION } = require('./utils/result-schema');
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'spend',
+    windowDays: windowDays !== undefined ? windowDays : null,
+    total,
+    byModel,
+    credit: credit || null,
+  };
+}
+
+/** Real deps; tests override via the second handleSpend arg. */
+function realDeps() {
+  return {
+    dir: undefined, // readSpendRows falls back to getConfigDir() itself
+    readApiKeyValues: () => require('./utils/api-key-store').readApiKeyValues(),
+    checkOpenRouterCredit: (key) => require('./utils/api-key-validation').checkOpenRouterCredit(key),
+    now: () => Date.now(),
+  };
+}
+
+/** Race a promise against a hard timeout; resolves `fallback` on timeout — never rejects, never hangs the caller. */
+function withTimeout(promise, ms, fallback) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => { if (!settled) { settled = true; resolve(fallback); } }, ms);
+    Promise.resolve(promise).then(
+      (v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } },
+      () => { if (!settled) { settled = true; clearTimeout(timer); resolve(fallback); } },
+    );
+  });
+}
+
+/**
+ * Best-effort OpenRouter credit footer. Never throws; never blocks past
+ * ~CREDIT_CHECK_TIMEOUT_MS; skipped (returns null) when no key is configured.
+ */
+async function fetchCreditFooter(deps) {
+  let values = {};
+  try { values = deps.readApiKeyValues() || {}; } catch { /* best-effort */ }
+  const key = values.openrouter;
+  if (!key) { return null; }
+  const res = await withTimeout(
+    Promise.resolve().then(() => deps.checkOpenRouterCredit(key)),
+    CREDIT_CHECK_TIMEOUT_MS,
+    null,
+  );
+  return res || null;
+}
+
+function renderHuman({ total, byModel, windowDays, credit }) {
+  if (total.runs === 0) { return 'No spend recorded yet.\n'; }
+  let out = windowDays ? `amicus spend (last ${windowDays}d)\n\n` : 'amicus spend (all time)\n\n';
+  out += 'model                                            runs  tokens(in/out)      cost      sources\n';
+  for (const m of byModel) {
+    const mix = `r${m.sourceMix.reported}/e${m.sourceMix.estimated}/u${m.sourceMix.unknown}`;
+    const tokCol = `${m.tokens.input}/${m.tokens.output}`;
+    out += `${String(m.model).slice(0, 48).padEnd(48)} ${String(m.runs).padStart(4)}  ` +
+      `${tokCol.padStart(15)}  ` +
+      `${formatCost({ amount: m.amount, source: dominantSource(m.sourceMix) }).padStart(9)}  ${mix}\n`;
+  }
+  out += `\nTotal: ${formatCost({ amount: total.amount, source: dominantSource(total.sourceMix) })} across ${total.runs} run(s)\n`;
+  if (credit && typeof credit.limitRemaining === 'number') {
+    out += `OpenRouter credit remaining: $${credit.limitRemaining}\n`;
+  }
+  return out;
+}
+
+/** Pick a representative source tag for formatCost's ~ prefix: mixed if >1 bucket populated. */
+function dominantSource(mix) {
+  const populated = Object.entries(mix).filter(([, n]) => n > 0).map(([k]) => k);
+  if (populated.length === 0) { return 'unknown'; }
+  if (populated.length > 1) { return 'mixed'; }
+  return populated[0];
+}
+
+/**
+ * `amicus spend [--since 7d] [--json]`
+ * @param {{_:string[], json?:boolean, since?:string}} args
+ * @param {object} [depsOverride] test seam
+ * @returns {Promise<number>} exit code
+ */
+async function handleSpend(args, depsOverride = {}) {
+  const useJson = !!args.json;
+  const deps = { ...realDeps(), ...depsOverride };
+
+  let windowDays = null;
+  if (args.since !== undefined) {
+    windowDays = parseSinceDays(args.since);
+    if (windowDays === null) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `invalid --since '${args.since}'`,
+        hint: "amicus spend --since 7d  (an integer followed by 'd')" });
+    }
+  }
+
+  let rows = readSpendRows(deps.dir);
+  if (windowDays !== null) {
+    const cutoff = deps.now() - windowDays * 86400000;
+    rows = rows.filter(r => {
+      const t = Date.parse(r.ts);
+      return Number.isFinite(t) && t >= cutoff;
+    });
+  }
+
+  const { total, byModel } = aggregateSpend(rows);
+  // Nothing recorded (or nothing in the --since window): skip the network
+  // credit probe entirely — there's no rollup to attach it to either way.
+  const credit = total.runs === 0 ? null : await fetchCreditFooter(deps).catch(() => null);
+
+  if (useJson) {
+    process.stdout.write(JSON.stringify(buildSpendDoc({ total, byModel, windowDays, credit }), null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(renderHuman({ total, byModel, windowDays, credit }));
+  return 0;
+}
+
+module.exports = { handleSpend, aggregateSpend, buildSpendDoc, parseSinceDays };

package/src/cli.js

@@ -94,6 +94,17 @@ function parseArgs(argv) {
       } else {
         result[key] = true;
       }
+    } else if (arg === '-o') {
+      // Single short-flag alias, scoped to exactly '-o' (council verdict's
+      // --out shorthand). No general short-flag support is implemented —
+      // any other leading-dash token still falls through to positionals.
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        result.out = next;
+        i++;
+      } else {
+        result.out = true;
+      }
     } else {
       result._.push(arg);
     }
@@ -338,7 +349,10 @@ Commands:
   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
+  council validate <file> [--json]      Validate a Stage-1 findings block (exit 0/2/1)
+  council verdict <tally.json> [--decisions <d.json>] [-o <out.json>]   Build + write verdict.json
   doctor      Check your setup: keys, catalog, binary, skills, MCP (--json)
+  spend [--since 7d] [--json]           Cross-run cost rollup from the spend ledger
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
@@ -465,12 +479,33 @@ Subcommands for 'council':
     --wave <wave.json>         Include per-leg run stats from a wave file
     --md                       Emit Markdown (default)
     --html                     Emit a self-contained HTML page
+  validate <file>               Validate a Stage-1 reviewer's findings block
+    --json                     Machine-readable output
+    Exit codes: 0 ok:true, 2 ok:false (validation failure), 1 BAD_ARGS
+                               (missing/unreadable file)
+  verdict <tally.json>          Build + write verdict.json (buildVerdict + atomic write)
+    --decisions <d.json>       Optional. Stage-4 decisions array (default [])
+    -o, --out <out.json>       Output path (default ./verdict.json)
+    --json                     Print the full verdict document
+  save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
+    --json                     Machine-readable output
+  list                          List saved councils plus the built-in benches
+    --json                     Machine-readable output
+  show <name>                   Resolve a council by name (saved or built-in)
+    --json                     Machine-readable output
 `,
   doctor: `
 Options for 'doctor':
   --json                       Machine-readable output
   --fix                        Self-heal fixable checks in place (provisions the
                                Electron GUI binary; no global reinstall)
+`,
+  spend: `
+Options for 'spend':
+  --since <Nd>                  Restrict to the last N days (e.g. --since 7d)
+  --json                        Machine-readable output (versioned spend doc)
+  Reads ~/.config/amicus/spend-ledger.jsonl (one row per completed run/leg).
+  Shows remaining OpenRouter credit when a key is configured.
 `,
   setup: `
 Options for 'setup':

package/src/council/presets-cli.js

@@ -0,0 +1,141 @@
+// src/council/presets-cli.js
+'use strict';
+
+/**
+ * `amicus council save|list|show` — CLI wrappers around the council-preset
+ * primitives (src/utils/config.js councils.*, src/utils/council-presets.js
+ * built-in benches). Split out of cli-handlers-council.js to keep that file
+ * under the 300-line size gate.
+ */
+
+const { failJson, ERROR_CODES } = require('../utils/error-doc');
+const { listBuiltinCouncilNames } = require('../utils/council-presets');
+
+/**
+ * `amicus council save <name> --models a,b,c`
+ * Validates >=2 members, each resolvable via the same alias/catalog logic
+ * `resolveCouncilMembers` uses (effective aliases, or a raw `provider/model`
+ * id containing '/'). Overwrites an existing name with a notice — this is
+ * also how a user shadows a built-in bench of the same name.
+ * @param {string|undefined} name
+ * @param {string|undefined} modelsArg comma-separated aliases/ids
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runSave(name, modelsArg, useJson) {
+  if (!name) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council save needs a <name>',
+      hint: 'amicus council save <name> --models a,b,c' });
+  }
+  if (typeof modelsArg !== 'string' || !modelsArg.trim()) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council save needs --models a,b,c',
+      hint: 'amicus council save <name> --models a,b,c' });
+  }
+  const members = modelsArg.split(',').map(m => m.trim()).filter(Boolean);
+  if (members.length < 2) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'a council needs at least 2 members',
+      hint: 'pass --models with 2 or more comma-separated aliases or provider/model IDs' });
+  }
+  const { getEffectiveAliases, loadConfig, saveConfig, getCouncil } = require('../utils/config');
+  const aliases = getEffectiveAliases();
+  const unresolved = members.filter(m => !m.includes('/') && !aliases[m]);
+  if (unresolved.length) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+      message: `unresolvable member(s): ${unresolved.join(', ')}`,
+      hint: 'each member must be a known alias (see `amicus models`) or a provider/model id containing "/"' });
+  }
+  const overwritten = !!getCouncil(name);
+  const cfg = loadConfig() || {};
+  if (!cfg.councils) { cfg.councils = {}; }
+  cfg.councils[name] = members;
+  saveConfig(cfg);
+  const doc = { ok: true, name, models: members, overwritten };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderSave(doc));
+  return 0;
+}
+
+function renderSave(doc) {
+  const notice = doc.overwritten ? ' (overwritten)' : '';
+  return `Saved council '${doc.name}'${notice}: ${doc.models.join(', ')}\n`;
+}
+
+/**
+ * `amicus council list [--json]` — user-saved councils plus the built-in
+ * benches (free/budget/frontier), each entry marked `builtin`. When a user
+ * council shares a name with a built-in, BOTH entries are listed: the user
+ * entry (builtin:false) is the one actually used by resolveCouncilMembers,
+ * and the built-in entry (builtin:true) is marked `shadowed:true`.
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runList(useJson) {
+  const { getCouncils } = require('../utils/config');
+  const userCouncils = getCouncils();
+  const userNames = new Set(Object.keys(userCouncils));
+  const entries = [];
+  for (const name of Object.keys(userCouncils).sort()) {
+    entries.push({ name, builtin: false, members: userCouncils[name] });
+  }
+  for (const name of listBuiltinCouncilNames()) {
+    const entry = { name, builtin: true };
+    if (userNames.has(name)) { entry.shadowed = true; }
+    entries.push(entry);
+  }
+  const doc = { councils: entries };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderList(entries));
+  return 0;
+}
+
+function renderList(entries) {
+  const lines = entries.map(e => {
+    if (e.builtin) { return `  ${e.name.padEnd(16)} [built-in]${e.shadowed ? ' (shadowed by a saved council of the same name)' : ''}`; }
+    return `  ${e.name.padEnd(16)} ${e.members.join(', ')}`;
+  });
+  return 'Councils:\n' + lines.join('\n') + '\n';
+}
+
+/**
+ * `amicus council show <name> [--json]` — resolves `name` exactly like
+ * `resolveCouncilMembers` (user config first, built-in fallback) and
+ * displays the raw members plus per-member resolution results (resolved /
+ * dropped). Unlike `resolveCouncilMembers` (which the run paths use, and
+ * which fails outright below 2 usable members), `show` is diagnostic-only:
+ * it always reports the full resolved/dropped split, even for a council
+ * that currently has fewer than 2 usable members.
+ * @param {string|undefined} name
+ * @param {boolean} useJson
+ * @returns {number} exit code
+ */
+function runShow(name, useJson) {
+  if (!name) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'council show needs a <name>',
+      hint: 'amicus council show <name> [--json]' });
+  }
+  const { getCouncilWithSource, getEffectiveAliases } = require('../utils/config');
+  const { readCache } = require('../utils/model-catalog');
+  const catalog = (readCache() || {}).models || [];
+  const { members, builtin } = getCouncilWithSource(name, catalog);
+  if (!members) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Unknown council '${name}'`,
+      hint: "'amicus council list' shows available councils, or 'amicus council save' to create one" });
+  }
+  const aliases = getEffectiveAliases();
+  const resolved = [];
+  const dropped = [];
+  for (const member of members) {
+    const id = member.includes('/') ? member : aliases[member];
+    (id ? resolved : dropped).push(member);
+  }
+  const doc = { name, builtin, members, resolved, dropped };
+  process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderShow(doc));
+  return 0;
+}
+
+function renderShow(doc) {
+  const tag = doc.builtin ? ' [built-in]' : '';
+  let out = `Council '${doc.name}'${tag}\n  members: ${doc.members.join(', ')}\n  resolved: ${doc.resolved.join(', ')}\n`;
+  if (doc.dropped.length) { out += `  dropped: ${doc.dropped.join(', ')}\n`; }
+  return out;
+}
+
+module.exports = { runSave, runList, runShow };