amicus 4.6.2 → 4.7.0

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,344 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.7.0] - 2026-08-08
+
+**"The count is the count."** Every number Amicus shows you is the number — what a council cost,
+which legs ran, and which model earned the credit. Shipped across ten `v4.7-*` PRs — PR0
+(extractions) through PR7, plus the PR3 riders and a closing documentation pass: the `runStats`
+completeness half of CA-4, the GOA-7 ledger prerequisite, F8 session/wave tagging with `--search`,
+and four correction sweeps.
+
+### CI
+
+- **The macOS/node-24 unit leg's `--workerIdleMemoryLimit` drops from 1GB to 512MB.** That leg
+  segfaulted a jest worker again on 2026-08-07 (PR #126) — killing
+  `tests/utils/gateway-route-audit.test.js` while 6791 tests passed and 0 failed, with a green
+  rerun — which was the first such hit *with* the 1GB ceiling in force, so 1GB does not bound the
+  growth on this runner. Halving recycles a worker sooner, at a small wall-clock cost on a leg
+  already mid-pack (~3m59s vs ubuntu's ~3m58s). Three pins in
+  `tests/scripts/ci-workflow.test.js` now guard the mitigation, which previously had none: it
+  produces no assertion failure when it works and none when it is deleted, so nothing else in the
+  repo would notice its loss. If a fifth hit lands at 512MB, the next lever is `--maxWorkers` on
+  that leg — fewer concurrent heaps — not a smaller idle ceiling.
+
+### Added
+
+- **`runStats` gains a row for every paid launch, not just one per requested seat** (v4.7 CA-4,
+  the row-per-launch design — closes the chair-cost accounting gap). Three new roles cover legs
+  that were billed but never rowed: `chair-attempt` (a failed ch1–ch3 chair launch), `repair`
+  (a Stage-1 `-p`, Stage-2 `-q`, chair-ch4, or debate-born `-d<N>r`/`-rv-…r` solo — a failed
+  defense or re-vote repair), and `superseded` (a first leg a later attempt replaced — an SL-2
+  retry or a debate repair); `wasChair` is always `false` on these. Every dead seat/critic/lens
+  with no recovery, and a chair walk that gives up entirely, now get an honest primary error row
+  too, extending the #83 judge treatment to every seat.
+- **`runStats[].waveId`** (emit-only-when-set): every row backed by a real billed leg now names
+  the exact wave/leg it came from; e.g. the synthetic `claude` row, a give-up chair's error row,
+  and a leg-less dead-seat/critic/lens primary error row (the two SL-2 retry note-classes that
+  never produced a real leg for the seat at all) carry none.
+- **The run-cost bijection invariant suite** (`tests/council/run-cost-bijection.test.js`): every
+  terminal run now proves Σ(`runStats` legged-row usage) equals `run.json`'s `usage` block —
+  cost, and the reported/estimated/unpriced/subtreeUnknown leg counts — across clean, repair,
+  chair-walk-failure, debate-repair, retry-healed, and retry-failed scenarios.
+- **`runStats[].resolvedModel`** (v4.7 GOA-7, emit-only-when-set): every row built from a served
+  leg now records the executable id that actually served (post-fallback-substitution), never the
+  alias; carried verbatim through `tally.json`/`verdict.json` and onto `council-ledger.jsonl` rows.
+- **`council stats` rows gain `aliases[]`** (every alias observed for the group, most recent
+  first — `aliases[0]` is the launch-preferred name) **and a `legacy` mark** on groups whose rows
+  all lack `resolvedModel`; the human table sizes the model column to the longest key (16-char
+  floor) and marks `legacy` in the notes column beside `low-N`.
+- **`--tag <t>` on `start`/`fanout`/`council run`** (CLI + MCP, v4.7 F8 D13): labels a session
+  for `list`/`--search`/`spend --group-by tag`. Reject-style validation
+  (`^[A-Za-z0-9_-]{1,64}$`) — an invalid tag fails fast rather than being silently truncated or
+  charset-stripped the way `sanitizeCouncilName` cleans, since a stored tag is a search key.
+  Stored absent-not-null on `metadata.json`/`wave.json`/`run.json` and every result doc; the MCP
+  shared-server's in-process start path stamps it too. `--tag` is rejected alongside
+  `--retry-failed` (`BAD_ARGS`).
+  Council sub-waves (Stage-1, critic/lens solos, Stage-2, chair, debate) all carry the run's tag
+  on their own wave metadata. Riders: `continue`/`resume` don't yet inherit the parent session's
+  tag (their rows group under `(unattributed)` for `--group-by tag`), and `--retry-failed` doesn't
+  yet inherit the original wave's tag either — both are future work, not oversights.
+- **`amicus list --search <q>` / MCP `amicus_list {search}`** (F8 D15, errata E-PR3-5):
+  case-insensitive substring filter over `id`, `tag`, and briefing material. Fan-out wave rows
+  match against the full `briefing.md` text (falling back to the row's 200-char excerpt when
+  unreadable); council-run rows match `briefing.md` written at MCP launch, or the
+  post-`--- MATERIAL / BRIEFING ---` portion of `briefing-stage1.md` for CLI-launched runs; leg
+  rows (spawned by a wave) match `id`/`tag` only, so a wave's briefing never surfaces once per
+  leg it spawned. A bare `--search` with no value is a usage error.
+- **`amicus spend --group-by tag`** (F8 D16): spend-ledger rows now carry `tag` (leg and solo
+  rows alike); untagged history groups under `(unattributed)`, matching every other dimension's
+  convention. `SPEND_LEDGER_SCHEMA_VERSION` stays at `1` — this is an additive field, not the kind
+  of change that forced the council-ledger's `LEDGER_SCHEMA_VERSION` 1 → 2 bump above, which
+  existed to segment history by resolved-model id, a different need.
+
+### Changed
+
+- **Tally/report/GUI cost totals now include legs that used to be silently dropped** — repairs,
+  failed chair attempts, and superseded/replaced legs all get a row now. Totals read HIGHER than
+  v4.6.x for an identical run, intentionally: this is the fix for the two-numbers-disagree
+  symptom (`council tally`'s sum vs. `run.json`'s total quietly diverging by the omitted spend).
+- **The council-ledger join is now an explicit allowlist, not a skip-set**: `seat`, `critic`,
+  `lens:*`, `chair`, `claude`, `council`, `redteam`. Fail-closed by design — consumers keying
+  `runStats` by model must now exclude every role outside that set, the v4.7 analogue of v4.6's
+  "must exclude `role: 'judge'`" rule: a custom/free-form `role` label (e.g. a skill-authored tag)
+  still renders in the tally/report artifact but no longer contributes role/wasChair/conformance
+  to `amicus council stats` reliability numbers.
+- **The Workspace seats panel no longer renders the three new non-seat launch rows**
+  (`chair-attempt`, `repair`, `superseded`) — they still appear in the report/tally cost tables,
+  just not as a seat.
+- **`LEDGER_SCHEMA_VERSION` 1 → 2** (v4.7 GOA-7). Legacy-read, no migration: rows without
+  `resolvedModel` (all pre-v4.7 history, plus leg-less rows whose resolution is unknowable)
+  aggregate under their alias; a group is marked `legacy` only when every row in it lacks
+  `resolvedModel`.
+- **`council stats` groups reliability by resolved model id** (`resolvedModel || model`) instead
+  of by alias alone — history splits honestly at the bump; a retargeted alias's new rows start
+  a fresh `low-N` group.
+- **Chair fallback promotion (`pickFallbackChair`) excludes candidates by their full name set**
+  (group key + `aliases[]`) and launches the group's most-recent alias (`aliases[0]`) — a bench
+  seat's resolved-keyed group can no longer be promoted as its own chair.
+- **`amicus list` and the MCP `amicus_list` tool now share one enumeration**
+  (`src/sidecar/read.js`, F8 D14): MCP rows gain `type`/`parentWave`/`legCount`, CLI rows gain
+  `mode`, and both gain `tag`. The MCP `status` input relaxed from a 3-value enum
+  (`'all' | 'running' | 'complete'`) to a free string, so `error`/`aborted`/`crashed`/
+  `timed-out`/`idle-timeout` — always real statuses, previously rejected outright by MCP's schema
+  even though the CLI already accepted them — now filter correctly there too. The CLI table
+  gained a `TAG` column.
+- Test/comment/docs sweep (v4.7 PR4, theme a): ~30 census nits dispositioned — no behavior
+  changes.
+- **`--out`/`-o` no longer accepts a flag-shaped value as a filename.** `--out -x` and
+  `--out=-x` previously wrote a file literally named `-x` (the dash-leading value was accepted
+  at face value); both forms now fail fast with `BAD_ARGS` ("-o/--out cannot start with '-':
+  got '-x'") instead. `-o -x` was already rejected before this change, via a separate internal
+  check — it still fails with the same code and exit status, now carrying the more accurate
+  message above in place of "-o/--out requires a value".
+- **`{{project}}` template variable is now path-resolved** (absolute, normalized via
+  `path.resolve`), matching `{{artifact_path}}`'s existing behavior — it previously rendered the
+  raw `--cwd`/`process.cwd()` string verbatim. All three `TEMPLATE_RENDER` error paths also gain a
+  real, followable `hint` instead of `hint: null`.
+- **MCP-launched council runs now record `run.template` provenance**, closing the one remaining
+  gap after Wave 1's D1 forwarded it on fanout/start — `mcp-council-run.js`'s template path no
+  longer discards `promptMeta`, so `run.json` carries `{name,hash}` the same way the CLI path
+  already did.
+
+### Fixed
+
+- **`amicus list --all` now actually lists every project.** The flag has been documented since
+  before v4.7 (`--all` / "Show all projects" in `amicus list`'s help text) but `listSidecars`
+  never read it, so it silently behaved exactly like a bare `amicus list`. It now enumerates
+  every project the global sessions-index knows about (an advisory navigation aid, not
+  authoritative — a stale entry pointing at a missing or unreadable project is skipped, not
+  surfaced as an error), deduped by canonical project identity.
+- **`amicus list --search` was accepted and silently ignored.** The generic CLI arg parser took
+  any `--search <value>`, but nothing downstream read it, so the flag — whose sibling convention,
+  `amicus models --search`, was already a repo-wide pattern — quietly did nothing. It's now
+  implemented; see Added, above.
+- **`amicus fanout --quiet` was accepted and silently ignored.** `quiet` is a repo-wide known
+  flag, so the command parsed and exited 0 — but `handleFanout` never forwarded it into
+  `runFanout`, which printed the launch banner and per-leg lines anyway. Same
+  accepted-but-ignored shape as `list --search` above.
+- **`amicus pack save --version <semver>` was accepted and silently ignored — it wrote no pack at
+  all.** `version` is a global boolean flag, so `parseArgs` set `args.version = true`, stranded the
+  semver in positionals, and `bin/amicus.js` printed the amicus version banner *before* command
+  dispatch — `handlePack` never ran, and the command exited 0 having saved nothing.
+  `--version=2.0.0` failed identically. Meanwhile the handler read `args.version` for a value it
+  could never receive, and both the help text and `docs/usage.md` documented `--version <semver>`
+  as a real option. The pack's own version is now spelled **`--pack-version <semver>`** (honored on
+  both the flags and `--from-run` paths), and `pack save --version` fails fast with `BAD_ARGS`
+  naming the right spelling. Every other `--version` still prints the banner. Third instance of the
+  accepted-but-ignored shape, after `list --search` and `fanout --quiet` above.
+- **A fanout whose server fails to start no longer drops its pack.** `errorWave` — the third
+  `buildWaveResult` call site — inherited a pre-seeded `tag` from `metadata.json` but not a
+  pre-seeded `pack`, so an MCP-spawned wave that died at server start persisted a `wave.json`
+  missing the pack it was launched with (and `amicus read --json` prefers `wave.json`). The two
+  other call sites already inherited both; this was the lone holdout.
+- **The test suite no longer writes session directories outside its sandbox.** Several suites
+  passed the literal `'/tmp'` as a project cwd — on Windows that resolves to `C:\tmp`, a real
+  directory — so every run leaked real session dirs onto the developer's filesystem and into the
+  global sessions-index. They now sandbox under `os.tmpdir()`, pinned by
+  `tests/hermetic-tmp-guard.test.js`. This residue was what made `--all` an 8-second, 21k-row
+  dump on a developer machine.
+- **`pack list` warnings now print to stderr, not stdout.** They previously shared stdout with
+  `pack list`'s data output — unlike `pack save`, which already used stderr for the same
+  "Warning:" text — so `pack list | grep` mixed diagnostics into data. `--json` output is
+  unaffected.
+- **A council pack combining `critic` and `lenses` with a by-name (string) bench is now rejected
+  at validate-time (`PACK_INVALID`), matching the array-bench form.** It previously survived
+  run-mode validation and could later surface a mutual-exclusion error naming a flag the user
+  never typed. One consequence: a string-bench pack naming both `critic` and `lenses` — even
+  invoked with an explicit flag — now hard-fails `PACK_INVALID` instead of running; array-bench
+  packs already behaved this way, so this closes a bench-shape-dependent inconsistency rather
+  than introducing a new restriction.
+- **The `{{var.}}` (empty variable key) template error now has a followable message.** It
+  previously told the user to run `--var =<value>` — a form the CLI's own `--var` parser rejects,
+  making the remedy unfollowable by construction; it now correctly explains that
+  `{{var.<key>}}` requires a key and lists the known variables.
+- **`doctor`'s tmp-sweep checks no longer report a name-shaped directory as an unremovable
+  orphan.** A directory whose name happened to match the tmp-file pattern (e.g.
+  `.metadata.json.<pid>.<rand>.tmp`) was picked up by the orphan scan, then permanently failed to
+  unlink — parking the check at `warn` forever ("swept 0, N remaining (too fresh or
+  unremovable)") even after every real orphan was cleared. Directories are now excluded from
+  both sweeps (the metadata sweep, which never follows symlinks, also excludes
+  symlinks/sockets/FIFOs) before the scan ever returns them, so the check reports `ok` once
+  nothing real is left.
+
+### Added (follow-up)
+
+- **`amicus list --limit <n>`**: show only the *n* newest rows (`0` = unlimited, and absent
+  behaves exactly as before). When the cap elides rows it says so, naming the real total; in
+  `--json` mode that notice goes to stderr so stdout stays a single parseable document. Caps
+  output only — `--all` still enumerates every project, since capping the walk would rank rows it
+  never saw.
+
+### CI
+
+- **The MCP-Registry skip-check's version match is no longer a BRE with unescaped dots.**
+  `$VERSION` (a semver like `4.7.0`) was interpolated directly into the grep pattern, where an
+  unescaped `.` matches any character; the fail direction is fail-toward-skip (a false match
+  would silently drop a publish), so the dots are now backslash-escaped before matching. Not
+  exploitable in practice, but tightens the same idempotency check the v4.6.3 CI fix below
+  hardened.
+
+### Fixed
+
+- A pack file whose JSON body is not an object (`null`, an array, a bare number or string) used to
+  read as a *successful* load and then crash with an uncaught `TypeError` — `council run --pack` and
+  `pack show` both died, and `pack show --json` exited 0 with `"pack": null`. It is now a clean
+  `PACK_NOT_FOUND`.
+- **The MCP `amicus_start` shared-server path skipped the budget gate entirely unless a pack set
+  `maxCost`.** It now gates unconditionally with the same `maxCost`/`maxCostPerMtok` config fallback
+  the CLI has always used. Runs that previously proceeded may now be refused — that is the fix.
+- Budget refusal text is now surface-aware on the MCP `amicus_start` (shared-server) path: it no
+  longer names `--max-cost`/`--no-cost-gate`, flags that do not exist there. Other MCP-visible
+  refusals — the `amicus_start` spawn fallback and the fanout/council reservation hint recorded in
+  run docs — still carry CLI-flavoured text; that remainder is filed, not fixed here. On BOTH
+  surfaces the remedy now names only levers that can actually clear the branch that fired: raising
+  the ceiling was previously suggested for a per-$/Mtok refusal, which it could never clear.
+- A council pack could set `options.timeout` to `true` or to a non-numeric string and have it reach
+  the engine — `validatePack` checks option key names, never value types, and the old post-merge
+  check was `timeout <= 0`, which `true` passes by coercing to `1`. Such a pack now exits 1.
+- `--cwd` typed without a value parsed as boolean `true` and reached 16 consumer sites — crashing
+  `council run` with a raw `TypeError` and silently resolving templates against `<cwd>/true`. It now
+  exits 1 at the entry point. Same treatment for `council run`'s `--out-dir`, `--claude-review`,
+  `--run-id`, and `--timeout` (which also accepted `NaN`).
+- **`council run --out-dir` could write outside the project.** The MCP path has been fenced since
+  v4.5; the CLI now applies the same containment check.
+- A council member whose model name collides with an `Object.prototype` key (`toString`,
+  `constructor`, …) crashed the Workspace seats repaint and every live tick after it.
+
+### Added (v4.7 PR7)
+
+- **The seats table's trailing flag column marks a seat that was retried and stayed failed**
+  (PR1F-4): `↻ retried once`, on the errored seat's own primary cost row. Previously that
+  information only existed on a dead-seat row the v4.7 CA-4 convergence now suppresses, so it had
+  no home at all; a status-cell suffix was rejected because a dead seat's row can legitimately
+  carry `status: 'complete'`, and `complete — retried once` reads as "it finished, twice." Terminal
+  path only (`seatsFromRunStats`) — a seat retried while its run is still live shows no marker
+  until the run finishes.
+
+### Fixed (v4.7 PR7)
+
+- **Four stale-paint paths in the workspace prose panels, plus three unhandled-rejection sites,
+  closed together (T19-m1/T19-m2).** A panel could repaint stale content after a
+  close/flip-blind/reopen sequence, after two loads landed out of order, after the same run's
+  artifact manifest grew mid-flight, or after being collapsed mid-flight and reopened; separately,
+  three fire-and-forget panel-load promises could reject uncaught. Fixed behind a new
+  `workspace-lazy.js` extraction: an unconditional panel-cache drop on every issue, a monotonic
+  per-panel issue token so only the newest in-flight load can paint, two-argument
+  `.then(ok, fail)` termination on every load promise (with an announced eviction and a self-check
+  against a stale cache write), and a sync-safe wrap around the matrix drill-in call so a
+  synchronous throw still surfaces instead of escaping uncaught. Worth recording honestly: the
+  collapse-mid-flight path was not closed by the cache-drop half — that half *converted* it from a
+  deterministic stale paint into a race, by orphaning a still-in-flight load that no longer had a
+  cache entry to fence it. The issue token is what actually closes it. Both land in the same commit
+  series, so no released state ever carried the race.
+- **`amicus_fanout`'s wave briefing is now the rendered prompt, not the raw one** (W1-M4),
+  matching the parity the `amicus_start` in-process path already had. Previously a spawned child
+  that aborted before rendering its own copy left `briefing.md` — the file
+  `amicus list --search`/`amicus read` treat as the wave's search corpus — permanently holding
+  unrendered template markup. **Behaviour change:** a wave launched from a pack that forwards a
+  `template` now writes a second file into the wave dir, `briefing-input.md` (the raw prompt handed
+  to the spawned child so its own render still drives `promptMeta.template` provenance), and
+  `--search` now matches the rendered text even for a wave whose MCP-spawned child aborted early —
+  previously it matched nothing meaningful in that case; the same rendered excerpt (first 200
+  characters) is also seeded into `metadata.json` at creation for every MCP fan-out wave, pack or
+  not, so `amicus list`'s BRIEFING column is populated for an aborted wave too, not just a
+  completed one. `amicus_start`'s identical divergence
+  (`mcp-server.js:669`) is unchanged; nobody has driven that path end to end yet, so it is filed in
+  `BACKLOG.md`, not fixed here.
+- **`amicus_fanout` now rejects an empty prompt or a non-positive timeout before creating anything
+  on disk**, closing the one remaining pid-less `status: 'running'` orphan-wave class the schema
+  didn't already cover. **Behaviour change:** a request shaped like `{prompt: '', ...}` or
+  `{timeout: -1, ...}` previously created a wave directory and spawned a child that then failed on
+  its own terms; it now returns a plain-text error and creates nothing. The Zod schema closes this
+  for one entry point (`prompt: z.string().min(1, …)`, `timeout: z.number().positive(…)`); a second,
+  identical check lives in the handler itself, after pack merge, because a pack can push the same
+  invalid values through a door the schema never sees (`validatePack` checks option key names, not
+  value types).
+
+### Changed (v4.7 PR7)
+
+- **The budget-refusal text recorded in a run/wave doc's degrade record is now surface-neutral**
+  (PR6F-1), since that doc is read by both the CLI and MCP: "the $N cost ceiling for this run
+  refused it" / "Raise this run's cost ceiling, or turn the cost gate off, to seat them," in place
+  of CLI-flavoured `--max-cost`/`--no-cost-gate` wording that named flags an MCP caller cannot type.
+  A separate, structurally-unreachable copy of the same CLI-flavoured trailer (nothing ever renders
+  its `hint` on that path) was removed rather than reworded.
+
+## [4.6.3] - 2026-08-05
+
+### Added
+
+- **`fable` now carries an authored direct-Anthropic route** (`anthropic/claude-fable-5`,
+  verified live: Anthropic's `/v1/models` lists it and a direct leg serves). With an
+  Anthropic key present, `fable` routes direct-first like the other Anthropic aliases;
+  the `ANTHROPIC_MODELS` floor gains a matching row so keyless installs validate it.
+- **`doctor` gains a `session-metadata-tmp` check; `--fix` sweeps the orphans.** A kill
+  between an atomic write's tmp-file and rename leaves `.metadata.json.*.tmp` orphans in
+  per-session directories (the B09 class — ~30 write sites). Plain `doctor` reports them;
+  `--fix` removes orphans older than 60 s from the current project's sessions root and
+  announces the heal in the one voice (`Recovered: …`).
+- **`council save` announces when it shadows a built-in bench.** Saving a council named
+  `free`/`budget`/`frontier` previously printed no notice at all (the overwrite marker only
+  tracked user-config names); the save now reports `shadowsBuiltin` (`--json`) and prints
+  the shadow notice.
+
+### Fixed
+
+- **`models --check` no longer false-flags deliberate gateway-only routes.** A curated
+  alias whose direct form is derived (not authored) from its OpenRouter route is no
+  longer reported STALE — flat row, `GATEWAY STALE` row, candidates, and the
+  `fix: --add-alias` retarget suggestion all suppressed together — when the OpenRouter
+  route still serves. Deliberately gateway-only entries (`gpt-pro`) are annotated in
+  the curated data and never audited for a direct sibling. Kills the v4.6.2
+  release-gate false positive whose suggested "fix" was a silent tier downgrade.
+- **The Workspace seats panel's dead-seat rows are now role-aware and old-run
+  resilient.** A model that died as critic but succeeded as chair no longer has
+  its dead row hidden by the chair's cost row (only a live reviewing leg —
+  seat/critic/lens — suppresses, and a dead critic only by a live critic leg);
+  the dead critic's row names its role. Pre-v4.6 runs render their losses too:
+  `verdict.seatLoss.deadBenchSeats` feeds rows, and `verdict.json`'s
+  `degrades[]` backstops a `run.json` that lost its checkpoint. A stale
+  `get-run` reply from a run you navigated away from can no longer repaint the
+  run now open.
+- **A valueless `-o`/`--out` on `council verdict` now errors** (`BAD_ARGS`, flag named,
+  exit 1) instead of crashing mid-write (renameSync `TypeError`) and orphaning a
+  `true.tmp-<pid>` temp file. Behavior change, per the v4.6.3 R1 ruling.
+- **README corrections from the v4.6.3 accuracy review**: the Node.js floor is
+  22.12 (required since v3.0 — the README, install scripts, landing page, and
+  `amicus doctor`'s node check still said 18), and the optional-council-elements
+  list now matches the shipped skill (four opt-ins; the chair's verdict scale
+  has been standard, not opt-in). The doctor's `node` row now errors below
+  22.12 (it previously passed anything ≥ 18).
+
+### CI
+
+- **The MCP-Registry skip-check now verifies the version it trusts.** The
+  release workflow's idempotency pre-check previously skipped registry publish
+  on a bare HTTP 200; it now also requires the response body to both name the
+  exact version and report it as `active`, so preview-API schema churn — or a
+  stale/deprecated registry entry — can no longer produce a false skip. Every
+  new failure mode still routes toward publishing.
+
 ## [4.6.2] - 2026-08-05
 
 ### Added
@@ -91,6 +429,17 @@ All notable changes to Amicus are documented here. Format follows
   with replacement suggestions by `models --check` / `doctor`. This was the pin that made
   `models --check` exit 1 — the v4.6.2 release-gate risk.
 
+### CI
+
+- **The macOS/node-24 unit leg now runs jest with `--workerIdleMemoryLimit=1GB`.** That leg —
+  and only that leg — intermittently lost a worker to a native SIGSEGV ("A jest worker process
+  was terminated by another process"), which fails whichever suite occupied the worker with
+  zero assertion failures and a green rerun. Three confirmed hits (2026-07-31
+  run-cost-unknown, 2026-08-04 PR #100 update-notice, 2026-08-05 PR #105 — 6466 passed, the
+  dead worker alone failed 1 suite) tripped the standing third-occurrence rule. The limit
+  makes jest recycle an idle worker before the leak reaches segfault territory; the flag is
+  injected via a matrix `include`, so the other five legs still run a bare `npm test`.
+
 ## [4.6.1] - 2026-08-03
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 **A multi-model LLM Council for Claude — with a parallel AI window underneath.**
 
-![The Amicus council mid-ritual: five models — Gemini, Llama, Grok, Claude Opus — reading the same material independently, chaired by GPT](./docs/council.png)
+<p align="center"><img src="./docs/cards/council-hero.svg" width="560" alt="The Amicus council ritual across three convenings: independent review spokes, anonymous cross-review, and a non-Claude chair synthesizing the verdict — the third convening seats a local Qwen2.5-Coder on-device alongside cloud peers"></p>
 
 Hand Claude a plan, a design, a diff, an architecture decision, a manuscript — anything — and say *council review this*: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and **fork** a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you **fold** the result back when you're ready. Claude orchestrates throughout; you stay in your editor.
 
@@ -12,7 +12,7 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 
 [![npm version](https://img.shields.io/npm/v/amicus?color=D97757&labelColor=1A1C29)](https://www.npmjs.com/package/amicus)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?labelColor=1A1C29)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?labelColor=1A1C29)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-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)
@@ -62,7 +62,7 @@ One install delivers six things that work together:
 
 Claude is the orchestrator. The council and chat skills run *on top of* the engine; you talk to Claude, and Claude drives Amicus.
 
-![What one install delivers: council skill, chat skill, CLI + MCP, live catalog](./docs/what-is-amicus.png)
+<p align="center"><img src="./docs/cards/what-is-amicus.svg" alt="One install: the second-opinion council and sidecar skills riding the amicus CLI + MCP engine, with the live model catalog, watch/spend, and Council Workspace fed off it"></p>
 
 ---
 
@@ -89,6 +89,8 @@ flowchart LR
     E --> F["Reviewed copy<br/>+ run folder"]
 ```
 
+<p align="center"><img src="./docs/cards/blind-ballots.svg" width="520" alt="Anonymized cross-review: reviews are relabeled A, B, C before the bench ranks them — one model disputes its own review"></p>
+
 **What a run produces** (in `output/<stem>-council/`):
 
 - `review-<model>.md` × N — each model's independent review.
@@ -99,14 +101,15 @@ flowchart LR
   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.
+**Optional council elements** (v2.2.0, all default off): four 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. **Chair verdict scale** *(standard since v2.2.0's follow-ups — no longer opt-in)*: the chair always closes with 3–5 hard questions and one parseable `VERDICT: Ship it | Fix these first | Fundamental rethink` line.
 
 - **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.
 
+<p align="center"><img src="./docs/cards/dial-it-up.svg" alt="The four opt-in council elements as toggles — critic seat and debate on, expert lenses and Claude-in-the-council off — with the up-front run-shape disclosure"></p>
+
 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:
@@ -115,6 +118,8 @@ The critic and lens methodologies are adapted from the `/critic` and `/debate` a
 
 Then the council waits for your confirmation.
 
+<p align="center"><img src="./docs/cards/priced-up-front.svg" width="520" alt="The budget gate: a $0.42 run passes, a $31.80 bench is blocked, and the receipt matches the estimate"></p>
+
 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)**.
 
 ---
@@ -128,10 +133,14 @@ The council is the hero — start with the everyday way, and reach for the more
 - **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)
 
+<p align="center"><img src="./docs/cards/same-table.svg" width="520" alt="A local Ollama model seated as an equal council member at $0.00 — a member, not a mode"></p>
+
 ### 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).
 
+<p align="center"><img src="./docs/cards/ship-gate.svg" alt="A council gating a release pipeline: exit 0 ships it, exit 1 sends it back"></p>
+
 ### 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`.
@@ -192,7 +201,7 @@ Every path delivers the MCP server and both skills. They differ in what else you
 
 #### With npm — recommended
 
-The canonical path, and the one that gets you the full interactive experience (needs [Node.js](https://nodejs.org) ≥ 18):
+The canonical path, and the one that gets you the full interactive experience (needs [Node.js](https://nodejs.org) ≥ 22.12):
 
 ```bash
 npm install -g amicus
@@ -202,7 +211,7 @@ This is the path to pick unless you specifically want the plugin's slash command
 
 #### With the install script
 
-Same result as npm, one command — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
+Same result as npm, one command — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 22.12):
 
 ```bash
 # macOS / Linux
@@ -333,7 +342,7 @@ Everything you need before your first run, and what's optional.
 
 **Runtime**
 
-- **Node.js ≥ 18** — `node --version` to check. This is the only hard runtime prerequisite.
+- **Node.js ≥ 22.12** — `node --version` to check. This is the only hard runtime prerequisite.
 - **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
 
 **Install path & the git toolchain**
@@ -398,7 +407,7 @@ When you don't need a full council — just one other model's take — fork a co
 |---------|--------------|
 | `amicus start` | Launch a new session (interactive or `--no-ui`). |
 | `amicus fanout` | Run N models on the same prompt in parallel (headless). |
-| `amicus list` | Show previous sessions. |
+| `amicus list` | Show previous sessions — shows the `--tag <t>` set at launch, `--search <q>` filters, `--limit <n>` caps the rows, `--all` spans every known project. |
 | `amicus resume` | Reopen a previous session with full history. |
 | `amicus continue` | Start a new session building on a previous one. |
 | `amicus read` | Output a session's summary / conversation / metadata. |
@@ -441,13 +450,13 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.6.2",
+  "version": "4.7.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
 ```
 
-`amicus list --status` accepts `running`, `complete`, `error`, `timed-out`, `aborted`, `crashed`, `idle-timeout`. Full field-by-field docs (a running session's `messages`/`STALLED` reporting, wave-ID status shape, etc.) are in [docs/usage.md](./docs/usage.md).
+`amicus list --status` accepts `running`, `complete`, `error`, `timed-out`, `aborted`, `crashed`, `idle-timeout`. Rows carry a `TAG` column (set at launch with `--tag <t>`); `--search <q>` filters by id/tag/briefing substring, `--limit <n>` caps the row count (0 = unlimited), and `--all` lists across every known project. Full field-by-field docs (a running session's `messages`/`STALLED` reporting, wave-ID status shape, etc.) are in [docs/usage.md](./docs/usage.md).
 
 ---
 
@@ -462,6 +471,8 @@ amicus models --search gemini # filter by substring
 
 `start`/`fanout` validate your model against the catalog before launching (skip with `--no-validate-model`). You can also always bypass aliases and pass a full model ID directly — bare `provider/model` (canonical) or `openrouter/provider/model` (explicit override); see Routing below. Catalog internals, alias management, and the full-id passthrough table are in **[docs/usage.md § Models](./docs/usage.md#amicus-models--the-model-catalog)**.
 
+<p align="center"><img src="./docs/cards/build-the-bench.svg" alt="Direct keys, one OpenRouter key, or local runtimes seat a mixed bench — different families, different blind spots"></p>
+
 ### Routing
 
 - **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4-8`, `google/gemini-3.6-flash`) is the canonical, policy-routed form — Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only an OpenRouter key exists.
@@ -475,7 +486,7 @@ Full details, the API-key/prefix table, and the migration notice are in **[docs/
 
 ## MCP integration
 
-The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes sixteen tools:
+The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes these tools:
 
 | Tool | What it does |
 |------|--------------|
@@ -483,7 +494,7 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_status` | Poll a task (or a fanout wave) for completion. |
 | `amicus_wait` | Block inside one tool call until a session/wave finishes or the wait window closes. |
 | `amicus_read` | Read results: summary, conversation, metadata, or JSON. |
-| `amicus_list` | List past sessions. |
+| `amicus_list` | List past sessions (`tag` field; `search` filters by id/tag/briefing substring). |
 | `amicus_resume` | Reopen a session. |
 | `amicus_continue` | New session building on a previous one. |
 | `amicus_abort` | Stop a running session. |

package/bin/amicus.js

@@ -23,6 +23,8 @@ const { handleResume, handleContinue } = require('../src/cli-handlers-resume-con
 const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
 const { suggestCommand } = require('../src/utils/input-validators');
 const { unknownFlags, getKnownFlags } = require('../src/utils/known-flags');
+const { packSaveVersionConflict } = require('../src/utils/cli-preflight');
+const { failJson } = require('../src/utils/error-doc');
 const { logger } = require('../src/utils/logger');
 
 const VERSION = require('../package.json').version;
@@ -53,6 +55,23 @@ async function main() {
     process.exit(1);
   }
 
+  // `--cwd` typed with no value parses as boolean `true` (src/cli.js:101) and
+  // `--cwd=` as '' (src/cli.js:72). DEFAULTS (src/cli.js:28) always seeds a
+  // real absolute string, so a non-string or empty cwd can ONLY mean "typed
+  // without a value" — which makes this guard provably free of false
+  // positives. Left unguarded it reached 16 `args.cwd || process.cwd()`
+  // sites across 9 handlers: council run threw a raw TypeError, template
+  // silently resolved <cwd>/true.
+  // No dash check here: absolute paths never start with '-', and
+  // `--cwd ./x` is legitimate.
+  if (typeof args.cwd !== 'string' || args.cwd === '') {
+    console.error('Error: --cwd requires a value');
+    console.error(command
+      ? `Run \`amicus ${command} --help\` to see valid options.`
+      : 'Run `amicus --help` to see valid options.');
+    process.exit(1);
+  }
+
   // Install crash handler for MCP-spawned processes (have --task-id)
   if (args['task-id'] && (command === 'start' || command === 'continue')) {
     const { installCrashHandler } = require('../src/sidecar/crash-handler');
@@ -86,6 +105,16 @@ async function main() {
     }
   }
 
+  // `pack save` documents a per-pack `--pack-version <semver>`. `--version` is a
+  // global BOOLEAN_FLAG, so `pack save … --version 2.0.0` used to fall straight
+  // into the banner below: exit 0, no pack written, the semver stranded in
+  // positionals. Reject that one combination by name instead of silently doing
+  // something else; every other --version still prints the banner.
+  const versionConflict = packSaveVersionConflict(args);
+  if (versionConflict) {
+    process.exit(failJson(!!args.json, versionConflict));
+  }
+
   // Handle --version
   if (args.version) {
     console.log(`amicus v${VERSION}`);
@@ -221,6 +250,8 @@ async function handleList(args) {
     status: args.status,
     all: args.all,
     json: args.json,
+    search: args.search,
+    limit: args.limit,
     project: args.cwd
   });
 }