amicus 4.2.1 → 4.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,7 +3,20 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
-## [Unreleased]
+## [4.3.0] - 2026-07-24
+
+### Added
+
+- **Observability data layer.** Three file surfaces every consumer polls, no push/IPC/`fs.watch` anywhere: the existing durable snapshots (`metadata.json`/`progress.json`/`wave.json`/council `run.json`, all additively extended), a new append-only `events.jsonl` milestone stream per wave dir / council-run dir, and the composed live doc (the `amicus_status` rollup, stamped `view:'live'` with per-leg read-time `usage`).
+- **`amicus watch <id>`** — live-render any fan-out wave, council run, or session from any terminal, reading only the data layer above (no attach): an in-place refresh table on a TTY, milestone lines (`--plain` / non-TTY), or NDJSON (`--json`). `--interval` controls the poll rate (default 2s, floor 0.5s); exit code maps the run's terminal state (`complete`→0, `partial`→2, else 1). `--ui` registers the flag for the v4.4 Council Workspace GUI (rejects `--json`) — the GUI itself is not shipped in this release.
+- **`--follow` on `fanout` and `council run`** — stream a run's own milestone events to stderr as they happen; stdout's `--json`/human contracts stay byte-identical. On `council run`, `--follow` covers the run's own lifecycle and each stage's boundaries, not the per-leg events inside a stage's internal fan-out sub-wave.
+- **`--on-complete` hook.** CLI: runs a user-authored shell command once a wave/council run reaches a terminal state, with the payload carried via 8 environment variables (`AMICUS_TASK_ID`, `AMICUS_TYPE`, `AMICUS_STATUS`, `AMICUS_EXIT_CODE`, `AMICUS_RESULT_FILE`, `AMICUS_EVENTS_FILE`, `AMICUS_COST`, `AMICUS_PROJECT`) — ids/paths only, never model-generated text; exit-isolated from the run (a non-zero exit or a 60s timeout is a warning only). MCP: only `onComplete: "mcp-notify"` is accepted, a best-effort advisory notification — `exec` is never exposed over MCP.
+- **Failed-leg resilience.** `fanout --retry-failed <waveId>` relaunches only a wave's terminal, non-complete legs as a new linked wave (byte-identical retry from each leg's saved context; `--models` filters which legs retry; the original `wave.json` is never touched). `--fallback` / `--no-fallback` opt into per-leg cheaper-model substitution, off by default, triggered only by a classified rate-limit/overload failure (never timeout or auth) and always recorded loudly (a `leg-fallback` event, an `attempts[]` array, a `fallback` block on the final doc).
+- **Spend visibility & attribution.** `continue`/`resume`/council rows are now recorded in the spend ledger, not just `start`/`fanout` legs, and every row carries attribution (`op`/`status`/`waveId`/`councilRunId`/`councilName`/`project`/`gateway`, plus fallback/retry linkage). `amicus spend` grows a full query surface — `--wave`/`--council`/`--project`/`--model`/`--op`/`--failed`/`--group-by <model|wave|council|project|op|day>`/`--rows` — plus a `wasted` rollup (both `--failed` and `wasted` deliberately exclude rows with no recorded status at all, so a pre-v4.3 ledger row is never counted as a failure that was never actually recorded). A new read-only `amicus_spend` MCP tool (16th tool) mirrors the same flags for MCP-only hosts.
+
+### Notes
+
+- All additive: no schema-breaking changes to v4.0 artifacts. `SPEND_LEDGER_SCHEMA_VERSION` stays `1`; both JSONL ledgers (`spend-ledger.jsonl`, `council-ledger.jsonl`) remain internal, non-envelope files, not published docs. A wave dir / council-run dir now also contains `events.jsonl`.
 
 ## [4.2.1] - 2026-07-23
 

package/README.md

@@ -45,12 +45,13 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 
 ## What is Amicus
 
-One install delivers four things that work together:
+One install delivers five things that work together:
 
 - **The `second-opinion` LLM Council skill.** Structured multi-model review: independent reviews → anonymized peer cross-review → a non-Claude chair verdict → tiered accept/deny decisions. This is the hero.
 - **The `sidecar` chat skill.** Ad-hoc fork/work/fold — spin up one other model in a real window (or headless), work alongside it, fold the summary back.
 - **The `amicus` CLI (with an `am` alias) and an MCP server.** The engine underneath both skills: launches sessions, shares context, runs parallel waves, and exposes the same surface to Claude as MCP tools.
 - **A self-updating model catalog.** Aliases and validation resolve against a live catalog fetched from provider APIs (cached locally), so model names stay current without a hard-coded table.
