amicus 1.2.1 → 1.4.0

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;
@@ -524,9 +531,38 @@ const handlers = {
   async amicus_fanout(input, project) {
     const cwd = project || getProjectDir(input.project);
     const { generateTaskId } = require('./sidecar/start');
-    const { deriveLegIds } = require('./sidecar/fanout');
+    const { deriveLegIds, DEFAULT_MAX_LEGS } = require('./sidecar/fanout');
+
+    // Resolve a single effective models list (council OR models), validated
+    // BEFORE any wave dir / metadata is written so a bad request never strands
+    // a pid-less 'running' orphan wave.
+    const inputModels = Array.isArray(input.models) ? input.models : [];
+    const hasModels = inputModels.length > 0;
+    const hasCouncil = typeof input.council === 'string' && input.council.trim();
+    if (hasModels && hasCouncil) {
+      return textResult("Pass exactly one of 'models' / 'council', not both.", true);
+    }
+    let effectiveModels;
+    if (hasCouncil) {
+      const { resolveCouncilMembers } = require('./utils/config');
+      const { readCache } = require('./utils/model-catalog');
+      const catalog = (readCache() || {}).models || [];
+      const expanded = resolveCouncilMembers(input.council.trim(), catalog);
+      if (expanded.error) { return textResult(expanded.error, true); }
+      effectiveModels = expanded.models;
+    } else if (hasModels) {
+      effectiveModels = inputModels;
+    } else {
+      return textResult("Provide 'models' or 'council'.", true);
+    }
+    const envCap = Number(process.env.AMICUS_FANOUT_MAX_LEGS);
+    const maxLegs = (Number.isInteger(envCap) && envCap > 0) ? envCap : DEFAULT_MAX_LEGS;
+    if (effectiveModels.length > maxLegs) {
+      return textResult(`Council/model list exceeds the fan-out cap of ${maxLegs} legs.`, true);
+    }
+
     const waveId = generateTaskId();
-    const legIds = deriveLegIds(waveId, input.models.length);
+    const legIds = deriveLegIds(waveId, effectiveModels.length);
     const waveDir = getSessionDir(cwd, waveId);
 
     let briefingPath;
@@ -538,14 +574,14 @@ const handlers = {
       fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
       fs.writeFileSync(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
-        models: input.models, headless: true, createdAt: new Date().toISOString(),
+        models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
       }, null, 2), { mode: 0o600 });
     } catch (err) {
       return textResult(`Failed to prepare fan-out wave: ${err.message}`, true);
     }
 
     const args = [
-      'fanout', '--models', input.models.join(','),
+      'fanout', '--models', effectiveModels.join(','),
       '--prompt-file', briefingPath, '--wave-id', waveId,
       '--json', '--client', 'cowork', '--cwd', cwd,
     ];
@@ -574,6 +610,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 +649,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

