amicus 4.6.3 → 4.7.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.6.3",
+  "version": "4.7.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

@@ -5,6 +5,355 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.7.1] - 2026-08-09
+
+### Changed
+
+- **`continue`, `resume`, and `--retry-failed` now inherit the parent session's/wave's tag,
+  instead of dropping it.** `amicus list` now shows a TAG for continuations (they no longer group
+  under `(unattributed)` for `--group-by tag`), and `--tag` is now **rejected** on `continue` and
+  `resume` — the tag can only come from the parent, it cannot be overridden. This deletes a
+  documented limitation, not a bug: `docs/usage.md` carried a paragraph headed "Known limitation: a
+  tag is not inherited", and v4.7.0's own release notes called the gap "future work, not
+  oversights." That limitation is now gone.
+- **`opencode-ai` and `@opencode-ai/sdk` are pinned to exactly `1.18.15`** (previously `^1.2.20` /
+  `^1.1.36`). Dev and CI now run on the same engine version end users resolve, so this is the
+  first release whose test suite actually ran against the engine users get. Honest scope: the pin
+  makes the *resolved* engine a pure function of the amicus version — it does nothing for a user
+  whose installed amicus version hasn't moved, and it does not force any existing npx cache to
+  re-resolve (that mechanism was investigated for #133 and found not to exist).
+
+### Fixed
+
+- **The no-output backstop message now reports what it observed, not what it guessed.** The old
+  three-line message asserted "likely a listed-but-not-serving model or a dead endpoint" with no
+  evidence behind it; it now names only what the deadline mechanism actually saw, and names
+  `AMICUS_NO_OUTPUT_BACKSTOP_MS` as the live governing window only when it is one, calling it out
+  as an overridden default otherwise.
+- **The no-output backstop window now doubles on a Stage-1 retry, clamped to the leg timeout, so
+  retries can now heal a class of no-output failure that previously required a manual rerun.**
+  This is not a fix for the backstop class itself — only Stage-1 bench/critic/lens units retry;
+  judges, chair, chair-repair, and debate legs do not, and can still hit the backstop with no
+  automatic recovery.
+- **`doctor` now reports engine version skew between installs instead of only grading on
+  presence.** A stale npx-cached copy of `opencode-ai` next to a newer global install now surfaces
+  as a WARN.
+- **`npm root -g` now resolves on Windows** (it previously threw `ENOENT`/`EINVAL`, making the
+  global amicus install invisible to `doctor`). This also un-blinds `doctor --fix`'s donor
+  selection, which depends on seeing that global install to pick a healthy engine to copy from.
+- **`npm test` no longer fails intermittently with `ENOENT: … src\__sizecheck_tmp__.js`.**
+  `tests/scripts/check-file-sizes.test.js` writes a real `src/__sizecheck_tmp__.js` and unlinks it a
+  few milliseconds later. It cannot move that fixture to a tmpdir: `checkAllTracked()` filters its
+  input through the anchored `src/**/*.js` include glob and only then resolves against
+  `process.cwd()`, so a tmpdir path is dropped before the read and the test would assert on an empty
+  violation list. Three suites walk `src/` in parallel jest workers, and a directory listing taken
+  while that file existed followed by a read issued after the unlink threw ENOENT — killing
+  `no-phantom-dependencies.test.js` during collection ("Test suite failed to run") on roughly 1 full
+  run in 2, with `cli-template-args.test.js` and `council/degrade-invariant.test.js` exposed
+  identically (both confirmed failing under a reproduction that widens the collision window). All
+  three now read through the new `tests/helpers/read-if-present.js`, which skips a file that vanished
+  mid-walk and still throws on any non-ENOENT failure, so an unreadable source file stays loud.
+  Pre-existing — reproduces at 0fe6128, unrelated to the graphify integration.
+
+### Internal
+
+- **`finalizeSpendForReopen` extracted to `src/sidecar/reopen-spend.js`**, out of
+  `sidecar/continue.js`, to keep that file under the 300-line gate; `resume.js` was already
+  reaching across into `continue.js` for it, so the shared home is the honest one.
+- **Deleted three unreachable helpers from `scripts/validate-docs.js`** (dead code with no call
+  site remaining after earlier `--check` work landed).
+- **Three doc/marker-freshness gates, all jest-enforced — one genuinely new, two hardened.**
+  `tests/docs-command-coverage.test.js` and the anchor-link gate
+  (`tests/docs-council-toc-anchors.test.js`) both already existed and already ran in CI; this
+  branch hardens them (the former now derives its command list from `bin/amicus.js`'s switch
+  instead of hardcoding five entries, the latter generalizes from one file to sixteen). Only the
+  CLAUDE.md AUTO-marker/cross-link freshness gate in this changelog entry's own commit is genuinely
+  new — `generate-docs --check` had never run in CI before — so a stale `CLAUDE.md` can no longer
+  pass CI silently.
+
+## [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

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.
 
@@ -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.
@@ -106,6 +108,8 @@ flowchart LR
 - **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.
 - **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:
@@ -114,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)**.
 
 ---
@@ -127,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`.
@@ -397,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. |
@@ -440,13 +450,13 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.6.3",
+  "version": "4.7.1",
   "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).
 
 ---
 
@@ -461,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.
@@ -474,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 |
 |------|--------------|
@@ -482,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
   });
 }