amicus 4.4.0 → 4.4.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "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,38 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.4.1] - 2026-07-27
+
+A fast-follow patch on 4.4.0. Every item is a correction to something already shipped, and almost all of it was measured against real paid council runs rather than reasoned about — the five gate councils that certified the Council Workspace are also what found these. Five behaviour changes ride along and are called out under **Changed**, because a user upgrading a patch should not discover them by surprise.
+
+### Fixed
+
+- **The repair path is whole for the first time.** 4.4.0 gave the Stage-1 findings repair the review it was repairing; the judge, chair, defense and re-vote repair prompts carried the identical omission, and `buildChairRepairPrompt` took no arguments at all. A repair leg is a *fresh* session with no memory of the turn it is repairing, so shipping only the validation errors asked a model to correct something it had never seen. **Three of the five paid gate councils burned a seat on it:** `wsgate02`'s `qwen` and `wsgate04`'s `glm` each refused twice ("I don't have a previous review to correct"), so a 4-model bench silently adjudicated on 3 while still paying for the fourth; `costgate01`'s `grok` complied instead — by **inventing a self-referential finding about its own empty output**, which entered `tally.json`, the street-cred rankings, the chair synthesis, and a human's decision. Every repair call site now embeds the text that actually failed, verbatim and uncapped, tracked across attempts so the errors and the artifact always describe the same generation. Separately, a repair that **silently changes the finding count is now refused** rather than adjudicated: the repair contract is "the same findings, fixed", and a count change is exactly the fabrication shape above. Where the original block was absent or unparseable there is no count to compare, so the repair is accepted but marked `findingsUnverified` rather than implying a check happened. A repair's output never replaces the review's prose — that would hand the judges a narrative-free review and put a JSON dump in the Stage-2 bundle.
+- **Three of four seats on a paid council were silently truncated by the fence extractor.** The closing-fence pattern was unanchored, so the **first triple-backtick anywhere inside a JSON body ended the match** — and a review *of markdown* inevitably quotes a fence. On the $1.95 renderer-review council, `glm`, `opus` and `minimax` all came back `NOT_PARSEABLE` and collapsed to `conformance: unstructured`; replayed against the same artifacts after the fix they yield 6, 5 and 4 findings respectively. **15 of 17 findings were lost or left to a paid repair wave to rescue, and the chair synthesised from the two that survived without knowing the rest existed.** The extractor now enumerates every fenced opener independently, reads each one both ways (close-at-line-start primary, same-line close as fallback), and lets **`JSON.parse` arbitrate** — the last opener whose body actually parses wins. This is the repo's only fence extractor and all five consumers funnel through it, so judge, debate-defense and re-vote parsing carried the identical defect and are fixed by the same change; each now has its own test so a future re-implementation cannot regress one silently. The malformed-versus-absent distinction is preserved deliberately: a cut-off emit that never closed at all is still *absent*, because the repair path answers "no findings block" and "a broken findings block" differently.
+- **A council run no longer races itself for OpenCode's database.** A run started a fresh OpenCode server for the Stage-1 seat wave, the critic solo, each findings repair, the Stage-2 judge wave, each judge repair, each debate wave and the chair chain — 10+ spawns, each one a fresh chance to lose OpenCode's SQLite startup race. Stage 1 launches its seat wave and its critic solo under one `Promise.all`, so two of those starts are ~140 ms apart *by construction*: one run **lost four of five seats in 736 ms** to `database is locked` and failed quorum, which is what made `--critic` a coin flip. A run now acquires **one** server and forwards it into every launch, closed once on the single path every terminal outcome already funnels through. It never fails closed — a shared server that will not start is a notice, and the run falls back to one server per wave exactly as before. The Stage-2 anonymization boundary was verified rather than assumed: judges run in the run's `_scratch` directory and scoping is per-call, so nothing about it ever lived in the server process. Separately, a **lock-class** start failure (`database is locked`, `database table is locked`, `SQLITE_BUSY` — and nothing else) is now retried 3 times over ≤750 ms, which covers the races a single process cannot remove: two amicus processes, or a CLI run beside a live MCP server. A missing binary, an auth failure, a port conflict and a failed health check are deterministic and fall straight through rather than tripling the latency before the same error.
+- **`amicus spend` stopped reporting a total that `council run` calls inexact.** A leg whose spawned subagent could not be accounted for wrote a **priced** ledger row, so `unpricedRows` never caught it and the product's two truthfulness surfaces disagreed about the same dollars. Such a row now carries the flag and is counted as `unattributedSubtreeRows` **beside — never instead of —** `unpricedRows`, since a row can be both; the human table gains a second, distinctly worded line, because "we could not see this leg at all" and "we saw this leg but not what it spawned" are different facts. The MCP `amicus_spend` tool inherits it unchanged. And the unknown-spend notice is no longer **sticky**: it guarded on a boolean, so the first unknown leg was announced and every one created afterwards — Stage 2, repairs, debate, chair — was silently swallowed. It now re-announces on a growing count, and says "so far this run" rather than repeating a cumulative number as if it were new.
+- **A leg observed only through cache tokens reports `unknown`, not a falsely free `$0`.** The observation gate accepted `cacheRead`/`cacheWrite`/`reasoning`, but the estimate prices `input`/`output` only — so a leg observed in neither passed the gate and resolved to `estimated $0.0000`, the same authoritative false zero 4.4.0 exists to eliminate, in the one corner its predicate did not cover. The v4.2 free-local `$0` tier is untouched: a real local seat reports genuine token counts and still resolves to `estimated ~$0.0000`.
+- **A leg that both fell back to another model and left an unattributable subtree no longer reports `costExact: true`.** Folding a leg's attempts together returned a bare `{tokens, cost}` and dropped the subtree flag, so `run.json` claimed a complete total for a number that was a floor. The fold now preserves every key: the flag ORs across attempts (a gap admitted once cannot be erased by a later clean attempt) and a measured subtree sums rather than last-wins. Separately, the spend reader promised to skip corrupt ledger lines but let a valid-JSON *scalar* through as a row, inflating both `runs` and `unpricedRows`.
+- **A failed leg no longer renders as complete in the Council Workspace.** A seat that errored or timed out could show a green check, because `timed-out` was missing from the terminal-state lists the mirror consults. Alongside it: the leg-role guard is now symmetric, a leg that throws writes a terminal progress record instead of leaving its last live one as the final word, and swallowed read failures are logged rather than discarded.
+- **A permission failure is no longer reported as "not written yet".** An unreadable run artifact was indistinguishable from one the run had not produced yet, which had been producing a **silent chairless fold reporting `{ok: true}`** — the fold said it succeeded and carried no verdict. Three dead fallbacks and an unwired `legsTotal`/`legsComplete` pair were deleted in the same pass: a documented field that is never populated is worse than no field.
+- **A Stage-1 wave that dies before its legs start no longer leaves the run looking healthy.** Such a wave wrote no `wave.json` at all, so nothing downstream could tell "the wave failed" from "the wave has not reported yet"; it now degrades the run loudly. A shared-server acquisition that fails likewise degrades loudly instead of silently, and its **success** is recorded too — previously only the failure was.
+- **The `haiku` alias was never broken.** It hard-404'd 3 of 3 times across two paid councils — as chair (twice, including the fallback retry) and as a bench seat, ~2 s and zero tokens each — and the standing diagnosis was a rotten model id. It is not: the cause is an `ANTHROPIC_BASE_URL` without its `/v1` suffix, an **environment** misconfiguration. Documented as such, because the prescribed "fix or remove the alias" would have deleted a working route. The more useful half of the lesson stands unchanged from 4.4.0: a dead alias does not stop a council, it shrinks one.
+- **Renderer and markdown robustness.** The workspace's markdown renderer no longer re-slices its input on every inline token (identical output on 219,543 verified inputs — exhaustive to length 6 plus 200,000 fuzz cases — removing a dependence on a V8 string-representation detail nothing stated or tested); heading text is trimmed rather than baking trailing blanks into a text node; and an unreachable heading-level clamp is gone, pinned so a future widening fails loudly instead of silently emitting an `<h7>`.
+
+### Changed
+
+- **A review that honestly finds nothing is now a valid review.** An empty finding set was a hard error, which structurally pressured a model to invent a finding — directly contradicting the anti-sycophancy clause shipped in every Stage-1 briefing, and `costgate01`'s `grok` did exactly that, reaching a human's decision. A **present-but-empty** `findings` array with a non-empty `overall` now validates. The lines that already existed are preserved: a broken emit keeps its own codes, an empty set with a blank or missing `overall` is still an error, and a *missing* `findings` key is still an error — only an array that is present and empty means "I read it and found nothing". The briefing now says what the validator enforces, which also makes the repair prompt's "emit an empty findings array and say so" branch describe an answer that can actually pass rather than a trap costing two paid legs. Downstream, an all-clean bench degrades gracefully: Stage 2 still runs (peer ranking, and therefore street-cred, is unaffected by an empty findings pool), and the judge bundle and chair packet **state** the empty index instead of rendering a heading over nothing under an order to adjudicate ids that do not exist — an instruction a judge obeying it answers by inventing an id, which buys up to two paid repair solos per judge. The debate stage is genuinely skipped and already records its reason. **This changes what a council means when every seat comes back clean.**
+- **A leg that exceeds the tool-settle grace ceiling now has its OpenCode session aborted.** 4.4.0 bounded the wait and completed the leg anyway; it left the underlying session running and **billing** for output nobody would read. The leg's completion and partial output are unchanged — only the session is stopped, after the child-session walk so subtree attribution survives, and before the server closes, since on a shared server (i.e. every council run) the server is not closed here at all — which is precisely the pathological case. Whether the abort landed rides the result, the terminal `progress.json` and the leg's `metadata.json` as `toolSettleAborted`, and it is recorded as `false` when the abort was attempted and failed rather than omitted: "we tried to stop it and could not; it may still be billing" is the useful half of that signal. A failed or hung abort can never alter a leg that already succeeded.
+- **A run under a `--max-cost` ceiling now exits `2` when its own total is inexact.** A fully-unpriced council could never trip the ceiling, so a ceiling silently bounded nothing while the run exited `0` — an unqualified success for a number the run itself was reporting as a floor. When a ceiling is set *and* the total is inexact, the run now exits `2`, through the same degraded path a budget-refused wave already uses; a signal and a real error are never re-labelled. **The ceiling still never blocks a run** and still trips on **known** spend only — a fully-unpriced bench under a $0.01 ceiling runs every stage to completion. The docs now say "`--max-cost` bounds **known** spend", which is what it has always done. Anything gating on `council run`'s exit status should expect `2` where it previously saw `0` on an inexact run.
+- **`amicus watch <id> --ui` now validates the run id.** A malformed id skipped validation entirely and surfaced whatever the run lookup produced — a vaguer error than the identical typo gets on the terminal path. It now **exits `1` with the validator's message instead of launching the workspace**. Bare `amicus watch --ui` still opens the project run-list landing; the check applies only when an id is actually supplied.
+- **`npm i -g amicus` now installs the documentation.** The package's `files[]` excluded `docs/` entirely, so every word of documentation was unreachable from an install — and the moment a user most needs troubleshooting text already on disk is an opaque `Not Found` with zero tokens, which is exactly when they have no reason to trust a browser tab instead. The 15 top-level `docs/*.md` pages now ship (**+15 files, 285 → 300; +93 KB packed, +8.8%**). Images and the plan/spec archive deliberately do not — ~425 KB with no offline value. A handful of roadmap references point at repo working files that still do not ship; they are now labelled as such rather than reading as broken paths.
+- **The fold's `Cost:` line stops saying the same thing twice.** It appended the source name on top of a glyph that already encoded the same fact, printing `~$0.0100 (estimated)` and `? (unknown)`. Those two words are gone — `~` already means inexact and a bare `?` already means unknown. Two sources keep their word because the glyph vocabulary cannot express them: **`reported`**, since a plain `$0.4321` is also what an unrecognised source renders as, so the absence of a glyph cannot mean "exact"; and **`mixed`**, since `~` says *inexact* without saying *which kind* — collapsing `mixed` to a bare `~$…` makes it indistinguishable from `estimated`, and the two are not the same claim. `mixed` asserts that part of the number is genuinely measured.
+
+### Security
+
+- **The Council Workspace's markdown renderer has finally been reviewed by a bench.** The component that turns **another model's prose into DOM** was in none of the five gate councils' review sets and shipped in 4.4.0 uncertified; one chair called that out explicitly and rated it blocking, while another cleared the same file by reading its *consumers* rather than the file. A paid council was run against the file itself. **It found nothing exploitable** — no DOM injection (`textContent`/`createTextNode` only, fixed tag names, no HTML parsing of model-controlled content) and no prototype pollution — and the findings it did raise are architectural, fixed above under **Fixed**. The certification is recorded here rather than in a working note because the disagreement it settles was a public one. Its adversarial coverage is now pinned: prototype-pollution inertness, `javascript:`/`data:` URL inertness, malformed and unmatched inline backticks, the resource budget at exactly the artifact-size cap under both pathological shapes, and a widened attribute-sink guard — the previous banned-token scan covered four HTML-string APIs and would **not** have caught `setAttribute('href', userText)`, with a negative control proving the guard is not vacuous. Two rendering-fidelity findings were surfaced and deliberately not fixed; neither is a security property.
+- **The Council Workspace's read-only posture is now enforced rather than asserted.** That the workspace never writes into a run directory was checked nowhere. It now is, by a guard that **parses** rather than greps: these files are dense with prose *about* writes, and a text scan that goes red for a comment gets weakened rather than fixed, so the guard builds an AST (comments are structurally absent from it) and matches string literals by exact equality. It pins that no write API appears in the workspace source, that the registered IPC channel set is **exactly** the seven known channels — so a new channel cannot be added without being classified — and that the one verb which legitimately writes, Abort, **delegates** to the engine's own abort path rather than writing itself. A positive control scans the engine's own writer and requires it to come back dirty, so a broken scan cannot pass by finding nothing. The Workspace's CSP likewise gains a real regression guard: "no violations" is also what a *loosened* policy produces, so the check now appends an inline `<script>` and requires the refusal to appear.
+
 ## [4.4.0] - 2026-07-26
 
 ### Added

