amicus 4.2.1 → 4.4.0

package/src/cli-handlers-run.js

@@ -116,6 +116,21 @@ async function handleStart(args) {
 async function handleFanout(args) {
   const useJson = !!args.json;
 
+  // --retry-failed <waveId> (v4.3 Task 19, spec 6.1): a completely different
+  // path from the --prompt/--models launch below (no briefing, no required
+  // --models — the original wave's failed legs supply their own saved
+  // context) — dispatch BEFORE any of that validation runs. --models here is
+  // optional and, when present, filters which failed legs get retried.
+  if (args['retry-failed']) {
+    const { retryFailedWave } = require('./sidecar/fanout-retry');
+    const { parseModelsList } = require('./sidecar/fanout-validate');
+    const { exitCode, errorDoc } = await retryFailedWave(String(args['retry-failed']), args.cwd || process.cwd(), {
+      models: parseModelsList(args.models), json: useJson,
+    });
+    if (errorDoc && useJson) { process.stdout.write(JSON.stringify(errorDoc) + '\n'); }
+    return exitCode;
+  }
+
   // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
   // --gateway via validateStartArgs (cli.js) — fanout never did, so a typo'd
   // value silently fell through to resolveGatewayMode's pass-through instead
@@ -178,6 +193,8 @@ async function handleFanout(args) {
   // Direct require — the src/index.js public re-export is added later (Task 13)
   const { runFanout } = require('./sidecar/fanout');
   const { loadConfig, resolveGatewayMode } = require('./utils/config');
+  const { resolveFallbackConfig } = require('./sidecar/fallback-chains');
+  const { readCache } = require('./utils/model-catalog');
   const cfg = loadConfig() || {};
   const { exitCode } = await runFanout({
     models: args.models,
@@ -211,6 +228,15 @@ async function handleFanout(args) {
     maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,
     noCostGate: !!args['no-cost-gate'],
     maxCostPerMtok: cfg.maxCostPerMtok,
+    follow: !!args.follow,
+    onComplete: args['on-complete'],
+    // v4.3 Task 18 (spec §6.2): opt-in cheaper-model substitution. --fallback
+    // forces on, --no-fallback forces off; unset defers to config `fallbacks.enabled`.
+    fallback: resolveFallbackConfig({
+      flagFallback: args.fallback === true ? true : (args['no-fallback'] ? false : undefined),
+      config: cfg,
+    }),
+    catalog: (readCache() || {}).models || [],
   });
   return exitCode;
 }

package/src/cli-handlers-spend.js

@@ -14,11 +14,20 @@
  * 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.
+ *
+ * filterRows/groupRows/computeWasted (spec §7.3/§6.3 query layer) live in the
+ * sibling ./spend-query.js instead of here: adding them inline pushed this
+ * file to 306 lines, over the 300-line size gate. They're re-exported below
+ * so existing/brief-specified imports of them from THIS module still resolve.
+ * GROUP_DIMS/ROWS_CAP (Task 5) live there too, as the single source shared
+ * with the MCP `amicus_spend` tool (src/mcp-tools.js, src/mcp-spend.js) —
+ * re-exported below for the same reason.
  */
 
 const { readSpendRows } = require('./utils/spend-ledger');
 const { formatCost } = require('./utils/pricing');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { filterRows, groupRows, computeWasted, emptyTokens, addTokens, GROUP_DIMS, ROWS_CAP } = require('./spend-query');
 
 const CREDIT_CHECK_TIMEOUT_MS = 5000;
 
@@ -29,36 +38,36 @@ function parseSinceDays(since) {
   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.
+ *
+ * v4.4: `unpricedRows` is the count of rows that contributed NOTHING to
+ * `amount` (no numeric cost). `sourceMix.unknown` is adjacent but not the same
+ * question — it buckets by the row's declared source, whereas this counts what
+ * the arithmetic actually saw. It exists so the renderers can say "$X plus N
+ * unknown" instead of coercing null→0 and printing a measured-looking $0.0000
+ * (diagnosis §8, final paragraph).
  * @param {Array<object>} rows
  */
 function aggregateSpend(rows) {
-  const total = { amount: 0, tokens: emptyTokens(), runs: rows.length, sourceMix: { reported: 0, estimated: 0, unknown: 0 } };
+  const total = { amount: 0, tokens: emptyTokens(), runs: rows.length, unpricedRows: 0, 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 } });
+      byModelMap.set(model, { model, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 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;
+    const priced = typeof cost.amount === 'number';
+    const amount = priced ? cost.amount : 0;
+    if (!priced) { bucket.unpricedRows += 1; total.unpricedRows += 1; }
     bucket.amount += amount;
     total.amount += amount;
     // Any source string outside {reported,estimated} buckets as unknown —
@@ -75,11 +84,16 @@ function aggregateSpend(rows) {
  * 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
+ * New fields (filters/groupBy/groups/wasted/rows/rowsTruncated, spec §7.3)
+ * are all additive and only appear when the caller passes them — byte-compat
+ * for callers/tests that only ever passed {total, byModel, windowDays, credit}.
+ * @param {{total:object, byModel:Array, windowDays:number|null, credit:object|null,
+ *   filters?:object, groupBy?:string, groups?:Array, wasted?:object,
+ *   rows?:Array, rowsTruncated?:boolean}} opts
  */
-function buildSpendDoc({ total, byModel, windowDays, credit }) {
+function buildSpendDoc({ total, byModel, windowDays, credit, filters, groupBy, groups, wasted, rows, rowsTruncated }) {
   const { SCHEMA_VERSION } = require('./utils/result-schema');
-  return {
+  const doc = {
     schemaVersion: SCHEMA_VERSION,
     type: 'spend',
     windowDays: windowDays !== undefined ? windowDays : null,
@@ -87,6 +101,12 @@ function buildSpendDoc({ total, byModel, windowDays, credit }) {
     byModel,
     credit: credit || null,
   };
+  if (filters !== undefined) { doc.filters = filters; }
+  if (groupBy !== undefined) { doc.groupBy = groupBy; }
+  if (groups !== undefined) { doc.groups = groups; }
+  if (wasted !== undefined) { doc.wasted = wasted; }
+  if (rows !== undefined) { doc.rows = rows; doc.rowsTruncated = !!rowsTruncated; }
+  return doc;
 }
 
 /** Real deps; tests override via the second handleSpend arg. */
@@ -128,7 +148,19 @@ async function fetchCreditFooter(deps) {
   return res || null;
 }
 
-function renderHuman({ total, byModel, windowDays, credit }) {
+/**
+ * Cost cell for one rollup bucket. v4.4: a bucket in which NO row carried a
+ * numeric amount has no dollar figure to show — it renders formatCost's `?`
+ * rather than `$0.0000`, which previously read as a measured zero and was the
+ * only thing contradicting the (correct but easily missed) `u` count.
+ */
+function bucketCost(bucket) {
+  const unpriced = bucket.unpricedRows || 0;
+  const hasKnown = (bucket.runs || 0) > unpriced;
+  return formatCost({ amount: hasKnown ? bucket.amount : null, source: dominantSource(bucket.sourceMix) });
+}
+
+function renderHuman({ total, byModel, windowDays, credit, wasted }) {
   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';
@@ -137,9 +169,18 @@ function renderHuman({ total, byModel, windowDays, credit }) {
     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`;
+      `${bucketCost(m).padStart(9)}  ${mix}\n`;
+  }
+  out += `\nTotal: ${bucketCost(total)} across ${total.runs} run(s)\n`;
+  // v4.4: the total is a FLOOR whenever any row is unpriced. Stated on its own
+  // line rather than squeezed into the fixed-width cost column.
+  if (total.unpricedRows > 0) {
+    out += `${total.unpricedRows} unpriced row(s) — cost unknown and NOT in the total; `
+      + 'real spend is at least this much.\n';
+  }
+  if (wasted && wasted.runs > 0) {
+    out += `Wasted (failed runs): ${formatCost({ amount: wasted.amount, source: 'mixed' })} across ${wasted.runs} rows — see amicus spend --failed\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`;
   }
@@ -155,8 +196,11 @@ function dominantSource(mix) {
 }
 
 /**
- * `amicus spend [--since 7d] [--json]`
- * @param {{_:string[], json?:boolean, since?:string}} args
+ * `amicus spend [--since 7d] [--wave <id>] [--council <runId|name>] [--project <path|.>]
+ *   [--model <id-or-prefix>] [--op <op>] [--failed] [--group-by <dim>] [--rows] [--json]`
+ * @param {{_:string[], json?:boolean, since?:string, wave?:string, council?:string,
+ *   project?:string|boolean, model?:string, op?:string, failed?:boolean,
+ *   'group-by'?:string, rows?:boolean}} args
  * @param {object} [depsOverride] test seam
  * @returns {Promise<number>} exit code
  */
@@ -173,26 +217,44 @@ async function handleSpend(args, depsOverride = {}) {
     }
   }
 
-  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 groupBy = args['group-by'] || 'model';
+  if (!GROUP_DIMS.includes(groupBy)) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `invalid --group-by '${groupBy}'`,
+      hint: `--group-by one of: ${GROUP_DIMS.join('|')}` });
+  }
+
+  const rows = readSpendRows(deps.dir);
+  const filters = {
+    wave: args.wave, council: args.council, model: args.model,
+    op: args.op, failed: !!args.failed,
+    project: args.project === '.' || args.project === true ? process.cwd() : args.project,
+  };
+  const filtered = filterRows(rows, { ...filters, since: windowDays, now: windowDays !== null ? deps.now() : undefined });
+
+  const { total, byModel } = aggregateSpend(filtered);
+  const groups = groupRows(filtered, groupBy);
+  const wasted = computeWasted(filtered);
+  let rowsOut, rowsTruncated;
+  if (args.rows) {
+    rowsTruncated = filtered.length > ROWS_CAP;
+    rowsOut = filtered.slice(0, ROWS_CAP);
   }
 
-  const { total, byModel } = aggregateSpend(rows);
-  // Nothing recorded (or nothing in the --since window): skip the network
+  // Nothing recorded (or nothing survives the filters): 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');
+    const doc = buildSpendDoc({ total, byModel, windowDays, credit,
+      filters, groupBy, groups, wasted, rows: rowsOut, rowsTruncated });
+    process.stdout.write(JSON.stringify(doc, null, 2) + '\n');
     return 0;
   }
-  process.stdout.write(renderHuman({ total, byModel, windowDays, credit }));
+  process.stdout.write(renderHuman({ total, byModel, windowDays, credit, wasted }));
   return 0;
 }
 
-module.exports = { handleSpend, aggregateSpend, buildSpendDoc, parseSinceDays };
+module.exports = {
+  handleSpend, aggregateSpend, buildSpendDoc, parseSinceDays,
+  filterRows, groupRows, computeWasted, GROUP_DIMS, ROWS_CAP,
+};

package/src/cli-handlers-watch.js

@@ -0,0 +1,116 @@
+// src/cli-handlers-watch.js
+'use strict';
+
+/**
+ * `amicus watch <id>` (spec 5.1) — render any in-flight (or terminal) run from
+ * any process, reading only the data layer (Surfaces A/B/C). This file owns id
+ * resolution + the command entry; the pure renderers live in
+ * src/observe/watch-render.js (Task 12). No fs.watch — a poll loop over the
+ * composed doc (via handlers.amicus_status) + the events tail.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateTaskId } = require('./utils/validators');
+
+/**
+ * Resolve a watch id to a wave / council / solo target (pure over disk).
+ * Resolution order (spec 5.1): council pointer file -> council; else session
+ * metadata (type:'wave' -> wave, else -> solo); nothing readable -> unknown.
+ * Uses the SAME canonical path builders the rest of the codebase resolves
+ * sessions/pointers with — readPointer (council/run-state.js) and
+ * getSessionDir (session-manager.js) — rather than hand-rolling disk paths,
+ * so watch can never drift from how start/status/council resolve ids.
+ * @param {string} id
+ * @param {string} project
+ * @returns {{kind:'wave'|'council'|'solo'|'unknown', id: string, runDir?: string}}
+ */
+function resolveWatchTarget(id, project) {
+  const clean = String(id).replace(/^council-/, '');
+
+  const { readPointer } = require('./council/run-state');
+  const { containsOnDisk } = require('./utils/path-fence');
+  const ptr = readPointer(project, clean);
+  // readPointer validates `council-<id>.json`'s {runId, runDir} only for
+  // truthiness (run-state.js:133-139), so a tampered or stale pointer can point
+  // runDir anywhere on disk — and this resolver's runDir is what
+  // observe/watch-render.js opens events.jsonl from. Same realpath-containment
+  // fence the v4.4 workspace reads use (src/utils/path-fence.js); a real
+  // runDir is always nested inside project (src/mcp-council-run.js:109 enforces
+  // it at creation time), so nothing legitimate is refused. An escaping pointer
+  // falls through to the session lookup and then 'unknown' — the same outcome a
+  // missing pointer already produces, so handleWatch's BAD_SESSION contract is
+  // unchanged.
+  if (ptr && containsOnDisk(project, ptr.runDir)) {
+    return { kind: 'council', id: clean, runDir: ptr.runDir };
+  }
+
+  // getSessionDir THROWS on a path-traversal id ('..' / separators) — this
+  // resolver is exported and docblocked "pure over disk", so it must be
+  // total for arbitrary input, not just for ids that already passed
+  // validateTaskId in the wired CLI path (handleWatch, below). A throw here
+  // (traversal or otherwise) falls through to 'unknown' like any other
+  // unreadable id, rather than propagating out of a "pure" resolver.
+  try {
+    const { getSessionDir } = require('./session-manager');
+    const metaPath = path.join(getSessionDir(project, clean), 'metadata.json');
+    if (fs.existsSync(metaPath)) {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      return { kind: meta.type === 'wave' ? 'wave' : 'solo', id: clean };
+    }
+  } catch { /* fall through to unknown */ }
+  return { kind: 'unknown', id: clean };
+}
+
+/**
+ * `amicus watch [--ui] <id> [--json|--plain] [--interval <sec>] [--project <p>]`
+ * @param {object} args parsed CLI args
+ * @returns {Promise<number>} exit code (render loop: Task 12)
+ */
+async function handleWatch(args) {
+  // v4.4: `amicus watch [--ui] [runId]` — GUI watch is the same verb (spec
+  // §4.4), not a separate command. Handled at the very top, above id
+  // resolution: unlike the machine-readable path, `--ui` alone (no runId)
+  // is valid and opens the Council Workspace run-list landing, so this
+  // branch must run BEFORE the "id is required" gate below.
+  if (args.ui) {
+    if (args.json) {
+      process.stderr.write('Error: --ui is interactive-only (no --json). Use amicus watch <id> --json for machine output.\n');
+      return 1;
+    }
+    // --project wins over --cwd (same precedence as the non-UI path below) —
+    // DE-ROT F46: `--project` is the documented first-priority option for
+    // `watch`; resolving from --cwd only would silently point the workspace
+    // at the wrong directory when a run was launched elsewhere.
+    const project = args.project || args.cwd || process.cwd();
+    const runId = args._[1] ? String(args._[1]) : '';
+    const { launchWorkspaceWindow } = require('./sidecar/workspace-window');
+    const res = await launchWorkspaceWindow({ project, runId });
+    if (res.error) { process.stderr.write(`${res.error}\n`); }
+    return res.code;
+  }
+
+  const { failJson, ERROR_CODES } = require('./utils/error-doc');
+  const id = args._[1];
+  if (!id || id === true) {
+    process.stderr.write('Error: id is required for watch\nUsage: amicus watch <id> [--json] [--plain] [--interval <sec>]\n');
+    return 1;
+  }
+  const check = validateTaskId(String(id));
+  if (!check.valid) { process.stderr.write(`${check.error}\n`); return 1; }
+
+  const project = args.project || args.cwd || process.cwd();
+  const target = resolveWatchTarget(String(id), project);
+  if (target.kind === 'unknown') {
+    return failJson(!!args.json, {
+      code: ERROR_CODES.BAD_SESSION,
+      message: `watch: id '${id}' not found or unreadable in ${project}`,
+      hint: 'Pass --project if the run was launched elsewhere.',
+    });
+  }
+
+  const { runWatchLoop } = require('./observe/watch-render');
+  return runWatchLoop(target, args, project);
+}
+
+module.exports = { handleWatch, resolveWatchTarget };

package/src/cli.js

@@ -143,6 +143,12 @@ function isBooleanFlag(key) {
      'render',               // council verdict: also refresh report.html next to the decided verdict
      'claude',               // init: register for Claude Code only (Task 15)
      'desktop',              // init: register for Claude Desktop only (Task 15)
+     'failed',               // spend: only non-complete (wasted) rows (v4.3 Task 4, spec §7.3)
+     'rows',                 // spend: include matching raw rows, capped at 1000 (v4.3 Task 4)
+     'plain',                // watch: milestone log lines instead of the refresh table (v4.3 Task 11)
+     'ui',                   // watch: open the Council Workspace window; v4.4 seam (v4.3 Task 11)
+     'follow',               // fanout / council run: stream this run's own events to stderr (v4.3 Task 13)
+     'fallback',             // fanout / council run: opt-in cheaper-model substitution (v4.3 Task 18, spec 6.2); --no-fallback negates via the generic no-* catch-all below
    ];
   return booleanFlags.includes(key);
 }
@@ -369,6 +375,7 @@ Commands:
   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
+  watch <id> [--json] [--plain] [--interval <sec>]   Live-render a run from any terminal
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
@@ -431,10 +438,27 @@ Options for 'fanout':
                                ~32KB Windows argument cap). Mutually exclusive
                                with --prompt. Also works with 'start'.
   --wave-id <id>               Explicit wave ID (leg IDs become <id>-1..N)
+  --retry-failed <waveId>       Relaunch ONLY that wave's failed/timed-out/crashed/
+                                aborted legs as a NEW linked wave, using each leg's
+                                own saved context (byte-identical retry). Skips
+                                --prompt/--models; --models filters which failed
+                                legs to retry. wave.json is never modified.
   --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
+  --fallback / --no-fallback   Opt-in cheaper-model substitution on a classified
+                               rate-limit/overload leg failure (spec 6.2). Overrides
+                               config fallbacks.enabled when passed; default: config, else off.
   --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
+  --follow                      Stream this run's events to stderr as they happen (--json -> NDJSON)
+  --on-complete <cmd>           Run a shell command once, at terminal state, after
+                                wave.json is durable. The command is user-authored
+                                on THIS command line (CLI-only — never sourced from
+                                config/briefings/model output); payload rides via
+                                env only (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/
+                                RESULT_FILE/EVENTS_FILE/COST/PROJECT), never model
+                                text. Child stdout/stderr go to amicus stderr.
+                                Never changes the wave's exit code, docs, or events.
   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
@@ -519,7 +543,8 @@ Subcommands for 'council':
       [--chair <model>] [--critic <model>] [--lenses s1,s2,...]
       [--out-dir <dir>] [--json] [--max-cost <usd>] [--timeout <min>]
       [--gateway auto|direct|openrouter] [--no-validate-model]
-      [--debate] [--claude-review <file>] [--no-cost-gate]
+      [--debate] [--claude-review <file>] [--no-cost-gate] [--follow]
+      [--fallback] [--no-fallback] [--on-complete <cmd>]
                                 Run the full headless council engine (v4.0).
                                 Chair default: deepseek (must NOT be a bench seat).
                                 --critic and --lenses are mutually exclusive.
@@ -527,6 +552,21 @@ Subcommands for 'council':
                                 --claude-review <file> enters Claude's own review as
                                 a judged entry; --no-cost-gate disables the per-leg
                                 price gate for the whole run (repairs + chair).
+                                --fallback/--no-fallback opts stage legs (Stage-1 +
+                                Stage-2) into cheaper-model substitution on a
+                                classified rate-limit/overload failure (spec 6.2);
+                                the chair never substitutes via chains.
+                                --follow streams run events to stderr as they
+                                happen (--json -> NDJSON).
+                                --on-complete <cmd> runs a shell command once, at
+                                terminal state, after run.json is durable. The
+                                command is user-authored on THIS command line
+                                (CLI-only — never sourced from config/briefings/
+                                model output); payload rides via env only
+                                (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/RESULT_FILE/
+                                EVENTS_FILE/COST/PROJECT), never model text. Child
+                                stdout/stderr go to amicus stderr. Never changes
+                                the run's exit code, docs, or events.
                                 Exit: 0 full run, 2 degraded, 1 quorum/cost/validation.
   save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
     --json                     Machine-readable output
@@ -544,9 +584,26 @@ Options for 'doctor':
   spend: `
 Options for 'spend':
   --since <Nd>                  Restrict to the last N days (e.g. --since 7d)
+  --wave <id>                   Only rows from this fan-out wave
+  --council <runId|name>        Only rows from this council run (id or preset name)
+  --project <path|.>            Only rows from this project ('.' = cwd)
+  --model <id-or-prefix>        Only rows whose model starts with this
+  --op <start|continue|resume|leg>   Only rows with this operation
+  --failed                      Only non-complete (wasted) rows
+  --group-by <model|wave|council|project|op|day>   Rollup dimension (default model)
+  --rows                        Include matching raw rows (capped at 1000)
   --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.
+`,
+  watch: `
+Options for 'watch':
+  <id>                          A fan-out wave id, council run id, or session id
+  --project <path>              Project the run was launched in (default cwd)
+  --interval <sec>              Refresh interval (default 2, floor 0.5)
+  --plain                       Milestone log lines instead of the refresh table
+  --json                        NDJSON: tailed events + composed doc on change + final doc
+  --ui                          Open the Council Workspace window (v4.4; interactive-only)
 `,
   setup: `
 Options for 'setup':

package/src/council/briefings.js

@@ -121,13 +121,46 @@ function buildLensBriefing({ lens, briefing, date }) {
  * repair loop). References ONLY the json-shape fragment — never the
  * "prose review THEN json" framing — so a headless model isn't handed license
  * to write a whole new prose review on a tight repair turn.
+ *
+ * ⚠️ LC-6. This used to carry the validation ERRORS without the REVIEW they
+ * were errors about, and a repair solo is a FRESH session with no memory of
+ * the review turn. Three of five paid councils burned a seat on it:
+ *   - wsgate02 `qwen`  — refused twice: "I don't have a previous review to correct"
+ *   - wsgate04 `glm`   — refused twice: "the previous review's content was
+ *                        excluded by the caller… I will not fabricate findings"
+ *   - costgate01 `grok` — COMPLIED, by inventing a self-referential finding
+ *                        about its own empty output, which then entered
+ *                        tally.json, the street-cred table and the chair
+ *                        synthesis as C1 and reached a human's decision.
+ * Honest models lose the seat (a 4-model bench silently adjudicating on 3,
+ * still paying for the fourth); compliant ones poison the record.
+ *
+ * `review` is the text that ACTUALLY failed — the original review on the first
+ * attempt, the previous repair's output on the second — so the errors and the
+ * artifact they describe are always the same thing. It is embedded verbatim and
+ * uncapped: the largest real case was 35 KB, and a silent truncation would
+ * recreate this defect in a subtler form (repairing a review the model can only
+ * half see).
+ * @param {{errors?: Array<{code: string, detail: string}>, review?: string}} args
  */
-function buildFindingsRepairPrompt({ errors }) {
+function buildFindingsRepairPrompt({ errors, review }) {
   const lines = (errors || []).map(e => `- ${e.code}: ${e.detail}`).join('\n');
+  const text = typeof review === 'string' ? review.trim() : '';
+  // The absent case is stated, never papered over with an empty block: a model
+  // asked to repair nothing must be told to report nothing rather than left to
+  // guess, which is precisely what produced grok's invented finding.
+  const prior = text
+    ? ['--- YOUR PREVIOUS REVIEW (verbatim — this is the text to correct) ---',
+      text,
+      '--- END OF YOUR PREVIOUS REVIEW ---'].join('\n')
+    : 'Your previous response was empty — there is no prior review text to correct. ' +
+      'Do not invent findings to satisfy the schema: emit an empty "findings" array ' +
+      'and say so in "overall".';
   return [
     'Do NOT use any tools or read any files; everything is in this message; begin ' +
     'immediately with the JSON block.',
-    'Your previous review\'s trailing findings JSON failed validation with these errors:',
+    prior,
+    'That review\'s trailing findings JSON failed validation with these errors:',
     lines,
     'Re-emit ONLY the corrected findings JSON block (the same findings, fixed — do not ' +
     'add or remove findings), as a single fenced ```json block:',