+- **Observability.** `amicus watch <id>` renders any live or finished run (fan-out or council) from any terminal; `--follow` streams milestones as they happen; `--on-complete` fires a hook when a run lands; `--retry-failed` plus opt-in cheaper-model fallbacks recover dead legs without relaunching the whole wave; `amicus spend` answers "what did this cost, and where" with per-run attribution.
 
 Claude is the orchestrator. The council and chat skills run *on top of* the engine; you talk to Claude, and Claude drives Amicus.
 
@@ -313,9 +314,10 @@ amicus update
 | `amicus continue` | Start a new session building on a previous one. |
 | `amicus read` | Output a session's summary / conversation / metadata. |
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
+| `amicus watch <id>` | Live-render a fan-out wave, council run, or session from any terminal until it finishes — in-place table on a TTY, `--plain` milestone lines, or `--json` NDJSON; exit code maps the terminal state. |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
-| `amicus spend` | Cross-run cost rollup from the spend ledger — total + per-model spend, tokens, and source mix, most-expensive first (`--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
+| `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
 | `amicus provider` | Add/list/test/remove local, OpenAI-compatible providers (LM Studio, Ollama, vLLM) — configured with `--preset` or `--url`, at **$0** marginal cost (`--json` on every subcommand). |
 | `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
@@ -348,7 +350,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -382,7 +384,7 @@ Full details, the API-key/prefix table, and the migration notice are in **[docs/
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes fifteen tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes sixteen tools:
 
 | Tool | What it does |
 |------|--------------|
@@ -401,6 +403,7 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_council_stats` | Reviewer-reliability stats from past council runs. |
 | `amicus_verdict` | Build the final council verdict from a tally + decisions; writes `<outDir>/report.html` when `render:true` and `outDir` are given. |
 | `amicus_council_run` | Run the full headless council engine (Stage-1 reviews → anonymized cross-review → tally → chair verdict); returns `{ runId, runDir }`, async. |
+| `amicus_spend` | Read-only cross-run cost rollup from the spend ledger (mirrors the CLI `amicus spend` flags). |
 
 The async pattern is **start → status → read** — `amicus_start`/`amicus_fanout` return immediately, then you poll `amicus_status` and call `amicus_read`; `amicus_wait` collapses that poll loop into one blocking call.
 

package/bin/amicus.js

@@ -127,6 +127,11 @@ async function main() {
         exitCode = await handleSpend(args);
         break;
       }
+      case 'watch': {
+        const { handleWatch } = require('../src/cli-handlers-watch');
+        exitCode = await handleWatch(args);
+        break;
+      }
       case 'provider': {
         const { handleProvider } = require('../src/cli-handlers-provider');
         exitCode = await handleProvider(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [

package/schemas/council-run-live.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/BourbonDog/amicus/schemas/council-run-live.schema.json",
+  "title": "Amicus composed live council-run doc (amicus_status/buildCouncilStatusPayload, view:'live')",
+  "type": "object",
+  "required": ["taskId", "type", "runId", "runDir", "status", "currentStage", "stages", "legsTotal", "legsComplete", "elapsed", "exitCode", "version"],
+  "properties": {
+    "type": { "const": "council-run" },
+    "view": { "const": "live" },
+    "runId": { "type": "string" },
+    "runDir": { "type": "string" },
+    "status": { "type": "string" },
+    "currentStage": { "type": ["string", "null"] },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status"],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string" },
+          "waveId": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "legsTotal": { "type": ["number", "null"] },
+    "legsComplete": { "type": ["number", "null"] },
+    "elapsed": { "type": "string" },
+    "exitCode": { "type": ["number", "null"] },
+    "usage": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/schemas/event.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/BourbonDog/amicus/schemas/event.schema.json",
+  "title": "Amicus observability event (events.jsonl line)",
+  "type": "object",
+  "required": ["schemaVersion", "type", "event", "ts", "id"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "type": { "const": "event" },
+    "event": { "enum": ["wave-started", "leg-started", "leg-fallback", "leg-terminal", "wave-terminal", "retry-started", "run-started", "stage-started", "stage-terminal", "run-terminal"] },
+    "ts": { "type": "string", "format": "date-time" },
+    "id": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/schemas/progress.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/BourbonDog/amicus/schemas/progress.schema.json",
+  "title": "Amicus leg/solo progress snapshot (progress.json)",
+  "type": "object",
+  "required": ["schemaVersion", "type", "stage", "updatedAt"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "type": { "const": "progress" },
+    "stage": { "type": "string" },
+    "stageLabel": { "type": "string" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "messagesReceived": { "type": "number" },
+    "latestTool": { "type": "string" },
+    "usage": {
+      "type": "object",
+      "properties": {
+        "tokens": { "type": "object" },
+        "costReported": { "type": "number" }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/run-live.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/BourbonDog/amicus/schemas/run-live.schema.json",
+  "title": "Amicus composed live single-session doc (amicus_status, view:'live')",
+  "description": "amicus_status's single-session response always stamps type:'run' (stampEnvelope); documented here as a const rather than the brief's 'may be absent' guess to match real output.",
+  "type": "object",
+  "required": ["taskId", "type", "status"],
+  "properties": {
+    "type": { "const": "run" },
+    "view": { "const": "live" },
+    "status": { "type": "string" },
+    "usage": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/schemas/spend.schema.json

@@ -11,6 +11,31 @@
     "windowDays": { "type": ["number", "null"] },
     "total": { "type": "object" },
     "byModel": { "type": "array", "items": { "type": "object" } },
-    "credit": { "type": ["object", "null"] }
+    "credit": { "type": ["object", "null"] },
+    "filters": { "type": "object" },
+    "groupBy": { "enum": ["model", "wave", "council", "project", "op", "day"] },
+    "groups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "amount", "runs"],
+        "properties": {
+          "key": { "type": "string" },
+          "amount": { "type": "number" },
+          "runs": { "type": "number" }
+        }
+      }
+    },
+    "wasted": {
+      "type": "object",
+      "required": ["amount", "runs", "byStatus"],
+      "properties": {
+        "amount": { "type": "number" },
+        "runs": { "type": "number" },
+        "byStatus": { "type": "object" }
+      }
+    },
+    "rows": { "type": "array" },
+    "rowsTruncated": { "type": "boolean" }
   }
 }

package/schemas/wave-live.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/BourbonDog/amicus/schemas/wave-live.schema.json",
+  "title": "Amicus composed live wave doc (amicus_status, view:'live')",
+  "type": "object",
+  "required": ["taskId", "type", "status", "legs"],
+  "properties": {
+    "type": { "const": "wave" },
+    "view": { "const": "live" },
+    "status": { "type": "string" },
+    "legs": { "type": "array", "items": { "type": "object", "properties": { "usage": { "type": "object" } } } },
+    "usage": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/src/cli-handlers-council-run.js

@@ -20,7 +20,30 @@ function parseList(value) {
   return String(value).split(',').map(s => s.trim()).filter(Boolean);
 }
 
-/** Resolve bench models from --models XOR --council (mirrors handleFanout). */
+/**
+ * Sanitize the internal `--council-name` passthrough before it can reach the
+ * spend ledger's `councilName` column (v4.3 Task 4 review fix, spec §7.3:
+ * spend docs hold only ids/numbers/paths "by construction"). That value is
+ * user-supplied (via mcp-council-run.js, ultimately an MCP caller's `input`),
+ * unbounded, and unvalidated — unlike a real `--council <preset>`, which is
+ * catalog-validated upstream. Strips control/non-printable characters, trims,
+ * and caps length so a hostile/malformed passthrough can't land raw in a
+ * `--group-by council` rollup. Precedence is untouched by this: it's applied
+ * only to the passthrough branch, never to the catalog-validated preset name.
+ * @param {string} name @returns {string|null} sanitized name, or null if empty after cleanup
+ */
+function sanitizeCouncilName(name) {
+  // eslint-disable-next-line no-control-regex -- deliberately stripping C0/DEL control chars
+  const cleaned = String(name).replace(/[\x00-\x1F\x7F]/g, '').trim().slice(0, 64);
+  return cleaned || null;
+}
+
+/**
+ * Resolve bench models from --models XOR --council (mirrors handleFanout).
+ * Also returns `presetName` (v4.3 Task 3, spec §7.1): the trimmed --council
+ * name when that branch was taken, else null — threaded into runCouncil's
+ * `councilName` option so council ledger rows can be attributed to a preset.
+ */
 function resolveBench(args, useJson) {
   const hasModels = typeof args.models === 'string' && args.models.trim();
   const hasCouncil = args.council !== undefined && args.council !== false;
@@ -40,16 +63,17 @@ function resolveBench(args, useJson) {
     const { resolveCouncilMembers } = require('./utils/config');
     const { readCache } = require('./utils/model-catalog');
     const catalog = (readCache() || {}).models || [];
-    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
+    const presetName = args.council.trim();
+    const expanded = resolveCouncilMembers(presetName, catalog);
     if (expanded.error) {
       return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }) };
     }
     if (expanded.dropped && expanded.dropped.length && !useJson) {
       process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
     }
-    return { bench: expanded.models };
+    return { bench: expanded.models, presetName };
   }
-  return { bench: parseList(args.models) };
+  return { bench: parseList(args.models), presetName: null };
 }
 
 function renderRunHuman(run) {
@@ -85,6 +109,19 @@ async function handleCouncilRun(args) {
   const benchRes = resolveBench(args, useJson);
   if (benchRes.fail !== undefined) { return benchRes.fail; }
   const bench = benchRes.bench;
+  // v4.3 Task 3 (spec §7.1): the preset name, when this run came from a real
+  // --council <preset>. `--council-name` is an internal, undocumented passthrough
+  // set by mcp-council-run.js — the MCP handler always expands a preset to
+  // `--models` before spawning (so `--council`/`--models` stay mutually exclusive
+  // on this CLI surface), which would otherwise strand the preset name with no
+  // way to reach this process. Never fabricated: --models with neither flag
+  // stays null, matching spec §7.1 ("preset name … else null"). The
+  // passthrough branch is sanitized (see sanitizeCouncilName docblock) — the
+  // preset-name branch is catalog-validated upstream and never touched here,
+  // so precedence (a real --council preset always outranks the passthrough)
+  // is unchanged.
+  const councilName = benchRes.presetName
+    || (typeof args['council-name'] === 'string' ? sanitizeCouncilName(args['council-name']) : null);
   if (bench.length < 2) {
     return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
       message: 'Error: a council needs at least 2 seats (fanout semantics)' });
@@ -139,8 +176,11 @@ async function handleCouncilRun(args) {
     ? path.resolve(project, String(args['out-dir']))
     : path.resolve(project, `council-${runId}`);
 
-  const { resolveGatewayMode } = require('./utils/config');
+  const { resolveGatewayMode, loadConfig } = require('./utils/config');
+  const { resolveFallbackConfig } = require('./sidecar/fallback-chains');
+  const { readCache } = require('./utils/model-catalog');
   const { runCouncil } = require('./council/run');
+  const cfg = loadConfig() || {};
   const { exitCode, run } = await runCouncil({
     briefing: promptRes.prompt, models: bench, chair, critic, lenses,
     project, runId, runDir,
@@ -148,6 +188,7 @@ async function handleCouncilRun(args) {
     gateway: resolveGatewayMode(args.gateway),
     noValidateModel: !!args['no-validate-model'],
     date: new Date().toISOString().slice(0, 10),
+    councilName,
     // v4.1 §4.5b/§4.5d. `--claude-review` is resolved here but VALIDATED by the
     // engine's preflightClaudeReview (run-assemble.js): the reserved-seat and
     // 'claude may not chair' guards live there on purpose so MCP, the GitHub
@@ -157,6 +198,21 @@ async function handleCouncilRun(args) {
     debate: !!args.debate,
     claudeReviewFile: args['claude-review'] ? path.resolve(args['claude-review']) : null,
     noCostGate: !!args['no-cost-gate'],
+    // v4.3 Task 13: --follow's json-vs-human mode mirrors the same --json this
+    // handler already resolved for the final run doc, so `--json --follow`
+    // NDJSON on stderr and the `--json` final doc on stdout agree.
+    follow: !!args.follow,
+    json: useJson,
+    onComplete: args['on-complete'],
+    // v4.3 Task 18 (spec §6.2): opt-in cheaper-model substitution for STAGE
+    // legs only (run-stages.js threads it through; the chair is excluded —
+    // see run-chair.js). --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 || [],
   });
 
   if (useJson) {

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,15 +38,6 @@ 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
@@ -75,11 +75,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 +92,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 +139,7 @@ async function fetchCreditFooter(deps) {
   return res || null;
 }
 
-function renderHuman({ total, byModel, windowDays, credit }) {
+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';
@@ -140,6 +151,9 @@ function renderHuman({ total, byModel, windowDays, credit }) {
       `${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 (wasted && wasted.runs > 0) {
+    out += `Wasted (failed runs): ${formatCost({ amount: wasted.amount, source: 'mixed' })} across ${wasted.runs} rows — see amicus spend --failed\n`;
+  }
   if (credit && typeof credit.limitRemaining === 'number') {
     out += `OpenRouter credit remaining: $${credit.limitRemaining}\n`;
   }
@@ -155,8 +169,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 +190,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,
+};