amicus 4.5.1 → 4.5.2

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.5.2] - 2026-07-31
+
+### Fixed
+
+- **OpenCode server-start timeout is no longer pinned to the SDK's 5000 ms, and a start timeout
+  is now retried.** `@opencode-ai/sdk` defaults `createOpencodeServer`'s start timeout to 5 s and
+  lets the caller override it; amicus never passed one, so every start on every platform ran on
+  that default — undocumented, untunable, and invisible to `amicus doctor`. Worse, the existing
+  start retry (`retryOnLockRace`) classified only `database is locked` / `SQLITE_BUSY`, so a start
+  timeout fell straight through with **zero** retries, past machinery already wired in at every
+  call site. On a Windows box with the project on a OneDrive-synced volume and Defender active, a
+  cold OpenCode/SQLite start blew the window: the council's shared server failed to acquire, the
+  run degraded to exactly the per-wave configuration `src/council/run-server.js` exists to
+  eliminate, and the whole Stage-1 bench died with `COUNCIL_QUORUM: Only 0 Stage-1 review(s)
+  survived`. Three of the reporter's runs were lost this way. A start timeout is now classified as
+  transient (`isTimeoutClassStartFailure`) and retried on the same bounded 250/500/1000/2000 ms
+  schedule, the timeout is threaded through `buildServerOptions` and both upstream start sites,
+  and the default is raised to **30 s on Windows / 15 s elsewhere** — a slow start costs latency,
+  a failed start costs a review seat.
+- **The Electron self-heal was dead code in every published install.** `src/sidecar/unzip.js`
+  did a bare, unguarded `require('extract-zip')` for a package that was never declared in
+  `dependencies` or `optionalDependencies`. It resolved in the dev tree only because `puppeteer`
+  (a devDependency) pulls it transitively — `npm ls extract-zip --omit=dev` returned empty — so on
+  a real `npm i -g amicus` `robustExtract` threw `MODULE_NOT_FOUND` before Strategy 1. That made
+  the native-unzip fallback below it unreachable, the bounded idle/max timers from the
+  extract-zip-node24 work inert, and `amicus doctor --fix` dead-end at `self-heal incomplete` —
+  while routing users toward antivirus allow-listing for what was actually a missing module.
+  `extract-zip` is now a declared production dependency, the `require` degrades into the native
+  strategies instead of throwing out of the function, and a new `no-phantom-dependencies` test
+  fails on any undeclared runtime require anywhere in `src/`, `bin/` or `electron/`.
+- **A lost critic is now recorded on `verdict.json`.** The critic is a solo wave with one leg, and
+  unlike a dead bench wave (which trips the quorum gate and fails the run loudly) a dead critic is
+  survivable — so a run could reach a full verdict, tally and chair synthesis that had never seen
+  the adversarial seat, with the only record being `deadWaves` in `run.json`. Field run `dfb6a692`
+  did exactly that. `verdict.json` now carries an optional `seatLoss` block
+  (`criticRequested`/`criticSeated`/`reason`/`deadBenchSeats`) whenever `--critic` was requested,
+  so a reader of the verdict can see the critic never ran. Additive; `schemaVersion` stays `2`.
+
+### Added
+
+- **`AMICUS_SERVER_START_TIMEOUT_MS`** — override the server-start window (see
+  [docs/configuration.md](docs/configuration.md#server-startup)). Values ≤ 0 are ignored rather
+  than honored, since a zero start timeout fails every start instantly.
+- **Successful server starts are logged at debug level** with both `startMs` and the `timeoutMs`
+  ceiling in force, so headroom on a slow box is measurable rather than inferred — the question
+  the field report could not answer.
+
 ## [4.5.1] - 2026-07-30
 
 ### Added

package/README.md

@@ -15,6 +15,8 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?labelColor=1A1C29)](https://nodejs.org)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?labelColor=1A1C29)](./CONTRIBUTING.md)
 
+**[Quick start ↓](#quick-start)** · [Commands](#commands) · [Documentation](#documentation) · [Troubleshooting](#troubleshooting)
+
 > **Supported clients:** Claude Code CLI, Claude Desktop, and Claude Cowork are fully tested and supported. Claude Code web is experimental.
 
 </div>
@@ -24,10 +26,10 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 ## Table of Contents
 
 - [What is Amicus](#what-is-amicus)
+- [The Council](#the-council)
 - [Ways to run the council](#ways-to-run-the-council)
 - [Quick start](#quick-start)
 - [Requirements & Dependencies](#requirements--dependencies)
-- [The Council](#the-council)
 - [The parallel window](#the-parallel-window)
 - [Commands](#commands)
 - [Models](#models)
@@ -52,7 +54,7 @@ One install delivers six things that work together:
 - **The `amicus` CLI (with an `am` alias) and an MCP server.** The engine underneath both skills: launches sessions, shares context, runs parallel waves, and exposes the same surface to Claude as MCP tools.
 - **A self-updating model catalog.** Aliases and validation resolve against a live catalog fetched from provider APIs (cached locally), so model names stay current without a hard-coded table.
 - **Observability.** `amicus watch <id>` renders any live or finished run (fan-out or council) from any terminal; `--follow` streams milestones as they happen; `--on-complete` fires a hook when a run lands; `--retry-failed` plus opt-in cheaper-model fallbacks recover dead legs without relaunching the whole wave; `amicus spend` answers "what did this cost, and where" with per-run attribution.
-- **Council Workspace.** `amicus watch <runId> --ui`: a window that shows a council *thinking* — live seats, the anonymized judge packet, the adjudication matrix, dissent drill-in, chair verdict, and cost-by-seat — for both live and historical runs. It also **auto-opens** on an MCP-invoked council run from Claude Code (local), so you no longer have to remember the flag (see [The Council](#the-council)).
+- **Council Workspace.** `amicus watch <runId> --ui`: a window that shows a council *thinking* — live seats, the anonymized judge packet, the adjudication matrix, dissent drill-in, chair verdict, and cost-by-seat — for both live and historical runs. It also **auto-opens** on an MCP-invoked council run from Claude Code (local), so you no longer have to remember the flag (see [docs/council.md](./docs/council.md#council-workspace-gui)).
 
 Claude is the orchestrator. The council and chat skills run *on top of* the engine; you talk to Claude, and Claude drives Amicus.
 
@@ -60,15 +62,103 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ---
 
+## The Council
+
+> Trigger it by saying *"council review this"* to Claude, or, on the plugin channel, run **`/amicus:council`** directly.
+
+**Why multi-model.** Any single model — including the one running your session — has consistent blind spots. Route the *same* material through models from *different* families and the disagreements surface: missed issues, overstated confidence, claims one model alone would have waved through. The council is the structured version of that idea.
+
+**The flow, in five beats:**
+
+1. **Independent reviews.** Each council model reviews the artifact on its own (one parallel wave), producing a structured findings list — claim, severity (`blocker | major | minor | nit`), location, rationale.
+2. **Anonymized cross-review.** Claude relabels every review (Review A, B, C…) and sends the identical bundle to every model. Each model ranks the reviews and adjudicates every finding (`agree | dispute | neutral`) — *unknowingly judging its own*, so self-bias washes out. This yields a **street-cred** ranking and sorts findings into **Disputed / Confirmed / Contested / Singleton** tiers.
+3. **Chair verdict.** A designated **non-Claude** chair receives the de-anonymized picture — all reviews, rankings, and adjudications — and synthesizes an independent verdict. Claude presents it verbatim; Claude does not synthesize.
+4. **Tiered decisions.** Confirmed findings get one bulk accept/deny; Contested and Singleton findings are decided one at a time (accept / deny / modify).
+5. **Outputs applied.** Accepted findings are written into a reviewed copy of the source; the full run is captured in the run folder.
+
+```mermaid
+flowchart LR
+    A["Artifact"] --> B["Independent<br/>reviews"]
+    B --> C["Anonymized<br/>cross-review"]
+    C --> D["Chair verdict<br/>(non-Claude)"]
+    D --> E["Tiered<br/>accept / deny"]
+    E --> F["Reviewed copy<br/>+ run folder"]
+```
+
+**What a run produces** (in `output/<stem>-council/`):
+
+- `review-<model>.md` × N — each model's independent review.
+- `crossreview-matrix.md` — the adjudication grid plus the de-anonymized street-cred table.
+- `verdict.md` — the chair's synthesis.
+- `report.md` — synthesis + the full decision log + a per-call run-stats table.
+- `report.html` — the deterministic renderer output (adjudication matrix, street-cred table,
+  findings-by-tier, cost — no chair prose). This is the default artifact handed to the user.
+- For an **editable source**, the accepted edits land in `<stem>-reviewed.<ext>` next to the original.
+
+**Optional council elements** (v2.2.0, all default off): five opt-in behaviors, offered once as a menu at launch — nothing turns on unless you name it, and the confirmation lists exactly what's on.
+
+- **Critic seat** — one reviewer swaps to a four-pass adversarial brief (adversarial pass, edge-case hunt, consistency check, executability test). Its findings enter the same anonymized bundle as everyone else's, so the bench disciplines the critic: manufactured negativity lands Disputed and dies in the tally.
+- **Expert lenses** — each reviewer takes a distinct expert perspective; you pick the panel domain (business, technical, customer, financial, or custom). Lens runs never feed the reliability ledger, and the report discloses the weakened cross-review anonymity.
+- **Debate mode** — after cross-review, every Contested or Disputed finding goes back to its raiser to **defend, amend, or withdraw**, and the disputing judges re-vote. Exactly one rebuttal round, then the final tally.
+- **Chair verdict scale** — the chair closes with 3–5 hard questions and one parseable line: `VERDICT: Ship it | Fix these first | Fundamental rethink`.
+- **Claude in the council** — Claude adds its own fresh review to the bundle so the bench ranks and adjudicates it. Claude is *judged* but never votes or chairs, so the verdict stays independent.
+
+The critic and lens methodologies are adapted from the `/critic` and `/debate` agents in [John Renaldi's product-kit](https://github.com/jrenaldi79/plugin-marketplace) (MIT); the briefing boilerplate lives in [`skills/second-opinion/SEAT-BRIEFS.md`](./skills/second-opinion/SEAT-BRIEFS.md).
+
+**Cost is disclosed up front.** Before any model launches, you see the run shape — including any enabled optional elements — for example:
+
+> This run uses 3 council models across 2 fanout waves + 1 chair call, with critic seat + debate mode ON (~7 base runs + up to 6 rebuttal calls).
+
+Then the council waits for your confirmation.
+
+The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**. For what `amicus council tally|verdict|report|stats` actually take as input and produce — field-by-field schemas, verdict.json's provenance, and a full worked example run against the real CLI — see **[docs/council.md](./docs/council.md)**.
+
+---
+
 ## Ways to run the council
 
 The council is the hero — start with the everyday way, and reach for the more powerful ways when you need them:
 
-- **Just ask, in Claude Code.** Hand Claude a plan, diff, design, or manuscript and say *"council review this."* The `second-opinion` skill runs the whole ritual in your session — several models review independently → anonymized cross-review → a non-Claude chair verdict → tiered accept/deny edits — with no setup beyond your API keys. This is how most people use it. → [The Council](#the-council)
-- **Headless, in CI, with no Claude runtime.** `amicus council run --prompt-file plan.md --council free` runs that same pipeline in one command — reviews → cross-review → tally → chair verdict — writing `verdict.json` and `report.html`. It needs no Claude session, so it drops straight into CI. → [Headless council](./docs/council.md#amicus-council-run)
+- **Just ask, in Claude Code.** Hand Claude a plan, diff, design, or manuscript and say *"council review this."* The `second-opinion` skill runs the whole ritual above in your session, with no setup beyond your API keys. This is how most people use it. → [Quick start](#quick-start)
+- **Headless, in CI, with no Claude runtime.** `amicus council run --prompt-file plan.md --council free` runs that same pipeline in one command — reviews → cross-review → tally → chair verdict — writing `verdict.json` and `report.html`. It needs no Claude session, so it drops straight into CI. → [Headless council (CI)](#headless-council-ci)
 - **With a debate round.** Add `--debate` and every Contested or Disputed finding goes back to its raiser to **defend, amend, or withdraw** while the disputing judges re-vote — exactly one rebuttal round, then the final tally. → [The Council](#the-council)
 - **On free, local, private models — at $0.** Point the council (and sidecars) at an OpenAI-compatible server already running on your machine — Ollama, LM Studio, or vLLM — with `amicus provider add`. No API key, no per-token bill, nothing leaves your machine, and it works offline. → [`amicus provider`](./docs/usage.md#amicus-provider)
 
+### Headless council (CI)
+
+The same pipeline runs with no Claude runtime at all: `amicus council run --prompt-file briefing.md --models gemini,glm --chair deepseek --json` executes the review waves, the anonymized cross-review, the tally, and the chair verdict in one command, and writes the full run directory (`verdict.json` with the chair's parsed `overallVerdict`, `report.html`, every review and judge output). That is what powers the repo's own **Council Review GitHub Action v2** — on PRs labeled `council-review` it posts an adjudicated verdict as a check run plus a sticky comment, uploads the run directory as an evidence artifact, and can optionally gate merges via its `fail_on` input (default: report-only). Reference: [docs/council.md](./docs/council.md#amicus-council-run).
+
+### Free council (zero-cost)
+
+Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
+
+Run it anywhere a council runs:
+
+```bash
+amicus fanout --council free --prompt "Review this design"
+```
+
+The `amicus_fanout` MCP tool takes the same `council` parameter, and the `second-opinion` skill reads `councils.free` automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are **rate-limited and quality-variable**, and some return 404 unless you enable data-sharing at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy).
+
+### Council presets
+
+Save your own named member lists with `amicus council save <name> --models a,b,c` (≥2 resolvable aliases or `provider/model` IDs), then run them with `--council <name>` anywhere a council runs. `amicus council list` shows saved presets plus three built-in benches that work with no setup at all — `free` (the same zero-cost dynamic pick described above, used when you haven't seeded `councils.free`), `budget` (cheap workhorses, one per vendor family), and `frontier` (premium flagships, one per vendor family). `amicus council show <name>` resolves any of them (saved or built-in) and reports which members are currently usable. A saved council always shadows a built-in of the same name — exactly how the wizard's `councils.free` seeding already worked.
+
+### Policy packs (v4.5)
+
+A council preset only saves the bench. A **pack** saves the whole run — bench, chair, critic/lenses, cost/timeout options, and a briefing template — as one named, shareable JSON file:
+
+```bash
+amicus pack save review-bench --kind council --bench gemini,deepseek,gpt --chair opus --timeout 20 --max-cost 2
+amicus council run --pack review-bench --prompt-file plan.md --json
+```
+
+Any flag you also type on that second line overrides just that value — a pack only fills in what you didn't say explicitly, and it's recorded on the run either way. Packs work the same way on `fanout`/`start` and on the `amicus_fanout`/`amicus_start`/`amicus_council_run` MCP tools. `amicus pack list`/`show`/`rm` manage them, and `--from-run <id>` builds one from a run you already liked instead of typing flags at all. Full reference: [docs/usage.md § Policy packs](./docs/usage.md#policy-packs).
+
+### Briefing templates (v4.5)
+
+`--template <name> --artifact <file>` (plus repeatable `--var k=v`) renders a `{{prompt}}`/`{{artifact}}`-style Markdown template before it's sent, on `start`/`fanout`/`council run` alike — templates live in `~/.config/amicus/templates/`, and a pack's `briefing.template` is how one reaches an MCP-invoked run (MCP has no template param of its own). `amicus template list|show` manage them; v4.5 ships one built-in, `review`. Full reference: [docs/usage.md § Briefing templates](./docs/usage.md#briefing-templates).
+
 ---
 
 ## Quick start
@@ -152,6 +242,14 @@ amicus start --model gemini --prompt "Fact-check the auth approach Claude just p
 
 A window opens alongside your editor with Gemini ready, pre-loaded with your conversation. Work with it, then **Fold** the summary back.
 
+### Updating
+
+Amicus checks the npm registry at most once every 24 hours (cached background check). When an update exists, the CLI prints a notice and the Electron toolbar shows a one-click **Update** banner. Or run it yourself:
+
+```bash
+amicus update
+```
+
 ### Install from GitHub
 
 The npm package is the primary path. To install straight from the repo instead — the postinstall runs **identically** (same MCP registration, same two skills) — you just need `git` on your `PATH`:
@@ -204,82 +302,6 @@ Everything you need before your first run, and what's optional.
 
 ---
 
-## The Council
-
-> Trigger it by saying *"council review this"* to Claude, or, on the plugin channel, run **`/amicus:council`** directly.
-
-**Why multi-model.** Any single model — including the one running your session — has consistent blind spots. Route the *same* material through models from *different* families and the disagreements surface: missed issues, overstated confidence, claims one model alone would have waved through. The council is the structured version of that idea.
-
-**The flow, in five beats:**
-
-1. **Independent reviews.** Each council model reviews the artifact on its own (one parallel wave), producing a structured findings list — claim, severity (`blocker | major | minor | nit`), location, rationale.
-2. **Anonymized cross-review.** Claude relabels every review (Review A, B, C…) and sends the identical bundle to every model. Each model ranks the reviews and adjudicates every finding (`agree | dispute | neutral`) — *unknowingly judging its own*, so self-bias washes out. This yields a **street-cred** ranking and sorts findings into **Disputed / Confirmed / Contested / Singleton** tiers.
-3. **Chair verdict.** A designated **non-Claude** chair receives the de-anonymized picture — all reviews, rankings, and adjudications — and synthesizes an independent verdict. Claude presents it verbatim; Claude does not synthesize.
-4. **Tiered decisions.** Confirmed findings get one bulk accept/deny; Contested and Singleton findings are decided one at a time (accept / deny / modify).
-5. **Outputs applied.** Accepted findings are written into a reviewed copy of the source; the full run is captured in the run folder.
-
-**What a run produces** (in `output/<stem>-council/`):
-
-- `review-<model>.md` × N — each model's independent review.
-- `crossreview-matrix.md` — the adjudication grid plus the de-anonymized street-cred table.
-- `verdict.md` — the chair's synthesis.
-- `report.md` — synthesis + the full decision log + a per-call run-stats table.
-- `report.html` — the deterministic renderer output (adjudication matrix, street-cred table,
-  findings-by-tier, cost — no chair prose). This is the default artifact handed to the user.
-- For an **editable source**, the accepted edits land in `<stem>-reviewed.<ext>` next to the original.
-
-**Optional council elements** (v2.2.0, all default off): five opt-in behaviors, offered once as a menu at launch — nothing turns on unless you name it, and the confirmation lists exactly what's on.
-
-- **Critic seat** — one reviewer swaps to a four-pass adversarial brief (adversarial pass, edge-case hunt, consistency check, executability test). Its findings enter the same anonymized bundle as everyone else's, so the bench disciplines the critic: manufactured negativity lands Disputed and dies in the tally.
-- **Expert lenses** — each reviewer takes a distinct expert perspective; you pick the panel domain (business, technical, customer, financial, or custom). Lens runs never feed the reliability ledger, and the report discloses the weakened cross-review anonymity.
-- **Debate mode** — after cross-review, every Contested or Disputed finding goes back to its raiser to **defend, amend, or withdraw**, and the disputing judges re-vote. Exactly one rebuttal round, then the final tally.
-- **Chair verdict scale** — the chair closes with 3–5 hard questions and one parseable line: `VERDICT: Ship it | Fix these first | Fundamental rethink`.
-- **Claude in the council** — Claude adds its own fresh review to the bundle so the bench ranks and adjudicates it. Claude is *judged* but never votes or chairs, so the verdict stays independent.
-
-The critic and lens methodologies are adapted from the `/critic` and `/debate` agents in [John Renaldi's product-kit](https://github.com/jrenaldi79/plugin-marketplace) (MIT); the briefing boilerplate lives in [`skills/second-opinion/SEAT-BRIEFS.md`](./skills/second-opinion/SEAT-BRIEFS.md).
-
-**Cost is disclosed up front.** Before any model launches, you see the run shape — including any enabled optional elements — for example:
-
-> This run uses 3 council models across 2 fanout waves + 1 chair call, with critic seat + debate mode ON (~7 base runs + up to 6 rebuttal calls).
-
-Then the council waits for your confirmation.
-
-The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**. For what `amicus council tally|verdict|report|stats` actually take as input and produce — field-by-field schemas, verdict.json's provenance, and a full worked example run against the real CLI — see **[docs/council.md](./docs/council.md)**.
-
-**Headless council (CI).** The same pipeline runs with no Claude runtime at all: `amicus council
-run --prompt-file briefing.md --models gemini,glm --chair deepseek --json` executes the review
-waves, the anonymized cross-review, the tally, and the chair verdict in one command, and writes
-the full run directory (`verdict.json` with the chair's parsed `overallVerdict`, `report.html`,
-every review and judge output). That is what powers the repo's own **Council Review GitHub Action
-v2** — on PRs labeled `council-review` it posts an adjudicated verdict as a check run plus a
-sticky comment, uploads the run directory as an evidence artifact, and can optionally gate merges
-via its `fail_on` input (default: report-only). Reference: [docs/council.md](./docs/council.md#amicus-council-run).
-
-**Free council (zero-cost).** Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
-
-Run it anywhere a council runs:
-
-```bash
-amicus fanout --council free --prompt "Review this design"
-```
-
-The `amicus_fanout` MCP tool takes the same `council` parameter, and the `second-opinion` skill reads `councils.free` automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are **rate-limited and quality-variable**, and some return 404 unless you enable data-sharing at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy).
-
-**Council presets.** Save your own named member lists with `amicus council save <name> --models a,b,c` (≥2 resolvable aliases or `provider/model` IDs), then run them with `--council <name>` anywhere a council runs. `amicus council list` shows saved presets plus three built-in benches that work with no setup at all — `free` (the same zero-cost dynamic pick described above, used when you haven't seeded `councils.free`), `budget` (cheap workhorses, one per vendor family), and `frontier` (premium flagships, one per vendor family). `amicus council show <name>` resolves any of them (saved or built-in) and reports which members are currently usable. A saved council always shadows a built-in of the same name — exactly how the wizard's `councils.free` seeding already worked.
-
-**Policy packs (v4.5).** A council preset only saves the bench. A **pack** saves the whole run — bench, chair, critic/lenses, cost/timeout options, and a briefing template — as one named, shareable JSON file:
-
-```bash
-amicus pack save review-bench --kind council --bench gemini,deepseek,gpt --chair opus --timeout 20 --max-cost 2
-amicus council run --pack review-bench --prompt-file plan.md --json
-```
-
-Any flag you also type on that second line overrides just that value — a pack only fills in what you didn't say explicitly, and it's recorded on the run either way. Packs work the same way on `fanout`/`start` and on the `amicus_fanout`/`amicus_start`/`amicus_council_run` MCP tools. `amicus pack list`/`show`/`rm` manage them, and `--from-run <id>` builds one from a run you already liked instead of typing flags at all. Full reference: [docs/usage.md § Policy packs](./docs/usage.md#policy-packs).
-
-**Briefing templates (v4.5).** `--template <name> --artifact <file>` (plus repeatable `--var k=v`) renders a `{{prompt}}`/`{{artifact}}`-style Markdown template before it's sent, on `start`/`fanout`/`council run` alike — templates live in `~/.config/amicus/templates/`, and a pack's `briefing.template` is how one reaches an MCP-invoked run (MCP has no template param of its own). `amicus template list|show` manage them; v4.5 ships one built-in, `review`. Full reference: [docs/usage.md § Briefing templates](./docs/usage.md#briefing-templates).
-
----
-
 ## The parallel window
 
 When you don't need a full council — just one other model's take — fork a conversation. Amicus extracts your current Claude Code context, opens a session pre-loaded with it, you **work** alongside it, and you **fold** a structured summary back into Claude's context when you're done.
@@ -305,12 +327,6 @@ When you don't need a full council — just one other model's take — fork a co
 
 **Safety.** Amicus warns on **file conflicts** (a file changed externally while the session ran) and on **context drift** (the shared context may be stale relative to your current session), so a fold never silently overwrites newer work.
 
-**Auto-update.** Amicus checks the npm registry at most once every 24 hours (cached background check). When an update exists, the CLI prints a notice and the Electron toolbar shows a one-click **Update** banner. Or run it yourself:
-
-```bash
-amicus update
-```
-
 ![The parallel-window architecture: fork, work, fold](./docs/architecture.png)
 
 ---
@@ -332,7 +348,7 @@ amicus update
 | `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
 | `amicus provider` | Add/list/test/remove local, OpenAI-compatible providers (LM Studio, Ollama, vLLM) — configured with `--preset` or `--url`, at **$0** marginal cost (`--json` on every subcommand). |
-| `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
+| `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [Council presets](#council-presets) for the built-in `free`/`budget`/`frontier` benches. |
 | `amicus council run` | The headless council engine: Stage-1 reviews → anonymized cross-review → deterministic tally → non-Claude chair verdict, in one command with no Claude runtime. Add `--debate` for a Stage-2.5 rebuttal round (raisers defend/amend/withdraw, disputing judges re-vote) and `--claude-review <file>` to enter Claude's own review as judged review N+1. Writes a run directory with `verdict.json` (including `overallVerdict`) and `report.html` — see [docs/council.md](./docs/council.md#amicus-council-run). |
 | `amicus pack` | Save a full run configuration — bench, chair/critic/lenses, options, briefing template — and invoke it by name: `save <name> --kind council\|fanout\|solo [flags]` (or `--from-run <id>`), `list`, `show <name>`, `rm <name>`. `--pack <name>` on `start`/`fanout`/`council run` loads one; explicit flags always override it. See [docs/usage.md § Policy packs](./docs/usage.md#policy-packs). |
 | `amicus template` | `list`/`show <name>` a briefing template. `--template <name> [--artifact <file>] [--var k=v]` on `start`/`fanout`/`council run` renders one before the briefing is sent. See [docs/usage.md § Briefing templates](./docs/usage.md#briefing-templates). |
@@ -364,7 +380,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -474,7 +490,7 @@ Run `amicus doctor` first — it checks keys, catalog, OpenCode binary, Electron
 | `npm install -g amicus` fails with `EEXIST: … claude-sidecar` | The old upstream `claude-sidecar` package is still installed globally; npm won't overwrite another package's bin shims | `npm uninstall -g claude-sidecar`, then `npm install -g amicus`. Your keys and past sessions are not lost, but v2.0.0 no longer reads the old paths automatically — see [docs/SHIMS.md](./docs/SHIMS.md) for the one-time migration steps (rename `~/.config/sidecar/` and any `.claude/sidecar_sessions/` dirs). |
 | Install fails partway, or `amicus doctor` reports the OpenCode binary "not found" | A **transient** error during the OpenCode engine's own postinstall (a spawn `ENOENT`, or an antivirus file-lock while it lays down its 11 per-platform binaries) can roll back the whole atomic install — retrying usually succeeds | Just re-run `npm install -g amicus`. If it still fails, clear the cache first: `npm cache clean --force && npm install -g amicus`. |
 | `401` / auth error | No usable key for the model's vendor — bare `provider/model` ids fall back to `OPENROUTER_API_KEY` automatically, so this means neither the direct key nor an OpenRouter key is configured (or `--gateway direct`/`openrouter` forced a gateway whose key is missing) | Run `amicus setup`, or `amicus key <provider> <key>` to add the missing key; see [Routing](#routing). |
-| `402` / "Payment Required" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter <key>` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See "Free council (zero-cost)" under [The Council](#the-council) above. |
+| `402` / "Payment Required" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter <key>` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See [Free council (zero-cost)](#free-council-zero-cost) above. |
 | Every direct `anthropic/…` model (`haiku`, `sonnet`, `opus`, `claude`) errors `Not Found` in ~2 s at zero tokens, but the same model works via `openrouter/anthropic/…` | An inherited `ANTHROPIC_BASE_URL` missing its `/v1` path segment. The engine appends only `/messages`, so requests hit `https://api.anthropic.com/messages` → HTTP 404 with an empty body → the bare status text. A shell spawned by Claude Code sets the `/v1`-less form for you. The model id, alias, and key are all fine. | `export ANTHROPIC_BASE_URL=https://api.anthropic.com/v1`, or unset it entirely, or pass `--gateway openrouter`. In a council a dead seat **degrades the run instead of failing it** — smoke-test each seat with one throwaway `amicus start` before paying for a council. See [docs/troubleshooting.md](./docs/troubleshooting.md#every-direct-anthropic-model-fails-with-not-found). |
 | `Model 'X' is unverified against the direct catalog; attempting anyway` for a model that plainly exists | Not a claim the model is wrong — amicus **couldn't check**. That vendor's direct catalog fetch failed (usually a stale or truncated stored key), leaving its namespace empty, and an empty namespace never blocks a launch. The engine may still run the model from its own credential store, so a working model warns forever. | `amicus models --refresh` and watch for a provider that stays empty; re-save the good key with `amicus key <provider> <apikey>`. See [docs/troubleshooting.md](./docs/troubleshooting.md#model-x-is-unverified-against-the-direct-catalog-attempting-anyway). |
 | Session not found | No session matches the given ID | Run `amicus list`, or omit `--session-id` to use the most recent. |

package/docs/configuration.md

@@ -137,6 +137,22 @@ Legacy `SIDECAR_IDLE_TIMEOUT*` names were removed in v2.0.0 — rename to the `A
 
 Set `AMICUS_IDLE_TIMEOUT=0` to disable self-termination entirely.
 
+### Server startup
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `AMICUS_SERVER_START_TIMEOUT_MS` | How long to wait for OpenCode to report it is listening before treating the start as failed. | `30000` on Windows, `15000` elsewhere |
+
+A start that exceeds this window is treated as **transient** and retried on the same bounded schedule as an OpenCode database lock race (5 attempts, 250/500/1000/2000 ms), because retrying costs nothing but the backoff while a failed start costs a whole review seat.
+
+Raise it if you see `Timeout waiting for server to start` on a slow box — a project directory on a sync-backed volume (OneDrive, Dropbox) with an antivirus scanner attached can push a cold OpenCode/SQLite start well past the default. Values of `0` or below are ignored rather than honored, since a zero start timeout fails every start instantly.
+
+To see how much headroom you actually have, run with `LOG_LEVEL=debug` and look for the `OpenCode server started` line — it reports both `startMs` (what the start took) and `timeoutMs` (the ceiling it ran against):
+
+```json
+{"level":"debug","msg":"OpenCode server started","startMs":561,"timeoutMs":30000}
+```
+
 ### Shared server
 
 The shared-server mode (`AMICUS_SHARED_SERVER=1`, which is the default) lets multiple Amicus sessions reuse a single OpenCode Go binary process rather than spawning one per invocation, eliminating cold-start latency on the second and subsequent calls. Disable it with `AMICUS_SHARED_SERVER=0` if you need per-process isolation or are diagnosing a crash loop.

package/docs/usage.md

@@ -443,7 +443,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -77,6 +77,7 @@
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@opencode-ai/sdk": "^1.1.36",
     "dotenv": "^17.2.3",
+    "extract-zip": "^2.0.1",
     "opencode-ai": "^1.2.20",
     "tiktoken": "^1.0.0",
     "update-notifier": "^7.3.1",
@@ -93,7 +94,7 @@
     "jest": "^29.0.0",
     "lint-staged": "^16.3.2",
     "puppeteer": "^24.36.0",
-    "sharp": "^0.33.5",
+    "sharp": "^0.35.3",
     "ws": "^8.19.0"
   },
   "engines": {

package/schemas/council-verdict.schema.json

@@ -4,53 +4,207 @@
   "title": "amicus council-verdict document",
   "description": "Verdict record (`council verdict --json`, amicus_verdict, verdict.json). overallVerdict is the chair's parsed VERDICT line — null in every Stage-4 manual path, populated by the headless engine.",
   "type": "object",
-  "required": ["schemaVersion", "type", "runId", "council", "overallVerdict", "findings", "streetCred", "runStats", "tierCounts"],
+  "required": [
+    "schemaVersion",
+    "type",
+    "runId",
+    "council",
+    "overallVerdict",
+    "findings",
+    "streetCred",
+    "runStats",
+    "tierCounts"
+  ],
   "properties": {
-    "schemaVersion": { "const": 2 },
-    "type": { "const": "council-verdict" },
-    "runId": { "type": "string" },
-    "runType": { "type": ["string", "null"] },
-    "date": { "type": ["string", "null"] },
-    "chair": { "type": ["string", "null"] },
-    "council": { "type": "array", "items": { "type": "string" } },
-    "claudeInCouncil": { "type": "boolean" },
+    "schemaVersion": {
+      "const": 2
+    },
+    "type": {
+      "const": "council-verdict"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "runType": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chair": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "council": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "claudeInCouncil": {
+      "type": "boolean"
+    },
     "overallVerdict": {
       "oneOf": [
-        { "enum": ["Ship it", "Fix these first", "Fundamental rethink"] },
-        { "type": "null" }
+        {
+          "enum": [
+            "Ship it",
+            "Fix these first",
+            "Fundamental rethink"
+          ]
+        },
+        {
+          "type": "null"
+        }
       ]
     },
     "findings": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "tier", "decision", "applied"],
+        "required": [
+          "id",
+          "tier",
+          "decision",
+          "applied"
+        ],
         "properties": {
-          "id": { "type": "string" },
-          "raiser": { "type": ["string", "null"] },
-          "severity": { "type": ["string", "null"] },
-          "tier": { "enum": ["Confirmed", "Contested", "Singleton", "Disputed"] },
-          "basis": { "type": "object" },
-          "confidence": { "enum": ["thin", "solid"] },
-          "tierOverride": { "type": ["object", "null"] },
-          "duplicateOf": { "type": ["string", "null"] },
-          "adjudications": { "type": "array" },
-          "decision": { "type": ["string", "null"] },
-          "applied": { "type": "boolean" },
+          "id": {
+            "type": "string"
+          },
+          "raiser": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "severity": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "tier": {
+            "enum": [
+              "Confirmed",
+              "Contested",
+              "Singleton",
+              "Disputed"
+            ]
+          },
+          "basis": {
+            "type": "object"
+          },
+          "confidence": {
+            "enum": [
+              "thin",
+              "solid"
+            ]
+          },
+          "tierOverride": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "duplicateOf": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "adjudications": {
+            "type": "array"
+          },
+          "decision": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "applied": {
+            "type": "boolean"
+          },
           "debate": {
             "type": "object",
             "properties": {
-              "action": { "enum": ["defended", "amended", "withdrawn", "no-response"] },
-              "previousTier": { "type": ["string", "null"] }
+              "action": {
+                "enum": [
+                  "defended",
+                  "amended",
+                  "withdrawn",
+                  "no-response"
+                ]
+              },
+              "previousTier": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
             },
-            "required": ["action"],
+            "required": [
+              "action"
+            ],
             "additionalProperties": false
           }
         }
       }
     },
-    "streetCred": { "type": "array", "items": { "type": "object" } },
-    "runStats": { "type": "array", "items": { "type": "object" } },
-    "tierCounts": { "type": "object" }
+    "streetCred": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "runStats": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "tierCounts": {
+      "type": "object"
+    },
+    "seatLoss": {
+      "type": "object",
+      "description": "Present only when --critic was requested. Records whether the adversarial seat actually reviewed: a dead critic wave is survivable (the quorum gate guards only the bench), so a run can otherwise reach a full verdict with the critic silently absent.",
+      "properties": {
+        "criticRequested": {
+          "type": "string",
+          "description": "The model asked for as critic."
+        },
+        "criticSeated": {
+          "type": "boolean",
+          "description": "False when the critic wave died before producing legs."
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Why the critic wave died, when it did."
+        },
+        "deadBenchSeats": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Bench models lost to dead waves, excluding the critic."
+        }
+      },
+      "required": [
+        "criticRequested",
+        "criticSeated"
+      ]
+    }
   }
 }

package/src/council/run-assemble.js

@@ -19,7 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
-const { buildVerdict, writeVerdictAtomic } = require('./verdict');
+const { buildVerdict, summarizeSeatLoss, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
 const { validateFindings } = require('./findings');
 const { toGlobalFindings } = require('./anonymize');
@@ -178,8 +178,12 @@ function writeTallyFiles({ runDir, tallyInput, record }) {
  * buildVerdict's own signature.
  * @returns {object} the verdict written to disk
  */
-function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
-  const verdict = buildVerdict(record, []);
+function writeVerdictFiles({ runDir, record, overallVerdict, chairText, critic, deadWaves }) {
+  // v4.5.2 — computed here rather than in run.js so verdict assembly stays in
+  // one place; see summarizeSeatLoss in ./verdict for why a lost critic has to
+  // reach the verdict at all.
+  const seatLoss = summarizeSeatLoss({ runId: record.meta.runId, critic, deadWaves });
+  const verdict = buildVerdict(record, [], { seatLoss });
   verdict.overallVerdict = (overallVerdict === undefined) ? null : overallVerdict;
   writeVerdictAtomic(path.join(runDir, 'verdict.json'), verdict);
   const html = buildReport({ verdict }, { format: 'html' });

package/src/council/run.js

@@ -284,7 +284,8 @@ async function runCouncil(options, deps = {}) {
     runState.updateStage(o.runDir, tallyStage, { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, tallyStage, null, o.follow);
     emitStageTerminal(o.runDir, o.runId, tallyStage, 'complete', null, o.follow);
-    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
+    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText,
+      critic: o.critic, deadWaves });
     runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, 'verdict', null, o.follow);
     emitStageTerminal(o.runDir, o.runId, 'verdict', 'complete', null, o.follow);

package/src/council/verdict.js

@@ -16,6 +16,44 @@ const VERDICT_SCHEMA_VERSION = 2;
  * @param {{overallVerdict?: (string|null)}} [opts] engine hook (Plan B): the
  *   parsed chair `VERDICT:` line; omitted/undefined → null.
  */
+/**
+ * Describe which requested seats actually reviewed, for the verdict's own face.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. The critic is a SOLO wave with one leg,
+ * so losing it loses 100% of the adversarial role — and unlike a dead bench wave
+ * (which trips the quorum gate and fails the run loudly) a dead critic is
+ * survivable, so the run continues to a full verdict, tally and chair synthesis
+ * that never saw the critic's findings. Run `dfb6a692` did exactly that and the
+ * only record was `deadWaves` in run.json, a file nobody opens when the verdict
+ * reads clean. A user who typed `--critic` asked for adversarial review; a
+ * verdict produced without it must say so where the verdict is read.
+ *
+ * Returns null when no critic was requested — there is nothing to report, and an
+ * always-present block would train readers to ignore it.
+ *
+ * @param {{runId: string, critic: ?string,
+ *   deadWaves: Array<{waveId: string, models: string[], reason: string}>}} o
+ * @returns {?{criticRequested: string, criticSeated: boolean, reason: ?string,
+ *   deadBenchSeats: string[]}}
+ */
+function summarizeSeatLoss({ runId, critic, deadWaves = [] } = {}) {
+  if (!critic) { return null; }
+  // Match on EITHER carrier. The `-c1` suffix is the convention run-stages.js
+  // uses, but a wave that names the critic model is the critic wave whatever it
+  // is called — and relying on the id alone would silently under-report if that
+  // convention ever changes.
+  const isCriticWave = w =>
+    w.waveId === `${runId}-c1` || (w.models || []).includes(critic);
+  const dead = deadWaves.find(isCriticWave) || null;
+  return {
+    criticRequested: critic,
+    criticSeated: !dead,
+    reason: dead ? dead.reason : null,
+    deadBenchSeats: deadWaves.filter(w => !isCriticWave(w))
+      .flatMap(w => w.models || []),
+  };
+}
+
 function buildVerdict(record, decisions = [], opts = {}) {
   const byId = new Map(decisions.map(d => [d.id, d]));
   return {
@@ -46,6 +84,9 @@ function buildVerdict(record, decisions = [], opts = {}) {
     streetCred: record.streetCred.map(s => ({ model: s.model, withSelf: s.withSelf, peersOnly: s.peersOnly })),
     runStats: record.runStats,
     tierCounts: record.tierCounts,
+    // Additive and OPTIONAL (schemaVersion stays 2): present only when a critic
+    // was requested, so its absence never has to be interpreted.
+    ...(opts.seatLoss ? { seatLoss: opts.seatLoss } : {}),
   };
 }
 
@@ -93,4 +134,6 @@ function writeVerdictAtomic(filePath, verdict) {
   fs.renameSync(tmp, filePath);
 }
 
-module.exports = { buildVerdict, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION };
+module.exports = {
+  buildVerdict, summarizeSeatLoss, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION,
+};

package/src/headless.js

@@ -272,6 +272,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       if (options.mcp) {
         serverOptions.mcp = options.mcp;
       }
+      // v4.5.2: explicit per-call override only — see the note at the matching
+      // hop in src/sidecar/session-utils.js. The default and the env knob both
+      // resolve downstream in buildServerOptions.
+      if (options.timeout !== undefined) {
+        serverOptions.timeout = options.timeout;
+      }
       // v4.4.1 fix wave (F5): this is the OTHER server-start site. It calls
       // startServer directly rather than going through startOpenCodeServer, so
       // the lock-class retry added for the concurrent-start race never covered

package/src/opencode-client.js

@@ -402,11 +402,67 @@ async function getSessionStatus(client, sessionId, directory) {
   return result.data || {};
 }
 
+/**
+ * How long to wait for OpenCode to announce it is listening, per platform.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. `@opencode-ai/sdk` defaults this to
+ * 5000ms (`dist/server.js:4-8`) and lets the caller override it; amicus never
+ * passed one, so every start on every platform ran on the SDK's 5s — untunable
+ * and invisible to `amicus doctor`. A reporter's Windows box (project on a
+ * OneDrive-synced volume, Defender active) blew through it on a cold
+ * OpenCode/SQLite open: the council's shared server failed to acquire, the run
+ * degraded to the per-wave configuration `src/council/run-server.js` exists to
+ * eliminate, and the whole Stage-1 bench died (`COUNCIL_QUORUM: Only 0 …`).
+ *
+ * The asymmetry decides the number: a slow start costs LATENCY, a failed start
+ * costs a REVIEW SEAT. win32 gets the widest window because that is where
+ * sync-backed volumes and always-on AV filter drivers are the norm.
+ *
+ * This is a ceiling, not a sleep — a healthy start still resolves in well under
+ * a second and pays none of it.
+ */
+const SERVER_START_TIMEOUT_MS = Object.freeze({ win32: 30000, default: 15000 });
+
+/**
+ * Resolve the start timeout: explicit option → env override → platform default.
+ *
+ * `0` and negatives are REJECTED rather than honored. For most amicus knobs `0`
+ * is a documented disable switch (see src/utils/env-num.js), but a 0ms start
+ * timeout disables nothing — it fails every start instantly. That is an own-goal
+ * an operator can only reach by accident, so it falls back to the default.
+ *
+ * @param {object} [options] - Server options ({timeout} respected if positive)
+ * @param {object} [env] - Environment (test seam; defaults to process.env)
+ * @param {string} [platform] - Platform (test seam; defaults to process.platform)
+ * @returns {number} milliseconds
+ */
+function resolveServerStartTimeoutMs(options = {}, env, platform) {
+  const plat = platform || process.platform;
+  const dflt = SERVER_START_TIMEOUT_MS[plat] || SERVER_START_TIMEOUT_MS.default;
+  const positive = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+  if (options.timeout !== undefined) {
+    const explicit = positive(options.timeout);
+    if (explicit) { return explicit; }
+  }
+  const raw = (env || process.env).AMICUS_SERVER_START_TIMEOUT_MS;
+  if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+    const fromEnv = positive(raw);
+    if (fromEnv) { return fromEnv; }
+  }
+  return dflt;
+}
+
 /**
  * Build the server options object for createOpencodeServer.
  * Extracted for testability (no SDK dependency).
  *
  * @param {object} [options] - Server options
+ * @param {number} [options.timeout] - Start timeout in ms. Omit to use
+ *   AMICUS_SERVER_START_TIMEOUT_MS or the platform default; NEVER omitted from
+ *   the object handed to the SDK, so the SDK's own 5000ms default is unreachable.
  * @param {number} [options.port] - Port to run on
  * @param {string} [options.hostname='127.0.0.1'] - Hostname to bind to
  * @param {AbortSignal} [options.signal] - Abort signal to stop server
@@ -544,6 +600,9 @@ function buildServerOptions(options = {}) {
 
   const serverOptions = {
     hostname: options.hostname || '127.0.0.1',
+    // ALWAYS set — unlike port/signal below, an omitted timeout is not a
+    // harmless "let the SDK decide", it is the 5000ms that cost a bench.
+    timeout: resolveServerStartTimeoutMs(options),
   };
 
   // Only include port/signal when explicitly set — passing undefined
@@ -660,11 +719,27 @@ async function startServer(options = {}) {
     }
   }
 
-  const createOpencodeServer = await getCreateOpencodeServer();
+  // `_createOpencodeServer` is a test seam, matching `_hasOpencodeBinary` /
+  // `_ensureEngine` / `_opencodeRoots` above: the SDK arrives through a dynamic
+  // `import()`, which `jest.mock` cannot intercept under CommonJS, so the start
+  // path is otherwise unreachable from a unit test.
+  const createOpencodeServer = options._createOpencodeServer
+    || await getCreateOpencodeServer();
   const serverOptions = buildServerOptions(options);
 
+  // Measure the healthy path. The v4.5.2 timeout had to be sized from the
+  // asymmetry of the failure (a slow start costs latency, a failed one costs a
+  // review seat) because nothing recorded how long a GOOD start takes — so the
+  // margin against the ceiling was unmeasurable on exactly the slow boxes that
+  // needed it. Now it is one debug line, not an inference.
+  const startedAt = Date.now();
   const sdkServer = await createOpencodeServer(serverOptions);
-  const client = await createClient(sdkServer.url);
+  const { logger } = require('./utils/logger');
+  logger.debug('OpenCode server started', {
+    startMs: Date.now() - startedAt,
+    timeoutMs: serverOptions.timeout,
+  });
+  const client = await (options._createClient || createClient)(sdkServer.url);
 
   // Capture the Go server PID once so close() can force-kill it cross-platform
   // (F3 #15). Prefer a PID the SDK exposes; fall back to the port listener.
@@ -822,6 +897,8 @@ module.exports = {
   abortSession,
   checkHealth,
   buildServerOptions,
+  resolveServerStartTimeoutMs,
+  SERVER_START_TIMEOUT_MS,
   buildServerHandle,
   startServer,
   loadMcpConfig,

package/src/sidecar/session-utils.js

@@ -253,6 +253,10 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
+  // Explicit per-call override only. Unset is the normal case and is correct:
+  // buildServerOptions resolves AMICUS_SERVER_START_TIMEOUT_MS / the platform
+  // default downstream, so forwarding `undefined` here would change nothing.
+  if (options.timeout !== undefined) { serverOptions.timeout = options.timeout; }
 
   // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
   // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).

package/src/sidecar/unzip.js

@@ -173,7 +173,22 @@ async function robustExtract(zip, opts = {}) {
     deps = {},
   } = opts;
   const fs = deps.fs || fsDefault;
-  const extractZip = deps.extractZip || require('extract-zip');
+  // GUARDED (v4.5.2). This `require` used to be bare, and `extract-zip` was
+  // never declared in dependencies — it resolved in the dev tree only because
+  // `puppeteer` (a devDependency) pulls it transitively, so a published install
+  // threw MODULE_NOT_FOUND here and took the WHOLE function with it: the native
+  // fallback below, the bounded idle/max timers, and `doctor --fix` all became
+  // unreachable. The dependency is now declared, so this should never fire —
+  // but Strategy 1 being unavailable is precisely what the native strategies
+  // exist for, so it must degrade into them rather than out of the function.
+  let extractZip = deps.extractZip;
+  if (!extractZip) {
+    try {
+      extractZip = require('extract-zip');
+    } catch (e) {
+      extractZip = () => { throw new Error(`extract-zip unavailable: ${e.message}`); };
+    }
+  }
   const spawn = deps.spawn || spawnSync;
   const setTimer = deps.setTimeout || setTimeout;
   const clearTimer = deps.clearTimeout || clearTimeout;

package/src/utils/server-setup.js

@@ -89,6 +89,28 @@ function ensurePortAvailable(port = DEFAULT_PORT) {
  */
 const LOCK_CLASS_START_FAILURE = /database is locked|database table is locked|SQLITE_BUSY/i;
 
+/**
+ * A start failure that is a TIMEOUT, not a deterministic error.
+ *
+ * `@opencode-ai/sdk` rejects with `Timeout waiting for server to start after
+ * ${timeout}ms` when OpenCode has not printed its listening line inside the
+ * caller-supplied window (SDK default: 5000ms — see AMICUS_SERVER_START_TIMEOUT_MS
+ * in src/opencode-client.js for why amicus no longer accepts that default).
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. A start timeout is TRANSIENT — a cold
+ * SQLite open on a sync-backed volume with an AV scanner attached simply takes
+ * longer than the window — and is therefore *more* retryable than a lock race,
+ * since retrying costs nothing but the backoff. Before this, it matched no
+ * alternative in LOCK_CLASS_START_FAILURE and so fell straight through
+ * `retryOnLockRace` with ZERO retries. A reporter's council degraded to per-wave
+ * servers on this error and then lost its entire Stage-1 bench
+ * (`COUNCIL_QUORUM: Only 0 Stage-1 review(s) survived`).
+ *
+ * Deliberately anchored to "…server to start". A REQUEST timeout, an ETIMEDOUT
+ * connect, and a generic "timeout" are NOT this class and must not sleep here.
+ */
+const TIMEOUT_CLASS_START_FAILURE = /Timeout waiting for server to start/i;
+
 /**
  * Backoff between start attempts; 5 attempts total, ≤3.75s of added latency.
  *
@@ -109,12 +131,48 @@ const LOCK_RETRY_DELAYS_MS = [250, 500, 1000, 2000];
  * @returns {boolean} true only for a lock-class (retryable) start failure
  */
 function isLockClassStartFailure(error) {
+  return matchesStartFailure(error, LOCK_CLASS_START_FAILURE);
+}
+
+/**
+ * @param {Error|null} error
+ * @returns {boolean} true only for a timeout-class (retryable) start failure
+ */
+function isTimeoutClassStartFailure(error) {
+  return matchesStartFailure(error, TIMEOUT_CLASS_START_FAILURE);
+}
+
+/**
+ * The union the retry actually applies to: lock-class OR timeout-class.
+ *
+ * Kept separate from the two predicates so each class keeps its own narrow,
+ * accurate meaning — `isLockClassStartFailure` still answers "was this a lock
+ * race?" and nothing else, so its docblock does not quietly become a lie.
+ *
+ * @param {Error|null} error
+ * @returns {boolean} true for any transient (retryable) start failure
+ */
+function isRetryableStartFailure(error) {
+  return isLockClassStartFailure(error) || isTimeoutClassStartFailure(error);
+}
+
+/**
+ * Test `pattern` against every carrier an error might arrive on.
+ *
+ * The real failure arrives as a message with the server's own stdout inlined
+ * ("Server exited with code 1 / Server output: … database is locked"), and
+ * amicus prefixes it again at the fanout boundary (`Failed to start server:
+ * …`), so check the usual carriers too — a wrapped/spawn-shaped error still
+ * has to match.
+ *
+ * @param {Error|null} error
+ * @param {RegExp} pattern
+ * @returns {boolean}
+ */
+function matchesStartFailure(error, pattern) {
   if (!error) { return false; }
-  // The real failure arrives as a message with the server's own stdout inlined
-  // ("Server exited with code 1 / Server output: … database is locked"), but
-  // check the usual carriers too so a wrapped/spawn-shaped error still matches.
   const carriers = [error.message, error.stderr, error.stdout, error.cause && error.cause.message];
-  return carriers.some(c => typeof c === 'string' && LOCK_CLASS_START_FAILURE.test(c));
+  return carriers.some(c => typeof c === 'string' && pattern.test(c));
 }
 
 /**
@@ -141,9 +199,16 @@ async function retryOnLockRace(attempt, opts = {}) {
     try {
       return await attempt(i);
     } catch (error) {
-      if (i >= delays.length || !isLockClassStartFailure(error)) { throw error; }
-      logger.warn('OpenCode server start lost a lock race — retrying', {
-        attempt: i + 1, of: delays.length + 1, delayMs: delays[i], error: error.message,
+      if (i >= delays.length || !isRetryableStartFailure(error)) { throw error; }
+      logger.warn('OpenCode server start failed transiently — retrying', {
+        attempt: i + 1,
+        of: delays.length + 1,
+        delayMs: delays[i],
+        // Name WHICH transient class fired: a run that retried on `timeout`
+        // wants a bigger AMICUS_SERVER_START_TIMEOUT_MS, one that retried on
+        // `lock` wants less concurrency. Same retry, different operator action.
+        failureClass: isLockClassStartFailure(error) ? 'lock' : 'timeout',
+        error: error.message,
       });
       await new Promise(resolve => setTimeout(resolve, delays[i]));
     }
@@ -158,5 +223,7 @@ module.exports = {
   killPortProcess,
   ensurePortAvailable,
   isLockClassStartFailure,
+  isTimeoutClassStartFailure,
+  isRetryableStartFailure,
   retryOnLockRace
 };