amicus 1.1.0 → 1.2.0

package/src/cli-handlers-run.js

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

package/src/cli-handlers.js

@@ -97,7 +97,7 @@ async function handleAbort(args) {
 
   if (!taskId) {
     console.error('Error: task_id is required for abort');
-    console.error('Usage: sidecar abort <task_id>');
+    console.error('Usage: amicus abort <task_id>');
     process.exit(1);
   }
 

package/src/cli.js

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

package/src/council/findings.js

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

package/src/council/ledger.js

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

package/src/council/tally.js

@@ -0,0 +1,108 @@
+// src/council/tally.js
+'use strict';
+
+/**
+ * Peers-only tier cascade. a/d are agree/dispute counts among PEER judges
+ * (the raiser's own adjudication is excluded by the caller).
+ * Exhaustive and mutually exclusive over all (a,d).
+ * @param {number} a - peer agree count
+ * @param {number} d - peer dispute count
+ * @returns {{tier:string, confidence:'thin'|'solid'}}
+ */
+function assignTier(a, d) {
+  let tier;
+  if (d >= 2 && d > a) { tier = 'Disputed'; }
+  else if (a >= 2 && a > d) { tier = 'Confirmed'; }
+  else if (d >= 1) { tier = 'Contested'; }
+  else { tier = 'Singleton'; }
+  const confidence = (a + d <= 1) ? 'thin' : 'solid';
+  return { tier, confidence };
+}
+
+function mean(arr) { return arr.reduce((s, x) => s + x, 0) / arr.length; }
+
+/** Map each model to its (possibly fractional) rank position in one judge's order. */
+function rankPositions(order) {
+  const pos = new Map();
+  let p = 1;
+  for (const slot of order) {
+    const group = Array.isArray(slot) ? slot : [slot];
+    const meanPos = p + (group.length - 1) / 2;
+    for (const m of group) { pos.set(m, meanPos); }
+    p += group.length;
+  }
+  return pos;
+}
+
+/**
+ * Both-numbers street-cred. Lower mean rank = better.
+ * @param {Array<{judge:string, order:Array<string|string[]>}>} rankings
+ * @param {string[]} models all reviewed models (incl. claude when in-council)
+ */
+function computeStreetCred(rankings, models) {
+  const judgePos = rankings.map(r => ({ judge: r.judge, pos: rankPositions(r.order) }));
+  return models.map(m => {
+    const all = [], peers = [], perJudgeRank = {};
+    for (const { judge, pos } of judgePos) {
+      if (!pos.has(m)) { continue; }       // absent from this judge's ranking → skip
+      const rank = pos.get(m);
+      perJudgeRank[judge] = rank;
+      all.push(rank);
+      if (judge !== m) { peers.push(rank); }
+    }
+    return {
+      model: m,
+      withSelf: all.length ? mean(all) : null,
+      peersOnly: peers.length ? mean(peers) : null,
+      perJudgeRank,
+    };
+  });
+}
+
+const COUNCIL_SCHEMA_VERSION = 1;
+const VERDICTS = { agree: 'a', dispute: 'd', neutral: 'n' };
+
+function countTiers(findings) {
+  const counts = { Confirmed: 0, Contested: 0, Singleton: 0, Disputed: 0 };
+  for (const f of findings) { counts[f.tier] += 1; }
+  return counts;
+}
+
+/**
+ * Deterministic council tally. Pure: no IO. Claude assembles `input`
+ * (de-anonymized) and may override margin tiers afterward.
+ * @returns {object} record
+ */
+function tally(input) {
+  const { meta, findings, rankings, adjudications, runStats } = input;
+  const byFinding = new Map();
+  for (const adj of adjudications) {
+    if (!byFinding.has(adj.findingId)) { byFinding.set(adj.findingId, []); }
+    byFinding.get(adj.findingId).push({ judge: adj.judge, verdict: adj.verdict });
+  }
+  const outFindings = findings.map(f => {
+    const votes = byFinding.get(f.id) || [];
+    const peers = votes.filter(v => v.judge !== f.raiser);
+    const basis = { a: 0, d: 0, n: 0 };
+    for (const v of peers) { basis[VERDICTS[v.verdict]] += 1; }
+    const { tier, confidence } = assignTier(basis.a, basis.d);
+    return { id: f.id, raiser: f.raiser, severity: f.severity, tier, basis, confidence,
+             tierOverride: null, adjudications: votes };
+  });
+  return {
+    schemaVersion: COUNCIL_SCHEMA_VERSION,
+    meta,
+    judged: Array.isArray(rankings) && rankings.length >= 2,
+    streetCred: computeStreetCred(rankings || [], meta.models),
+    findings: outFindings,
+    runStats: (runStats || []).map(r => ({
+      model: r.model, role: r.role, wasChair: !!r.wasChair, conformance: r.conformance || 'clean',
+      status: r.status || 'unknown',
+      durationMs: typeof r.durationMs === 'number' ? r.durationMs : null,
+      usage: r.usage || null,
+    })),
+    tierCounts: countTiers(outFindings),
+  };
+}
+
+module.exports = { assignTier, computeStreetCred, tally, COUNCIL_SCHEMA_VERSION };

package/src/council/verdict.js

@@ -0,0 +1,48 @@
+// src/council/verdict.js
+'use strict';
+const fs = require('fs');
+
+const VERDICT_SCHEMA_VERSION = 1;
+
+/**
+ * Merge a tally record with Claude's Stage-4 decisions into the verdict record.
+ * @param {object} record  tally() output
+ * @param {Array<{id,decision,applied,duplicateOf,tierOverride}>} decisions
+ */
+function buildVerdict(record, decisions = []) {
+  const byId = new Map(decisions.map(d => [d.id, d]));
+  return {
+    schemaVersion: VERDICT_SCHEMA_VERSION,
+    runId: record.meta.runId,
+    runType: record.meta.runType,
+    date: record.meta.date,
+    chair: record.meta.chair,
+    council: record.meta.models,
+    claudeInCouncil: record.meta.claudeInCouncil,
+    findings: record.findings.map(f => {
+      const d = byId.get(f.id) || {};
+      const tierOverride = d.tierOverride || f.tierOverride || null;
+      return {
+        id: f.id, raiser: f.raiser, severity: f.severity,
+        tier: tierOverride ? tierOverride.to : f.tier,
+        basis: f.basis, confidence: f.confidence, tierOverride,
+        duplicateOf: d.duplicateOf || null,
+        adjudications: f.adjudications,
+        decision: d.decision || null,
+        applied: d.applied === true,
+      };
+    }),
+    streetCred: record.streetCred.map(s => ({ model: s.model, withSelf: s.withSelf, peersOnly: s.peersOnly })),
+    runStats: record.runStats,
+    tierCounts: record.tierCounts,
+  };
+}
+
+/** Atomic write: tmp + rename (matches the repo's wave.json convention). */
+function writeVerdictAtomic(filePath, verdict) {
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(verdict, null, 2));
+  fs.renameSync(tmp, filePath);
+}
+
+module.exports = { buildVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION };