amicus 4.6.3 → 4.7.1

package/docs/ROADMAP.md

@@ -2,19 +2,26 @@
 
 **Reprioritization guidance (Christian, 2026-07-18):** engine-first is locked; the near-term work
 ships as an incremental **4.x point-release line**, each rev delivering a **behavioral / feature
-benefit users feel**; **enterprise-readiness is a venture unto itself** — the deliberate **5.0**
-major jump, gated on funding/cofounder. The observability arc is split so the **data layer ships
-first (v4.3)** and the **Electron "Council Workspace" (v4.4)** rides on top of it. `--dry-run` cost
-preview dropped to the backlog.
-
-Amicus is at **v4.6.2** (tagged 2026-08-05). Each 4.x rev below leads with the benefit, not the
+benefit users feel**. The observability arc is split so the **data layer ships first (v4.3)** and
+the **Electron "Council Workspace" (v4.4)** rides on top of it. `--dry-run` cost preview dropped to
+the backlog.
+
+**Amendment (Christian, 2026-08-05): enterprise-readiness leaves the rev pipeline.** It was carried
+here as a numbered **v5.0** heading, which made it read as *scheduled work with a version reserved
+for it* — a commitment the product cannot make while it is gated on funding and a cofounder. It now
+lives under **Backlog (tracked, not scheduled)** with everything else that is real but unscheduled.
+Nothing about the content changed and no judgment about its value is implied; only its status. When
+an org buyer and the org to support them exist, it earns a number then.
+
+Amicus is at **v4.7.0** (tagged 2026-08-08). Each 4.x rev below leads with the benefit, not the
 plumbing.
 
-**Status:** v4.0 through **v4.6.2** have **shipped** — everything down to the v4.7 heading is a
-record of what landed, not a plan. **v4.7 (composition + tagging + GUI ergonomics) is the next
-planned rev** — that scope carried the number v4.6 here until the degrade-announcement-invariant
-milestone took the v4.6.0 release (2026-08-02); renumbered, not descoped. v5.0 remains
-forward-looking.
+**Status:** v4.0 through **v4.7.0** have **shipped** — everything on this page is a record of what
+landed, not a plan. Composition — the scope that
+carried the number v4.6 here until the degrade-announcement-invariant milestone took the v4.6.0
+release (2026-08-02) — is now an unscheduled candidate for the next rev, tabled in its own section
+below (dropped from v4.7, 2026-08-05); its contents are decided at kickoff per the anti-rot rule,
+not assumed in advance. There is **no numbered major** on this roadmap.
 
 > 📁 **Reading this from an npm install?** Some references below point at working documents that
 > live in the git repository and are deliberately **not** in the published package — anything under
@@ -169,20 +176,78 @@ fooled, and a handful of proven small defects land with tests.
   path; the README/install scripts/doctor all agree on the real Node ≥22.12 floor; eleven
   duplicated doctor test fixtures consolidate into one factory — #110
 
