amicus 4.8.0 → 4.9.0

package/docs/usage.md

@@ -203,6 +203,7 @@ amicus council run --prompt-file briefing.md --models gemini,glm --chair deepsee
 | `--artifact <file>` | File whose content fills `{{artifact}}`/`{{artifact_path}}` (256 KB cap). Requires `--template`. |
 | `--var <k=v>` | Set `{{var.<key>}}`; repeatable. Requires `--template`. |
 | `--tag <t>` | Label this run for `list`/`--search`/`spend --group-by tag` (1-64 chars, `[A-Za-z0-9_-]`; rejected, not cleaned). Every stage's sub-waves (Stage-1, critic/lens solos, Stage-2, chair, debate) carry the same tag on their wave metadata. |
+| `--intent <review\|task>` | The run's intent (v4.9). `review` — the default — is never stored; `task` marks a task-mode run, recorded as `intent: "task"` on `run.json`/`verdict.json` and kept out of the reliability ledger. Over MCP: the `intent` param on `amicus_council_run`, and a hand-assembled `amicus_council_tally` input may carry `meta.intent` the same emit-when-`task` way. What forks stage by stage — and what stays byte-identical — is in [docs/council.md § Task mode](./council.md#task-mode---intent-task). |
 
 **Exit codes:** `0` full run · `2` degraded but reportable (fewer than 2 judges, chair failure —
 `overallVerdict: null` — a cost ceiling hit after the tally, or a `--max-cost` ceiling set over a
@@ -403,7 +404,7 @@ Each stored alias resolves to one of three outcomes:
 | Outcome | Example line | Meaning |
 |---------|--------------|---------|
 | `SERVED` | `SERVED: gemini -> openrouter/google/gemini-3.6-flash ($0.0004)` | The model answered; cost shown in parens. |
-| `SILENT` (`accepted-but-silent`) | `SILENT: probetest -> anthropic/claude-opus-4-8 — NO_OUTPUT_BACKSTOP: … (accepted but not serving)` | Nothing arrived at all within the probe's 30 s backstop window — shorter than the ordinary 300 s leg default, and not tunable. ⚠️ `accepted-but-silent` is the CLASSIFICATION's name, not a proven fact about the endpoint: a fired backstop shows only that no output, reasoning or tool call arrived in the window, which a stalled gateway or a dropped connection produces just as readily as a model that accepted and then said nothing. Either way it is the "listed but not actually serving" failure this check exists to catch. |
+| `SILENT` (`accepted-but-silent`) | `SILENT: probetest -> anthropic/claude-opus-4-8 — NO_OUTPUT_BACKSTOP: … (no output within the probe window)` | Nothing arrived at all within the probe's 30 s backstop window — shorter than the ordinary 300 s leg default, and not tunable. ⚠️ `accepted-but-silent` is the CLASSIFICATION's name, not a proven fact about the endpoint: a fired backstop shows only that no output, reasoning or tool call arrived in the window, which a stalled gateway or a dropped connection produces just as readily as a model that accepted and then said nothing. Either way it is the "listed but not actually serving" failure this check exists to catch. |
 | `ERROR` | `ERROR:  gpt -> openai/gpt-5.6-terra — 402 Payment Required` | Routing, auth, or provider failure; the raw error is printed. |
 
 **Exit code.** The probe's non-served count folds into the same exit code as the static audit — `max(existing exit, min(nonServedCount, 100))` — so a single `SILENT` or `ERROR` fails the check even when every alias is otherwise catalog-fresh. No stored aliases prints `Live probe: no stored aliases to probe` and never affects the exit code. `--json` adds `probe` (the per-alias array) and `probeCount` (its length) to the `alias-audit` document — both additive, `[]`/`0` when `--live` wasn't passed.
@@ -464,12 +465,31 @@ amicus setup --add-alias fast=google/gemini-2.5-flash   # Add/override one alias
 the same core fields everywhere: `id`, `model`, `status`, `mode` (`interactive`/`headless`),
 `type` (`run` by default), `parentWave` (`null` unless the row is a fan-out leg), `legCount`
 (`null` unless the row is a wave), and `tag` — the one field that's omitted, not `null`, when the
-session has none. The human-readable CLI table adds a `TAG` column. Council-run rows are an
-**MCP-only** row class: the CLI's own directory scan skips their `council-<runId>.json` pointer
-files (a pointer's filename fails the session-ID pattern every other row's directory name must
-match), so `amicus list` never shows a council run — only the MCP `amicus_list` tool merges them
-in, each carrying `type: 'council-run'`, a fixed `mode: 'headless'`, and its own 80-char sanitized
-`briefing` preview plus a `stage` field naming whichever stage is currently running. The MCP tool
+session has none. The human-readable CLI table adds a `TAG` column. Council-run rows join the
+listing on **both surfaces** through a separate merge (`src/sidecar/list-council.js`): the
+directory scan itself still skips their `council-<runId>.json` pointer files (a pointer's
+filename fails the session-ID pattern every other row's directory name must match), which is
+exactly why the merge exists. Each merged row carries `type: 'council-run'`, a fixed
+`mode: 'headless'`, and its own 80-char sanitized `briefing` preview plus a `stage` field naming
+whichever stage is currently running; the CLI table renders `council(<stage>)` in its MODEL
+column and re-truncates that 80-char preview to its usual 30-char slice. That merge is scoped
+to the CURRENT project on both surfaces — `--all` included, so under `--all` the session rows
+span every known project while the council rows do not: council runs are found through
+per-project pointer files and there is no cross-project council index to walk. The CLI says
+so at runtime rather than only here — every human-readable `--all` listing ends with
+`council runs: current project only (no cross-project index).`, under the table or right after
+`No amicus sessions found.` when there is no table, and after the `--limit` elision notice when
+one is printed. That line is human-surface only: `--json`
+keeps its shape, on stdout and stderr alike, because no flag can widen the scope it reports.
+If the merge itself cannot run — an unreadable or corrupt council pointer, say — the listing
+still prints the sessions it already had and adds `council runs: unavailable (<reason>)`,
+rather than dropping every council row in silence. It appears with or without `--all` (under
+`--all` it sits just above the scope note), and the reason is the underlying error message,
+sanitised and capped to one line. This one is human-surface only for a *different* reason than
+the scope note: not that nothing could widen it, but that `--json`'s shape is a contract and
+this is prose. The residual that leaves — a `--json` caller reads a well-formed document that
+is silently short — is recorded at the pins in `tests/list-council-merge.test.js`.
+The MCP tool
 also re-sanitizes every other row's `briefing` to that same 80-char cap and, for any row still
 `status: 'running'`, adds live-progress fields (`phase`, `messageCount`, `lastActivityAt`,
 `latestPreview`) — enrichments the CLI table doesn't apply, since it prints the raw 30-char slice
@@ -481,10 +501,10 @@ at a missing or unreadable project is skipped rather than surfaced as an error.
 fan-out wave row reads its full `briefing.md` off disk (falling back to the row's 200-char excerpt
 if that file isn't readable), and a leg row (one spawned by a wave) matches on `id`/`tag` only —
 its briefing is the parent wave's, and matching it there would surface the same wave once per leg
-it spawned. On the MCP tool specifically, a council-run row's search material is `briefing.md`
-written at MCP launch time, or falls back to the portion of `briefing-stage1.md` after
-`--- MATERIAL / BRIEFING ---` (CLI-launched runs only ever have the latter file) — this clause is
-MCP-only, since the CLI never lists a council row to search in the first place. A bare `--search`
+it spawned. A council-run row's search material (both surfaces, now that the CLI merges council
+rows too) is `briefing.md` written at MCP launch time, or falls back to the portion of
+`briefing-stage1.md` after `--- MATERIAL / BRIEFING ---` (CLI-launched runs only ever have the
+latter file). A bare `--search`
 with no value is a usage error on the CLI. Tag itself is set at launch with `--tag <t>` on
 `start`/`fanout`/`council run` (see those sections above), and is also a dimension for
 `amicus spend --group-by tag`. `amicus continue` and `amicus resume` don't take a `--tag` of
@@ -518,7 +538,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -849,6 +869,102 @@ The async pattern is **start → status → read**: `amicus_start` (or `amicus_f
 
 Session statuses: `running`, `complete`, `aborted`, `crashed`, `error`, `timed-out`, `idle-timeout`
 
+### MCP tool parameters
+
+Every tool below also takes an optional `project` — an absolute path naming the working directory the call resolves against, auto-detected from the caller's cwd when omitted. `amicus_setup` and `amicus_guide` take no parameters at all; `amicus_council_stats` takes only `project`; and `amicus_spend`'s nine filters are described in the paragraph above. A handful of parameters not listed here are filled in by the calling agent from facts only it can see (the Cowork VM process name, the parent session UUID) rather than chosen by you — they are documented in the tool schema the agent reads, and pinned as such in `tests/mcp-tool-params-docs.test.js`.
+
+**`amicus_start`** — spawn a session with another model.
+
+- `model` — short alias (`gemini`, `gpt`, `opus`, `deepseek`, …) or a full `provider/model` id. Omitted uses your configured default.
+- `gateway` — routing preference: `auto` (direct-first, the default), `direct`, or `openrouter`.
+- `prompt` — the task briefing: objective, background, files of interest, success criteria.
+- `agent` — OpenCode agent mode (`Chat`, `Plan`, `Build`); see [OpenCode Agent Types](#opencode-agent-types) below.
+- `noUi` — run headless instead of opening the Electron window. Default `false`.
+- `thinking` — reasoning effort (`low` | `medium` | `high`). Default `medium`.
+- `timeout` — headless timeout in minutes (default 15); applies only when `noUi` is true.
+- `contextTurns` — max parent-conversation turns to include. Default 50; the MCP twin of `--context-turns`.
+- `contextSince` — time window for parent context (`30m`, `2h`, `1d`); overrides `contextTurns` when set. The MCP twin of `--context-since`.
+- `contextMaxTokens` — cap on the included context, in tokens. Default 80000.
+- `includeContext` — include the parent conversation at all. Default `true`; set `false` for a self-contained briefing (the MCP twin of `--no-context`).
+- `summaryLength` — fold-summary verbosity: `brief`, `normal` (default), or `verbose`.
+- `windowPosition` — where the interactive window lands: `right` (default), `left`, or `center`.
+- `pack` — [policy pack](#policy-packs) name or path supplying defaults; explicit params still win.
+- `tag` — a 1-64 character label (letters, digits, `_`, `-`) for `list`/`search`/`spend` grouping.
+
+**`amicus_status`** — one-shot status. Takes `taskId` (a session or wave id).
+
+**`amicus_abort`** — stop a running session. Takes `taskId`.
+
+**`amicus_wait`** — block until a run reaches a terminal state, replacing a sleep+poll loop.
+
+- `taskId` — the session or wave id to wait on.
+- `waveId` — alias for `taskId` when waiting on a fan-out wave.
+- `timeoutMs` — max wait in milliseconds. Default 50000, capped at 110000 so the call returns before typical MCP client kill windows; on expiry you get `{timedOut: true}`, not an error, and re-call.
+
+**`amicus_read`** — read a finished session. Every mode is capped at ~50KB.
+
+- `taskId` — the task to read.
+- `mode` — `summary` (default), `conversation`, or `metadata`. Paging is ignored in `metadata`.
+- `offset` — byte offset to start from (0-based). Suppresses the cap and the truncation notice, and takes precedence over `tail`.
+- `limit` — max bytes to return (1-51200). Defaults to the cap.
+- `tail` — return the LAST `limit` bytes instead of the first. Ignored when `offset` is given; it is also the implicit behaviour when content exceeds the cap and neither is set.
+
+**`amicus_list`** — list sessions.
+
+- `status` — filter by status (`all`, `running`, `complete`, `error`, `aborted`, …). Default: everything.
+- `search` — case-insensitive substring filter over id, tag, and briefing material.
+
+**`amicus_resume`** — reopen a finished session. Takes `taskId`, plus `noUi` and `timeout` with the same meanings as on `amicus_start`.
+
+**`amicus_continue`** — send a follow-up turn into a previous session.
+
+- `taskId` — the session to continue from; `prompt` — the new task description.
+- `model` / `gateway` — override the model or routing for the continuation.
+- `noUi` / `timeout` — headless mode and its timeout, as on `amicus_start`.
+- `contextTurns` / `contextMaxTokens` — how much of the previous session's conversation rides along.
+
+**`amicus_fanout`** — same briefing, many models, one wave.
+
+- `models` — 1-10 aliases or full ids (2+ for a genuine fan-out). Mutually exclusive with `council`.
+- `council` — a saved council or a built-in bench (`free`, `budget`, `frontier`) instead of `models`.
+- `prompt` — the briefing every leg receives; `agent`, `thinking`, `timeout`, `summaryLength`, `gateway`, `includeContext`, `pack` and `tag` all mean what they do on `amicus_start`, applied to every leg (`timeout` is per-leg).
+- `onComplete` — `mcp-notify`: send an MCP info notification carrying the terminal event doc when the wave finishes. Advisory and best-effort — `amicus_wait` stays the reliable completion mechanism, and exec commands are never accepted over MCP.
+
+**`amicus_council_tally`** — deterministic tiers + street-cred from an assembled council record.
+
+- `meta` — run metadata; `meta.models` lists every reviewed model, and `meta.intent` marks a task run.
+- `findings` — the run-global findings, ids already `A1`/`B2`/`C3`-prefixed.
+- `adjudications` — one row per (judge × finding): `judge`, `findingId`, `verdict`.
+- `rankings` — each judge's preference order over the reviews; ties are a nested array.
+- `runStats` — optional per-model run stats (status/duration/usage).
+
+**`amicus_verdict`** — merge a tally record with Stage-4 decisions into `verdict.json`.
+
+- `record` — a tally output record (from `amicus_council_tally`).
+- `decisions` — per-finding Stage-4 decisions; defaults to `[]`.
+- `overallVerdict` — the chair's terminal line, carried through from the engine-written `verdict.json`. It is the only copy; omit it when the chair was skipped, and never author one yourself.
+- `seatLoss` / `degrades` — the engine-written critic-seating block and the "what was lost" list, carried through the same way. Omitted means absent, never fabricated.
+- `render` — also return the markdown rendering of the decided verdict.
+- `outDir` — where to refresh `report.html` when `render` is true; rejected if it escapes the project dir. Omit to write nothing.
+
+**`amicus_council_run`** — the full headless council engine, no orchestrating agent required.
+
+- `briefingFile` — path to the briefing (self-contained material + criteria). Councils always brief via file; the file is copied into the run dir.
+- `models` — 2-10 bench seats, or `council` to name a saved council or a built-in bench instead.
+- `chair` — the synthesizing model (default `deepseek`). Must NOT be a bench seat.
+- `critic` — swap one bench seat to an adversarial brief. Must BE a bench seat; mutually exclusive with `lenses`.
+- `lenses` — one expert lens per seat (count must equal seat count). Forces no-ledger; mutually exclusive with `critic`.
+- `outDir` — the run directory. Default `<project>/council-<runId>/`.
+- `maxCost` — whole-run USD ceiling, checked before each paid stage launch.
+- `noCostGate` — disable the per-leg price gate for the WHOLE run, repairs and chair included. Independent of `maxCost`, which still caps the total. See [Cost gate](configuration.md#cost-gate).
+- `timeoutMinutes` — per-leg timeout in minutes (fanout semantics). Default 15.
+- `gateway` — routing preference, as on `amicus_start`.
+- `debate` — add a Stage-2.5 rebuttal round before the chair synthesizes.
+- `claudeReviewFile` — path to Claude's own review, included as a judged entry. Claude is reviewed and ranked like a seat, but never judges or chairs.
+- `intent` — `task` marks a task-mode run (recorded on `run.json`/`verdict.json`, kept out of the reliability ledger): seats produce the deliverable and the chair closes with `ANSWER:` on a disjoint scale. `review` is the default and is never stored. See [docs/council.md § Task mode](./council.md#task-mode---intent-task).
+- `ui` — auto-open the Council Workspace window for this run. Default: opens under Claude Code (local) when Electron and a display exist and `workspace.autoOpen` is not `false`.
+- `onComplete`, `pack`, `tag` — as on `amicus_fanout`.
+
 > Legacy `sidecar_*` tool names were removed entirely in v2.0.0 — the tool surface is `amicus_*` only, always. `AMICUS_LEGACY_ALIASES=1` (the v1.8.0 opt-in switch that used to restore the `sidecar_*` twins) is now a no-op: setting it on the MCP server entry changes nothing. See [docs/SHIMS.md](./SHIMS.md) for the removal record.
 
 > The MCP server auto-detects whether it's running under Claude Code or Claude Desktop/Cowork (from the MCP `initialize` handshake) and passes the right `--client` value downstream — this drives context inclusion, MCP discovery, and session-dir resolution. If detection ever picks the wrong one, force it with `"env": {"AMICUS_MCP_CLIENT": "code-local"}` (or `code-web` / `cowork`) on the MCP server entry.

package/electron/ipc-setup.js

@@ -25,6 +25,10 @@ const { registerLocalProviderHandlers } = require('./ipc-setup-local');
  *   resolves through this local binding instead.
  */
 function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ipcMain } = {}) {
+  // Offer-session catalog snapshots (V17/A4 + PR 199 B1/D2/A1) — the full
+  // lifetime contract lives in electron/offer-session.js.
+  const offerCatalogs = require('./offer-session').createOfferSessions();
+
   ipcMain.handle('sidecar:validate-key', async (_event, provider, key) => {
     try {
       const { validateApiKey } = require('../src/utils/api-key-store');
@@ -62,6 +66,7 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
             const { buildProviderDefaultChoices } = require('../src/utils/provider-default-picker');
             const catalog = await getCatalog();
             result.providerDefault = buildProviderDefaultChoices(provider, { catalog });
+            offerCatalogs.set(_event, provider, catalog);
           } catch (err) {
             logger.error('save-key providerDefault error', { error: err.message });
             result.providerDefault = null;
@@ -80,10 +85,38 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
   // Task 8: apply a per-provider default picker choice. Read-modify-write,
   // no-clobber -- applyProviderDefault only ever writes aliases[vendor] and
   // seeds config.default when absent (see provider-default-picker.js).
-  ipcMain.handle('sidecar:set-provider-default', (_event, provider, chosenId) => {
+  // Applies against the save-key offer's catalog snapshot (V17 / issue 195):
+  // applyProviderDefault uses directFormIfProven (model-canonicalization.js)
+  // to decide whether to strip an OpenRouter prefix off chosenId, and needs
+  // the catalog the offer was built from to do it. Fetching fresh only when
+  // no snapshot exists (no prior offer, or the offer session already ended
+  // via setup-done).
+  ipcMain.handle('sidecar:set-provider-default', async (_event, provider, chosenId) => {
+    // Reads WITHOUT consuming (PR 199 B1/D2 re-ruled after review F1): the
+    // user's pick is routinely the second-or-later apply for one offer
+    // (auto-apply on render, re-apply per radio change), and each must see
+    // the catalog the visible rows were built from. Staleness is bounded by
+    // the offer session instead: setup-done clears the map, a re-offer
+    // overwrites the entry.
+    let catalog = offerCatalogs.get(_event, provider);
+    if (!catalog) {
+      catalog = [];
+      try {
+        const { getCatalog } = require('../src/utils/model-catalog');
+        catalog = await getCatalog();
+      } catch (err) {
+        // Best-effort only -- a fetch failure leaves `catalog` empty, which
+        // directFormIfProven (F1, council review of PR 198) reads as NO
+        // evidence, never as license to strip: chosenId is persisted exactly
+        // as given, not re-derived. Applying an already-made picker choice
+        // must never abort on a catalog hiccup, and must never fabricate an
+        // id on one either -- that was the exact bug issue 195 fixed.
+        logger.error('set-provider-default catalog fetch error', { error: err.message });
+      }
+    }
     try {
       const { applyProviderDefault } = require('../src/utils/provider-default-picker');
-      return applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true });
+      return applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true, catalog });
     } catch (err) {
       logger.error('set-provider-default handler error', { error: err.message });
       return { success: false, error: err.message };
@@ -119,6 +152,10 @@ function registerSetupHandlers(getMainWindow, { ipcMain = require('electron').ip
   });
 
   ipcMain.handle('sidecar:setup-done', (_event, defaultModel, keyCount) => {
+    // The offer session ends with the wizard: any apply after this fetches
+    // fresh evidence rather than reusing a closed offer's catalog (B1/D2).
+    // A1: only THIS sender's offer sessions end here — never another window's.
+    offerCatalogs.endSession(_event);
     const { BrowserWindow } = require('electron');
     const senderWindow = BrowserWindow.fromWebContents(_event.sender);
     const mainWin = getMainWindow();

package/electron/main.js

@@ -327,11 +327,24 @@ function createAmicusWindow() {
 async function createSetupWindow() {
   // Lazy-load setup UI to avoid loading it for sidecar mode
   const { buildSetupHTML } = require('./setup-ui');
-  const { resolveQuickPicks } = require('../src/utils/quick-picks');
+  const { resolveQuickPicks, toStorableRoute } = require('../src/utils/quick-picks');
   let quickPicks;
+  const shortlists = {};
   try {
     const catalog = await require('../src/utils/model-catalog').getCatalog();
     quickPicks = resolveQuickPicks(catalog);
+
+    // issue 138: one vendor shortlist per family card, resolved server-side from
+    // the same catalog the quick picks came from (no extra IPC round-trip).
+    const { buildModelShortlist } = require('../src/utils/model-shortlist');
+    for (const p of quickPicks) {
+      try {
+        shortlists[p.alias] = buildModelShortlist(p.vendorPath, {
+          catalog,
+          recommendedId: toStorableRoute(p),
+        });
+      } catch (_e) { /* a shortlist failure must never block the wizard */ }
+    }
   } catch (_err) {
     quickPicks = undefined;  // buildSetupHTML falls back to pinned
   }
@@ -348,7 +361,7 @@ async function createSetupWindow() {
     }
   });
 
-  const html = buildSetupHTML({ client: CLIENT, quickPicks });
+  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists });
   mainWindow.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
   mainWindow.webContents.on('page-title-updated', (e) => e.preventDefault());
 
@@ -499,6 +512,36 @@ registerSetupHandlers(() => mainWindow);
 function createSettingsChildWindow() {
   const { buildSetupHTML } = require('./setup-ui');
 
+  // issue 138: mirror createSetupWindow's catalog resolution so Step 2 shows
+  // live per-model options here too, instead of falling back to the pinned
+  // `[offline list]` badge. This window must stay synchronous (opening
+  // Settings must never trigger a network fetch), so read the on-disk cache
+  // directly with readCache() rather than the async fetch-and-refresh helper
+  // createSetupWindow awaits. A missing or corrupt cache reads back as null
+  // and degrades to the same pinned fallback buildSetupHTML already applies
+  // when no quickPicks are given.
+  const { resolveQuickPicks, toStorableRoute } = require('../src/utils/quick-picks');
+  const { readCache } = require('../src/utils/model-catalog');
+  let quickPicks;
+  const shortlists = {};
+  try {
+    const cacheDoc = readCache();
+    const catalog = cacheDoc ? cacheDoc.models : [];
+    quickPicks = resolveQuickPicks(catalog);
+
+    const { buildModelShortlist } = require('../src/utils/model-shortlist');
+    for (const p of quickPicks) {
+      try {
+        shortlists[p.alias] = buildModelShortlist(p.vendorPath, {
+          catalog,
+          recommendedId: toStorableRoute(p),
+        });
+      } catch (_e) { /* a shortlist failure must never block the wizard */ }
+    }
+  } catch (_err) {
+    quickPicks = undefined;  // buildSetupHTML falls back to pinned
+  }
+
   const settingsWin = new BrowserWindow({
     width: 560, height: 680,
     parent: mainWindow, modal: false,
@@ -512,7 +555,7 @@ function createSettingsChildWindow() {
     }
   });
 
-  const html = buildSetupHTML({ client: CLIENT });
+  const html = buildSetupHTML({ client: CLIENT, quickPicks, shortlists });
   settingsWin.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
   settingsWin.webContents.on('page-title-updated', (e) => e.preventDefault());
 }

package/electron/offer-session.js

@@ -0,0 +1,51 @@
+/**
+ * Offer-session catalog snapshots for the setup wizard's provider-default
+ * flow (extracted from ipc-setup.js at the 300-line gate, v4.9 / PR 199).
+ *
+ * V17 (council A4): each save-key offer snapshots the catalog it was built
+ * from, so set-provider-default applies against the SAME catalog the picker
+ * offered — a re-fetch there could return a different catalog and flip
+ * directFormIfProven's evidence (TOCTOU).
+ *
+ * Lifetime = the OFFER SESSION (PR 199 B1/D2, re-ruled after review F1):
+ * the wizard auto-applies on render and re-applies on every radio change,
+ * so EVERY apply while the offer is on screen must see the offer's own
+ * catalog — a one-shot delete-on-read handed every human pick a fresh
+ * fetch, which is the original A4 race. A re-offer overwrites the entry;
+ * setup-done ends the sender's sessions.
+ *
+ * Keyed per SENDER + provider (PR 199 round-2 council A1): two Settings
+ * windows are independent offer sessions — one window's offer, apply, or
+ * completion must never alter another's. A harness event with no sender id
+ * keys by provider alone (also the single-window behavior), and its
+ * endSession ends every session.
+ */
+
+'use strict';
+
+function createOfferSessions() {
+  const snapshots = new Map();
+  const senderId = (event) => {
+    const sid = event && event.sender ? event.sender.id : undefined;
+    return (sid === undefined || sid === null) ? null : sid;
+  };
+  const key = (event, provider) => {
+    const sid = senderId(event);
+    return (sid !== null ? sid + ':' : '') + provider;
+  };
+  return {
+    /** Arm (or re-arm) the sender's offer session for a provider. */
+    set(event, provider, catalog) { snapshots.set(key(event, provider), catalog); },
+    /** The sender's live offer catalog for a provider, or undefined. */
+    get(event, provider) { return snapshots.get(key(event, provider)); },
+    /** End every offer session belonging to this sender (setup-done). */
+    endSession(event) {
+      const sid = senderId(event);
+      for (const k of [...snapshots.keys()]) {
+        if (sid === null || k.startsWith(sid + ':')) { snapshots.delete(k); }
+      }
+    },
+  };
+}
+
+module.exports = { createOfferSessions };

package/electron/setup-ui-model.js

@@ -20,6 +20,26 @@ const PROVIDER_NAMES = {
   deepseek: 'DeepSeek'
 };
 
+/**
+ * F5: HTML-escape a value for safe interpolation into BOTH an attribute
+ * value (double-quoted) and element text content. Catalog ids are
+ * data-controlled (this repo's own convention documents them as such --
+ * see renderSearchResults in electron/setup-ui.js, which uses createElement
+ * + textContent instead of a template string for this exact row source),
+ * so every id/name reaching a template string here must be escaped rather
+ * than trusted.
+ * @param {*} value
+ * @returns {string}
+ */
+function escapeAttr(value) {
+  return String(value === null || value === undefined ? '' : value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 /**
  * Check if a model has at least one route with a configured key.
  * When no keys are configured at all (empty configuredKeys), all models are available
@@ -63,15 +83,68 @@ function buildModelSearchHTML() {
     </div>`;
 }
 
+/**
+ * issue 138: the family -> model second level for one card. Renders EVERY model
+ * in one <select> (scrollable and type-ahead searchable, so nothing is
+ * hidden), grouped "Suggested" / "All N models". Returns '' when no
+ * shortlist was supplied (or its `total` is 0).
+ *
+ * That '' is NOT dropped by the caller — buildModelStepHTML always splices
+ * it into the card template as its own line, so a card with no shortlist
+ * gains one whitespace-only line versus the pre-issue-138 HTML string. It is NOT
+ * byte-for-byte identical to that old output. It IS behaviorally identical:
+ * no <select> is emitted, and whitespace-only text nodes are inert once
+ * parsed as HTML, so the rendered card is unchanged.
+ *
+ * CONTROLLER RULING R1 (issue 138, 2026-08-24): every <option> carries
+ * data-or="<openrouterId>" (empty string when the row has no OpenRouter
+ * form), so a later task can read the user's chosen route without
+ * re-deriving a gateway prefix from the value id.
+ * @param {string} alias
+ * @param {{recommendedId:string, suggested:Array<object>, rest:Array<object>, total:number}} [shortlist]
+ * @returns {string} HTML fragment
+ */
+function buildModelPickHTML(alias, shortlist) {
+  if (!shortlist || !shortlist.total) { return ''; }
+  const opt = (r) => {
+    const price = r.pricePerMInput === null ? '' : ` · $${r.pricePerMInput.toFixed(2)}/M`;
+    const sel = r.isRecommended ? ' selected' : '';
+    return `<option value="${escapeAttr(r.id)}" data-or="${escapeAttr(r.openrouterId || '')}"${sel}>${escapeAttr(r.id)}${price}</option>`;
+  };
+  // Escaping-discipline consistency pass (council review, PR 196): alias
+  // is one of the five hardcoded FAMILIES names, not catalog data, so this
+  // is not closing a live vulnerability -- it matches the escapeAttr() use
+  // a few lines up for r.id/r.openrouterId, which ARE catalog-derived, so
+  // every attribute interpolation in this function follows the same rule.
+  let html = `<select class="model-pick" data-alias="${escapeAttr(alias)}">`;
+  html += `<optgroup label="Suggested">${shortlist.suggested.map(opt).join('')}</optgroup>`;
+  if (shortlist.rest.length > 0) {
+    // council review, PR 196 (F2): this optgroup holds ONLY `rest` -- label it
+    // by rest.length, not shortlist.total, or the label overstates what's in
+    // it (e.g. "All 14 models" over 6 rows when 8 are already under
+    // "Suggested" above). Singular/plural handled explicitly so a 9-row
+    // vendor with one leftover row doesn't read "1 models".
+    const restCount = shortlist.rest.length;
+    const restLabel = restCount === 1 ? '1 more model' : `${restCount} more models`;
+    html += `<optgroup label="${restLabel}">${shortlist.rest.map(opt).join('')}</optgroup>`;
+  }
+  return html + '</select>';
+}
+
 /**
  * Build the HTML fragment for Step 2 (Model Selection).
  * @param {Array<{alias:string, label:string, blurb:string, source:string, routes:Object<string,string>}>} choices
  *   Resolved rows from resolveQuickPicks(). Each row has separate label + blurb fields.
  * @param {string} [selectedAlias] - Pre-selected alias; defaults to first available choice.
  * @param {Object<string,boolean>} [configuredKeys] - Provider IDs the user has keys for.
+ * @param {Object<string,object>} [shortlists] - issue 138: per-alias vendor shortlist
+ *   from buildModelShortlist(), used to render the model-level <select>.
+ *   Defaults to {}; omitting it (or passing {}) is behaviorally identical to
+ *   today's card (no <select> for that alias) but not byte-for-byte identical
+ *   to the pre-issue-138 HTML string — see buildModelPickHTML's docstring.
  * @returns {string} HTML fragment
  */
-function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}) {
+function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}, shortlists = {}) {
   // Determine availability for each model
   const availability = choices.map(c => {
     const providers = Object.keys(c.routes);
@@ -102,6 +175,20 @@ function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}) {
 
     // Resolved id for the write-preview (prefer bestProvider route)
     const previewId = c.routes[bestProvider] || Object.values(c.routes)[0] || '';
+    // Escaping-discipline consistency pass (council review, PR 196; extended
+    // by a second pass, N-c): NOT closing a live vulnerability -- c.alias is
+    // one of the five hardcoded FAMILIES names and previewId is filtered
+    // through resolveQuickPicks' anchored idPattern regexes (or a hardcoded
+    // fallback), neither of which can carry a payload. This applies the
+    // same escapeAttr() used a few lines up (buildModelPickHTML, for
+    // genuinely catalog-derived r.id/r.openrouterId) to every c.alias /
+    // previewId interpolation in this card template -- attributes
+    // (data-alias, the radio value) and text content alike (.model-alias,
+    // .model-resolved, .write-preview-id, the write-preview <code>s) --
+    // so a reader of this template does not have to work out which
+    // interpolations are "safe" and which are escaped; the rule is uniform.
+    const escapedAlias = escapeAttr(c.alias);
+    const escapedPreviewId = escapeAttr(previewId);
 
     // Offline badge for fallback rows
     const badge = c.source === 'fallback'
@@ -114,23 +201,26 @@ function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}) {
       const pills = providers.map(p => {
         const isActive = p === bestProvider;
         const cls = isActive ? 'route-pill active' : 'route-pill';
-        return `<button class="${cls}" data-alias="${c.alias}" data-provider="${p}">${PROVIDER_NAMES[p]}</button>`;
+        return `<button class="${cls}" data-alias="${escapedAlias}" data-provider="${p}">${PROVIDER_NAMES[p]}</button>`;
       }).join('');
       const toggleDisplay = showToggle ? '' : ' style="display:none"';
       const staticDisplay = showToggle ? ' style="display:none"' : '';
-      routeHtml = `<span class="route-toggle" data-alias="${c.alias}"${toggleDisplay}>${pills}</span>`;
-      routeHtml += `<span class="route-static" data-alias="${c.alias}"${staticDisplay}>via ${PROVIDER_NAMES[bestProvider]}</span>`;
+      routeHtml = `<span class="route-toggle" data-alias="${escapedAlias}"${toggleDisplay}>${pills}</span>`;
+      routeHtml += `<span class="route-static" data-alias="${escapedAlias}"${staticDisplay}>via ${PROVIDER_NAMES[bestProvider]}</span>`;
     } else {
       routeHtml = `<span class="route-static">via ${PROVIDER_NAMES[bestProvider]}</span>`;
     }
 
