amicus 4.9.7 → 4.10.0

package/.claude-plugin/plugin.json

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

@@ -3,6 +3,131 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.10.0] - 2026-09-14
+
+### Added
+
+- **`amicus aliases`** — your model aliases as a standing command: `following` (the shipped
+  pin, moves with releases) vs `pinned` (yours), grouped by vendor; `--review` walks every
+  proposal in a numbered picker (accept a newer same-tier sibling, follow the shipped pin,
+  choose another catalog id, skip, or never ask again — no copy-paste); `--json` for scripts.
+  Without a terminal `--review` prints the list, says it is interactive, and exits 1;
+  `--unpin <name>` removes a pin (a curated name goes back to following, a custom name is
+  deleted); refuses instead when `name` is also your (non-curated) `config.default`, so a
+  delete can never leave the default dangling on a key that no longer resolves — pick a new
+  default first. The sibling comparator behind "newer same-tier sibling" (and shared with the
+  CI alias-pin drift gate, `scripts/check-ci-alias-pins.js`) never reads a size/variant token
+  glued to a number (`20b`, `8x22b`) as a version, so a differently-sized variant is never
+  offered as a sibling of another. (#238, #249)
+
+### Changed
+
+- **A curated alias follows the shipped pin unless you pin it.** A name absent from
+  `config.aliases` resolves to the pin amicus ships (this is how the merge always worked);
+  a present key is a pin. On save, a key equal to the shipped pin is dropped with a Notice —
+  every alias still resolves to the same id it did before. The setup wizard no longer seeds
+  the 21 curated ids; it pins only the default you chose, and only when its live flagship
+  differs from the shipped pin, and says so. (#238 D1/D6/Q9)
+- **The drift report cannot propose a downgrade.** `models --check`'s family fallback-drift
+  line ignores non-authoritative catalog rows and is silent when the OpenRouter namespace was
+  rejected this run. (#238 §5)
+- The `--add-alias` copy-paste hints in `models --check`, model validation and alias repair now
+  point at `amicus aliases --review` where the alias is reviewable there. (#238 D4)
+
+## [4.9.8] - 2026-09-13
+
+### Changed
+
+- **Council legs run as two per-run agents with an explicit tool allowlist.** Stage-1 seats and
+  their retries run as `council-seat` — task mode defaults to `webfetch`, review mode to no tools,
+  and `--tools <a,b,c>` (MCP: `tools`) opts more in, validated against the engine's own declared
+  ids before any leg launches; repair, judge, debate and chair legs run as `council-support` with
+  no tools at all. `task` and `skill` are refused (they spawn or escape the session), as are
+  `edit`/`write`/`apply_patch`/`question`/`invalid`; `--agent Plan|Build` is the escape hatch
+  (`Plan` = the pre-4.9.8 behaviour: edits denied, reads/searches/shell allowed). A local tool
+  needs `--out-dir` outside the project tree and scopes the seats to the tree with
+  `external_directory: deny`. With `read` opted in the seat is denied `.env`, `.env.*` and
+  `.envrc` files at the engine (the match is case-sensitive on Linux; the deny rules are
+  measured to render after the seat's own read allow; the refusal itself is exercised by the
+  release ritual's live run); `grep` and `bash` have no per-file fence. `bash` is outside
+  every fence (run directory, home, network) and the CLI says so when it is opted in; the CLI
+  also prints a Notice for `grep`/`glob` (no per-file fence) and for `--agent Plan` (every leg
+  can run commands); `tools: null` is treated as unset like `agent: null`; an `--agent` run's
+  directory stays inside the project; `--tools` and `--agent` cannot be combined; `todowrite`
+  counts as a tool that never touches the tree. After registration, the run also reads back
+  what the engine actually rendered for each council agent — over the run directory, its
+  `_scratch` support-leg directory, and the project tree when local — and refuses before
+  launch if an `opencode.json`/`.opencode/agent` file the engine loads for that directory (the
+  tree's, or your global config) widened it, or if the engine cannot be asked at all
+  once verification can run — including when the run's own shared OpenCode server fails to
+  start: a default (non-`--agent`) run now refuses before any launch instead of falling back,
+  and the per-wave fallback servers that used to absorb that failure for every run now serve
+  only an `--agent` run, whose verification is skipped by design; a reviewed tree's own config
+  was measured to merge into the registered agent by key order (ruling P2-R33; the
+  unconditional refusal on an unverifiable engine, a failed shared-server start included, is
+  P2-R38/P2-R43, `_scratch` coverage is P2-R39, and the external_directory exemption for the
+  engine's own tool-output cache — resolved XDG-first, matching `auth-json.js`/`engine-log.js`
+  — is narrowed by P2-R40/P2-R42). The tripwire also verifies the council agents' non-permission
+  surface (prompt, model, sampling, options, mode) as rendered, since a tree can set those too
+  (P2-R53); a council agent is registered by replacing any same-name entry; the local-tool
+  placement rule compares physical paths, so a run directory reached through a symlink into the
+  project is refused (P2-R54); the CLI prints a Notice for `read` naming its exact fence;
+  `tools: null` over MCP is unset (P2-R55).
+  Two of the three leg-loss classes in the 2026-09-11 study shared one
+  precondition — a seat reached for a tool it did not need (gemini `grep`/`glob` over the global
+  install, cohere `task {}`) — and this closes that door. Previously every leg ran as the engine's
+  `Plan` agent, which denies file edits but leaves the rest of the tool set available (the
+  study saw seats reach for `grep`, `glob` and `task` under it). (`docs/council.md` § Tool
+  access; spec §4; PR 2 of 3.)
+
+### Fixed
+
+- **Headless legs are no longer declared complete while the engine is still answering.**
+  The stable-idle heuristic (`headless.js`, the v4.4 B4 "measured defect site") now
+  defers to `session.status`: while the engine reports `busy` (or `retry`, provider
+  backoff) and no tool call is live, flat output is treated as activity rather than
+  silence, and the leg waits for its message to finalize. In-flight reasoning and text
+  are invisible to the poller, so a seat that narrated between tool calls and then
+  answered for longer than 60 s was harvested mid-answer — three complete council
+  deliverables were discarded 39–107 s before they finished in the 2026-09-11
+  study (run D0), and the run reported `complete` with no degrades. The B4 bounded
+  tool-settle ceiling is unchanged and still governs whenever a tool call is live. When
+  `session.status` is unavailable the heuristic runs as the fallback it was always meant
+  to be. The trade is explicit: a busy-but-wedged (or permanently retrying) leg that
+  already produced output now runs to its `--timeout` (15 min default) and is named
+  `timeout`, instead of being declared complete at 60 s on a stub; the debug trace
+  names the veto once per flat stretch (and again whenever a non-zero count is reset,
+  e.g. a status flip-flop) and the exit line records the last engine status. When the
+  fallback heuristic ends an unfinalized message the leg logs a warning naming the
+  status it saw, and a retry whose next attempt lies beyond the leg deadline ends the
+  leg at once as `RETRY_BEYOND_DEADLINE` instead of holding the seat (never once the
+  last message has finalized — that leg completes normally — and never while a tool
+  call is live, where the tool-settle ceiling governs).
+  (`docs/superpowers/specs/2026-09-11-council-leg-completion-design.md` §3; PR 1 of 3.)
+- **A seat whose findings nothing could verify is now visible in the report and in the verdict
+  census.** When a Stage-1 response carried no parseable findings block and the bounded repair
+  supplied one, the seat's `runStats` row has carried `findingsUnverified: true` since the repair
+  contract landed (LC-11) — through `tally.json` and `verdict.json` — and died at the renderer:
+  `report.html`'s **What was lost** table held only the degrade sink's records (dead legs and the
+  like), and `seatsReviewed` counted the seat as a full reviewer. Now the report (Markdown and
+  HTML) gains one **What was lost** row per such seat (channel `unverified-repair`: *seat X's
+  findings came from a repair of a response with no findings block — nothing verified them*) and
+  one per refused repair (channel `repair-refused`, naming the code), derived from `runStats` when
+  the report is built — so `amicus council report` on an older `verdict.json` shows them too, and
+  nothing in `run.json`, the exit code or the degrade sink changes. `verdict.json`'s census gains
+  two numbers, `seatsReviewed: {reviewed, unverified, refused, of}` (always written, never more
+  than `reviewed`; older documents still validate) — `refused` (council #248 round 2) counts
+  seats whose repair was refused: they tallied no findings and would otherwise read as full
+  reviewers on every gate surface, and the council-review check title and sticky comment print
+  `(N unverified)` and `(N refused)` when non-zero. A run also prints one `Notice:` line on
+  stderr at the end naming its unverified and refused seats, so a local run is no longer silent
+  about them; the exit code and every artifact are unchanged. The wording never says "stub":
+  the flag also fires on a real review whose trailing JSON block was malformed. Study run D0
+  (three narration stubs, three repairs) now reads `{reviewed: 3, unverified: 3, refused: 0,
+  of: 3}` in `verdict.json` — `seats reviewed: 3 of 3 (3 unverified)` in the sticky comment
+  — with three rows in the report, where it read `{reviewed: 3, of: 3}` and nothing. (#242;
+  `docs/superpowers/specs/2026-09-11-council-leg-completion-design.md` §5; PR 3 of 3.)
+
 ## [4.9.7] - 2026-09-09
 
 Three findings deferred from the v4.9.6 cut, and the two open questions filed beside them. The

package/README.md

@@ -419,6 +419,7 @@ When you don't need a full council — just one other model's take — fork a co
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus watch <id>` | Live-render a fan-out wave, council run, or session from any terminal until it finishes — in-place table on a TTY, `--plain` milestone lines, or `--json` NDJSON; exit code maps the terminal state. `--ui` opens the [Council Workspace](./docs/council.md#council-workspace-gui) window instead (interactive-only, no `--json`). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
+| `amicus aliases` | Your model aliases — following / pinned; `--review` walks the update proposals, `--unpin <name>` removes a pin, `--json` for scripts. |
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
 | `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
@@ -455,7 +456,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.7",
+  "version": "4.10.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -165,6 +165,11 @@ async function main() {
         exitCode = await handleModels(args);
         break;
       }
+      case 'aliases': {
+        const { handleAliases } = require('../src/sidecar/aliases');
+        exitCode = await handleAliases(args);
+        break;
+      }
       case 'council': {
         const { handleCouncil } = require('../src/cli-handlers-council');
         exitCode = await handleCouncil(args);

package/docs/ROADMAP.md

@@ -13,13 +13,14 @@ lives under **Backlog (tracked, not scheduled)** with everything else that is re
 Nothing about the content changed and no judgment about its value is implied; only its status. When
 an org buyer and the org to support them exist, it earns a number then.
 
-Amicus is at **v4.9.7** (2026-09-09). Each 4.x rev below leads with the benefit, not the
-plumbing; the patch releases since v4.9.0 carry no section of their own, because each corrected a
+Amicus is at **v4.10.0** (2026-09-14). Each 4.x rev below leads with the benefit, not the
+plumbing; the v4.9.x patch releases carry no section of their own, because each corrected a
 defect rather than adding scope — where one added a surface (v4.9.4's `--thinking` refusals and
-`output-budget` doctor row, v4.9.5's Electron digest gate, v4.9.6's artifact custody, v4.9.7's dual name-table rescue boundary) it did so to
-make an existing promise true, not to widen it. See `CHANGELOG.md` for what each one contained.
+`output-budget` doctor row, v4.9.5's Electron digest gate, v4.9.6's artifact custody, v4.9.7's dual name-table rescue boundary, v4.9.8's per-run seat tool allowlist and its unverified/refused seat census) it did so to
+make an existing promise true, not to widen it. v4.10.0 adds a surface (`amicus aliases`) and so
+gets a section. See `CHANGELOG.md` for what each one contained.
 
-**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.7 patch releases —
+**Status:** v4.0 through **v4.10.0** have **shipped**, plus the v4.9.1–v4.9.8 patch releases —
 everything on this page is a record of what landed, not a plan. Composition — the scope that
 carried the number v4.6 here until the degrade-announcement-invariant milestone took the v4.6.0
 release (2026-08-02) — is now an unscheduled candidate for the next rev, tabled in its own section
@@ -447,6 +448,33 @@ a verdict about a review that never happened.
 > to do* — announcing losses, counting money, attributing seats. v4.9 changes what a council can be
 > asked for in the first place, which is a different kind of rev and is scoped as one.
 
+## v4.10 — "Your aliases follow the pins" *(follow-or-pin aliases — #238 Phase 1)* — ✅ SHIPPED v4.10.0, 2026-09-14
+**Benefit:** a curated alias tracks the pin amicus ships until you deliberately pin it, and
+`amicus aliases` shows which is which and walks every worthwhile change in a numbered picker —
+no more copy-pasting `--add-alias` lines out of `models --check`.
+
+- **★ `amicus aliases`** — every alias as `following` (the shipped pin, moves with releases) or
+  `pinned` (yours), grouped by vendor; `--review` proposes one change per pinned alias (a strictly
+  newer same-tier sibling, the shipped pin, a same-vendor replacement for an id gone from the
+  catalog) and accepts, skips or dismisses it in place; `--json` for scripts; `--unpin <name>`
+  removes a pin (a curated name goes back to following, a custom name is deleted, the alias your
+  default points at is refused). **Closes the user half of #238** *(L)*
+- **Absence is follow** — a name absent from `config.aliases` resolves to the shipped pin, a
+  present key is a pin, and a key equal to the shipped pin is dropped on save with a Notice; the
+  setup wizard stops seeding the 21 curated ids and pins only the default you chose, and only when
+  its live flagship differs from the shipped one *(M)*
+- **The drift report cannot propose a downgrade** — `models --check`'s fallback-drift line ignores
+  non-authoritative catalog rows and is silent when the OpenRouter namespace was rejected *(S)*
+- **The sibling comparator is tier-safe** — lifted out of the CI alias-pin drift gate and shared
+  with it; a size or variant token glued to a number (`20b`, `8x22b`, `4o`) is never read as a
+  version, so a differently-sized model is never offered as a "newer" sibling *(S)*
+> Why here: the two council rounds on #249 (16 + 13 findings) shaped the release — the typed
+> shipped id follows without a catalog, the comparator's size rule, the `--unpin` default guard
+> and the terminal-escape sanitizer on every alias surface all came out of them. Phases 2–4 of
+> the #238 design (owner mode with `curated-pins.json`, the Electron "Needs review" section, the
+> quiet update notice) are unscheduled; the spec that scopes them ships in the repo under
+> `docs/superpowers/specs/`.
+
 ## Backlog (tracked, not scheduled)
 
 ### Enterprise-readiness *(unscheduled — gated on funding / cofounder)*

package/docs/architecture-map.md

@@ -38,6 +38,7 @@ src/
 │   ├── presets-cli.js
 │   ├── report-cost.js
 │   ├── report-html.js
+│   ├── report-lost-rows.js
 │   ├── report-md.js
 │   ├── report.js
 │   ├── run-assemble.js
@@ -56,6 +57,8 @@ src/
 │   ├── run-retry-notes.js
 │   ├── run-retry-window.js  # The Stage-1 retry's no-output window: how long a RELAUNCHED leg may stay
 │   ├── run-retry.js
+│   ├── run-seat-tools-verify.js  # The engine-rendering tripwire's pure pieces, plus `verificationDirectories`'
+│   ├── run-seat-tools.js
 │   ├── run-server.js
 │   ├── run-stage1-launch.js  # Stage-1 launch pass for the council engine.
 │   ├── run-stage1-rows.js
@@ -66,6 +69,7 @@ src/
 │   ├── run-stats-entry.js
 │   ├── run-verdict-files.js
 │   ├── run.js
+│   ├── seat-tools.js
 │   ├── seats.js
 │   ├── stage1-bind.js
 │   ├── street-cred.js
@@ -102,6 +106,11 @@ src/
 ├── prompts/
 │   └── cowork-agent-prompt.js  # Cowork Agent Prompt
 ├── sidecar/
+│   ├── aliases-review-gate.js  # Pure §5-gate helpers for `amicus aliases --review` (#249 r1 R2/R3), split
+│   ├── aliases-review-prompt.js  # The real-readline prompt for `amicus aliases --review`, split out of
+│   ├── aliases-review-render.js  # Pure, side-effect-free screen text for `amicus aliases --review` (#238 §4),
+│   ├── aliases-review.js  # `amicus aliases --review` (#238 §4): a numbered readline picker over the
+│   ├── aliases.js  # `amicus aliases` (#238 D4) — the user's alias map as a standing command.
 │   ├── budget.js
 │   ├── child-sessions.js
 │   ├── context-builder.js  # Context Builder Module
@@ -135,6 +144,7 @@ src/
 │   ├── fanout-validate.js
 │   ├── fanout-wave-io.js
 │   ├── fanout.js
+│   ├── heartbeat.js
 │   ├── interactive-abort.js
 │   ├── interactive-mirror.js
 │   ├── interactive-process.js  # Sidecar Interactive Process Helpers - Electron probe/env/process-exit plumbing
@@ -180,9 +190,13 @@ src/
 │   ├── activity-poller.js
 │   ├── agent-mapping.js  # Agent Mapping Module
 │   ├── alias-audit.js  # Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3).
+│   ├── alias-groups.js  # Vendor-derived alias grouping (issue 213). Moved VERBATIM out of
+│   ├── alias-proposals.js  # The alias review ENGINE (#238 §2): pure, no I/O, no prompts. Turns
 │   ├── alias-resolver.js  # Alias Resolver Utilities
 │   ├── alias-shadow-writer.js  # The alias-shadow notice's WRITE half: say it without ever sinking the run.
 │   ├── alias-shadow.js  # Alias-shadow self-diagnosis — name a local alias that repoints a curated one.
+│   ├── alias-state.js  # Following-vs-pinned state for model aliases (#238 D1) and the normalization
+│   ├── alias-store.js  # The write sinks the alias review flow needs beyond `setup.js :: addAlias`
 │   ├── api-key-store.js  # API Key Store — reading, saving, and validating API keys.
 │   ├── api-key-validation.js  # API Key Validation — test API keys against provider endpoints.
 │   ├── atomic-write.js  # Atomic file write helper.
@@ -247,6 +261,7 @@ src/
 │   ├── model-classification.js  # Tri-state catalog classification (#61).
 │   ├── model-descriptor.js  # Model-descriptor grammar + RouteResult factories (#61).
 │   ├── model-fetcher.js  # Model Fetcher
+│   ├── model-id-siblings.js  # The tier-safe sibling comparator (#238 D7). A sibling shares a pin's vendor
 │   ├── model-input-default.js
 │   ├── model-output-limit.js  # Issue #218 — the per-model `limit` descriptor amicus hands opencode.
 │   ├── model-shortlist.js  # Vendor model shortlist (#138) -- the family -> model second level.
@@ -308,6 +323,7 @@ src/
 │   └── seat-space.js  # Council Workspace — the seat-space PREDICATES (v4.8 PR5b).
 ├── cli-council-run-bench.js  # Bench and input resolution for the council run command.
 ├── cli-council-run-render.js
+├── cli-council-run-tools.js  # `--tools`/`--agent` validation and the v4.7 out-dir fence for `council run`.
 ├── cli-handlers-abort.js  # CLI Abort Handler (B21-rest extraction)
 ├── cli-handlers-council-run.js
 ├── cli-handlers-council.js
@@ -336,6 +352,7 @@ src/
 ├── jsonl-parser.js  # JSONL Parser
 ├── mcp-council-awareness.js
 ├── mcp-council-bench.js
+├── mcp-council-pack-map.js  # COUNCIL_PACK_PARAM_MAP, split out of mcp-council-run.js for the 300-line size gate (P2-R16).
 ├── mcp-council-run.js
 ├── mcp-notify.js  # Pure helpers + in-process registry for the MCP `onComplete: 'mcp-notify'`
 ├── mcp-server.js  # @module mcp-server — Amicus MCP Server (stdio transport)
@@ -419,6 +436,7 @@ scripts/
 ├── integration-test.sh
 ├── mark-test-passed.js  # Writes the current git HEAD SHA to .test-passed for the pre-push SHA cache
 ├── postinstall.js  # Post-install script for amicus
+├── probe-council-agents.js  # Spec 2026-09-11 §4 — the ENGINE side of the council agents (ruling P2-R21).
 ├── probe-darwin-extract.js
 ├── probe-max-tokens.js  # Wire probe for issue #218: what max_tokens / reasoning / thinking does the
 ├── run-integration-keyless.js
@@ -452,6 +470,7 @@ evals/
 |--------|---------|-------------|
 | `cli-council-run-bench.js` | Bench and input resolution for the council run command. | `resolveBench()`, `resolveChair()`, `resolveCritic()`, `CHAIR_DEFAULT()`, `parseList()` |
 | `cli-council-run-render.js` |  | `renderRunHuman()` |
+| `cli-council-run-tools.js` | `--tools`/`--agent` validation and the v4.7 out-dir fence for `council run`. | `checkCouncilRunTools()` |
 | `cli-handlers-abort.js` | CLI Abort Handler (B21-rest extraction) | `handleAbort()` |
 | `cli-handlers-council-run.js` |  | `handleCouncilRun()`, `renderRunHuman()`, `CHAIR_DEFAULT()` |
 | `cli-handlers-council.js` |  | `handleCouncil()` |
@@ -480,6 +499,7 @@ evals/
 | `jsonl-parser.js` | JSONL Parser | `parseJSONLLine()`, `readJSONL()`, `extractTimestamp()`, `formatMessage()`, `formatContext()` |
 | `mcp-council-awareness.js` |  | `subWaveIds()`, `countWaveLegs()`, `elapsedOf()`, `enginePid()`, `buildCouncilStatusPayload()` |
 | `mcp-council-bench.js` |  | `resolveBenchInput()`, `auditBenchAliases()` |
+| `mcp-council-pack-map.js` | COUNCIL_PACK_PARAM_MAP, split out of mcp-council-run.js for the 300-line size gate (P2-R16). | `COUNCIL_PACK_PARAM_MAP()` |
 | `mcp-council-run.js` |  | `handleCouncilRunTool()`, `COUNCIL_PACK_PARAM_MAP()`, `buildCouncilStatusPayload()`, `listCouncilRuns()`, `abortCouncilRun()` |
 | `mcp-notify.js` | Pure helpers + in-process registry for the MCP `onComplete: 'mcp-notify'` | `validateOnComplete()`, `buildNotifyPayload()`, `requestMcpNotify()`, `consumeMcpNotify()` |
 | `mcp-server.js` | @module mcp-server — Amicus MCP Server (stdio transport) | `handlers()`, `startMcpServer()`, `getProjectDir()`, `resolveProjectDir()`, `getClientRoot()` |
@@ -494,7 +514,7 @@ evals/
 | `spend-query.js` |  | `filterRows()`, `groupRows()`, `computeWasted()`, `emptyTokens()`, `addTokens()` |
 | `council/anonymize.js` |  | `assignLabels()`, `toGlobalId()`, `toGlobalFindings()`, `rankingToOrder()`, `LETTERS()` |
 | `council/briefings-chair-task.js` |  | `CHAIR_ANSWER_VALUES()`, `ANSWER_SCALE_ADDENDUM()`, `TASK_CHAIR_SYNTHESIS()`, `TASK_CHAIR_SYNTHESIS_NO_CLAIMS()`, `TASK_CONCURRENCE_CAVEAT()` |
-| `council/briefings-chair.js` |  | `dateLine()`, `CHAIR_NO_TOOLS_PREAMBLE()`, `chairRepairPromptFor()`, `CHAIR_VERDICT_VALUES()`, `VERDICT_SCALE_ADDENDUM()` |
+| `council/briefings-chair.js` |  | `dateLine()`, `CHAIR_NO_TOOLS_LEAD()`, `CHAIR_NO_TOOLS_PREAMBLE()`, `chairRepairPromptFor()`, `CHAIR_VERDICT_VALUES()` |
 | `council/briefings-debate.js` |  | `DEBATE_NO_TOOLS_PREAMBLE()`, `DEFENSE_CONTRACT()`, `REVOTE_CONTRACT()`, `buildDefenseBrief()`, `buildRevoteBundle()` |
 | `council/briefings-stage2-task.js` |  | `TASK_JUDGE_FRAME()`, `TASK_JUDGE_A()`, `TASK_JUDGE_B()`, `TASK_JUDGE_B_NO_CLAIMS()`, `NO_CLAIMS_INDEX()` |
 | `council/briefings-stage2.js` |  | `JUDGE_NO_TOOLS_PREAMBLE()`, `CHAIR_NO_TOOLS_PREAMBLE()`, `CHAIR_VERDICT_VALUES()`, `JUDGE_OUTPUT_CONTRACT()`, `VERDICT_SCALE_ADDENDUM()` |
@@ -511,6 +531,7 @@ evals/
 | `council/presets-cli.js` |  | `runSave()`, `runList()`, `runShow()` |
 | `council/report-cost.js` |  | `buildCostModel()` |
 | `council/report-html.js` |  | `renderHtml()` |
+| `council/report-lost-rows.js` |  | `lostRowsOf()` |
 | `council/report-md.js` |  | `renderMd()` |
 | `council/report.js` |  | `buildReport()`, `toModel()`, `TIER_ORDER()`, `SYMBOL()`, `isSeatSpace()` |
 | `council/run-assemble.js` |  | `buildRunStatsEntry()`, `worseConformance()`, `buildTallyInput()`, `writeTallyFiles()`, `writeVerdictFiles()` |
@@ -519,7 +540,7 @@ evals/
 | `council/run-debate-revote.js` |  | `legOpts()`, `legRow()`, `runRevoteWave()` |
 | `council/run-debate-stage.js` |  | `runDebateStage()` |
 | `council/run-debate.js` |  | `runDebate()`, `nothingToDebate()`, `disputingJudges()`, `debateTargets()` |
-| `council/run-degrade.js` |  | `createDegradeSink()` |
+| `council/run-degrade.js` |  | `createDegradeSink()`, `noteDroppedMembers()` |
 | `council/run-finalize.js` |  | `statusForExit()`, `resolveTerminalExit()`, `writeRunTerminal()`, `SIGNAL_EXIT()` |
 | `council/run-finish.js` |  | `finishRun()` |
 | `council/run-launch.js` |  | `createLaunchers()`, `materializeReviews()`, `materializeDebate()`, `sanitizeName()`, `isAbortExit()` |
@@ -529,7 +550,9 @@ evals/
 | `council/run-retry-notes.js` |  | `waveStillDeadNote()`, `skippedWaveNote()`, `srcLegStillDeadNote()`, `retryLegStillDeadNote()`, `missingLegStillDeadNote()` |
 | `council/run-retry-window.js` | The Stage-1 retry's no-output window: how long a RELAUNCHED leg may stay | `retryBackstopMs()` |
 | `council/run-retry.js` |  | `groupStage1Losses()`, `retryStage1Losses()` |
-| `council/run-server.js` |  | `acquireRunServer()`, `releaseRunServer()`, `resolveRunServerModels()`, `recordServerFate()` |
+| `council/run-seat-tools-verify.js` | The engine-rendering tripwire's pure pieces, plus `verificationDirectories`' | `verificationDirectories()`, `listEngineAgents()`, `verifyAgentRendering()`, `verifyAgentFields()`, `resolvePhysicalPath()` |
+| `council/run-seat-tools.js` |  | `preflightSeatTools()`, `validateSeatToolsAgainstEngine()`, `listEngineAgents()`, `verifyAgentRendering()`, `verifyAgentFields()` |
+| `council/run-server.js` |  | `acquireRunServer()`, `releaseRunServer()`, `resolveRunServerModels()`, `recordServerFate()`, `listEngineToolIds()` |
 | `council/run-stage1-launch.js` | Stage-1 launch pass for the council engine. | `launchStage1()` |
 | `council/run-stage1-rows.js` |  | `pushDeadSeatRows()`, `supersededRows()` |
 | `council/run-stage1-superseded.js` |  | `supersededRows()` |
@@ -539,12 +562,13 @@ evals/
 | `council/run-stats-entry.js` |  | `buildRunStatsEntry()` |
 | `council/run-verdict-files.js` |  | `writeVerdictFiles()` |
 | `council/run.js` |  | `runCouncil()`, `pickFallbackChair()`, `SIGNAL_EXIT()` |
+| `council/seat-tools.js` |  | `REFUSED_TOOL_IDS()`, `REMOTE_TOOL_IDS()`, `NON_LOCAL_TOOL_IDS()`, `SEAT_READ_DENY_PATTERNS()`, `defaultToolsFor()` |
 | `council/seats.js` |  | `buildSeats()`, `roleAt()`, `bindSeats()`, `artifactName()`, `displayName()` |
 | `council/stage1-bind.js` |  | `bindStage1Waves()`, `orphanLegNote()`, `missingSeatDeadWave()`, `bindPaddedWave()` |
 | `council/street-cred.js` |  | `computeStreetCred()`, `rankPositions()`, `credSeats()` |
 | `council/tally.js` |  | `assignTier()`, `computeStreetCred()`, `tally()`, `COUNCIL_SCHEMA_VERSION()` |
 | `council/verdict-seat-loss.js` |  | `summarizeSeatLoss()`, `deriveSeatLoss()` |
-| `council/verdict-seats-reviewed.js` | #202: the bench-seat census for verdict.json, as a spreadable fragment. | `seatsReviewedOf()` |
+| `council/verdict-seats-reviewed.js` | #202: the bench-seat census for verdict.json, as a spreadable fragment. | `seatsReviewedOf()`, `isBenchRole()`, `isUnverifiedSeat()`, `isRefusedSeat()`, `seatLabel()` |
 | `council/verdict.js` |  | `buildVerdict()`, `summarizeSeatLoss()`, `deriveSeatLoss()`, `readOverallVerdict()`, `readPriorVerdictSurfaces()` |
 | `design/tokens.js` |  | `tokenCss()`, `TOKENS()` |
 | `observe/council-legs.js` |  | `buildLegRows()` |
@@ -559,6 +583,11 @@ evals/
 | `pack/pack-store.js` |  | `packsDir()`, `canonicalHash()`, `resolvePackRef()`, `readPack()`, `writePack()` |
 | `pack/pack-validate.js` |  | `validatePack()`, `KIND_OPTIONS()`, `KINDS()` |
 | `prompts/cowork-agent-prompt.js` | Cowork Agent Prompt | `buildCoworkAgentPrompt()` |
+| `sidecar/aliases-review-gate.js` | Pure §5-gate helpers for `amicus aliases --review` (#249 r1 R2/R3), split | `classifyTypedId()`, `notInCatalogLine()`, `notVerifiedLine()`, `staleCatalogBanner()` |
+| `sidecar/aliases-review-prompt.js` | The real-readline prompt for `amicus aliases --review`, split out of | `createPrompt()` |
+| `sidecar/aliases-review-render.js` | Pure, side-effect-free screen text for `amicus aliases --review` (#238 §4), | `ageLabel()`, `menuFor()`, `menuLineText()`, `renderScreen()`, `refreshingCatalogLine()` |
+| `sidecar/aliases-review.js` | `amicus aliases --review` (#238 §4): a numbered readline picker over the | `runReview()` |
+| `sidecar/aliases.js` | `amicus aliases` (#238 D4) — the user's alias map as a standing command. | `handleAliases()`, `collectAliasView()`, `renderAliasList()`, `buildAliasesDoc()`, `loadDeps()` |
 | `sidecar/budget.js` |  | `checkBudget()`, `formatBudgetError()`, `DEFAULT_MAX_COST_PER_MTOK()`, `ASSUMED_OUTPUT_TOKENS()` |
 | `sidecar/child-sessions.js` |  | `collectSubtreeUsage()`, `subtreeIsUnknown()`, `SUBTREE_MAX_DEPTH()`, `SUBTREE_MAX_SESSIONS()` |
 | `sidecar/context-builder.js` | Context Builder Module | `buildContext()`, `parseDuration()`, `resolveSessionFile()`, `applyContextFilters()`, `findCoworkSession()` |
@@ -592,6 +621,7 @@ evals/
 | `sidecar/fanout-validate.js` |  | `parseModelsList()`, `DEFAULT_MAX_LEGS()`, `validateFanoutModels()` |
 | `sidecar/fanout-wave-io.js` |  | `writeWaveMetadata()`, `writeWaveDoc()`, `finishWave()`, `stampLegAttribution()` |
 | `sidecar/fanout.js` |  | `parseModelsList()`, `deriveLegIds()`, `validateFanoutModels()`, `DEFAULT_MAX_LEGS()`, `runFanout()` |
+| `sidecar/heartbeat.js` |  | `HEARTBEAT_INTERVAL()`, `createHeartbeat()` |
 | `sidecar/interactive-abort.js` |  | `startAbortWatch()`, `markResultAborted()`, `readAbortedMarker()`, `DEFAULT_INTERVAL_MS()` |
 | `sidecar/interactive-mirror.js` |  | `startInteractiveMirror()` |
 | `sidecar/interactive-process.js` | Sidecar Interactive Process Helpers - Electron probe/env/process-exit plumbing | `getElectronPath()`, `checkElectronAvailable()`, `buildElectronEnv()`, `handleElectronProcess()` |
@@ -635,9 +665,13 @@ evals/
 | `utils/activity-poller.js` |  | `createActivityPoller()`, `killIfAlive()` |
 | `utils/agent-mapping.js` | Agent Mapping Module | `PRIMARY_AGENTS()`, `OPENCODE_AGENTS()`, `HEADLESS_SAFE_AGENTS()`, `mapAgentToOpenCode()`, `isValidAgent()` |
 | `utils/alias-audit.js` | Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3). | `collectAliasSources()`, `findStaleAliases()`, `findDriftedStoredAliases()`, `suggestReplacements()`, `findFabricatedAliasRepairs()` |
+| `utils/alias-groups.js` | Vendor-derived alias grouping (issue 213). Moved VERBATIM out of | `groupAliases()`, `aliasVendorOf()`, `vendorLabel()`, `titleCaseVendor()`, `PREFERRED_VENDOR_ORDER()` |
+| `utils/alias-proposals.js` | The alias review ENGINE (#238 §2): pure, no I/O, no prompts. Turns | `buildAliasProposals()`, `gatedCatalogIds()` |
 | `utils/alias-resolver.js` | Alias Resolver Utilities | `autoRepairAlias()` |
 | `utils/alias-shadow-writer.js` | The alias-shadow notice's WRITE half: say it without ever sinking the run. | `safeWrite()`, `armStream()`, `writeNoticeToStderr()` |
 | `utils/alias-shadow.js` | Alias-shadow self-diagnosis — name a local alias that repoints a curated one. | `findAliasShadows()`, `formatAliasShadow()`, `noteAliasShadows()`, `auditAliasShadows()` |
+| `utils/alias-state.js` | Following-vs-pinned state for model aliases (#238 D1) and the normalization | `normalizeAliases()`, `listAliasRows()`, `isCurated()` |
+| `utils/alias-store.js` | The write sinks the alias review flow needs beyond `setup.js :: addAlias` | `removeAlias()`, `readDismissals()`, `recordDismissal()` |
 | `utils/api-key-store.js` | API Key Store — reading, saving, and validating API keys. | `getEnvPath()`, `loadEnvEntries()`, `readApiKeys()`, `readApiKeyHints()`, `readApiKeyValues()` |
 | `utils/api-key-validation.js` | API Key Validation — test API keys against provider endpoints. | `validateApiKey()`, `redactSecret()`, `validateOpenRouterKey()`, `checkOpenRouterCredit()`, `OPENROUTER_NO_CREDIT_WARNING()` |
 | `utils/atomic-write.js` | Atomic file write helper. | `writeFileAtomic()` |
@@ -702,6 +736,7 @@ evals/
 | `utils/model-classification.js` | Tri-state catalog classification (#61). | `classifyModel()` |
 | `utils/model-descriptor.js` | Model-descriptor grammar + RouteResult factories (#61). | `GATEWAY_MODES()`, `parseDescriptor()`, `resolved()`, `selectionRequired()`, `routeError()` |
 | `utils/model-fetcher.js` | Model Fetcher | `fetchModelsFromProvider()`, `fetchAllModels()`, `fetchAllModelsDetailed()`, `fetchModelsFromProviderDetailed()`, `providersToFetch()` |
+| `utils/model-id-siblings.js` | The tier-safe sibling comparator (#238 D7). A sibling shares a pin's vendor | `parsePin()`, `compareVersions()`, `newestSibling()` |
 | `utils/model-input-default.js` |  | `resolveModelInputOrDefault()` |
 | `utils/model-output-limit.js` | Issue #218 — the per-model `limit` descriptor amicus hands opencode. | `normalizeOutputBudget()`, `buildLimitLookup()`, `computeModelLimit()`, `positiveCount()` |
 | `utils/model-shortlist.js` | Vendor model shortlist (#138) -- the family -> model second level. | `buildModelShortlist()`, `compareShortlistRows()`, `SHORTLIST_LIMIT()` |
@@ -721,7 +756,7 @@ evals/
 | `utils/provider-default-picker.js` | Provider-default picker core (Part 2, Task 4). | `buildProviderDefaultChoices()`, `applyProviderDefault()`, `pricePerMInputFrom()`, `directFormIfSafe()`, `directFormIfProven()` |
 | `utils/provider-default-prompt.js` | Provider-default prompt flow (Part 2, Task 6/7 shared helper). | `runProviderDefaultFlow()`, `formatPrice()`, `formatRow()` |
 | `utils/provider-registry.js` | Provider-capability registry — the single source of truth for provider | `PROVIDERS()`, `getProvider()`, `isDirectProvider()`, `listDirectProviders()`, `PROVIDER_ENV_MAP()` |
-| `utils/quick-picks.js` | Quick-pick resolution (wizard Step 2) — resolves each curated family to | `compareIdsDesc()`, `canonicalRoutesFor()`, `pickCurrent()`, `resolveQuickPicks()`, `toLiveSeedAliases()` |
+| `utils/quick-picks.js` | Quick-pick resolution (wizard Step 2) — resolves each curated family to | `compareIdsDesc()`, `canonicalRoutesFor()`, `pickCurrent()`, `resolveQuickPicks()`, `toStorableRoute()` |
 | `utils/read-slice.js` | Byte-bounded slicing for amicus_read (15a.3 / B17). | `sliceForRead()`, `READ_CAP_BYTES()` |
 | `utils/remediation-hints.js` |  |  |
 | `utils/result-schema-rebuild.js` |  | `buildRunResultFromSession()`, `buildWaveResultFromSession()` |
@@ -742,7 +777,7 @@ evals/
 | `utils/shared-server.js` |  | `SharedServerManager()` |
 | `utils/spend-ledger.js` |  | `appendSpend()`, `readSpendRows()`, `SPEND_LEDGER_FILE()`, `SPEND_LEDGER_SCHEMA_VERSION()` |
 | `utils/start-helpers.js` | Start Command Helpers | `resolveLaunchModel()`, `deriveAlias()`, `maybeOfferProviderDefaults()` |
-| `utils/text-sanitize.js` | One third-party string, safe to render: no escapes, no bidi, one short line. | `collapseExcerpt()`, `MAX_EXCERPT_CHARS()` |
+| `utils/text-sanitize.js` | One third-party string, safe to render: no escapes, no bidi, one short line. | `collapseExcerpt()`, `MAX_EXCERPT_CHARS()`, `safeFragment()`, `MAX_FRAGMENT_CHARS()` |
 | `utils/thinking-validators.js` | Thinking Level Validators | `VARIANT_LEVELS()`, `validateThinkingLevel()` |
 | `utils/ttft.js` | The one honesty predicate for the time-to-first-token probe (v4.9 W13). | `isMeasuredTtft()` |
 | `utils/untrusted-fence.js` | Untrusted sidecar output fence. | `fenceSidecarOutput()`, `defangOutboundFenceTags()`, `OUTBOUND_FENCE_TAGS()` |

package/docs/configuration.md

@@ -540,7 +540,7 @@ amicus models --check && echo "aliases ok"
 
 ## Model Aliases
 
-Aliases are short names that resolve to full provider-prefixed model IDs. `amicus setup` seeds a curated default set (e.g. `gemini`, `gpt`, `opus`, `deepseek`) to the bare canonical form for direct-capable vendors. You add or override aliases with:
+Aliases are short names that resolve to full provider-prefixed model IDs. Amicus ships a curated set (`gemini`, `gpt`, `opus`, `deepseek`, `claude`, `glm`, …) that resolves to the pins the package ships — an alias you have not pinned FOLLOWS those pins and moves with each release. `amicus setup` no longer copies them into your config; it pins only the default alias you chose, and only when its live flagship differs from the shipped pin. See `amicus aliases` for what resolves on your machine. You add or override aliases with:
 
 ```bash
 amicus setup --add-alias fast=google/gemini-3.1-flash-lite-preview
@@ -671,14 +671,14 @@ level includes everything above it.
   // Default alias, resolved via `aliases` below when --model is omitted.
   "default": "gemini",
 
-  // Short name -> full model id. Bare `provider/model` (canonical) routes direct-first;
-  // `amicus setup` seeds direct-capable vendors this way automatically.
-  // `amicus setup --add-alias name=provider/model` adds more.
+  // Short name -> full model id, for the aliases YOU pinned. A curated alias
+  // (gemini, gpt, opus, …) that is ABSENT here FOLLOWS the pin amicus ships and
+  // moves with each release; a present key is pinned and reviewable with
+  // `amicus aliases --review`. A key equal to the shipped pin is dropped on save
+  // (with a Notice) — it is the same as following.
   "aliases": {
-    "gemini": "google/gemini-3-pro-preview",
-    "gpt": "openai/gpt-5",
-    "opus": "anthropic/claude-opus-4",
-    "deepseek": "deepseek/deepseek-v3"
+    "glm": "openrouter/z-ai/glm-5.4",
+    "fast": "google/gemini-3.6-flash-lite"
   },
 
   // Named council member lists, e.g. seeded by the Free OpenRouter council
@@ -700,6 +700,12 @@ level includes everything above it.
     "tier_onboarded": true
   },
 
+  // Written by `amicus aliases --review`'s "never ask again" — keyed
+  // `alias@proposedId`; hand-delete a key here to be asked again.
+  "aliasReview": {
+    "dismissed": { "glm@openrouter/z-ai/glm-5.4": "2026-09-14T00:00:00.000Z" }
+  },
+
   // User-defined local / OpenAI-compatible providers (v4.2) — written by
   // `amicus provider add`, or hand-edited. id -> normalized entry; `pricing`
   // defaults to {prompt: 0, completion: 0} (the $0 tier) when omitted.