-## v4.7 — "Compose your councils" *(renumbered from v4.6, 2026-08-02 — spec + fresh plan at kickoff per the anti-rot rule)*
-**Benefit:** councils chain — generate → critique → refine with no manual copy-paste — and history
-becomes navigable.
-- **Composable/chained waves** (`--input-from <id>` / `--prompt-file -` pipe + per-source digests) —
-  F6 *(M)* — brings the `{{input}}` template variable + the `critique`/`refine` built-ins
-- **Session/wave tagging + `--search` + grouped history** (F8) *(S–M)*
-- **GUI power ergonomics** (F10: focus-follows fold hotkey, distinguishable window titles, tiling
-  presets) *(S each)*
-- Deferred-item candidates per the v4.5 design doc's §8: RN-2, TST-1/TST-2, REL-2, CA-4
-  (repair-solos half — the failed-chair half shipped v4.6.2), remainder of TST-7
-- **README + docs update** *(S)*
-> The 2026-07-19 combined spec (`2026-07-19-v4.5-policy-packs-composition-design.md`) holds the
-> approved chaining/tagging/F10 design detail and is the primary input to the v4.7 brainstorm; it
-> is NOT executed as-written — v4.7 gets its own spec + fresh plan at kickoff.
+## v4.7 — "The count is the count" — ✅ SHIPPED v4.7.0, 2026-08-08
+**Benefit:** every number amicus shows you is the number — what a council cost, which legs ran, and
+which model earned the credit.
+
+**Shipped across ten `v4.7-*` PRs** — PR0 (extractions) through PR7, plus the PR3 riders and a
+closing documentation pass: the `runStats` completeness half of CA-4, the GOA-7 ledger
+prerequisite, F8 session/wave tagging with `--search`, and four correction sweeps (PR4–PR7).
+
+**Why this scope, and why it replaced composition.** Rescoped after a roadmap review on 2026-08-05
+(the number was carried here as v4.6 until the degrade-announcement-invariant milestone took the
+v4.6.0 release) that started from *how the tool is actually used* rather than from the deferral
+list. Two findings drove it:
+
+1. **The Workspace is an instrument panel, not a workspace** (owner, 2026-08-05): it is used for
+   **live status while a council runs** and for **quantitative stats** — *never* to read council
+   output, which is read in the terminal or through the orchestrating agent. That retires the F10
+   ergonomics line wholesale (all three items are reading/working affordances) and promotes anything
+   that makes the numbers right.
+2. **`runStats` is a cost source, not just a record.** Verified at `8d0584a`:
+   `cli-handlers-council.js:56` computes `amicus council stats` cost as
+   `sumWaveUsage(r.runStats).cost` with **no fallback**; `council/report.js:79` falls back to
+   `sumWaveUsage(runStats).cost` when wave usage is absent; `council/ledger.js:24` joins street-cred
+   off the same array. So CA-4's omissions are not a schema nicety — they under-report spend on the
+   surface the owner relies on, which collides with the cost-truth principle (*reported > estimated
+   > unknown; never fabricate $0*). An omitted leg is not "unknown" — it renders as money never
+   spent on legs that spent money.
+
+> **Tense note.** The bullets below were written as pre-work problem statements and are kept for
+> the record of *why* the rev was scoped this way. Each now leads with what shipped; the
+> problem-statement text that follows it is history, not a live defect.
+
+- **CA-4 (remaining half) — `runStats` completeness** *(M)*: **shipped.** Stage-2 judges and repair
+  solos *were* absent from `tally.json`'s `runStats` (observed: 5 rows for 11 real legs in
+  `wsgate04`); `runStats` now carries one row per paid launch — one `judge` row per judge
+  (`run-assemble.js:180-184`) and one `repair` row per `-q<N>` solo, failed ones included
+  (`run-stage2.js:122`).
+  ⚠️ **Scope correction:** the failed-chair third of the original CA-4 is **closed** — v4.6.2's
+  `chairAttempts[]` records every attempt on `run.json` (`run-chair.js:133` cites LC-5 by name), and
+  failed-chair cost already reaches `runStats` too: a failed ch1–ch3 attempt gets its own
+  `chair-attempt` row there carrying that leg's real `usage` (`run-chair.js:154-156`), so no third
+  row class was needed.
+- **GOA-7 prerequisite — segment the ledger by RESOLVED model, not alias** *(S–M)*: **shipped.**
+  `ledger.js:124` now keys on `row.resolvedModel || row.model` and `LEDGER_SCHEMA_VERSION` is 2.
+  It *was* a live defect: ledger rows keyed by council alias and aliases silently retarget (`gpt-pro` →
+  `gpt-5.6-sol-pro`, the `opus` re-pin — both 2026-08-04), so `council stats` conflates distinct
+  models under one name. The ledger is append-only, so every run adds rows that will later have to
+  be distrusted, and both GOA-1 and GOA-2 plan to build on this data. Bump `LEDGER_SCHEMA_VERSION`;
+  old rows stay readable (absent id ⇒ legacy). Full write-up and schema discipline: `BACKLOG.md`
+  GOA-7. *(Recency decay — GOA-7's second half — is NOT in this rev.)*
+- **Session/wave tagging + `--search` + grouped history** (F8) *(S–M)* — **shipped**
+  (`--tag`, `amicus list --search`, `--limit`, `spend --group-by tag`). The one element carried
+  over from the composition scope, and the one with a visible paper trail: this repo's own
+  `BACKLOG.md` hand-maintained an index of run identifiers (`wave 47278069`, `run dfb6a692`,
+  `runs 0084d48c + 2039b2d1`, `wsgate02`/`wsgate04`) **because there was no search**. It is also the
+  rev's only daily-felt user surface — three schema fixes alone are a thin story.
+- **README + docs update** *(S)* — the last scope line; **closed by PR #132**, which corrected the
+  sentences v4.7 had made false rather than adding coverage the feature PRs had already shipped.
+
+> **Why these belong in one rev.** CA-4 and GOA-7's prerequisite are the same defect class — the run
+> record under-reporting what actually happened — and both are schema-shaped. Each was individually
+> deferred with the same reason (*"M, a schema question, not a fix"*), which is exactly why neither
+> has ever been done: too big for a patch, too small to carry a rev alone. One schema pass is
+> materially cheaper than two.
+>
+> **Lineage.** v4.6 made a loss announce itself; v4.7 makes the accounting match reality. Same
+> invariant family, applied to numbers instead of degradation.
+>
+> ⚠️ **Two hard gates apply before any task touches council internals** — see `BACKLOG.md`
+> *Next-rev hard gates*: the tight-file extraction pass (`cli-handlers-council-run.js` is at
+> **299/300 exactly**, `run-debate.js` at 299, two files **at 300**), and KNOWN_VARIABLES
+> single-sourcing **only if** `{{input}}` is ever scoped — it is not in this rev, so that gate
+> travels with composition rather than blocking here.
 
 ### Deferred out of v4.4.1 into v4.5 (2026-07-27)
 
@@ -202,7 +267,7 @@ a proposed disposition — v4.5 ride-along / v4.6 / backlog — tabled for rulin
 | **CA-4** | `tally.json`'s `runStats` omits Stage-2 judges, repair solos and failed chair attempts (5 rows for 11 real legs in `wsgate04`) | `M` — a schema question, not a fix |
 | **CA-5** | `isSubagentToolCall` is still a `name === 'task'` string proxy | `M`, and **reduced** by v4.4.0: it is now only the fallback when the real subtree walk finds nothing |
 | **LC-1** | B53's stall kill is skipped while a tool-settle deferral is active | `S–M` — shipped deliberately; the author wants a second opinion, which needs data from real runs |
-| **LC-5** | A chair fallback leaves no trace in `run.json` (`wsgate02`'s haiku failed twice; only `"chair":"minimax"` was recorded) | `M` — a run-record schema addition |
+| ~~**LC-5**~~ | ~~A chair fallback leaves no trace in `run.json`~~ — ✅ **CLOSED by v4.6.2**: `chairAttempts[]` records every attempt (`{waveId, model, outcome, reason}`), checkpointed after each; `run-chair.js:113` cites LC-5 by name. **Do not re-file.** | — |
 | **RN-1** | `sanitizeName` collisions surface as a banner rather than a refusal | `S` + a product decision that was already argued once |
 | **RN-2** | `renderRunList` blind masking is best-effort — only the open run resolves labels | `M` |
 | **RN-5** | A blind-mode flip closes every open prose panel and repaints twice | `S–M` |
@@ -219,15 +284,6 @@ record ("eleven `Number(env) || default` sites"), not a task — a blanket migra
 six new defects to fix one, and `src/utils/env-num.js`'s docblock records which knobs deliberately
 keep the old form.
 
-## v5.0 — Enterprise-readiness *(the deliberate major jump — a venture unto itself, gated on funding / cofounder)*
-**Benefit:** team/org deployment — but a distinct product + go-to-market motion (SOC2, SLAs, sales, support), not a feature drop. Parked as the 5.0 major per the chair's hard-question #5: a solo dev can't credibly ship or support this alone.
-- Secret-store backends + env-var-only mode (A3); org allowlists/blocklists, per-team cost ceilings, read-only enforcement (A6); RBAC
-- Audit & compliance: reproducibility manifests + replay (B11), seed/temp/version pinning (A7), spend export to SIEM/warehouse (A10), `/health` + metrics + structured logging (A8)
-- Team config `.amicusrc` (A9); spend **governance** (per-team caps/enforcement) — the governance half of A4
-- Learning loops that need scale anyway: reliability-aware seat selection (B4), calibration benchmarks (B5), decision-outcome feedback (B10), adaptive strategy planner (B8), evidence provenance (B6)
-- README + docs update: deployment/admin documentation for the above, in `README.md` and `docs/`
-> These cluster because they share one prerequisite you don't have yet: an org buyer + the org to support. Revisit as a funded track.
-
 ---
 
 ### Design notes — auto-open the Council Workspace
@@ -271,6 +327,57 @@ LC-10) that stretch the definition; a third that pops a GUI window would not be
 patch. Sits naturally beside v4.5's existing **GUI power ergonomics (F10)** line.
 
 ## Backlog (tracked, not scheduled)
+
+### Enterprise-readiness *(unscheduled — gated on funding / cofounder)*
+*Moved here from a numbered `v5.0` heading, 2026-08-05. Content unchanged; only its status. It was
+never a rev — it is a distinct product and go-to-market motion (SOC2, SLAs, sales, support), and per
+the chair's hard-question #5 a solo dev can't credibly ship or support it alone. These items cluster
+because they share one prerequisite that does not exist yet: **an org buyer, and the org to support
+them.** Revisit as a funded track; it earns a version number when that track is real.*
+- Secret-store backends + env-var-only mode (A3); org allowlists/blocklists, per-team cost ceilings, read-only enforcement (A6); RBAC
+- Audit & compliance: reproducibility manifests + replay (B11), seed/temp/version pinning (A7), spend export to SIEM/warehouse (A10), `/health` + metrics + structured logging (A8)
+- Team config `.amicusrc` (A9); spend **governance** (per-team caps/enforcement) — the governance half of A4
+- Learning loops that need scale anyway: reliability-aware seat selection (B4), calibration benchmarks (B5), decision-outcome feedback (B10), adaptive strategy planner (B8), evidence provenance (B6)
+- README + docs update: deployment/admin documentation for the above, in `README.md` and `docs/`
+> ⚠️ **B4 (reliability-aware seat selection) now overlaps live backlog work.** `GOA-1` (auto-bench
+> query-aware seat selection, filed 2026-08-05 in `BACKLOG.md`) blends the street-cred ledger into
+> seat choice — that is B4's core idea arriving as a single-user feature rather than an enterprise
+> learning loop. Reconcile before either is scoped; do not build both.
+
+### Composition / chained waves (F6) *(unscheduled — dropped from v4.7, 2026-08-05)*
+`--input-from <id>` / `--prompt-file -` pipe + per-source digests *(M)*, bringing the `{{input}}`
+template variable and the `critique`/`refine` built-ins.
+
+*Not cancelled — waiting on a use case that asks for it.* The reasoning, recorded so it is not
+re-argued from scratch: **the chaining already happens, performed by the orchestrating agent.** When
+a council needs to critique a previous council's output, Claude reads run A's verdict and composes
+run B's prompt — adapting the handoff, dropping what is irrelevant, reframing what matters. A fixed
+`--input-from` digest is *less* flexible than that for interactive use. The feature's real
+beneficiary is **headless/CI chaining, where no orchestrator is in the loop** — and the one headless
+consumer today (the Council Review GitHub Action) runs a single review per PR, not a chain.
+
+**Revisit when:** a headless or scheduled workflow genuinely needs to chain councils without an
+agent driving it, or the `critique`/`refine` built-ins are wanted on their own — those are a much
+smaller slice than the chaining machinery and could ship independently of F6.
+
+⚠️ **Carries its own hard gate:** KNOWN_VARIABLES single-sourcing (`src/template/render.js:45` keeps
+two hand-maintained copies of the known-variable set) must land **before** `{{input}}` does. See
+`BACKLOG.md` *Next-rev hard gates* — that gate travels with this item, not with v4.7.
+
+### GUI power ergonomics (F10) *(unscheduled — dropped from v4.7, 2026-08-05)*
+Focus-follows-fold hotkey, distinguishable window titles, tiling presets *(S each)*.
+
+Dropped on an owner usage finding, recorded here because it should inform every future GUI decision:
+**the Council Workspace is used as an instrument panel — live status while a council runs, plus
+quantitative stats — and never to read council output.** All three F10 items are reading/working
+ergonomics for a surface that is not used that way; "distinguishable window titles" and "tiling
+presets" both presuppose multi-window reading sessions that do not happen.
+
+**Consequence beyond F10:** GUI work should be judged on *live-status fidelity* and *stat accuracy*
+first. The prose-panel and blind-masking nits (RN-2, RN-5, the `T19-*`/`T20-*` family in
+`BACKLOG.md`) sit on the unused half of the surface and should rank accordingly.
+
+### Other tracked items
 - **`--dry-run` / cost & route preview** across start/fanout/council — E2/C7/F4 *(M)* — "know the cost/route before you commit"; useful, not essential to the near-term line.
 - **F7** — Parallel council panels + super-chair (opt-in `--panels N` high-assurance; niche).
 - **E7** — Prompt dedup cache (exact-dup, opt-in, excludes council/fanout) — minor cost optimization.
@@ -285,6 +392,6 @@ patch. Sits naturally beside v4.5's existing **GUI power ergonomics (F10)** line
 - **Local providers stays near-term** (v4.2) — a broad cost/privacy benefit, not enterprise.
 - **Observability arc split:** v4.3 = the data layer + terminal surface + resilience + spend (ships first); **v4.4 = the Electron Council Workspace (B9)** as a GUI on that data.
 - **`--dry-run` cost preview → backlog** (was in the observability rev).
-- **Enterprise/governance/audit/compliance/learning-loops → v5.0**, reframed as the deliberate *major-version venture* gated on funding.
+- **Enterprise/governance/audit/compliance/learning-loops → v5.0**, reframed as the deliberate *major-version venture* gated on funding. **Superseded 2026-08-05:** moved out of the rev pipeline entirely, into *Backlog (tracked, not scheduled)*. A reserved version number read as a commitment; it isn't one.
 - The **cheap trust fixes** (envelope, injection fencing, fold nonce) pulled into **v4.0** because the engine needs them to be trustworthy in automation.
 - **Docs are part of the rev (2026-07-20):** every rev from v4.1 onward closes with a **README + docs update** line item, so each release ships its own documentation rather than deferring it.

package/docs/configuration.md

@@ -238,7 +238,7 @@ Everything lives under `~/.config/amicus/` (`getConfigDir()` in `src/utils/confi
 | `.env` | `amicus setup` / `amicus key` | API keys (`OPENROUTER_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`). `0600` permissions. |
 | `model-catalog.json` | `refreshCatalog()` (`src/utils/model-catalog.js`) | The cached provider model list, schema-versioned, with a **24-hour TTL**. Also carries refresh-outcome fields — `lastRefreshAttempt` and `lastRefreshError` — stamped on a *failed* refresh without touching the last-good `models`/`fetchedAt` (a bad fetch never clobbers a good cache). Human-readable JSON; safe to delete, it rebuilds on next use. |
 | `sessions-index.json` | `session-index.js` (`recordSession`, written at session start) | A **global** map of `taskId → project path`, consulted only when a per-project session lookup misses (e.g. an MCP server whose cwd differs from where the session was created). Navigation aid only, never authoritative — a corrupt index degrades to "no entry," never a crash. |
-| `council-ledger.jsonl` | `src/council/ledger.js` (`appendRun`), on every `council tally` | One row per council model per run — findings raised, severity breakdown, street-cred, conformance. Read back by `amicus council stats`. |
+| `council-ledger.jsonl` | `src/council/ledger.js` (`appendRun`), on every `council tally` | One row per council model per run — findings raised, severity breakdown, street-cred, conformance. At `LEDGER_SCHEMA_VERSION` **2** (v4.7 GOA-7), rows may also carry `resolvedModel` (the executable id that served); legacy-read, no migration — a row without one (all pre-v2 history, plus leg-less rows) aggregates under its alias, and a group is marked `legacy` only when every row in it lacks `resolvedModel`. Read back by `amicus council stats`. |
 | `spend-ledger.jsonl` | `src/utils/spend-ledger.js` (`appendSpend`), new in Phase 16 | One row per completed run/leg — tokens + resolved cost. Read back by `amicus spend` for the cross-run rollup. Append is best-effort and can never fail the run it's recording; safe to delete (starts fresh, loses history only). |
 | `packs/<name>.json` (v4.5) | `amicus pack save` (`src/pack/pack-store.js`) | One JSON file per saved policy pack — bench/model, chair/critic/lenses, options, and a briefing-template *reference*. Peer directory of `templates/` below. Safe to inspect, hand-edit, or delete individually; see [Policy packs](./usage.md#policy-packs). |
 | `templates/<name>.md` (v4.5) | You, by hand (your editor is the manager) | User-authored briefing templates; a file here shadows a built-in of the same name. Amicus itself never writes into this directory — there is no `template save`/`rm`. See [Briefing templates](./usage.md#briefing-templates). |
@@ -287,8 +287,20 @@ Per-session directory contents:
 **Fanout waves.** A wave (`amicus fanout`) gets its own session dir at `<waveId>` (same
 `amicus_sessions/` root); each leg is a full sibling session dir named `<waveId>-1` through
 `<waveId>-N` (`deriveLegIds()` in `src/sidecar/fanout.js`). The wave-heartbeat display reads each
-leg's `progress.json`/`conversation.jsonl` directly — nothing wave-specific is stored beyond the
-per-leg session dirs themselves plus the wave's own `metadata.json` (type `wave`, `legs: [...]`).
+leg's `progress.json`/`conversation.jsonl` directly. The wave dir itself holds:
+
+```
+<waveId>/
+  metadata.json   # type "wave", legs: [...], plus a 200-char rendered briefing excerpt
+  wave.json       # written on completion
+  briefing.md     # the RENDERED prompt — the corpus `amicus list --search` matches against.
+                  # Written by mcp-server.js BEFORE the child spawns (so an aborted wave
+                  # stays searchable), and again by fanout.js:145 once the child runs
+```
+
+One more file appears only for an `amicus_fanout` wave whose prompt came from a **template**: a
+sibling `briefing-input.md` holding the raw pre-render prompt handed to the spawned child, so the
+child's own re-render stays byte-identical and `promptMeta.template` provenance survives.
 
 ### Log location + LOG_LEVEL
 
@@ -383,6 +395,42 @@ a hard-coded built-in (`DEFAULTS` in `src/cli.js`) — so for those the chain is
 pack > built-in** today. See [Policy packs](./usage.md#policy-packs) for the full per-kind field
 reference.
 
+### Cost gate
+
+Two independent pre-flight guards run before a paid model call, both set via top-level
+`config.json` keys that are **hand-edited only** — no wizard or CLI command writes them
+(`src/sidecar/budget.js`):
+
+- **`maxCostPerMtok`** — hard per-$/Mtok refusal threshold. Refuses any leg whose catalog
+  price-per-Mtok exceeds the cap. Defaults to **60**; a non-positive value falls back to that
+  default.
+- **`maxCost`** — soft ceiling on the estimated total $ for the call. Absent, zero or negative all
+  mean no ceiling.
+
+> ⚠️ **`0` means the opposite thing on each key.** `maxCostPerMtok: 0` falls back to the default 60,
+> so that guard stays **on**; `maxCost: 0` disables the ceiling entirely. Neither key is turned off
+> by setting it to zero in the way you might expect — use `--no-cost-gate` (CLI) or
+> `noCostGate` (`amicus_council_run`) to actually disable them.
+
+```jsonc
+{
+  "maxCostPerMtok": 60,
+  "maxCost": 5
+}
+```
+
+On the CLI, `--max-cost <$>` overrides `maxCost` for that call, and `--no-cost-gate` disables both
+guards (e.g. for an intentional o3 run).
+
+Over MCP the per-call override depends on the tool. `amicus_council_run` takes its own `maxCost`
+and `noCostGate` params, which forward to the spawned child exactly as the CLI flags do.
+**`amicus_start` takes neither.** On that path `maxCostPerMtok` is config-only and nothing can turn
+the gate off at all; the soft ceiling is the **effective** `maxCost` — the pack's if the run used a
+pack that set one, otherwise the config's (`mcp-server.js:454`). Only one of those two values is in
+effect, so raising the other one changes nothing. See
+[Troubleshooting: MCP run fails with "budget gate refused the
+run"](./troubleshooting.md#mcp-run-fails-with-budget-gate-refused-the-run).
+
 ### Uninstall instructions
 
 `npm uninstall -g amicus` removes the package and its bin shims. It does **not** clean up everything
@@ -412,6 +460,6 @@ aliases, and council presets carry over untouched.
 | `eslint` ^8.0.0 | Code linting |
 | `lint-staged` ^16.3.2 | Run linters on staged files |
 
-`opencode-ai` (>=1.0.0) is the bundled LLM conversation engine — it is installed automatically as a postinstall step and does not need a separate `npm install`.
+The bundled **`opencode-ai`** engine (pinned to `1.18.15`, matched by `@opencode-ai/sdk`) installs automatically as a normal dependency — you don't install it separately. Its own postinstall lays down the per-platform binaries.
 
 > **Legacy names.** Pre-rebrand `SIDECAR_*` environment variables were removed entirely in v2.0.0 — they are no longer read, with no warning. Rename to the `AMICUS_*` equivalents documented above. See [docs/SHIMS.md](./SHIMS.md) for the full removal record and rename table.

package/docs/council.md

@@ -85,9 +85,15 @@ Three things to hold onto:
    changed for them.** The skill's opt-in elements (critic seat, expert lenses, debate mode, chair
    verdict scale — see [SKILL.md](../skills/second-opinion/SKILL.md) and
    [SEAT-BRIEFS.md](../skills/second-opinion/SEAT-BRIEFS.md)) ride on existing engine surfaces:
-   seat roles travel as free-form `runStats[].role` labels (`"critic"`, `"lens:<slug>"`), debate
-   mode runs the Stage-2 tally with `--no-ledger` (provisional) and re-tallies after the rebuttal
-   round (that second, post-rebuttal tally is the ledger-recorded one), and lens runs always pass
+   seat roles travel as free-form `runStats[].role` labels in the tally/verdict artifact
+   (`"critic"`, `"lens:<slug>"`, or any other skill-authored label) — **but since v4.7 the
+   council-ledger join reads only an allowlist** (`seat`, `critic`, `lens:*`, `chair`, `claude`,
+   `council`, `redteam` — see the `runStats[]` row inventory under
+   [`amicus council tally`](#amicus-council-tally)), so a custom/free-form label outside that set
+   still renders in the tally/report artifact but no longer contributes its
+   role/wasChair/conformance to `amicus council stats` reliability numbers. Debate mode runs the
+   Stage-2 tally with `--no-ledger` (provisional) and re-tallies after the rebuttal round (that
+   second, post-rebuttal tally is the ledger-recorded one), and lens runs always pass
    `--no-ledger` so non-comparable reviews never feed `stats`.
 
 ---
@@ -322,8 +328,10 @@ launch:
   discovered from the sessions-dir pointer files (`council-<runId>.json`); each row shows status,
   the chair's `overallVerdict` chip once one exists, and cost.
 - **Run detail** (`--ui <runId>`) — header + status/verdict chips, a stage rail, a live **Seats**
-  table (model, role, status, stage, messages, tokens, cost, last activity, a stall flag), the
-  Stage-1 reviews, the **verbatim** anonymized Stage-2 packet (`bundle-stage2.md`, shown as-is —
+  table (model, role, status, stage, messages, tokens, cost, last activity, and a trailing flag
+  cell — `⏳ stalled` while live, or on a finished run `↻ retried once` marking a reviewing seat
+  whose once-only Stage-1 retry didn't save it), the Stage-1 reviews, the **verbatim** anonymized
+  Stage-2 packet (`bundle-stage2.md`, shown as-is —
   never re-rendered), judge prose, the **adjudication matrix** (finding × judge, tier-colored
   rows, `a/d/n` basis counts, a `thin` badge when `a+d<=1`, an override badge when a Stage-4
   decision changed a finding's tier, capped at 500 rows with a "showing N of M" note past that),
@@ -532,8 +540,8 @@ model to the reliability ledger. Thin CLI wrapper over `tally()` (`src/council/t
 ### Tally-input schema
 
 Claude assembles this file at the end of Stage 2 (the full assembly recipe is in
-[SKILL.md](../skills/second-opinion/SKILL.md#stage-2--cross-review), under "Stage-2 → tally
-assembly recipe"). It needs **all five top-level keys** — `tally()` throws
+[SKILL.md](../skills/second-opinion/SKILL.md#the-engine-run--stages-13-plus-the-stage-5-artifacts),
+under "Stage-2 → tally assembly recipe"). It needs **all five top-level keys** — `tally()` throws
 `Cannot read properties of undefined (reading 'map')` if `meta` or `findings` is missing:
 
 | Field | Type | Meaning |
@@ -546,7 +554,44 @@ assembly recipe"). It needs **all five top-level keys** — `tally()` throws
 | `findings[]` | array | One entry per finding across all reviews: `{id, raiser, severity}` (`claim` may ride along but isn't required by the tally engine). `id` is the run-global label (e.g. `A1`, `B2`) assigned during Stage-2 assembly, not the reviewer's local integer id. |
 | `adjudications[]` | array | One entry per (judge × finding): `{findingId, judge, verdict}`, `verdict ∈ {agree, dispute, neutral}`. Include every judge's verdict on every finding, **including the raiser's own adjudication of its own finding** — the engine excludes it automatically when scoring (don't pre-filter it). |
 | `rankings[]` | array | One entry per judge: `{judge, order}`. `order` is that judge's `FINAL RANKING:` block translated to model ids, e.g. `["gpt", "deepseek"]` (ties may use a nested array, e.g. `[["gpt","deepseek"], "mistral"]`). |
-| `runStats[]` | array | One entry per model call: `{model, role, wasChair, conformance, status, durationMs, usage}`. May be `[]`. Any leg with no run document gets `durationMs: null, usage: null` — never invent a value. |
+| `runStats[]` | array | One row per paid launch (v4.7 spec §5 D1/D2 — no longer capped at one row per model; see the role roster below): `{model, role, wasChair, conformance, status, durationMs, usage, waveId?, resolvedModel?}`. May be `[]`. Any leg with no run document gets `durationMs: null, usage: null` — never invent a value. `waveId` is emit-only-when-set. `resolvedModel?` (v4.7) — the executable id that actually served the row's leg, emit-only-when-set; leg-less rows (the give-up chair row, dead seats with no leg, the claude row) never carry it. `model` stays the council alias. |
+
+**`runStats[].role` roster (v4.7 row-per-launch).** Every leg the run budget counts gets exactly
+one row, so a seat that needed a repair or lost a leg to a retry can now show up more than once.
+
+*Primary rows* — exactly one per requested reviewing seat, unchanged in shape from pre-v4.7:
+`seat`, `critic`, `lens:<slug>`, `judge`, `chair` (`wasChair: true`), synthetic `claude`, and the
+legacy default `council` (pre-#83 rows, or hand-assembled tally input that never set a role). A
+dead seat/critic/lens with no recovery, and a chair walk that gives up entirely, get an honest
+primary **error** row too — the #83 judge treatment extended to every seat (`usage: null` on the
+give-up chair; the dead leg's own usage on a dead seat/critic/lens).
+
+*Non-primary rows* — `wasChair` always `false`: `chair-attempt` (a failed ch1–ch3 chair launch),
+`repair` (a Stage-1 `-p`, Stage-2 `-q`, chair-ch4, or debate-born `-d<N>r`/`-rv-…r` solo — a
+failed defense or re-vote repair), and `superseded` (a first leg a later attempt replaced — an
+SL-2 retry or a debate repair) — all three new in v4.7's row-per-launch change — plus `rebuttal`
+and `revote` (a `--debate` round's defense/re-vote legs; v4.1, pre-dating row-per-launch). All
+five still cost money and land in `runStats`, so they raise the run's totals everywhere those are
+summed. In `council report`'s cost table only `judge`/`chair-attempt`/`repair`/`superseded` get a
+suffixed label (`rebuttal`/`revote` render unsuffixed); `council tally` has no per-row cost table
+at all, only an aggregate. And only `chair-attempt`/`repair`/`superseded` are filtered out of the
+Workspace seats panel — `rebuttal`/`revote` rows still render there.
+
+`runStats[].waveId` names the exact wave/leg a row was built from, present **iff a real billed
+leg backs the row** — e.g. the synthetic `claude` row, a give-up chair's error row, and a
+leg-less dead-seat/critic/lens primary error row (the two SL-2 retry note-classes that never
+produced a real leg for the seat at all) carry none. It's the join key the leg–row bijection
+invariant suite (`tests/council/run-cost-bijection.test.js`) uses to prove every budget-counted
+leg lands on exactly one row. `resolvedModel` follows the same emit-only-when-set discipline and
+the same never-invent rule — it is never derived from the alias.
+
+**Ledger-join consequence.** `council stats`'s reliability aggregation (`ledger.js`) only reads
+rows whose role is in the allowlist above (`seat`, `critic`, `lens:*`, `chair`, `claude`,
+`council`, `redteam`) — everything else, including all three new non-primary roles and any
+custom/free-form label a skill or caller invents, is fail-closed excluded and never contributes
+role/wasChair/conformance to reliability stats, even though it still renders in the tally/report
+artifact. Since v4.7 the ledger row copies the joined row's `resolvedModel` and `council stats`
+groups by `resolvedModel || model` — see the stats section below.
 
 ### Tally-record schema (what `tally()` returns / prints)
 
@@ -723,7 +768,10 @@ Since v4.0 (council schema v2), `--json` wraps the rows in the family envelope
 `{ "schemaVersion": 2, "type": "council-stats", "models": [ … ] }` — the per-model row
 shape below is unchanged. (Pre-4.0 emitted the bare array.)
 
-**Output**, one row per model that has ever appeared in `meta.models`:
+**Output**: one row per RESOLVED model (v4.7 — rows that carry `resolvedModel` group by the
+executable id that served; rows without one group by alias and are marked `legacy`). Each row
+also lists `aliases[]` — every alias observed for the group, most recent first; the chair
+fallback promotion launches `aliases[0]`.
 
 | Field | Meaning |
 |---|---|
@@ -733,6 +781,8 @@ shape below is unchanged. (Pre-4.0 emitted the bare array.)
 | `lifetimeConfirmRate` | Mean, across runs, of `(findings this model raised that landed Confirmed) / (findings this model raised)`. `null` when `judged` was false for every run or the model raised nothing. |
 | `lifetimeFactErrorRate` | Same shape, but for the `Disputed` tier — a proxy for how often the bench caught this model asserting something wrong. |
 | `conformance` | Tally of `{clean, repaired, unstructured}` counts — how often this model's Stage-1 findings JSON needed a repair re-prompt. |
+| `aliases` | Every alias (row-level `model` value) observed for this group, most recently observed first (v4.7). `aliases[0]` is the launch-preferred name. |
+| `legacy` | `true` when every row in the group lacks `resolvedModel` — alias-keyed history from before resolved-id segmentation, or leg-less rows whose resolution is unknowable (v4.7). Omitted (not `false`) when the group has any resolved rows. |
 
 This is the data source the `second-opinion` skill's Stage 0 model recommendations and the
 `MODEL-NOTES.md` quantitative table both read — **never hand-edit reliability numbers there**;
@@ -910,11 +960,14 @@ _Legend: ✓ agree · ✗ dispute · – neutral · `*` raiser's own vote_
 ```bash
 $ amicus council stats
 model            runs  avg-cred  confirm  fact-err  notes
-deepseek            1  2.00     1.00    0.00   low-N
-gpt                 1  1.00     0.00    0.00   low-N
+deepseek            1  2.00     1.00    0.00   low-N   legacy
+gpt                 1  1.00     0.00    0.00   low-N   legacy
 ```
 
-(`low-N` because each model has only 1 recorded run — `runs < 3`.)
+(`low-N` because each model has only 1 recorded run — `runs < 3`. `legacy` because this
+hand-assembled `tally-input.json` never sets `runStats[].resolvedModel` — v4.7 groups by
+alias and marks the group `legacy` whenever none of its rows carry a resolved id; see
+[`amicus council stats`](#amicus-council-stats) above.)
 
 **7. Presets**, for reference (independent of the run above):
 

package/docs/doc-system.md

@@ -56,16 +56,18 @@ When running `--check` mode, the script validates every markdown link in CLAUDE.
 
 ## Plans Index
 
-`docs/plans/index.md` is auto-generated by the same script. It lists all `.md` files in:
-- `docs/plans/` (active plans)
-- `docs/archive/plans/` (archived plans)
-
-Each entry shows the filename, first heading, and date extracted from the filename.
+No plans index is generated **today**. `buildPlansIndex()` in `scripts/generate-docs.js` scans
+`docs/plans/` and `docs/archive/plans/`, but neither directory exists in this repo, and
+`runWriteMode()` writes `docs/plans/index.md` only when `docs/plans/` already exists — so the write
+never fires. Note that guard is a runtime `fs.existsSync` check, not a disabled feature: creating
+`docs/plans/` would silently reactivate it, emitting a bare list of `- [name](path)` links without
+the per-plan first heading or date the old text here promised. Plans actually live in
+`docs/superpowers/plans/`, uncataloged.
 
 ## Commands
 
 ```bash
-node scripts/generate-docs.js          # Regenerate all auto sections + plans index
+node scripts/generate-docs.js          # Regenerate all auto sections
 node scripts/generate-docs.js --check  # Verify everything is current (CI mode)
 npm run generate-docs                  # Alias for write mode
 npm run generate-docs:check            # Alias for check mode
@@ -89,4 +91,3 @@ Hook order:
 | "Marker not found" error | Ensure `<!-- AUTO:name -->` and `<!-- /AUTO:name -->` exist in CLAUDE.md |
 | Stale markers after code change | Run `node scripts/generate-docs.js` manually |
 | Cross-link validation failure | Fix the broken link in CLAUDE.md or create the missing file |
-| Plans index missing | Run the script; it creates `docs/plans/index.md` |

package/docs/schemas.md

@@ -49,7 +49,16 @@ This is the one non-additive shape change in the envelope unification; migrate `
 
 ## Documented exclusions
 
-- **The two JSONL ledgers** (`council-ledger.jsonl`, `spend-ledger.jsonl`): internal append-only storage, each stays at its own v1 row format (`SPEND_LEDGER_SCHEMA_VERSION` is 1, unrelated to and unbumped by the result/council envelope versions above) — not an emitted/published doc. `spend.schema.json` (the `amicus spend --json` output) is the published, versioned doc built *from* `spend-ledger.jsonl` rows — the ledger row shape itself is not published.
+- **The two JSONL ledgers** (`council-ledger.jsonl`, `spend-ledger.jsonl`): internal
+  append-only storage, not emitted/published docs. `spend-ledger.jsonl` stays at its own v1
+  row format (`SPEND_LEDGER_SCHEMA_VERSION` is 1, unrelated to the envelope versions above).
+  `council-ledger.jsonl` is at `LEDGER_SCHEMA_VERSION` **2** (v4.7 GOA-7): v2 rows may carry
+  `resolvedModel` — the executable id that actually served. **Legacy-read, no migration:**
+  readers never inspect a row's schemaVersion; a row without `resolvedModel` (all pre-v2
+  history, plus leg-less rows whose resolution is unknowable) simply aggregates under its
+  alias — a group is marked `legacy` in `council stats` output only when EVERY row in it
+  lacks `resolvedModel`. `spend.schema.json` (above) is still the published doc built from
+  `spend-ledger.jsonl` rows — neither ledger's row shape itself is published.
 - **`amicus_list`** (MCP): returns a bare JSON array of session rows; a wrap would be a second breaking change and is deliberately not taken.
 - **`setup` / `update` / `key`**: interactive-only commands with no `--json` mode.
 - **MCP acks and live-status snapshots** (start/resume/continue/abort acks, `amicus_status`/`amicus_wait` bodies): carry the envelope keys with subject-family types (`run`/`wave`/`abort`) but are point-in-time snapshots, not the durable result docs the published schemas describe.

package/docs/testing.md

@@ -523,7 +523,7 @@ Complete mapping of test files to their targets and focus areas.
 | `evals/tests/result_writer.test.js` | Result output | Summary formatting, file writing |
 | `scripts/check-secrets.test.js` | Secret detection | Pattern matching, allowlist, multi-secret |
 | `scripts/check-file-sizes.test.js` | File size limits | Line counting, batch checking |
-| `scripts/validate-docs.test.js` | Doc drift detection | Section extraction, drift comparison, staged file check |
+| `scripts/validate-docs.test.js` | Doc drift detection | Staged file check |
 | `helpers/cdp-client.test.js` | CDP helper | Mock HTTP+WebSocket CDP server, factory methods |
 | `electron-headless-mode.test.js` | Electron headless | Source-level verify `AMICUS_HEADLESS_TEST` guard |
 | `cli-headless-e2e.integration.test.js` | CLI E2E (real LLM) | `start --no-ui`, `list`, `read`, `read --metadata` |

package/docs/troubleshooting.md

@@ -5,7 +5,33 @@
 
 ## First: run `amicus doctor`
 
-Before working through any symptom below, run `amicus doctor` (plugin-only installs: `npx -y amicus@latest doctor`). It checks, in order: Node version, config directory, API keys, default model, catalog freshness, alias staleness and drift, the ANTHROPIC_BASE_URL form, the OpenCode binary, the OpenCode engine's MCP launch path, Electron, installed skills, MCP registration, the legacy sidecar MCP entry, session index tmp files, OpenRouter credit, local providers, and the project root — and prints a targeted fix hint for every failing check. `amicus doctor --fix` self-heals what it can (e.g. re-installs a broken Electron in place); `--json` gives machine-readable output.
+Before working through any symptom below, run `amicus doctor` (plugin-only installs: `npx -y amicus@latest doctor`). It checks, in order: Node version, config directory, API keys, default model, catalog freshness, alias staleness and drift, the ANTHROPIC_BASE_URL form, the OpenCode binary, the OpenCode engine's MCP launch path, Electron, installed skills, MCP registration, the legacy sidecar MCP entry, session index and session metadata tmp files, OpenRouter credit, local providers, and the project root — and prints a targeted fix hint for every failing check. `amicus doctor --fix` self-heals what it can (e.g. re-installs a broken Electron in place); `--json` gives machine-readable output.
+
+---
+
+## MCP run fails with "budget gate refused the run"
+
+**Symptom:** An `amicus_start` call over MCP returns an error with `message: "Error: budget gate
+refused the run"` (`ERROR_CODES.BUDGET_EXCEEDED`).
+
+**Cause:** v4.7 made the `amicus_start` shared-server budget gate unconditional
+(`src/mcp-server.js:442-467`) — it used to run only when a pack forwarded `maxCost`, so a no-pack
+MCP start that worked on 4.6.x can now refuse. The gate has two independent guards; when both fire,
+raising only one will not clear the run.
+
+**Fix:** the error text names which guard fired — raise that one, or choose a cheaper model. **If
+both fired, you must raise both**; clearing one leaves the other refusing. See
+[Cost gate](./configuration.md#cost-gate).
+
+- **`maxCostPerMtok`** (the per-$/Mtok guard) lives only in `config.json`. No pack and no MCP param
+  can override it.
+- **`maxCost`** (the total-$ ceiling) is whichever value is *in effect*: **the pack's if this run
+  used a pack that set one, otherwise the config's.** Editing the loser of that pair changes
+  nothing.
+
+`amicus_start` has **no per-call override** — it takes neither a `maxCost` nor a `noCostGate` param,
+and nothing can turn the gate off on that path. (`amicus_council_run` is different: it does take
+both, and they forward to its child exactly like the CLI flags.)
 
 ---
 
@@ -207,13 +233,15 @@ For full headless configuration, see [docs/configuration.md](./configuration.md)
 
 ## Headless Leg Fails with `NO_OUTPUT_BACKSTOP`
 
-**Symptom:** A headless leg (`amicus start --no-ui`, or one leg of a `fanout`/council run) fails with an error starting `NO_OUTPUT_BACKSTOP: model produced no output, reasoning, or tool calls in Ns`.
+**Symptom:** A headless leg (`amicus start --no-ui`, or one leg of a `fanout`/council run) fails with an error starting `NO_OUTPUT_BACKSTOP: no output, reasoning, or tool calls in Ns — the AMICUS_NO_OUTPUT_BACKSTOP_MS window (0 disables)`. You may instead see `...in Ns — a caller-set window overriding the AMICUS_NO_OUTPUT_BACKSTOP_MS default` — this covers two different cases with the same wording: a Stage-1 retry (its window is the resolved `AMICUS_NO_OUTPUT_BACKSTOP_MS` value **doubled**, so a 120 s default reads `240s` on the retry) and the `amicus models --check --live` probe (a fixed, non-tunable `30s` — see below). Both are "caller-set" in the sense that the specific window wasn't read live from the env var at that call, but only the retry case is actually governed by it.
+
+**Cause:** The mechanism only knows that the deadline passed with no substantive activity — no output, reasoning, or tool calls — for the backstop window (120 s by default for an ordinary leg). It does **not** know *why*. Do not read this as "the endpoint is dead" or "the model isn't being served" — the message deliberately stops short of that claim, because at one of its two firing sites the backstop can win the race before the prompt send even resolves, so acceptance itself was never observed. Treat `NO_OUTPUT_BACKSTOP` as "silence past the deadline," not a diagnosis.
 
-**Cause:** The model endpoint accepted the request but produced nothing — no output, reasoning, or tool calls — for the entire backstop window (120 s by default). This is the "accepted but not serving" class: usually a dead or misconfigured endpoint, or a catalog-listed model that's no longer actually being served upstream.
+**Lesson from #133:** an earlier version of this message *did* guess a cause ("likely a listed-but-not-serving model or a dead endpoint"), and that guess sent 30 minutes of debugging at model ids and API keys on a real incident. The actual cause was an OpenCode engine version skew between the npx-cached copy and the global install — sitting the whole time in `~/.local/share/opencode/log/opencode.log`. **Before chasing model/endpoint theories, check that log for the session's real error.**
 
-**Confirm:** `amicus models --check` — audits your configured aliases against the live catalog and flags drift/staleness. A model that still resolves locally but has quietly been retired upstream is exactly this failure mode, but a static audit only compares against the catalog's *listing* — it can't tell you whether a still-listed model actually answers. For that, run `amicus models --check --live` on demand: it sends one tiny real request to every stored alias and reports `SERVED` / `SILENT` / `ERROR` per alias, where `SILENT` (`accepted-but-silent`) is this exact `NO_OUTPUT_BACKSTOP` failure, caught deliberately instead of by accident. It spends real money (one tiny leg per stored alias) — see [docs/usage.md § `amicus models`](./usage.md#amicus-models--the-model-catalog) for cost, scope, and exit-code details.
+**Confirm:** `amicus models --check` — audits your configured aliases against the live catalog and flags drift/staleness. A model that still resolves locally but has quietly been retired upstream is one possible explanation, but a static audit only compares against the catalog's *listing* — it can't tell you whether a still-listed model actually answers. For that, run `amicus models --check --live` on demand: it sends one tiny real request to every stored alias and reports `SERVED` / `SILENT` / `ERROR` per alias, where `SILENT` (`accepted-but-silent`) is this exact `NO_OUTPUT_BACKSTOP` failure, caught deliberately instead of by accident. It spends real money (one tiny leg per stored alias) — see [docs/usage.md § `amicus models`](./usage.md#amicus-models--the-model-catalog) for cost, scope, and exit-code details.
 
-**Fix:** Check the alias's target (`amicus models --search <term>` to find the current id, then re-point the alias) — this is the common case. Raise `AMICUS_NO_OUTPUT_BACKSTOP_MS` only if a model legitimately needs more than 120 s to produce its first token; see [docs/configuration.md § Headless Poller Tuning](./configuration.md#headless-poller-tuning).
+**Fix:** Check the `~/.local/share/opencode/log/opencode.log` for the session's real error first (see #133 above). Then check the alias's target (`amicus models --search <term>` to find the current id, then re-point the alias) — a stale alias is a common case, but not the only one. If the failing leg was a Stage-1 retry (the window read `240s`, or generally double your configured/default value), `AMICUS_NO_OUTPUT_BACKSTOP_MS` **is** the lever — raising it raises both the first attempt's window and the retry's doubled one, unless your `--timeout` is low enough that the doubled window is clamped to the leg timeout. On an ordinary (non-retry) leg, raise it only if a model legitimately needs more than 120 s to produce its first token. The live probe's fixed 30 s window is the one case the env var genuinely cannot touch. See [docs/configuration.md § Headless Poller Tuning](./configuration.md#headless-poller-tuning).
 
 ---