+    const modelPickHtml = buildModelPickHTML(c.alias, shortlists[c.alias]);
+
     return `<label class="${cardClass}">
-        <input type="radio" name="default-model" value="${c.alias}" ${checked}${disabled}>
-        <span class="model-alias">${c.alias}</span>
+        <input type="radio" name="default-model" value="${escapedAlias}" ${checked}${disabled}>
+        <span class="model-alias">${escapedAlias}</span>
         <span class="model-label">${c.label} — ${c.blurb}</span>${badge}
-        <span class="model-resolved">${previewId}</span>
+        <span class="model-resolved" data-alias="${escapedAlias}">${escapedPreviewId}</span>
         ${routeHtml}
-        <span class="write-preview" data-alias="${c.alias}">will set <code>${c.alias}</code> → <code class="write-preview-id">${previewId}</code></span>
+        ${modelPickHtml}
+        <span class="write-preview" data-alias="${escapedAlias}">will set <code>${escapedAlias}</code> → <code class="write-preview-id">${escapedPreviewId}</code></span>
       </label>`;
   }).join('\n      ');
 
@@ -145,4 +235,4 @@ function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}) {
   </div>`;
 }
 
-module.exports = { buildModelSearchHTML, buildModelStepHTML, PROVIDER_NAMES };
+module.exports = { buildModelSearchHTML, buildModelStepHTML, buildModelPickHTML, PROVIDER_NAMES, escapeAttr };

package/electron/setup-ui-styles.js

@@ -192,6 +192,28 @@ function __rawWizardCSS() {
     margin-left: auto; font-size: 11px; color: var(--text-faint); font-style: italic;
   }
 
+  /* Model-level picker (Step 2 card) — issue 138. Mirrors .alias-model-select's
+     token-driven approach (background/border/radius/color/font/outline/cursor),
+     but this control lives inside a wrapping .model-card row alongside the
+     radio and route pills, not the Step-3 alias table's own linear row —
+     so it takes flex-basis:100% (its own line, below the route pills) rather
+     than alias-model-select's flex:1, and a plain --border (not --accent,
+     which the alias editor reserves for its active-edit state) so it reads
+     as a subordinate refinement, not the card's primary affordance. The
+     option/optgroup rules are load-bearing: Windows does not inherit a
+     <select>'s background/color into its <option>/<optgroup> children. */
+  .model-pick {
+    flex-basis: 100%; margin-top: 4px; padding: 3px 6px;
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--r-3); color: var(--text-muted); font-size: 11px;
+    font-family: var(--font-mono);
+    outline: none; cursor: pointer; max-width: 280px;
+  }
+  .model-pick:hover { border-color: var(--border-strong); }
+  .model-pick:focus { border-color: var(--accent); }
+  .model-pick option { background: var(--surface); color: var(--text); }
+  .model-pick optgroup { color: var(--text-muted); font-style: normal; }
+
   /* Routing example */
   .routing-example {
     background: var(--surface); border: 1px solid var(--border); border-radius: var(--r-8);