package/README.md

@@ -351,7 +351,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -462,6 +462,8 @@ Run `amicus doctor` first — it checks keys, catalog, OpenCode binary, Electron
 | 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. |
+| 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. |
 | No conversation history found | Project-path encoding | Check `~/.claude/projects/`; `/` and `_` in the project path are encoded as `-` in the directory name. |
 | Headless run never finishes | Task is bigger than the default timeout | Raise it: `--timeout 30`. |

package/docs/DISTRIBUTION.md

@@ -0,0 +1,234 @@
+# Distribution channels
+
+Amicus ships through three channels. This doc is the runbook for each — what's
+live today, what the submission/publish steps are, and what to check before
+pulling the trigger on a release-facing action.
+
+## 1. npm (existing)
+
+**Status: live.** Tag `v*` on `main` → `.github/workflows/publish.yml` → npm
+**Trusted Publishing** (GitHub OIDC, no long-lived npm token in CI) →
+`npm publish --access public --provenance`. The workflow also cuts a GitHub
+Release and asks Claude to draft categorized release notes from the commit
+log + diff since the previous tag.
+
+Postinstall (`scripts/postinstall.js`) registers the MCP server in Claude
+Code / Claude Desktop / Cowork and copies both skills (`sidecar`,
+`second-opinion`) into `~/.claude/skills/`. It does **not** copy
+`commands/council.md` — that only ships via the plugin channel below. This
+is a known, accepted gap for npm/install-script users (slash commands are
+plugin-channel-only by design; see the npm-vs-plugin note at the top of the
+CHANGELOG's Unreleased section).
+
+## 2. Claude Code community marketplace (claude-community)
+
+**Status: submitted 2026-07-01 — awaiting Anthropic review.** (Update this
+line as the process advances: `submitted <date> / approved <date> / listed <date>`.
+Note: the submission predates the Phase-9 polish on `main` — reviewers pulling
+the repo see the current surface, including `commands/` and a clean
+`claude plugin validate . --strict`.)
+
+Two Anthropic-run marketplaces exist:
+- **`claude-plugins-official`** — curated by Anthropic, no application process.
+- **`claude-community`** — third-party plugins, submitted for review. This is
+  the one amicus targets.
+
+Approved plugins are pinned to a commit SHA in
+`anthropics/claude-plugins-community/.claude-plugin/marketplace.json`. CI in
+that repo auto-bumps the pin as we push to `main`, and the public catalog
+syncs from it nightly (a delay after any push is normal, not a bug). **PRs
+opened directly against `anthropics/claude-plugins-community` are closed
+automatically** — the only way in is the submission form below.
+
+Because the pin auto-bumps on every push to `main`, every push after listing
+reaches marketplace users on their next sync. `plugin.json` already pins an
+explicit `version` synced to `package.json` (enforced by
+`tests/plugin-manifest.test.js`), so this is the existing safe behavior:
+users only see a version bump when we bump it, not on every commit. Treat
+`main` as release-quality once listed.
+
+### Preflight (run before every submission or major post-listing update)
+
+```bash
+claude plugin validate . --strict
+claude --plugin-dir .   # smoke: /amicus:council, /amicus:sidecar, /amicus:second-opinion, MCP tools
+npm test
+```
+
+- `claude plugin validate . --strict` is the same structural check the
+  review pipeline runs; `--strict` promotes unrecognized-field warnings to
+  errors so nothing slips through that CI would later flag. It needs the
+  Claude Code CLI installed locally — it is **not** wired into this repo's
+  CI (runners have no `claude` auth), so `tests/plugin-manifest.test.js` is
+  the CI-side proxy for manifest completeness.
+- `claude --plugin-dir .` loads the plugin from the working tree so you can
+  manually confirm `/amicus:council`, `/amicus:sidecar`, and
+  `/amicus:second-opinion` all appear in the command picker exactly once,
+  and that the `amicus` MCP server connects (tools list populates).
+- `npm test` must be green, specifically `tests/plugin-manifest.test.js`
+  and `tests/plugin-commands.test.js`.
+
+**Known current-tree preflight result (checked 2026-07-02, `p9/distribution`
+at a1bea3c):** `claude plugin validate . --strict` passes clean, exit 0.
+(History: `--strict` previously flagged an unknown `plugin.json → bugs`
+field; that field was removed in commit `4207485`, so the warning is gone.)
+
+### Submit
+
+- **Individual-author route:** https://platform.claude.com/plugins/submit
+  (Console form). This is the route for us — Christian has no Team/Enterprise
+  org, so the directory-management admin route below doesn't apply.
+- **Team/Enterprise route:** https://claude.ai/admin-settings/directory/submissions/plugins/new
+  (requires Team/Enterprise org + directory management permissions — not
+  applicable here, listed for completeness).
+- **Metadata to enter in the form:**
+  - Repository: `https://github.com/BourbonDog/amicus` (public, MIT)
+  - Plugin name: `amicus`
+  - Description: pulled from `.claude-plugin/plugin.json` → `description`
+  - Contact: `sendtowags@outlook.com`
+- **Timing:** submit only after Task 9a (`commands/council.md` + the sidecar
+  argument surface) has merged to `main`, so the SHA the reviewer evaluates
+  and the SHA that eventually gets pinned both include the slash commands.
+  Submitting before 9a merges means the reviewed surface is incomplete.
+- Never open a PR against `anthropics/claude-plugins-community` — it's a
+  read-only mirror for the public catalog; PRs there are auto-closed.
+
+### What review checks (and what it might ask about)
+
+The pipeline runs `claude plugin validate` plus automated safety screening.
+There's no published SLA for turnaround — **budget this as unscheduled** and
+don't put any downstream work on the critical path of approval.
+
+Anticipated reviewer question: the npm package runs a postinstall
+(`scripts/postinstall.js`) and the repo ships `install.sh` / `install.ps1`.
+The **plugin channel itself never triggers postinstall** —
+`.claude-plugin/plugin.json`'s `mcpServers.amicus.env` sets
+`AMICUS_SKIP_POSTINSTALL=1`, so a plugin install only ever runs
+`npx -y amicus@latest mcp` with that guard set, not the interactive
+setup/registration flow. This paragraph is the answer if a reviewer asks.
+
+### After approval
+
+1. Search `"amicus"` in
+   https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json
+   to confirm the listing synced (nightly delay after approval is normal).
+2. End-to-end verify:
+   ```bash
+   claude plugin marketplace add anthropics/claude-plugins-community
+   claude plugin install amicus@claude-community
+   ```
+3. Update the Status line at the top of this section with the
+   submitted/approved/listed dates.
+4. Optionally add an "Install as a Claude Code plugin" section to
+   `README.md` referencing `@claude-community` (not done as part of this
+   task — premature before approval, since the listing doesn't exist yet).
+
+*(Everything in this subsection past "search 'amicus' in
+`marketplace.json`" is unverified as of 2026-07-02 in the sense that we
+haven't been through it yet — it's the documented expected flow per
+Anthropic's published docs, not something we've personally exercised
+end-to-end against the real submission.)*
+
+## 3. MCP Registry
+
+**Status: wired, not yet published (Phase 9c).** `server.json` (repo root)
+and the `mcpName` field in `package.json` now exist, and
+`.github/workflows/publish.yml` publishes to the MCP Registry
+(`registry.modelcontextprotocol.io`) as the last three steps before the GitHub
+Release, on every `v*` tag push. This has not fired yet — the first tag
+push after this merge is the first real publish attempt.
+
+**Namespace:** `io.github.BourbonDog/amicus` (case-sensitive — the registry
+grants `io.github.<Login>/*` using the exact-case GitHub login/repository
+owner). Confirmed unclaimed via
+`https://registry.modelcontextprotocol.io/v0/servers?search=amicus`
+(0 results, checked 2026-07-02).
+
+**Flow:** tag↔`package.json` version lockstep is verified first (fails fast
+with `::error::` on a mis-tag) → npm publish (existing, OIDC), itself guarded
+by a version-exists check so a re-run does not re-attempt a version already
+live on npm → `mcp-publisher` binary installed → `server.json` version
+synced from the tag via `jq` (belt-and-braces; the in-repo
+`server.json`/`package.json`/`packages[0]` versions are also kept in
+lockstep by hand at release time and enforced by
+`tests/scripts/package-manifest.test.js`) → MCP Registry publish, itself
+pre-checked against the registry API so a re-run does not double-publish →
+`mcp-publisher login github-oidc` (no secret needed, uses the same
+`id-token: write` OIDC permission as the npm Trusted Publishing step),
+retried up to 5 times on transient OIDC token-exchange failures → `mcp-publisher
+publish`, retried up to 5 times (npm propagation lag) before hard-failing the
+job → GitHub Release creation, guarded by an existence check so a re-run
+does not fail on a release that already exists. The registry steps run
+strictly after `npm publish` because npm-side ownership validation reads
+`mcpName` from the *published* `package.json`.
+
+**Release-order dependency (historical — satisfied before the first registry
+publish):** the first post-merge `v*` tag had to wait for the Phase 4
+tool-surface de-bloat, because the server still registered 13 deprecated
+`sidecar_*` aliases alongside the real tools and the first registry publish
+snapshots whatever surface exists at that time. Both have long since landed.
+The rule that outlives the episode: **a registry publish snapshots the tool
+surface, so land any tool-surface change before you cut the tag.** For the
+current tool count, see the MCP table in [README.md](../README.md) — it is the
+single source of truth and moves with each release (v4.0 added
+`amicus_council_run`).
+
+**Registry preview caveat:** the MCP Registry is still in preview per its
+own docs (breaking changes/data resets possible before general
+availability). The publish steps are additive to the existing npm/GitHub
+Release flow and do not touch it; a registry publish failure after 5 retries
+does fail the workflow job (hard `exit 1`), which means the 'Create GitHub
+Release' step does not run on that path. If that trade-off proves unwanted
+in practice, add `continue-on-error: true` to the 'Publish to MCP Registry'
+step.
+
+**First-publish de-risk:** before relying on CI for the first real publish,
+run once locally: download `mcp-publisher` (Windows: the tarball flow from
+the quickstart docs), `mcp-publisher login github` (device-flow auth as
+BourbonDog), then `mcp-publisher publish` — to fail fast on any
+namespace/validation error outside of CI. If publish returns "You do not
+have permission…", the error message states the granted pattern; align
+`server.json`'s `name` casing to it exactly.
+
+**If the registry publish fails in CI (Phase 11 hardening):** re-running the
+workflow is now the primary recovery path. Every publish-ish step in
+`publish.yml` is idempotency-guarded, so a re-run skips whatever already
+succeeded and only retries the step that actually failed:
+- **npm publish** checks `npm view amicus@<version>` first and skips with a
+  `::notice::` if that version is already on the registry (instead of
+  hitting `EPUBLISHCONFLICT`).
+- **MCP Registry publish** pre-checks
+  `registry.modelcontextprotocol.io/v0/servers/io.github.BourbonDog%2Famicus/versions/<version>`
+  (HTTP 200 = already published, 404 = not yet) and skips with a
+  `::notice::` if present, before attempting login or publish.
+- **`mcp-publisher login github-oidc`** now retries up to 5 times (20s
+  apart) on transient OIDC token-exchange failures, same pattern as the
+  publish retry.
+- **GitHub Release creation** checks `gh release view <tag>` first and skips
+  with a `::notice::` if the release already exists.
+
+So: fix whatever caused the failure (registry outage, OIDC hiccup, etc.),
+then re-run the failed job from the Actions tab (or `gh run rerun
+--failed`). Do not delete and re-push the tag — the existing job re-run is
+sufficient, and steps that already succeeded (npm publish, an earlier
+registry publish, an existing release) are detected and skipped rather than
+re-attempted or double-published.
+
+**Caveat — content-level 422s are NOT re-run-recoverable.** A workflow
+re-run checks out the tag, so a `server.json` validation error (the registry
+returns HTTP 422 naming the failing field) reproduces identically on re-run.
+Fix `server.json` on main and recover via the manual path below, or let the
+fix ride the next tag. Known registry constraint (learned live): the
+top-level `description` is capped at **100 characters** — v1.9.0's first
+publish attempt 422'd on a 199-char description (2026-07-03); now pinned by
+`tests/scripts/package-manifest.test.js`.
+
+**Manual recovery (fallback, if re-run is not viable):**
+1. **Registry publish:** run the same local de-risk flow above for real —
+   `mcp-publisher login github` (device-flow login as BourbonDog), sync
+   `server.json`'s `.version` and `.packages[0].version` to the tag that
+   already published to npm, then `mcp-publisher publish`.
+2. **GitHub Release:** cut it by hand:
+   `gh release create <tag> --generate-notes --latest`. The "Generate release
+   notes with Claude" step is optional polish — skip it or run it manually
+   against the API.

package/docs/ROADMAP.md

@@ -0,0 +1,200 @@
+# Amicus — reprioritized roadmap
+
+**Reprioritization guidance (Christian, 2026-07-18):** engine-first is locked; the near-term work
+ships as an incremental **4.x point-release line**, each rev delivering a **behavioral / feature
+benefit users feel**; **enterprise-readiness is a venture unto itself** — the deliberate **5.0**
+major jump, gated on funding/cofounder. The observability arc is split so the **data layer ships
+first (v4.3)** and the **Electron "Council Workspace" (v4.4)** rides on top of it. `--dry-run` cost
+preview dropped to the backlog.
+
+Amicus is at **v4.4.1** (2026-07-27), the fast-follow patch on v4.4.0 (tagged 2026-07-26). Each
+4.x rev below leads with the benefit, not the plumbing.
+
+**Status:** v4.0 through **v4.4.1** have **shipped** — everything down to the v4.5 heading is a
+record of what landed, not a plan. **v4.5 (policy packs + composition) is the next rev.** v5.0
+remains forward-looking.
+
+> 📁 **Reading this from an npm install?** Some references below point at working documents that
+> live in the git repository and are deliberately **not** in the published package — anything under
+> `.superpowers/` (the SDD working area, gitignored) and the root `BACKLOG.md`. The npm tarball
+> ships `docs/*.md` only. Read those files at
+> [github.com/BourbonDog/amicus](https://github.com/BourbonDog/amicus); the `.superpowers/` ones are
+> local-only working notes and are not published anywhere. Every claim this roadmap makes is
+> summarized here — the pointers are provenance, not prerequisites.
+
+---
+
+## v4.0 — "Councils become a command you can trust" *(foundation — engine-first)* — ✅ SHIPPED v4.0.0, 2026-07-20
+**Benefit:** the flagship council stops being a manual 6-stage ritual — run a real adjudicated
+council headlessly and in CI, and trust the output enough to gate on it.
+- **Headless council orchestration engine** + `council run --headless` + `amicus_council_run` MCP — B1/A2/D2/F1 *(L)*
+- **Council Review GitHub Action v2** (real adjudicated verdict on PRs) — B2 *(M)*
+- **Versioned JSON envelope + published schema**, all failures routed through it — D3/C3 *(M)* — the engine's trustable contract
+- **Prompt-injection fencing on JSON MCP tools** (H9) — A5/C6/D5 *(S)* — required before councils chew on untrusted CI content
+- **Per-run fold nonce** (BL-7) — C5/D4 *(S)* — correctness/safety
+> Why here: the engine is the moat and everything downstream (CI, automation, dashboards) needs it. The 3 cheap trust fixes ride along because a council you can't trust in automation isn't automatable.
+
+## v4.1 — "The skill sheds the ritual" *(skill-on-engine fast path)* — ✅ SHIPPED v4.1.0, 2026-07-21
+**Benefit:** the daily interactive council stops being a manual 6-stage ritual too — the
+second-opinion skill delegates Stages 1–3+5 to `council run` and keeps only the human stages
+(0 intake, 4 decisions, 6 lessons).
+- **Skill fast path** — SKILL.md orchestration rewired onto `amicus council run` *(M)*
+- **Debate mode headless** (Stage 2.5 rebuttal round in the engine; here or v4.2 at the latest) *(M)*
+- **README + docs update** — skill fast path and headless debate mode reflected in `README.md` and `docs/council.md` *(S)*
+> Why here: locked during the v4.0 design (2026-07-19) — the engine proves itself in CI first
+> (v4.0), then the flagship interactive UX adopts it before any new feature front opens.
+
+## v4.2 — "Bring your own models — $0, private, offline" — ✅ SHIPPED v4.2.0, 2026-07-23
+**Benefit:** run sidecars and councils on local / OpenAI-compatible models (Ollama, LM Studio, vLLM)
+— free marginal cost, private, air-gapped. The single biggest adoption + cost unlock (5 of 6 lenses' #1).
+- **Local / OpenAI-compatible provider support** — `baseURL`/`type` discriminator, `$0`/offline pricing tier, setup-wizard support — A1/B3/C1/D1/E1 *(L)*
+- **Adoption polish** (rides the "easy to start" story): `amicus init --claude` (C2), `doctor` at end of setup wizard (C8), docs for `spend`/`doctor`/`key` (C10) *(S)*
+- **README + docs update** — local / OpenAI-compatible provider setup + `$0` pricing tier in `README.md` and `docs/configuration.md` *(S)*
+> Why here (not enterprise): local models are a broad user benefit — cost, privacy, offline — not an enterprise-only feature. Comes right after the engine so councils can run on free/local seats.
+
+## v4.3 — "See runs live in the terminal — and never waste one" *(observability data layer, first)* — ✅ SHIPPED v4.3.0, 2026-07-24
+**Benefit:** watch runs in real time in the terminal, recover from dead legs, and see where every dollar went.
+- **Live wave observability data layer** + CLI/TUI `amicus watch <waveId>` + `--follow` streaming + `--on-complete <exec|mcp-notify>` hook — F3/D6 *(M)* — the shared data layer v4.4 builds on
+- **Failed-leg retry** `fanout --retry-failed <waveId>` + **cheaper-model fallback chains** + failed-leg partial-spend tracking — F2/E10/E8 *(M)*
+- **Spend visibility & attribution (basic):** fix continue/resume zero-spend rows, attribute waveId/council/project on every row, queryable `spend query` — A4(basic)/E3/E4/E9/D7/C9 *(M)*
+- **README + docs update** — `watch`/`--follow`, failed-leg retry, and `spend query` documented in `README.md` and `docs/usage.md` *(S)*
+> Why here / why first: this is the observability data layer + terminal surface. It ships **before** the GUI (v4.4) because the desktop workspace is a front-end on exactly this data. All M-effort, so it lands fast.
+
+## v4.4 — "The Council Workspace" *(desktop GUI on the v4.3 data layer)* — ✅ SHIPPED v4.4.0, 2026-07-26
+**Benefit:** the same live data as a rich desktop app — watch a council *think*, not just tail a log.
+- **★ Electron "Council Workspace" GUI** — live reviewer progress, anonymized peer packets, adjudication tiers, dissent, cost-by-seat, one-click fold into Claude Code — **B9** *(L)*
+- **README + docs update** — Council Workspace walkthrough + screenshots in `README.md` and `docs/` *(S)*
+> Why here: a GUI layer on top of v4.3's data layer. Split into its own point release because it's the one **L-effort** build in the observability arc — keeping v4.3 small and shippable.
+>
+> The five paid gate councils run against it (`wsgate01`–`wsgate04`, `costgate01`) are also what
+> produced the 4.4.1 backlog below: the GUI shipped, and running real money through it is what
+> surfaced the cost-attribution and repair-path defects that patch closes.
+
+## v4.4.1 — "What the gate councils found" *(fast-follow patch on 4.4.0)* — ✅ SHIPPED v4.4.1, 2026-07-27
+**Benefit:** the product stops mis-stating its own spend, a repair leg stops fabricating findings,
+and a review that honestly finds nothing stops being an error.
+- **Cost truthfulness** — subtree-unknown spend carried into the ledger, the sticky unknown-spend notice unstuck, a cache-only leg reported `unknown` rather than falsely free, and `--max-cost` degraded to exit `2` when the total is inexact rather than claiming a percentage it cannot know — CA-2/CA-3/CA-6/CA-7 *(M)*
+- **The repair path, whole** — all four remaining repair-prompt builders now carry the artifact they are repairing, and a repaired review no longer splices two generations together — LC-12/LC-11 *(M)*
+- **A clean review is a valid review** — `EMPTY_FINDINGS` accepts a well-formed empty set, and the tally, street-cred and chair degrade gracefully on an all-clean bench — LC-10 *(M)*
+- **One OpenCode server per council run** — concurrent waves no longer race each other's SQLite open, which was making `--critic` a coin flip *(M)*
+- Renderer, progress and leg-row robustness; `electron/` under the lint gate; the read-only-workspace invariant test; live rails green as documented *(S each)*
+> Why a patch and not a rev: every item is a correction to something already shipped, all of it
+> measured against real paid runs. Two behaviour changes ride along (LC-2's session abort at the
+> tool-settle ceiling, LC-10's acceptance of an empty finding set) — both owner-ruled, both
+> corrections rather than new capability. Scope, rulings and the full 61-item inventory live in the
+> repo's working notes (`.superpowers/sdd/v441/backlog-and-proposal.md`, local-only) and in the
+> repo's root `BACKLOG.md` — neither ships in the npm package; see the note at the top.
+
+## v4.5 — "Save, share, and compose your councils"
+**Benefit:** complex councils become one-command, repeatable, and chainable.
+- **★ Auto-open the Council Workspace on a council run (Christian, 2026-07-26)** — when a council is
+  invoked from Claude Desktop and Electron is already present, the Workspace window opens by
+  default instead of requiring a separate `amicus watch <runId> --ui`. Today the GUI is opt-in and
+  discoverable only from `watch --help`, so the flagship v4.4 surface goes unseen on the very
+  client best able to show it. *(S–M; the pieces exist — see the design notes below.)*
+- **Council policy packs + full run-profiles** (bench + lenses + options + briefing template, invoke by name) — B7/F5 *(M)*
+- **Composable/chained waves** (`--input-from <waveId>` / pipe) for generate→critique→refine — F6 *(M)*
+- **Briefing templates + library** (F9), **session/wave tagging + `--search` + grouped history** (F8), **GUI power ergonomics** (F10) *(S–M)*
+- **README + docs update** — policy packs, chained waves, and the briefing-template library in `README.md` and `docs/` *(S)*
+> Why here: velocity multipliers that only pay off once councils are a command (v4.0) and observable (v4.3/v4.4).
+
+### Deferred out of v4.4.1 into v4.5 (2026-07-27)
+
+Each is `M`+, or needs data or a design decision — the bar a patch on a published release cannot
+carry. The table below is self-contained; the full write-ups (what, where, what breaks if it stays)
+live in the repo's local-only working notes — `.superpowers/sdd/v44/v4.4.1-backlog.md`, with the
+disposition that put them here in `.superpowers/sdd/v441/backlog-and-proposal.md`. **If you have
+those notes, read that backlog's Appendix A (settled decisions) and Appendix B (known false
+positives) before re-filing anything from this list.**
+
+| ID | What | Why not 4.4.1 |
+|---|---|---|
+| **CA-4** | `tally.json`'s `runStats` omits Stage-2 judges, repair solos and failed chair attempts (5 rows for 11 real legs in `wsgate04`) | `M` — a schema question, not a fix |
+| **CA-5** | `isSubagentToolCall` is still a `name === 'task'` string proxy | `M`, and **reduced** by v4.4.0: it is now only the fallback when the real subtree walk finds nothing |
+| **LC-1** | B53's stall kill is skipped while a tool-settle deferral is active | `S–M` — shipped deliberately; the author wants a second opinion, which needs data from real runs |
+| **LC-5** | A chair fallback leaves no trace in `run.json` (`wsgate02`'s haiku failed twice; only `"chair":"minimax"` was recorded) | `M` — a run-record schema addition |
+| **RN-1** | `sanitizeName` collisions surface as a banner rather than a refusal | `S` + a product decision that was already argued once |
+| **RN-2** | `renderRunList` blind masking is best-effort — only the open run resolves labels | `M` |
+| **RN-5** | A blind-mode flip closes every open prose panel and repaints twice | `S–M` |
+| **RN-11** | `renderSeats` never reorders existing rows | `S`, cosmetic, no consequence yet |
+| **REL-2** | `mcp-repomix-e2e` skips, so plugin-chain MCP discovery is exercised nowhere | `M` — needs `AMICUS_REPOMIX_E2E_PROJECT` pointed at a real project *and* `repomix` on PATH |
+| **TST-1 / TST-2** | No real `--debate` fixture; the `lens:<slug>` role branch has zero coverage | `M` each, and they want doing together |
+| **TST-3** | Abort confirm→status-flip is proven only against the fake DOM | `M` — needs a real CDP pass |
+| **TST-7** | Six render functions have no unit coverage | `M` |
+| *(new)* | **Residual integration-suite handle leaks** — a NAMED leak with evidence, filed 2026-07-27 after 4.4.1 fixed ENV-6 and the live rail still warned from *different* suites | `S–M`. Full evidence, including why `--detectOpenHandles` cannot diagnose this class, is in the repo's root `BACKLOG.md` (not in the npm package — read it on GitHub) — start there rather than re-deriving it |
+
+**ENV-6 is NOT on this list** — it was pulled into 4.4.1 by owner ruling and fixed at the source
+(the CDP e2e suite's SIGKILL escalation timer). **ENV-1** is not on it either: it is a decision
+record ("eleven `Number(env) || default` sites"), not a task — a blanket migration would introduce
+six new defects to fix one, and `src/utils/env-num.js`'s docblock records which knobs deliberately
+keep the old form.
+
+## v5.0 — Enterprise-readiness *(the deliberate major jump — a venture unto itself, gated on funding / cofounder)*
+**Benefit:** team/org deployment — but a distinct product + go-to-market motion (SOC2, SLAs, sales, support), not a feature drop. Parked as the 5.0 major per the chair's hard-question #5: a solo dev can't credibly ship or support this alone.
+- Secret-store backends + env-var-only mode (A3); org allowlists/blocklists, per-team cost ceilings, read-only enforcement (A6); RBAC
+- Audit & compliance: reproducibility manifests + replay (B11), seed/temp/version pinning (A7), spend export to SIEM/warehouse (A10), `/health` + metrics + structured logging (A8)
+- Team config `.amicusrc` (A9); spend **governance** (per-team caps/enforcement) — the governance half of A4
+- Learning loops that need scale anyway: reliability-aware seat selection (B4), calibration benchmarks (B5), decision-outcome feedback (B10), adaptive strategy planner (B8), evidence provenance (B6)
+- README + docs update: deployment/admin documentation for the above, in `README.md` and `docs/`
+> These cluster because they share one prerequisite you don't have yet: an org buyer + the org to support. Revisit as a funded track.
+
+---
+
+### Design notes — auto-open the Council Workspace
+
+Recorded 2026-07-26 from a read of the shipped code, so the v4.5 implementer starts from facts
+rather than re-deriving them.
+
+**The pieces already exist.**
+
+| Need | Where it lives today |
+|---|---|
+| Launch the window | `src/sidecar/workspace-window.js` `launchWorkspaceWindow({project, runId})` |
+| Detect the client | `src/utils/client-detect.js` `detectClient(mcpServer)` → `code-local` \| `code-web` \| `cowork` |
+| Is Electron usable | `src/sidecar/electron-install.js` `isElectronUsable` / `resolveElectronBinary` |
+| Current entry point | `amicus watch <runId> --ui` (`src/cli-handlers-watch.js:87`) |
+
+**"Claude Desktop" maps to `code-local`.** ⚠️ But `detectClient` reads the MCP client's
+`getClientVersion().name`, so it **only works on the MCP path** — `amicus_council_run`, which is
+exactly the Claude Desktop case. A `council run` typed into a terminal has no MCP server, so
+detection there falls through to the env override or the `cowork` status-quo default. Do not build
+this on the CLI path expecting detection to work; either gate it on the MCP entry point or thread
+an explicit client tag through. (Related: the Phase 12 backlog item about persisting the client tag
+into shared-server `metadata.json` is the same seam.)
+
+**Four guards, all load-bearing:**
+
+1. **Never under `--json`.** `--ui` already rejects `--json` (interactive-only); an implicit default
+   must not create the combination the explicit flag refuses.
+2. **Never in CI or headless.** `council run` is the engine behind the Council Review GitHub Action
+   and every headless fanout. A popped window on a runner is a hang, not a feature. Gate on the same
+   display check the e2e suite uses (`HAS_DISPLAY`).
+3. **Never trigger an install.** Requirement is *"where Electron is installed"* — check
+   `isElectronUsable`, and if it is absent, do nothing silently. An implicit ~100 MB Electron
+   download on someone's first council run is a hostile surprise.
+4. **Must be opt-out.** A `--no-ui` (or config key) that suppresses it, because this changes default
+   behaviour for an existing command.
+
+**Why not v4.4.1.** It is a new default behaviour — a feature — and 4.4.1 is a patch on a shipped
+release whose scope was explicitly locked. The patch already carries two behaviour changes (LC-2,
+LC-10) that stretch the definition; a third that pops a GUI window would not be defensible as a
+patch. Sits naturally beside v4.5's existing **GUI power ergonomics (F10)** line.
+
+## Backlog (tracked, not scheduled)
+- **`--dry-run` / cost & route preview** across start/fanout/council — E2/C7/F4 *(M)* — "know the cost/route before you commit"; useful, not essential to the near-term line.
+- **F7** — Parallel council panels + super-chair (opt-in `--panels N` high-assurance; niche).
+- **E7** — Prompt dedup cache (exact-dup, opt-in, excludes council/fanout) — minor cost optimization.
+- **E6** — Cost-per-quality metric (withdrawn in debate; revisit if street-cred stabilizes).
+- **`amicus key --local` picker** *(S)* — a default local-provider picker so `amicus key` sets/clears a bearer without naming the provider id: auto-select (and announce) when exactly one local provider is configured, a numbered prompt when several, and a hard error under `--json`/non-interactive rather than guessing a secret's destination. Register `--local` as a boolean flag. Deferred out of v4.2.1 as feature material (a new CLI surface, not a patch fix).
+- **Headless no-output fast-fail backstop** *(M)* — fail a headless run fast (env-tunable `AMICUS_NO_OUTPUT_BACKSTOP_MS`, ~120s default) when a misconfigured local model produces zero output, reasoning, and tool-calls, instead of polling to the request/overall timeout. Disarms permanently on the first token/reasoning/tool_use, so a legit slow cold-prefill local model (30–90s is normal) is never affected. Deferred out of v4.2.1 as new runtime behavior.
+
+## What changed vs. the council's flat top-10
+- Split the flat list into a **benefit-themed 4.x point-release line** (v4.0 → v4.2 → v4.3 → v4.4 → v4.5).
+- **v4.1 inserted post-design (2026-07-19):** skill-on-engine fast path + headless debate mode,
+  between the engine (v4.0) and local providers (v4.2). Spec: `docs/superpowers/specs/2026-07-19-v4.0-headless-council-engine-design.md`.
+- **Local providers stays near-term** (v4.2) — a broad cost/privacy benefit, not enterprise.
+- **Observability arc split:** v4.3 = the data layer + terminal surface + resilience + spend (ships first); **v4.4 = the Electron Council Workspace (B9)** as a GUI on that data.
+- **`--dry-run` cost preview → backlog** (was in the observability rev).
+- **Enterprise/governance/audit/compliance/learning-loops → v5.0**, reframed as the deliberate *major-version venture* gated on funding.
+- The **cheap trust fixes** (envelope, injection fencing, fold nonce) pulled into **v4.0** because the engine needs them to be trustworthy in automation.
+- **Docs are part of the rev (2026-07-20):** every rev from v4.1 onward closes with a **README + docs update** line item, so each release ships its own documentation rather than deferring it.

package/docs/SHIMS.md

@@ -0,0 +1,62 @@
+# Amicus compatibility shims — v2.0.0 removal record
+
+v2.0.0 removed every pre-rebrand `sidecar*` compatibility shim (#19). This
+document is now a **removal record**, not a live shim inventory: it exists so
+that (a) anyone still on a `sidecar*`-era install has a one-line migration
+remedy per removed shim, and (b) the v2.0.0 CHANGELOG migration section can be
+lifted from this table nearly verbatim.
+
+Two of the rows below are **not** removals — one is re-scoped as a kept
+healing tool, the other was never a compat shim to begin with — each explains
+its own status inline in its own Status/Migration cells. A related but
+separate guard, which is not itself a table row, is called out explicitly
+below the table: see "Not a removal: the mcp-self-identity recursive-spawn
+guard".
+
+| Shim | Location (at removal) | Legacy form | Status | Migration |
+| --- | --- | --- | --- | --- |
+| Env var prefix | `src/utils/env-compat.js` (deleted) | `SIDECAR_*` env vars | REMOVED in v2.0.0 | Rename every `SIDECAR_*` var you set to its `AMICUS_*` equivalent (e.g. `SIDECAR_ENV_DIR` → `AMICUS_ENV_DIR`, `SIDECAR_IDLE_TIMEOUT*` → `AMICUS_IDLE_TIMEOUT*`, `SIDECAR_DEBUG_PORT` → `AMICUS_DEBUG_PORT`, `SIDECAR_MOCK_UPDATE` → `AMICUS_MOCK_UPDATE`). One additional rename landed in the same removal pass: `SIDECAR_MAX_SESSIONS` → `AMICUS_MAX_SESSIONS` (this was the last remaining legacy-prefixed env var read anywhere in the codebase). Unrenamed `SIDECAR_*` vars are now silently ignored — no warning, no fallback. |
+| CLI bins | `package.json` `bin` | `sidecar`, `claude-sidecar` commands | REMOVED in v2.0.0 | Use `amicus` (or the `am` short alias). If `npm install -g amicus` now fails with `EEXIST` naming an old `claude-sidecar`/`sidecar` file, that's a *stale* global install of the old upstream package, not this shim — see [docs/troubleshooting.md](./troubleshooting.md#install-fails-with-eexist--claude-sidecar). |
+| Config dir | `src/utils/config.js` `getConfigDir()` | `~/.config/sidecar` fallback + `migrateLegacyConfigDir()` | REMOVED in v2.0.0 | No action needed for most users: config data was auto-migrated forward on every v1.x run (each v1.x launch copied `~/.config/sidecar/` into `~/.config/amicus/` once, non-destructively, if the new dir didn't exist yet). If you skipped every v1.x release and jumped straight from a pre-rebrand install to v2.0.0, copy `~/.config/sidecar/` to `~/.config/amicus/` by hand — `getConfigDir()` no longer reads the old location at all. |
+| Session dir | `src/session-manager.js` + call sites | `.claude/sidecar_sessions/` dual-read | REMOVED in v2.0.0 | Amicus only reads `.claude/amicus_sessions/` now. Old session directories are not auto-migrated (per-project, not worth a background sweep) — rename `.claude/sidecar_sessions/` to `.claude/amicus_sessions/` in any project whose history you want `amicus list`/`amicus read` to see again. |
+| Config token | `skills/sidecar/SKILL.md` dual-token instruction + test-only regexes (**not** `config.js` — `config.js` only ever emitted the canonical form; see History below for `c3de5bf`) | `[SIDECAR_CONFIG_UPDATE]` stderr marker / `sidecar-config-hash` HTML-comment parse | REMOVED in v2.0.0 | The skill instructs the canonical forms only: `[AMICUS_CONFIG_UPDATE]` and `<!-- amicus-config-hash: ... -->`. Old CLAUDE.md files carrying a leftover `<!-- sidecar-config-hash: ... -->` comment are not auto-migrated — the comment is simply no longer recognized; the next `amicus setup` alias change will write a fresh `amicus-config-hash` comment and the stale one can be deleted by hand. |
+| MCP tool names | `src/mcp-server.js` registration | `sidecar_*` tool aliases — opt-in via `AMICUS_LEGACY_ALIASES=1` since v1.8.0 | REMOVED in v2.0.0 | `AMICUS_LEGACY_ALIASES=1` is now a **no-op**: setting it changes nothing, and only the canonical `amicus_*` tools register (regression-pinned in `tests/mcp-server-legacy-aliases.test.js`). Update any MCP client config or tooling that still calls a `sidecar_*` tool name to use the `amicus_*` equivalent. |
+| Public API | `src/index.js` | `startSidecar`/`listSidecars`/`resumeSidecar`/`continueSidecar`/`readSidecar` exports | REMOVED in v2.0.0 | These were exported as deprecated aliases from the package root through v1.9.1 (present on npm in every release). v2.0.0 deletes them from `module.exports`; only the canonical `startAmicus`/`listAmicus`/`resumeAmicus`/`continueAmicus`/`readAmicus` names remain exported. Rename any import of a `*Sidecar`-named export from `amicus`'s package root to its `*Amicus` equivalent. |
+| MCP registration cleanup | `src/utils/legacy-mcp-migration.js`, invoked by `scripts/postinstall.js` and `amicus doctor --fix` | duplicate `'sidecar'` MCP server entry in `~/.claude.json` / `claude_desktop_config.json` | **KEPT** (re-scoped, #19) | Not a compat shim — a one-shot **healing** tool for pre-1.8.0 installs that registered the same server under both `'amicus'` and `'sidecar'`. It only removes a `'sidecar'` entry verified identical-in-effect to the `'amicus'` one (`isAmicusMcpConfig()`); a customized `'sidecar'` entry pointing elsewhere is left alone. Still runs on every `postinstall` and via `amicus doctor --fix`. Kept indefinitely — there is no removal date. |
+| Fold-marker constant | `src/headless.js` `FOLD_MARKER`/`COMPLETE_MARKER` exports | bare `[SIDECAR_FOLD]` literal, export-only back-compat — as of v4.0 no code path writes OR matches the bare form (`extractSummary`/`formatFoldOutput` require the per-run nonce; the legacy matcher/writer fallbacks are retired). On the wire the bare literal survives only as the prefix inside the nonced `[SIDECAR_FOLD:<nonce>]` form — see [docs/architecture.md](./architecture.md) | **KEEP** — deliberate wire-token continuity, not a compat shim, not scheduled for removal (B38 keeps it) | No action needed. |
+
+## Not a removal: the mcp-self-identity recursive-spawn guard
+
+`src/utils/mcp-self-identity.js` still recognizes the old bin/server names
+`'sidecar'`/`'claude-sidecar'` in its self-exclusion lists (`SELF_MCP_NAMES`,
+`SELF_BIN_NAMES`), even though v2.0.0 no longer ships them. This is
+**deliberate and out of scope for this removal** — it's a defense, not a
+shim: a stale pre-rebrand global install can still have `sidecar`/
+`claude-sidecar` linked on a user's `PATH`, and a stale `claude.json`/MCP
+config can still reference the old `'sidecar'` server name. Recognizing them
+here only ever prevents amicus from recursively spawning itself under an old
+alias — it never restores old behavior or re-exposes removed surface, so
+there's no cost to keeping the wider net. Not tracked for future removal.
+
+## Verification
+
+Removal is verified in the codebase, not just asserted here:
+
+- `grep -r "SIDECAR_" src/` → every hit is the `[SIDECAR_FOLD:<nonce>]` fold-marker contract (`src/headless.js`, `src/prompt-builder.js`, `src/utils/fold-marker.js`), a comment referencing it (e.g. `src/sidecar/interactive-process.js`), or the bracket-less `SIDECAR_FOLD` prefix inside the nonced form. The bare `[SIDECAR_FOLD]` literal survives **in code** in exactly two inert spots: the export-only back-compat constant `FOLD_MARKER` (`src/headless.js` — assigned, aliased to `COMPLETE_MARKER`, exported, never used in live logic), and the fallback branch of `buildHeadlessModeSection` (`src/prompt-builder.js`: `nonce ? buildFoldMarker(nonce) : '[SIDECAR_FOLD]'`) — reachable ONLY via the deprecated, production-unused `buildSystemPrompt()`, which builds no prompt for any real run. No **live** run path writes or matches the bare form since v4.0: `buildPrompts` — the orchestration entry point every real headless run routes through (`start` / `continue` / `fanout` / `mcp-server`) — throws a `TypeError` rather than emit a nonce-less headless prompt, and the detector (`trailingFoldMarkerRegex` in `src/utils/fold-marker.js`) matches only the nonced form. No `SIDECAR_*` env var is read or written anywhere in `src/`.
+- `tests/mcp-server-legacy-aliases.test.js` — regression-pins that `AMICUS_LEGACY_ALIASES=1` registers zero `sidecar_*` tools.
+- `tests/where-things-live-docs.test.js`, `tests/shim-removal-docs.test.js` — pin that docs describe the removal, not a live shim.
+
+## History
+
+Removed across the following commits on `p18/shim-removal` (#19):
+
+- `a33690c` — MCP tool alias shim
+- `fc7f0db` — public API `*Sidecar` alias exports
+- `3791a6e` — `SIDECAR_*` env-var fallback shim
+- `e9dade0` — `~/.config/sidecar` dir-fallback + `migrateLegacyConfigDir`
+- `887912a` — `sidecar_sessions` dual-read shim
+- `4ebc84d` — `sidecar`/`claude-sidecar` CLI bin aliases
+- `c3de5bf` — dead `sidecar-config-hash` comment-parse tolerance (test-only tolerance removal — `config.js` never had dual-parse code; the skill-text acceptance instruction is fixed by this docs sweep)
+- `9273dd1` — `SIDECAR_MAX_SESSIONS` → `AMICUS_MAX_SESSIONS` rename (the last legacy-prefixed env var read anywhere in the codebase)
+
+See the rebrand plan for the original shim rationale: `docs/superpowers/plans/2026-06-08-amicus-rebrand.md`.