amicus 4.8.1 → 4.9.1

package/docs/council.md

@@ -21,6 +21,7 @@ orchestration recipe. This page is the reference for the artifacts that recipe p
 
 - [The pipeline, end to end](#the-pipeline-end-to-end)
 - [`amicus council run`](#amicus-council-run)
+  - [Task mode (`--intent task`)](#task-mode---intent-task)
   - [Debate mode](#debate-mode)
 - [Council Workspace (GUI)](#council-workspace-gui)
   - [Auto-open on `amicus_council_run` (v4.5)](#auto-open-on-amicus_council_run-v45)
@@ -112,6 +113,7 @@ amicus council run --prompt-file <briefing.md>
     [--gateway auto|direct|openrouter] [--no-validate-model]
     [--template <name|path>] [--artifact <file>] [--var k=v]  # v4.5, see docs/usage.md#briefing-templates
     [--pack <name|path>]                                       # v4.5, see docs/usage.md#policy-packs
+    [--intent review|task]                                     # v4.9, see Task mode below
 ```
 
 **The headless engine (v4.0).** Everything the `second-opinion` skill orchestrates by hand in
@@ -258,7 +260,10 @@ cross-process lock.
 `verdict.json` here is the **undecided** verdict — same schema as [`amicus council
 verdict`](#amicus-council-verdict)'s output (council family v2) plus **`overallVerdict`**
 (`"Ship it" | "Fix these first" | "Fundamental rethink" | null`), parsed from the chair's final
-`VERDICT:` line. Example excerpt:
+`VERDICT:` line — or, on a task run (`--intent task`, v4.9), `"Converged" | "Split" |
+"Insufficient" | null` parsed from its final `ANSWER:` line instead (both scales, and why they
+are disjoint, are in the `overallVerdict` key note under [`amicus council
+verdict`](#amicus-council-verdict)). Example excerpt:
 
 ```json
 {
@@ -282,6 +287,82 @@ Consumers gate on **tiers + the chair verdict line** (`overallVerdict`), per the
 report-only Stage-4 policy. Headless runs pin `meta.claudeInCouncil: false`,
 `meta.runType: "headless"`, and the chair is excluded from the street-cred universe.
 
+### Task mode (`--intent task`)
+
+By default a council **reviews** the material it is given. `--intent task` (over MCP: the `intent`
+parameter on `amicus_council_run`, spelled `'task'`) points the same pipeline at **open-ended work**
+instead: the bench *produces* what the briefing asks for, and the chair synthesizes an **answer**
+rather than a verdict about a review that never happened.
+
+`review` is the default, and it is never stored: `--intent review` is accepted and normalized away
+at every door, so nothing writes `intent: "review"` onto `run.json`, `tally.json` or `verdict.json`.
+Only `"task"` is ever recorded — the same emit-when-set idiom as `--tag`. Any other value is a
+pre-flight `BAD_ARGS` failure before any spend.
+
+**What changes, stage by stage:**
+
+| Stage | Review intent (default) | Task intent |
+|---|---|---|
+| Stage 1 | *"You are one reviewer… Review the material"* — each seat critiques the briefing | *"you are not reviewing the briefing, you are executing it"* — each seat produces the deliverable, then declares the load-bearing claims it rests on |
+| Stage 2 rank | Order the reviews by how **accurate** each critique was | Order the responses from the one that **best does the work the briefing asked for** to the one that does it least well |
+| Stage 2 adjudicate | For every finding id, `agree`/`dispute`/`neutral` on the **critique** | For every claim id, `agree`/`dispute`/`neutral` on whether **the claim holds** |
+| Chair | `VERDICT: Ship it \| Fix these first \| Fundamental rethink` | `ANSWER: Converged \| Split \| Insufficient` |
+| Reliability ledger | One row per (run × model) appended | **Nothing appended** |
+
+**The two scales are disjoint on purpose.** They share no value and no keyword, which is what lets
+each parser stay blind to the other's line: a task run can never report `"Ship it"`, and a review run
+can never report `"Converged"`. The run's intent is what selects the parser — including on a Stage-5
+`amicus council verdict` rebuild long after the run is over, where a carried `overallVerdict` from
+the *wrong* scale is refused and the chair's prose is re-parsed instead. Full field semantics are in
+the `overallVerdict` and `intent` key notes under
+[`amicus council verdict`](#amicus-council-verdict).
+
+**What does *not* change.** The Stage-1 output contract is identical — the same trailing fenced JSON
+skeleton, the same `blocker | major | minor | nit` severity enum, the same required-non-empty
+`location`, validated by the same validator and repaired by the same bounded repair loop. Only the
+frame and the field *glosses* fork. In task mode `location` is the grounding discipline: it names
+what the claim rests on — a source, a computation, or the literal word `assumption`. An empty
+`findings[]` under a real `overall` is a valid task response, exactly as it is a valid review, and
+the bench is told so rather than left to invent claims to fill the array.
+
+Two things a task bundle carries that a review bundle never does: the Stage-2 judge packet ends with
+a `--- THE BRIEFING (what every response was asked to do) ---` section — judges cannot rank *how well
+the work was done* without the ask — and that section is fenced as reference material, because it is
+the first time briefing text reaches a judge in band.
+
+**Task runs write no reliability rows, and say so.** Two gates enforce it (the engine's own append
+and `amicus council tally`'s), and `council tally` refuses a `meta.intent` that is neither spelling
+rather than letting a near-miss slide into the ledger. Where the skip is **load-bearing** it is
+**announced, and the announcement does not degrade the run** — a `Note:` record on the
+`ledger-skipped` channel with `kind: "info"`, which the degrade sink cannot use to flip a run's
+`degraded` state. ⚠️ It is emitted at one site, not on every task run: the chair-fallback promotion
+arm, reached only after the chair's own attempts have all failed and the run still has budget,
+because that arm is the one step that draws on ledger history a task run never fed. A task run whose
+chair answers has no `ledger-skipped` note, and needs none. `info` records are announcements, not losses: the report gives
+them their own **Notes:** list and keeps them out of `## What was lost`. Relatedly,
+[`amicus council stats`](#amicus-council-stats) on an empty ledger now names where rows come from
+instead of implying that no council ever ran.
+
+**Read the tiers correctly.** A task run's report carries the line *"Tiers report peer concurrence,
+never verification."* directly under the tier counts, and the chair's own packet carries the same
+caveat beside the adjudications it is weighing. Peer agreement on a generative bench is correlation
+between models trained on overlapping priors — a tier says *how many peers concurred*, never *that
+the claim was checked*.
+
+**Review runs are byte-identical.** Not "unchanged as far as we know": the review path composes
+through the same dispatcher, and the shared packet — section headers, `Review by <model>` labels,
+empty-section wordings — is used verbatim in both intents. One vocabulary, two instructions.
+
+**Limitations, as of v4.9:**
+
+- **One intent per run.** There is no mixed bench; the whole run is a task run or a review run.
+- **Intent is not pack-settable.** A [policy pack](./usage.md#policy-packs) cannot carry it — pass
+  the flag (or the MCP parameter) explicitly.
+- **`--claude-review` is refused with `--intent task`.** Entering a file as review N+1 is review
+  machinery and has no task-mode meaning.
+- **Task runs build no reliability history**, so they never contribute to — and never benefit from —
+  `amicus council stats`, including the ledger-driven chair-fallback promotion.
+
 ### Debate mode
 
 `--debate` adds a **Stage-2.5 rebuttal round** between cross-review and the final tally
@@ -757,7 +838,8 @@ named here. That is why the v4.8 keys below each needed their own line.
 **Key notes:**
 - `schemaVersion` — verdict-document schema version (currently `2`).
 - `type` — document-type discriminator; always `"council-verdict"` (council family v2 envelope).
-- `overallVerdict` — the chair's verdict-scale outcome: one of `"Ship it"`, `"Fix these first"`, `"Fundamental rethink"`, or `null` when no chair verdict was produced (populated by the headless engine during Stage 3; `null` for a plain `council verdict` merge without engine integration).
+- `overallVerdict` — the chair's terminal-line outcome, on **one of two disjoint scales, chosen by the run's intent**. A review run (no `intent` key) carries a verdict-scale value — `"Ship it"`, `"Fix these first"`, `"Fundamental rethink"` — parsed from the chair's `VERDICT:` line. A **task run** (`intent: "task"`, v4.9) carries an answer-scale value — `"Converged"`, `"Split"`, `"Insufficient"` — parsed from the chair's `ANSWER:` line. The two scales share no value and no keyword, which is what lets each parser be blind to the other's line; a task run therefore never reports `"Ship it"`, and a review run never reports `"Converged"`. `null` on either scale when no chair terminal line was produced (populated by the headless engine during Stage 3; `null` for a plain `council verdict` merge without engine integration).
+- `intent` — **v4.9**, optional, `"task"` only. Present exactly when the run was launched with `--intent task`; absent means review — the engine never writes `"review"` (emit-when-task, the same idiom as `tag`). It is the key every renderer forks on: the report's concurrence qualifier and header word, the fold's and the Workspace chip's `ANSWER:`/`VERDICT:` label, and the chair's own packet/parser upstream of this document.
 - `seats` — **v4.8**, optional. The tally record's `meta.seats` (same `{id, alias, role, lens, position}` shape), promoted to the top level next to `seatLoss`. Present only when the tally record carried one, i.e. only when the bench repeated an alias. It is what makes the `alias#N` ids on `findings[].raiserSeat`, `adjudications[].seat` and `runStats[].seat` resolvable from the verdict **alone** — before v4.8 the verdict named seats it could not resolve. `council report` reads it to give each seat its own adjudication-matrix column; when it is absent, or is not an array of objects each carrying a string `id`, the **adjudication matrix** falls back to alias space whole and renders exactly as it did before v4.8. ⚠️ **That fallback is the matrix's alone — it is not a whole-document guarantee.** The street-cred table beside it labels each row from `streetCred[].seat` whenever the row carries one, a predicate independent of this key, so a verdict with seated `streetCred[]` rows and no usable `seats` renders seat ids in the street-cred table and aliases in the matrix (measured on an absent `seats`, a non-array `seats`, and an array-of-strings `seats`). In-process both fields come from the same twin bench and travel together; the split is reachable on a hand-assembled or externally-supplied record, which `buildVerdict`'s own docblock names. A verdict written before v4.8 carries no `streetCred[].seat` at all and is unaffected.
 - `findings[].raiserSeat` — **v4.8**, optional. The raising seat's id, carried through from the tally record; absent unless the bench repeated an alias. `findings[].raiser` stays the alias.
 - `findings[].sameModelCorroboration` — **v4.8**, optional, `true` only. Carried through from the tally record; see the tally-record notes above for the stamp's meaning **and for the two directions in which it is wrong** (it misses one model behind two aliases, and it fires falsely on one alias behind two executables).
@@ -802,7 +884,12 @@ wrapper over `buildReport()` (`src/council/report.js`, which builds the neutral
 dispatches to `report-md.js` / `report-html.js` — the two renderers that own the string formats).
 
 **What it renders**, in this order: a header (run type, id, date, chair, council members), a
-verdict-summary tier-count table, the **adjudication matrix** (finding × judge, `✓`/`✗`/`–` with
+tier-count summary table — headed **Verdict summary** on a review run and **Answer summary** on a
+task run, since a task run produces an answer, not a verdict, and on a task run followed by the
+one-line concurrence qualifier (*tiers report peer concurrence, never verification*) — a
+**What was lost** section
+when the run degraded (plus a **Notes** list for informational records, e.g. a task run's
+ledger-skipped announcement), the **adjudication matrix** (finding × judge, `✓`/`✗`/`–` with
 `*` marking the raiser's own vote), the **peers-only street-cred table**, **findings grouped by
 tier** (Disputed first), and a **cost table** (per-model status/duration/cost + wave total,
 sourced from `runStats[].usage`).
@@ -873,17 +960,18 @@ matrix does not carry — `` `†` `` marks a finding corroborated only by anoth
 same model — so from v4.8.0 the two legends are no longer interchangeable. That line, and the `†`
 itself, appear only on a run that actually raised such a finding, which is a twin bench only.
 
-⚠️ **v4.8 — a SECOND report/Workspace divergence, in the street-cred table, filed not fixed.** The
-sentence above is scoped to the **matrix**, and stays true. The street-cred table is a different
-story: both renderers (`report-md.js`, `report-html.js`) label each row `seat || model`, so a twin
-bench reads `gemini#1` / `gemini#2`, while the Workspace's street-cred table still labels from the
-model alias
-and reads `gemini` twice with different numbers under one identical name. **On a bench that repeats
-an alias the two street-cred tables now disagree**; on any bench with no repeated alias they are
-identical, because every seat id there *is* its alias. The report side is the corrected one. The
-Workspace side is not a one-liner — its blind mode resolves the label through `opts.labelOf(...)`,
-which would have to accept a seat id first — and is filed in `BACKLOG.md` for v4.9 with that
-signature change as its gate.
+⚠️ **v4.8 filed a SECOND report/Workspace divergence, in the street-cred table — CLOSED in v4.9.**
+The sentence above is scoped to the **matrix**, and stays true. All three street-cred renderers now
+label each row `seat || model`: `report-md.js` and `report-html.js` (v4.8), and the Workspace's own
+(`electron/workspace-ui/workspace-matrix.js :: renderVerdict`, v4.9). A twin bench reads
+`gemini#1` / `gemini#2` in every one of them, instead of the Workspace reading `gemini` twice with
+different numbers under one identical name; on any bench with no repeated alias all three are
+unchanged, because every seat id there *is* its alias. ⚠️ **Blind mode is the deliberate exception
+and is unchanged**: the Workspace still shows the anonymised label, falls back to the model alias
+when no label resolves, and renders a seat id in neither case — a seat id contains its alias, so
+printing one would defeat blind mode (the same rule the matrix follows two paragraphs above).
+`BACKLOG.md` filed this behind the gate *"`opts.labelOf` must accept a seat id"*, which the fix did
+not need: `labelOf` stays alias-keyed, because the value blind mode has to show was never the seat.
 
 This is the same renderer the `second-opinion` skill calls in Stage 5 to produce `report.html`.
 **`report.md` and this renderer's output are two different files** — `report.md` is Claude-authored

package/docs/troubleshooting.md

@@ -237,11 +237,18 @@ For full headless configuration, see [docs/configuration.md](./configuration.md)
 
 **Cause:** The mechanism only knows that the deadline passed with no substantive activity — no output, reasoning, or tool calls — for the backstop window (300 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.
 
-**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.**
+Two trailing clauses are the exceptions, and neither is the mechanism's inference:
+
+- ` — engine log: <excerpt>` (since v4.9) is the OpenCode engine's own ERROR line for this exact session, quoted verbatim from the engine's log. That clause is the engine speaking. "For this exact session" is strict: the line must name your session in one of the engine's own session fields (`session.id=`, `id=`, …), so a neighbouring session's failure is never quoted at you — and when nothing on disk meets that bar, the clause is simply absent rather than approximate.
+- ` (engine skew: server <a> ≠ installed <b>)` (since v4.9) means the engine serving **this** run reported a different version than the `opencode-ai` sitting in the install that launched it — two facts, both published by the software itself, neither guessed. It names the server this leg actually talked to, as of this leg's most recent session: a skew seen on some other server in the same process, or one that was fixed part-way through, never rides along on a report it does not belong to. This is #133's own shape; see the Lesson below.
+
+The two clauses are independent: either can appear without the other, and the skew clause is **not** conditional on the log read succeeding. With neither, the message is exactly what it was before v4.9. Everything before them is still only "silence past the deadline".
+
+**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 in the engine's own log the whole time, at the exact timestamp of every dead session. **Both halves are now surfaced for you** (v4.9): the log line becomes the ` — engine log:` clause, and the skew itself is detected at session-create time — announced on stderr as `[amicus] engine version skew: …` (once per standing skew per server, not once per session) and repeated in the ` (engine skew: …)` clause above. The remedy is to make the two copies the same version — update whichever is behind (`npm i -g amicus`, or re-run the installer for the surface that failed). `amicus doctor` will **not** confirm this one: its engine check compares npx-cached copies against the global install and is structurally blind to the copy the running server loaded, so it can report clean while this notice is firing. One related line can also appear, once per process: `[amicus] server identity unavailable — skew attribution is process-wide; SDK shape may have changed`. It means amicus could not read which server a client is talking to, so skew records stop being kept per server and share one bucket — the skew detection still works, but a clause could in principle be attributed to the wrong server when a run talks to more than one. It is a report about amicus itself, not about your models; if you see it, the OpenCode SDK has probably changed shape and amicus needs an update. If neither clause is present, read the log yourself before chasing model/endpoint theories — see the fix below for where it lives.
 
 **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 `~/.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 `600s`, 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 300 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).
+**Fix:** Read the ` — engine log: …` clause on the failure message first, if it has one — that is the engine's own account of this session (see #133 above). If it has none, look yourself: OpenCode writes its logs to `$XDG_DATA_HOME/opencode/log` when that variable is set, otherwise `~/.local/share/opencode/log` (that path holds on Windows too) — check **both** when `XDG_DATA_HOME` is set, since a leftover value can point at a directory the running engine never writes to (amicus searches all of them, newest file first, and answers from the most recently written line that both is an ERROR and names your session). Current engine builds write **one timestamped file per process** there, e.g. `2026-08-25T185532.log`; older ones append to a single `opencode.log` in the same directory, and both layouts turn up on real machines — so check the newest files by modification time, not one fixed filename. The session's `ses_…` id is the correlation key. 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 `600s`, 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 300 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).
 
 ---
 

package/docs/usage.md

@@ -203,6 +203,7 @@ amicus council run --prompt-file briefing.md --models gemini,glm --chair deepsee
 | `--artifact <file>` | File whose content fills `{{artifact}}`/`{{artifact_path}}` (256 KB cap). Requires `--template`. |
 | `--var <k=v>` | Set `{{var.<key>}}`; repeatable. Requires `--template`. |
 | `--tag <t>` | Label this run for `list`/`--search`/`spend --group-by tag` (1-64 chars, `[A-Za-z0-9_-]`; rejected, not cleaned). Every stage's sub-waves (Stage-1, critic/lens solos, Stage-2, chair, debate) carry the same tag on their wave metadata. |
+| `--intent <review\|task>` | The run's intent (v4.9). `review` — the default — is never stored; `task` marks a task-mode run, recorded as `intent: "task"` on `run.json`/`verdict.json` and kept out of the reliability ledger. Over MCP: the `intent` param on `amicus_council_run`, and a hand-assembled `amicus_council_tally` input may carry `meta.intent` the same emit-when-`task` way. What forks stage by stage — and what stays byte-identical — is in [docs/council.md § Task mode](./council.md#task-mode---intent-task). |
 
 **Exit codes:** `0` full run · `2` degraded but reportable (fewer than 2 judges, chair failure —
 `overallVerdict: null` — a cost ceiling hit after the tally, or a `--max-cost` ceiling set over a
@@ -403,7 +404,7 @@ Each stored alias resolves to one of three outcomes:
 | Outcome | Example line | Meaning |
 |---------|--------------|---------|
 | `SERVED` | `SERVED: gemini -> openrouter/google/gemini-3.6-flash ($0.0004)` | The model answered; cost shown in parens. |
-| `SILENT` (`accepted-but-silent`) | `SILENT: probetest -> anthropic/claude-opus-4-8 — NO_OUTPUT_BACKSTOP: … (accepted but not serving)` | Nothing arrived at all within the probe's 30 s backstop window — shorter than the ordinary 300 s leg default, and not tunable. ⚠️ `accepted-but-silent` is the CLASSIFICATION's name, not a proven fact about the endpoint: a fired backstop shows only that no output, reasoning or tool call arrived in the window, which a stalled gateway or a dropped connection produces just as readily as a model that accepted and then said nothing. Either way it is the "listed but not actually serving" failure this check exists to catch. |
+| `SILENT` (`accepted-but-silent`) | `SILENT: probetest -> anthropic/claude-opus-4-8 — NO_OUTPUT_BACKSTOP: … (no output within the probe window)` | Nothing arrived at all within the probe's 30 s backstop window — shorter than the ordinary 300 s leg default, and not tunable. ⚠️ `accepted-but-silent` is the CLASSIFICATION's name, not a proven fact about the endpoint: a fired backstop shows only that no output, reasoning or tool call arrived in the window, which a stalled gateway or a dropped connection produces just as readily as a model that accepted and then said nothing. Either way it is the "listed but not actually serving" failure this check exists to catch. |
 | `ERROR` | `ERROR:  gpt -> openai/gpt-5.6-terra — 402 Payment Required` | Routing, auth, or provider failure; the raw error is printed. |
 
 **Exit code.** The probe's non-served count folds into the same exit code as the static audit — `max(existing exit, min(nonServedCount, 100))` — so a single `SILENT` or `ERROR` fails the check even when every alias is otherwise catalog-fresh. No stored aliases prints `Live probe: no stored aliases to probe` and never affects the exit code. `--json` adds `probe` (the per-alias array) and `probeCount` (its length) to the `alias-audit` document — both additive, `[]`/`0` when `--live` wasn't passed.
@@ -464,12 +465,31 @@ amicus setup --add-alias fast=google/gemini-2.5-flash   # Add/override one alias
 the same core fields everywhere: `id`, `model`, `status`, `mode` (`interactive`/`headless`),
 `type` (`run` by default), `parentWave` (`null` unless the row is a fan-out leg), `legCount`
 (`null` unless the row is a wave), and `tag` — the one field that's omitted, not `null`, when the
-session has none. The human-readable CLI table adds a `TAG` column. Council-run rows are an
-**MCP-only** row class: the CLI's own directory scan skips their `council-<runId>.json` pointer
-files (a pointer's filename fails the session-ID pattern every other row's directory name must
-match), so `amicus list` never shows a council run — only the MCP `amicus_list` tool merges them
-in, each carrying `type: 'council-run'`, a fixed `mode: 'headless'`, and its own 80-char sanitized
-`briefing` preview plus a `stage` field naming whichever stage is currently running. The MCP tool
+session has none. The human-readable CLI table adds a `TAG` column. Council-run rows join the
+listing on **both surfaces** through a separate merge (`src/sidecar/list-council.js`): the
+directory scan itself still skips their `council-<runId>.json` pointer files (a pointer's
+filename fails the session-ID pattern every other row's directory name must match), which is
+exactly why the merge exists. Each merged row carries `type: 'council-run'`, a fixed
+`mode: 'headless'`, and its own 80-char sanitized `briefing` preview plus a `stage` field naming
+whichever stage is currently running; the CLI table renders `council(<stage>)` in its MODEL
+column and re-truncates that 80-char preview to its usual 30-char slice. That merge is scoped
+to the CURRENT project on both surfaces — `--all` included, so under `--all` the session rows
+span every known project while the council rows do not: council runs are found through
+per-project pointer files and there is no cross-project council index to walk. The CLI says
+so at runtime rather than only here — every human-readable `--all` listing ends with
+`council runs: current project only (no cross-project index).`, under the table or right after
+`No amicus sessions found.` when there is no table, and after the `--limit` elision notice when
+one is printed. That line is human-surface only: `--json`
+keeps its shape, on stdout and stderr alike, because no flag can widen the scope it reports.
+If the merge itself cannot run — an unreadable or corrupt council pointer, say — the listing
+still prints the sessions it already had and adds `council runs: unavailable (<reason>)`,
+rather than dropping every council row in silence. It appears with or without `--all` (under
+`--all` it sits just above the scope note), and the reason is the underlying error message,
+sanitised and capped to one line. This one is human-surface only for a *different* reason than
+the scope note: not that nothing could widen it, but that `--json`'s shape is a contract and
+this is prose. The residual that leaves — a `--json` caller reads a well-formed document that
+is silently short — is recorded at the pins in `tests/list-council-merge.test.js`.
+The MCP tool
 also re-sanitizes every other row's `briefing` to that same 80-char cap and, for any row still
 `status: 'running'`, adds live-progress fields (`phase`, `messageCount`, `lastActivityAt`,
 `latestPreview`) — enrichments the CLI table doesn't apply, since it prints the raw 30-char slice
@@ -481,10 +501,10 @@ at a missing or unreadable project is skipped rather than surfaced as an error.
 fan-out wave row reads its full `briefing.md` off disk (falling back to the row's 200-char excerpt
 if that file isn't readable), and a leg row (one spawned by a wave) matches on `id`/`tag` only —
 its briefing is the parent wave's, and matching it there would surface the same wave once per leg
-it spawned. On the MCP tool specifically, a council-run row's search material is `briefing.md`
-written at MCP launch time, or falls back to the portion of `briefing-stage1.md` after
-`--- MATERIAL / BRIEFING ---` (CLI-launched runs only ever have the latter file) — this clause is
-MCP-only, since the CLI never lists a council row to search in the first place. A bare `--search`
+it spawned. A council-run row's search material (both surfaces, now that the CLI merges council
+rows too) is `briefing.md` written at MCP launch time, or falls back to the portion of
+`briefing-stage1.md` after `--- MATERIAL / BRIEFING ---` (CLI-launched runs only ever have the
+latter file). A bare `--search`
 with no value is a usage error on the CLI. Tag itself is set at launch with `--tag <t>` on
 `start`/`fanout`/`council run` (see those sections above), and is also a dimension for
 `amicus spend --group-by tag`. `amicus continue` and `amicus resume` don't take a `--tag` of
@@ -518,7 +538,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.8.1",
+  "version": "4.9.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -849,6 +869,102 @@ The async pattern is **start → status → read**: `amicus_start` (or `amicus_f
 
 Session statuses: `running`, `complete`, `aborted`, `crashed`, `error`, `timed-out`, `idle-timeout`
 
+### MCP tool parameters
+
+Every tool below also takes an optional `project` — an absolute path naming the working directory the call resolves against, auto-detected from the caller's cwd when omitted. `amicus_setup` and `amicus_guide` take no parameters at all; `amicus_council_stats` takes only `project`; and `amicus_spend`'s nine filters are described in the paragraph above. A handful of parameters not listed here are filled in by the calling agent from facts only it can see (the Cowork VM process name, the parent session UUID) rather than chosen by you — they are documented in the tool schema the agent reads, and pinned as such in `tests/mcp-tool-params-docs.test.js`.
+
+**`amicus_start`** — spawn a session with another model.
+
+- `model` — short alias (`gemini`, `gpt`, `opus`, `deepseek`, …) or a full `provider/model` id. Omitted uses your configured default.
+- `gateway` — routing preference: `auto` (direct-first, the default), `direct`, or `openrouter`.
+- `prompt` — the task briefing: objective, background, files of interest, success criteria.
+- `agent` — OpenCode agent mode (`Chat`, `Plan`, `Build`); see [OpenCode Agent Types](#opencode-agent-types) below.
+- `noUi` — run headless instead of opening the Electron window. Default `false`.
+- `thinking` — reasoning effort (`low` | `medium` | `high`). Default `medium`.
+- `timeout` — headless timeout in minutes (default 15); applies only when `noUi` is true.
+- `contextTurns` — max parent-conversation turns to include. Default 50; the MCP twin of `--context-turns`.
+- `contextSince` — time window for parent context (`30m`, `2h`, `1d`); overrides `contextTurns` when set. The MCP twin of `--context-since`.
+- `contextMaxTokens` — cap on the included context, in tokens. Default 80000.
+- `includeContext` — include the parent conversation at all. Default `true`; set `false` for a self-contained briefing (the MCP twin of `--no-context`).
+- `summaryLength` — fold-summary verbosity: `brief`, `normal` (default), or `verbose`.
+- `windowPosition` — where the interactive window lands: `right` (default), `left`, or `center`.
+- `pack` — [policy pack](#policy-packs) name or path supplying defaults; explicit params still win.
+- `tag` — a 1-64 character label (letters, digits, `_`, `-`) for `list`/`search`/`spend` grouping.
+
+**`amicus_status`** — one-shot status. Takes `taskId` (a session or wave id).
+
+**`amicus_abort`** — stop a running session. Takes `taskId`.
+
+**`amicus_wait`** — block until a run reaches a terminal state, replacing a sleep+poll loop.
+
+- `taskId` — the session or wave id to wait on.
+- `waveId` — alias for `taskId` when waiting on a fan-out wave.
+- `timeoutMs` — max wait in milliseconds. Default 50000, capped at 110000 so the call returns before typical MCP client kill windows; on expiry you get `{timedOut: true}`, not an error, and re-call.
+
+**`amicus_read`** — read a finished session. Every mode is capped at ~50KB.
+
+- `taskId` — the task to read.
+- `mode` — `summary` (default), `conversation`, or `metadata`. Paging is ignored in `metadata`.
+- `offset` — byte offset to start from (0-based). Suppresses the cap and the truncation notice, and takes precedence over `tail`.
+- `limit` — max bytes to return (1-51200). Defaults to the cap.
+- `tail` — return the LAST `limit` bytes instead of the first. Ignored when `offset` is given; it is also the implicit behaviour when content exceeds the cap and neither is set.
+
+**`amicus_list`** — list sessions.
+
+- `status` — filter by status (`all`, `running`, `complete`, `error`, `aborted`, …). Default: everything.
+- `search` — case-insensitive substring filter over id, tag, and briefing material.
+
+**`amicus_resume`** — reopen a finished session. Takes `taskId`, plus `noUi` and `timeout` with the same meanings as on `amicus_start`.
+
+**`amicus_continue`** — send a follow-up turn into a previous session.
+
+- `taskId` — the session to continue from; `prompt` — the new task description.
+- `model` / `gateway` — override the model or routing for the continuation.
+- `noUi` / `timeout` — headless mode and its timeout, as on `amicus_start`.
+- `contextTurns` / `contextMaxTokens` — how much of the previous session's conversation rides along.
+
+**`amicus_fanout`** — same briefing, many models, one wave.
+
+- `models` — 1-10 aliases or full ids (2+ for a genuine fan-out). Mutually exclusive with `council`.
+- `council` — a saved council or a built-in bench (`free`, `budget`, `frontier`) instead of `models`.
+- `prompt` — the briefing every leg receives; `agent`, `thinking`, `timeout`, `summaryLength`, `gateway`, `includeContext`, `pack` and `tag` all mean what they do on `amicus_start`, applied to every leg (`timeout` is per-leg).
+- `onComplete` — `mcp-notify`: send an MCP info notification carrying the terminal event doc when the wave finishes. Advisory and best-effort — `amicus_wait` stays the reliable completion mechanism, and exec commands are never accepted over MCP.
+
+**`amicus_council_tally`** — deterministic tiers + street-cred from an assembled council record.
+
+- `meta` — run metadata; `meta.models` lists every reviewed model, and `meta.intent` marks a task run.
+- `findings` — the run-global findings, ids already `A1`/`B2`/`C3`-prefixed.
+- `adjudications` — one row per (judge × finding): `judge`, `findingId`, `verdict`.
+- `rankings` — each judge's preference order over the reviews; ties are a nested array.
+- `runStats` — optional per-model run stats (status/duration/usage).
+
+**`amicus_verdict`** — merge a tally record with Stage-4 decisions into `verdict.json`.
+
+- `record` — a tally output record (from `amicus_council_tally`).
+- `decisions` — per-finding Stage-4 decisions; defaults to `[]`.
+- `overallVerdict` — the chair's terminal line, carried through from the engine-written `verdict.json`. It is the only copy; omit it when the chair was skipped, and never author one yourself.
+- `seatLoss` / `degrades` — the engine-written critic-seating block and the "what was lost" list, carried through the same way. Omitted means absent, never fabricated.
+- `render` — also return the markdown rendering of the decided verdict.
+- `outDir` — where to refresh `report.html` when `render` is true; rejected if it escapes the project dir. Omit to write nothing.
+
+**`amicus_council_run`** — the full headless council engine, no orchestrating agent required.
+
+- `briefingFile` — path to the briefing (self-contained material + criteria). Councils always brief via file; the file is copied into the run dir.
+- `models` — 2-10 bench seats, or `council` to name a saved council or a built-in bench instead.
+- `chair` — the synthesizing model (default `deepseek`). Must NOT be a bench seat.
+- `critic` — swap one bench seat to an adversarial brief. Must BE a bench seat; mutually exclusive with `lenses`.
+- `lenses` — one expert lens per seat (count must equal seat count). Forces no-ledger; mutually exclusive with `critic`.
+- `outDir` — the run directory. Default `<project>/council-<runId>/`.
+- `maxCost` — whole-run USD ceiling, checked before each paid stage launch.
+- `noCostGate` — disable the per-leg price gate for the WHOLE run, repairs and chair included. Independent of `maxCost`, which still caps the total. See [Cost gate](configuration.md#cost-gate).
+- `timeoutMinutes` — per-leg timeout in minutes (fanout semantics). Default 15.
+- `gateway` — routing preference, as on `amicus_start`.
+- `debate` — add a Stage-2.5 rebuttal round before the chair synthesizes.
+- `claudeReviewFile` — path to Claude's own review, included as a judged entry. Claude is reviewed and ranked like a seat, but never judges or chairs.
+- `intent` — `task` marks a task-mode run (recorded on `run.json`/`verdict.json`, kept out of the reliability ledger): seats produce the deliverable and the chair closes with `ANSWER:` on a disjoint scale. `review` is the default and is never stored. See [docs/council.md § Task mode](./council.md#task-mode---intent-task).
+- `ui` — auto-open the Council Workspace window for this run. Default: opens under Claude Code (local) when Electron and a display exist and `workspace.autoOpen` is not `false`.
+- `onComplete`, `pack`, `tag` — as on `amicus_fanout`.
+
 > Legacy `sidecar_*` tool names were removed entirely in v2.0.0 — the tool surface is `amicus_*` only, always. `AMICUS_LEGACY_ALIASES=1` (the v1.8.0 opt-in switch that used to restore the `sidecar_*` twins) is now a no-op: setting it on the MCP server entry changes nothing. See [docs/SHIMS.md](./SHIMS.md) for the removal record.
 
 > The MCP server auto-detects whether it's running under Claude Code or Claude Desktop/Cowork (from the MCP `initialize` handshake) and passes the right `--client` value downstream — this drives context inclusion, MCP discovery, and session-dir resolution. If detection ever picks the wrong one, force it with `"env": {"AMICUS_MCP_CLIENT": "code-local"}` (or `code-web` / `cowork`) on the MCP server entry.

package/electron/ipc-setup.js

@@ -25,6 +25,10 @@ const { registerLocalProviderHandlers } = require('./ipc-setup-local');
  *   resolves through this local binding instead.
  */
 function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ipcMain } = {}) {
+  // Offer-session catalog snapshots (V17/A4 + PR 199 B1/D2/A1) — the full
+  // lifetime contract lives in electron/offer-session.js.
+  const offerCatalogs = require('./offer-session').createOfferSessions();
+
   ipcMain.handle('sidecar:validate-key', async (_event, provider, key) => {
     try {
       const { validateApiKey } = require('../src/utils/api-key-store');
@@ -62,6 +66,7 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
             const { buildProviderDefaultChoices } = require('../src/utils/provider-default-picker');
             const catalog = await getCatalog();
             result.providerDefault = buildProviderDefaultChoices(provider, { catalog });
+            offerCatalogs.set(_event, provider, catalog);
           } catch (err) {
             logger.error('save-key providerDefault error', { error: err.message });
             result.providerDefault = null;
@@ -80,22 +85,34 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
   // Task 8: apply a per-provider default picker choice. Read-modify-write,
   // no-clobber -- applyProviderDefault only ever writes aliases[vendor] and
   // seeds config.default when absent (see provider-default-picker.js).
-  // Fetches the catalog before applying (issue 195): applyProviderDefault
-  // uses directFormIfProven (model-canonicalization.js) to decide whether to
-  // strip an OpenRouter prefix off chosenId, and needs the catalog to do it.
+  // Applies against the save-key offer's catalog snapshot (V17 / issue 195):
+  // applyProviderDefault uses directFormIfProven (model-canonicalization.js)
+  // to decide whether to strip an OpenRouter prefix off chosenId, and needs
+  // the catalog the offer was built from to do it. Fetching fresh only when
+  // no snapshot exists (no prior offer, or the offer session already ended
+  // via setup-done).
   ipcMain.handle('sidecar:set-provider-default', async (_event, provider, chosenId) => {
-    let catalog = [];
-    try {
-      const { getCatalog } = require('../src/utils/model-catalog');
-      catalog = await getCatalog();
-    } catch (err) {
-      // Best-effort only -- a fetch failure leaves `catalog` empty, which
-      // directFormIfProven (F1, council review of PR 198) reads as NO
-      // evidence, never as license to strip: chosenId is persisted exactly
-      // as given, not re-derived. Applying an already-made picker choice
-      // must never abort on a catalog hiccup, and must never fabricate an
-      // id on one either -- that was the exact bug issue 195 fixed.
-      logger.error('set-provider-default catalog fetch error', { error: err.message });
+    // Reads WITHOUT consuming (PR 199 B1/D2 re-ruled after review F1): the
+    // user's pick is routinely the second-or-later apply for one offer
+    // (auto-apply on render, re-apply per radio change), and each must see
+    // the catalog the visible rows were built from. Staleness is bounded by
+    // the offer session instead: setup-done clears the map, a re-offer
+    // overwrites the entry.
+    let catalog = offerCatalogs.get(_event, provider);
+    if (!catalog) {
+      catalog = [];
+      try {
+        const { getCatalog } = require('../src/utils/model-catalog');
+        catalog = await getCatalog();
+      } catch (err) {
+        // Best-effort only -- a fetch failure leaves `catalog` empty, which
+        // directFormIfProven (F1, council review of PR 198) reads as NO
+        // evidence, never as license to strip: chosenId is persisted exactly
+        // as given, not re-derived. Applying an already-made picker choice
+        // must never abort on a catalog hiccup, and must never fabricate an
+        // id on one either -- that was the exact bug issue 195 fixed.
+        logger.error('set-provider-default catalog fetch error', { error: err.message });
+      }
     }
     try {
       const { applyProviderDefault } = require('../src/utils/provider-default-picker');
@@ -135,6 +152,10 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
   });
 
   ipcMain.handle('sidecar:setup-done', (_event, defaultModel, keyCount) => {
+    // The offer session ends with the wizard: any apply after this fetches
+    // fresh evidence rather than reusing a closed offer's catalog (B1/D2).
+    // A1: only THIS sender's offer sessions end here — never another window's.
+    offerCatalogs.endSession(_event);
     const { BrowserWindow } = require('electron');
     const senderWindow = BrowserWindow.fromWebContents(_event.sender);
     const mainWin = getMainWindow();
@@ -163,11 +184,13 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
       let cfg = loadConfig();
       if (!cfg) {
         const { toLiveSeedAliases } = require('../src/utils/quick-picks');
-        let catalog = [];
+        // issue 214: getCatalogInfo, not getCatalog -- toLiveSeedAliases PERSISTS
+        // these routes, so it must see which namespaces were rejected.
+        let catalogInfo = { models: [] };
         try {
-          catalog = await require('../src/utils/model-catalog').getCatalog();
+          catalogInfo = await require('../src/utils/model-catalog').getCatalogInfo();
         } catch (_err) { /* offline: pinned seeds */ }
-        cfg = { aliases: toLiveSeedAliases(catalog) };
+        cfg = { aliases: toLiveSeedAliases(catalogInfo) };
       }
       if (!cfg.aliases) { cfg.aliases = {}; }
       if (defaultModel) { cfg.default = defaultModel; }

package/electron/main.js

@@ -327,12 +327,20 @@ function createAmicusWindow() {
 async function createSetupWindow() {
   // Lazy-load setup UI to avoid loading it for sidecar mode
   const { buildSetupHTML } = require('./setup-ui');
-  const { resolveQuickPicks, toStorableRoute } = require('../src/utils/quick-picks');
+  const { resolveQuickPicks, canonicalRoutesFor, toStorableRoute } = require('../src/utils/quick-picks');
   let quickPicks;
   const shortlists = {};
   try {
-    const catalog = await require('../src/utils/model-catalog').getCatalog();
+    // issue 208: getCatalogInfo (not getCatalog) -- the shortlist needs the
+    // per-provider fetch outcomes, or directFormIfSafe's namespace-failure
+    // gate cannot fire and a rejected namespace still yields bare direct ids.
+    const catalogInfo = await require('../src/utils/model-catalog').getCatalogInfo();
+    const catalog = catalogInfo.models;
     quickPicks = resolveQuickPicks(catalog);
+    // issue 214: decide each pick's safe storable form HERE, with the catalog in
+    // hand, and ship it as data. The page cannot require() the canonicalisation
+    // primitives, and its hand-copy of them dropped their guards.
+    for (const p of quickPicks) { p.canonicalRoutes = canonicalRoutesFor(p, catalogInfo); }
 
     // issue 138: one vendor shortlist per family card, resolved server-side from
     // the same catalog the quick picks came from (no extra IPC round-trip).
@@ -341,7 +349,8 @@ async function createSetupWindow() {
       try {
         shortlists[p.alias] = buildModelShortlist(p.vendorPath, {
           catalog,
-          recommendedId: toStorableRoute(p),
+          providerFailures: catalogInfo.providerFailures,
+          recommendedId: toStorableRoute(p, catalogInfo),
         });
       } catch (_e) { /* a shortlist failure must never block the wizard */ }
     }
@@ -520,21 +529,26 @@ function createSettingsChildWindow() {
   // createSetupWindow awaits. A missing or corrupt cache reads back as null
   // and degrades to the same pinned fallback buildSetupHTML already applies
   // when no quickPicks are given.
-  const { resolveQuickPicks, toStorableRoute } = require('../src/utils/quick-picks');
+  const { resolveQuickPicks, canonicalRoutesFor, toStorableRoute } = require('../src/utils/quick-picks');
   const { readCache } = require('../src/utils/model-catalog');
   let quickPicks;
   const shortlists = {};
   try {
     const cacheDoc = readCache();
     const catalog = cacheDoc ? cacheDoc.models : [];
+    // issue 208: the cache doc carries the fetch outcomes for THESE rows.
+    const providerFailures = (cacheDoc && cacheDoc.providerFailures) || [];
     quickPicks = resolveQuickPicks(catalog);
+    // issue 214: see the note at the other resolveQuickPicks site.
+    for (const p of quickPicks) { p.canonicalRoutes = canonicalRoutesFor(p, { models: catalog, providerFailures }); }
 
     const { buildModelShortlist } = require('../src/utils/model-shortlist');
     for (const p of quickPicks) {
       try {
         shortlists[p.alias] = buildModelShortlist(p.vendorPath, {
           catalog,
-          recommendedId: toStorableRoute(p),
+          providerFailures,
+          recommendedId: toStorableRoute(p, { models: catalog, providerFailures }),
         });
       } catch (_e) { /* a shortlist failure must never block the wizard */ }
     }

package/electron/offer-session.js

@@ -0,0 +1,51 @@
+/**
+ * Offer-session catalog snapshots for the setup wizard's provider-default
+ * flow (extracted from ipc-setup.js at the 300-line gate, v4.9 / PR 199).
+ *
+ * V17 (council A4): each save-key offer snapshots the catalog it was built
+ * from, so set-provider-default applies against the SAME catalog the picker
+ * offered — a re-fetch there could return a different catalog and flip
+ * directFormIfProven's evidence (TOCTOU).
+ *
+ * Lifetime = the OFFER SESSION (PR 199 B1/D2, re-ruled after review F1):
+ * the wizard auto-applies on render and re-applies on every radio change,
+ * so EVERY apply while the offer is on screen must see the offer's own
+ * catalog — a one-shot delete-on-read handed every human pick a fresh
+ * fetch, which is the original A4 race. A re-offer overwrites the entry;
+ * setup-done ends the sender's sessions.
+ *
+ * Keyed per SENDER + provider (PR 199 round-2 council A1): two Settings
+ * windows are independent offer sessions — one window's offer, apply, or
+ * completion must never alter another's. A harness event with no sender id
+ * keys by provider alone (also the single-window behavior), and its
+ * endSession ends every session.
+ */
+
+'use strict';
+
+function createOfferSessions() {
+  const snapshots = new Map();
+  const senderId = (event) => {
+    const sid = event && event.sender ? event.sender.id : undefined;
+    return (sid === undefined || sid === null) ? null : sid;
+  };
+  const key = (event, provider) => {
+    const sid = senderId(event);
+    return (sid !== null ? sid + ':' : '') + provider;
+  };
+  return {
+    /** Arm (or re-arm) the sender's offer session for a provider. */
+    set(event, provider, catalog) { snapshots.set(key(event, provider), catalog); },
+    /** The sender's live offer catalog for a provider, or undefined. */
+    get(event, provider) { return snapshots.get(key(event, provider)); },
+    /** End every offer session belonging to this sender (setup-done). */
+    endSession(event) {
+      const sid = senderId(event);
+      for (const k of [...snapshots.keys()]) {
+        if (sid === null || k.startsWith(sid + ':')) { snapshots.delete(k); }
+      }
+    },
+  };
+}
+
+module.exports = { createOfferSessions };