@@ -255,8 +255,11 @@ function getTools() {
       'document (per-leg summaries inside). Each leg is also an ordinary ' +
       'session readable by taskId.',
     inputSchema: {
-      models: z.array(safeModel).min(1).max(10).describe(
-        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed.`
+      models: z.array(safeModel).min(1).max(10).optional().describe(
+        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
+      ),
+      council: z.string().optional().describe(
+        "Run a saved council by name (e.g. 'free') instead of 'models'. Expands to the council's members. Mutually exclusive with 'models'."
       ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
@@ -281,6 +284,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/setup.js

@@ -40,19 +40,23 @@ function addAlias(name, modelString) {
 }
 
 /**
- * Create a new config with all default aliases and the chosen default model
+ * Ensure a config exists with the chosen default model. Read-modify-write:
+ * preserves every pre-existing top-level key (aliases, councils, …) and only
+ * fills in the default + any missing default aliases. Never clobbers.
  * @param {string} defaultModel - Default model alias or full model string
- * @returns {object} The created config object
+ * @returns {object} The resulting config object
  */
 function createDefaultConfig(defaultModel) {
+  const existing = loadConfig() || {};
   const cfg = {
-    default: defaultModel,
-    aliases: getDefaultAliases()
+    ...existing,
+    default: existing.default || defaultModel,
+    aliases: { ...getDefaultAliases(), ...(existing.aliases || {}) },
   };
   saveConfig(cfg);
-  logger.info('Default config created', {
-    default: defaultModel,
-    aliasCount: Object.keys(cfg.aliases).length
+  logger.info('Default config ensured', {
+    default: cfg.default,
+    aliasCount: Object.keys(cfg.aliases).length,
   });
   return cfg;
 }
@@ -152,13 +156,70 @@ async function seedCatalog(print) {
   log('Model catalog unavailable (offline?) — it will refresh on first start.');
 }
 
+/**
+ * Free OpenRouter council branch of the readline wizard. Requires
+ * OPENROUTER_API_KEY; lists free catalog models, lets the user multi-pick
+ * (Enter = the vendor-diverse default), seeds aliases + councils.free, and
+ * never touches config.default.
+ * @param {readline.Interface} rl
+ */
+async function runFreeCouncilBranch(rl) {
+  const keys = detectApiKeys();
+  if (!keys.openrouter) {
+    console.log('');
+    console.log('A free council needs OPENROUTER_API_KEY (free models route only through OpenRouter).');
+    console.log('Set OPENROUTER_API_KEY and re-run: amicus setup. No changes made.');
+    return;
+  }
+  const { getCatalog } = require('../utils/model-catalog');
+  const { listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS } = require('../utils/free-models');
+  let catalog = [];
+  try { catalog = await getCatalog(); } catch (_e) { /* offline */ }
+  let free = listFreeModels(catalog);
+  if (free.length === 0) {
+    console.log('Live free-model list unavailable (offline?) — using a small pinned set.');
+    free = PINNED_FREE_MODELS.map(id => ({ id }));
+  }
+  const defaults = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
+  console.log('');
+  console.log('Free OpenRouter models (★ = default council):');
+  free.forEach((r, i) => {
+    const star = defaults.has(r.id) ? '★' : ' ';
+    console.log(`  ${star} ${i + 1}) ${r.id}`);
+  });
+  console.log('');
+  const answer = await askQuestion(rl,
+    'Pick members (comma-separated numbers, or Enter for the ★ default): ');
+  let pickIds;
+  if (!answer) {
+    pickIds = free.filter(r => defaults.has(r.id)).map(r => r.id);
+  } else {
+    pickIds = answer.split(',').map(s => parseInt(s.trim(), 10))
+      .filter(n => n >= 1 && n <= free.length).map(n => free[n - 1].id);
+  }
+  if (pickIds.length < 2) {
+    console.log('A council needs at least 2 models. No changes made.');
+    return;
+  }
+  const { council } = seedFreeCouncil(pickIds);
+  await seedCatalog();
+  console.log('');
+  console.log(`Free council saved: councils.free = [${council.join(', ')}]`);
+  console.log('Run it:   amicus fanout --council free --prompt "..."');
+  console.log('config.default left unchanged.');
+  console.log('');
+  console.log('Heads up (free tier): rate-limited & quality-variable; some models 404');
+  console.log('unless you enable data-sharing at openrouter.ai/settings/privacy.');
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Default model selection from live quick-picks (read-modify-write, no clobber)
- * 3. Config file save
+ * 2. Mode selection (standard or free council)
+ * 3. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 4. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -185,6 +246,13 @@ async function runReadlineSetup() {
     }
     console.log('');
 
+    const mode = await askQuestion(rl,
+      'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
+    if (mode === '2') {
+      await runFreeCouncilBranch(rl);
+      return;
+    }
+
     const { getCatalog } = require('../utils/model-catalog');
     const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
     let catalog = [];
@@ -282,12 +350,64 @@ async function runInteractiveSetup() {
 
 /* eslint-enable no-console */
 
+/**
+ * Collision-safe alias name from a free model id. Strips the openrouter/
+ * prefix and trailing :free, sanitizes '/'/':' to '-', prefixes 'free-',
+ * and disambiguates against `taken` with a numeric suffix.
+ * @param {string} id e.g. openrouter/deepseek/deepseek-r1:free
+ * @param {Set<string>} taken alias names already in use
+ * @returns {string} e.g. free-deepseek-deepseek-r1
+ */
+function deriveFreeAlias(id, taken) {
+  const base = 'free-' + id
+    .replace(/^openrouter\//, '')
+    .replace(/:free$/, '')
+    .replace(/[/:]/g, '-')
+    .replace(/-+/g, '-');
+  let name = base;
+  let n = 2;
+  while (taken.has(name)) { name = `${base}-${n++}`; }
+  taken.add(name);
+  return name;
+}
+
+/**
+ * Seed free-model aliases + councils.free from chosen catalog ids.
+ * Single atomic read-modify-write. Reuses an existing alias that already
+ * maps to the same id (idempotent re-runs); never touches config.default.
+ * @param {string[]} pickIds full openrouter/.../...:free ids
+ * @returns {{added: Array<{alias:string, model:string}>, council: string[]}}
+ */
+function seedFreeCouncil(pickIds) {
+  const cfg = loadConfig() || { aliases: {} };
+  if (!cfg.aliases) { cfg.aliases = {}; }
+  const taken = new Set(Object.keys(cfg.aliases));
+  const council = [];
+  const added = [];
+  for (const id of pickIds) {
+    const existing = Object.entries(cfg.aliases).find(([, m]) => m === id);
+    if (existing) { if (!council.includes(existing[0])) { council.push(existing[0]); } continue; }
+    const alias = deriveFreeAlias(id, taken);
+    cfg.aliases[alias] = id;
+    added.push({ alias, model: id });
+    council.push(alias);
+  }
+  if (!cfg.councils) { cfg.councils = {}; }
+  cfg.councils.free = Array.from(new Set(council));
+  saveConfig(cfg);
+  logger.info('Free council seeded', { count: cfg.councils.free.length });
+  return { added, council: cfg.councils.free };
+}
+
 module.exports = {
   addAlias,
   createDefaultConfig,
+  deriveFreeAlias,
   detectApiKeys,
+  runFreeCouncilBranch,
   runInteractiveSetup,
   runReadlineSetup,
   runApiKeySetup,
   seedCatalog,
+  seedFreeCouncil,
 };

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/config.js

@@ -273,6 +273,57 @@ function detectFallback(alias, resolvedModel) {
   return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
 }
 
+/** @returns {Object<string,string[]>} the councils map (empty if none) */
+function getCouncils() {
+  const config = loadConfig();
+  return (config && config.councils) || {};
+}
+
+/** @param {string} name @returns {string[]|null} council members, or null if absent */
+function getCouncil(name) {
+  return getCouncils()[name] || null;
+}
+
+/**
+ * Expand a saved council into a runnable members list, degrading gracefully.
+ * Each member is resolved to its full model id (alias → id via effective
+ * aliases; a member containing '/' is taken as-is) and that id checked against
+ * the cached catalog. Unresolvable aliases and delisted ids are dropped with a
+ * warning rather than fail-fast-aborting the whole wave. The catalog check is
+ * skipped when the catalog is empty (offline). Returns members RAW (alias or
+ * id) — leg-time validation resolves them again.
+ * @param {string} name
+ * @param {Array<{id:string}>} [catalog]
+ * @returns {{models:string[], dropped:string[]} | {error:string}}
+ */
+function resolveCouncilMembers(name, catalog = []) {
+  const members = getCouncil(name);
+  if (!members) {
+    return { error: `Unknown council '${name}'. Run 'amicus setup' to create one.` };
+  }
+  if (!Array.isArray(members) || members.length === 0) {
+    return { error: `Council '${name}' is empty. Run 'amicus setup' to populate it.` };
+  }
+  const aliases = getEffectiveAliases();
+  const known = new Set((Array.isArray(catalog) ? catalog : []).map(m => m && m.id).filter(Boolean));
+  const models = [];
+  const dropped = [];
+  for (const member of members) {
+    const id = member.includes('/') ? member : aliases[member];
+    if (!id) { dropped.push(member); continue; }                 // alias no longer resolves
+    if (known.size > 0 && !known.has(id)) { dropped.push(member); continue; } // delisted model
+    models.push(member);
+  }
+  if (models.length < 2) {
+    return {
+      error: `Council '${name}' has fewer than 2 usable members` +
+        (dropped.length ? ` (dropped: ${dropped.join(', ')})` : '') +
+        '. Run \'amicus setup\' to refresh it.',
+    };
+  }
+  return { models, dropped };
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -288,4 +339,7 @@ module.exports = {
   formatAliasNames,
   tryResolveModel,
   buildProviderModels,
+  getCouncils,
+  getCouncil,
+  resolveCouncilMembers,
 };

package/src/utils/free-models.js

@@ -0,0 +1,50 @@
+/**
+ * Free OpenRouter model detection (Unit A).
+ *
+ * A free model is an openrouter/* catalog id whose slug ends in ':free'.
+ * The ':free' suffix is OpenRouter's authoritative free-tier marker. A
+ * zero prompt/completion price is deliberately NOT used: the catalog
+ * normalizer keeps only {prompt, completion} and discards request/image
+ * pricing, so a per-request-charged model with prompt:'0' would be
+ * mislabeled. Pure + network-free.
+ */
+'use strict';
+
+/** Offline last-resort free ids (used only when the live catalog is empty). */
+const PINNED_FREE_MODELS = [
+  'openrouter/deepseek/deepseek-r1:free',
+  'openrouter/google/gemini-2.0-flash-exp:free',
+  'openrouter/qwen/qwen3-coder:free',
+];
+
+/** @param {{id?:string}} row @returns {boolean} */
+function isFreeModel(row) {
+  const id = row && typeof row.id === 'string' ? row.id : '';
+  return id.startsWith('openrouter/') && id.endsWith(':free');
+}
+
+/** @param {Array} catalog @returns {Array} free rows, sorted by vendor then id */
+function listFreeModels(catalog) {
+  const rows = (Array.isArray(catalog) ? catalog : []).filter(isFreeModel);
+  return rows.sort((a, b) => {
+    const va = a.id.split('/')[1] || '';
+    const vb = b.id.split('/')[1] || '';
+    return va === vb ? a.id.localeCompare(b.id) : va.localeCompare(vb);
+  });
+}
+
+/** @param {Array} catalog @param {number} n @returns {Array} ≤n free rows, one per vendor */
+function suggestFreeCouncil(catalog, n = 3) {
+  const out = [];
+  const seenVendors = new Set();
+  for (const row of listFreeModels(catalog)) {
+    const vendor = row.id.split('/')[1] || '';
+    if (seenVendors.has(vendor)) { continue; }
+    seenVendors.add(vendor);
+    out.push(row);
+    if (out.length >= n) { break; }
+  }
+  return out;
+}
+
+module.exports = { isFreeModel, listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS };

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