diff --git a/.env.example b/.env.example
index 5ee72f42..beb105a8 100644
--- a/.env.example
+++ b/.env.example
@@ -59,10 +59,13 @@ AGENT_QUALITY_CANDIDATE_TIMEOUT_MS=45000
 OPENROUTER_FREE_MODEL_CACHE_MS=600000
 OPENROUTER_REQUIRE_NO_TRAINING=1
 OPENROUTER_FREE_ALLOW_FILE_EGRESS=0
-# Provider-neutral NodeAgent uses OpenRouter's governed free ladder first, then
-# this direct Gemini route when free routes are unavailable. Receipts retain the
-# catalog price because an account's free-tier entitlement cannot be asserted.
-NODEAGENT_FREE_AUTO_GOOGLE_MODEL=gemini-3.5-flash
+# Provider-neutral NodeAgent uses OpenRouter's governed free ladder only. This
+# direct Gemini route is an opt-in paid leg: it is taken only when the caller sets
+# allowPaidFallback AND passes a spend meter (adapter.ts), and no production caller
+# does either, so by default a free-route outage is an error, not a paid request.
+# Receipts retain the catalog price because an account's free-tier entitlement
+# cannot be asserted.
+NODEAGENT_FREE_AUTO_GOOGLE_MODEL=gemini-3.8-flash
 AGENT_MODEL=gpt-5.4-nano
 # Optional voice provider overrides. Browser TTS is the free client default;
 # Convex `/voice/*` endpoints are authenticated hosted fallbacks.
@@ -81,7 +84,7 @@ VOICE_CLOUDFLARE_TTS_MODEL=@cf/myshell-ai/melotts
 VOICE_CLOUDFLARE_TTS_LANG=en
 GEMINI_API_KEY=
 VOICE_GEMINI_TTS_FREE_TIER_CONFIRMED=0
-VOICE_GEMINI_TTS_MODEL=gemini-3.1-flash-tts-preview
+VOICE_GEMINI_TTS_MODEL=gemini-3.8-flash-tts
 VOICE_GEMINI_TTS_VOICE=Kore
 VOICE_GEMINI_TTS_INSTRUCTIONS=Read clearly and concisely for a collaborative work room.
 GOOGLE_CLOUD_TTS_API_KEY=
@@ -113,7 +116,7 @@ SEO_QA_GOOGLE_TARGET_PHRASE=NodeRoom collaborative AI room
 GOOGLE_SEARCH_CONSOLE_SITE_URL=https://noderoom.live/
 GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN=
 GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT_JSON=
-GEMINI_SEO_VIDEO_JUDGE_MODEL=gemini-3.5-flash
+GEMINI_SEO_VIDEO_JUDGE_MODEL=gemini-3.6-flash
 NEBIUS_SEO_JUDGE_MODEL=nebius/MiniMaxAI/MiniMax-M2.5
 NEBIUS_SMOKE_MODEL=nebius/MiniMaxAI/MiniMax-M2.5
 NEBIUS_ENABLE_VISION_JUDGE=0
@@ -162,8 +165,8 @@ FREE_JOB_GOAL=
 FREE_JOB_TIMEOUT_MS=900000
 
 # Optional server-side parser model overrides.
-PROVIDER_PARSER_GEMINI_MODEL=gemini-3.5-flash
+PROVIDER_PARSER_GEMINI_MODEL=gemini-3.8-flash,gemini-3.6-flash
 PROVIDER_PARSER_OPENAI_MODEL=gpt-5.4-mini
-PROVIDER_PARSER_ANTHROPIC_MODEL=claude-haiku-4-5
-PROVIDER_PARSER_OPENROUTER_MODEL=z-ai/glm-5.2,moonshotai/kimi-k2.7-code,cohere/north-mini-code:free,nvidia/nemotron-3-ultra-550b-a55b,nex-agi/nex-n2-pro
+PROVIDER_PARSER_ANTHROPIC_MODEL=claude-haiku-5-5,claude-sonnet-5-5
+PROVIDER_PARSER_OPENROUTER_MODEL=z-ai/glm-5.2,moonshotai/kimi-k2.7-code,cohere/north-mini-code:free,nvidia/nemotron-3-ultra-550b-a55b
 PROVIDER_PARSER_ALLOW_FILE_EGRESS=0
diff --git a/.tours/01-primary-user-flow.tour b/.tours/01-primary-user-flow.tour
index cdd9f11d..00eb3a0f 100644
--- a/.tours/01-primary-user-flow.tour
+++ b/.tours/01-primary-user-flow.tour
@@ -27,14 +27,14 @@
     },
     {
       "file": "src/ui/Chat.tsx",
-      "line": 1878,
+      "line": 1879,
       "pattern": "const send = \\(raw\\?: string",
       "title": "The primary user action",
       "description": "`send` is what the Send button calls. Two separate things happen and it matters that they are separate:\n\n1. The message is posted to the room, with a client-generated `clientMsgId` — that id is how a retry updates the same message instead of double-posting it.\n2. Only then is the text inspected to see whether it was addressed to the assistant."
     },
     {
       "file": "src/ui/Chat.tsx",
-      "line": 1166,
+      "line": 1167,
       "pattern": "function parsePublicNodeAgentRequest",
       "title": "Where text becomes intent",
       "description": "The assistant that can edit the shared sheet is addressable ONLY as a leading `@nodeagent …` directive. Mentioning it mid-sentence does not summon it.\n\nThis decides intent. It does not decide permission — that happens on the server, in the next step but one."
@@ -48,7 +48,7 @@
     },
     {
       "file": "convex/agentJobs.ts",
-      "line": 2782,
+      "line": 2799,
       "pattern": "export const startPublicAsk = mutation\\(",
       "title": "Where input becomes trusted (live tier)",
       "description": "This is the real trust boundary. Convex validators reject a malformed payload before a job row exists, and `requireActorProof` checks that this browser is actually a member of this room.\n\nThe client-side parse two steps back exists to decide what the user meant. This decides what they are allowed to do."
diff --git a/.tours/03-debug-and-recovery.tour b/.tours/03-debug-and-recovery.tour
index 83e77502..2aa1316b 100644
--- a/.tours/03-debug-and-recovery.tour
+++ b/.tours/03-debug-and-recovery.tour
@@ -27,21 +27,21 @@
     },
     {
       "file": "src/ui/Chat.tsx",
-      "line": 269,
+      "line": 270,
       "pattern": "const MAX_FAILED_SENDS = 50;",
       "title": "Failure 3 — a message fails to post, and the list is bounded",
       "description": "`MAX_FAILED_SENDS = 50`, FIFO. Every in-memory collection on an agent path needs a cap and an eviction rule; agents loop, and an unbounded list fills memory in minutes rather than months."
     },
     {
       "file": "src/ui/Chat.tsx",
-      "line": 1943,
+      "line": 1944,
       "pattern": "const retrySend = \\(cid: string, text: string\\)",
       "title": "Retry that cannot double-post",
       "description": "`retrySend` re-sends with the SAME `clientMsgId`. That id is what makes the retry idempotent at the store, so a user hammering Retry on a flaky connection does not produce five copies of their message."
     },
     {
       "file": "src/ui/Chat.tsx",
-      "line": 935,
+      "line": 936,
       "pattern": "function buildAgentFailureNotice\\(",
       "title": "Failure 4 — the agent fails",
       "description": "`buildAgentFailureNotice` turns a provider error into a sentence a non-engineer can act on, carrying which model selection was used, what was asked, and which job it was. A stack trace on this surface is a defect, not a debug aid — this is a surface where a user decides whether to trust the assistant."
diff --git a/CHANGELOG/README.md b/CHANGELOG/README.md
index c0a25e56..03bd9e91 100644
--- a/CHANGELOG/README.md
+++ b/CHANGELOG/README.md
@@ -23,6 +23,7 @@ entries have not been invented or backfilled.
 ## Quality assurance
 
 - [Benchmark timeout budgets](qa/benchmark-timeout-budgets.md)
+- [Model default refresh](qa/model-refresh-noderoom.md)
 - [NodeKit note reference proof](qa/nodekit-note-reference-proof.md)
 
 See [TEMPLATE.md](TEMPLATE.md) before adding or editing a lane.
diff --git a/CHANGELOG/qa/model-refresh-noderoom.md b/CHANGELOG/qa/model-refresh-noderoom.md
new file mode 100644
index 00000000..ff1c27f6
--- /dev/null
+++ b/CHANGELOG/qa/model-refresh-noderoom.md
@@ -0,0 +1,202 @@
+# Model default refresh (NodeRoom)
+
+Append-only lane for the 2026-10 refresh of NodeRoom's default model ids
+(model-defaults SPEC Part A, section A.2.9).
+
+## 2026-10-14 — Refresh stale model defaults and fix Claude 5.5 request shapes
+
+Google deprecated `gemini-3.5-flash` on 2026-10-08 and OpenRouter drops
+`google/gemini-2.5-*` on 2026-10-20, so the agent default moves to one constant,
+`DEFAULT_AGENT_MODEL` (`convex/modelDefaults.ts`, `gemini-3.8-flash`). Claude
+defaults move to the 5.5 ids, the dotted-id regex in `resolveModelAlias` becomes
+an explicit table, forced `tool_choice` is downgraded to `auto` for Sonnet/Opus
+5.5, and `evals/ladder.ts` now refuses a `--real` run without a dollar cap and
+reserves cost at every provider dispatch. Merge waits for the L1-L4 ladder
+receipt `docs/eval/ladder/model-refresh-noderoom.json`; until it exists
+`tests/qaMatrix.test.ts` stays red on purpose, and the fast lane in
+`adaptiveRouter.ts` stays on `gemini-3.5-flash`.
+
+**Commit**: `922fdb6`. **Author**: Homen Shum.
+
+## 2026-10-14 — Review round 1: merge blockers, receipt fields, tiered pricing
+
+PR 261 is a draft and carries the `needs-live-eval` label; both stay until the three
+live checks below exist (SPEC A.0.3: the label is a block, not a note):
+
+1. the L1-L4 ladder receipt `docs/eval/ladder/model-refresh-noderoom.json`;
+2. the manual listen check of `gemini-3.8-flash-tts` (`convex/http.ts:36`, A.0.7);
+3. the observed Environment smoke that OpenRouter accepts `anthropic/claude-sonnet-5.5`
+   for `top_paid` with `tool_choice: auto` and `strict: true` tool definitions.
+
+Fixes: the `--json-out` report now carries `command`, `candidateIds`, `echoedModels`,
+per-dispatch `rows` (provider-echoed model, usage, cost, `fallbackUsed`), `environment`
+and `budget.requestCeiling`, so a receipt can be judged against A.0.3. The echoed model is
+read from the raw response body (`modelVersion` / `model`) because the AI SDK's
+`response.modelId` is the requested id for Google. A refused reservation is terminal for the
+meter: no retry, fallback model or candidate may dispatch after it, and the provider-neutral
+Google fallback honours `crossModelFallback: false`. `claude-haiku-5-5` is priced
+tier-aware (`longContext`, $0.50/$2.50 above 100K prompt tokens) in every cost and
+reservation path. Sonnet/Opus 5.5 send `strict: true` tool definitions wherever a forced
+`tool_choice` is downgraded to `auto`; the AI-SDK capture reasoner and provider parser send
+the explicit §1.3 effort. `.env.example` copies of the changed defaults now match the code.
+
+**Commit**: the commit after `71a1f15` on this branch. **Author**: Homen Shum.
+
+## 2026-10-15 — Review round 2: per-request tiers, call-site tests, free-auto ceiling
+
+The long-context price tier is now chosen per provider request only (`priceRequest`,
+`convexPriceRequest`, reservation, meter settlement, runtime `priceStep`). Usage summed over
+several requests is priced at base-tier rates (`priceRun`, `convexPriceRun`, `creditModel`,
+`proofloopModelTracking`), and the ladder sums settled dispatch costs, so two 60K requests are
+no longer billed as one 120K request. `claude-haiku-5-5` carries its `$0.05` cache-read rate
+above 100K. The five `DEFAULT_AGENT_MODEL` call sites (`convex/agent.ts` x2, `agentJobRunner.ts`,
+`streaming.ts`, `Chat.tsx`) and the remaining judge/benchmark scripts now have tests that fail
+on revert; `qaMatrix` checks both `AGENT_MODEL` fallbacks. The LangChain bridge sends
+`strict: true` on the forced-choice downgrade, `probe.ts` and `providerParseSmoke.ts` send the
+explicit effort, `providerParseSmoke.ts` now reaches Google for Gemini ids, and the ladder
+pre-flight multiplies a free-auto route by `OPENROUTER_FREE_AUTO_LIMIT`. The merge blockers
+above are unchanged.
+
+**Commit**: the commit after `0ff118a` on this branch. **Author**: Homen Shum.
+
+## 2026-10-15 — Review round 3: cost class preserved, unknown ids fail closed, honest failed-rung cost
+
+Closes the round-1 findings 1 and 2 that rounds 1 and 2 left open (SPEC A.0.10), plus four round-2 defects.
+
+- **Unknown ids fail closed.** `resolveModelAlias` now throws `UnknownModelError` for an id that is not priced, not
+  declared by the alias table and not free-looking, so `model()` and `convexModel()` (and the fallback lists they read)
+  throw before any request. An unknown `-free` / `:free` id resolves to `openrouter/free-auto`. Pricing and telemetry
+  readers (`priceRun`, `reserveDispatch`, `creditModel`, `proofloopModelTracking`, the egress policy, `benchmark/run.ts`,
+  the interop normalizer) read the lenient `lookupModelAlias`, because they must tolerate historical ids and never dispatch.
+- **Free never becomes paid.** A free primary no longer falls back to a paid model: adapter `fallbackModelFor` and
+  `convexModel` drop the paid candidate unless the caller sets `allowPaidFallback: true` and there is a reservation
+  (adapter: a `SpendMeter`, reserved in `meteredDispatch`; Convex: a finite `maxCostUsd`, estimated per candidate by the
+  failover controller). Paid -> paid and paid -> free are unchanged.
+- **Failed rung cost.** `runRung`'s catch branch reports the sum of its settled dispatch costs, not `0`.
+- **Alias fan-out.** `ladderRequestCeiling` / `estimateLadderUsd` resolve the route before testing for free-auto fan-out,
+  so `free` and `openrouter-auto` count 8 requests per step, not 1.
+- **Request shape + pricing agreement.** `probe.ts` `gpt-6.1-sol` is asserted on the wire (URL, `model`, no sampling).
+  `benchmark/run.ts` pricing moved to `scripts/benchmark/pricingAtRun.ts` (run.ts runs the benchmark on import) so
+  `tests/modelPricingAgreement.test.ts` runs it, and the `--dry-run` sweep script, on a dated OpenRouter `/models`
+  fixture; a x1e5 conversion now fails both.
+- **Tests retargeted, not loosened.** `evals/ladderBudget.test.ts` (g), `tests/convexModelFreeAutoMode.test.ts` and
+  `tests/modelAliasClaude.test.ts` used never-heard-of ids that were dispatched; they now assert the refusal, and the
+  original invariants (zero requests, meter untouched, terminal stop, conservative reservation) are kept on the id the
+  alias table declares without a price row (`claude-sonnet-4.5`).
+- **Spec discrepancies left for a human (SPEC section C), not decided here:** see the PR body.
+
+**Commit**: the commit after `55261e8` on this branch. **Author**: Homen Shum.
+
+## 2026-10-16 — Review round 5: known ids from the repo's lists, one guard per boundary, D2 for top_paid, REA/ORX
+
+Closes the round-3 review of the refreshed ids (SPEC-v9 D1, D2, D5; A.0.4, A.0.6, A.0.10).
+
+- **Known = named by the repo or by SPEC section 1.2 (D1).** `REPO_DECLARED_UNPRICED_IDS` now holds every
+  `OPENROUTER_TOP_PAID_AGENT_ROUTES` route and every section 1.2 wire id on every transport. Before this, 9 of the 19
+  top-paid routes and 18 of the 32 section 1.2 ids threw `UnknownModelError`, so `model-eval-matrix --route-set top-paid`
+  broke for those routes. `tests/modelKnownIds.test.ts` now reads `resolveRouteSet(...)` for all six route sets,
+  `allAgentLlmRoutes()` and the section 1.2 list (typed in the test, because the spec lives outside this repo).
+- **Eval scripts stay pass-through (D1).** `model(id, { operatorSelected: true })` keeps an operator- or live-list-selected
+  id as written: an unknown paid id is not refused and a concrete `:free` id is not rewritten to `openrouter/free-auto`.
+  Only `scripts/benchmark/run.ts`, `scripts/proofloop-free-model-gauge.ts`, `evals/ladder.ts` (`--real`, including
+  `ladder:free --free-auto-top`), `scripts/spreadsheetbench-run.ts` and `evals/chatIntakeRuntime.ts` set it. Server code
+  never does. The alias table still applies.
+- **PlanPreview-blocked runs record again.** `runRoomAgent` records a blocked run with the marker `modelPolicy: "not_started"`
+  (no model runs). The boundary check rejected it, so the plan message and the credit settlement were never reached. The
+  marker is accepted only together with `initialStatus: "blocked"`. A convex-test drives `runRoomAgent`'s blocked branch.
+- **Private stream and capture fail closed.** `streamPrivateReplyText` and `aiSdkReasoner` call `resolveModelAlias` first
+  (one guard each; `aiSdkReasoner` covers `capturesNode`, `captureSource` and the Firecrawl tool). Tests assert 0 fetch calls
+  for an unknown `AGENT_MODEL` and for `claude-not-in-catalog-9`, `gpt-not-in-catalog`, `o3-not-in-catalog`, `claude-opus-9`.
+- **Call sites driven, not grepped.** `tests/modelRefreshAgentWire.test.ts` runs `runRoomAgent` (public_ask),
+  `runPrivateAgent` and `runFreeAutoJobSlice` (a claimed job with no `modelPolicy`) through a convex-test database and a
+  fake `fetch`, and asserts the model in the request URL is `gemini-3.8-flash` (or the `AGENT_MODEL` override) and that no
+  sampling key is sent. Reverting `modelNameForEgress` to always return the file-egress model, or the runner default to
+  `gemini-3.5-flash`, fails five of its six tests.
+- **D2 for `top_paid`.** `convex/agentJobs.ts` `top_paid` defaulted to the retired `anthropic/claude-sonnet-4`; round 1
+  moved it to `anthropic/claude-sonnet-5.5`. No OpenRouter key exists, so under D2 it is now
+  `DEFAULT_TOP_PAID_MODEL = nvidia/nemotron-3.5-super-vl:free` (`convex/modelDefaults.ts`), the newest `:free` row of the
+  public list `https://openrouter.ai/api/v1/models` (fetched 2026-10-16T11:32:04Z, recorded in
+  `docs/eval/openrouter-free-models-2026-10-16.json`) with `tools`, `tool_choice`, `structured_outputs`, a 1,000,000-token
+  context, text output and no `expiration_date`. Newer or equal rows were skipped on the stated criteria:
+  `dots-studio/dots-3-note-preview:free` and `poolside/laguna-s-2.1:free` carry an `expiration_date`; `liquid/lfm-2.5-2.6b:free`
+  has 65,536 context; `nvidia/nemotron-3.5-lightning:free` and the two `thinkingmachines` rows lack `structured_outputs` or
+  `tool_choice`. **Marked: live-unverified (no key, Homen 2026-10-16).** Behaviour change to expect: a free route cannot take
+  an uploaded file, so a `top_paid` job in a room with a file is refused at the free-file-egress gate (or promoted to
+  `z-ai/glm-4.7-flash` when the existing `FREE_AUTO_ALLOW_FILE_EGRESS_PROMOTION` opt-in is set) unless `AGENT_TOP_PAID_MODEL` or
+  `AGENT_MODEL` is set; those env vars still win. The `anthropic/claude-sonnet-5.5` request-shape handling (`auto` plus
+  `strict: true`) stays in `convexModel` and its test for an operator who sets that id. Merge blocker 3 (the Environment
+  smoke for `claude-sonnet-5.5`) therefore no longer applies to a code default.
+  - Other OpenRouter-routed rows: `providerParserLive.ts:113` only drops the unlisted `nex-agi/nex-n2-pro`; it picks no new
+    target, the remaining candidates are frozen paid routes with no vendor successor (D2a), so D2 does not apply.
+    `modelRegistry.ts:48` stays **defer** (`anthropic/claude-fable-5` is active, floor 2027-06-09), so D2 does not apply.
+- **Docs.** The `.env.example` note on `NODEAGENT_FREE_AUTO_GOOGLE_MODEL` now says the direct Gemini leg is opt-in
+  (`allowPaidFallback` plus a meter, `adapter.ts`) and that no production caller sets either.
+
+### REA (how mature references do the same thing) and ORX (primary sources), fetched 2026-10-16
+
+REA reads the mechanisms this PR touches: an explicit alias table instead of a regex, a known-id registry that fails
+closed, tiered per-request pricing, a spend meter. Facts, with what was adopted or rejected.
+
+| Reference (fetched) | Fact observed | Adopted | Rejected |
+|---|---|---|---|
+| LiteLLM `model_prices_and_context_window.json` (raw.githubusercontent.com/BerriAI/litellm/main, 4,194 entries, 2026-10-16T14:44Z) | One flat map keyed by provider-prefixed wire id (`gemini/gemini-3.8-flash`, `vertex_ai/gemini-3.8-flash`, `claude-haiku-5-5`, `bedrock_mantle/anthropic.claude-haiku-5-5`). Tier prices are separate keys on the same row (`input_cost_per_token_above_100k_tokens`, `*_above_200k_tokens`, `cache_read_input_token_cost_above_100k_tokens`); `claude-haiku-5-5` carries 5e-07 / 2.5e-06 / 5e-08 above 100K. `deprecation_date` is per row and differs by transport (`azure_ai/claude-sonnet-5` 2027-06-30, `vertex_ai/claude-sonnet-5` 2026-12-24, native `claude-sonnet-5` null). `max_output_tokens` is 128000 for `claude-haiku-5-5`. | An id is looked up by its exact wire string per transport (the explicit table, no regex); the tier is a field of the price row and is chosen per request; a lifecycle date belongs to the transport, not to the model name (SPEC B.1). Our Haiku 5.5 tier ($0.50 / $2.50 / cache read $0.05 above 100K) equals LiteLLM's. | A single unified id space across transports; regional multipliers (`us.anthropic.*` rows at 1.1x) and batch keys, which no NodeRoom path uses. |
+| models.dev `https://models.dev/api.json` (231 providers, 2026-10-16T14:44Z) | `anthropic/claude-haiku-5-5`: cost 0.1 / 0.5, `cache_read` 0.01, `cache_write` 0.125, one `tiers` entry `{type: "context", size: 100000}` at 0.5 / 2.5 / 0.05 / 0.625; `limit.output` 128000; `release_date` 2026-10-07; `tool_call` and `structured_output` true. Resellers re-price the same model (`poe/google/gemini-3.8-flash` input 0.7576 against 0.75 at the vendor). | The tier boundary (100K prompt tokens, per request) and the vendor rates cross-check our table; `release_date` agrees with the spec. | Reseller rows as a price source: prices come from the vendor page, never an aggregator. |
+| OpenRouter `GET /api/v1/models` (public, no key; 465 rows, 2026-10-16T11:32:04Z; earlier reads 2026-10-10 and 2026-10-14 in the spec) | Each row has `id`, `created`, `context_length`, per-token string `pricing`, `supported_parameters` (`tools`, `tool_choice`, `structured_outputs`) and `expiration_date`; 18 of 465 rows carry an `expiration_date`, including two of the newest `:free` rows. | Capability selection from `supported_parameters`, the `expiration_date` exclusion and `created` ordering for D2; the per-token to per-1M conversion is already pinned by `tests/modelPricingAgreement.test.ts`. | Treating absence from the list as a vendor retirement (it is "unlisted on this transport", SPEC 1.1). |
+| Vercel AI SDK `@ai-sdk/anthropic` 3.0.120 (installed source, `dist/index.mjs` `getModelCapabilities`, read 2026-10-16) | Capabilities are matched by substring. `claude-haiku-5-5` matches no 5.x branch (only `claude-opus-5-5`, `claude-opus-5` and `claude-sonnet-5` do), so it falls into the generic `claude-` branch: `maxOutputTokens` 128000, `isKnownModel: false`. The SDK reports the flag and still dispatches. | The `isKnownModel` idea, enforced instead of reported: `resolveModelAlias` throws `UnknownModelError`, and `modelMaxOutputTokens` keeps its own 2048 floor and caps for the 5.5 ids rather than trusting the SDK fallback. | Substring matching (it is how `claude-haiku-5-5` ended up in the fallback branch). |
+
+ORX, primary sources behind the ids, prices and dates in this PR (ids and prices were not taken from recall):
+
+- Claude ids, prices and floors: `frontier.json` (read 2026-10-10, which cites `platform.claude.com/docs/en/models/overview`
+  and the release notes); the Anthropic deprecations page re-read live 2026-10-14 (stored copy
+  `_scratch/anthropic-deprecations-2026-10-14-v8.html` in the model-defaults workspace): `claude-haiku-4-5-20251001` Active,
+  floor 2026-10-15; `claude-sonnet-4-5-20250929` deprecated, retires 2026-11-30.
+- Gemini ids, prices and the `gemini-3.5-flash` deprecation (2026-10-08) and `gemini-3.1-flash-tts-preview` shutdown
+  (2026-11-17): `frontier.json` (read 2026-10-10), Google's deprecations table as quoted in SPEC 1.1.
+- OpenAI ids and the 2026-10-14 GPT-4-series notice (removal 2027-01-14): OpenAI deprecations page re-read live 2026-10-14.
+- OpenRouter ids, `expiration_date` and the D2 selection: the public list above, recorded in
+  `docs/eval/openrouter-free-models-2026-10-16.json` (all 15 `:free` rows with the criteria columns).
+- Not verified by a request: no provider call was made. Every `:free` route and the Claude 5.5 ids over OpenRouter are
+  request-shape tested against a fake transport only.
+
+## 2026-10-16 — Review round 6: operator ids stay pass-through everywhere, free-looking unknown ids are not sent raw, env defaults checked at the boundary
+
+Closes the round-4 review (SPEC-v9 D1; A.0.4, A.0.5, A.0.6, A.0.10). No check, test or threshold was weakened; no provider call was made.
+
+- **Operator overrides stay pass-through at every CLI entry point (D1, A.0.4).** Round 5 set `operatorSelected` in five scripts and
+  missed the rest. It is now also set in `evals/financeModelLive.ts`, `evals/managedLockPerf.ts`, `evals/professionalRuntimeLive.ts`,
+  `scripts/halo-live-path-calibration.ts`, `scripts/sfn-nonbtb-nodeagent-runner.ts` (`SFN_MODEL_ID`, found by the same search),
+  `src/eval/bankerToolBenchNodeAgentGeneral.ts` (`--model-id`) and `scripts/startup-diligence-provider-eval.ts`. The last one
+  calls `convexModel()`, which had no such option: `ConvexModelOptions.operatorSelected` now has the same contract as
+  `ModelAdapterOptions.operatorSelected`, and `normalizeFallbackModelIds` no longer re-resolves a primary id its caller already
+  resolved. Server code never sets it. `tests/modelKnownIds.test.ts` replaced its five-file regex pin with a scan of every
+  resolver call (balanced parentheses, so multi-line calls count) in twelve entry points.
+- **A free-looking unknown id is no longer sent under its raw name (A.0.10).** `aiSdkReasoner` and `streamPrivateReplyText` called
+  the resolver and threw the result away. Now the RESOLVED id is what dispatches. The streaming path routes `openrouter/free-auto`
+  to OpenRouter like any known free-auto input; the capture seam serves only Anthropic and OpenAI, so it refuses
+  (`capture_reasoner_route_unsupported`) instead of sending a free route to a provider that cannot serve it.
+- **Env defaults and the file-egress promotion pass the public-boundary check (A.0.10).** `defaultModelPolicyForRoute` ran
+  `knownModelPolicy` only on an explicit `modelPolicy`; the `AGENT_ORCHESTRATOR_MODEL` / `AGENT_MODEL` / `AGENT_TOP_PAID_MODEL` /
+  `AGENT_RESEARCH_MODEL` defaults and `configuredFileEgressModel()` now pass it too. Override precedence is unchanged.
+  `.tours/01-primary-user-flow.tour` step 7 moved from `agentJobs.ts:2798` to `:2799` (one comment line was added above it).
+- **Retained dotted ids keep the wire form main sent (A.0.5).** `claude-opus-4.1` and `claude-haiku-3.5` alias to
+  `claude-opus-4-1` and `claude-haiku-3-5` (the old regex did this for every dotted id), with hyphenated price rows at the
+  dotted rows' prices so they still price. `openrouter/auto`, the label `chooseNodeAgentRoute` gives the benchmark lane, is declared
+  known again (unpriced: a metered run still refuses it).
+- **`gemini-3.6-flash` context window (A.0.6).** `frontier.json` marks it UNVERIFIED. The value 1048576 is `context_length` for
+  `google/gemini-3.6-flash` on the public OpenRouter list (`GET /api/v1/models`, read 2026-10-16), now cited in the row.
+
+## 2026-10-17 — Review round 7: an operator-picked model is the model measured, the private stream refuses the free sentinel, pricing source 6 is exercised
+
+- **The startup-diligence eval measures the model the operator named (D1, A.0.4).** `--model gemini-not-in-catalog` reached the provider,
+  but the contract eval then passed that id to `agentJobs.createOrReuse` as `modelPolicy`, whose public boundary refuses an id outside the
+  catalog (`unknown_model_policy`). The candidate loop swallowed the error, sent a second paid request to `gemini-3.8-flash` and reported
+  that model. The job now always carries the catalog free route (the runner is stubbed, it is never dispatched); the model measured is
+  recorded on the attempt rows as before. Test: one request, one reported model.
+- **`judge()` takes `operatorSelected` (D1, A.0.4).** `evals/professionalLiveCatalog.ts` (`--model`) and `scripts/benchmark/run.ts`
+  (`JUDGE_MODEL`) pass it; `scripts/openrouter-free-discover.ts` keeps the strict resolver for its fixed id. Without the option nothing changes.
+- **The private stream refuses `openrouter/free-auto` before any request (A.0.10).** The sentinel is not an OpenRouter model id (the public
+  `/api/v1/models` list read 2026-10-17 has `openrouter/free` and `openrouter/auto`), so posting it failed every time, and the comment that
+  said the egress policy refused it was false. `streamPrivateReplyText` now throws `private_stream_free_auto_unsupported`.
+- **Tests.** Pricing source 6 (`proofloopModelTracking`) is called by the agreement test for every refresh row, the tier edge and the two retired
+  rows; the retired `claude-opus-4-1` / `claude-haiku-3-5` rows stay undated on purpose (main's prices, no vendor read). The Anthropic
+  `generateObject` parser tests assert no forced `tool_choice`, no `json` tool, native `output_config.format` and a `max_tokens` of at least 64K.
diff --git a/convex/agent.ts b/convex/agent.ts
index 657a22fd..bfa43ed9 100644
--- a/convex/agent.ts
+++ b/convex/agent.ts
@@ -19,6 +19,7 @@
 
 import { v } from "convex/values";
 import { makeFunctionReference } from "convex/server";
+import { DEFAULT_AGENT_MODEL, DEFAULT_FILE_EGRESS_MODEL } from "./modelDefaults";
 import { action } from "./_generated/server";
 import type { Id } from "./_generated/dataModel";
 import { actorProofV } from "./lib";
@@ -38,7 +39,7 @@ import { AgentRunError, runAgent } from "../src/nodeagent/core/runtime";
 import type { AgentTraceEvent } from "../src/nodeagent/core/types";
 import { SERVER_PRODUCTION_ROOM_TOOLS as PRODUCTION_ROOM_TOOLS } from "../src/nodeagent/skills/server/productionTools";
 import { MANAGED_LOCK_SYSTEM_PROMPT } from "../src/nodeagent/models/prompts/systemPrompt";
-import { convexModel as agentModel, convexPriceRun as priceRun } from "../src/nodeagent/models/convexModel";
+import { convexModel as agentModel, convexPriceRequest, convexPriceRun as priceRun } from "../src/nodeagent/models/convexModel";
 import { buildResearchContext, buildNoteContext, buildWallContext } from "../src/nodeagent/core/worldModel";
 import { injectMemoryIntoSystemPrompt } from "../src/nodemem/memoryContextBuilder";
 import { nodeMemInjectionEnabled, nodeMemRoomConfigEnabled } from "./nodemem";
@@ -62,7 +63,6 @@ const MIN_ACTION_RESERVE_MS = 10_000;
 const ACTION_SAFETY_MARGIN_MS = 15_000;
 const DEFAULT_CONTEXT_MAX_CHARS = 24_000;
 const DEFAULT_CONTEXT_KEEP_RECENT = 10;
-const DEFAULT_FILE_EGRESS_MODEL = "z-ai/glm-4.7-flash";
 const roomsFullRef = makeFunctionReference<"query">("rooms:full");
 const agentJobsCreateOrReuseRef = makeFunctionReference<"mutation">("agentJobs:createOrReuse") as any;
 const agentJobsFinishInteractiveRef = makeFunctionReference<"mutation">("agentJobs:finishInteractive") as any;
@@ -338,12 +338,13 @@ export const runRoomAgent = action({
     //  - research (background synthesis): deepseek-v4-flash — first route to clear the v3 composite-
     //    synthesis benchmark 9/9 at $0.0034/run (docs/eval/results.json; ~300x cheaper than gemini-3.5-flash's
     //    measured $1.10/task). Evidence covers the fetch->synthesize->write shape ONLY.
-    //  - interactive collaboration (lock/CAS/draft): stays on gemini-3.5-flash, the only route with a
-    //    recorded L1-L4 collaboration-ladder pass. flash gets this lane only after it passes the ladder.
+    //  - interactive collaboration (lock/CAS/draft): DEFAULT_AGENT_MODEL (gemini-3.8-flash). The recorded
+    //    L1-L4 collaboration-ladder pass is for gemini-3.5-flash (Google now serves it as 3.6); this default
+    //    merges only with docs/eval/ladder/model-refresh-noderoom.json (3.6 + 3.8, 8/8 pass).
     const egressArtifacts = providerEgressArtifactsFromRoomState(roomState);
     const requestedModelName = a.mode === "research"
       ? (process.env.AGENT_RESEARCH_MODEL ?? "minimax/minimax-m3")
-      : (process.env.AGENT_MODEL ?? "gemini-3.5-flash");
+      : (process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL);
     const model = agentModel(modelNameForEgress(requestedModelName, "public_ask", egressArtifacts), { entrypoint: "public_ask" });
     const egressDecision = providerEgressDecision({
       model: model.name,
@@ -643,7 +644,7 @@ export const runRoomAgent = action({
           maxTokens: envNumber("AGENT_MAX_TOKENS_PER_RUN", 250_000, 1_000, 4_000_000),
           maxCostUsd: envNumber("AGENT_MAX_USD_PER_RUN", 2, 0.01, 100),
         },
-        priceStep: (modelName, inputTokens, outputTokens) => priceRun(modelName, inputTokens, outputTokens),
+        priceStep: convexPriceRequest,
         onTrace: (event) => {
           void recordLiveOperation({
             kind: liveOperationKind(event),
@@ -780,7 +781,7 @@ export const runPrivateAgent = action({
     const requester = roomState.members.find((m: { id: unknown }) => String(m.id) === a.requester.actor.id) as { id: unknown; name: string } | undefined;
     if (!requester) throw new Error("member_required");
     const egressArtifacts = providerEgressArtifactsFromRoomState(roomState);
-    const model = agentModel(modelNameForEgress(process.env.AGENT_MODEL ?? "gemini-3.5-flash", "private_agent", egressArtifacts), { entrypoint: "private_agent" });
+    const model = agentModel(modelNameForEgress(process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL, "private_agent", egressArtifacts), { entrypoint: "private_agent" });
     const egressDecision = providerEgressDecision({
       model: model.name,
       entrypoint: "private_agent",
diff --git a/convex/agentJobRunner.ts b/convex/agentJobRunner.ts
index 259cbdb6..56c49c92 100644
--- a/convex/agentJobRunner.ts
+++ b/convex/agentJobRunner.ts
@@ -19,7 +19,7 @@ import { SERVER_PRODUCTION_ROOM_TOOLS as PRODUCTION_ROOM_TOOLS } from "../src/no
 import { MANAGED_LOCK_SYSTEM_PROMPT } from "../src/nodeagent/models/prompts/systemPrompt";
 import { injectMemoryIntoSystemPrompt } from "../src/nodemem/memoryContextBuilder";
 import { nodeMemInjectionEnabled, nodeMemRecordingEnabled, nodeMemRoomConfigEnabled } from "./nodemem";
-import { configuredConvexModelFallbacks, convexModel as agentModel, convexPriceRun as priceRun } from "../src/nodeagent/models/convexModel";
+import { configuredConvexModelFallbacks, convexModel as agentModel, convexPriceRequest, convexPriceRun as priceRun } from "../src/nodeagent/models/convexModel";
 import { qualityFailoverRetryAt } from "../src/nodeagent/models/qualityFailover";
 import { authorizedModelForFramePhase } from "../src/nodeagent/models/phaseModel";
 import { buildResearchContext, buildCompanyDeepDiveContext } from "../src/nodeagent/core/worldModel";
@@ -43,6 +43,7 @@ import {
 } from "../src/nodeagent/guardrails/egressPolicy";
 import { makeConvexStepJournal } from "./agentStepJournalClient";
 import { createVerifiedWorkbookWorkflowHook } from "../src/nodeagent/guardrails/workbookWorkflow";
+import { DEFAULT_AGENT_MODEL, DEFAULT_FILE_EGRESS_MODEL } from "./modelDefaults";
 
 const CONVEX_ACTION_LIMIT_MS = 10 * 60_000;
 const DEFAULT_SLICE_BUDGET_MS = 7 * 60_000;
@@ -53,7 +54,6 @@ const DEFAULT_LEASE_EXTRA_MS = 60_000;
 const DEFAULT_RESUME_DELAY_MS = 5_000;
 const DEFAULT_CONTEXT_MAX_CHARS = 24_000;
 const DEFAULT_CONTEXT_KEEP_RECENT = 10;
-const DEFAULT_FILE_EGRESS_MODEL = "z-ai/glm-4.7-flash";
 const RESUME_CHECKPOINT_PREFIX = "RESUME CHECKPOINT:";
 const agentJobsClaimSliceRef = makeFunctionReference<"mutation">("agentJobs:claimSlice") as any;
 const agentJobsFinishSliceRef = makeFunctionReference<"mutation">("agentJobs:finishSlice") as any;
@@ -509,7 +509,7 @@ export const runFreeAutoJobSlice = internalAction({
     const roomArtifacts = await ctx.runQuery(artifactsListForRoomRef, { roomId: claimed.roomId }) as Array<{ title?: string; kind?: string; meta?: unknown; visibility?: string }>;
     const egressArtifacts = providerEgressArtifactsForClaimedJob(roomArtifacts, claimed);
     let entrypoint = runnerEntrypoint(claimed);
-    const modelPolicy = claimed.modelPolicy || (entrypoint === "free" ? "openrouter/free-auto" : process.env.AGENT_MODEL ?? "gemini-3.5-flash");
+    const modelPolicy = claimed.modelPolicy || (entrypoint === "free" ? "openrouter/free-auto" : process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL);
     let resolvedModelPolicy = modelPolicy === "openrouter/free-auto"
       ? process.env.FREE_AUTO_JOB_MODEL ?? modelPolicy
       : modelPolicy;
@@ -928,7 +928,7 @@ export const runFreeAutoJobSlice = internalAction({
           deadlineAt,
           reserveMs,
           spendLimits,
-          priceStep: (modelName: string, inputTokens: number, outputTokens: number) => priceRun(modelName, inputTokens, outputTokens),
+          priceStep: convexPriceRequest,
           onTextDelta: (delta, step) => onPublicTextDelta(delta, step),
           onStreamEvent: (event) => recordStreamEvent(event),
           onTrace: (event) => {
@@ -961,7 +961,7 @@ export const runFreeAutoJobSlice = internalAction({
         // USD half reachable (P0-4: without it the gate received costUsd=0 and maxCostUsd was dead
         // surface — one env var pointing free-auto at a paid model meant unbounded spend).
         spendLimits,
-        priceStep: (modelName: string, inputTokens: number, outputTokens: number) => priceRun(modelName, inputTokens, outputTokens),
+        priceStep: convexPriceRequest,
         onTextDelta: (delta, step) => onPublicTextDelta(delta, step),
         onStreamEvent: (event) => recordStreamEvent(event),
         onTrace: (event) => {
diff --git a/convex/agentJobs.ts b/convex/agentJobs.ts
index a9178743..6b0bdc0a 100644
--- a/convex/agentJobs.ts
+++ b/convex/agentJobs.ts
@@ -28,13 +28,14 @@ import {
 } from "../src/nodeagent/guardrails/egressPolicy";
 import { parseBulkCompanyIngest } from "../src/nodeagent/skills/finance/bulkIngest";
 import { finalizePublicAgentJobStreamAfterTerminal } from "./agentStreamTerminal";
+import { DEFAULT_AGENT_MODEL, DEFAULT_FILE_EGRESS_MODEL, DEFAULT_TOP_PAID_MODEL } from "./modelDefaults";
+import { resolveModelAlias, UnknownModelError } from "../src/nodeagent/models/modelCatalog";
 
 // BOUND: cap a single bulk-diligence fan-out so one command can't enqueue unbounded jobs.
 const MAX_BULK_COMPANIES = 50;
 const MAX_INVESTIGATION_ELEMENTS = 8_192;
 const MAX_INVESTIGATION_WRITE_IDS = 8_192;
 const LEASE_EXPIRY_GRACE_MS = 30_000;
-const DEFAULT_FILE_EGRESS_MODEL = "z-ai/glm-4.7-flash";
 const INVESTIGATION_RESEARCH_GOAL = "Research every pending or stale company in the exact authorized dataset: claim only its editable research fields, retrieve public sources, write evidence-bearing summary/funding/headcount/recent_signal plus source/source2/last_researched/status, and release every managed lock.";
 const INVESTIGATION_WRITABLE_FIELD_IDS = [
   "summary",
@@ -2094,13 +2095,29 @@ function defaultEntrypointForRoute(routePolicy: RoutePolicy): DurableStartEntryp
   return routePolicy === "free_auto" ? "free" : "public_ask";
 }
 
-function defaultModelPolicyForRoute(args: { routePolicy: RoutePolicy; entrypoint: DurableStartEntrypoint; mode?: "variance" | "research"; modelPolicy?: string }) {
-  if (args.modelPolicy) return args.modelPolicy;
+/** SPEC A.0.10 at the public API boundary: a model string the catalog does not know is refused before a job row persists it. */
+function knownModelPolicy(modelPolicy: string): string {
+  try {
+    resolveModelAlias(modelPolicy);
+  } catch (error) {
+    if (error instanceof UnknownModelError) throw new Error("unknown_model_policy");
+    throw error;
+  }
+  return modelPolicy;
+}
+
+/** `runRoomAgent` records a PlanPreview-blocked run with this marker: no model runs for a blocked job, so there is no id to check. */
+const NO_MODEL_MARKER = "not_started";
+
+function defaultModelPolicyForRoute(args: { routePolicy: RoutePolicy; entrypoint: DurableStartEntrypoint; mode?: "variance" | "research"; modelPolicy?: string; initialStatus?: "running" | "blocked" }) {
+  if (args.modelPolicy === NO_MODEL_MARKER && args.initialStatus === "blocked") return args.modelPolicy;
+  if (args.modelPolicy) return knownModelPolicy(args.modelPolicy);
   if (args.routePolicy === "explicit") throw new Error("explicit_route_requires_modelPolicy");
   if (args.routePolicy === "free_auto" || args.entrypoint === "free") return "openrouter/free-auto";
-  if (args.routePolicy === "top_paid") return process.env.AGENT_TOP_PAID_MODEL ?? process.env.AGENT_MODEL ?? "anthropic/claude-sonnet-4";
-  if (args.mode === "research") return process.env.AGENT_RESEARCH_MODEL ?? process.env.AGENT_WORKER_MODEL ?? "minimax/minimax-m3";
-  return process.env.AGENT_ORCHESTRATOR_MODEL ?? process.env.AGENT_MODEL ?? "gemini-3.5-flash";
+  // Env defaults are operator-set strings and reach the job row like a caller's argument, so they pass the same boundary check.
+  if (args.routePolicy === "top_paid") return knownModelPolicy(process.env.AGENT_TOP_PAID_MODEL ?? process.env.AGENT_MODEL ?? DEFAULT_TOP_PAID_MODEL);
+  if (args.mode === "research") return knownModelPolicy(process.env.AGENT_RESEARCH_MODEL ?? process.env.AGENT_WORKER_MODEL ?? "minimax/minimax-m3");
+  return knownModelPolicy(process.env.AGENT_ORCHESTRATOR_MODEL ?? process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL);
 }
 
 function configuredFileEgressModel() {
@@ -2451,7 +2468,7 @@ async function startDurableAgentJob(ctx: any, a: DurableStartAgentJobArgs): Prom
       throw new Error("investigation_write_scope_empty");
     }
   }
-  let modelPolicy = defaultModelPolicyForRoute({ routePolicy, entrypoint, mode: a.mode, modelPolicy: a.modelPolicy });
+  let modelPolicy = defaultModelPolicyForRoute({ routePolicy, entrypoint, mode: a.mode, modelPolicy: a.modelPolicy, initialStatus: a.initialStatus });
   const egressArtifacts = await providerEgressArtifactsForRoom(ctx, a.roomId, artifact);
   const freeFileEgressDecision = providerEgressDecision({
     model: modelPolicy,
@@ -2464,7 +2481,7 @@ async function startDurableAgentJob(ctx: any, a: DurableStartAgentJobArgs): Prom
   if (promotedForFileEgress) {
     entrypoint = "public_ask";
     routePolicy = "explicit";
-    modelPolicy = configuredFileEgressModel();
+    modelPolicy = knownModelPolicy(configuredFileEgressModel());
   }
   const defaultMaxAttempts = execution === "inline"
     ? 1
diff --git a/convex/http.ts b/convex/http.ts
index 7403d7b4..26f00878 100644
--- a/convex/http.ts
+++ b/convex/http.ts
@@ -15,6 +15,7 @@ import type { StreamId } from "@convex-dev/persistent-text-streaming";
 import { streamingComponent } from "./streaming";
 import { streamPrivateReplyText } from "./streamingModel";
 import { privateAgentSystemPrompt } from "./agentPrompts";
+import { DEFAULT_AGENT_MODEL } from "./modelDefaults";
 import { auth } from "./auth";
 
 const http = httpRouter();
@@ -32,7 +33,7 @@ const NVIDIA_STT_MODEL = "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning";
 const NVIDIA_AUDIO_MAX_BYTES = 5 * 1024 * 1024;
 const CLOUDFLARE_AI_MODEL_TTS = "@cf/myshell-ai/melotts";
 const GEMINI_TTS_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
-const GEMINI_TTS_MODEL = "gemini-3.1-flash-tts-preview";
+const GEMINI_TTS_MODEL = "gemini-3.8-flash-tts";
 const GOOGLE_TTS_URL = "https://texttospeech.googleapis.com/v1/text:synthesize";
 type VoiceSttProvider = "openai" | "nvidia";
 type VoiceTtsProvider = "openai" | "cloudflare" | "gemini" | "google" | "disabled";
@@ -172,7 +173,7 @@ http.route({
       const userMsg = `ROOM CONTEXT\n${meta.roomContext}\n\n${meta.requesterName} asks: ${meta.goal}`;
       let answer = "";
       try {
-        answer = await streamPrivateReplyText(process.env.AGENT_MODEL ?? "gemini-3.5-flash", system, userMsg, append);
+        answer = await streamPrivateReplyText(process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL, system, userMsg, append);
       } catch (error) {
         // HONEST_STATUS: the partial text persists, the error is visible text, never a silent 2xx void.
         const msg = `(private agent error: ${error instanceof Error ? error.message.slice(0, 160) : "model call failed"})`;
diff --git a/convex/modelDefaults.ts b/convex/modelDefaults.ts
new file mode 100644
index 00000000..b19bbab4
--- /dev/null
+++ b/convex/modelDefaults.ts
@@ -0,0 +1,28 @@
+/**
+ * Convex-safe default model ids (no imports, no Node APIs). One literal per default so a model
+ * refresh edits one line. Env chains (AGENT_MODEL ?? ...) stay at the call sites.
+ *
+ * Spec: model-defaults SPEC Part A §A.2 (NodeRoom).
+ */
+
+/**
+ * Default agent model. Was "gemini-3.5-flash": Google deprecated it 2026-10-08 and auto-routes it
+ * to gemini-3.6-flash. Merge is gated on the L1-L4 ladder receipt in
+ * docs/eval/ladder/model-refresh-noderoom.json (see CHANGELOG/qa/model-refresh-noderoom.md).
+ */
+export const DEFAULT_AGENT_MODEL = "gemini-3.8-flash";
+
+/** File-egress fallback (OpenRouter). Listed, no expiry; unchanged by the refresh. */
+export const DEFAULT_FILE_EGRESS_MODEL = "z-ai/glm-4.7-flash";
+
+/**
+ * `top_paid` route default (convex/agentJobs.ts; env chain AGENT_TOP_PAID_MODEL ?? AGENT_MODEL ?? this stays at the call site).
+ * Was "anthropic/claude-sonnet-4" (retired 2026-06-15). SPEC-v9 D2 (Homen, 2026-10-16): no working OpenRouter key exists, so
+ * an OpenRouter-routed role moves to the newest `:free` model that the public https://openrouter.ai/api/v1/models list shows
+ * with the capabilities the role needs. This role runs the tool loop (forced tool_choice, tools, structured outputs) over long
+ * room context, so it needs `tools`, `tool_choice`, `structured_outputs` and a >= 256K context. List fetched
+ * 2026-10-16T11:32Z: nvidia/nemotron-3.5-super-vl:free (created 2026-10-15, 1,000,000 context, text output, no expiration_date).
+ * LIVE-UNVERIFIED (no key, Homen 2026-10-16): never called. Unlike the old paid default this is a free route, so a room with
+ * an uploaded file is blocked by the free-file-egress gate unless AGENT_TOP_PAID_MODEL / AGENT_MODEL is set (CHANGELOG/qa).
+ */
+export const DEFAULT_TOP_PAID_MODEL = "nvidia/nemotron-3.5-super-vl:free";
diff --git a/convex/streaming.ts b/convex/streaming.ts
index b8d10b62..a3ebf6b8 100644
--- a/convex/streaming.ts
+++ b/convex/streaming.ts
@@ -25,6 +25,7 @@ import { actorProofV, actorV, requireActiveAgentJobLease, requireActorCanUseChan
 import { summarizeRoomForPrivate } from "./agentPrompts";
 import { assertProviderEgressAllowed } from "../src/nodeagent/guardrails/egressPolicy";
 import { streamingComponent } from "./streamingComponent";
+import { DEFAULT_AGENT_MODEL } from "./modelDefaults";
 export { streamingComponent } from "./streamingComponent";
 
 const roomsFullRef = makeFunctionReference<"query">("rooms:full");
@@ -65,7 +66,7 @@ export const createPrivateReplyStream = mutation({
     const roomState = await ctx.runQuery(roomsFullRef, { roomId: a.roomId, requester: a.requester });
     if (!roomState) throw new Error("room_not_found");
     assertProviderEgressAllowed({
-      model: process.env.AGENT_MODEL ?? "gemini-3.5-flash",
+      model: process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL,
       entrypoint: "private_agent",
       artifacts: roomState.artifacts.map((art: { title: string; kind: string; meta?: unknown }) => ({
         title: art.title,
diff --git a/convex/streamingModel.ts b/convex/streamingModel.ts
index b8df4456..27816911 100644
--- a/convex/streamingModel.ts
+++ b/convex/streamingModel.ts
@@ -8,6 +8,8 @@
  */
 import { redactPII } from "../src/nodeagent/guardrails/gateway";
 import { assertProviderRouteAllowed } from "../src/nodeagent/guardrails/egressPolicy";
+import { isNodeAgentFreeAutoModel, resolveModelAlias } from "../src/nodeagent/models/modelCatalog";
+import { isOpenRouterFreeAutoModel } from "../src/nodeagent/models/openRouterFreeModels";
 import { openAiCompatibleTokenLimitParam } from "../src/nodeagent/models/openAiTokenLimit";
 
 export type StreamAppend = (text: string) => Promise<void>;
@@ -55,7 +57,13 @@ export async function streamPrivateReplyText(
   userMsg: string,
   append: StreamAppend,
 ): Promise<string> {
-  const route = assertProviderRouteAllowed({ model: modelId, entrypoint: "private_agent", env: process.env });
+  // SPEC A.0.10: an id the catalog does not know never dispatches (convexModel() throws the same error), and the RESOLVED id is
+  // what the egress policy routes: an unknown free-looking id becomes `openrouter/free-auto`. That is an internal sentinel (the
+  // free-model picker resolves it per call; so does `nodeagent/free-auto`), not an OpenRouter model id, and this single-shot stream has no picker, so it is
+  // refused here before any request instead of posting the sentinel or the raw string.
+  const resolved = resolveModelAlias(modelId);
+  if (isOpenRouterFreeAutoModel(resolved) || isNodeAgentFreeAutoModel(resolved)) throw new Error(`private_stream_free_auto_unsupported:${modelId}`);
+  const route = assertProviderRouteAllowed({ model: resolved, entrypoint: "private_agent", env: process.env });
   const safeSystem = redactPII(system).text;
   const safeUser = redactPII(userMsg).text;
   if (route.provider === "gemini") return geminiStream(route.resolvedModel, safeSystem, safeUser, append);
diff --git a/docs/eval/openrouter-free-models-2026-10-16.json b/docs/eval/openrouter-free-models-2026-10-16.json
new file mode 100644
index 00000000..9ae7c8e3
--- /dev/null
+++ b/docs/eval/openrouter-free-models-2026-10-16.json
@@ -0,0 +1,189 @@
+{
+  "source": "https://openrouter.ai/api/v1/models (public, no key)",
+  "fetchedAt": "2026-10-16T11:32:04Z",
+  "totalRows": 465,
+  "note": "SPEC-v9 D2: the :free rows of the public list. top_paid needs tools + tool_choice + structured_outputs, context >= 256000, text output, no expiration_date; the newest such row is selected.",
+  "selected": "nvidia/nemotron-3.5-super-vl:free",
+  "rows": [
+    {
+      "id": "nvidia/nemotron-3.5-super-vl:free",
+      "created": 1792076662,
+      "contextLength": 1000000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": true,
+      "expirationDate": null
+    },
+    {
+      "id": "dots-studio/dots-3-note-preview:free",
+      "created": 1786680361,
+      "contextLength": 512000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": true,
+      "expirationDate": "2026-12-31"
+    },
+    {
+      "id": "liquid/lfm-2.5-2.6b:free",
+      "created": 1786470519,
+      "contextLength": 65536,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": true,
+      "expirationDate": null
+    },
+    {
+      "id": "nvidia/nemotron-3.5-lightning:free",
+      "created": 1786452751,
+      "contextLength": 1000000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "thinkingmachines/inkling-small:free",
+      "created": 1785443117,
+      "contextLength": 1048576,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": false,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "poolside/laguna-s-2.1:free",
+      "created": 1784652683,
+      "contextLength": 262144,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": "2026-10-31"
+    },
+    {
+      "id": "thinkingmachines/inkling:free",
+      "created": 1784325956,
+      "contextLength": 1048576,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": false,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "poolside/laguna-xs-2.1:free",
+      "created": 1783002429,
+      "contextLength": 262144,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": "2026-10-31"
+    },
+    {
+      "id": "cohere/north-mini-code:free",
+      "created": 1781723748,
+      "contextLength": 256000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "nvidia/nemotron-3.5-content-safety:free",
+      "created": 1780581864,
+      "contextLength": 128000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": false,
+      "toolChoice": false,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "nvidia/nemotron-3-ultra-550b-a55b:free",
+      "created": 1780551208,
+      "contextLength": 1000000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+      "created": 1777393095,
+      "contextLength": 256000,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "google/gemma-4-26b-a4b-it:free",
+      "created": 1775227989,
+      "contextLength": 262144,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "google/gemma-4-31b-it:free",
+      "created": 1775148486,
+      "contextLength": 262144,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": false,
+      "expirationDate": null
+    },
+    {
+      "id": "nvidia/nemotron-3-super-120b-a12b:free",
+      "created": 1773245239,
+      "contextLength": 262144,
+      "outputModalities": [
+        "text"
+      ],
+      "tools": true,
+      "toolChoice": true,
+      "structuredOutputs": true,
+      "expirationDate": null
+    }
+  ]
+}
\ No newline at end of file
diff --git a/evals/chatIntakeRuntime.ts b/evals/chatIntakeRuntime.ts
index ed011286..1ff9aa1d 100644
--- a/evals/chatIntakeRuntime.ts
+++ b/evals/chatIntakeRuntime.ts
@@ -533,7 +533,7 @@ if (isCli) {
   const route = optionValue("--real");
   const lockMode: ChatIntakeLockMode = process.argv.includes("--managed-locks") ? "runtime_managed_lock" : "explicit_agent_lock";
   const agent = route
-    ? (await import("../src/nodeagent/models/adapter")).model(route)
+    ? (await import("../src/nodeagent/models/adapter")).model(route, { operatorSelected: true })
     : scriptedModel(
       lockMode === "runtime_managed_lock" ? chatIntakeManagedCapturePlan() : chatIntakeCapturePlan(),
       lockMode === "runtime_managed_lock" ? "scripted-chat-intake-managed" : "scripted-chat-intake",
diff --git a/evals/financeModelLive.ts b/evals/financeModelLive.ts
index 2113b48b..6ccde665 100644
--- a/evals/financeModelLive.ts
+++ b/evals/financeModelLive.ts
@@ -1022,7 +1022,7 @@ async function main(): Promise<void> {
   const traceRefs: string[] = [];
 
   for (let run = 1; run <= runs; run++) {
-    const agent = scripted ? scriptedModel(financeModelSolvePlan(gold), `scripted-finance-solver-${run}`) : realModel(route);
+    const agent = scripted ? scriptedModel(financeModelSolvePlan(gold), `scripted-finance-solver-${run}`) : realModel(route, { operatorSelected: true });
     const roomVariant = variantCycle[(run - 1) % variantCycle.length];
     const report = await runFinanceModelLiveSolve({
       gold, pack, agent,
diff --git a/evals/ladder.ts b/evals/ladder.ts
index bb17f2b5..a8e86451 100644
--- a/evals/ladder.ts
+++ b/evals/ladder.ts
@@ -6,8 +6,10 @@
  *   npm run ladder:real -- gpt-5.4-nano,gemini-3.1-flash-lite
  */
 import "../scripts/benchmark/loadEnv";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
 import { appendEvalRuns, computeCaseSetHash, DEFAULT_STORE, runKey, type EvalRunRecord } from "./evalStore";
 import { dirname, join, relative, resolve } from "node:path";
 import { z } from "zod";
@@ -20,7 +22,20 @@ import { runAgent } from "../src/nodeagent/core/runtime";
 import type { AgentMessage, AgentModel, AgentResult, AgentTool, AgentTraceEvent, RoomTools } from "../src/nodeagent/core/types";
 import { scriptedModel, type Planner } from "../src/nodeagent/models/scripted";
 import { recomputeVariancePlan } from "../src/nodeagent/core/plans";
-import { model as realModel, priceRun } from "../src/nodeagent/models/adapter";
+import {
+  MAX_DISPATCH_RECORDS,
+  createSpendMeter,
+  model as realModel,
+  priceRequest,
+  openRouterFreeAutoLimit,
+  priceRequestStrict,
+  requestInputTokenUpperBound,
+  type DispatchPolicy,
+  type DispatchRecord,
+  type SpendMeter,
+} from "../src/nodeagent/models/adapter";
+import { getModelPricing, lookupModelAlias, priceTokens, resolveModelAlias } from "../src/nodeagent/models/modelCatalog";
+import { modelMaxOutputTokens } from "../src/nodeagent/models/outputTokens";
 import { selectOpenRouterFreeModels } from "../src/nodeagent/models/openRouterFreeModels";
 import { stableJournalHash } from "../src/nodeagent/core/journal";
 
@@ -97,6 +112,23 @@ interface Rung {
 interface RuntimeBudget {
   rungTimeoutMs?: number;
   reserveMs: number;
+  /** Dollar cap for a --real run (LADDER_MAX_COST_USD / --max-cost-usd). Mandatory when any provider is called. */
+  maxCostUsd?: number;
+}
+
+/** Every --real run: no adapter retries, no cross-model fallback, so one step = at most one reserved request. */
+export const RECEIPT_DISPATCH_POLICY: DispatchPolicy = { maxRetries: 0, crossModelFallback: false };
+
+interface LadderBudgetReport {
+  maxUsd: number;
+  estimateUsd: number;
+  spentUsd: number;
+  requests: number;
+  /** Pre-flight request ceiling (routes x rungs x max steps, fan-out included); `requests` above it fails review (A.0.3). */
+  requestCeiling: number;
+  stoppedBy: SpendMeter["stoppedBy"];
+  /** Requests past the dispatch-record cap: counted in `requests`/`spentUsd` but absent from `rows`. Non-zero means the receipt's rows are incomplete. */
+  dispatchesDropped: number;
 }
 
 interface RungResult {
@@ -116,6 +148,8 @@ interface RungResult {
   checks: Record<string, boolean>;
   /** P1-5: for each FAILING trace-derived check, a pointer at the offending trace event. */
   checkDetails?: Record<string, string>;
+  /** Every provider request this rung issued (metered runs only): echoed model, usage, cost, fallbackUsed. */
+  dispatches?: DispatchRecord[];
   trace: AgentTraceEvent[];
 }
 
@@ -562,7 +596,7 @@ function checkFailurePointers(rung: Rung, result: AgentResult, checks: Record<st
   return out;
 }
 
-async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName: string, budget: RuntimeBudget): Promise<RungResult> {
+async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName: string, budget: RuntimeBudget, meter?: SpendMeter): Promise<RungResult> {
   const env = (rung.makeEnv ?? demoEnv)();
   rung.setup?.(env);
   const rt = new CountingRoomTools(env.engine, env.roomId, env.artifactId, env.actor, env.sessionId, env.stats);
@@ -581,6 +615,10 @@ async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName:
   };
   const t0 = Date.now();
   const deadlineAt = budget.rungTimeoutMs ? t0 + budget.rungTimeoutMs : undefined;
+  const dispatchesFrom = meter?.dispatches.length ?? 0;
+  // Rung cost is the meter's own spend delta, not the sum of recorded rows: rows stop at MAX_DISPATCH_RECORDS, spend does not.
+  const spentFrom = meter?.spentUsd ?? 0;
+  const rungDispatches = () => (meter ? { dispatches: meter.dispatches.slice(dispatchesFrom) } : {});
   try {
     const runOnce = (goal: string, m: AgentModel, maxSteps: number) => runAgent({
       rt,
@@ -593,6 +631,9 @@ async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName:
       deadlineAt,
       reserveMs: budget.reserveMs,
       onTrace: (event) => rung.onTrace?.(event, env),
+      // A metered run hands the runtime the dollars still left job-wide and the strict (throwing) price.
+      // The tier belongs to one request's prompt, so a step is priced per request (never from aggregated usage).
+      ...(meter ? { spendLimits: { maxCostUsd: Math.max(0, meter.maxUsd - meter.spentUsd) }, priceStep: priceRequestStrict } : { priceStep: priceRequest }),
     });
     let result: AgentResult;
     let slice1: AgentResult | undefined;
@@ -625,8 +666,11 @@ async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName:
     const combinedTrace = slice1
       ? [...slice1.trace, { step: -1, tool: "slice_boundary", args: { forced: true, slice1Exhausted: slice1.exhausted }, result: { handoff: slice1.handoff?.summary ?? null }, ms: 0 } as AgentTraceEvent, ...result.trace]
       : result.trace;
-    const cost = (result.usage ? priceRun(resolvedModel, result.usage.inputTokens, result.usage.outputTokens) : 0)
-      + (slice1?.usage ? priceRun(resolvedModel, slice1.usage.inputTokens, slice1.usage.outputTokens) : 0);
+    // Per-request costs only: the meter's settled dispatches on a metered run (a paid run never costs a guessed
+    // $1/$5 row), the runtime's per-step priced total otherwise. Never price summed usage: a tier is per request.
+    const cost = meter
+      ? meter.spentUsd - spentFrom
+      : (result.usage?.costUsd ?? 0) + (slice1?.usage?.costUsd ?? 0);
     return {
       pass,
       checkDetails,
@@ -642,6 +686,7 @@ async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName:
       handoff: result.handoff?.summary,
       reason: pass ? "" : rung.diagnose?.(result, env) ?? result.handoff?.summary ?? "failed",
       checks,
+      ...rungDispatches(),
       trace: combinedTrace,
     };
   } catch (error) {
@@ -655,9 +700,11 @@ async function runRung(rung: Rung, maker: (rung: Rung) => AgentModel, modelName:
       level: rung.level,
       ms: Date.now() - t0,
       tools: 0,
-      cost: 0,
+      // A rung that failed after issuing charged dispatches still spent that money: the row carries it, as in the try branch.
+      cost: meter ? meter.spentUsd - spentFrom : 0,
       error: error instanceof Error ? error.message : String(error),
       checks: { completed: false },
+      ...rungDispatches(),
       trace: [],
     };
   }
@@ -691,6 +738,7 @@ function parseRuntimeBudget(): RuntimeBudget {
   return {
     rungTimeoutMs: optionNumber("--rung-timeout-ms", "LADDER_RUNG_TIMEOUT_MS"),
     reserveMs: optionNumber("--reserve-ms", "LADDER_RESERVE_MS") ?? 5_000,
+    maxCostUsd: optionNumber("--max-cost-usd", "LADDER_MAX_COST_USD"),
   };
 }
 
@@ -737,17 +785,45 @@ async function parseModelRoutes(): Promise<string[]> {
   return routes;
 }
 
-function writeJsonReport(results: RungResult[], selectedRungs: Rung[], requestedRoutes: string[]): void {
+/** What makes a --real report a receipt (SPEC A.0.3): the tested commit, the constant it tested, the spend, the policy. */
+interface ReportReceipt {
+  startedAt: string;
+  budget: LadderBudgetReport | null;
+  dispatchPolicy: DispatchPolicy | null;
+}
+
+/** Run environment a reviewer needs to reproduce the receipt. No keys, no hostnames, no paths. */
+function receiptEnvironment(): { node: string; platform: string; ci: boolean } {
+  return { node: process.version, platform: process.platform, ci: Boolean(process.env.CI) };
+}
+
+function sha256OfFile(path: string): string | null {
+  try { return createHash("sha256").update(readFileSync(path)).digest("hex"); } catch { return null; }
+}
+
+function writeJsonReport(results: RungResult[], selectedRungs: Rung[], requestedRoutes: string[], receipt: ReportReceipt): void {
   const outPath = optionValue("--json-out");
   if (!outPath) return;
   const absolute = resolve(process.cwd(), outPath);
   mkdirSync(dirname(absolute), { recursive: true });
+  const real = receipt.budget !== null;
+  const identity = real ? readGitIdentity() : undefined;
+  // One flat row per provider request (A.0.3 `rows`), tagged with the rung that issued it.
+  const rows = results.flatMap((r) => (r.dispatches ?? []).map((d) => ({ rung: r.rung, ...d })));
+  const echoedModels = [...new Set(rows.map((r) => r.echoedModel).filter((m): m is string => m !== null))];
   writeFileSync(
     absolute,
     JSON.stringify({
       generatedAt: new Date().toISOString(),
+      startedAt: receipt.startedAt,
+      ...(real ? { command: ["tsx", "evals/ladder.ts", ...process.argv.slice(2)].join(" ") } : {}),
       requestedRoutes,
+      ...(real ? { candidateIds: requestedRoutes, echoedModels, rows } : {}),
       rungs: selectedRungs.map((r) => ({ id: r.id, level: r.level, label: r.label })),
+      ...(identity ? { testedCommit: identity.commitSha, gitDirty: identity.gitDirty, constantSha256: sha256OfFile("convex/modelDefaults.ts") } : {}),
+      budget: receipt.budget,
+      dispatchPolicy: receipt.dispatchPolicy,
+      ...(real ? { environment: receiptEnvironment() } : {}),
       results: results.map(publicResult),
     }, null, 2),
   );
@@ -817,7 +893,8 @@ function readGitIdentity(): GitIdentity {
   let commitSha = "nocommit";
   let status = "";
   let diff = "";
-  try { commitSha = execSync("git rev-parse --short HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { /* not a git repo */ }
+  // Full SHA: the receipt's testedCommit must be an ancestor-checkable 40-hex id (SPEC A.0.3), not a short prefix.
+  try { commitSha = execSync("git rev-parse HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { /* not a git repo */ }
   try { status = execSync("git status --porcelain=v1", { stdio: ["ignore", "pipe", "ignore"] }).toString(); } catch { /* not a git repo */ }
   try { diff = execSync("git diff --no-ext-diff --binary HEAD --", { stdio: ["ignore", "pipe", "ignore"], maxBuffer: 16 * 1024 * 1024 }).toString(); } catch { /* large or unavailable diff */ }
   const gitDirty = status.trim().length > 0;
@@ -857,24 +934,134 @@ function normalizePath(value: string): string {
   return value.replace(/\\/g, "/");
 }
 
-async function main() {
+/** Opening-context size and per-step growth of one rung, read from a scripted dry run (zero provider requests). */
+interface RungShape {
+  rung: Rung;
+  ctxTokens0: number;
+  growthTokens: number;
+  /** Provider-request upper bound for one model on this rung (resume rungs run two slices). */
+  maxSteps: number;
+}
+
+async function scriptedRungShape(rung: Rung, budget: RuntimeBudget): Promise<RungShape> {
+  const sizes: number[] = [];
+  const probe = (r: Rung): AgentModel => {
+    const base = r.scripted();
+    return {
+      get name() { return base.name; },
+      async next(input) {
+        sizes.push(requestInputTokenUpperBound(input.system, input.messages, input.tools));
+        return base.next(input);
+      },
+    };
+  };
+  await runRung(rung, probe, "scripted", { ...budget, maxCostUsd: undefined });
+  const ctxTokens0 = sizes[0] ?? 0;
+  const growthTokens = sizes.length > 1 ? Math.max(0, ((sizes.at(-1) ?? 0) - ctxTokens0) / (sizes.length - 1)) : 0;
+  const maxSteps = (rung.maxSteps ?? 18) + (rung.resume?.slice1MaxSteps ?? 0);
+  return { rung, ctxTokens0, growthTokens, maxSteps };
+}
+
+/**
+ * Provider-request ceiling for the grid: routes x rungs x max steps. A free-auto route fans out over the candidate
+ * limit the ADAPTER enforces (`openRouterFreeAutoLimit`), not over `--free-auto-top`, which only decides which extra
+ * concrete routes join the grid.
+ */
+export function ladderRequestCeiling(routes: string[], shapes: RungShape[], freeAutoCandidates = openRouterFreeAutoLimit()): number {
+  const steps = shapes.reduce((sum, shape) => sum + shape.maxSteps, 0);
+  return routes.reduce((sum, route) => sum + routeFanOut(route, freeAutoCandidates) * steps, 0);
+}
+
+/** Dispatch resolves aliases first ("free", "openrouter-auto" -> openrouter/free-auto), so the fan-out test must too. */
+function routeFanOut(route: string, freeAutoCandidates: number): number {
+  return /free-auto$/i.test(resolveModelAlias(route)) ? Math.max(1, freeAutoCandidates) : 1;
+}
+
+/**
+ * Worst-case USD before the first paid request:
+ *   Σ_models Σ_rungs Σ_{step=1..maxSteps} ((ctx0 + (step-1)·growth) · inPerM + maxOut · outPerM) / 1e6.
+ * ctx0 and growth come from the scripted dry run, so this is a pre-flight sanity bound ("can the cap cover a full
+ * grid at all?"), not the spend guard: the guard is the per-dispatch reservation, which prices each request's real
+ * input bytes. A free-auto route fans out over its candidates, so it multiplies by the candidate limit. The
+ * request count holds only under RECEIPT_DISPATCH_POLICY: with retries and fallback each step could issue several.
+ */
+export function estimateLadderUsd(routes: string[], shapes: RungShape[], freeAutoCandidates = openRouterFreeAutoLimit()): number {
+  let total = 0;
+  for (const route of routes) {
+    const pricing = getModelPricing(resolveModelAlias(route));
+    if (!pricing) throw new Error(`no pricing row for "${route}"`);
+    const maxOut = modelMaxOutputTokens(resolveModelAlias(route));
+    const fanOut = routeFanOut(route, freeAutoCandidates);
+    for (const shape of shapes) {
+      for (let step = 1; step <= shape.maxSteps; step++) {
+        total += fanOut * priceTokens(pricing, shape.ctxTokens0 + (step - 1) * shape.growthTokens, maxOut);
+      }
+    }
+  }
+  return total;
+}
+
+export async function main() {
   const realModels = await parseModelRoutes();
   const budget = parseRuntimeBudget();
-  const models: { name: string; maker: (rung: Rung) => AgentModel }[] = realModels.length
-    ? realModels.map((id) => ({ name: id, maker: () => realModel(id) }))
-    : [{ name: "scripted", maker: (rung) => rung.scripted() }];
-
+  const startedAt = new Date().toISOString();
   const rungFilter = parseRungFilter();
   const selectedRungs = rungFilter ? RUNGS.filter((r) => rungFilter.has(r.id)) : RUNGS;
+  const real = realModels.length > 0;
+
+  let meter: SpendMeter | undefined;
+  let estimateUsd = 0;
+  let requestCeiling = 0;
+  const budgetReport = (): LadderBudgetReport | null => (meter
+    ? { maxUsd: meter.maxUsd, estimateUsd, spentUsd: meter.spentUsd, requests: meter.requests, requestCeiling, stoppedBy: meter.stoppedBy, dispatchesDropped: meter.droppedDispatches }
+    : null);
+  const refuse = (message: string) => {
+    console.error(`ladder: ${message}`);
+    writeJsonReport([], selectedRungs, realModels, { startedAt, budget: budgetReport(), dispatchPolicy: RECEIPT_DISPATCH_POLICY });
+    process.exitCode = 1;
+  };
+
+  if (real) {
+    // A paid run needs a dollar cap, and every id it will call must have a verified price: no cap, no guessed row.
+    if (budget.maxCostUsd === undefined) {
+      console.error("ladder: --real needs a dollar cap (LADDER_MAX_COST_USD or --max-cost-usd). Refusing to start; no request was made.");
+      process.exitCode = 1;
+      return;
+    }
+    meter = createSpendMeter(budget.maxCostUsd);
+    const unpriced = realModels.find((id) => !getModelPricing(lookupModelAlias(id)));
+    if (unpriced) {
+      meter.stoppedBy = "unpriced_model";
+      refuse(`no pricing row for "${unpriced}"; add a verified row (modelCatalog.modelPricing) before a paid run. No request was made.`);
+      return;
+    }
+    const shapes: RungShape[] = [];
+    for (const rung of selectedRungs) shapes.push(await scriptedRungShape(rung, budget));
+    estimateUsd = estimateLadderUsd(realModels, shapes);
+    requestCeiling = ladderRequestCeiling(realModels, shapes);
+    console.log(`pre-flight: worst case $${estimateUsd.toFixed(4)} for ${realModels.length} route(s) x ${selectedRungs.length} rung(s); cap $${meter.maxUsd.toFixed(4)}`);
+    if (estimateUsd > meter.maxUsd) {
+      meter.stoppedBy = "spend_budget";
+      refuse(`worst-case estimate $${estimateUsd.toFixed(4)} exceeds the $${meter.maxUsd.toFixed(4)} cap. Raise the cap or narrow --levels; no request was made.`);
+      return;
+    }
+  }
+
+  const models: { name: string; maker: (rung: Rung) => AgentModel }[] = real
+    ? realModels.map((id) => ({ name: id, maker: () => realModel(id, { dispatch: RECEIPT_DISPATCH_POLICY, meter, operatorSelected: true }) }))
+    : [{ name: "scripted", maker: (rung) => rung.scripted() }];
 
   const grid: Record<string, Record<string, boolean>> = {};
   const results: RungResult[] = [];
   for (const model of models) {
     grid[model.name] = {};
     for (const rung of selectedRungs) {
+      if (meter?.stoppedBy) break; // the cap is reached: no further rung may spend
       process.stdout.write(`  ${model.name} · ${rung.id} ... `);
-      const res = await runRung(rung, model.maker, model.name, budget);
+      const res = await runRung(rung, model.maker, model.name, budget, meter);
       results.push(res);
+      // The runtime's own pre-call gate can end a rung on the cap before the adapter is asked to dispatch.
+      if (meter && res.stopReason === "spend_budget") meter.stoppedBy ??= "spend_budget";
       grid[model.name][rung.id] = res.pass;
       const stop = "stopReason" in res && res.stopReason !== "done" ? `, ${res.stopReason}` : "";
       const resolved = res.resolvedModel !== model.name ? `, resolved=${res.resolvedModel}` : "";
@@ -891,13 +1078,18 @@ async function main() {
   }
   console.log("-".repeat(72));
   console.log("legend: " + selectedRungs.map((r) => `L${r.level}=${r.label}`).join(" | "));
-  writeJsonReport(results, selectedRungs, models.map((m) => m.name));
+  if (meter) console.log(`spend: $${meter.spentUsd.toFixed(4)} of $${meter.maxUsd.toFixed(4)} over ${meter.requests} provider request(s)${meter.droppedDispatches ? `; ${meter.droppedDispatches} request(s) have no receipt row (cap ${MAX_DISPATCH_RECORDS})` : ""}${meter.stoppedBy ? `; STOPPED by ${meter.stoppedBy} (not a receipt)` : ""}`);
+  writeJsonReport(results, selectedRungs, models.map((m) => m.name), { startedAt, budget: budgetReport(), dispatchPolicy: real ? RECEIPT_DISPATCH_POLICY : null });
   recordRunsToStore(results);
 
+  if (meter?.stoppedBy) process.exitCode = 1; // a budget stop is an incomplete run, never a pass
+  if (meter?.droppedDispatches) process.exitCode = 1; // requests past the record cap have no receipt row: incomplete, never a pass
   if (Object.values(grid).some((row) => Object.values(row).some((ok) => !ok))) process.exitCode = 1;
 }
 
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
diff --git a/evals/ladderBudget.test.ts b/evals/ladderBudget.test.ts
new file mode 100644
index 00000000..9135541d
--- /dev/null
+++ b/evals/ladderBudget.test.ts
@@ -0,0 +1,528 @@
+/**
+ * Ladder spend budget (SPEC Part A §A.2.9 "Ladder budget", Codex R1, v4-new-2, v5-new-1).
+ *
+ * Tests the ACTUAL adapter path, not a fake AgentModel: `model(id, { dispatch, meter })` runs the real AI-SDK
+ * Google provider with `fetch` replaced by a fake transport that counts physical requests. The claims:
+ *   - the meter moves at DISPATCHES (one reservation per physical request, retries and fallbacks included);
+ *   - a request whose worst case would cross the cap is never issued;
+ *   - the AI SDK's own retry loop adds no request of its own (pinned to 0);
+ *   - an id the catalog cannot price is refused before any request, never reserved at a guessed price.
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createSpendMeter,
+  model,
+  priceRequestStrict,
+  requestInputTokenUpperBound,
+  reserveDispatch,
+  SpendBudgetError,
+  UnpricedModelError,
+  type DispatchPolicy,
+} from "../src/nodeagent/models/adapter";
+import { UnknownModelError } from "../src/nodeagent/models/modelCatalog";
+import { modelMaxOutputTokens } from "../src/nodeagent/models/outputTokens";
+
+const PRICED = "gemini-3.8-flash";
+// Round 3 (SPEC A.0.10): an id the catalog has never heard of no longer reaches the adapter at all. `UNPRICED` was
+// "routes to the Google provider, has no pricing row" and used to be dispatched; it now throws UnknownModelError at
+// model() (see the A.0.10 test below). The (g) invariants - zero requests, meter untouched, terminal stop - are about an
+// id the adapter CAN route but the catalog cannot price, which is now only an id the alias table declares without a
+// price row: a persisted-room string such as "claude-sonnet-4.5" (resolves to claude-sonnet-4-5, priced nowhere).
+const UNPRICED = "gemini-9.9-unpriced-test";
+const UNPRICED_ALIAS = "claude-sonnet-4.5";
+const RECEIPT: DispatchPolicy = { maxRetries: 0, crossModelFallback: false };
+const TURN = { system: "s", messages: [{ role: "user" as const, content: "hi" }], tools: [] };
+const BOUND = requestInputTokenUpperBound(TURN.system, TURN.messages, TURN.tools);
+const RESERVE = reserveDispatch(PRICED, BOUND, Number.POSITIVE_INFINITY);
+
+type Call = { url: string; body: Record<string, any> };
+let calls: Call[] = [];
+let billedUsd = 0;
+
+function ok(inputTokens = 1_000, outputTokens = 200) {
+  return new Response(JSON.stringify({
+    candidates: [{ content: { role: "model", parts: [{ text: "ok" }] }, finishReason: "STOP", index: 0 }],
+    usageMetadata: { promptTokenCount: inputTokens, candidatesTokenCount: outputTokens, totalTokenCount: inputTokens + outputTokens },
+  }), { status: 200, headers: { "content-type": "application/json" } });
+}
+const unavailable = () => new Response(JSON.stringify({ error: { code: 503, message: "Service unavailable", status: "UNAVAILABLE" } }), { status: 503, headers: { "content-type": "application/json" } });
+
+function fakeTransport(answer: (n: number, call: Call) => Response | Promise<Response>) {
+  calls = [];
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const call: Call = { url, body: JSON.parse(typeof init?.body === "string" ? init.body : "{}") };
+    calls.push(call);
+    return answer(calls.length, call);
+  });
+}
+
+const SAVED = { key: process.env.GOOGLE_GENERATIVE_AI_API_KEY, fb: process.env.AGENT_FALLBACK_MODEL, cap: process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS, ladderCap: process.env.LADDER_MAX_COST_USD };
+beforeEach(() => {
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+  delete process.env.AGENT_FALLBACK_MODEL;
+  delete process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS;
+  delete process.env.LADDER_MAX_COST_USD;
+  billedUsd = 0;
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+  for (const [k, v] of [["GOOGLE_GENERATIVE_AI_API_KEY", SAVED.key], ["AGENT_FALLBACK_MODEL", SAVED.fb], ["AGENT_MODEL_MAX_OUTPUT_TOKENS", SAVED.cap], ["LADDER_MAX_COST_USD", SAVED.ladderCap]] as const) {
+    if (v === undefined) delete process.env[k]; else process.env[k] = v;
+  }
+});
+
+describe("meter moves at dispatches (adapter path, fake transport)", () => {
+  it("(a) a charged response then ECONNRESET under the receipt policy: exactly two dispatches, error propagates, failed reservation is kept", async () => {
+    fakeTransport((n) => {
+      if (n === 1) return ok(1_000, 200);
+      throw Object.assign(new Error("fetch failed: ECONNRESET"), { code: "ECONNRESET" });
+    });
+    const meter = createSpendMeter(10);
+    const m = model(PRICED, { dispatch: RECEIPT, meter });
+
+    await m.next(TURN);
+    expect(meter.requests).toBe(1);
+    expect(meter.spentUsd).toBeCloseTo(priceRequestStrict(PRICED, 1_000, 200), 12); // reservation replaced by the priced usage
+
+    await expect(m.next(TURN)).rejects.toThrow(/ECONNRESET/);
+    expect(calls).toHaveLength(2); // maxRetries 0: no retry, no SDK retry, no fallback
+    expect(meter.requests).toBe(2);
+    expect(meter.spentUsd).toBeCloseTo(priceRequestStrict(PRICED, 1_000, 200) + RESERVE, 12); // the failed dispatch's reservation is retained
+  });
+
+  it("(b) the same sequence (charged response, then ECONNRESET) under the default policy reserves once per attempt and never crosses the cap", async () => {
+    vi.useFakeTimers();
+    fakeTransport((n) => {
+      if (n === 1) return ok(1_000, 200);
+      throw Object.assign(new Error("fetch failed: ECONNRESET"), { code: "ECONNRESET" }); // transient: the default policy retries it
+    });
+    const first = priceRequestStrict(PRICED, 1_000, 200);
+    const meter = createSpendMeter(first + RESERVE * 2.5); // after the charged answer: room for two more reservations, not three
+    const m = model(PRICED, { meter }); // default policy: 3 retries, fallback allowed (no AGENT_FALLBACK_MODEL set)
+
+    await m.next(TURN);
+    expect(calls).toHaveLength(1);
+    expect(meter.spentUsd).toBeCloseTo(first, 12);
+
+    const outcome = m.next(TURN).then(() => null, (e: unknown) => e);
+    await vi.advanceTimersByTimeAsync(120_000);
+    const error = await outcome;
+
+    expect(error).toBeInstanceOf(SpendBudgetError);
+    expect((error as SpendBudgetError).receipt.stopReason).toBe("spend_budget");
+    expect(calls).toHaveLength(3); // the charged answer + two reset attempts; the attempt whose reservation would cross the cap is not issued
+    expect(meter.requests).toBe(3);
+    expect(meter.spentUsd).toBeCloseTo(first + RESERVE * 2, 12); // each issued attempt kept its own reservation
+    expect(meter.spentUsd).toBeLessThanOrEqual(meter.maxUsd);
+    expect(meter.stoppedBy).toBe("spend_budget");
+  });
+
+  it("every issued request leaves one receipt row: requested/resolved id, the provider's echoed model, usage, cost, fallbackUsed", async () => {
+    fakeTransport(() => new Response(JSON.stringify({
+      candidates: [{ content: { role: "model", parts: [{ text: "ok" }] }, finishReason: "STOP", index: 0 }],
+      usageMetadata: { promptTokenCount: 1_000, candidatesTokenCount: 200, totalTokenCount: 1_200 },
+      modelVersion: "gemini-3.6-flash", // Google serving the request under another model than the one asked for
+    }), { status: 200, headers: { "content-type": "application/json" } }));
+    const meter = createSpendMeter(10);
+    await model(PRICED, { dispatch: RECEIPT, meter }).next(TURN);
+    expect(meter.dispatches).toEqual([{
+      requestedModel: PRICED,
+      resolvedModel: PRICED,
+      echoedModel: "gemini-3.6-flash",
+      usage: { inputTokens: 1_000, outputTokens: 200 },
+      costUsd: priceRequestStrict(PRICED, 1_000, 200),
+      fallbackUsed: false,
+    }]);
+  });
+
+  it("a cross-model fallback dispatch is marked fallbackUsed: true (the receipt rejects such a row)", async () => {
+    vi.useFakeTimers();
+    process.env.AGENT_FALLBACK_MODEL = "gemini-3.5-flash-lite";
+    fakeTransport((_n, call) => call.url.includes("/models/gemini-3.5-flash-lite:") ? ok(100, 10) : unavailable());
+    const meter = createSpendMeter(10);
+    const outcome = model(PRICED, { meter }).next(TURN); // default policy: 4 attempts on the primary, then the fallback model
+    await vi.advanceTimersByTimeAsync(120_000);
+    await outcome;
+    expect(meter.dispatches.map((d) => [d.resolvedModel, d.requestedModel, d.fallbackUsed])).toEqual([
+      [PRICED, PRICED, false], [PRICED, PRICED, false], [PRICED, PRICED, false], [PRICED, PRICED, false],
+      ["gemini-3.5-flash-lite", PRICED, true],
+    ]);
+  });
+
+  it("a request that throws keeps its full reservation as its row cost, with no echoed model or usage", async () => {
+    fakeTransport(() => { throw Object.assign(new Error("fetch failed: ECONNRESET"), { code: "ECONNRESET" }); });
+    const meter = createSpendMeter(10);
+    await expect(model(PRICED, { dispatch: RECEIPT, meter }).next(TURN)).rejects.toThrow(/ECONNRESET/);
+    expect(meter.dispatches).toEqual([{ requestedModel: PRICED, resolvedModel: PRICED, echoedModel: null, usage: null, costUsd: RESERVE, fallbackUsed: false }]);
+  });
+
+  it("(c) a reservation above the remaining budget before the first dispatch throws spend_budget with zero fetch calls", async () => {
+    fakeTransport(() => ok());
+    const meter = createSpendMeter(RESERVE / 2);
+    await expect(model(PRICED, { dispatch: RECEIPT, meter }).next(TURN)).rejects.toMatchObject({ receipt: { stopReason: "spend_budget" } });
+    expect(calls).toHaveLength(0);
+    expect(meter.requests).toBe(0);
+    expect(meter.spentUsd).toBe(0);
+  });
+
+  it("(d) every issued request body carries the output cap the reservation priced", async () => {
+    fakeTransport(() => ok());
+    const meter = createSpendMeter(10);
+    const m = model(PRICED, { dispatch: RECEIPT, meter });
+    await m.next(TURN);
+    await m.next(TURN);
+    expect(calls.map((c) => c.body.generationConfig?.maxOutputTokens)).toEqual([modelMaxOutputTokens(), modelMaxOutputTokens()]);
+    process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS = "2048";
+    await m.next(TURN);
+    expect(calls.at(-1)!.body.generationConfig.maxOutputTokens).toBe(2048);
+  });
+
+  it("(f) retryable 503s under { maxRetries: 3 }: exactly four requests, four reservations; the SDK adds none", async () => {
+    vi.useFakeTimers();
+    fakeTransport(() => unavailable());
+    const meter = createSpendMeter(10);
+    const m = model(PRICED, { dispatch: { maxRetries: 3, crossModelFallback: false }, meter });
+    const outcome = m.next(TURN).then(() => null, (e: unknown) => e);
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(await outcome).toBeInstanceOf(Error);
+    expect(calls).toHaveLength(4);
+    expect(meter.requests).toBe(4);
+    expect(meter.spentUsd).toBeCloseTo(RESERVE * 4, 12);
+  });
+});
+
+describe("(g) zero requests for an unpriced id", () => {
+  it("model() with a $10 meter and at the $0.01 equality case: UnpricedModelError, zero fetch calls, meter untouched", async () => {
+    fakeTransport(() => ok()); // the transport would answer 200 if anything were sent
+    for (const maxUsd of [10, 0.01]) {
+      const meter = createSpendMeter(maxUsd);
+      const error = await model(UNPRICED_ALIAS, { dispatch: RECEIPT, meter }).next(TURN).then(() => null, (e: unknown) => e);
+      expect(error).toBeInstanceOf(UnpricedModelError);
+      expect((error as UnpricedModelError).receipt.stopReason).toBe("spend_budget");
+      expect(meter.requests).toBe(0);
+      expect(meter.spentUsd).toBe(0);
+      expect(meter.stoppedBy).toBe("unpriced_model");
+    }
+    expect(calls).toHaveLength(0);
+  });
+
+  it("(A.0.10) an id the catalog has never heard of never reaches the adapter: model() throws before any request, metered or not", async () => {
+    fakeTransport(() => ok());
+    const meter = createSpendMeter(10);
+    expect(() => model(UNPRICED, { dispatch: RECEIPT, meter })).toThrow(UnknownModelError);
+    expect(() => model(UNPRICED)).toThrow(UnknownModelError); // the unmetered legacy caller is refused too: no paid default
+    expect(calls).toHaveLength(0);
+    expect(meter.requests).toBe(0);
+    expect(meter.spentUsd).toBe(0);
+  });
+
+  it("a priced primary answering four 503s with an unpriced AGENT_FALLBACK_MODEL makes the primary's four requests and none for the fallback", async () => {
+    vi.useFakeTimers();
+    process.env.AGENT_FALLBACK_MODEL = UNPRICED_ALIAS;
+    fakeTransport(() => unavailable());
+    const meter = createSpendMeter(10);
+    const outcome = model(PRICED, { meter }).next(TURN).then(() => null, (e: unknown) => e); // default policy
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(await outcome).toBeInstanceOf(UnpricedModelError);
+    expect(calls).toHaveLength(4);
+    expect(calls.every((c) => c.url.includes(`/models/${PRICED}:`))).toBe(true);
+    expect(meter.requests).toBe(4);
+  });
+
+  it("a terminal stop ends the dispatch: an unpriced primary never reaches a priced AGENT_FALLBACK_MODEL", async () => {
+    process.env.AGENT_FALLBACK_MODEL = PRICED; // would be affordable and priced: must still not be dispatched
+    fakeTransport(() => ok());
+    const meter = createSpendMeter(10);
+    const error = await model(UNPRICED_ALIAS, { meter }).next(TURN).then(() => null, (e: unknown) => e); // default policy: fallback allowed
+    expect(error).toBeInstanceOf(UnpricedModelError);
+    expect(meter.stoppedBy).toBe("unpriced_model");
+    expect(calls).toHaveLength(0);
+    expect(meter.requests).toBe(0);
+  });
+
+  it("a terminal stop ends the dispatch: a cap-refused primary never reaches a cheaper AGENT_FALLBACK_MODEL", async () => {
+    process.env.AGENT_FALLBACK_MODEL = "gemini-3.5-flash-lite"; // its reservation would fit under the cap
+    fakeTransport(() => ok());
+    const cheap = reserveDispatch("gemini-3.5-flash-lite", BOUND, Number.POSITIVE_INFINITY);
+    expect(cheap).toBeLessThan(RESERVE);
+    const meter = createSpendMeter((RESERVE + cheap) / 2); // primary does not fit, the fallback would
+    const error = await model(PRICED, { meter }).next(TURN).then(() => null, (e: unknown) => e);
+    expect(error).toBeInstanceOf(SpendBudgetError);
+    expect(meter.stoppedBy).toBe("spend_budget");
+    expect(calls).toHaveLength(0);
+    expect(meter.requests).toBe(0);
+    expect(meter.spentUsd).toBe(0);
+  });
+
+  it("after a stop the meter refuses every further dispatch, even a different model that would fit", async () => {
+    fakeTransport(() => ok());
+    const meter = createSpendMeter(10);
+    meter.stoppedBy = "spend_budget";
+    await expect(model("gemini-3.5-flash-lite", { dispatch: RECEIPT, meter }).next(TURN)).rejects.toBeInstanceOf(SpendBudgetError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("an unmetered adapter is unchanged: no reservation, no refusal", async () => {
+    const savedKey = process.env.ANTHROPIC_API_KEY;
+    process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+    try {
+      fakeTransport(() => anthropicAnswer(10, 5));
+      const step = await model(UNPRICED_ALIAS).next(TURN); // no meter: legacy callers are not budget-gated
+      expect(step.text).toBe("done");
+      expect(calls).toHaveLength(1);
+    } finally {
+      if (savedKey === undefined) delete process.env.ANTHROPIC_API_KEY; else process.env.ANTHROPIC_API_KEY = savedKey;
+    }
+  });
+});
+
+describe("main(): pre-flight and the grid", () => {
+  let dir: string;
+  const argvBefore = process.argv;
+  const exitBefore = process.exitCode;
+  beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "ladder-budget-")); vi.spyOn(console, "log").mockImplementation(() => {}); vi.spyOn(console, "error").mockImplementation(() => {}); });
+  afterEach(() => { process.argv = argvBefore; process.exitCode = exitBefore; rmSync(dir, { recursive: true, force: true }); vi.restoreAllMocks(); });
+
+  async function runMain(args: string[]) {
+    const out = join(dir, "report.json");
+    process.argv = ["node", "ladder.ts", ...args, "--json-out", out];
+    process.exitCode = undefined;
+    const { main } = await import("./ladder");
+    await main();
+    const exitCode = process.exitCode;
+    process.exitCode = exitBefore;
+    let report: Record<string, any> | undefined;
+    try { report = JSON.parse(readFileSync(out, "utf8")); } catch { /* refusal before any report */ }
+    return { exitCode, report };
+  }
+
+  it("refuses --real without a dollar cap: exit 1, no request", async () => {
+    fakeTransport(() => ok());
+    const { exitCode } = await runMain(["--real", PRICED, "--levels=1-4"]);
+    expect(exitCode).toBe(1);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("(g) --real with an unpriced id exits 1 at pre-flight: stoppedBy unpriced_model, no result rows, zero fetch calls", async () => {
+    fakeTransport(() => ok());
+    const { exitCode, report } = await runMain(["--real", UNPRICED, "--levels=1-4", "--max-cost-usd=1"]);
+    expect(exitCode).toBe(1);
+    expect(report?.budget).toMatchObject({ stoppedBy: "unpriced_model", requests: 0, spentUsd: 0 });
+    expect(report?.results).toEqual([]);
+    expect(report?.dispatchPolicy).toEqual(RECEIPT);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("refuses to start when the worst-case estimate exceeds the cap (the human raises the cap, never the check)", async () => {
+    fakeTransport(() => ok());
+    const { exitCode, report } = await runMain(["--real", PRICED, "--levels=1-4", "--max-cost-usd=0.0001"]);
+    expect(exitCode).toBe(1);
+    expect(report?.budget.estimateUsd).toBeGreaterThan(0.0001);
+    expect(report?.budget).toMatchObject({ stoppedBy: "spend_budget", requests: 0 });
+    expect(calls).toHaveLength(0);
+  });
+
+  it("(e) usage within each reservation, a context that outgrows the scripted pre-flight: the grid stops BEFORE the cap, spentUsd <= maxUsd, budget.requests equals the fetch count", async () => {
+    // Pass the pre-flight with the smallest admissible cap (the estimate itself), then answer every step with a tool
+    // call plus 20K characters of text so the real prompt outgrows the scripted dry run the estimate was built on.
+    // Each answer bills half its request body in tokens (realistic, and below the 1-byte-per-token reservation), so
+    // no settlement ever exceeds its reservation: the only thing that can end the grid is a refused reservation.
+    fakeTransport(() => ok());
+    const probe = await runMain(["--real", PRICED, "--levels=1-4", "--max-cost-usd=0.0001"]);
+    const cap = Math.ceil(probe.report!.budget.estimateUsd * 1e4) / 1e4; // >= the estimate, so the pre-flight admits it
+    expect(calls).toHaveLength(0);
+
+    fakeTransport((_n, call) => {
+      const tokens = Math.floor(JSON.stringify(call.body).length / 2);
+      billedUsd += priceRequestStrict(PRICED, tokens, 50);
+      return new Response(JSON.stringify({
+        candidates: [{ content: { role: "model", parts: [{ text: "x".repeat(20_000) }, { functionCall: { name: "list_artifacts", args: {} } }] }, finishReason: "STOP", index: 0 }],
+        usageMetadata: { promptTokenCount: tokens, candidatesTokenCount: 50, totalTokenCount: tokens + 50 },
+        modelVersion: PRICED,
+      }), { status: 200, headers: { "content-type": "application/json" } });
+    });
+
+    const { exitCode, report } = await runMain(["--real", PRICED, "--levels=1-4", `--max-cost-usd=${cap}`]);
+    const budget = report!.budget;
+    expect(budget.stoppedBy).toBe("spend_budget"); // a reservation was refused...
+    expect(budget.spentUsd).toBeLessThanOrEqual(budget.maxUsd); // ...so the cap was never crossed
+    expect(budget.spentUsd).toBeLessThan(budget.maxUsd); // the grid stopped short of it, not on it
+    expect(billedUsd).toBeLessThanOrEqual(budget.maxUsd);
+    expect(calls.length).toBeGreaterThan(2);
+    expect(budget.requests).toBe(calls.length); // nothing was issued after the stop
+    expect(budget.requests).toBeLessThan(budget.requestCeiling);
+    expect(exitCode).toBe(1); // a stop is not a receipt
+  }, 30_000);
+
+  it("the --json-out report carries what an A.0.3 review needs: command, candidateIds, echoedModels, rows, environment, requestCeiling", async () => {
+    fakeTransport(() => new Response(JSON.stringify({
+      candidates: [{ content: { role: "model", parts: [{ text: "done" }] }, finishReason: "STOP", index: 0 }],
+      usageMetadata: { promptTokenCount: 500, candidatesTokenCount: 20, totalTokenCount: 520 },
+      modelVersion: "gemini-3.6-flash", // Google answering as another model: the receipt must show it
+    }), { status: 200, headers: { "content-type": "application/json" } }));
+    const probe = await runMain(["--real", PRICED, "--levels=1-4", "--max-cost-usd=0.0001"]);
+    const cap = Math.ceil(probe.report!.budget.estimateUsd * 1e4) / 1e4;
+
+    const { report } = await runMain(["--real", PRICED, "--levels=1-4", `--max-cost-usd=${cap}`]);
+    expect(report?.command).toContain(`--real ${PRICED}`);
+    expect(report?.candidateIds).toEqual([PRICED]);
+    expect(report?.echoedModels).toEqual(["gemini-3.6-flash"]);
+    expect(report?.environment).toMatchObject({ node: process.version, platform: process.platform });
+    expect(report?.rows.length).toBe(calls.length);
+    expect(report?.rows[0]).toMatchObject({
+      requestedModel: PRICED,
+      resolvedModel: PRICED,
+      echoedModel: "gemini-3.6-flash",
+      usage: { inputTokens: 500, outputTokens: 20 },
+      fallbackUsed: false,
+    });
+    expect(report?.budget.requests).toBeLessThanOrEqual(report?.budget.requestCeiling);
+    expect(report?.results.every((r: { dispatches: unknown[] }) => Array.isArray(r.dispatches))).toBe(true);
+  });
+
+  it("a rung that issued charged dispatches and then failed on a provider error reports what it spent, not 0 (round 3)", async () => {
+    // Persona: the operator runs the L1 rung on a paid route; the network resets on the second request. The rung row
+    // used to say cost 0 while its own dispatch rows and the job-wide meter carried the charge (Codex: 0.05301075 vs 0).
+    fakeTransport(() => ok());
+    const probe = await runMain(["--real", PRICED, "--levels=1-1", "--max-cost-usd=0.0001"]);
+    const cap = Math.ceil(probe.report!.budget.estimateUsd * 1e4) / 1e4;
+
+    fakeTransport((n) => {
+      if (n === 1) {
+        return new Response(JSON.stringify({
+          candidates: [{ content: { role: "model", parts: [{ functionCall: { name: "list_artifacts", args: {} } }] }, finishReason: "STOP", index: 0 }],
+          usageMetadata: { promptTokenCount: 2_000, candidatesTokenCount: 40, totalTokenCount: 2_040 },
+          modelVersion: PRICED,
+        }), { status: 200, headers: { "content-type": "application/json" } });
+      }
+      throw Object.assign(new Error("fetch failed: ECONNRESET"), { code: "ECONNRESET" });
+    });
+    const { report } = await runMain(["--real", PRICED, "--levels=1-1", `--max-cost-usd=${cap}`]);
+    expect(calls).toHaveLength(2); // the charged answer, then the reset (receipt policy: no retry, no fallback)
+    const row = report!.results[0];
+    expect(row.error).toMatch(/ECONNRESET/);
+    expect(row.pass).toBe(false);
+    const dispatchCost = row.dispatches.reduce((sum: number, d: { costUsd: number }) => sum + d.costUsd, 0);
+    expect(dispatchCost).toBeGreaterThan(0);
+    expect(row.cost).toBeCloseTo(dispatchCost, 12);
+    expect(row.cost).toBeCloseTo(report!.budget.spentUsd, 12);
+    expect(row.dispatches[0].costUsd).toBeCloseTo(priceRequestStrict(PRICED, 2_000, 40), 12); // the settled one
+  });
+});
+
+// ───────────────────────────── review round 2 ─────────────────────────────
+
+/** An Anthropic Messages answer reporting `inputTokens` / `outputTokens`; `toolUse` makes the step ask for a tool. */
+function anthropicAnswer(inputTokens: number, outputTokens: number, toolUse = false) {
+  return new Response(JSON.stringify({
+    id: "msg_test", type: "message", role: "assistant", model: "claude-haiku-5-5",
+    content: toolUse ? [{ type: "tool_use", id: "tu_1", name: "list_artifacts", input: {} }] : [{ type: "text", text: "done" }],
+    stop_reason: toolUse ? "tool_use" : "end_turn", stop_sequence: null,
+    usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+  }), { status: 200, headers: { "content-type": "application/json" } });
+}
+
+describe("the long-context tier belongs to one request, never to a sum of requests", () => {
+  const HAIKU = "claude-haiku-5-5";
+  const SAVED_ANTHROPIC = process.env.ANTHROPIC_API_KEY;
+  beforeEach(() => { process.env.ANTHROPIC_API_KEY = "test-anthropic-key"; });
+  afterEach(() => { if (SAVED_ANTHROPIC === undefined) delete process.env.ANTHROPIC_API_KEY; else process.env.ANTHROPIC_API_KEY = SAVED_ANTHROPIC; });
+
+  const base = (inTok: number, outTok: number) => (inTok * 0.10 + outTok * 0.50) / 1_000_000;
+
+  it("meter settlement: two 60K/1K dispatches (120K prompt tokens in total) settle at the base tier, one 120K dispatch at the tier", async () => {
+    fakeTransport(() => anthropicAnswer(60_000, 1_000));
+    const meter = createSpendMeter(10);
+    const m = model(HAIKU, { dispatch: RECEIPT, meter });
+    await m.next(TURN);
+    await m.next(TURN);
+    expect(meter.dispatches.map((d) => d.costUsd)).toEqual([base(60_000, 1_000), base(60_000, 1_000)]);
+    expect(meter.spentUsd).toBeCloseTo(0.013, 9); // was $0.065 when the sum was tiered
+
+    fakeTransport(() => anthropicAnswer(120_000, 2_000));
+    const long = createSpendMeter(10);
+    await model(HAIKU, { dispatch: RECEIPT, meter: long }).next(TURN);
+    expect(long.spentUsd).toBeCloseTo((120_000 * 0.50 + 2_000 * 2.50) / 1_000_000, 9); // 0.065: a real 120K prompt IS tiered
+  });
+
+  it("ladder rung cost is the sum of its settled dispatches (two sub-100K requests are not billed as one 120K request)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "ladder-tier-"));
+    const argvBefore = process.argv;
+    const exitBefore = process.exitCode;
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const run = async (cap: string) => {
+        const out = join(dir, `report-${cap}.json`);
+        process.argv = ["node", "ladder.ts", "--real", HAIKU, "--levels=1-1", `--max-cost-usd=${cap}`, "--json-out", out];
+        process.exitCode = undefined;
+        const { main } = await import("./ladder");
+        await main();
+        process.exitCode = exitBefore;
+        try { return JSON.parse(readFileSync(out, "utf8")) as Record<string, any>; } catch { return undefined; }
+      };
+      fakeTransport(() => anthropicAnswer(1, 1));
+      const probe = await run("0.0001");
+      const cap = String(Math.ceil(probe!.budget.estimateUsd * 1e4) / 1e4);
+      // Step 1 asks for a tool, step 2 answers: exactly two dispatches of 60K/1K.
+      fakeTransport((n) => anthropicAnswer(60_000, 1_000, n === 1));
+      const report = await run(cap);
+      expect(calls).toHaveLength(2);
+      const row = report!.results[0];
+      expect(row.dispatches.map((d: { costUsd: number }) => d.costUsd)).toEqual([base(60_000, 1_000), base(60_000, 1_000)]);
+      expect(row.cost).toBeCloseTo(0.013, 9); // was $0.065
+      expect(row.cost).toBeCloseTo(report!.budget.spentUsd, 9);
+    } finally {
+      process.argv = argvBefore;
+      process.exitCode = exitBefore;
+      rmSync(dir, { recursive: true, force: true });
+      vi.restoreAllMocks();
+    }
+  });
+});
+
+describe("pre-flight request ceiling follows the candidate limit the adapter enforces", () => {
+  const shapes = [{ maxSteps: 3, ctxTokens0: 1_000, growthTokens: 0 }, { maxSteps: 2, ctxTokens0: 1_000, growthTokens: 0 }] as never;
+  const SAVED_LIMIT = process.env.OPENROUTER_FREE_AUTO_LIMIT;
+  afterEach(() => { if (SAVED_LIMIT === undefined) delete process.env.OPENROUTER_FREE_AUTO_LIMIT; else process.env.OPENROUTER_FREE_AUTO_LIMIT = SAVED_LIMIT; });
+
+  it("a free-auto route multiplies by OPENROUTER_FREE_AUTO_LIMIT (default 8, max 20), a concrete route by 1", async () => {
+    const { ladderRequestCeiling, estimateLadderUsd } = await import("./ladder");
+    const steps = 3 + 2;
+    delete process.env.OPENROUTER_FREE_AUTO_LIMIT;
+    expect(ladderRequestCeiling([PRICED], shapes)).toBe(steps);
+    expect(ladderRequestCeiling(["openrouter/free-auto"], shapes)).toBe(8 * steps); // Codex observed 8 requests for one step whose ceiling was 1
+    expect(ladderRequestCeiling([PRICED, "openrouter/free-auto"], shapes)).toBe(steps + 8 * steps);
+    process.env.OPENROUTER_FREE_AUTO_LIMIT = "5";
+    expect(ladderRequestCeiling(["openrouter/free-auto"], shapes)).toBe(5 * steps);
+    process.env.OPENROUTER_FREE_AUTO_LIMIT = "99";
+    expect(ladderRequestCeiling(["openrouter/free-auto"], shapes)).toBe(20 * steps);
+    expect(estimateLadderUsd(["openrouter/free-auto"], shapes)).toBe(0); // free route: any fan-out costs nothing
+  });
+
+  it("an alias of a free-auto route fans out like the route it resolves to (dispatch resolves aliases first)", async () => {
+    const { ladderRequestCeiling, estimateLadderUsd } = await import("./ladder");
+    const steps = 3 + 2;
+    delete process.env.OPENROUTER_FREE_AUTO_LIMIT;
+    // 'free' and 'openrouter-auto' used to get a ceiling of 1 step each while one model("free").next() issues up to 8 requests.
+    for (const alias of ["free", "free-auto", "openrouter-auto", "openrouter-free-auto", "FREE", "nodeagent-auto", "nodeagent/free-auto"]) {
+      expect(ladderRequestCeiling([alias], shapes), alias).toBe(8 * steps);
+      if (!alias.startsWith("nodeagent")) expect(() => estimateLadderUsd([alias], shapes), alias).not.toThrow(); // nodeagent/free-auto has no price row: main() refuses it at pre-flight
+    }
+    expect(ladderRequestCeiling(["openrouter/free"], shapes), "the single-model meta route does not fan out").toBe(steps);
+    expect(ladderRequestCeiling(["claude-sonnet"], shapes), "a concrete alias does not fan out").toBe(steps);
+    process.env.OPENROUTER_FREE_AUTO_LIMIT = "3";
+    expect(ladderRequestCeiling(["free", PRICED], shapes)).toBe(3 * steps + steps);
+  });
+
+  it("an unknown route is refused by the ceiling and the estimate instead of being counted as one request (A.0.10)", async () => {
+    const { ladderRequestCeiling, estimateLadderUsd } = await import("./ladder");
+    expect(() => ladderRequestCeiling(["gemini-9-flash-unknown"], shapes)).toThrow(/unknown model id/);
+    expect(() => estimateLadderUsd(["gemini-9-flash-unknown"], shapes)).toThrow(/unknown model id/);
+  });
+});
diff --git a/evals/managedLockPerf.ts b/evals/managedLockPerf.ts
index 6fdae549..a199efd0 100644
--- a/evals/managedLockPerf.ts
+++ b/evals/managedLockPerf.ts
@@ -140,10 +140,10 @@ async function main() {
   const jsonOut = optionValue("--json-out") ?? DEFAULT_JSON_OUT;
   const real = Boolean(realRoute);
   const explicitAgent = real
-    ? realModel(realRoute!)
+    ? realModel(realRoute!, { operatorSelected: true })
     : scriptedModel(recomputeVariancePlan(TARGETS, { lock: true }), "scripted-explicit-lock");
   const managedAgent = real
-    ? realModel(realRoute!)
+    ? realModel(realRoute!, { operatorSelected: true })
     : scriptedModel(managedBatchVariancePlan(TARGETS), "scripted-managed-lock");
 
   const explicit = await runCase({ lane: "explicit_agent_lock", agent: explicitAgent, real });
diff --git a/evals/professionalLiveCatalog.ts b/evals/professionalLiveCatalog.ts
index b35d949e..5ed3b5dc 100644
--- a/evals/professionalLiveCatalog.ts
+++ b/evals/professionalLiveCatalog.ts
@@ -182,7 +182,7 @@ async function runProfessionalLiveCatalogCase(
   const started = Date.now();
   const prompt = buildProfessionalLiveCatalogPrompt(evalCase);
   try {
-    const raw = await judge(modelName, prompt);
+    const raw = await judge(modelName, prompt, { operatorSelected: true });
     const answer = parseProfessionalLiveCatalogAnswer(raw);
     const checks = gradeProfessionalLiveCatalogAnswer(evalCase, answer);
     const score = scoreChecks(checks);
diff --git a/evals/professionalRuntimeLive.ts b/evals/professionalRuntimeLive.ts
index e86dc31f..c8ae050e 100644
--- a/evals/professionalRuntimeLive.ts
+++ b/evals/professionalRuntimeLive.ts
@@ -141,7 +141,7 @@ async function runProfessionalRuntimeLiveCase(
   const built = buildRuntimeRoom(scenario);
   const agent = options.modelName === "scripted"
     ? scriptedModel(runtimeSmokePlan(scenario, built.noteId), `scripted:${evalCase.id}`)
-    : realModel(options.modelName);
+    : realModel(options.modelName, { operatorSelected: true });
   const started = Date.now();
   try {
     const result = await runAgent({
diff --git a/package-lock.json b/package-lock.json
index 140d6c65..8f5db488 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,7 +9,7 @@
       "version": "0.1.1",
       "license": "MIT",
       "dependencies": {
-        "@ai-sdk/anthropic": "^3.0.84",
+        "@ai-sdk/anthropic": "^3.0.120",
         "@ai-sdk/google": "^3.0.82",
         "@ai-sdk/openai": "^3.0.71",
         "@assistant-ui/react-o11y": "^0.0.25",
@@ -99,13 +99,13 @@
       }
     },
     "node_modules/@ai-sdk/anthropic": {
-      "version": "3.0.117",
-      "resolved": "https://registry.npmjs.org/@ai-sdk/anthropic/-/anthropic-3.0.117.tgz",
-      "integrity": "sha512-ZdcpT3tWRifu93DPL5jSGvx9QmRi4zi0H7JiCKp76dH6dytQKYdg12Jpl1HHamCT3KgxSrNMOPKCv8q+gXqAVw==",
+      "version": "3.0.120",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/anthropic/-/anthropic-3.0.120.tgz",
+      "integrity": "sha512-nDdCokLr0nexRUwUpWzzXzK73+KbejgmZMJdo8XthIeeeCXQvtKuhvpNs091N97NEaM3XHmOI55Z8/TWuNSWcQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@ai-sdk/provider": "3.0.16",
-        "@ai-sdk/provider-utils": "4.0.51"
+        "@ai-sdk/provider-utils": "4.0.52"
       },
       "engines": {
         "node": ">=18"
@@ -114,6 +114,33 @@
         "zod": "^3.25.76 || ^4.1.8"
       }
     },
+    "node_modules/@ai-sdk/anthropic/node_modules/@ai-sdk/provider-utils": {
+      "version": "4.0.52",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider-utils/-/provider-utils-4.0.52.tgz",
+      "integrity": "sha512-cUimyIz1jjwYoF9n6HO7sU+UBW7Nu3T4lW7562yRvEhM9/8JqlW4cecxSpkiafjRzAphZG2NfJ3/Ch5cHoCIhg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "3.0.16",
+        "@standard-schema/spec": "^1.1.0",
+        "eventsource-parser": "^3.0.8",
+        "undici": "^6.28.0"
+      },
+      "engines": {
+        "node": ">=18.17"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/anthropic/node_modules/undici": {
+      "version": "6.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.29.0.tgz",
+      "integrity": "sha512-R+RODBqp6i2pPflGdq+xIOUkl+RNfGgHwoinecKu/JCuf2uO06cOKoDbI2P7Dn6KcswdKwrczbU6IYJ6K8X+wg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
     "node_modules/@ai-sdk/gateway": {
       "version": "3.0.191",
       "resolved": "https://registry.npmjs.org/@ai-sdk/gateway/-/gateway-3.0.191.tgz",
diff --git a/package.json b/package.json
index a0b382fd..4b866fac 100644
--- a/package.json
+++ b/package.json
@@ -250,7 +250,7 @@
     "eval:credit": "tsx evals/creditEval.ts",
     "ladder": "tsx evals/ladder.ts",
     "ladder:real": "tsx evals/ladder.ts --real",
-    "ladder:free": "tsx evals/ladder.ts --real openrouter/free-auto --free-auto-top=5 --levels=1-4 --rung-timeout-ms=540000 --reserve-ms=30000 --json-out docs/eval/free-auto-router-ladder.json",
+    "ladder:free": "tsx evals/ladder.ts --real openrouter/free-auto --free-auto-top=5 --max-cost-usd=1 --levels=1-4 --rung-timeout-ms=540000 --reserve-ms=30000 --json-out docs/eval/free-auto-router-ladder.json",
     "eval:diff": "tsx evals/evalDiff.ts",
     "proofs:staleness": "tsx scripts/proof-staleness-check.ts",
     "proofs:publish": "tsx scripts/proof-release-publish.ts --write-readme",
@@ -275,7 +275,7 @@
     "voice:prod-deploy:proof": "tsx scripts/voice-prod-deploy-proof.ts"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.84",
+    "@ai-sdk/anthropic": "^3.0.120",
     "@ai-sdk/google": "^3.0.82",
     "@ai-sdk/openai": "^3.0.71",
     "@assistant-ui/react-o11y": "^0.0.25",
diff --git a/packages/walkthrough-review-cli/README.md b/packages/walkthrough-review-cli/README.md
index b5b03896..a5654cf6 100644
--- a/packages/walkthrough-review-cli/README.md
+++ b/packages/walkthrough-review-cli/README.md
@@ -22,7 +22,7 @@ Generic shape:
 walkthrough-review run \
   --config walkthrough-review.config.json \
   --base http://127.0.0.1:5178 \
-  --model gemini-3.5-flash \
+  --model gemini-3.6-flash \
   --ui-review \
   startup-diligence-war-room
 ```
diff --git a/packages/walkthrough-review-cli/src/core.ts b/packages/walkthrough-review-cli/src/core.ts
index 4f70b55f..16e40ad0 100644
--- a/packages/walkthrough-review-cli/src/core.ts
+++ b/packages/walkthrough-review-cli/src/core.ts
@@ -75,7 +75,7 @@ type CommandVariables = {
 };
 
 const DEFAULT_CONFIG = "walkthrough-review.config.json";
-const DEFAULT_MODEL = "gemini-3.5-flash";
+const DEFAULT_MODEL = "gemini-3.6-flash";
 const DEFAULT_OUTPUT_ROOT = join("docs", "eval", "walkthrough-review");
 const DEFAULT_DRY_OUTPUT_ROOT = join(".tmp-qa", "walkthrough-review");
 const DEFAULT_MEDIA_ROOT = join("docs", "walkthroughs");
diff --git a/scripts/benchmark/pricingAtRun.ts b/scripts/benchmark/pricingAtRun.ts
new file mode 100644
index 00000000..b7e6fe74
--- /dev/null
+++ b/scripts/benchmark/pricingAtRun.ts
@@ -0,0 +1,69 @@
+/**
+ * Pricing the benchmark records on every row (`pricingAtRun`). The OpenRouter /models snapshot of the run wins
+ * (dated by `fetchedAt` + `routeSnapshotId`); the catalog row is the fallback; a flagged $1/$5 `fallback_estimate`
+ * is the last resort. Split out of run.ts, which runs the benchmark on import, so the pricing agreement test
+ * (SPEC A.0.6) can load these paths.
+ */
+import { getModelPricing, lookupModelAlias, type ModelPricing } from "../../src/nodeagent/models/modelCatalog";
+import type { OpenRouterModelInfo } from "../../src/nodeagent/models/openRouterFreeModels";
+
+export type PricingAtRun = {
+  source: "openrouter_snapshot" | "catalog" | "fallback_estimate";
+  inputPer1M: number;
+  outputPer1M: number;
+  cachedInputPer1M?: number;
+  contextWindow?: number;
+  routeSnapshotId?: string;
+};
+
+export type RouteSnapshot = {
+  routeSnapshotId: string;
+  fetchedAt: string;
+  source: "openrouter" | "unavailable";
+  modelsById: Map<string, OpenRouterModelInfo>;
+  error?: string;
+};
+
+export function priceFromOpenRouterInfo(info: OpenRouterModelInfo, routeSnapshotId: string): PricingAtRun | undefined {
+  const prompt = Number(info.pricing?.prompt);
+  const completion = Number(info.pricing?.completion);
+  if (!Number.isFinite(prompt) || !Number.isFinite(completion)) return undefined;
+  const cacheRead = Number(info.pricing?.input_cache_read);
+  return {
+    source: "openrouter_snapshot",
+    inputPer1M: prompt * 1_000_000,
+    outputPer1M: completion * 1_000_000,
+    ...(Number.isFinite(cacheRead) ? { cachedInputPer1M: cacheRead * 1_000_000 } : {}),
+    contextWindow: info.context_length ?? info.top_provider?.context_length,
+    routeSnapshotId,
+  };
+}
+
+export function catalogPricingAtRun(modelId: string): PricingAtRun {
+  const pricing: ModelPricing | null = getModelPricing(lookupModelAlias(modelId));
+  if (!pricing) {
+    return {
+      source: "fallback_estimate",
+      inputPer1M: 1,
+      outputPer1M: 5,
+    };
+  }
+  return {
+    source: "catalog",
+    inputPer1M: pricing.inputPer1M,
+    outputPer1M: pricing.outputPer1M,
+    ...(pricing.cachedInputPer1M != null ? { cachedInputPer1M: pricing.cachedInputPer1M } : {}),
+    contextWindow: pricing.contextWindow,
+  };
+}
+
+export function pricingAtRunFor(modelId: string, snapshot?: RouteSnapshot): PricingAtRun {
+  const resolved = lookupModelAlias(modelId);
+  const fromSnapshot = snapshot?.modelsById.get(resolved);
+  if (snapshot && fromSnapshot) return priceFromOpenRouterInfo(fromSnapshot, snapshot.routeSnapshotId) ?? catalogPricingAtRun(resolved);
+  return catalogPricingAtRun(resolved);
+}
+
+export function costFromPricing(pricing: PricingAtRun, inputTokens: number, outputTokens: number): number {
+  return (inputTokens * pricing.inputPer1M + outputTokens * pricing.outputPer1M) / 1_000_000;
+}
diff --git a/scripts/benchmark/probe.ts b/scripts/benchmark/probe.ts
index 8bd2755a..0ea97084 100644
--- a/scripts/benchmark/probe.ts
+++ b/scripts/benchmark/probe.ts
@@ -6,33 +6,39 @@ const { generateText } = await import("ai");
 const { anthropic } = await import("@ai-sdk/anthropic");
 const { openai, createOpenAI } = await import("@ai-sdk/openai");
 const { google } = await import("@ai-sdk/google");
+const { claudeEffortProviderOptions } = await import("../../src/nodeagent/models/modelCatalog");
 const or = createOpenAI({ apiKey: process.env.OPENROUTER_API_KEY, baseURL: "https://openrouter.ai/api/v1" });
 
 const cases: [string, any][] = [
-  // Anthropic latest
+  // Anthropic latest (5.5 = the migration-guide successors; claude-opus-4-8 is still Active)
+  ["claude-haiku-5-5", anthropic("claude-haiku-5-5")],
+  ["claude-sonnet-5-5", anthropic("claude-sonnet-5-5")],
+  ["claude-opus-5-5", anthropic("claude-opus-5-5")],
   ["claude-opus-4-8", anthropic("claude-opus-4-8")],
   ["claude-sonnet-4-6", anthropic("claude-sonnet-4-6")],
   ["claude-haiku-4-5", anthropic("claude-haiku-4-5")],
-  // Google latest (gemini 3.x)
+  // Google latest (gemini 3.x). gemini-3.5-flash stays on purpose: Google auto-routes it to 3.6 since 2026-10-08.
+  ["gemini-3.8-flash", google("gemini-3.8-flash")],
+  ["gemini-3.5-flash-lite", google("gemini-3.5-flash-lite")],
   ["gemini-3.5-flash", google("gemini-3.5-flash")],
   ["gemini-3-flash-preview", google("gemini-3-flash-preview")],
   ["gemini-3.1-flash-lite", google("gemini-3.1-flash-lite")],
   ["gemini-2.5-flash", google("gemini-2.5-flash")],
   ["gemini-2.5-flash-lite", google("gemini-2.5-flash-lite")],
-  // OpenAI latest (gpt-5.x)
+  // OpenAI latest (gpt-5.x / gpt-6.x)
+  ["gpt-6.1-sol", openai("gpt-6.1-sol")],
   ["gpt-5.5", openai("gpt-5.5")],
   ["gpt-5.4", openai("gpt-5.4")],
   ["gpt-5.4-mini", openai("gpt-5.4-mini")],
   ["gpt-5.4-nano", openai("gpt-5.4-nano")],
   // OpenRouter (cheap/free) — simple-call reachability
-  ["OR nex-agi/nex-n2-pro:free", or.chat("nex-agi/nex-n2-pro:free")],
   ["OR ibm-granite/granite-4.1-8b", or.chat("ibm-granite/granite-4.1-8b")],
   ["OR deepseek/deepseek-v4-flash", or.chat("deepseek/deepseek-v4-flash")],
   ["OR z-ai/glm-4.7-flash", or.chat("z-ai/glm-4.7-flash")],
 ];
 for (const [name, model] of cases) {
   try {
-    const r = await generateText({ model, prompt: "Reply with the word OK." });
+    const r = await generateText({ model, prompt: "Reply with the word OK.", ...claudeEffortProviderOptions(name) }); // explicit SPEC §1.3 effort on claude-*-5-5
     console.log(`✅ ${name.padEnd(26)} -> "${(r.text || "").slice(0, 16).trim()}"`);
   } catch (e: any) {
     const status = e?.statusCode ?? e?.status ?? "";
diff --git a/scripts/benchmark/run.ts b/scripts/benchmark/run.ts
index cdb58093..b25807f2 100644
--- a/scripts/benchmark/run.ts
+++ b/scripts/benchmark/run.ts
@@ -20,7 +20,8 @@ import { buildDemoRoom, RESEARCH_COMPANIES } from "../../src/engine/demoRoom";
 import { InMemoryRoomTools } from "../../src/nodeagent/skills/integration/noderoomAdapter";
 import { runAgent } from "../../src/nodeagent/core/runtime";
 import { model, priceRun, judge } from "../../src/nodeagent/models/adapter";
-import { getModelPricing, resolveModelAlias, type ModelPricing } from "../../src/nodeagent/models/modelCatalog";
+import { lookupModelAlias } from "../../src/nodeagent/models/modelCatalog";
+import { costFromPricing, pricingAtRunFor, type PricingAtRun, type RouteSnapshot } from "./pricingAtRun";
 import { fetchSourceReal } from "../../src/nodeagent/skills/search/fetchSource";
 import type { AgentMessage, AgentModel, AgentTool, RoomTools, SourceResult } from "../../src/nodeagent/core/types";
 import { isOpenRouterFreeAutoModel, selectOpenRouterFreeModels, type OpenRouterModelInfo } from "../../src/nodeagent/models/openRouterFreeModels";
@@ -62,7 +63,7 @@ const CHECKS = [
 // Fixed cheap judge (isolated yes/no per the grounded-eval rule — low variance, not a holistic grade).
 const JUDGE = process.env.JUDGE_MODEL || "gemini-3.1-flash-lite";
 async function scoreJudgeCompany(company: string, summary: string, evidence: string): Promise<CompanyJudgeResult> {
-  return judgeCompanyWith(judge, JUDGE, company, summary, evidence);
+  return judgeCompanyWith((id, prompt) => judge(id, prompt, { operatorSelected: true }), JUDGE, company, summary, evidence);
 }
 
 // Default research smoke set. The full supported route matrix lives in
@@ -95,23 +96,6 @@ interface RunModelOptions {
   routeSnapshot?: RouteSnapshot;
 }
 
-type PricingAtRun = {
-  source: "openrouter_snapshot" | "catalog" | "fallback_estimate";
-  inputPer1M: number;
-  outputPer1M: number;
-  cachedInputPer1M?: number;
-  contextWindow?: number;
-  routeSnapshotId?: string;
-};
-
-type RouteSnapshot = {
-  routeSnapshotId: string;
-  fetchedAt: string;
-  source: "openrouter" | "unavailable";
-  modelsById: Map<string, OpenRouterModelInfo>;
-  error?: string;
-};
-
 function unique(items: string[]): string[] {
   return [...new Set(items.filter(Boolean))];
 }
@@ -192,52 +176,8 @@ async function loadRouteSnapshot(): Promise<RouteSnapshot> {
   }
 }
 
-function priceFromOpenRouterInfo(info: OpenRouterModelInfo, routeSnapshotId: string): PricingAtRun | undefined {
-  const prompt = Number(info.pricing?.prompt);
-  const completion = Number(info.pricing?.completion);
-  if (!Number.isFinite(prompt) || !Number.isFinite(completion)) return undefined;
-  const cacheRead = Number(info.pricing?.input_cache_read);
-  return {
-    source: "openrouter_snapshot",
-    inputPer1M: prompt * 1_000_000,
-    outputPer1M: completion * 1_000_000,
-    ...(Number.isFinite(cacheRead) ? { cachedInputPer1M: cacheRead * 1_000_000 } : {}),
-    contextWindow: info.context_length ?? info.top_provider?.context_length,
-    routeSnapshotId,
-  };
-}
-
-function catalogPricingAtRun(modelId: string): PricingAtRun {
-  const pricing: ModelPricing | null = getModelPricing(resolveModelAlias(modelId));
-  if (!pricing) {
-    return {
-      source: "fallback_estimate",
-      inputPer1M: 1,
-      outputPer1M: 5,
-    };
-  }
-  return {
-    source: "catalog",
-    inputPer1M: pricing.inputPer1M,
-    outputPer1M: pricing.outputPer1M,
-    ...(pricing.cachedInputPer1M != null ? { cachedInputPer1M: pricing.cachedInputPer1M } : {}),
-    contextWindow: pricing.contextWindow,
-  };
-}
-
-function pricingAtRunFor(modelId: string, snapshot?: RouteSnapshot): PricingAtRun {
-  const resolved = resolveModelAlias(modelId);
-  const fromSnapshot = snapshot?.modelsById.get(resolved);
-  if (fromSnapshot) return priceFromOpenRouterInfo(fromSnapshot, snapshot.routeSnapshotId) ?? catalogPricingAtRun(resolved);
-  return catalogPricingAtRun(resolved);
-}
-
-function costFromPricing(pricing: PricingAtRun, inputTokens: number, outputTokens: number): number {
-  return (inputTokens * pricing.inputPer1M + outputTokens * pricing.outputPer1M) / 1_000_000;
-}
-
 function isOpenRouterRoute(modelId: string): boolean {
-  const resolved = resolveModelAlias(modelId);
+  const resolved = lookupModelAlias(modelId);
   return isOpenRouterFreeAutoModel(resolved) || resolved.includes("/");
 }
 
@@ -273,7 +213,7 @@ async function routeSmoke(modelId: string): Promise<{ ok: true; resolvedModels:
   const timer = setTimeout(() => ctl.abort(), timeoutMs);
   const resolvedModels: string[] = [];
   try {
-    const schemaRoute = model(modelId);
+    const schemaRoute = model(modelId, { operatorSelected: true });
     const schemaStep = await schemaRoute.next({
       system: "You are a route-contract smoke test. Return only JSON, no prose.",
       messages: [{
@@ -296,7 +236,7 @@ async function routeSmoke(modelId: string): Promise<{ ok: true; resolvedModels:
       };
     }
 
-    const toolRoute = model(modelId);
+    const toolRoute = model(modelId, { operatorSelected: true });
     const smokeTool: AgentTool = {
       name: "report_answer",
       description: "Report a short route-smoke answer.",
@@ -421,7 +361,7 @@ function runModelInChild(modelId: string, options: RunModelOptions, snapshot?: R
 }
 
 function recordingModel(modelId: string): { agentModel: AgentModel; resolvedModels: string[] } {
-  const baseModel = model(modelId);
+  const baseModel = model(modelId, { operatorSelected: true });
   const resolvedModels: string[] = [];
   return {
     resolvedModels,
diff --git a/scripts/design-qa/rubric-panel.ts b/scripts/design-qa/rubric-panel.ts
index d4921683..ad359785 100644
--- a/scripts/design-qa/rubric-panel.ts
+++ b/scripts/design-qa/rubric-panel.ts
@@ -19,7 +19,7 @@
 import "../benchmark/loadEnv";
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { generateObject, type ModelMessage } from "ai";
+import { generateObject, type UserContent } from "ai";
 import { google } from "@ai-sdk/google";
 import { z } from "zod";
 
@@ -28,7 +28,7 @@ const opt = (n: string) => args.find((a) => a.startsWith(`--${n}=`))?.slice(n.le
 const mediaPath = opt("media");
 const refPath = opt("reference");
 const floorPath = opt("floor");
-const model = process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.5-flash";
+const model = process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.6-flash";
 const outPath = opt("out") ?? join(process.cwd(), ".tmp-qa", "design-rubric.json");
 if (!mediaPath) throw new Error("--media=<candidate png> required");
 if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) throw new Error("GOOGLE_GENERATIVE_AI_API_KEY required");
@@ -59,7 +59,7 @@ const lensSchema = (dims: string[]) => z.object({
 });
 
 async function judgeLens(lens: typeof LENSES[number]) {
-  const content: ModelMessage["content"] = [
+  const content: UserContent = [
     { type: "text", text: [
       `You are the ${lens.key} critic in a design-QA jury for NodeRoom (a calm multiplayer finance-diligence room).`,
       `Judge ONLY your lens: ${lens.brief}`,
@@ -72,7 +72,7 @@ async function judgeLens(lens: typeof LENSES[number]) {
     { type: "file", data: candidate, filename: "candidate.png", mediaType: "image/png" },
   ];
   if (reference) content.push({ type: "file", data: reference, filename: "reference.png", mediaType: "image/png" });
-  const { object } = await generateObject({ model: google(model), schema: lensSchema(lens.dims), messages: [{ role: "user", content }], temperature: 0.2 });
+  const { object } = await generateObject({ model: google(model), schema: lensSchema(lens.dims), messages: [{ role: "user", content }] });
   return { lens: lens.key, ...object };
 }
 
diff --git a/scripts/eval/painJudge.ts b/scripts/eval/painJudge.ts
index db3283f9..e7f2c04f 100644
--- a/scripts/eval/painJudge.ts
+++ b/scripts/eval/painJudge.ts
@@ -5,7 +5,7 @@
  * point is addressed. This is the independent "does the live workflow truly relieve the
  * pain" check, before the Remotion demo.
  *
- *   npx tsx scripts/eval/painJudge.ts            # gemini-3.5-flash
+ *   npx tsx scripts/eval/painJudge.ts            # gemini-3.6-flash
  *   JUDGE_MODEL=gemini-3.1-flash-lite npx tsx scripts/eval/painJudge.ts
  */
 import "../benchmark/loadEnv";
@@ -15,7 +15,7 @@ import { generateText } from "ai";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 
 const ROOT = process.cwd();
-const MODEL = process.env.JUDGE_MODEL || "gemini-3.5-flash";
+const MODEL = process.env.JUDGE_MODEL || "gemini-3.6-flash";
 const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });
 
 const FRAMES: [string, string][] = [
diff --git a/scripts/eval/providerParseSmoke.ts b/scripts/eval/providerParseSmoke.ts
index faac869d..bde76df0 100644
--- a/scripts/eval/providerParseSmoke.ts
+++ b/scripts/eval/providerParseSmoke.ts
@@ -5,7 +5,7 @@
  * Verifies the architecture invariant: canonical Convex storageId != disposable provider file id.
  *
  *   npx tsx scripts/eval/providerParseSmoke.ts                       # gemini default
- *   npx tsx scripts/eval/providerParseSmoke.ts gemini-3.5-flash,gpt-5.4-mini,claude-haiku-4-5
+ *   npx tsx scripts/eval/providerParseSmoke.ts gemini-3.8-flash,gpt-5.4-mini,claude-haiku-5-5
  */
 import "../benchmark/loadEnv";
 import { z } from "zod";
@@ -13,12 +13,12 @@ import { generateObject } from "ai";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createAnthropic } from "@ai-sdk/anthropic";
-import { getProviderForModel } from "../../src/nodeagent/models/modelCatalog";
-import { priceRun } from "../../src/nodeagent/models/adapter";
+import { claudeEffortProviderOptions, getProviderForModel } from "../../src/nodeagent/models/modelCatalog";
+import { priceRequest } from "../../src/nodeagent/models/adapter";
 import { artifactsFromProviderExtraction, providerFileCacheMeta, type CanonicalFileRef, type ProviderExtraction, type ProviderUploadResult } from "../../src/app/providerParserAdapter";
 import type { CellPayload, ProviderParser } from "../../src/engine/types";
 
-const MODELS = (process.argv[2] || "gemini-3.5-flash,gpt-5.4-mini,claude-haiku-4-5").split(",").map((s) => s.trim());
+const MODELS = (process.argv[2] || "gemini-3.8-flash,gpt-5.4-mini,claude-haiku-5-5").split(",").map((s) => s.trim());
 
 // Synthetic messy diligence text — the ParselyFi/PitchBook archetype (unstructured → structured), no private data.
 const SAMPLE = `Diligence scratch notes (messy):
@@ -41,7 +41,7 @@ const SCHEMA = z.object({
 
 function providerModel(modelId: string) {
   const p = getProviderForModel(modelId);
-  if (p === "google") return createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })(modelId);
+  if (p === "gemini") return createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })(modelId);
   if (p === "anthropic") return createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })(modelId);
   if (p === "openrouter") return createOpenAI({ apiKey: process.env.OPENROUTER_API_KEY, baseURL: "https://openrouter.ai/api/v1" }).chat(modelId);
   return createOpenAI({ apiKey: process.env.OPENAI_API_KEY }).chat(modelId); // openai
@@ -50,7 +50,7 @@ function providerModel(modelId: string) {
 async function smoke(modelId: string) {
   const provider = getProviderForModel(modelId) as ProviderParser;
   const t0 = Date.now();
-  const res = await generateObject({ model: providerModel(modelId), schema: SCHEMA, prompt: PROMPT });
+  const res = await generateObject({ model: providerModel(modelId), schema: SCHEMA, prompt: PROMPT, ...claudeEffortProviderOptions(modelId) });
   const ms = Date.now() - t0;
   const extraction = res.object as ProviderExtraction;
 
@@ -60,7 +60,7 @@ async function smoke(modelId: string) {
   const providerFile = providerFileCacheMeta(file, upload);
   const artifacts = artifactsFromProviderExtraction({ file, providerFile, provider, model: modelId, extraction });
 
-  const cost = priceRun(modelId, res.usage?.inputTokens ?? 0, res.usage?.outputTokens ?? 0);
+  const cost = priceRequest(modelId, res.usage?.inputTokens ?? 0, res.usage?.outputTokens ?? 0);
   const art = artifacts[0];
   const tbl = extraction.tables?.[0];
   console.log(`\n=== ${modelId} (${provider}) · ${(ms / 1000).toFixed(1)}s · $${cost.toFixed(4)} ===`);
diff --git a/scripts/gemini-demo-media-judge.ts b/scripts/gemini-demo-media-judge.ts
index e1c209fc..74052e76 100644
--- a/scripts/gemini-demo-media-judge.ts
+++ b/scripts/gemini-demo-media-judge.ts
@@ -18,7 +18,7 @@ import { z } from "zod";
 const ROOT = process.cwd();
 const args = process.argv.slice(2);
 const invokedCommand = ["npm", "run", "media:gemini-judge", "--", ...args].map(quoteCommandArg).join(" ");
-const model = optionValue("--model") ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.5-flash";
+const model = optionValue("--model") ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.6-flash";
 const runId = optionValue("--run-id") ?? timestampId(new Date());
 const only = optionValue("--only")?.toLowerCase();
 const inputPaths = optionValues("--input");
@@ -238,7 +238,6 @@ async function judgeAsset(asset: Asset): Promise<AssetResult> {
       model: google(model),
       schema: judgeSchema,
       messages,
-      temperature: 0.2,
     });
     const judge = normalizeJudge(result.object);
     return {
diff --git a/scripts/gemini-mp4-workflow-review.ts b/scripts/gemini-mp4-workflow-review.ts
index ed6c8a44..56928617 100644
--- a/scripts/gemini-mp4-workflow-review.ts
+++ b/scripts/gemini-mp4-workflow-review.ts
@@ -12,7 +12,7 @@ import { z } from "zod";
 const args = process.argv.slice(2);
 const mediaPath = optionValue("--media");
 const outPath = optionValue("--out") ?? join(process.cwd(), "docs", "eval", "agent-improvement-loop", "mp4-workflow-review.json");
-const model = optionValue("--model") ?? process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.5-flash";
+const model = optionValue("--model") ?? process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.6-flash";
 
 if (!mediaPath) throw new Error("--media=<video> is required");
 if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) throw new Error("GOOGLE_GENERATIVE_AI_API_KEY is required");
@@ -79,7 +79,6 @@ const result = await generateObject({
   model: google(model),
   schema: reviewSchema,
   messages,
-  temperature: 0.2,
 });
 
 const out = {
diff --git a/scripts/gemini-ui-review.ts b/scripts/gemini-ui-review.ts
index d1bf8f76..d09e5509 100644
--- a/scripts/gemini-ui-review.ts
+++ b/scripts/gemini-ui-review.ts
@@ -8,7 +8,7 @@ import { z } from "zod";
 const args = process.argv.slice(2);
 const mediaPath = optionValue("--media");
 const outPath = optionValue("--out") ?? join(process.cwd(), "docs", "eval", "agent-improvement-loop", "gemini-ui-review.json");
-const model = optionValue("--model") ?? process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.5-flash";
+const model = optionValue("--model") ?? process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.6-flash";
 
 if (!mediaPath) throw new Error("--media=<screenshot-or-video> is required");
 if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) throw new Error("GOOGLE_GENERATIVE_AI_API_KEY is required");
diff --git a/scripts/gemini-visual-polish.ts b/scripts/gemini-visual-polish.ts
index b8397f09..9e6b275d 100644
--- a/scripts/gemini-visual-polish.ts
+++ b/scripts/gemini-visual-polish.ts
@@ -11,7 +11,7 @@ const args = process.argv.slice(2);
 const mediaPath = args.find((a) => a.startsWith("--media="))?.slice("--media=".length);
 const outPath = args.find((a) => a.startsWith("--out="))?.slice("--out=".length)
   ?? join(process.cwd(), ".tmp-qa", "gemini-visual-polish.json");
-const model = process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.5-flash";
+const model = process.env.GEMINI_UI_REVIEW_MODEL ?? "gemini-3.6-flash";
 if (!mediaPath) throw new Error("--media=<png> required");
 if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) throw new Error("GOOGLE_GENERATIVE_AI_API_KEY required");
 
@@ -52,7 +52,7 @@ const prompt = [
 ].join("\n");
 
 const messages: ModelMessage[] = [{ role: "user", content: [{ type: "text", text: prompt }, { type: "file", data: bytes, filename: "room.png", mediaType }] }];
-const result = await generateObject({ model: google(model), schema, messages, temperature: 0.2 });
+const result = await generateObject({ model: google(model), schema, messages });
 mkdirSync(dirname(outPath), { recursive: true });
 writeFileSync(outPath, JSON.stringify({ generatedAt: new Date().toISOString(), model, mediaPath, review: result.object }, null, 2));
 console.log(`overall=${result.object.overall} :: ${result.object.oneLineVerdict}`);
diff --git a/scripts/halo-live-path-calibration.ts b/scripts/halo-live-path-calibration.ts
index 7f93eb86..58bcf65c 100644
--- a/scripts/halo-live-path-calibration.ts
+++ b/scripts/halo-live-path-calibration.ts
@@ -61,7 +61,7 @@ async function runLiveManagedPath(runIndex: number): Promise<HaloSelfImprovement
   const result = await runAgent({
     rt,
     goal: "Set r_rev__variance to +24% and r_cogs__variance to +27.5%. Use runtime-managed writes and stop when both cells are written.",
-    model: realModel(route),
+    model: realModel(route, { operatorSelected: true }),
     tools: PRODUCTION_ROOM_TOOLS,
     systemPrompt: MANAGED_LOCK_SYSTEM_PROMPT,
     maxSteps: 10,
diff --git a/scripts/judge-demo-gif.ts b/scripts/judge-demo-gif.ts
index e8023806..a329725d 100644
--- a/scripts/judge-demo-gif.ts
+++ b/scripts/judge-demo-gif.ts
@@ -1,5 +1,5 @@
 /**
- * Gemini GIF judge — every demo GIF must be JUDGED AND VISUALLY VERIFIED by gemini-3.5-flash
+ * Gemini GIF judge — every demo GIF must be JUDGED AND VISUALLY VERIFIED by gemini-3.6-flash
  * before "demo ready" can be claimed (standing rule, 2026-06-11).
  *
  * The judge decodes the SHIPPED .gif itself (ImageMagick `-coalesce` for composed frames +
@@ -21,7 +21,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { WORKFLOWS } from "./workflow-preview/capture";
 
-const JUDGE_MODEL = "gemini-3.5-flash";
+const JUDGE_MODEL = process.env.GEMINI_JUDGE_MODEL ?? "gemini-3.6-flash";
 const GIF_DIR = "docs/eval/workflow-previews";
 const OUT_DIR = "docs/eval/gif-judge";
 const MAX_FRAMES = 12;
@@ -126,7 +126,7 @@ async function judge(id: string, gifPath: string): Promise<Verdict> {
     const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${JUDGE_MODEL}:generateContent?key=${key}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ contents: [{ parts }], generationConfig: { responseMimeType: "application/json", temperature: 0 } }),
+      body: JSON.stringify({ contents: [{ parts }], generationConfig: { responseMimeType: "application/json" } }),
       signal: controller.signal,
     });
     if (!res.ok) throw new Error(`judge HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
@@ -172,5 +172,5 @@ for (const id of targets) {
   for (const issue of v.topIssues.slice(0, 2)) console.log(`     · ${issue}`);
 }
 const failed = results.filter((r) => !r.pass);
-console.log(`\n${results.length - failed.length}/${results.length} shipped GIFs pass the gemini-3.5-flash judge -> ${OUT_DIR}/`);
+console.log(`\n${results.length - failed.length}/${results.length} shipped GIFs pass the gemini-3.6-flash judge -> ${OUT_DIR}/`);
 if (failed.length) { console.log(`FAILING: ${failed.map((f) => f.workflow).join(", ")} — fix and re-judge before claiming demo-ready.`); process.exit(1); }
diff --git a/scripts/judge-state-captures.ts b/scripts/judge-state-captures.ts
index df429758..94621b73 100644
--- a/scripts/judge-state-captures.ts
+++ b/scripts/judge-state-captures.ts
@@ -1,5 +1,5 @@
 /**
- * State-set vision judge — gemini-3.5-flash scores each SURFACE's full set of state captures
+ * State-set vision judge — gemini-3.6-flash scores each SURFACE's full set of state captures
  * (default/hover/focus/disabled/error/empty/locked/proposal/...) against the same adversarial
  * discipline as the GIF judge. The manifest's `mustBeTrue` line per capture tells the model what
  * each state is supposed to demonstrate, so the judge measures intent-vs-pixels, not vibes.
@@ -14,7 +14,7 @@ import "./benchmark/loadEnv";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-const JUDGE_MODEL = "gemini-3.5-flash";
+const JUDGE_MODEL = process.env.GEMINI_JUDGE_MODEL ?? "gemini-3.6-flash";
 const CAP_DIR = "docs/qa/state-captures";
 const OUT_DIR = "docs/qa/state-judge";
 const MANIFEST = join(CAP_DIR, "manifest.json");
@@ -82,7 +82,7 @@ async function judge(surface: string, caps: Capture[]): Promise<Verdict> {
     const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${JUDGE_MODEL}:generateContent?key=${key}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ contents: [{ parts }], generationConfig: { responseMimeType: "application/json", temperature: 0 } }),
+      body: JSON.stringify({ contents: [{ parts }], generationConfig: { responseMimeType: "application/json" } }),
       signal: controller.signal,
     });
     if (!res.ok) throw new Error(`judge HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
@@ -122,5 +122,5 @@ for (const s of surfaces) {
   for (const issue of v.topIssues.slice(0, 2)) console.log(`     · ${issue}`);
 }
 const failed = results.filter((r) => !r.pass);
-console.log(`\n${results.length - failed.length}/${results.length} surfaces pass the gemini-3.5-flash state judge -> ${OUT_DIR}/`);
+console.log(`\n${results.length - failed.length}/${results.length} surfaces pass the gemini-3.6-flash state judge -> ${OUT_DIR}/`);
 if (failed.length) { console.log(`FAILING: ${failed.map((f) => f.surface).join(", ")} — fix and re-judge.`); process.exit(1); }
diff --git a/scripts/proofloop-free-model-gauge.ts b/scripts/proofloop-free-model-gauge.ts
index 7986f968..e72cfeea 100644
--- a/scripts/proofloop-free-model-gauge.ts
+++ b/scripts/proofloop-free-model-gauge.ts
@@ -2,7 +2,7 @@ import "./benchmark/loadEnv";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { z } from "zod";
-import { model, priceRun } from "../src/nodeagent/models/adapter";
+import { model, priceRequest } from "../src/nodeagent/models/adapter";
 import { selectOpenRouterFreeModels } from "../src/nodeagent/models/openRouterFreeModels";
 
 type GaugeRow = {
@@ -96,7 +96,7 @@ for (const candidate of candidates) {
   }
 
   try {
-    const route = model(candidate.id);
+    const route = model(candidate.id, { operatorSelected: true });
     const response = await route.next({
       system: "You are running inside the NodeAgent proof-loop harness. Use the provided tool exactly once. Do not answer in prose.",
       messages: [{
@@ -132,7 +132,7 @@ for (const candidate of candidates) {
       contextLength,
       inputTokens: response.usage?.inputTokens ?? 0,
       outputTokens: response.usage?.outputTokens ?? 0,
-      estimatedCostUsd: Number(priceRun(candidate.id, response.usage?.inputTokens ?? 0, response.usage?.outputTokens ?? 0).toFixed(8)),
+      estimatedCostUsd: Number(priceRequest(candidate.id, response.usage?.inputTokens ?? 0, response.usage?.outputTokens ?? 0).toFixed(8)),
       durationMs: Date.now() - started,
       attemptedRequests: 1,
       completedRequests: 1,
diff --git a/scripts/sfn-nonbtb-nodeagent-runner.ts b/scripts/sfn-nonbtb-nodeagent-runner.ts
index c0517905..78777015 100644
--- a/scripts/sfn-nonbtb-nodeagent-runner.ts
+++ b/scripts/sfn-nonbtb-nodeagent-runner.ts
@@ -113,7 +113,7 @@ async function runOne(taskId: string) {
   const result = await runAgent({
     rt: stubRoomTools(),
     goal,
-    model: routedModel(MODEL_ID),
+    model: routedModel(MODEL_ID, { operatorSelected: true }),
     tools,
     maxSteps: 8,
   });
diff --git a/scripts/spreadsheetbench-chart-visual-grade.ts b/scripts/spreadsheetbench-chart-visual-grade.ts
index 37fad1e1..9591e236 100644
--- a/scripts/spreadsheetbench-chart-visual-grade.ts
+++ b/scripts/spreadsheetbench-chart-visual-grade.ts
@@ -10,7 +10,7 @@ import { z } from "zod";
 const args = process.argv.slice(2);
 const taskId = optionValue("--task-id") ?? "Visualization/Task 126";
 const sheet = optionValue("--sheet") ?? "Surprise";
-const model = optionValue("--model") ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.5-flash";
+const model = optionValue("--model") ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.6-flash";
 const outDir = resolve(optionValue("--out-dir") ?? join("docs", "eval", "spreadsheetbench-chart-visual", "task-126"));
 const tempDir = resolve(optionValue("--tmp-dir") ?? join(".tmp", "spreadsheetbench-chart-visual", "task-126"));
 const jsonOut = resolve(optionValue("--json-out") ?? join(outDir, "vlm-report.json"));
@@ -93,7 +93,6 @@ const result = await generateObject({
   model: google(model),
   schema: judgeSchema,
   messages,
-  temperature: 0,
 });
 
 const judged = result.object;
diff --git a/scripts/spreadsheetbench-run.ts b/scripts/spreadsheetbench-run.ts
index 8b8a1d59..bfcbcf81 100644
--- a/scripts/spreadsheetbench-run.ts
+++ b/scripts/spreadsheetbench-run.ts
@@ -88,6 +88,7 @@ if (modelRepairAttempts < 0 || modelRepairAttempts > 3) {
 const agentModel = modelId
   ? (await import("../src/nodeagent/models/adapter")).model(modelId, {
       freeAutoMode: freeAutoMode ?? (mode === "nodeagent-workbook" ? "agent" : mode === "model-edit-plan" ? "structured" : undefined),
+      operatorSelected: true,
     })
   : undefined;
 
diff --git a/scripts/startup-diligence-live-eval.ts b/scripts/startup-diligence-live-eval.ts
index efde9dac..7f8334cb 100644
--- a/scripts/startup-diligence-live-eval.ts
+++ b/scripts/startup-diligence-live-eval.ts
@@ -164,7 +164,10 @@ export async function runStartupDiligenceConvexContractEval(
     goal: jobGoal,
     entrypoint: "public_ask" as const,
     scope: "public_room" as const,
-    modelPolicy: modelForRun,
+    // The job only needs a route the public boundary accepts (SPEC A.0.10: a model outside the catalog is refused with
+    // unknown_model_policy). The runner is stubbed, so this route is never dispatched. The model the operator picked
+    // (possibly one the catalog does not know, D1) is recorded on the attempt rows via modelForRun, not here.
+    modelPolicy: "openrouter/free-auto",
     idempotencyKey: `startup-live-eval-${code}`,
     approvalPolicy: "host_review" as const,
     evidencePolicy: "public_only" as const,
diff --git a/scripts/startup-diligence-provider-eval.ts b/scripts/startup-diligence-provider-eval.ts
index 5489b343..e36988f7 100644
--- a/scripts/startup-diligence-provider-eval.ts
+++ b/scripts/startup-diligence-provider-eval.ts
@@ -2,7 +2,7 @@ import "./benchmark/loadEnv";
 import { performance } from "node:perf_hooks";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { convexModel, convexPriceRun } from "../src/nodeagent/models/convexModel";
+import { convexModel, convexPriceRequest } from "../src/nodeagent/models/convexModel";
 import type { StartupGeneratedCellPayload, StartupProviderGeneratedContent } from "./startup-diligence-live-eval";
 import {
   runStartupDiligenceConvexContractEval,
@@ -19,7 +19,7 @@ type ProviderDraft = {
 };
 
 async function generateProviderContent(modelId: string): Promise<StartupProviderGeneratedContent> {
-  const model = convexModel(modelId, { entrypoint: "public_ask" });
+  const model = convexModel(modelId, { entrypoint: "public_ask", operatorSelected: true });
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
   const started = performance.now();
@@ -73,7 +73,7 @@ async function generateProviderContent(modelId: string): Promise<StartupProvider
       cellPayload: parsed.cellPayload,
       finalText: parsed.finalText,
       usage: { inputTokens, outputTokens },
-      costUsd: convexPriceRun(model.name, inputTokens, outputTokens),
+      costUsd: convexPriceRequest(model.name, inputTokens, outputTokens),
       ms,
     };
   } finally {
@@ -147,12 +147,11 @@ function providerCandidates(explicit?: string): string[] {
     process.env.STARTUP_DILIGENCE_PROVIDER_MODEL,
     process.env.AGENT_RESEARCH_MODEL,
     process.env.AGENT_MODEL,
-    process.env.GOOGLE_GENERATIVE_AI_API_KEY ? "gemini-3.5-flash" : undefined,
-    process.env.GOOGLE_GENERATIVE_AI_API_KEY ? "gemini-2.5-flash" : undefined,
+    process.env.GOOGLE_GENERATIVE_AI_API_KEY ? "gemini-3.8-flash" : undefined,
     process.env.OPENROUTER_API_KEY ? "moonshotai/kimi-k2.6" : undefined,
     process.env.OPENROUTER_API_KEY ? "z-ai/glm-4.7-flash" : undefined,
     process.env.OPENAI_API_KEY ? "gpt-5.4-nano" : undefined,
-    process.env.ANTHROPIC_API_KEY ? "claude-haiku-4-5" : undefined,
+    process.env.ANTHROPIC_API_KEY ? "claude-haiku-5-5" : undefined,
   ].filter((value): value is string => !!value && value.trim().length > 0);
   return [...new Set(candidates.map((value) => value.trim()))];
 }
diff --git a/scripts/walkthroughs/judge-video.ts b/scripts/walkthroughs/judge-video.ts
index af8ca1f5..90c260d8 100644
--- a/scripts/walkthroughs/judge-video.ts
+++ b/scripts/walkthroughs/judge-video.ts
@@ -4,7 +4,7 @@
  * feel), returning timestamped defects. The render is no longer human-eyes-only.
  *
  * Run:  npx tsx scripts/walkthroughs/judge-video.ts noderoom-live-collab-v1 [renders/short.mp4]
- * Key:  GOOGLE_GENERATIVE_AI_API_KEY (env → .env.local). Model: gemini-3.5-flash (override via
+ * Key:  GOOGLE_GENERATIVE_AI_API_KEY (env → .env.local). Model: gemini-3.6-flash (override via
  *       GEMINI_JUDGE_MODEL). Video sent inline (<20MB) — short verticals fit comfortably.
  * Out:  episodes/<id>/judge.md (+ raw judge.json)
  */
@@ -50,7 +50,7 @@ const run = async () => {
   if (!existsSync(videoPath)) throw new Error(`missing ${videoPath}`);
   const bytes = readFileSync(videoPath);
   console.log(`[judge] ${rel} — ${(bytes.length / 1048576).toFixed(1)}MB → gemini`);
-  const model = process.env.GEMINI_JUDGE_MODEL ?? "gemini-3.5-flash";
+  const model = process.env.GEMINI_JUDGE_MODEL ?? "gemini-3.6-flash";
   const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key()}`, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -59,7 +59,7 @@ const run = async () => {
         { inline_data: { mime_type: "video/mp4", data: bytes.toString("base64") } },
         { text: RUBRIC },
       ] }],
-      generationConfig: { temperature: 0.2, response_mime_type: "application/json" },
+      generationConfig: { response_mime_type: "application/json" },
     }),
   });
   if (!res.ok) throw new Error(`gemini ${res.status}: ${(await res.text()).slice(0, 300)}`);
diff --git a/skills/seo-qa/scripts/judge-video-gemini.ts b/skills/seo-qa/scripts/judge-video-gemini.ts
index df1353f4..2090987b 100644
--- a/skills/seo-qa/scripts/judge-video-gemini.ts
+++ b/skills/seo-qa/scripts/judge-video-gemini.ts
@@ -1,7 +1,7 @@
 import "../../../scripts/benchmark/loadEnv";
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, relative } from "node:path";
+import { basename, extname, join, relative } from "node:path";
 import { generateObject, type ModelMessage } from "ai";
 import { google } from "@ai-sdk/google";
 import { z } from "zod";
@@ -9,7 +9,7 @@ import { z } from "zod";
 const ROOT = process.cwd();
 const args = process.argv.slice(2);
 const input = optionValue("--input");
-const model = optionValue("--model") ?? process.env.GEMINI_SEO_VIDEO_JUDGE_MODEL ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.5-flash";
+const model = optionValue("--model") ?? process.env.GEMINI_SEO_VIDEO_JUDGE_MODEL ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.6-flash";
 const scenario = optionValue("--scenario") ?? "landing";
 const dryRun = hasFlag("--dry-run");
 const outDir = optionValue("--out-dir") ?? join(ROOT, "docs", "seo", "journey-artifacts", "gemini-video-judges");
@@ -63,7 +63,6 @@ async function judgeVideo(): Promise<{ input: string; model: string; scenario: s
     model: google(model),
     schema,
     messages,
-    temperature: 0.2,
   });
   return {
     input: slash(relative(ROOT, inputPath)),
diff --git a/src/eval/bankerToolBenchNodeAgentGeneral.ts b/src/eval/bankerToolBenchNodeAgentGeneral.ts
index 81f76a53..ca5f8281 100644
--- a/src/eval/bankerToolBenchNodeAgentGeneral.ts
+++ b/src/eval/bankerToolBenchNodeAgentGeneral.ts
@@ -2,7 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { z } from "zod";
 import { runAgent, type AgentMessage, type AgentModel, type AgentTool, type AgentTraceEvent, type RoomTools } from "../nodeagent";
-import { model as routedModel, priceRun } from "../nodeagent/models/adapter";
+import { model as routedModel, priceRequest, priceRun } from "../nodeagent/models/adapter";
 
 export interface BankerToolBenchSourcePacket {
   schema: string;
@@ -302,7 +302,7 @@ export async function runBankerToolBenchNodeAgentGeneral(
         deadlineAt: toolPlannerDeadlineAt,
         reserveMs,
         spendLimits: { maxTokens: 260_000, maxCostUsd: 8 },
-        priceStep: priceRun,
+        priceStep: priceRequest,
         contextBuilder: async () => [
           {
             role: "user",
@@ -1233,7 +1233,7 @@ function createPlannerModel(
       },
     };
   }
-  return routedModel(modelId, { entrypoint: "room_work" });
+  return routedModel(modelId, { entrypoint: "room_work", operatorSelected: true });
 }
 
 function createPlannerTools(onPlan: (plan: BankerToolBenchArtifactPlan) => void): AgentTool[] {
diff --git a/src/eval/proofloopModelTracking.ts b/src/eval/proofloopModelTracking.ts
index 21344478..062d47bc 100644
--- a/src/eval/proofloopModelTracking.ts
+++ b/src/eval/proofloopModelTracking.ts
@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { normalizeInteropModelRoute } from "../nodeagent/integrations/modelInterop";
-import { getModelPricing, resolveModelAlias } from "../nodeagent/models/modelCatalog";
+import { getModelPricing, priceAggregateTokens, lookupModelAlias } from "../nodeagent/models/modelCatalog";
 
 export type ProofloopModelRole = "planner" | "worker" | "judge" | "verifier";
 export type ProofloopCostAccountingStatus = "actual" | "estimated" | "free" | "unknown";
@@ -180,7 +180,7 @@ export function isProofloopFreeLocalOrNoProviderModel(args: {
   routePolicy?: string;
 }): boolean {
   const id = (args.id ?? "").trim();
-  const resolved = resolveModelAlias(id).toLowerCase();
+  const resolved = lookupModelAlias(id).toLowerCase();
   const provider = (args.provider ?? "").trim().toLowerCase();
   const routePolicy = (args.routePolicy ?? "").trim().toLowerCase();
   if (!id) return false;
@@ -188,7 +188,7 @@ export function isProofloopFreeLocalOrNoProviderModel(args: {
   if (provider === "local" || provider === "none" || provider === "no-provider" || provider === "no_provider") return true;
   if (resolved.startsWith("local/") || resolved === "local") return true;
   if (resolved.endsWith(":free") || resolved.startsWith("openrouter/free")) return true;
-  const pricing = getModelPricing(resolveModelAlias(id));
+  const pricing = getModelPricing(lookupModelAlias(id));
   return pricing != null && pricing.inputPer1M === 0 && pricing.outputPer1M === 0;
 }
 
@@ -272,14 +272,14 @@ function finiteNonNegative(value: number | null | undefined): value is number {
 }
 
 function estimateModelCostUsd(modelId: string, tokensIn: number, tokensOut: number): number | undefined {
-  const pricing = getModelPricing(resolveModelAlias(modelId));
+  const pricing = getModelPricing(lookupModelAlias(modelId));
   if (!pricing) return undefined;
-  return Number(((tokensIn * pricing.inputPer1M + tokensOut * pricing.outputPer1M) / 1_000_000).toFixed(8));
+  return Number(priceAggregateTokens(pricing, tokensIn, tokensOut).toFixed(8));
 }
 
 function freeAccountingSource(modelId: string, provider: string): ProofloopCostAccountingSource {
   const normalizedProvider = provider.trim().toLowerCase();
-  const normalizedModel = resolveModelAlias(modelId).toLowerCase();
+  const normalizedModel = lookupModelAlias(modelId).toLowerCase();
   if (normalizedProvider === "none" || normalizedProvider === "no-provider" || normalizedProvider === "no_provider") return "no_provider";
   if (normalizedProvider === "local" || normalizedModel.startsWith("local/") || normalizedModel === "local") return "free_local";
   return "free_provider";
diff --git a/src/eval/spreadsheetBenchChartVisualProbe.ts b/src/eval/spreadsheetBenchChartVisualProbe.ts
index 9f0bc485..d1f4ff2c 100644
--- a/src/eval/spreadsheetBenchChartVisualProbe.ts
+++ b/src/eval/spreadsheetBenchChartVisualProbe.ts
@@ -68,7 +68,7 @@ export type SpreadsheetBenchChartVisualProbeOptions = {
 export function runSpreadsheetBenchChartVisualProbe(
   options: SpreadsheetBenchChartVisualProbeOptions = {},
 ): SpreadsheetBenchChartVisualProbe {
-  const model = options.model ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.5-flash";
+  const model = options.model ?? process.env.GEMINI_MEDIA_JUDGE_MODEL ?? "gemini-3.6-flash";
   const env = options.env ?? process.env;
   const runCommand = options.runCommand ?? run;
   const candidates = (options.rendererCommands ?? defaultRendererCommands()).map((candidate) =>
diff --git a/src/eval/spreadsheetBenchRunner.ts b/src/eval/spreadsheetBenchRunner.ts
index bf4216cc..68a9f419 100644
--- a/src/eval/spreadsheetBenchRunner.ts
+++ b/src/eval/spreadsheetBenchRunner.ts
@@ -10,7 +10,7 @@ import {
 } from "./spreadsheetBenchScorer";
 import type { SpreadsheetBenchTrack } from "./spreadsheetBenchAdapter";
 import type { AgentModel, TokenUsage } from "../nodeagent/core/types";
-import { priceRun } from "../nodeagent/models/adapter";
+import { priceRequest, priceRun } from "../nodeagent/models/adapter";
 import { getModelPricing } from "../nodeagent/models/modelCatalog";
 import {
   runSpreadsheetBenchNodeAgentBridge,
@@ -1444,7 +1444,7 @@ async function prepareBatchedModelPlans(
       .digest("hex")
       .slice(0, 16);
     const totalCostUsd = getModelPricing(modelName)
-      ? priceRun(modelName, usage.inputTokens, usage.outputTokens)
+      ? priceRequest(modelName, usage.inputTokens, usage.outputTokens) // one batch = one provider request
       : 0;
 
     for (const [taskIndex, item] of batchPrepared.entries()) {
@@ -1715,7 +1715,7 @@ async function emitModelEditCandidateWorkbook(args: {
       args.trajectory.push({ step: "call_model_for_edit_plan", detail: args.model.name });
       const usage = step.usage ?? { inputTokens: 0, outputTokens: 0 };
       const modelName = args.model.name || attemptedModelName;
-      const costUsd = step.usage && getModelPricing(modelName) ? priceRun(modelName, usage.inputTokens, usage.outputTokens) : 0;
+      const costUsd = step.usage && getModelPricing(modelName) ? priceRequest(modelName, usage.inputTokens, usage.outputTokens) : 0;
       modelInfo = {
         name: modelName,
         ...(requestedModelName && requestedModelName !== modelName ? { requestedName: requestedModelName } : {}),
@@ -1987,7 +1987,7 @@ function aggregateModelPlanningStep(
   const usage = step.usage ?? { inputTokens: 0, outputTokens: 0 };
   const resolved = resolvedName || current.name;
   const stepCost = step.usage && getModelPricing(resolved)
-    ? priceRun(resolved, usage.inputTokens, usage.outputTokens)
+    ? priceRequest(resolved, usage.inputTokens, usage.outputTokens)
     : 0;
   return {
     ...current,
diff --git a/src/nodeagent/capture/reasoning.ts b/src/nodeagent/capture/reasoning.ts
index 8b351492..5eefd8e5 100644
--- a/src/nodeagent/capture/reasoning.ts
+++ b/src/nodeagent/capture/reasoning.ts
@@ -8,6 +8,7 @@
 import { generateObject, type LanguageModel } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAI } from "@ai-sdk/openai";
+import { claudeEffortProviderOptions, getProviderForModel, resolveModelAlias } from "../models/modelCatalog";
 import type { ReasoningModel } from "./types";
 
 // Trim env keys: a stray trailing \r (Windows copy/pipe artifact in `convex env set`) would otherwise
@@ -20,7 +21,14 @@ function providerFor(modelId: string): LanguageModel {
   return anthropic(modelId); // default + all claude-* ids
 }
 
-export function aiSdkReasoner(modelId = "claude-haiku-4-5"): ReasoningModel {
+export function aiSdkReasoner(modelId = "claude-haiku-5-5"): ReasoningModel {
+  // SPEC A.0.10: `convex/capturesNode.ts` passes a client-supplied modelId, and providerFor() picks a provider by prefix alone,
+  // so an id the catalog does not know would still dispatch. The resolver throws for it; an unknown free-looking id resolves to
+  // `openrouter/free-auto`, which this Anthropic/OpenAI seam cannot serve, so it is refused rather than sent under the raw name.
+  // One guard here covers every caller (capturesNode, captureSource, the Firecrawl tool); the RESOLVED id is what dispatches.
+  const routeId = resolveModelAlias(modelId);
+  const provider = getProviderForModel(routeId);
+  if (provider !== "anthropic" && provider !== "openai") throw new Error(`capture_reasoner_route_unsupported:${routeId}`);
   return {
     name: modelId,
     async decide<T>({ system, instruction, context, schema, signal }: {
@@ -36,10 +44,11 @@ export function aiSdkReasoner(modelId = "claude-haiku-4-5"): ReasoningModel {
       const content: Array<{ type: "text"; text: string } | { type: "image"; image: Uint8Array }> = [{ type: "text", text }];
       if (context.screenshot) content.push({ type: "image", image: context.screenshot.png });
       const { object } = await generateObject({
-        model: providerFor(modelId),
+        model: providerFor(routeId),
         schema, // zod schema → generateObject validates the result to T
         system,
         messages: [{ role: "user", content }],
+        ...claudeEffortProviderOptions(routeId), // explicit SPEC §1.3 effort for claude-*-5-5
         abortSignal: signal,
       });
       return object as T;
diff --git a/src/nodeagent/core/adaptiveRouter.ts b/src/nodeagent/core/adaptiveRouter.ts
index db92b58d..95afca82 100644
--- a/src/nodeagent/core/adaptiveRouter.ts
+++ b/src/nodeagent/core/adaptiveRouter.ts
@@ -1,6 +1,7 @@
 import type { ModelPricing } from "../models/modelCatalog";
 import { getModelPricing, getProviderForModel, resolveModelAlias } from "../models/modelCatalog";
 import { OPENROUTER_FREE_AUTO_MODEL, selectOpenRouterFreeModels } from "../models/openRouterFreeModels";
+import { DEFAULT_AGENT_MODEL } from "../../../convex/modelDefaults";
 
 export type NodeAgentRouteRisk = "low" | "medium" | "high";
 export type NodeAgentLatencyClass = "interactive" | "batch" | "overnight";
@@ -81,7 +82,7 @@ export interface ReviewAdaptiveRoute {
 export function defaultRouteForTask(taskType: AdaptiveRouteRequest["taskType"]): string {
   if (taskType === "research" || taskType === "finance") return process.env.AGENT_RESEARCH_MODEL ?? "minimax/minimax-m3";
   if (taskType === "router") return process.env.AGENT_ROUTER_MODEL ?? OPENROUTER_FREE_AUTO_MODEL;
-  return process.env.AGENT_MODEL ?? "gemini-3.5-flash";
+  return process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL;
 }
 
 export function chooseModelRoute(request: AdaptiveRouteRequest): AdaptiveRouteDecision {
@@ -133,6 +134,8 @@ export function chooseNodeAgentRoute(req: NodeAgentRouteRequest): NodeAgentRoute
       requireN5Promotion: true,
     };
   }
+  // Fast lane stays on the model with the recorded L1-L4 ladder pass. It moves to DEFAULT_AGENT_MODEL only
+  // after docs/eval/ladder/model-refresh-noderoom.json exists (SPEC Part A §A.2.9; requireN5Promotion below).
   const modelId = "gemini-3.5-flash";
   return {
     model: modelId,
diff --git a/src/nodeagent/core/creditModel.ts b/src/nodeagent/core/creditModel.ts
index 1698ca73..2931ca10 100644
--- a/src/nodeagent/core/creditModel.ts
+++ b/src/nodeagent/core/creditModel.ts
@@ -17,14 +17,14 @@
  * agentRuns rows (see PRODUCTION_CALIBRATION), not invented. Re-run the calibration
  * query and update these if the live distribution shifts.
  */
-import { getModelPricing, resolveModelAlias } from "../models/modelCatalog";
+import { getModelPricing, priceAggregateTokens, lookupModelAlias } from "../models/modelCatalog";
 import type { NodeAgentBudgetProfile } from "./budgetProfiles";
 
 /** LLM run cost in USD. Inlined from adapter.priceRun (same modelPricing table) so this
  *  module has NO AI-SDK dependency and is safe to import from Convex functions + scripts. */
 function priceRun(modelId: string, inTok: number, outTok: number): number {
-  const p = getModelPricing(resolveModelAlias(modelId));
-  return (inTok * (p?.inputPer1M ?? 1) + outTok * (p?.outputPer1M ?? 5)) / 1_000_000;
+  const p = getModelPricing(lookupModelAlias(modelId));
+  return p ? priceAggregateTokens(p, inTok, outTok) : (inTok * 1 + outTok * 5) / 1_000_000;
 }
 
 // ---------------------------------------------------------------------------
diff --git a/src/nodeagent/core/runtime.ts b/src/nodeagent/core/runtime.ts
index d0718141..214e0d32 100644
--- a/src/nodeagent/core/runtime.ts
+++ b/src/nodeagent/core/runtime.ts
@@ -513,7 +513,7 @@ export async function runAgent(opts: {
   spendLimits?: SpendLimits;
   /** P0-4: price a completed step in USD so maxCostUsd actually fires — without this the gate
    *  receives costUsd:0 and the dollar half of the ceiling is dead surface (HONEST_STATUS class).
-   *  Pass priceRun (src/nodeagent/models/adapter.ts) or convexPriceRun (src/nodeagent/models/convexModel.ts) from the caller. */
+   *  Pass priceRequest (src/nodeagent/models/adapter.ts) or convexPriceRequest (src/nodeagent/models/convexModel.ts) from the caller: it prices ONE request, so a tiered row bills each prompt at its own tier. */
   priceStep?: (modelName: string, inputTokens: number, outputTokens: number) => number;
   /** Keep the model's context bounded on long runs. */
   compaction?: CompactionOpts;
diff --git a/src/nodeagent/guardrails/egressPolicy.ts b/src/nodeagent/guardrails/egressPolicy.ts
index ec6303f1..cd2bcfc5 100644
--- a/src/nodeagent/guardrails/egressPolicy.ts
+++ b/src/nodeagent/guardrails/egressPolicy.ts
@@ -1,4 +1,4 @@
-import { getProviderForModel, resolveModelAlias, type LlmProvider } from "../models/modelCatalog";
+import { getProviderForModel, lookupModelAlias, type LlmProvider } from "../models/modelCatalog";
 import { providerHealthDecision } from "./providerHealth";
 
 type Env = Record<string, string | undefined>;
@@ -144,7 +144,7 @@ export function providerRouteDecision(args: {
 }): ProviderRouteDecision {
   const env = args.env ?? process.env;
   const requestedModel = args.model.trim();
-  const resolvedModel = resolveModelAlias(requestedModel);
+  const resolvedModel = lookupModelAlias(requestedModel);
   const allowedProviders = providerAllowlist(env);
   const external = isExternalProviderRoute(resolvedModel);
   const provider = external ? getProviderForModel(resolvedModel) : "local";
diff --git a/src/nodeagent/integrations/langchain.ts b/src/nodeagent/integrations/langchain.ts
index 1d4a0315..a4a22271 100644
--- a/src/nodeagent/integrations/langchain.ts
+++ b/src/nodeagent/integrations/langchain.ts
@@ -1,6 +1,7 @@
 import type { AgentMessage, AgentModel, AgentStep, AgentTool, AgentToolChoice, RoomTools, ToolCall } from "../core/types";
 import { runAgent } from "../core/runtime";
 import { normalizeInteropModelRoute } from "./modelInterop";
+import { needsStrictTools, lookupModelAlias } from "../models/modelCatalog";
 
 export type LangChainMessageLike = {
   role?: string;
@@ -43,7 +44,7 @@ export function createLangChainAgentModel(chatModel: LangChainChatModelLike, opt
     async next({ system, messages, tools, signal, onTextDelta, toolChoice }): Promise<AgentStep> {
       const toolDefs = langChainToolDefinitions(tools);
       const runnable = typeof chatModel.bindTools === "function" && toolDefs.length
-        ? chatModel.bindTools(toolDefs, langChainToolChoiceConfig(toolChoice))
+        ? chatModel.bindTools(toolDefs, langChainToolChoiceConfig(toolChoice, modelNameFor(chatModel)))
         : chatModel;
       const output = await runnable.invoke(
         toLangChainMessages(system, messages),
@@ -205,7 +206,10 @@ function argsValue(value: unknown): Record<string, unknown> {
   return objectRecord(value) ?? {};
 }
 
-function langChainToolChoiceConfig(toolChoice?: AgentToolChoice): Record<string, unknown> {
+function langChainToolChoiceConfig(toolChoice: AgentToolChoice | undefined, modelName: string): Record<string, unknown> {
+  // Claude 5.5 Sonnet/Opus reject a forced tool_choice (SPEC §1.3): leave it unset so the provider default (auto)
+  // applies, and bind the tools with `strict: true` so their arguments are still schema-valid.
+  if (needsStrictTools(lookupModelAlias(modelName), toolChoice)) return { strict: true };
   return toolChoice === "required" ? { tool_choice: "any" } : {};
 }
 
diff --git a/src/nodeagent/integrations/modelInterop.ts b/src/nodeagent/integrations/modelInterop.ts
index 4a1ab15b..cc7af062 100644
--- a/src/nodeagent/integrations/modelInterop.ts
+++ b/src/nodeagent/integrations/modelInterop.ts
@@ -1,4 +1,4 @@
-import { isNodeAgentFreeAutoModel, resolveModelAlias } from "../models/modelCatalog";
+import { isNodeAgentFreeAutoModel, lookupModelAlias } from "../models/modelCatalog";
 
 export type InteropRouteRuntime = "native" | "langchain" | "litellm" | "openrouter";
 
@@ -11,6 +11,10 @@ export type InteropModelRoute = {
   basis: string[];
 };
 
+/**
+ * Labels a route for receipts and the bridges; it never dispatches, so it reads the lenient `lookupModelAlias`.
+ * Dispatch fails closed on an unknown id at `model()` / `convexModel()` (SPEC A.0.10).
+ */
 export function normalizeInteropModelRoute(route: string): InteropModelRoute {
   const requested = route.trim();
   const lower = requested.toLowerCase();
@@ -36,7 +40,7 @@ export function normalizeInteropModelRoute(route: string): InteropModelRoute {
     };
   }
 
-  const resolvedNativeRoute = resolveModelAlias(requested);
+  const resolvedNativeRoute = lookupModelAlias(requested);
   if (isNodeAgentFreeAutoModel(resolvedNativeRoute)) {
     return {
       requested,
@@ -78,7 +82,7 @@ export function normalizeInteropModelRoute(route: string): InteropModelRoute {
   const openrouter = requested.match(/^openrouter:(.+)$/i);
   if (openrouter) {
     const model = openrouter[1].trim();
-    const modelId = model === "free" || model === "free-auto" ? `openrouter/${model}` : resolveModelAlias(model);
+    const modelId = model === "free" || model === "free-auto" ? `openrouter/${model}` : lookupModelAlias(model);
     return {
       requested,
       modelId,
@@ -113,7 +117,7 @@ function normalizeProvider(provider: string): string {
 function normalizeProviderScopedModel(provider: string, model: string): string {
   const trimmed = model.trim();
   if (provider === "openrouter" && (trimmed === "free" || trimmed === "free-auto")) return `openrouter/${trimmed}`;
-  return resolveModelAlias(trimmed);
+  return lookupModelAlias(trimmed);
 }
 
 function normalizeScopedGatewayModel(model: string): { provider: string; modelId: string } {
@@ -122,7 +126,7 @@ function normalizeScopedGatewayModel(model: string): { provider: string; modelId
   const payload = rest.join("/");
   const provider = normalizeProvider(scope ?? "");
   if (!payload || !["openai", "anthropic", "google", "openrouter"].includes(provider)) {
-    const modelId = resolveModelAlias(trimmed);
+    const modelId = lookupModelAlias(trimmed);
     return { provider: inferProvider(modelId, "litellm"), modelId };
   }
   return {
diff --git a/src/nodeagent/models/adapter.ts b/src/nodeagent/models/adapter.ts
index 4985fd50..a6762c9f 100644
--- a/src/nodeagent/models/adapter.ts
+++ b/src/nodeagent/models/adapter.ts
@@ -19,14 +19,24 @@ import { dirname, resolve } from "node:path";
 import { anthropic } from "@ai-sdk/anthropic";
 import { google } from "@ai-sdk/google";
 import { openai, createOpenAI } from "@ai-sdk/openai";
+import { z } from "zod";
 import type { AgentModel, AgentMessage, AgentTool, AgentToolChoice, ToolCall } from "../core/types";
 import {
+  claudeEffortProviderOptions,
+  forbidsForcedToolChoice,
   getProviderForModel,
   getModelPricing,
+  isFreeModelId,
   isNodeAgentFreeAutoModel,
+  lookupModelAlias,
+  needsStrictTools,
+  priceAggregateTokens,
+  priceTokens,
   NODEAGENT_FREE_AUTO_MODEL,
   resolveModelAlias,
 } from "./modelCatalog";
+import { modelMaxOutputTokens } from "./outputTokens";
+import { DEFAULT_AGENT_MODEL } from "../../../convex/modelDefaults";
 import {
   OPENROUTER_FREE_AUTO_MODEL,
   isOpenRouterFreeAutoModel,
@@ -79,27 +89,110 @@ function providerFor(modelId: string): LanguageModel {
   }
 }
 
+/**
+ * How many provider requests one logical turn may issue. `withRetry` is the ONLY retry layer (the AI SDK's
+ * own loop is pinned to 0), so every physical request is one attempt carrying its own reservation.
+ * The ladder receipt policy is { maxRetries: 0, crossModelFallback: false }.
+ */
+export type DispatchPolicy = {
+  maxRetries: number;
+  crossModelFallback: boolean;
+  /**
+   * SPEC A.0.10: a free primary never falls back to a paid model unless this is `true` AND the request carries a
+   * `SpendMeter` (`meteredDispatch` reserves the paid model's worst case before the request is issued).
+   */
+  allowPaidFallback?: boolean;
+};
+export const DEFAULT_DISPATCH_POLICY: DispatchPolicy = { maxRetries: 3, crossModelFallback: true };
+
+/**
+ * One provider request as the receipt needs it (SPEC A.0.3): what was asked for, what the adapter chose, the
+ * model string the PROVIDER answered with (`echoedModel`, null when the request threw), its usage, its cost
+ * (the settled price, or the full reservation when usage is unknown) and whether it was a fallback dispatch.
+ */
+export type DispatchRecord = {
+  requestedModel: string;
+  resolvedModel: string;
+  echoedModel: string | null;
+  usage: { inputTokens: number; outputTokens: number } | null;
+  costUsd: number;
+  fallbackUsed: boolean;
+};
+
+/** A paid run issues at most a few hundred requests; the bound only guards a loop that lost its cap. */
+export const MAX_DISPATCH_RECORDS = 4096;
+
+/** Job-wide USD meter for a paid run. Moves at dispatches only (see `meteredDispatch`). */
+export type SpendMeter = {
+  maxUsd: number;
+  spentUsd: number;
+  requests: number;
+  stoppedBy: null | "spend_budget" | "unpriced_model";
+  /** One row per issued request, oldest first, capped at MAX_DISPATCH_RECORDS (`requests` and `spentUsd` keep counting). */
+  dispatches: DispatchRecord[];
+  /** Requests issued past the cap that have no row in `dispatches`; a receipt with a non-zero count is incomplete (A.0.3). */
+  droppedDispatches: number;
+};
+export const createSpendMeter = (maxUsd: number): SpendMeter => ({ maxUsd, spentUsd: 0, requests: 0, stoppedBy: null, dispatches: [], droppedDispatches: 0 });
+
+/** A dispatch the budget cannot cover. `receipt.stopReason` is what runtime.ts turns into a `spend_budget` handoff. */
+export class SpendBudgetError extends Error {
+  readonly receipt = { stopReason: "spend_budget" as const };
+  constructor(message: string) {
+    super(message);
+    this.name = "SpendBudgetError";
+  }
+}
+
+/** An id the adapter can route but the catalog cannot price. Never reserved, never dispatched. */
+export class UnpricedModelError extends SpendBudgetError {
+  constructor(readonly modelId: string) {
+    super(`no pricing row for "${modelId}"; add a verified row to modelCatalog.modelPricing before a paid run`);
+    this.name = "UnpricedModelError";
+  }
+}
+
 export type ModelAdapterOptions = {
   entrypoint?: ProviderRouteEntrypoint;
   artifacts?: ProviderEgressArtifact[];
   freeAutoMode?: OpenRouterFreeModelMode;
+  /** Retry / cross-model-fallback policy. Defaults to today's behaviour (3 retries, fallback allowed). */
+  dispatch?: DispatchPolicy;
+  /** When set, every provider request reserves its worst-case cost here before it is issued. */
+  meter?: SpendMeter;
+  /**
+   * Eval and smoke scripts only (SPEC-v9 D1: operator overrides stay pass-through). The id was typed by an operator (CLI flag,
+   * `*_LIVE_MODEL`) or picked from the live OpenRouter list: the alias table still applies, but an id the catalog does not
+   * know goes to the provider as written - it does not throw and a concrete `:free` id is not rewritten to the auto router,
+   * so a run is measured under the label it was asked for. Server code never sets this; it stays fail-closed (A.0.10).
+   */
+  operatorSelected?: boolean;
 };
 
 /** Any catalog model behind the SAME seam — swap freely in the benchmark + the action. */
 export function model(modelId: string, options: ModelAdapterOptions = {}): AgentModel {
-  const aliasModelId = resolveModelAlias(modelId);
+  const aliasModelId = options.operatorSelected ? lookupModelAlias(modelId) : resolveModelAlias(modelId);
   const entrypoint = options.entrypoint ?? "system";
   const artifacts = options.artifacts ?? [];
   const freeAutoMode = options.freeAutoMode;
+  const dispatchPolicy = options.dispatch ?? DEFAULT_DISPATCH_POLICY;
+  const meter = options.meter;
   // free-auto resolves a concrete free model per call; record the actual one used so the
   // agentRuns audit captures which model produced the cells, not just the "openrouter/free-auto" alias.
   let resolvedModelId = aliasModelId;
   return {
     get name() { return resolvedModelId; },
-    async next({ system, messages, tools, signal, toolChoice }) {
+    async next({ system, messages, tools, signal, toolChoice, maxCostUsd }) {
       assertProviderEgressAllowed({ model: aliasModelId, entrypoint, artifacts, env: process.env });
       const safeSystem = redactPII(system).text;
       const safeMessages = messages.map((m) => (m.role === "user" && m.content ? { ...m, content: redactPII(m.content).text } : m));
+      const dispatch: DispatchContext = {
+        policy: dispatchPolicy,
+        requestedModel: modelId,
+        meter,
+        maxCostUsd,
+        inputTokenUpperBound: meter ? requestInputTokenUpperBound(safeSystem, safeMessages, tools) : 0,
+      };
       const sdkTools = Object.fromEntries(tools.map((t) => [t.name, tool({ description: t.description, inputSchema: t.schema })]));
       const { res, resolvedModel, providerRoute, qualityFailover } = await generateAgentText(
         aliasModelId,
@@ -112,6 +205,7 @@ export function model(modelId: string, options: ModelAdapterOptions = {}): Agent
         toolChoice,
         freeAutoMode,
         { messages: safeMessages, tools },
+        dispatch,
       );
       resolvedModelId = resolvedModel;
       const toolCalls: ToolCall[] = (res.toolCalls ?? []).map((tc: { toolCallId: string; toolName: string; input?: Record<string, unknown>; providerMetadata?: Record<string, unknown> }) => ({ id: tc.toolCallId, tool: tc.toolName, args: tc.input ?? {}, providerMetadata: tc.providerMetadata }));
@@ -129,27 +223,148 @@ export function model(modelId: string, options: ModelAdapterOptions = {}): Agent
 }
 
 /** Back-compat alias (Convex action default). */
-export const anthropicModel = (modelId = "claude-haiku-4-5"): AgentModel => model(modelId);
+export const anthropicModel = (modelId = "claude-haiku-5-5"): AgentModel => model(modelId);
 
-/** A plain text/JSON completion (no tools) — used by the eval's LLM-judge. */
-export async function judge(modelId: string, prompt: string): Promise<string> {
+/**
+ * A plain text/JSON completion (no tools) — used by the eval's LLM-judge. `operatorSelected` is for eval callers whose
+ * model id was typed by an operator (CLI flag, env): same meaning as in `ModelAdapterOptions` (SPEC-v9 D1).
+ */
+export async function judge(modelId: string, prompt: string, options: Pick<ModelAdapterOptions, "operatorSelected"> = {}): Promise<string> {
   const safePrompt = redactPII(prompt).text;
-  const res = await generatePromptText(resolveModelAlias(modelId), safePrompt);
+  const res = await generatePromptText(options.operatorSelected ? lookupModelAlias(modelId) : resolveModelAlias(modelId), safePrompt);
   return res.text ?? "";
 }
 
-/** Cost from the catalog's pricing (per 1M tokens) — single source of truth, no parallel table. */
+/**
+ * Cost of usage SUMMED over several requests, from the catalog's pricing (per 1M tokens) — single source of truth,
+ * no parallel table. Base-tier rates only: the long-context tier is a property of one request's prompt, so it is
+ * never inferred from a total. A per-request `priceStep` must use `priceRequest`.
+ */
 export const priceRun = (modelId: string, inTok: number, outTok: number): number => {
-  const p = getModelPricing(resolveModelAlias(modelId));
-  return (inTok * (p?.inputPer1M ?? 1) + outTok * (p?.outputPer1M ?? 5)) / 1_000_000;
+  const p = getModelPricing(lookupModelAlias(modelId));
+  return p ? priceAggregateTokens(p, inTok, outTok) : (inTok * 1 + outTok * 5) / 1_000_000;
+};
+
+/** Cost of ONE provider request (`inTok` is that request's prompt), tier-aware. This is the `priceStep` price. */
+export const priceRequest = (modelId: string, inTok: number, outTok: number): number => {
+  const p = getModelPricing(lookupModelAlias(modelId));
+  return p ? priceTokens(p, inTok, outTok) : (inTok * 1 + outTok * 5) / 1_000_000;
 };
 
+/** Same formula as `priceRequest`, but an id with no pricing row throws instead of costing a guessed $1/$5. */
+export const priceRequestStrict = (modelId: string, inTok: number, outTok: number): number => {
+  const p = getModelPricing(lookupModelAlias(modelId));
+  if (!p) throw new UnpricedModelError(modelId);
+  return priceTokens(p, inTok, outTok);
+};
+
+/**
+ * Worst-case USD for ONE provider request: the whole input upper bound at the input price plus the
+ * output cap the request carries at the output price. A price-less id is refused, never estimated.
+ * Throws `SpendBudgetError` when that exceeds `remainingUsd` (equality is admitted).
+ */
+export function reserveDispatch(modelId: string, inputTokenUpperBound: number, remainingUsd: number): number {
+  const resolved = lookupModelAlias(modelId);
+  const p = getModelPricing(resolved);
+  if (!p) throw new UnpricedModelError(modelId);
+  // The prompt upper bound picks the tier, so a long prompt reserves at the long-context rates.
+  const reserveUsd = priceTokens(p, inputTokenUpperBound, modelMaxOutputTokens(resolved));
+  if (reserveUsd > remainingUsd) {
+    throw new SpendBudgetError(`dispatch to ${modelId} reserves $${reserveUsd.toFixed(6)}, above the $${Math.max(0, remainingUsd).toFixed(6)} left`);
+  }
+  return reserveUsd;
+}
+
+type DispatchContext = {
+  policy: DispatchPolicy;
+  /** The id the caller asked `model()` for; recorded on every dispatch row. */
+  requestedModel?: string;
+  meter?: SpendMeter;
+  /** Remaining dollars the runtime handed to this turn (`next({ maxCostUsd })`). */
+  maxCostUsd?: number;
+  inputTokenUpperBound: number;
+};
+
+/** Bytes bound tokens (>= 1 byte per token); framing allowance mirrors convexModel's. Used only for reservations. */
+export function requestInputTokenUpperBound(system: string, messages: AgentMessage[], tools: AgentTool[]): number {
+  const toolSchemas = tools.map((t) => {
+    try { return { name: t.name, description: t.description, parameters: z.toJSONSchema(t.schema as z.ZodType) }; }
+    catch { return { name: t.name, description: t.description, parameters: "x".repeat(2_048) }; }
+  });
+  const bytes = new TextEncoder().encode(JSON.stringify({ system, messages, tools: toolSchemas })).byteLength;
+  return bytes + 64 * (messages.length + tools.length + 2);
+}
+
+/**
+ * Run one provider request under the meter. Reserve BEFORE the request (so a request that would cross the
+ * cap is never issued), then settle to the priced usage. A request that throws, or answers without usage,
+ * keeps its full reservation: unknown usage is charged at the worst case. No meter = no change.
+ */
+/**
+ * The model string the PROVIDER answered with, read from the raw response body (`modelVersion` for Google,
+ * `model` for Anthropic / OpenAI-compatible). The AI SDK's `response.modelId` is not used: @ai-sdk/google fills it
+ * with the id that was REQUESTED, so it can never show Google serving a request under another model.
+ */
+export function providerEchoedModel(res: { response?: { body?: unknown } }): string | null {
+  const body = res.response?.body;
+  if (typeof body !== "object" || body === null) return null;
+  const { modelVersion, model: model_ } = body as { modelVersion?: unknown; model?: unknown };
+  const echoed = typeof modelVersion === "string" ? modelVersion : typeof model_ === "string" ? model_ : null;
+  return echoed && echoed.trim() ? echoed : null;
+}
+
+async function meteredDispatch<T extends { usage?: { inputTokens?: number; outputTokens?: number }; response?: { body?: unknown } }>(
+  ctx: DispatchContext,
+  modelId: string,
+  run: () => Promise<T>,
+  fallbackUsed = false,
+): Promise<T> {
+  const meter = ctx.meter;
+  if (!meter) return run();
+  // A refused reservation or an unpriced id is terminal for the job: nothing may dispatch after it, whatever
+  // path (retry, fallback, candidate loop) asks next.
+  if (meter.stoppedBy) {
+    throw new SpendBudgetError(`dispatch to ${modelId} refused: the meter already stopped (${meter.stoppedBy})`);
+  }
+  const remaining = Math.min(meter.maxUsd - meter.spentUsd, ctx.maxCostUsd ?? Number.POSITIVE_INFINITY);
+  let reserveUsd: number;
+  try {
+    reserveUsd = reserveDispatch(modelId, ctx.inputTokenUpperBound, remaining);
+  } catch (error) {
+    meter.stoppedBy = error instanceof UnpricedModelError ? "unpriced_model" : "spend_budget";
+    throw error;
+  }
+  meter.spentUsd += reserveUsd;
+  meter.requests += 1;
+  const record: DispatchRecord = {
+    requestedModel: ctx.requestedModel ?? modelId,
+    resolvedModel: modelId,
+    echoedModel: null,
+    usage: null,
+    costUsd: reserveUsd, // unknown usage is charged at the worst case
+    fallbackUsed,
+  };
+  if (meter.dispatches.length < MAX_DISPATCH_RECORDS) meter.dispatches.push(record);
+  else meter.droppedDispatches += 1;
+  const res = await run();
+  record.echoedModel = providerEchoedModel(res);
+  const input = res.usage?.inputTokens;
+  const output = res.usage?.outputTokens;
+  if (Number.isFinite(input) && Number.isFinite(output)) {
+    const settled = priceRequestStrict(modelId, input as number, output as number);
+    meter.spentUsd += settled - reserveUsd;
+    record.usage = { inputTokens: input as number, outputTokens: output as number };
+    record.costUsd = settled;
+  }
+  return res;
+}
+
 // Our AgentMessage[] → the AI SDK's message shape (kept loose; SDK part types are version-specific).
 type SdkToolSet = Record<string, any>;
 type GenerateTextResultAny = any;
 
 const NODEAGENT_PROVIDER_NEUTRAL_POLICY = "nodeagent_provider_neutral_free_first_v1" as const;
-const DEFAULT_NODEAGENT_GOOGLE_FALLBACK_MODEL = "gemini-3.5-flash";
+const DEFAULT_NODEAGENT_GOOGLE_FALLBACK_MODEL = DEFAULT_AGENT_MODEL;
 
 type ProviderNeutralBilling = {
   /** This describes route pricing, not the account's eventual invoice or free-tier entitlement. */
@@ -183,6 +398,7 @@ type ProviderNeutralRouteReceipt = ProviderRouteReceipt & {
 // honoring the deadline AbortSignal, plus an optional cross-model fallback. (async_reliability layer 2)
 const TRANSIENT_RE = /(\b429\b|\b5\d\d\b|rate.?limit|overloaded|temporar|timed?.?out|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|fetch failed|socket hang up|service unavailable)/i;
 export function isTransientError(error: unknown): boolean {
+  if (error instanceof SpendBudgetError) return false; // a refused reservation is a decision, not an outage: never retry it
   if (error instanceof Error && (error.name === "AbortError" || /\baborted\b/i.test(error.message))) return false; // deadline abort → never retry
   const m = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
   return TRANSIENT_RE.test(m);
@@ -199,7 +415,7 @@ function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
     signal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("aborted")); }, { once: true });
   });
 }
-async function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal, maxRetries = 3): Promise<T> {
+async function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal, maxRetries = DEFAULT_DISPATCH_POLICY.maxRetries): Promise<T> {
   let lastError: unknown;
   for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
     try { return await fn(); }
@@ -212,9 +428,14 @@ async function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal, maxRetri
   throw lastError;
 }
 /** Optional cross-model safety net after the primary path's retries exhaust (e.g. free-tier outage). */
-function fallbackModelFor(modelId: string): string | undefined {
+function fallbackModelFor(modelId: string, dispatch: DispatchContext): string | undefined {
+  if (!dispatch.policy.crossModelFallback) return undefined;
   const fb = process.env.AGENT_FALLBACK_MODEL?.trim();
-  return fb && resolveModelAlias(fb) !== modelId ? resolveModelAlias(fb) : undefined;
+  const resolved = fb ? resolveModelAlias(fb) : undefined;
+  if (!resolved || resolved === modelId) return undefined;
+  // Cost class is preserved (A.0.10): free -> paid needs an explicit allowPaidFallback and a meter to reserve against.
+  if (isFreeModelId(modelId) && !isFreeModelId(resolved) && !(dispatch.policy.allowPaidFallback === true && dispatch.meter)) return undefined;
+  return resolved;
 }
 
 async function generateAgentText(
@@ -228,6 +449,7 @@ async function generateAgentText(
   toolChoice?: AgentToolChoice,
   freeAutoMode?: OpenRouterFreeModelMode,
   qualityContext?: { messages: AgentMessage[]; tools: AgentTool[] },
+  dispatch: DispatchContext = { policy: DEFAULT_DISPATCH_POLICY, inputTokenUpperBound: 0 },
 ): Promise<{
   res: GenerateTextResultAny;
   resolvedModel: string;
@@ -245,28 +467,34 @@ async function generateAgentText(
       toolChoice,
       freeAutoMode,
       qualityContext,
+      dispatch,
     });
   }
   if (!isOpenRouterFreeAutoModel(modelId)) {
-    const call = async (id: string) => {
+    const call = async (id: string, fallbackUsed: boolean) => {
       const providerRoute = assertProviderRouteAllowed({ model: id, entrypoint, env: process.env });
       assertProviderEgressAllowed({ model: id, entrypoint, artifacts, env: process.env });
-      const res = await withRetry(() => generateText({
+      const res = await withRetry(() => meteredDispatch(dispatch, id, () => generateText({
         model: providerFor(id),
         system,
         messages,
-        tools: sdkTools,
+        tools: sdkToolsForModel(sdkTools, id, toolChoice),
         toolChoice: Object.keys(sdkTools).length ? sdkToolChoiceForModel(id, toolChoice) : undefined,
+        maxOutputTokens: modelMaxOutputTokens(id),
+        maxRetries: 0, // withRetry is the only retry layer: every physical request is one reserved attempt
+        ...claudeEffortProviderOptions(id), // explicit SPEC §1.3 effort: a vendor default change cannot move the lane
         abortSignal: signal,
-      }), signal);
+      }), fallbackUsed), signal, dispatch.policy.maxRetries);
       return { res, providerRoute };
     };
     try {
-      return { ...await call(modelId), resolvedModel: modelId };
+      return { ...await call(modelId, false), resolvedModel: modelId };
     } catch (error) {
-      const fb = fallbackModelFor(modelId);
+      // A refused reservation is the budget's decision, not an outage: no fallback model may be tried after it.
+      if (error instanceof SpendBudgetError) throw error;
+      const fb = fallbackModelFor(modelId, dispatch);
       if (!fb || signal?.aborted) throw error;
-      return { ...await call(fb), resolvedModel: fb }; // primary exhausted retries → cross-model safety net
+      return { ...await call(fb, true), resolvedModel: fb }; // primary exhausted retries → cross-model safety net
     }
   }
   hydrateOpenRouterFreeRouteHealth();
@@ -289,14 +517,16 @@ async function generateAgentText(
     execute: async (candidate, context) => {
       const providerRoute = assertProviderRouteAllowed({ model: candidate.id, entrypoint, env: process.env });
       assertProviderEgressAllowed({ model: candidate.id, entrypoint, artifacts, env: process.env });
-      const res = await withRetry(() => generateText({
+      const res = await withRetry(() => meteredDispatch(dispatch, candidate.id, () => generateText({
         model: openrouter().chat(candidate.id),
         system,
         messages,
-        tools: sdkTools,
+        tools: sdkToolsForModel(sdkTools, candidate.id, toolChoice),
         toolChoice: Object.keys(sdkTools).length ? sdkToolChoiceForModel(candidate.id, toolChoice) : undefined,
+        maxOutputTokens: modelMaxOutputTokens(candidate.id),
+        maxRetries: 0,
         abortSignal: context.signal,
-      }), context.signal, openRouterFreeCandidateRetries());
+      })), context.signal, Math.min(openRouterFreeCandidateRetries(), dispatch.policy.maxRetries));
       return { res, providerRoute };
     },
     assessResult: ({ res }) => assessAgentToolTurnQuality({
@@ -347,6 +577,7 @@ async function generateProviderNeutralAgentText(args: {
   toolChoice?: AgentToolChoice;
   freeAutoMode?: OpenRouterFreeModelMode;
   qualityContext?: { messages: AgentMessage[]; tools: AgentTool[] };
+  dispatch: DispatchContext;
 }): Promise<{
   res: GenerateTextResultAny;
   resolvedModel: string;
@@ -365,6 +596,7 @@ async function generateProviderNeutralAgentText(args: {
       args.toolChoice,
       args.freeAutoMode,
       args.qualityContext,
+      args.dispatch,
     );
     if (!primary.providerRoute) {
       throw new Error(`${NODEAGENT_FREE_AUTO_MODEL} primary route returned no provider receipt`);
@@ -380,6 +612,12 @@ async function generateProviderNeutralAgentText(args: {
   } catch (primaryError) {
     const unavailable = openRouterPrimaryUnavailable(primaryError);
     if (!unavailable || args.signal?.aborted) throw primaryError;
+    // The direct Google route is a cross-model fallback (free OpenRouter -> paid Gemini): a policy that forbids
+    // cross-model fallback forbids it, and a refused reservation is never recovered from. Cost class is preserved
+    // (A.0.10): the paid leg also needs an explicit allowPaidFallback and a meter to reserve against, exactly the
+    // guard `fallbackModelFor` applies to every other free -> paid fallback.
+    const paidLegAuthorized = args.dispatch.policy.allowPaidFallback === true && !!args.dispatch.meter;
+    if (primaryError instanceof SpendBudgetError || !args.dispatch.policy.crossModelFallback || !paidLegAuthorized) throw primaryError;
 
     const configuredKey = envValue("GOOGLE_GENERATIVE_AI_API_KEY");
     if (!configuredKey) {
@@ -412,14 +650,16 @@ async function generateProviderNeutralAgentText(args: {
     }
 
     try {
-      const res = await withRetry(() => generateText({
+      const res = await withRetry(() => meteredDispatch(args.dispatch, fallbackModel, () => generateText({
         model: google(fallbackModel),
         system: args.system,
         messages: args.messages,
         tools: args.sdkTools,
         toolChoice: Object.keys(args.sdkTools).length ? sdkToolChoiceForModel(fallbackModel, args.toolChoice) : undefined,
+        maxOutputTokens: modelMaxOutputTokens(fallbackModel),
+        maxRetries: 0,
         abortSignal: args.signal,
-      }), args.signal);
+      }), true), args.signal, args.dispatch.policy.maxRetries);
       return {
         res,
         resolvedModel: fallbackModel,
@@ -638,7 +878,8 @@ async function generatePromptText(modelId: string, prompt: string): Promise<Gene
   throw new Error(`openrouter/free-auto prompt failed for ${attempted.join(", ")}: ${shortProviderError(lastError)}`);
 }
 
-function openRouterFreeAutoLimit(): number {
+/** Candidates one `openrouter/free-auto` request fans out over (OPENROUTER_FREE_AUTO_LIMIT, default 8, max 20). */
+export function openRouterFreeAutoLimit(): number {
   const raw = Number(envValue("OPENROUTER_FREE_AUTO_LIMIT") ?? 8);
   return Number.isFinite(raw) ? Math.max(1, Math.min(20, raw)) : 8;
 }
@@ -699,8 +940,17 @@ function envValue(name: string): string | undefined {
   return value || undefined;
 }
 
+/** `strict: true` on every tool definition exactly when a forced tool choice was downgraded to `auto` (SPEC §1.3). */
+function sdkToolsForModel(sdkTools: SdkToolSet, modelId: string, requested?: AgentToolChoice): SdkToolSet {
+  if (!needsStrictTools(modelId, requested)) return sdkTools;
+  return Object.fromEntries(Object.entries(sdkTools).map(([name, t]) => [name, { ...t, strict: true }]));
+}
+
 function sdkToolChoiceForModel(modelId: string, requested?: AgentToolChoice): AgentToolChoice {
   const choice = requested ?? "auto";
+  // Claude 5.5 Sonnet/Opus 400 on a forced tool_choice (SPEC §1.3). `auto` is the transport hint; the harness
+  // validates required writes after the turn (convexModel.ts assessConvexTurnQuality / runtime required-tool check).
+  if (choice === "required" && forbidsForcedToolChoice(modelId)) return "auto";
   if (choice === "required" && getProviderForModel(modelId) === "openrouter" && /^(?:qwen\/qwen3(?:[.-]|$)|qwen3(?:[.-]|$))/i.test(modelId)) {
     return "auto";
   }
diff --git a/src/nodeagent/models/convexModel.ts b/src/nodeagent/models/convexModel.ts
index 5d9f485a..fb1099b3 100644
--- a/src/nodeagent/models/convexModel.ts
+++ b/src/nodeagent/models/convexModel.ts
@@ -8,7 +8,8 @@
  */
 
 import type { AgentMessage, AgentModel, AgentModelRouteState, AgentStep, AgentTool, AgentToolChoice, TokenUsage, ToolCall } from "../core/types";
-import { getModelPricing, getProviderForModel, modelFallbackChains, modelPricing, resolveModelAlias } from "./modelCatalog";
+import { forbidsForcedToolChoice, getModelPricing, getProviderForModel, isFreeModelId, lookupModelAlias, modelFallbackChains, modelPricing, needsStrictTools, priceAggregateTokens, priceTokens, ratesForPrompt, resolveModelAlias } from "./modelCatalog";
+import { modelMaxOutputTokens } from "./outputTokens";
 import {
   isOpenRouterFreeAutoModel,
   openRouterFreeCandidateTimeoutMs,
@@ -109,7 +110,6 @@ type GeminiResponse = {
 
 const OPENROUTER_REFERER = "https://noderoom.local";
 const OPENROUTER_TITLE = "NodeRoom benchmark";
-const DEFAULT_MAX_OUTPUT_TOKENS = 8_192;
 const UNKNOWN_MODEL_RESERVE_INPUT_PER_1M = Object.values(modelPricing)
   .reduce((highest, pricing) => Math.max(highest, pricing.inputPer1M), 1);
 const UNKNOWN_MODEL_RESERVE_OUTPUT_PER_1M = Object.values(modelPricing)
@@ -121,8 +121,19 @@ export type ConvexModelOptions = {
   freeAutoMode?: OpenRouterFreeModelMode;
   /** Ordered, already-authorized fallback routes. Pass [] to keep an explicit model exact. */
   fallbackModelIds?: string[];
+  /**
+   * SPEC A.0.10: a free primary never falls back to a paid route unless the caller sets this AND `next()` is handed a
+   * finite `maxCostUsd` (the failover controller reserves each candidate's estimate against it before dispatch).
+   */
+  allowPaidFallback?: boolean;
   /** Checkpointed concrete-route preference/cooldowns from a prior durable slice. */
   routeState?: AgentModelRouteState;
+  /**
+   * Eval and smoke scripts only (SPEC-v9 D1: operator overrides stay pass-through; same contract as `ModelAdapterOptions`
+   * in adapter.ts). The id was typed by an operator: the alias table still applies, but an id the catalog does not know
+   * goes to the provider as written instead of throwing. Server code never sets this; it stays fail-closed (A.0.10).
+   */
+  operatorSelected?: boolean;
 };
 
 type ConcreteRouteState = {
@@ -188,13 +199,16 @@ function geminiUsage(usage?: GeminiResponse["usageMetadata"]): TokenUsage | unde
 }
 
 export function convexModel(modelId: string, options: ConvexModelOptions = {}): AgentModel {
-  const aliasModelId = resolveModelAlias(modelId);
+  const aliasModelId = options.operatorSelected ? lookupModelAlias(modelId) : resolveModelAlias(modelId);
   const entrypoint = options.entrypoint ?? "system";
   const freeAutoMode = options.freeAutoMode;
   // Fallbacks must be authorized by the caller that owns artifact-aware egress context.
   // Non-durable/direct call sites remain exact even when deployment fallback env vars exist.
   const fallbackModelIds = normalizeFallbackModelIds(aliasModelId, options.fallbackModelIds ?? []);
-  const concreteRouteState = hydrateConcreteRouteState(aliasModelId, fallbackModelIds, options.routeState);
+  // Cost class is preserved (A.0.10): without allowPaidFallback and a reservation budget, only same-class routes stay.
+  const sameClassFallbackIds = isFreeModelId(aliasModelId) ? fallbackModelIds.filter(isFreeModelId) : fallbackModelIds;
+  const authorizedFallbackIds = options.allowPaidFallback === true ? fallbackModelIds : sameClassFallbackIds;
+  const concreteRouteState = hydrateConcreteRouteState(aliasModelId, authorizedFallbackIds, options.routeState);
   let resolvedModelId = aliasModelId;
   return {
     get name() {
@@ -207,33 +221,41 @@ export function convexModel(modelId: string, options: ConvexModelOptions = {}):
       // Gateway PII firewall — redact PII/secrets from the system + user content before the prompt leaves.
       const safeSystem = redactPII(system).text;
       const safeMessages = messages.map((m) => (m.role === "user" && m.content ? { ...m, content: redactPII(m.content).text } : m));
-      const { step, resolvedModel } = await generateConvexAgentStep(aliasModelId, safeSystem, safeMessages, tools, entrypoint, signal, onTextDelta, toolChoice, freeAutoMode, fallbackModelIds, concreteRouteState, maxCostUsd);
+      const { step, resolvedModel } = await generateConvexAgentStep(aliasModelId, safeSystem, safeMessages, tools, entrypoint, signal, onTextDelta, toolChoice, freeAutoMode, Number.isFinite(maxCostUsd) ? authorizedFallbackIds : sameClassFallbackIds, concreteRouteState, maxCostUsd);
       resolvedModelId = resolvedModel;
       return step;
     },
   };
 }
 
+/** Cost of usage SUMMED over several requests: base-tier rates (a tier belongs to one request's prompt). */
 export function convexPriceRun(modelId: string, inTok: number, outTok: number): number {
-  const pricing = getModelPricing(resolveModelAlias(modelId));
-  return (inTok * (pricing?.inputPer1M ?? 1) + outTok * (pricing?.outputPer1M ?? 5)) / 1_000_000;
+  const pricing = getModelPricing(lookupModelAlias(modelId));
+  return pricing ? priceAggregateTokens(pricing, inTok, outTok) : (inTok * 1 + outTok * 5) / 1_000_000;
+}
+
+/** Cost of ONE provider request (`inTok` is that request's prompt), tier-aware. This is the `priceStep` price. */
+export function convexPriceRequest(modelId: string, inTok: number, outTok: number): number {
+  const pricing = getModelPricing(lookupModelAlias(modelId));
+  return pricing ? priceTokens(pricing, inTok, outTok) : (inTok * 1 + outTok * 5) / 1_000_000;
 }
 
 function exactConvexUsageCost(
   modelId: string,
   usage: Pick<TokenUsage, "inputTokens" | "outputTokens" | "cachedInputTokens" | "cacheCreationInputTokens">,
 ): number | undefined {
-  const pricing = getModelPricing(resolveModelAlias(modelId));
+  const pricing = getModelPricing(lookupModelAlias(modelId));
   if (!pricing) return undefined;
   // The catalog does not yet carry provider cache-write rates. Never label a
   // cache-creation turn exact by silently charging it at the read/input rate.
   if ((usage.cacheCreationInputTokens ?? 0) > 0) return undefined;
   const cachedInputTokens = Math.min(usage.inputTokens, Math.max(0, usage.cachedInputTokens ?? 0));
   const uncachedInputTokens = Math.max(0, usage.inputTokens - cachedInputTokens);
+  const rates = ratesForPrompt(pricing, usage.inputTokens); // long prompts bill at the long-context tier
   return (
-    uncachedInputTokens * pricing.inputPer1M
-    + cachedInputTokens * (pricing.cachedInputPer1M ?? pricing.inputPer1M)
-    + usage.outputTokens * pricing.outputPer1M
+    uncachedInputTokens * rates.inputPer1M
+    + cachedInputTokens * (rates.cachedInputPer1M ?? rates.inputPer1M)
+    + usage.outputTokens * rates.outputPer1M
   ) / 1_000_000;
 }
 
@@ -261,17 +283,18 @@ function convexAttemptCostReservationUsd(
   inputTokenUpperBound: number,
   maxCostUsd?: number,
 ): number {
-  const pricing = getModelPricing(resolveModelAlias(modelId));
+  const pricing = getModelPricing(lookupModelAlias(modelId));
   if (!pricing && Number.isFinite(maxCostUsd)) {
     const budget = Math.max(0, maxCostUsd ?? 0);
     return budget + Math.max(1e-9, Math.max(1, budget) * 1e-9);
   }
-  const inputPer1M = pricing?.inputPer1M ?? UNKNOWN_MODEL_RESERVE_INPUT_PER_1M;
-  const outputPer1M = pricing?.outputPer1M ?? UNKNOWN_MODEL_RESERVE_OUTPUT_PER_1M;
+  const rates = pricing ? ratesForPrompt(pricing, inputTokenUpperBound) : undefined;
+  const inputPer1M = rates?.inputPer1M ?? UNKNOWN_MODEL_RESERVE_INPUT_PER_1M;
+  const outputPer1M = rates?.outputPer1M ?? UNKNOWN_MODEL_RESERVE_OUTPUT_PER_1M;
   if (inputPer1M === 0 && outputPer1M === 0) return 0;
   return (
     inputTokenUpperBound * inputPer1M
-    + modelMaxOutputTokens() * outputPer1M
+    + modelMaxOutputTokens(modelId) * outputPer1M
   ) / 1_000_000;
 }
 
@@ -751,7 +774,7 @@ async function providerStep(
       onProviderRequest,
     });
   }
-  if (provider === "anthropic") return anthropicStep(modelId, system, messages, tools, signal, onProviderRequest);
+  if (provider === "anthropic") return anthropicStep(modelId, system, messages, tools, signal, onProviderRequest, toolChoice);
   if (provider === "gemini") {
     if (onTextDelta) {
       const deltas: string[] = [];
@@ -838,9 +861,9 @@ async function openAiCompatibleBlockingStep(args: {
   const res = await postJson<OpenAiChatResponse>(args.endpoint, {
     model: args.modelId,
     messages: [{ role: "system", content: args.system }, ...toOpenAiMessages(args.messages)],
-    tools: args.tools.length ? args.tools.map(openAiTool) : undefined,
+    tools: args.tools.length ? args.tools.map((t) => openAiTool(t, openAiCompatibleStrictTools(args.modelId, args.endpoint, args.toolChoice))) : undefined,
     tool_choice: args.tools.length ? openAiCompatibleToolChoice(args.modelId, args.endpoint, args.toolChoice) : undefined,
-    ...openAiCompatibleTokenLimitParam(args.modelId, args.endpoint, modelMaxOutputTokens()),
+    ...openAiCompatibleTokenLimitParam(args.modelId, args.endpoint, modelMaxOutputTokens(args.modelId)),
     ...openAiCompatibleProviderOptions(args.modelId, args.endpoint),
   }, {
     ...args.headers,
@@ -888,9 +911,9 @@ async function openAiCompatibleStreamStep(args: {
       stream: true,
       stream_options: { include_usage: true },
       messages: [{ role: "system", content: args.system }, ...toOpenAiMessages(args.messages)],
-      tools: args.tools.length ? args.tools.map(openAiTool) : undefined,
+      tools: args.tools.length ? args.tools.map((t) => openAiTool(t, openAiCompatibleStrictTools(args.modelId, args.endpoint, args.toolChoice))) : undefined,
       tool_choice: args.tools.length ? openAiCompatibleToolChoice(args.modelId, args.endpoint, args.toolChoice) : undefined,
-      ...openAiCompatibleTokenLimitParam(args.modelId, args.endpoint, modelMaxOutputTokens()),
+      ...openAiCompatibleTokenLimitParam(args.modelId, args.endpoint, modelMaxOutputTokens(args.modelId)),
       ...openAiCompatibleProviderOptions(args.modelId, args.endpoint),
     })),
     signal: args.signal,
@@ -956,13 +979,15 @@ async function anthropicStep(
   tools: AgentTool[],
   signal?: AbortSignal,
   onProviderRequest?: () => void,
+  toolChoice?: AgentToolChoice,
 ) {
+  const strict = needsStrictTools(modelId, toolChoice);
   const res = await postJson<AnthropicResponse>("https://api.anthropic.com/v1/messages", {
     model: modelId,
-    max_tokens: modelMaxOutputTokens(),
+    max_tokens: modelMaxOutputTokens(modelId),
     system,
     messages: toAnthropicMessages(messages),
-    tools: tools.length ? tools.map(anthropicTool) : undefined,
+    tools: tools.length ? tools.map((t) => anthropicTool(t, strict)) : undefined,
   }, {
     "x-api-key": requireEnv("ANTHROPIC_API_KEY"),
     "anthropic-version": "2023-06-01",
@@ -1002,7 +1027,7 @@ async function geminiStep(
     systemInstruction: { parts: [{ text: system }] },
     contents: toGeminiContents(messages),
     tools: tools.length ? [{ functionDeclarations: tools.map(geminiTool) }] : undefined,
-    generationConfig: { maxOutputTokens: modelMaxOutputTokens() },
+    generationConfig: { maxOutputTokens: modelMaxOutputTokens(modelId) },
   }, {}, signal, onProviderRequest);
 
   const parts = res.candidates?.[0]?.content?.parts ?? [];
@@ -1045,7 +1070,7 @@ async function geminiStreamStep(
       systemInstruction: { parts: [{ text: system }] },
       contents: toGeminiContents(messages),
       tools: tools.length ? [{ functionDeclarations: tools.map(geminiTool) }] : undefined,
-      generationConfig: { maxOutputTokens: modelMaxOutputTokens() },
+      generationConfig: { maxOutputTokens: modelMaxOutputTokens(modelId) },
     })),
     signal,
   });
@@ -1166,22 +1191,24 @@ function toGeminiContents(messages: AgentMessage[]) {
   });
 }
 
-function openAiTool(tool: AgentTool) {
+function openAiTool(tool: AgentTool, strict = false) {
   return {
     type: "function" as const,
     function: {
       name: tool.name,
       description: tool.description,
       parameters: toolParameters(tool.name),
+      ...(strict ? { strict: true } : {}),
     },
   };
 }
 
-function anthropicTool(tool: AgentTool) {
+function anthropicTool(tool: AgentTool, strict = false) {
   return {
     name: tool.name,
     description: tool.description,
     input_schema: toolParameters(tool.name),
+    ...(strict ? { strict: true } : {}),
   };
 }
 
@@ -1802,16 +1829,6 @@ function nebiusBaseUrl(): string {
   return envValue("NEBIUS_BASE_URL") ?? "https://api.tokenfactory.nebius.com/v1";
 }
 
-function modelMaxOutputTokens(): number {
-  return envNumber("AGENT_MODEL_MAX_OUTPUT_TOKENS", DEFAULT_MAX_OUTPUT_TOKENS, 1_024, 32_000);
-}
-
-function envNumber(name: string, fallback: number, min: number, max: number): number {
-  const raw = Number(envValue(name) ?? fallback);
-  if (!Number.isFinite(raw)) return fallback;
-  return Math.max(min, Math.min(max, raw));
-}
-
 function openAiCompatibleProviderOptions(modelId: string, endpoint: string): JsonObject {
   // GLM/Qwen hybrid-thinking models served through OpenRouter/vLLM can spend the entire
   // output cap on hidden thinking, and Qwen rejects required tool_choice while thinking.
@@ -1829,9 +1846,19 @@ function openAiCompatibleToolChoice(modelId: string, endpoint: string, requested
   if (choice === "required" && isOpenRouterEndpoint(endpoint) && isOpenRouterQwenHybridThinkingModel(modelId)) {
     return "auto";
   }
+  // Claude 5.5 Sonnet/Opus (and Fable 5.1) answer a forced tool_choice with a 400 (SPEC §1.3). Whether
+  // OpenRouter rewrites it is unobserved, so send `auto`; the harness validates required writes after the turn.
+  if (choice === "required" && isOpenRouterEndpoint(endpoint) && forbidsForcedToolChoice(modelId)) {
+    return "auto";
+  }
   return choice;
 }
 
+/** Strict tool definitions accompany exactly the `required` -> `auto` downgrade above (SPEC §1.3). */
+function openAiCompatibleStrictTools(modelId: string, endpoint: string, requested?: AgentToolChoice): boolean {
+  return isOpenRouterEndpoint(endpoint) && needsStrictTools(modelId, requested);
+}
+
 function isOpenRouterEndpoint(endpoint: string): boolean {
   try {
     return new URL(endpoint).hostname.includes("openrouter.ai");
@@ -1866,7 +1893,8 @@ export function configuredConvexModelFallbacks(
 }
 
 function normalizeFallbackModelIds(modelId: string, values: readonly string[]): string[] {
-  const primary = resolveModelAlias(modelId);
+  // The primary was resolved (or operator-selected) by the caller; only the fallback values are validated here.
+  const primary = lookupModelAlias(modelId);
   const seen = new Set([primary]);
   const result: string[] = [];
   for (const value of values) {
diff --git a/src/nodeagent/models/modelCatalog.ts b/src/nodeagent/models/modelCatalog.ts
index fc2362ee..9ec86afd 100644
--- a/src/nodeagent/models/modelCatalog.ts
+++ b/src/nodeagent/models/modelCatalog.ts
@@ -13,18 +13,15 @@
  * - gpt-5.4-mini: Efficient reasoning
  * - gpt-5.4-nano: Ultra-efficient
  *
- * Anthropic (current + compatibility lanes):
- * - claude-opus-4.7: latest flagship
- * - claude-sonnet-4.6: latest balanced lane
- * - claude-haiku-4.5: latest fast lane
+ * Anthropic (5.5 lanes first; 4.x kept as compatibility lanes for persisted rooms):
+ * - claude-opus-5-5 / claude-sonnet-5-5 / claude-haiku-5-5: current flagship / balanced / fast
+ * - claude-opus-4.7 / claude-sonnet-4.6 / claude-haiku-4.5: compatibility lanes
  *
- * Google (6 models):
- * - gemini-3.1-pro-preview: latest flagship preview
- * - gemini-3-flash-preview: fast preview lane
- * - gemini-3.1-flash-lite-preview: low-cost preview lane
- * - gemini-2.5-pro: Stable flagship (1M context)
- * - gemini-2.5-flash: stable efficient lane
- * - gemini-2.5-flash-lite: ultra-efficient stable lane
+ * Google (live lanes; the 2026-10 refresh, SPEC Part A §A.2.9):
+ * - gemini-3.1-pro-preview: the one Pro
+ * - gemini-3.8-flash: GA Flash (DEFAULT_AGENT_MODEL)
+ * - gemini-3.5-flash-lite: low-cost lane
+ * - gemini-3-flash-preview / gemini-3.1-flash-lite-preview / gemini-2.5-*: pricing rows kept for persisted rooms only
  *
  * For model resolution logic, see: convex/domains/agents/mcp_tools/models/
  */
@@ -33,7 +30,8 @@
 // TYPE DEFINITIONS
 // ═══════════════════════════════════════════════════════════════════════════
 
-import { OPENROUTER_FREE_AUTO_MODEL, OPENROUTER_FREE_META_MODEL, freeOpenRouterPricing } from "./openRouterFreeModels";
+import { OPENROUTER_FREE_AUTO_MODEL, OPENROUTER_FREE_META_MODEL, OPENROUTER_KNOWN_FREE_IDS, freeOpenRouterPricing } from "./openRouterFreeModels";
+import { DEFAULT_AGENT_MODEL } from "../../../convex/modelDefaults";
 
 /** Provider-neutral, free-first NodeAgent route. Concrete providers are resolved by the adapter. */
 export const NODEAGENT_FREE_AUTO_MODEL = "nodeagent/free-auto";
@@ -67,8 +65,45 @@ export interface ModelPricing {
   outputPer1M: number;   // Cost per 1M output tokens
   cachedInputPer1M?: number; // Cached input discount (if supported)
   contextWindow: number; // Max context window
+  /** Date the vendor list price was read (A.0.6 agreement test). Present on the 2026-10 refresh rows. */
+  pricingAsOf?: string;
+  /**
+   * Higher tier the vendor applies to the WHOLE request once its prompt exceeds `aboveInputTokens`
+   * (SPEC §1.3: claude-haiku-5-5 is $0.10/$0.50 up to 100K prompt tokens, $0.50/$2.50 above). The row's own
+   * rates are the lower tier. `cachedInputPer1M` is omitted when the vendor page does not list it; callers then
+   * charge cached tokens at the tier's input rate rather than guess (Haiku 5.5 lists both: $0.01 and $0.05).
+   */
+  longContext?: { aboveInputTokens: number; inputPer1M: number; outputPer1M: number; cachedInputPer1M?: number };
 }
 
+/** The rates a request with `inputTokens` prompt tokens is billed at: the row's own, or its long-context tier. */
+export function ratesForPrompt(pricing: ModelPricing, inputTokens: number): Pick<ModelPricing, "inputPer1M" | "outputPer1M" | "cachedInputPer1M"> {
+  const tier = pricing.longContext;
+  return tier && inputTokens > tier.aboveInputTokens ? tier : pricing;
+}
+
+/**
+ * USD for ONE provider request, tier-aware (uncached input). The tier is chosen from this request's own prompt size,
+ * so it is only correct when `inputTokens` is a single request's prompt. Reservations, settlement and per-step
+ * pricing (`priceStep`) route through this; usage summed over several requests must NOT (see `priceAggregateTokens`).
+ */
+export function priceTokens(pricing: ModelPricing, inputTokens: number, outputTokens: number): number {
+  const rates = ratesForPrompt(pricing, inputTokens);
+  return (inputTokens * rates.inputPer1M + outputTokens * rates.outputPer1M) / 1_000_000;
+}
+
+/**
+ * USD for usage summed over an unknown number of requests, at the row's own (base-tier) rates. A sum of 60K + 60K
+ * prompts is not one 120K prompt, so no tier is guessed from the total; this is a floor for runs that actually
+ * crossed the long-context tier. Prefer the sum of per-request settled costs (`usage.costUsd`, meter dispatches)
+ * whenever the caller has them.
+ */
+export function priceAggregateTokens(pricing: ModelPricing, inputTokens: number, outputTokens: number): number {
+  return (inputTokens * pricing.inputPer1M + outputTokens * pricing.outputPer1M) / 1_000_000;
+}
+
+const HAIKU_5_5_LONG_CONTEXT = { aboveInputTokens: 100_000, inputPer1M: 0.50, outputPer1M: 2.50, cachedInputPer1M: 0.05 }; // vendor "Cache read $0.01 / $0.05" (frontier.json)
+
 export const modelPricing: Record<string, ModelPricing> = {
   // OpenAI - GPT-5.4 family (official docs, April 2026)
   "gpt-5.4": { inputPer1M: 2.50, outputPer1M: 15.00, cachedInputPer1M: 0.25, contextWindow: 1050000 },
@@ -97,10 +132,32 @@ export const modelPricing: Record<string, ModelPricing> = {
   "claude-haiku-4-5": { inputPer1M: 1.00, outputPer1M: 5.00, cachedInputPer1M: 0.10, contextWindow: 200000 },
   "claude-sonnet-4-6": { inputPer1M: 3.00, outputPer1M: 15.00, cachedInputPer1M: 0.30, contextWindow: 1000000 },
   "claude-opus-4-8": { inputPer1M: 5.00, outputPer1M: 25.00, cachedInputPer1M: 0.50, contextWindow: 1000000 },
+  // Retired (kept for persisted rows): the dotted display ids alias to these, as the old regex rewrite did, so they price under either spelling.
+  // Prices are origin/main's own "claude-opus-4.1" / "claude-haiku-3.5" rows, whose block header reads "official docs, April 2026" (A.0.6: dated, source cited).
+  "claude-opus-4-1": { inputPer1M: 15.00, outputPer1M: 75.00, cachedInputPer1M: 1.50, contextWindow: 200000, pricingAsOf: "2026-04" },
+  "claude-haiku-3-5": { inputPer1M: 0.80, outputPer1M: 4.00, cachedInputPer1M: 0.08, contextWindow: 200000, pricingAsOf: "2026-04" },
   // gemini-3.1-flash-lite-preview was shut down → the GA id:
   "gemini-3.1-flash-lite": { inputPer1M: 0.25, outputPer1M: 1.50, contextWindow: 1000000 },
   "gemini-3.5-flash": { inputPer1M: 1.50, outputPer1M: 9.00, contextWindow: 1000000 }, // latest, most-intelligent Flash
   "gpt-5.5": { inputPer1M: 5.00, outputPer1M: 30.00, contextWindow: 400000 }, // OpenAI flagship (newer than 5.4)
+  // ── 2026-10 model refresh (SPEC Part A §A.2.9; vendor list prices read 2026-10-10, frontier.json) ──
+  // claude-haiku-5-5 is TIERED: the row is the <=100K tier; `longContext` is the $0.50/$2.50 tier above 100K prompt tokens.
+  "claude-haiku-5-5": { inputPer1M: 0.10, outputPer1M: 0.50, cachedInputPer1M: 0.01, contextWindow: 1000000, pricingAsOf: "2026-10-10", longContext: HAIKU_5_5_LONG_CONTEXT },
+  "claude-sonnet-5-5": { inputPer1M: 2.00, outputPer1M: 10.00, cachedInputPer1M: 0.10, contextWindow: 1000000, pricingAsOf: "2026-10-10" },
+  "claude-opus-5-5": { inputPer1M: 4.00, outputPer1M: 20.00, cachedInputPer1M: 0.20, contextWindow: 1000000, pricingAsOf: "2026-10-10" },
+  // OpenRouter transport of the same models (slug form, A.0.5); same list price.
+  "anthropic/claude-haiku-5.5": { inputPer1M: 0.10, outputPer1M: 0.50, cachedInputPer1M: 0.01, contextWindow: 1000000, pricingAsOf: "2026-10-10", longContext: HAIKU_5_5_LONG_CONTEXT },
+  "anthropic/claude-sonnet-5.5": { inputPer1M: 2.00, outputPer1M: 10.00, cachedInputPer1M: 0.10, contextWindow: 1000000, pricingAsOf: "2026-10-10" },
+  "anthropic/claude-opus-5.5": { inputPer1M: 4.00, outputPer1M: 20.00, cachedInputPer1M: 0.20, contextWindow: 1000000, pricingAsOf: "2026-10-10" },
+  // Exact id behind the claude-opus-4.7 display id (it used to be rewritten to 4-8; see modelAliases). frontier.json lists
+  // only "$5 in / $25 out" for it, so no cached rate is stated (ModelPricing: omitted when the vendor page does not list it).
+  "claude-opus-4-7": { inputPer1M: 5.00, outputPer1M: 25.00, contextWindow: 1000000, pricingAsOf: "2026-10-10" },
+  // Gemini Flash intro price: $0.75/$3.75 through 2026-12-31, then $1.50/$7.50 from 2027-01-01 (re-price then).
+  "gemini-3.8-flash": { inputPer1M: 0.75, outputPer1M: 3.75, cachedInputPer1M: 0.075, contextWindow: 1048576, pricingAsOf: "2026-10-10" },
+  // Ladder receipt baseline (3.5 is served as 3.6). contextWindow: frontier.json marks the 3.6 context UNVERIFIED; the figure is
+  // context_length 1048576 for google/gemini-3.6-flash on the public OpenRouter list (GET /api/v1/models, read 2026-10-16).
+  "gemini-3.6-flash": { inputPer1M: 0.75, outputPer1M: 3.75, contextWindow: 1048576, pricingAsOf: "2026-10-10" },
+  "gemini-3.5-flash-lite": { inputPer1M: 0.30, outputPer1M: 2.50, cachedInputPer1M: 0.03, contextWindow: 1048576, pricingAsOf: "2026-10-10" },
   // OpenRouter FREE tier (tool-calling) — needs OPENROUTER_API_KEY to actually run:
   [OPENROUTER_FREE_AUTO_MODEL]: freeOpenRouterPricing(1_000_000),
   [OPENROUTER_FREE_META_MODEL]: freeOpenRouterPricing(200_000),
@@ -212,7 +269,7 @@ export const tierLimits: Record<UserTier, TierLimits> = {
     tokensPerDay: 10_000,
     maxTokensPerRequest: 2_000,
     allowedProviders: ["openai", "anthropic", "gemini"],
-    allowedModels: ["gpt-5.4-nano", "claude-haiku-4.5", "gemini-3.1-flash-lite-preview"],
+    allowedModels: ["gpt-5.4-nano", "claude-haiku-4.5", "gemini-3.1-flash-lite-preview", "claude-haiku-5-5", "gemini-3.5-flash-lite"],
     costLimitPerDay: 0.01,
   },
   free: {
@@ -220,7 +277,7 @@ export const tierLimits: Record<UserTier, TierLimits> = {
     tokensPerDay: 100_000,
     maxTokensPerRequest: 8_000,
     allowedProviders: ["openai", "anthropic", "gemini"],
-    allowedModels: ["gpt-5.4-mini", "gpt-5.4-nano", "claude-haiku-4.5", "gemini-2.5-flash"],
+    allowedModels: ["gpt-5.4-mini", "gpt-5.4-nano", "claude-haiku-4.5", "gemini-2.5-flash", "claude-haiku-5-5", "gemini-3.5-flash-lite"],
     costLimitPerDay: 0.50,
   },
   pro: {
@@ -269,34 +326,36 @@ export const llmModelCatalog: ModelCatalog = {
     coding: ["gpt-5.4", "gpt-5.4-mini"],
   },
   anthropic: {
-    chat: ["claude-haiku-4.5", "claude-sonnet-4.6"],
-    agent: ["claude-haiku-4.5", "claude-sonnet-4.6", "claude-opus-4.7"],
-    router: ["claude-haiku-4.5"],
-    judge: ["claude-sonnet-4.6", "claude-opus-4.7"],
-    analysis: ["claude-sonnet-4.6", "claude-opus-4.7"],
-    deepResearch: ["claude-sonnet-4.6", "claude-opus-4.7"],
-    vision: ["claude-sonnet-4.6", "claude-opus-4.7"],
-    fileSearch: ["claude-haiku-4.5"],
-    voice: ["claude-haiku-4.5"],
-    coding: ["claude-sonnet-4.6", "claude-opus-4.7"],
+    // 5.5 ids first (add-only; the 4.x ids stay valid for persisted rooms).
+    chat: ["claude-haiku-5-5", "claude-sonnet-5-5", "claude-haiku-4.5", "claude-sonnet-4.6"],
+    agent: ["claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5", "claude-haiku-4.5", "claude-sonnet-4.6", "claude-opus-4.7"],
+    router: ["claude-haiku-5-5", "claude-haiku-4.5"],
+    judge: ["claude-sonnet-5-5", "claude-opus-5-5", "claude-sonnet-4.6", "claude-opus-4.7"],
+    analysis: ["claude-sonnet-5-5", "claude-opus-5-5", "claude-sonnet-4.6", "claude-opus-4.7"],
+    deepResearch: ["claude-sonnet-5-5", "claude-opus-5-5", "claude-sonnet-4.6", "claude-opus-4.7"],
+    vision: ["claude-sonnet-5-5", "claude-opus-5-5", "claude-sonnet-4.6", "claude-opus-4.7"],
+    fileSearch: ["claude-haiku-5-5", "claude-haiku-4.5"],
+    voice: ["claude-haiku-5-5", "claude-haiku-4.5"],
+    coding: ["claude-sonnet-5-5", "claude-opus-5-5", "claude-sonnet-4.6", "claude-opus-4.7"],
   },
   gemini: {
-    // Gemini 3 (preview) → 2.5 (stable) → 2.0 (deprecated March 31 2026).
-    // Callers can still override explicitly with any model ID.
-    chat: ["gemini-3-flash-preview", "gemini-3.1-flash-lite-preview", "gemini-2.5-flash"],
-    agent: ["gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro"],
-    router: ["gemini-3.1-flash-lite-preview", "gemini-2.5-flash-lite"],
-    judge: ["gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro"],
-    analysis: ["gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro"],
+    // GA Flash (3.8) + Flash-Lite (3.5) + the one Pro (3.1 preview). gemini-3.1-flash-lite-preview was shut
+    // down 2026-05-25; gemini-2.5-* is prior-users-only (OpenRouter expiry 2026-10-20); gemini-3-flash-preview
+    // is deprecated. Their pricing rows stay for persisted rooms. Callers can still override with any id.
+    chat: ["gemini-3.8-flash", "gemini-3.5-flash-lite"],
+    agent: ["gemini-3.1-pro-preview", "gemini-3.8-flash"],
+    router: ["gemini-3.5-flash-lite"],
+    judge: ["gemini-3.1-pro-preview", "gemini-3.8-flash"],
+    analysis: ["gemini-3.1-pro-preview", "gemini-3.8-flash"],
     deepResearch: [
       "deep-research-preview-04-2026",
       "deep-research-max-preview-04-2026",
       "deep-research-pro-preview-12-2025",
     ],
-    vision: ["gemini-3-flash-preview", "gemini-3.1-pro-preview", "gemini-2.5-pro"],
-    fileSearch: ["gemini-3.1-flash-lite-preview", "gemini-2.5-flash-lite"],
-    voice: ["gemini-3.1-flash-lite-preview", "gemini-2.5-flash-lite"],
-    coding: ["gemini-3.1-pro-preview", "gemini-3-flash-preview", "gemini-2.5-pro"],
+    vision: ["gemini-3.8-flash", "gemini-3.1-pro-preview"],
+    fileSearch: ["gemini-3.5-flash-lite"],
+    voice: ["gemini-3.5-flash-lite"],
+    coding: ["gemini-3.1-pro-preview", "gemini-3.8-flash"],
   },
   openrouter: {
     // Kimi K3 (1M ctx) leads the agentic lanes; z-ai/glm-5.2 demoted to fallback so no
@@ -391,7 +450,7 @@ export function getAvailableModels(task: LlmTask, provider: LlmProvider = "openr
  */
 export function isValidModel(modelName: string, provider: LlmProvider): boolean {
   const allModels = Object.values(llmModelCatalog[provider] ?? {}).flat();
-  const resolved = resolveModelAlias(modelName);
+  const resolved = lookupModelAlias(modelName);
   return allModels.includes(modelName) || allModels.includes(resolved);
 }
 
@@ -415,11 +474,9 @@ export function calculateRequestCost(
     return (inputTokens * 0.15 + outputTokens * 0.60) / 1_000_000;
   }
 
-  const inputRate = useCachedInput && pricing.cachedInputPer1M 
-    ? pricing.cachedInputPer1M 
-    : pricing.inputPer1M;
-
-  return (inputTokens * inputRate + outputTokens * pricing.outputPer1M) / 1_000_000;
+  const rates = ratesForPrompt(pricing, inputTokens);
+  const inputRate = useCachedInput && rates.cachedInputPer1M ? rates.cachedInputPer1M : rates.inputPer1M;
+  return (inputTokens * inputRate + outputTokens * rates.outputPer1M) / 1_000_000;
 }
 
 /**
@@ -612,14 +669,26 @@ export const modelAliases: Record<string, string> = {
   "claude": "claude-sonnet-4.6",
   "claude-4": "claude-sonnet-4.6",
   "claude-sonnet": "claude-sonnet-4.6",
-  "claude-opus": "claude-opus-4.7",
+  // The opus shortcuts keep resolving to 4-8 (what "claude-opus-4.7" used to be rewritten to); the dotted
+  // display id below is now exact. Moving the shortcuts to 5.5 is a product decision, not part of this refresh.
+  "claude-opus": "claude-opus-4-8",
   "claude-haiku": "claude-haiku-4.5",
-  // Dotted display ids -> hyphenated direct-API ids (dotted Anthropic ids 404; opus display lags to 4-8).
+  // Dotted display ids -> hyphenated direct-API ids (dotted Anthropic ids 404). Explicit table (A.0.5):
+  // the old /\./g regex rewrite is gone, so every dotted id that may sit in a persisted row is listed.
+  "claude-sonnet-4.5": "claude-sonnet-4-5",
   "claude-sonnet-4.6": "claude-sonnet-4-6",
   "claude-haiku-4.5": "claude-haiku-4-5",
-  "claude-opus-4.7": "claude-opus-4-8",
+  "claude-opus-4.5": "claude-opus-4-5",
+  "claude-opus-4.6": "claude-opus-4-6",
+  "claude-opus-4.7": "claude-opus-4-7", // was "claude-opus-4-8" (lossy: a 4.7 request silently ran 4.8)
+  "claude-opus-4.8": "claude-opus-4-8",
+  "claude-opus-4.1": "claude-opus-4-1", // retired; the old regex sent the hyphenated form
+  "claude-haiku-3.5": "claude-haiku-3-5", // retired; the old regex sent the hyphenated form
+  "claude-haiku-5.5": "claude-haiku-5-5",
+  "claude-sonnet-5.5": "claude-sonnet-5-5",
+  "claude-opus-5.5": "claude-opus-5-5",
   "sonnet": "claude-sonnet-4.6",
-  "opus": "claude-opus-4.7",
+  "opus": "claude-opus-4-8",
   "haiku": "claude-haiku-4.5",
   "anthropic": "claude-sonnet-4.6",
 
@@ -639,7 +708,7 @@ export const modelAliases: Record<string, string> = {
 
   // OpenRouter aliases
   "openrouter": "z-ai/glm-5.2",
-  "auto": "gemini-3.5-flash",
+  "auto": DEFAULT_AGENT_MODEL,
   "free": OPENROUTER_FREE_AUTO_MODEL,
   "free-auto": OPENROUTER_FREE_AUTO_MODEL,
   "openrouter-auto": OPENROUTER_FREE_AUTO_MODEL,
@@ -698,18 +767,144 @@ export const modelAliases: Record<string, string> = {
   "nebius/deepseek-v4-pro": "nebius/deepseek-ai/DeepSeek-V4-Pro",
 };
 
+// ═══════════════════════════════════════════════════════════════════════════
+// CLAUDE 5.5 REQUEST-SHAPE FACTS (SPEC §1.3, keyed by exact wire id, never by pattern)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Claude 5.5 wire ids: direct `claude-*-5-5`, OpenRouter `anthropic/claude-*-5.5` (SPEC §1.2). */
+const CLAUDE_55_IDS: ReadonlySet<string> = new Set([
+  "claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5",
+  "anthropic/claude-haiku-5.5", "anthropic/claude-sonnet-5.5", "anthropic/claude-opus-5.5",
+]);
+
+/** Ids whose §1.3 row rejects a forced `tool_choice` (`any` / named) with a 400. Haiku 5.5 accepts it. */
+const FORCED_TOOL_CHOICE_FORBIDDEN: ReadonlySet<string> = new Set([
+  "claude-sonnet-5-5", "claude-opus-5-5", "claude-fable-5-1",
+  "anthropic/claude-sonnet-5.5", "anthropic/claude-opus-5.5", "anthropic/claude-fable-5.1",
+]);
+
+/** Thinking counts toward max_tokens on 5.5, so caps sized for 4.5 truncate. */
+export function isClaude55Id(modelId: string): boolean {
+  return CLAUDE_55_IDS.has(modelId.trim().toLowerCase());
+}
+
+/** True when the provider would 400 a forced tool_choice; callers send `auto` and validate after the turn. */
+export function forbidsForcedToolChoice(modelId: string): boolean {
+  return FORCED_TOOL_CHOICE_FORBIDDEN.has(modelId.trim().toLowerCase());
+}
+
+/** Default effort per 5.5 id (SPEC §1.3), sent explicitly so a vendor default change cannot move the lane. */
+export function claudeDefaultEffort(modelId: string): "medium" | "high" | undefined {
+  switch (modelId.trim().toLowerCase()) {
+    case "claude-haiku-5-5": case "anthropic/claude-haiku-5.5": return "medium";
+    case "claude-sonnet-5-5": case "anthropic/claude-sonnet-5.5": return "high";
+    case "claude-opus-5-5": case "anthropic/claude-opus-5.5": return "medium";
+    default: return undefined;
+  }
+}
+
+/** `providerOptions` carrying the explicit §1.3 effort for a direct-Anthropic Claude 5.5 id; `{}` for every other id. */
+export function claudeEffortProviderOptions(modelId: string): { providerOptions?: { anthropic: { effort: "medium" | "high" } } } {
+  const effort = claudeDefaultEffort(modelId);
+  return effort && getProviderForModel(modelId) === "anthropic" ? { providerOptions: { anthropic: { effort } } } : {};
+}
+
+/**
+ * SPEC §1.3: where a forced `tool_choice` is replaced by `auto` (Sonnet/Opus 5.5), the tool definitions carry
+ * `strict: true` so the arguments are still schema-valid. True exactly when that downgrade happens.
+ */
+export function needsStrictTools(modelId: string, requested?: "auto" | "required"): boolean {
+  return requested === "required" && forbidsForcedToolChoice(modelId);
+}
+
 /**
  * Resolve a model alias to its full model ID.
  * If no alias exists, returns the original input.
  */
-export function resolveModelAlias(modelInput: string): string {
-  const normalized = modelInput.toLowerCase().trim();
+export function lookupModelAlias(modelInput: string): string {
+  const hop = (id: string) => (Object.hasOwn(modelAliases, id.toLowerCase().trim()) ? modelAliases[id.toLowerCase().trim()] : id);
   // Resolve up to two hops: a shortcut ("claude-sonnet") -> dotted display id ("claude-sonnet-4.6")
   // -> hyphenated direct-API id ("claude-sonnet-4-6"). Dotted Anthropic ids 404.
-  const once = modelAliases[normalized] ?? modelInput;
-  const twice = modelAliases[once.toLowerCase().trim()] ?? once;
-  if (twice.startsWith("claude-") && twice.includes(".")) return twice.replace(/\./g, "-");
-  return twice;
+  return hop(hop(modelInput));
+}
+
+/** Every name the alias table declares, as a key or a target: the catalog knows them even where no price row exists yet. */
+const ALIAS_DECLARED_IDS: ReadonlySet<string> = new Set([...Object.keys(modelAliases), ...Object.values(modelAliases)]);
+
+/**
+ * Ids the repo ships or freezes by name but has no price row for: the mobile picker (`MODEL_REGISTRY`), the benchmark
+ * routes (`SUPPORTED_MODEL_ROUTES`, a frozen promotion table) and the frozen benchmark defaults (SPEC A.2.9: the BTB
+ * identity `gpt-4.1-mini`, the benchmark judge). They resolve exactly as before this PR (A.0.4: caller arguments are
+ * kept); a metered run still refuses them as unpriced (`priceRunStrict`). Keep in step with those sources:
+ * tests/modelKnownIds.test.ts fails when one of them names an id this set and the catalog do not know.
+ */
+const REPO_DECLARED_UNPRICED_IDS: readonly string[] = [
+  // src/landing/modelRegistry.ts MODEL_REGISTRY (the defer row :48 stays as shipped)
+  "anthropic/claude-fable-5", "openai/gpt-5.5", "google/gemini-3.5-flash",
+  // scripts/benchmark/modelEvalConfig.ts SUPPORTED_MODEL_ROUTES (frozen promotion tags)
+  "ibm-granite/granite-4.1-8b", "inclusionai/ring-2.6-1t", "xiaomi/mimo-v2.5", "google/gemini-3.1-flash-lite",
+  "poolside/laguna-xs.2:free", "poolside/laguna-m.1:free",
+  // frozen benchmark defaults: bankertoolbench-nodeagent-clean-sequential.mjs:8 and its OpenRouter form
+  "gpt-4.1-mini", "openai/gpt-4.1-mini",
+  // frozen official judges (SPEC A.2.9 Frozen): finch-official-judge.py:20 / package.json:82, mbabench-official-sweep.py:26
+  "gpt-5-mini", "google/gemini-3-flash-preview",
+  // src/nodeagent/core/adaptiveRouter.ts chooseNodeAgentRoute: the benchmark-lane label (origin/main resolved it as itself).
+  "openrouter/auto",
+  // scripts/benchmark/modelEvalConfig.ts OPENROUTER_TOP_PAID_AGENT_ROUTES (frozen; `model-eval-matrix --route-set top-paid`
+  // resolves every one through model(id)). SPEC-v9 D1 names this list; origin/main resolved all 19 as themselves.
+  "z-ai/glm-5.2", "moonshotai/kimi-k2.7-code", "nvidia/nemotron-3-ultra-550b-a55b", "qwen/qwen3.7-plus", "minimax/minimax-m3",
+  "stepfun/step-3.7-flash", "qwen/qwen3.7-max", "x-ai/grok-build-0.1", "inclusionai/ring-2.6-1t", "x-ai/grok-4.3",
+  "poolside/laguna-xs.2", "poolside/laguna-m.1", "qwen/qwen3.5-plus-20260420", "qwen/qwen3.6-flash", "qwen/qwen3.6-35b-a3b",
+  "qwen/qwen3.6-27b", "deepseek/deepseek-v4-pro",
+  // SPEC-v9 section 1.2 wire ids, every transport (D1: an id in 1.2 is known). Most carry a price row above; the rest are
+  // known unpriced, and a metered run still refuses them (priceRunStrict). The verified :free ids are OPENROUTER_KNOWN_FREE_IDS.
+  "claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5", "claude-fable-5-1",
+  "anthropic/claude-haiku-5.5", "anthropic/claude-sonnet-5.5", "anthropic/claude-opus-5.5", "anthropic/claude-fable-5.1",
+  "anthropic.claude-haiku-5-5", "anthropic.claude-sonnet-5-5", "anthropic.claude-opus-5-5", "anthropic.claude-fable-5-1",
+  "gemini-3.8-flash", "gemini-3.6-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.8-flash-tts", "gemini-3.8-live",
+  "google/gemini-3.8-flash", "google/gemini-3.6-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview",
+  "gpt-6.1-sol", "openai/gpt-6.1-sol", "gpt-6-luna", "openai/gpt-6-luna", "gpt-5.4-mini", "openai/gpt-5.4-mini",
+  "moonshotai/kimi-k3", "z-ai/glm-5.3", "minimax/minimax-m3", "nvidia/nemotron-3-super-120b-a12b:free",
+];
+
+/** Every name the catalog knows without a price row: alias keys and targets, the declared ids above, the known free ids. */
+const UNPRICED_KNOWN_IDS: ReadonlySet<string> = new Set([
+  ...ALIAS_DECLARED_IDS, ...REPO_DECLARED_UNPRICED_IDS, ...OPENROUTER_KNOWN_FREE_IDS,
+].map((id) => id.toLowerCase()));
+
+/** An id that is not priced, not an alias, not declared by the repo, not a free route and not free-looking (SPEC A.0.10): never a paid default. */
+export class UnknownModelError extends Error {
+  constructor(readonly modelId: string) {
+    super(`unknown model id "${modelId}": not in the catalog, so it cannot be routed (add a verified row to modelCatalog.modelPricing)`);
+    this.name = "UnknownModelError";
+  }
+}
+
+/** `-free` / `:free` suffix: the id CLAIMS to cost nothing. */
+const FREE_LOOKING_ID = /[-:]free$/i;
+
+/**
+ * Route resolution for anything that DISPATCHES (SPEC A.0.10 - cost class preserved, unknown ids fail closed).
+ * A catalog id (priced, or a free route) resolves through the alias table; an unknown free-looking id resolves to
+ * the verified free route `openrouter/free-auto`; every other unknown id throws `UnknownModelError`.
+ * Pricing and telemetry readers, which must tolerate historical ids, use `lookupModelAlias`.
+ */
+export function resolveModelAlias(modelInput: string): string {
+  const resolved = lookupModelAlias(modelInput);
+  // Known = priced, or declared without a price (persisted rows may hold "claude-sonnet-4.5" / "claude-sonnet-4-5",
+  // which the alias table lists but no price row covers; the picker, benchmark and free catalogs too). A known id is
+  // returned as itself - a concrete `:free` id is never rerouted - and a metered run still refuses an unpriced one.
+  const known = [resolved, modelInput.trim(), modelInput.toLowerCase().trim()];
+  if (isNodeAgentFreeAutoModel(resolved) || known.some((id) => Object.hasOwn(modelPricing, id) || UNPRICED_KNOWN_IDS.has(id.toLowerCase()))) return resolved;
+  if (FREE_LOOKING_ID.test(resolved.trim())) return OPENROUTER_FREE_AUTO_MODEL;
+  throw new UnknownModelError(modelInput);
+}
+
+/** True when the resolved route costs nothing per token (a zero-priced row, a `:free` id, a free route). */
+export function isFreeModelId(modelId: string): boolean {
+  if (isNodeAgentFreeAutoModel(modelId)) return true;
+  const pricing = getModelPricing(lookupModelAlias(modelId));
+  return pricing != null && pricing.inputPer1M === 0 && pricing.outputPer1M === 0;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -806,33 +1001,43 @@ export function validateContextWindow(
 export const modelFallbackChains: Record<string, string[]> = {
   // OpenAI flagship → smaller OpenAI → cross-provider small model
   "gpt-5.4": ["z-ai/glm-5.2", "moonshotai/kimi-k2.7-code", "gemini-3.1-pro-preview", "gpt-5.4-mini", "minimax/minimax-m3"],
-  "gpt-5.4-mini": ["gemini-3.1-flash-lite-preview", "minimax/minimax-m3", "qwen/qwen3.7-plus", "gemini-3-flash-preview", "gpt-5.4-nano"],
+  "gpt-5.4-mini": ["gemini-3.5-flash-lite", "minimax/minimax-m3", "qwen/qwen3.7-plus", "gemini-3.8-flash", "gpt-5.4-nano"],
 
   // Anthropic premium → cheaper Anthropic → cross-provider small model
+  // Claude 5.5 ids (the migration-guide successors); the 4.x keys below stay for persisted rooms.
+  "claude-opus-5-5": ["claude-sonnet-5-5", "z-ai/glm-5.2", "gpt-5.4", "gemini-3.1-pro-preview", "gpt-5.4-mini"],
+  "claude-sonnet-5-5": ["z-ai/glm-5.2", "gpt-5.4-mini", "gemini-3.8-flash", "moonshotai/kimi-k2.7-code", "minimax/minimax-m3"],
+  "claude-haiku-5-5": ["gpt-5.4-nano", "gemini-3.5-flash-lite", "qwen/qwen3.7-plus", "minimax/minimax-m3", "z-ai/glm-4.7-flash"],
   "claude-opus-4.7": ["claude-sonnet-4.6", "z-ai/glm-5.2", "gpt-5.4", "gemini-3.1-pro-preview", "gpt-5.4-mini"],
-  "claude-sonnet-4.6": ["z-ai/glm-5.2", "gpt-5.4-mini", "gemini-3-flash-preview", "moonshotai/kimi-k2.7-code", "minimax/minimax-m3"],
-  "claude-haiku-4.5": ["gpt-5.4-nano", "gemini-3.1-flash-lite-preview", "qwen/qwen3.7-plus", "minimax/minimax-m3", "z-ai/glm-4.7-flash"],
-  "claude-opus-4.1": ["claude-opus-4", "claude-sonnet-4", "claude-haiku-3.5", "gpt-5.4-mini", "gemini-2.5-flash"],
-  "claude-opus-4": ["claude-sonnet-4", "claude-haiku-3.5", "gpt-5.4-mini", "gemini-2.5-flash"],
-  "claude-sonnet-4": ["claude-haiku-3.5", "gpt-5.4-mini", "gemini-2.5-flash"],
-
-  // Gemini 3.x preview → stable 2.5 → cross-provider advisor/executor lanes
-  "gemini-3.1-pro-preview": ["z-ai/glm-5.2", "gemini-3-flash-preview", "gemini-2.5-pro", "moonshotai/kimi-k2.7-code", "gpt-5.4"],
-  "gemini-3-flash-preview": ["qwen/qwen3.7-plus", "gemini-3.1-flash-lite-preview", "gemini-2.5-flash", "gpt-5.4-mini", "minimax/minimax-m3"],
-  "gemini-3.1-flash-lite-preview": ["qwen/qwen3.7-plus", "gemini-3-flash-preview", "gemini-2.5-flash-lite", "gpt-5.4-mini", "minimax/minimax-m3"],
-  "gemini-2.5-pro": ["z-ai/glm-5.2", "gemini-3.1-pro-preview", "gemini-3-flash-preview", "moonshotai/kimi-k2.7-code", "gpt-5.4"],
-  "gemini-2.5-flash": ["qwen/qwen3.7-plus", "gemini-3-flash-preview", "gemini-3.1-flash-lite-preview", "gpt-5.4-mini", "minimax/minimax-m3"],
+  "claude-sonnet-4.6": ["z-ai/glm-5.2", "gpt-5.4-mini", "gemini-3.8-flash", "moonshotai/kimi-k2.7-code", "minimax/minimax-m3"],
+  "claude-haiku-4.5": ["gpt-5.4-nano", "gemini-3.5-flash-lite", "qwen/qwen3.7-plus", "minimax/minimax-m3", "z-ai/glm-4.7-flash"],
+  // Retired Claude 4 / 4.1 / Haiku 3.5 keys: members that are retired are dropped, the chain points at live ids.
+  "claude-opus-4.1": ["claude-sonnet-5-5", "gpt-5.4-mini", "gemini-3.8-flash"],
+  "claude-opus-4": ["claude-sonnet-5-5", "gpt-5.4-mini", "gemini-3.8-flash"],
+  "claude-sonnet-4": ["claude-sonnet-5-5", "gpt-5.4-mini", "gemini-3.8-flash"],
+
+  // Gemini 3.x Pro + retired Gemini keys → cross-provider advisor/executor lanes. Retired or
+  // prior-users-only members (gemini-3.1-flash-lite-preview, gemini-2.5-*) are dropped from the values;
+  // those ids stay as keys so a persisted room still on one of them has an escape route.
+  // gemini-3.8-flash (DEFAULT_AGENT_MODEL), gemini-3.6-flash and gemini-3.5-flash-lite deliberately have NO key:
+  // origin/main's default route had no failover chain, and a chain would send room content cross-provider
+  // (OpenRouter, OpenAI) on a failed default turn. Adding one is a separate decision.
+  "gemini-3.1-pro-preview": ["z-ai/glm-5.2", "gemini-3.8-flash", "moonshotai/kimi-k2.7-code", "gpt-5.4"],
+  "gemini-3-flash-preview": ["qwen/qwen3.7-plus", "gemini-3.5-flash-lite", "gpt-5.4-mini", "minimax/minimax-m3"],
+  "gemini-3.1-flash-lite-preview": ["qwen/qwen3.7-plus", "gemini-3.8-flash", "gpt-5.4-mini", "minimax/minimax-m3"],
+  "gemini-2.5-pro": ["z-ai/glm-5.2", "gemini-3.1-pro-preview", "gemini-3.8-flash", "moonshotai/kimi-k2.7-code", "gpt-5.4"],
+  "gemini-2.5-flash": ["qwen/qwen3.7-plus", "gemini-3.8-flash", "gemini-3.5-flash-lite", "gpt-5.4-mini", "minimax/minimax-m3"],
   "deep-research-max-preview-04-2026": ["deep-research-preview-04-2026", "gemini-3.1-pro-preview", "gpt-5.4"],
-  "deep-research-preview-04-2026": ["deep-research-max-preview-04-2026", "gemini-3.1-pro-preview", "gemini-2.5-pro"],
+  "deep-research-preview-04-2026": ["deep-research-max-preview-04-2026", "gemini-3.1-pro-preview"],
   "deep-research-pro-preview-12-2025": ["deep-research-preview-04-2026", "deep-research-max-preview-04-2026", "gemini-3.1-pro-preview"],
   "glm-5.2": ["moonshotai/kimi-k2.7-code", "qwen/qwen3.7-plus", "gemini-3.1-pro-preview", "gpt-5.4", "minimax/minimax-m3"],
   "z-ai/glm-5.2": ["moonshotai/kimi-k2.7-code", "qwen/qwen3.7-plus", "gemini-3.1-pro-preview", "gpt-5.4", "minimax/minimax-m3"],
   "nebius/zai-org/GLM-5.2": ["qwen/qwen3.7-plus", "nebius/MiniMaxAI/MiniMax-M2.5", "cohere/north-mini-code:free"],
   "kimi-k2.7-code": ["z-ai/glm-5.2", "qwen/qwen3.7-plus", "gemini-3.1-pro-preview", "gpt-5.4", "minimax/minimax-m3"],
   "moonshotai/kimi-k2.7-code": ["z-ai/glm-5.2", "qwen/qwen3.7-plus", "gemini-3.1-pro-preview", "gpt-5.4", "minimax/minimax-m3"],
-  "qwen/qwen3.7-plus": ["minimax/minimax-m3", "z-ai/glm-5.2", "gemini-3.1-flash-lite-preview", "stepfun/step-3.7-flash"],
-  "minimax-m3": ["qwen/qwen3.7-plus", "gemini-3.1-flash-lite-preview", "gpt-5.4-mini", "gemini-3-flash-preview"],
-  "minimax/minimax-m3": ["qwen/qwen3.7-plus", "gemini-3.1-flash-lite-preview", "gpt-5.4-mini", "gemini-3-flash-preview"],
+  "qwen/qwen3.7-plus": ["minimax/minimax-m3", "z-ai/glm-5.2", "gemini-3.5-flash-lite", "stepfun/step-3.7-flash"],
+  "minimax-m3": ["qwen/qwen3.7-plus", "gemini-3.5-flash-lite", "gpt-5.4-mini", "gemini-3.8-flash"],
+  "minimax/minimax-m3": ["qwen/qwen3.7-plus", "gemini-3.5-flash-lite", "gpt-5.4-mini", "gemini-3.8-flash"],
 };
 
 export function getNextFallback(model: string, attempted: string[]): string | null {
diff --git a/src/nodeagent/models/openAiTokenLimit.ts b/src/nodeagent/models/openAiTokenLimit.ts
index af7eab47..3d64f7da 100644
--- a/src/nodeagent/models/openAiTokenLimit.ts
+++ b/src/nodeagent/models/openAiTokenLimit.ts
@@ -18,5 +18,5 @@ function isDirectOpenAiEndpoint(endpoint: string): boolean {
 }
 
 function requiresMaxCompletionTokens(modelId: string): boolean {
-  return /^gpt-5(?:[.-]|$)/i.test(modelId);
+  return /^gpt-[56](?:[.-]|$)/i.test(modelId);
 }
diff --git a/src/nodeagent/models/openRouterFreeModels.ts b/src/nodeagent/models/openRouterFreeModels.ts
index fb077ff0..efa9c52c 100644
--- a/src/nodeagent/models/openRouterFreeModels.ts
+++ b/src/nodeagent/models/openRouterFreeModels.ts
@@ -145,6 +145,27 @@ const FALLBACK_FREE_MODELS: OpenRouterModelInfo[] = [
   },
 ];
 
+/**
+ * The concrete `:free` ids this repo knows by name (SPEC A.0.10: a known free id is dispatched as itself, never rerouted).
+ * Three sources, none invented: the catalog fallback and the preferred list above, and the OpenRouter live `:free` list
+ * read 2026-10-10 (SPEC section 1.2; `dots-3-note-preview` expires 2026-12-31, both `laguna-*` 2026-10-31 - the id stays
+ * valid for persisted rows and the provider answers for itself once it expires).
+ */
+const OPENROUTER_LIVE_FREE_2026_10_10 = [
+  "apodex/apodex-1.1-mini:free", "dots-studio/dots-3-note-preview:free", "liquid/lfm-2.5-2.6b:free",
+  "nvidia/nemotron-3.5-lightning:free", "thinkingmachines/inkling-small:free", "poolside/laguna-s-2.1:free",
+  "thinkingmachines/inkling:free", "poolside/laguna-xs-2.1:free", "cohere/north-mini-code:free",
+  "nvidia/nemotron-3.5-content-safety:free", "nvidia/nemotron-3-ultra-550b-a55b:free",
+  "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free", "google/gemma-4-26b-a4b-it:free",
+  "google/gemma-4-31b-it:free", "nvidia/nemotron-3-super-120b-a12b:free",
+];
+/** Added by the public list fetched 2026-10-16T11:32Z (SPEC-v9 D2): the newest `:free` row with tools, tool_choice, structured outputs and 1M context; the `top_paid` default. */
+const OPENROUTER_LIVE_FREE_2026_10_16 = ["nvidia/nemotron-3.5-super-vl:free"];
+export const OPENROUTER_KNOWN_FREE_IDS: ReadonlySet<string> = new Set(
+  [...FALLBACK_FREE_MODELS.map((m) => m.id), ...DEFAULT_PREFERRED_FREE_MODELS, ...OPENROUTER_LIVE_FREE_2026_10_10, ...OPENROUTER_LIVE_FREE_2026_10_16]
+    .map((id) => id.toLowerCase()),
+);
+
 export function isOpenRouterFreeAutoModel(modelId: string): boolean {
   return normalizeModelId(modelId) === OPENROUTER_FREE_AUTO_MODEL;
 }
diff --git a/src/nodeagent/models/outputTokens.ts b/src/nodeagent/models/outputTokens.ts
new file mode 100644
index 00000000..be12cc02
--- /dev/null
+++ b/src/nodeagent/models/outputTokens.ts
@@ -0,0 +1,20 @@
+/**
+ * Output-token cap shared by the Convex-safe HTTP model (convexModel.ts) and the AI-SDK adapter
+ * (adapter.ts), so the cap a request carries is the same number the spend reservation prices.
+ */
+import { isClaude55Id } from "./modelCatalog";
+
+const DEFAULT_MAX_OUTPUT_TOKENS = 8_192;
+/** Claude 5.5 spends thinking inside max_tokens; a cap sized for 4.5 truncates the answer. */
+const CLAUDE_55_MIN_OUTPUT_TOKENS = 2_048;
+
+function envNumber(name: string, fallback: number, min: number, max: number): number {
+  const raw = Number(process.env[name]?.trim() || fallback);
+  if (!Number.isFinite(raw)) return fallback;
+  return Math.max(min, Math.min(max, raw));
+}
+
+export function modelMaxOutputTokens(modelId?: string): number {
+  const configured = envNumber("AGENT_MODEL_MAX_OUTPUT_TOKENS", DEFAULT_MAX_OUTPUT_TOKENS, 1_024, 32_000);
+  return modelId && isClaude55Id(modelId) ? Math.max(configured, CLAUDE_55_MIN_OUTPUT_TOKENS) : configured;
+}
diff --git a/src/nodeagent/models/piAiAdapter.ts b/src/nodeagent/models/piAiAdapter.ts
index d1818d6d..ab57b74c 100644
--- a/src/nodeagent/models/piAiAdapter.ts
+++ b/src/nodeagent/models/piAiAdapter.ts
@@ -1,10 +1,11 @@
 import { model } from "./adapter";
 import type { AgentModel } from "../core/types";
+import { DEFAULT_AGENT_MODEL } from "../../../convex/modelDefaults";
 
 export interface PiAdapterOptions {
   modelName?: string;
 }
 
 export function createPiAiAdapter(options: PiAdapterOptions = {}): AgentModel {
-  return model(options.modelName ?? "gemini-2.5-flash");
+  return model(options.modelName ?? DEFAULT_AGENT_MODEL);
 }
\ No newline at end of file
diff --git a/src/nodeagent/models/providerParserLive.ts b/src/nodeagent/models/providerParserLive.ts
index 65bbd1ad..06643c86 100644
--- a/src/nodeagent/models/providerParserLive.ts
+++ b/src/nodeagent/models/providerParserLive.ts
@@ -13,6 +13,7 @@ import {
   type ProviderUploadResult,
 } from "../../app/providerParserAdapter";
 import type { ProviderFileCacheMeta, ProviderParser } from "../../engine/types";
+import { claudeEffortProviderOptions } from "./modelCatalog";
 import type { UploadedArtifactInput } from "../../app/uploadedArtifact";
 import {
   assertProviderEgressAllowed,
@@ -107,10 +108,10 @@ const PROVIDER_MODEL_ENV_KEYS: Record<ProviderParser, string> = {
 };
 
 const PROVIDER_MODEL_DEFAULTS: Record<ProviderParser, string[]> = {
-  gemini: ["gemini-3.5-flash", "gemini-3-flash-preview", "gemini-2.5-flash", "gemini-2.0-flash"],
-  openai: ["gpt-5.5", "gpt-5.4-mini", "gpt-5-mini", "gpt-4.1-mini"],
-  anthropic: ["claude-haiku-4-5", "claude-3-5-haiku-latest", "claude-sonnet-4-5"],
-  openrouter: ["z-ai/glm-5.2", "moonshotai/kimi-k2.7-code", "cohere/north-mini-code:free", "nvidia/nemotron-3-ultra-550b-a55b", "nex-agi/nex-n2-pro"],
+  gemini: ["gemini-3.8-flash", "gemini-3.6-flash"],
+  openai: ["gpt-5.5", "gpt-5.4-mini"],
+  anthropic: ["claude-haiku-5-5", "claude-sonnet-5-5"],
+  openrouter: ["z-ai/glm-5.2", "moonshotai/kimi-k2.7-code", "cohere/north-mini-code:free", "nvidia/nemotron-3-ultra-550b-a55b"],
 };
 
 export function providerParserModelCandidates(
@@ -248,22 +249,24 @@ async function extractWithLiveProvider(args: {
 }): Promise<{ extraction: ProviderExtraction; providerRoute: ProviderRouteReceipt }> {
   const providerRoute = assertProviderParserAllowed(args);
   const model = providerLanguageModel(args.provider, providerRoute.resolvedModel);
+  // Explicit SPEC §1.3 effort for claude-*-5-5 on the direct Anthropic transport (no-op for every other provider/id).
+  const effort = args.provider === "anthropic" ? claudeEffortProviderOptions(providerRoute.resolvedModel) : {};
   const prompt = buildExtractionPrompt(args.prompt, args.file, args.source);
   const input = buildPromptInput(prompt, args.file, args.source);
 
   const extraction = await extractProviderExtractionWithFallback({
     structured: async () => {
       const res = "messages" in input
-        ? await generateObject({ model, schema: providerExtractionSchema, messages: input.messages })
-        : await generateObject({ model, schema: providerExtractionSchema, prompt: input.prompt });
+        ? await generateObject({ model, schema: providerExtractionSchema, messages: input.messages, ...effort })
+        : await generateObject({ model, schema: providerExtractionSchema, prompt: input.prompt, ...effort });
       return res.object;
     },
     text: async () => {
       const textPrompt = `${prompt}\n\nReturn JSON only. The JSON must match this shape: ${schemaHint()}`;
       const textInput = buildPromptInput(textPrompt, args.file, args.source);
       const res = "messages" in textInput
-        ? await generateText({ model, messages: textInput.messages })
-        : await generateText({ model, prompt: textInput.prompt });
+        ? await generateText({ model, messages: textInput.messages, ...effort })
+        : await generateText({ model, prompt: textInput.prompt, ...effort });
       return res.text;
     },
   });
diff --git a/src/ui/Chat.tsx b/src/ui/Chat.tsx
index ac7dc18e..17715db0 100644
--- a/src/ui/Chat.tsx
+++ b/src/ui/Chat.tsx
@@ -13,6 +13,7 @@ import { useStore, CONVEX_SITE_URL, type AgentJobDetailTelemetry, type AgentJobT
 import { abortable, parseUploadedFiles, UPLOAD_TIMEOUT_MS } from "../app/uploadedArtifact";
 import type { StreamId } from "@convex-dev/persistent-text-streaming";
 import { api } from "../../convex/_generated/api";
+import { DEFAULT_AGENT_MODEL } from "../../convex/modelDefaults";
 import type { Actor, Artifact, CellPayload, Channel, Message } from "../engine/types";
 import { getProviderForModel, llmModelCatalog, modelPricing, resolveModelAlias, type LlmProvider } from "../nodeagent/models/modelCatalog";
 import {
@@ -868,7 +869,7 @@ type AgentFailureNotice = {
 const AGENT_MODEL_PRESETS: AgentModelPresetOption[] = [
   { value: "adaptive", label: "Adaptive", badge: "recommended", detail: "Server router chooses the best available NodeAgent route with fallbacks." },
   { value: "free", label: "Free", badge: "$0", detail: "Rotates across healthy $0 models; the final resolved model is shown and terminal failures stay actionable." },
-  { value: "top_paid", label: "Top paid", badge: "best", detail: "Pins the strongest configured paid route for higher-recall work." },
+  { value: "top_paid", label: "Top paid", badge: "operator", detail: "Pins the route the operator configured as top paid (AGENT_TOP_PAID_MODEL, else AGENT_MODEL). With neither set, the server default is a free model." },
   { value: "specific", label: "Specific model", badge: "pin", detail: "Pin one provider/model from the approved NodeAgent catalog." },
 ];
 
@@ -1687,7 +1688,7 @@ export function Chat({ roomId, me, channel, variant, agentName, activeArtifactId
     if (override) return override;
     if (forceFree) return { mode: "free" };
     return modelSelectionMode === "specific"
-      ? { mode: "specific", modelPolicy: specificModelPolicy || defaultSpecificModel || "gemini-3.5-flash" }
+      ? { mode: "specific", modelPolicy: specificModelPolicy || defaultSpecificModel || DEFAULT_AGENT_MODEL }
       : { mode: modelSelectionMode };
   };
 
diff --git a/tests/agentJobsRuntime.test.ts b/tests/agentJobsRuntime.test.ts
index 7f64c736..22630bdc 100644
--- a/tests/agentJobsRuntime.test.ts
+++ b/tests/agentJobsRuntime.test.ts
@@ -2,7 +2,7 @@
 import { convexTest } from "convex-test";
 import { internalAction } from "../convex/_generated/server";
 import { v } from "convex/values";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import schema from "../convex/schema";
 import { api, internal } from "../convex/_generated/api";
 import { hashToken } from "../convex/lib";
@@ -71,7 +71,7 @@ describe("agentJobs runtime contract", () => {
       scope: "public_room" as const,
       routePolicy: "explicit" as const,
       runtimePolicy: "workflow_sliced" as const,
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       idempotencyKey: "job-runtime-central-start",
       approvalPolicy: "auto_commit_safe" as const,
       evidencePolicy: "public_only" as const,
@@ -83,7 +83,7 @@ describe("agentJobs runtime contract", () => {
     expect(blockedStart).toMatchObject({
       reused: false,
       status: "blocked",
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       routePolicy: "explicit",
       runtimePolicy: "workflow_sliced",
     });
@@ -94,7 +94,7 @@ describe("agentJobs runtime contract", () => {
       scope: "public_room",
       routePolicy: "explicit",
       runtimePolicy: "workflow_sliced",
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       runtime: "workflow",
     });
     expect(blockedDetail?.job.workflowId).toBeUndefined();
@@ -107,7 +107,7 @@ describe("agentJobs runtime contract", () => {
       scope: "public_room",
       routePolicy: "explicit",
       runtimePolicy: "workflow_sliced",
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       traceLevel: "standard",
     });
   });
@@ -662,6 +662,36 @@ describe("agentJobs runtime contract", () => {
     expect(jobs).toHaveLength(0);
   });
 
+  it("derives the default model per route policy from the refreshed ids when no env or client model is set", async () => {
+    // SPEC A.2.9: top_paid was "anthropic/claude-sonnet-4" (retired 2026-06-15); the orchestrator default was
+    // "gemini-3.5-flash" (deprecated 2026-10-08). SPEC-v9 D2 (2026-10-16, no OpenRouter key): top_paid is the newest :free
+    // OpenRouter row with tools + structured outputs + a long context, from the public list fetched 2026-10-16T11:32Z
+    // (docs/eval/openrouter-free-models-2026-10-16.json); rounds 1-4 expected "anthropic/claude-sonnet-5.5" here. The ids are literals here on purpose.
+    for (const name of ["AGENT_MODEL", "AGENT_TOP_PAID_MODEL", "AGENT_ORCHESTRATOR_MODEL"]) vi.stubEnv(name, undefined);
+    try {
+      const { t, proof, roomId, artifactId } = await setupRoom({ seedElement: true });
+      const policies: Array<[string, string]> = [];
+      for (const routePolicy of ["top_paid", "fast_default"] as const) {
+        const started = await t.mutation(api.agentJobs.startPublicAsk, {
+          roomId,
+          requester: proof,
+          goal: `default model for ${routePolicy}`,
+          contextArtifactId: String(artifactId),
+          routePolicy,
+          disposition: "redirect" as const,
+        });
+        const detail = await t.query(api.agentJobs.detail, { jobId: started.jobId, requester: proof });
+        policies.push([routePolicy, String(detail?.job.modelPolicy)]);
+      }
+      expect(policies).toEqual([
+        ["top_paid", "nvidia/nemotron-3.5-super-vl:free"],
+        ["fast_default", "gemini-3.8-flash"],
+      ]);
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   it("starts public chat asks server-side against the active work-surface artifact", async () => {
     const { t, proof, roomId, artifactId } = await setupRoom({ seedElement: true });
 
@@ -2813,6 +2843,137 @@ describe("agentJobs runtime contract", () => {
     expect(hostDetail).toBeNull();
     expect(hostAttempts).toEqual([]);
   });
+  // SPEC A.0.10 at the public API boundary. Persona: a client (or a script holding a room token) names a model the
+  // catalog has never heard of; the job row must not persist a string that could only ever fail later, in the runner.
+  describe("unknown model ids are refused at the public mutations", () => {
+    const UNKNOWN = "gemini-not-in-catalog";
+
+    it("createOrReuse refuses an unknown modelPolicy and persists no job", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom();
+      await expect(t.mutation(api.agentJobs.createOrReuse, { ...jobArgs({ roomId, artifactId, proof, idempotencyKey: "job-unknown-create" }), modelPolicy: UNKNOWN }))
+        .rejects.toThrow("unknown_model_policy");
+      expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+    });
+
+    it("start refuses an unknown modelPolicy on the explicit route", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom();
+      await expect(t.mutation(api.agentJobs.start, { ...jobArgs({ roomId, artifactId, proof, idempotencyKey: "job-unknown-start" }), routePolicy: "explicit" as const, modelPolicy: UNKNOWN }))
+        .rejects.toThrow("unknown_model_policy");
+      expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+    });
+
+    it("startPublicAsk refuses an unknown modelPolicy on the explicit route", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom({ seedElement: true });
+      await expect(t.mutation(api.agentJobs.startPublicAsk, { roomId, requester: proof, goal: "compute the metrics", contextArtifactId: String(artifactId), routePolicy: "explicit" as const, modelPolicy: UNKNOWN }))
+        .rejects.toThrow("unknown_model_policy");
+      expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+    });
+
+    it("a catalog id, an alias and a declared-but-unpriced id still start (nothing the repo knows is refused)", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom();
+      for (const [i, modelPolicy] of ["gemini-3.8-flash", "claude-sonnet", "anthropic/claude-fable-5"].entries()) {
+        const started = await t.mutation(api.agentJobs.createOrReuse, { ...jobArgs({ roomId, artifactId, proof, idempotencyKey: `job-known-${i}` }), modelPolicy });
+        const detail = await t.query(api.agentJobs.detail, { jobId: started.jobId, requester: proof });
+        expect(detail?.job.modelPolicy).toBe(modelPolicy);
+      }
+    });
+
+    // Regression (review round 3, defect 2): runRoomAgent records a PlanPreview-blocked run with the marker
+    // modelPolicy "not_started" (no model runs, so no id to check). The boundary check threw unknown_model_policy there,
+    // so the plan message and the credit-hold release after createOrReuse were never reached.
+    it("runRoomAgent's PlanPreview-blocked branch still records the job, posts the plan and releases the credit hold", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom();
+      const { runRoomAgent } = await import("../convex/agent");
+      const { getFunctionName } = await import("convex/server");
+      const calls: string[] = [];
+      vi.stubEnv("CREDITS_ENFORCED", "true");
+      const ctx = {
+        runQuery: async (ref: any) => {
+          const name = getFunctionName(ref);
+          if (name === "rooms:full") return { members: [{ id: proof.actor.id }], artifacts: [{ id: artifactId, kind: "sheet", title: "Sheet", order: [] }], sessions: [{ id: "s", scope: "public", agentId: "agent_room", agentName: "Agent" }] };
+          if (name === "agentRuns:roomSpendSince") return 0;
+          if (name === "agentRuns:globalSpendSince") return { totalUsd: 0, distinctRooms: 0, runCount: 0, truncated: false };
+          if (name === "artifacts:listProposals") return [];
+          throw new Error(`unexpected query ${name}`);
+        },
+        runMutation: async (ref: any, args: any) => {
+          const name = getFunctionName(ref);
+          calls.push(name);
+          if (name === "agentJobs:createOrReuse") return t.mutation(api.agentJobs.createOrReuse, args);
+          if (name === "credits:reserve") return { ok: true };
+          if (name === "credits:settle" || name === "messages:sendAgent") return null;
+          throw new Error(`unexpected mutation ${name}`);
+        },
+      };
+      try {
+        const result = await (runRoomAgent as any)._handler(ctx, { roomId, artifactId, requester: proof, goal: "Wait for human approval before changing anything." });
+        expect(result.stopReason).toBe("plan_blocked");
+        expect(calls).toEqual(["credits:reserve", "agentJobs:createOrReuse", "messages:sendAgent", "credits:settle"]);
+        const detail = await t.query(api.agentJobs.detail, { jobId: result.jobId, requester: proof });
+        expect(detail?.job).toMatchObject({ status: "blocked", modelPolicy: "not_started" });
+      } finally {
+        vi.unstubAllEnvs();
+      }
+    }, 60_000); // the first import of convex/agent.ts pulls in the whole runtime graph
+
+    it("the no-model marker is accepted only with initialStatus blocked; otherwise it is an unknown model", async () => {
+      const { t, proof, roomId, artifactId } = await setupRoom();
+      await expect(t.mutation(api.agentJobs.createOrReuse, { ...jobArgs({ roomId, artifactId, proof, idempotencyKey: "job-marker-running" }), modelPolicy: "not_started" }))
+        .rejects.toThrow("unknown_model_policy");
+    });
+
+    // Review round 6, defect 3. Persona: an operator sets a default-model env var on the deployment with a typo or a retired
+    // name and a user starts a job without naming any model. The default reaches the job row exactly like a caller's argument,
+    // so it passes the same boundary check; before this, six env x endpoint combinations persisted the unknown string.
+    describe.each([
+      { env: "AGENT_ORCHESTRATOR_MODEL", args: {} },
+      { env: "AGENT_MODEL", args: {} },
+      { env: "AGENT_TOP_PAID_MODEL", args: { routePolicy: "top_paid" as const } },
+      { env: "AGENT_RESEARCH_MODEL", args: { mode: "research" as const } },
+    ])("an unknown $env default", ({ env, args: extra }) => {
+      const arrange = () => {
+        for (const name of ["AGENT_ORCHESTRATOR_MODEL", "AGENT_MODEL", "AGENT_TOP_PAID_MODEL", "AGENT_RESEARCH_MODEL", "AGENT_WORKER_MODEL"]) vi.stubEnv(name, "");
+        vi.stubEnv(env, UNKNOWN);
+      };
+      afterEach(() => { vi.unstubAllEnvs(); });
+
+      it("is refused by start and persists no job", async () => {
+        arrange();
+        const { t, proof, roomId, artifactId } = await setupRoom();
+        const { modelPolicy: _omit, ...base } = jobArgs({ roomId, artifactId, proof, idempotencyKey: `job-env-start-${env}` });
+        await expect(t.mutation(api.agentJobs.start, { ...base, ...extra })).rejects.toThrow("unknown_model_policy");
+        expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+      });
+
+      if (!("mode" in extra)) it("is refused by startPublicAsk and persists no job", async () => {
+        arrange();
+        const { t, proof, roomId, artifactId } = await setupRoom({ seedElement: true });
+        await expect(t.mutation(api.agentJobs.startPublicAsk, { roomId, requester: proof, goal: "compute the metrics", contextArtifactId: String(artifactId), ...extra }))
+          .rejects.toThrow("unknown_model_policy");
+        expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+      });
+    });
+
+    it("an unknown file-egress model is refused when a free job is promoted to it, and no job persists", async () => {
+      vi.stubEnv("FREE_AUTO_ALLOW_FILE_EGRESS_PROMOTION", "1");
+      vi.stubEnv("AGENT_FILE_EGRESS_MODEL", UNKNOWN);
+      try {
+        const { t, proof, roomId, artifactId, actor } = await setupRoom({ seedElement: true });
+        await t.run((ctx) =>
+          ctx.db.insert("artifacts", {
+            roomId, kind: "note" as const, title: "source_financials.csv", version: 1, order: ["source"], updatedAt: Date.now(), createdBy: actor,
+            visibility: "room" as const, meta: { upload: { fileName: "source_financials.csv", mimeType: "text/csv", size: 96 } },
+          }),
+        );
+        await expect(t.mutation(api.agentJobs.startPublicAsk, { roomId, requester: proof, goal: "compute the uploaded financial metrics", contextArtifactId: String(artifactId), routePolicy: "free_auto" as const }))
+          .rejects.toThrow("unknown_model_policy");
+        expect(await t.run(async (ctx) => (await ctx.db.query("agentJobs").collect()).length)).toBe(0);
+      } finally {
+        vi.unstubAllEnvs();
+      }
+    });
+  });
+
 });
 
 async function setupRoom(options: { seedElement?: boolean; extraMember?: boolean; researchPolicy?: boolean; autoAllow?: boolean } = {}) {
@@ -3024,7 +3185,7 @@ function jobArgs(args: {
     goal: "Verify the unified agent job runtime",
     entrypoint: "public_ask" as const,
     scope: "public_room" as const,
-    modelPolicy: "test-model",
+    modelPolicy: "z-ai/glm-5.2",
     idempotencyKey: args.idempotencyKey,
     approvalPolicy: "auto_commit_safe" as const,
     evidencePolicy: "public_only" as const,
diff --git a/tests/agentJobsSource.test.ts b/tests/agentJobsSource.test.ts
index e69b84ee..14e7f974 100644
--- a/tests/agentJobsSource.test.ts
+++ b/tests/agentJobsSource.test.ts
@@ -471,7 +471,9 @@ describe("long-running agent job source invariants", () => {
     expect(runner).toContain("agentJobRunner.runFreeAutoJobSlice");
     expect(runner).toContain("onTrace: (event)");
     expect(runner).toContain("liveOperationKind(event)");
-    expect(model).toContain("AGENT_MODEL_MAX_OUTPUT_TOKENS");
+    // The output-token cap moved to the module convexModel.ts and adapter.ts share (SPEC A.2.9); same knob, same default.
+    expect(model).toContain('from "./outputTokens"');
+    expect(readFileSync("src/nodeagent/models/outputTokens.ts", "utf8")).toContain("AGENT_MODEL_MAX_OUTPUT_TOKENS");
     expect(model).toContain("chat_template_kwargs");
     expect(model).toContain("enable_thinking: false");
     expect(model).toContain("isOpenRouterHybridThinkingModel");
diff --git a/tests/convexModelFreeAutoMode.test.ts b/tests/convexModelFreeAutoMode.test.ts
index 3b0a6561..8439a2d2 100644
--- a/tests/convexModelFreeAutoMode.test.ts
+++ b/tests/convexModelFreeAutoMode.test.ts
@@ -6,6 +6,7 @@ import { AgentRunError, InMemoryRoomTools, ROOM_TOOLS, runAgent } from "../src/n
 import type { AgentTool } from "../src/nodeagent/core/types";
 import { configuredConvexModelFallbacks, convexModel } from "../src/nodeagent/models/convexModel";
 import { openRouterFreeRouteHealthSnapshot, resetOpenRouterFreeRouteHealth } from "../src/nodeagent/models/openRouterFreeModels";
+import { UnknownModelError } from "../src/nodeagent/models/modelCatalog";
 import { QualityFailoverError } from "../src/nodeagent/models/qualityFailover";
 
 const freeModels = [
@@ -545,12 +546,28 @@ describe("Convex free-auto model routing", () => {
     expect(result.text).toBe("fallback answer");
   });
 
+  // Round 3 (SPEC A.0.10): these two tests used "vendor/unknown-paid-model", an id the catalog has never heard of, which
+  // convexModel() then DISPATCHED to OpenRouter - the defect. An unknown id now throws (first test below). The cost
+  // accounting they guard (conservative reservation; a hard turn budget blocks before the call) is about a route the
+  // adapter can route but the catalog cannot price: only an id the alias table declares without a price row, such as the
+  // persisted-room string "claude-sonnet-4.5" (resolves to claude-sonnet-4-5).
+  const UNPRICED_DECLARED = "claude-sonnet-4.5";
+  const anthropicAnswer = () => new Response(JSON.stringify({
+    content: [{ type: "text", text: "answer" }],
+    usage: { input_tokens: 5, output_tokens: 2 },
+  }), { status: 200, headers: { "Content-Type": "application/json" } });
+
+  it("refuses an unknown paid id at convexModel() before any provider call, with or without a turn budget", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    expect(() => convexModel("vendor/unknown-paid-model", { entrypoint: "public_ask" })).toThrow(UnknownModelError);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
   it("retains a conservative reservation when catalog pricing cannot be measured exactly", async () => {
-    vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({
-      choices: [{ message: { content: "answer" } }],
-      usage: { prompt_tokens: 5, completion_tokens: 2 },
-    }), { status: 200, headers: { "Content-Type": "application/json" } })));
-    const step = await convexModel("vendor/unknown-paid-model", { entrypoint: "public_ask" }).next({
+    process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+    vi.stubGlobal("fetch", vi.fn(async () => anthropicAnswer()));
+    const step = await convexModel(UNPRICED_DECLARED, { entrypoint: "public_ask" }).next({
       system: "Answer.",
       messages: [{ role: "user", content: "hello" }],
       tools: [],
@@ -561,7 +578,7 @@ describe("Convex free-auto model routing", () => {
     const result = await runAgent({
       rt: runtimeTools(),
       goal: "answer the question",
-      model: convexModel("vendor/unknown-paid-model", { entrypoint: "public_ask" }),
+      model: convexModel(UNPRICED_DECLARED, { entrypoint: "public_ask" }),
       tools: [],
       maxSteps: 1,
       priceStep: () => 0.01,
@@ -570,11 +587,12 @@ describe("Convex free-auto model routing", () => {
     expect(result.usage.costUsd).toBeGreaterThan(0);
   });
 
-  it("blocks an unknown paid route before the provider call when a hard turn budget is present", async () => {
+  it("blocks an unpriced paid route before the provider call when a hard turn budget is present", async () => {
+    process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
     const fetchSpy = vi.fn();
     vi.stubGlobal("fetch", fetchSpy);
 
-    const error = await convexModel("vendor/unknown-paid-model", { entrypoint: "public_ask" }).next({
+    const error = await convexModel(UNPRICED_DECLARED, { entrypoint: "public_ask" }).next({
       system: "Answer.",
       messages: [{ role: "user", content: "hello" }],
       tools: [],
@@ -586,7 +604,7 @@ describe("Convex free-auto model routing", () => {
     expect((error as QualityFailoverError).receipt).toMatchObject({
       stopReason: "spend_budget",
       routeAttempts: [],
-      skippedRoutes: [{ routeId: "vendor/unknown-paid-model", reason: "spend_budget" }],
+      skippedRoutes: [{ routeId: "claude-sonnet-4-5", reason: "spend_budget" }],
     });
   });
 
diff --git a/tests/modelAdapterProviderNeutralRoute.test.ts b/tests/modelAdapterProviderNeutralRoute.test.ts
index 54e64c17..c662aab5 100644
--- a/tests/modelAdapterProviderNeutralRoute.test.ts
+++ b/tests/modelAdapterProviderNeutralRoute.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { normalizeInteropModelRoute } from "../src/nodeagent/integrations/modelInterop";
+import { DEFAULT_AGENT_MODEL } from "../convex/modelDefaults";
 import {
   getProviderForModel,
   NODEAGENT_FREE_AUTO_MODEL,
@@ -34,7 +35,8 @@ vi.mock("@ai-sdk/google", () => ({
 }));
 
 const OPENROUTER_MODEL = "nvidia/nemotron-3-super-120b-a12b:free";
-const GOOGLE_MODEL = "gemini-3.5-flash";
+// The direct-Google fallback id is the default-model constant (was the literal "gemini-3.5-flash", deprecated 2026-10-08).
+const GOOGLE_MODEL = DEFAULT_AGENT_MODEL;
 const ROUTING_ENV = [
   "OPENROUTER_API_KEY",
   "OPENROUTER_FREE_MODEL_CACHE_MS",
@@ -63,9 +65,18 @@ function successfulTurn(modelId: string) {
   };
 }
 
+/**
+ * The paid Gemini leg is a free -> paid fallback (SPEC A.0.10): it needs an explicit allowPaidFallback AND a meter to
+ * reserve against. Every test below that expects the leg to run authorizes it; the default-policy test refuses it.
+ */
 async function runNeutralRoute() {
-  const { model } = await import("../src/nodeagent/models/adapter");
-  const route = model(NODEAGENT_FREE_AUTO_MODEL, { freeAutoMode: "structured", entrypoint: "system" });
+  const { createSpendMeter, model } = await import("../src/nodeagent/models/adapter");
+  const route = model(NODEAGENT_FREE_AUTO_MODEL, {
+    freeAutoMode: "structured",
+    entrypoint: "system",
+    dispatch: { maxRetries: 3, crossModelFallback: true, allowPaidFallback: true },
+    meter: createSpendMeter(1),
+  });
   const step = await route.next({
     system: "Return JSON only.",
     messages: [{ role: "user", content: "emit a structured edit plan" }],
@@ -162,8 +173,10 @@ describe("provider-neutral NodeAgent free-first routing", () => {
           billing: {
             free: false,
             classification: "catalog_priced",
-            inputPer1M: 1.5,
-            outputPer1M: 9,
+            // gemini-3.8-flash vendor list price, read 2026-10-10 (SPEC A.2.9 R-row; pricingAsOf in modelCatalog).
+            // Was 1.5 / 9 for the deprecated gemini-3.5-flash.
+            inputPer1M: 0.75,
+            outputPer1M: 3.75,
           },
         },
       },
@@ -171,6 +184,36 @@ describe("provider-neutral NodeAgent free-first routing", () => {
     expect(step.providerRoute?.basis).toContain("billing:account_free_tier:not_asserted");
   });
 
+  it("never dispatches paid Gemini under the default policy: no allowPaidFallback and no meter, so the free failure is the answer", async () => {
+    process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+    generateTextMock.mockRejectedValue(new Error("AI_RetryError: Failed after 3 attempts. Last error: Rate limit exceeded: free-models-per-day-high-balance."));
+    const { createSpendMeter, model } = await import("../src/nodeagent/models/adapter");
+    // The first failure cools the free route, so later attempts see the cooldown instead of the quota error: both are the free route's own failure.
+    const FREE_FAILURE = /Rate limit exceeded|candidates cooling down/;
+    const turn = { system: "Return JSON only.", messages: [{ role: "user" as const, content: "emit a structured edit plan" }], tools: [] };
+
+    // Default dispatch policy (3 retries, cross-model fallback allowed) - what every unconfigured caller gets.
+    await expect(model(NODEAGENT_FREE_AUTO_MODEL, { freeAutoMode: "structured", entrypoint: "system" }).next(turn)).rejects.toThrow(FREE_FAILURE);
+    // Authorization without a reservation is not enough either, nor a meter without authorization.
+    await expect(model(NODEAGENT_FREE_AUTO_MODEL, { freeAutoMode: "structured", entrypoint: "system", dispatch: { maxRetries: 3, crossModelFallback: true, allowPaidFallback: true } }).next(turn)).rejects.toThrow(FREE_FAILURE);
+    await expect(model(NODEAGENT_FREE_AUTO_MODEL, { freeAutoMode: "structured", entrypoint: "system", meter: createSpendMeter(1) }).next(turn)).rejects.toThrow(FREE_FAILURE);
+
+    const dispatched = generateTextMock.mock.calls.map((call) => call[0].model.provider);
+    expect(dispatched.length).toBeGreaterThan(0);
+    expect(dispatched.every((provider) => provider === "openrouter"), `no paid request was made: ${dispatched.join(",")}`).toBe(true);
+  });
+
+  it("never falls back to paid Gemini when the dispatch policy forbids cross-model fallback", async () => {
+    process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+    generateTextMock.mockRejectedValue(new Error("AI_RetryError: Failed after 3 attempts. Last error: Rate limit exceeded: free-models-per-day-high-balance."));
+    const { model } = await import("../src/nodeagent/models/adapter");
+    // The same quota exhaustion as above, but under the ladder receipt policy: the free route's failure is the answer.
+    const route = model(NODEAGENT_FREE_AUTO_MODEL, { freeAutoMode: "structured", entrypoint: "system", dispatch: { maxRetries: 0, crossModelFallback: false } });
+
+    await expect(route.next({ system: "Return JSON only.", messages: [{ role: "user", content: "emit a structured edit plan" }], tools: [] })).rejects.toThrow(/Rate limit exceeded/);
+    expect(generateTextMock.mock.calls.map((call) => call[0].model)).toEqual([{ provider: "openrouter", id: OPENROUTER_MODEL }]);
+  });
+
   it("falls back to direct Gemini when every governed free route is cooling", async () => {
     process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
     recordOpenRouterFreeRouteOutcome({
diff --git a/tests/modelAliasClaude.test.ts b/tests/modelAliasClaude.test.ts
index 535bcda6..1c690837 100644
--- a/tests/modelAliasClaude.test.ts
+++ b/tests/modelAliasClaude.test.ts
@@ -4,20 +4,34 @@
  * turn every Claude shortcut / dotted display id into the valid hyphenated API id.
  */
 import { describe, it, expect } from "vitest";
-import { resolveModelAlias } from "../src/nodeagent/models/modelCatalog";
+import { lookupModelAlias, resolveModelAlias, UnknownModelError } from "../src/nodeagent/models/modelCatalog";
 
 describe("resolveModelAlias — Claude dotted -> hyphenated API ids", () => {
   it("maps dotted display ids to the hyphenated API ids the Anthropic API accepts", () => {
     expect(resolveModelAlias("claude-sonnet-4.6")).toBe("claude-sonnet-4-6");
     expect(resolveModelAlias("claude-haiku-4.5")).toBe("claude-haiku-4-5");
-    // opus display lags (4.7) the latest available API id (4-8)
-    expect(resolveModelAlias("claude-opus-4.7")).toBe("claude-opus-4-8");
+    // Was "claude-opus-4-8" (the display id lagged the API id, so a 4.7 request silently ran 4.8). SPEC A.2.9 makes the
+    // mapping exact: modelCatalog.ts:612-620's regex is replaced by an explicit table with claude-opus-4.7 -> claude-opus-4-7.
+    expect(resolveModelAlias("claude-opus-4.7")).toBe("claude-opus-4-7");
+  });
+
+  it("maps the 5.5 display ids and rewrites no id that is not in the table", () => {
+    expect(resolveModelAlias("claude-haiku-5.5")).toBe("claude-haiku-5-5");
+    expect(resolveModelAlias("claude-sonnet-5.5")).toBe("claude-sonnet-5-5");
+    expect(resolveModelAlias("claude-opus-5.5")).toBe("claude-opus-5-5");
+    // no regex: an unlisted dotted id passes through unchanged instead of being rewritten into a guess. Round 3 (SPEC A.0.10):
+    // resolveModelAlias also REFUSES it (it was `.toBe("claude-future-9.9")` and was then dispatched); the no-rewrite
+    // property is asserted on lookupModelAlias, the alias table read that does not route.
+    expect(lookupModelAlias("claude-future-9.9")).toBe("claude-future-9.9");
+    expect(() => resolveModelAlias("claude-future-9.9")).toThrow(UnknownModelError);
+    // OpenRouter slugs keep their dots (A.0.5: wire ids per transport)
+    expect(resolveModelAlias("anthropic/claude-sonnet-5.5")).toBe("anthropic/claude-sonnet-5.5");
   });
 
   it("resolves shortcuts through to the hyphenated API id (2-hop)", () => {
     expect(resolveModelAlias("claude-sonnet")).toBe("claude-sonnet-4-6");
     expect(resolveModelAlias("sonnet")).toBe("claude-sonnet-4-6");
-    expect(resolveModelAlias("claude-opus")).toBe("claude-opus-4-8");
+    expect(resolveModelAlias("claude-opus")).toBe("claude-opus-4-8"); // shortcut unchanged: still the newest 4.x
     expect(resolveModelAlias("claude-haiku")).toBe("claude-haiku-4-5");
   });
 
diff --git a/tests/modelCatalogRefresh.test.ts b/tests/modelCatalogRefresh.test.ts
new file mode 100644
index 00000000..df78b7d8
--- /dev/null
+++ b/tests/modelCatalogRefresh.test.ts
@@ -0,0 +1,112 @@
+/**
+ * 2026-10 model refresh (SPEC Part A §A.2.9): catalog invariants. Persisted rooms keep working (old strings stay
+ * valid), while no live lane, tier list or fallback chain points at a retired, shut-down or prior-users-only id.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  claudeDefaultEffort,
+  forbidsForcedToolChoice,
+  getModelPricing,
+  getProviderForModel,
+  isClaude55Id,
+  isModelAllowedForTier,
+  llmModelCatalog,
+  modelFallbackChains,
+  resolveModelAlias,
+} from "../src/nodeagent/models/modelCatalog";
+import { modelMaxOutputTokens } from "../src/nodeagent/models/outputTokens";
+
+/** Ids that fail (retired / shut down) or are closed to new users (gemini-2.5-*, OpenRouter expiry 2026-10-20). */
+const DEAD_IN_LIVE_LANES = [
+  "claude-opus-4", "claude-opus-4.1", "claude-sonnet-4", "claude-haiku-3.5",
+  "gemini-2.0-flash", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-3.1-flash-lite-preview",
+];
+
+describe("llmModelCatalog task lanes", () => {
+  it("lists the 5.5 Claude ids first in every Anthropic lane, with the 4.x ids kept behind them", () => {
+    for (const [task, ids] of Object.entries(llmModelCatalog.anthropic)) {
+      expect(ids[0], task).toMatch(/^claude-(haiku|sonnet)-5-5$/);
+    }
+    expect(llmModelCatalog.anthropic.agent).toEqual(expect.arrayContaining(["claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5", "claude-haiku-4.5", "claude-opus-4.7"]));
+  });
+
+  it("no Gemini lane offers a dead id; chat is [gemini-3.8-flash, gemini-3.5-flash-lite]", () => {
+    expect(llmModelCatalog.gemini.chat).toEqual(["gemini-3.8-flash", "gemini-3.5-flash-lite"]);
+    for (const [task, ids] of Object.entries(llmModelCatalog.gemini)) {
+      for (const dead of DEAD_IN_LIVE_LANES) expect(ids, `${task}: ${dead}`).not.toContain(dead);
+    }
+  });
+
+  it("every id in every lane is routable and priced", () => {
+    for (const [provider, lanes] of Object.entries(llmModelCatalog)) {
+      for (const [task, ids] of Object.entries(lanes)) {
+        for (const id of ids) {
+          expect(getProviderForModel(id), `${provider}/${task}/${id} provider`).not.toBeNull();
+          expect(getModelPricing(resolveModelAlias(id)), `${provider}/${task}/${id} price`).not.toBeNull();
+        }
+      }
+    }
+  });
+});
+
+describe("entitlement tiers (exact-string match)", () => {
+  it("admit the new ids and still admit the old strings persisted rows carry", () => {
+    for (const tier of ["anonymous", "free"] as const) {
+      for (const id of ["claude-haiku-5-5", "gemini-3.5-flash-lite", "claude-haiku-4.5"]) expect(isModelAllowedForTier(id, tier), `${tier}/${id}`).toBe(true);
+    }
+    expect(isModelAllowedForTier("gemini-3.1-flash-lite-preview", "anonymous")).toBe(true); // old string, kept
+    expect(isModelAllowedForTier("claude-opus-5-5", "anonymous")).toBe(false); // not on the cheap tier
+    expect(isModelAllowedForTier("claude-opus-5-5", "pro")).toBe(true);
+  });
+});
+
+describe("fallback chains", () => {
+  const chains = Object.entries(modelFallbackChains);
+
+  it("have no retired, shut-down or prior-users-only member", () => {
+    for (const [key, chain] of chains) for (const dead of DEAD_IN_LIVE_LANES) expect(chain, `${key} -> ${dead}`).not.toContain(dead);
+  });
+
+  it("every member is routable, and the 5.5 ids have chains of their own", () => {
+    for (const [key, chain] of chains) for (const id of chain) expect(getProviderForModel(id), `${key} -> ${id}`).not.toBeNull();
+    for (const id of ["claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5"]) {
+      expect(modelFallbackChains[id]?.length, id).toBeGreaterThan(0);
+    }
+  });
+
+  it("keeps the default route and the other new Gemini ids chain-less, as on main (no unqualified cross-provider failover)", () => {
+    for (const id of ["gemini-3.8-flash", "gemini-3.6-flash", "gemini-3.5-flash-lite"]) expect(modelFallbackChains[id], id).toBeUndefined();
+  });
+
+  it("keeps a chain for each retired key so a persisted room on one of them still has an escape route", () => {
+    for (const key of ["claude-opus-4.1", "claude-opus-4", "claude-sonnet-4", "gemini-2.5-flash", "gemini-2.5-pro", "gemini-3.1-flash-lite-preview"]) {
+      expect(modelFallbackChains[key]?.length, key).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("§1.3 request-shape facts are keyed by exact id", () => {
+  it("forbids a forced tool_choice for Sonnet/Opus 5.5 (both transports) but not Haiku 5.5 or 4.x", () => {
+    for (const id of ["claude-sonnet-5-5", "claude-opus-5-5", "anthropic/claude-sonnet-5.5", "anthropic/claude-opus-5.5"]) expect(forbidsForcedToolChoice(id), id).toBe(true);
+    for (const id of ["claude-haiku-5-5", "anthropic/claude-haiku-5.5", "claude-sonnet-4-6", "gemini-3.8-flash", "z-ai/glm-5.2"]) expect(forbidsForcedToolChoice(id), id).toBe(false);
+  });
+
+  it("pins the §1.3 default effort per 5.5 id and none elsewhere", () => {
+    expect([claudeDefaultEffort("claude-haiku-5-5"), claudeDefaultEffort("claude-sonnet-5-5"), claudeDefaultEffort("claude-opus-5-5")]).toEqual(["medium", "high", "medium"]);
+    expect(claudeDefaultEffort("claude-opus-4-8")).toBeUndefined();
+    expect(isClaude55Id("claude-opus-4-8")).toBe(false);
+  });
+
+  it("floors the output cap at 2048 for 5.5 ids only", () => {
+    const saved = process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS;
+    process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS = "1024";
+    try {
+      expect(modelMaxOutputTokens("claude-sonnet-5-5")).toBe(2048);
+      expect(modelMaxOutputTokens("anthropic/claude-haiku-5.5")).toBe(2048);
+      expect(modelMaxOutputTokens("claude-haiku-4-5")).toBe(1024);
+      expect(modelMaxOutputTokens()).toBe(1024);
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS; else process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS = saved;
+    }
+  });
+});
diff --git a/tests/modelCostClass.test.ts b/tests/modelCostClass.test.ts
new file mode 100644
index 00000000..a6a9fba3
--- /dev/null
+++ b/tests/modelCostClass.test.ts
@@ -0,0 +1,249 @@
+/**
+ * SPEC A.0.10 - cost class is preserved and unknown ids fail closed (NodeRoom, PR model-refresh/noderoom).
+ *
+ * Persona: an operator who runs rooms on free OpenRouter models and keeps AGENT_FALLBACK_MODEL (or the Convex
+ * AGENT_FALLBACK_MODELS list) pointing at a paid Gemini for the day OpenRouter is down. Failures to prevent:
+ *   1. a typo or a made-up id (`gemini-9-flash-unknown`, `claude-opus-4.9`) is dispatched to a paid provider
+ *      instead of being refused;
+ *   2. an outage on a FREE model silently bills the operator by falling back to a paid model nobody reserved against.
+ * Every test drives the repo's own builders (`resolveModelAlias`, adapter `model()`, `convexModel()`) with a fake
+ * `fetch`, so "no request was made" is observed on the wire, not read off the code.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSpendMeter, MAX_DISPATCH_RECORDS, model } from "../src/nodeagent/models/adapter";
+import { convexModel } from "../src/nodeagent/models/convexModel";
+import {
+  isFreeModelId,
+  lookupModelAlias,
+  resolveModelAlias,
+  UnknownModelError,
+} from "../src/nodeagent/models/modelCatalog";
+import { OPENROUTER_FREE_AUTO_MODEL } from "../src/nodeagent/models/openRouterFreeModels";
+
+const FREE = "cohere/north-mini-code:free"; // a concrete, catalog-priced free model
+const PAID = "gemini-3.8-flash";
+const TURN = { system: "s", messages: [{ role: "user" as const, content: "hi" }], tools: [] };
+const UNKNOWN_PAID = ["gemini-9-flash-unknown", "acme/paid-unknown-model", "claude-opus-4.9", "gpt-9-unknown", "made-up"];
+
+type Call = { url: string; provider: "openrouter" | "google" | "anthropic" | "openai" | "other" };
+let calls: Call[] = [];
+const providerOf = (url: string): Call["provider"] =>
+  url.includes("openrouter.ai") ? "openrouter" : url.includes("googleapis.com") ? "google" : url.includes("anthropic.com") ? "anthropic" : url.includes("openai.com") ? "openai" : "other";
+
+/** OpenRouter is down (503) while Google answers; every request is recorded by provider. */
+function openRouterDownGoogleUp() {
+  calls = [];
+  vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    calls.push({ url, provider: providerOf(url) });
+    if (providerOf(url) === "google") {
+      return new Response(JSON.stringify({
+        candidates: [{ content: { role: "model", parts: [{ text: "ok" }] }, finishReason: "STOP", index: 0 }],
+        usageMetadata: { promptTokenCount: 100, candidatesTokenCount: 20, totalTokenCount: 120 },
+      }), { status: 200, headers: { "content-type": "application/json" } });
+    }
+    return new Response(JSON.stringify({ error: { message: "Service unavailable", code: 503 } }), { status: 503, headers: { "content-type": "application/json" } });
+  });
+}
+const paidCalls = () => calls.filter((c) => c.provider === "google" || c.provider === "anthropic" || c.provider === "openai");
+
+const ENV = ["AGENT_FALLBACK_MODEL", "AGENT_FALLBACK_MODELS", "GOOGLE_GENERATIVE_AI_API_KEY", "OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"] as const;
+const saved: Record<string, string | undefined> = {};
+beforeEach(() => {
+  for (const k of ENV) { saved[k] = process.env[k]; delete process.env[k]; }
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+  process.env.OPENROUTER_API_KEY = "test-openrouter-key";
+  process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+  process.env.OPENAI_API_KEY = "test-openai-key";
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+  for (const k of ENV) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; }
+});
+
+describe("unknown ids fail closed at the resolver and at both public boundaries", () => {
+  it.each(UNKNOWN_PAID)("resolveModelAlias(%s) throws UnknownModelError", (id) => {
+    expect(() => resolveModelAlias(id)).toThrow(UnknownModelError);
+    expect(lookupModelAlias(id), "the lenient lookup used by pricing readers still returns the input").toBe(id);
+  });
+
+  it.each(UNKNOWN_PAID)("adapter model(%s) and convexModel(%s) throw before any request, metered or not", async (id) => {
+    openRouterDownGoogleUp();
+    expect(() => model(id)).toThrow(UnknownModelError);
+    expect(() => model(id, { meter: createSpendMeter(10) })).toThrow(UnknownModelError);
+    expect(() => convexModel(id)).toThrow(UnknownModelError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("an unknown id configured as the fallback is refused too, after the primary's own failed request", async () => {
+    openRouterDownGoogleUp();
+    process.env.AGENT_FALLBACK_MODEL = "gemini-9-flash-unknown";
+    await expect(model(FREE, { dispatch: { maxRetries: 0, crossModelFallback: true } }).next(TURN)).rejects.toBeInstanceOf(UnknownModelError);
+    expect(calls.map((c) => c.provider)).toEqual(["openrouter"]); // only the primary's request; the unknown fallback was never dispatched
+
+    expect(() => convexModel(FREE, { fallbackModelIds: ["gemini-9-flash-unknown"] })).toThrow(UnknownModelError);
+  });
+
+  it.each([
+    ["vendor/not-in-catalog:free", "a :free suffix"],
+    ["made-up-free", "a -free suffix"],
+    ["Acme/New-Model:FREE", "a :free suffix in any case"],
+  ])("the unknown free-looking id %s (%s) resolves to the verified free route, never a paid default", async (id) => {
+    openRouterDownGoogleUp();
+    expect(resolveModelAlias(id)).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(isFreeModelId(resolveModelAlias(id))).toBe(true);
+    expect(model(id).name).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(convexModel(id).name).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("catalog ids, aliases and old persisted strings still resolve (nothing the catalog knows is refused)", () => {
+    expect(resolveModelAlias(PAID)).toBe(PAID);
+    expect(resolveModelAlias("free")).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(resolveModelAlias("openrouter-auto")).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(resolveModelAlias("claude-sonnet")).toBe("claude-sonnet-4-6");
+    expect(resolveModelAlias("claude-sonnet-4.5")).toBe("claude-sonnet-4-5"); // priced under its dotted id only
+    expect(resolveModelAlias("nodeagent/free-auto")).toBe("nodeagent/free-auto");
+    expect(resolveModelAlias(FREE)).toBe(FREE);
+  });
+
+  it("Object.prototype keys are not catalog ids", () => {
+    for (const id of ["constructor", "__proto__", "toString"]) expect(() => resolveModelAlias(id), id).toThrow(UnknownModelError);
+  });
+});
+
+describe("a free request never becomes a paid request (adapter path)", () => {
+  beforeEach(() => { process.env.AGENT_FALLBACK_MODEL = PAID; });
+  const POLICY = { maxRetries: 0, crossModelFallback: true };
+
+  it("the default policy: a concrete :free model that is down does NOT fall through to AGENT_FALLBACK_MODEL; the free model's error surfaces", async () => {
+    vi.useFakeTimers();
+    openRouterDownGoogleUp();
+    const outcome = model(FREE).next(TURN).then(() => null, (e: unknown) => e); // DEFAULT_DISPATCH_POLICY: 3 retries, fallback allowed
+    await vi.advanceTimersByTimeAsync(120_000);
+    expect(await outcome).toBeInstanceOf(Error);
+    expect(calls.length).toBeGreaterThan(0);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("allowPaidFallback alone is not enough: without a meter nothing reserves the paid model, so it is not dispatched", async () => {
+    openRouterDownGoogleUp();
+    await expect(model(FREE, { dispatch: { ...POLICY, allowPaidFallback: true } }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("a meter alone is not enough either: the caller must say allowPaidFallback", async () => {
+    openRouterDownGoogleUp();
+    const meter = createSpendMeter(10);
+    await expect(model(FREE, { dispatch: POLICY, meter }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+    expect(meter.dispatches.every((d) => !d.fallbackUsed)).toBe(true);
+  });
+
+  it("allowPaidFallback AND a meter: the paid fallback is reserved against the meter and then dispatched", async () => {
+    openRouterDownGoogleUp();
+    const meter = createSpendMeter(10);
+    const step = await model(FREE, { dispatch: { ...POLICY, allowPaidFallback: true }, meter }).next(TURN);
+    expect(step.text).toBe("ok");
+    expect(paidCalls()).toHaveLength(1);
+    const paid = meter.dispatches.find((d) => d.fallbackUsed);
+    expect(paid).toMatchObject({ resolvedModel: PAID, fallbackUsed: true });
+    expect(paid!.costUsd).toBeGreaterThan(0);
+    expect(meter.spentUsd).toBeGreaterThanOrEqual(paid!.costUsd);
+  });
+
+  it("a paid fallback the meter cannot afford is refused before it is sent, even with allowPaidFallback", async () => {
+    openRouterDownGoogleUp();
+    const meter = createSpendMeter(1e-9);
+    await expect(model(FREE, { dispatch: { ...POLICY, allowPaidFallback: true }, meter }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("a free -> free fallback is the same cost class and needs nothing", async () => {
+    openRouterDownGoogleUp();
+    process.env.AGENT_FALLBACK_MODEL = "nvidia/nemotron-3-ultra-550b-a55b:free";
+    await expect(model(FREE, { dispatch: POLICY }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(calls.map((c) => c.provider)).toEqual(["openrouter", "openrouter"]);
+    expect(calls[1].url).toContain("openrouter.ai");
+  });
+
+  it("a paid primary keeps its fallback behaviour (paid -> paid, and paid -> free, are not free -> paid)", async () => {
+    calls = [];
+    vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      calls.push({ url, provider: providerOf(url) });
+      return new Response(JSON.stringify({ error: { code: 503, message: "Service unavailable" } }), { status: 503, headers: { "content-type": "application/json" } });
+    });
+    process.env.AGENT_FALLBACK_MODEL = FREE;
+    await expect(model(PAID, { dispatch: POLICY }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(calls.map((c) => c.provider)).toEqual(["google", "openrouter"]);
+  });
+});
+
+describe("a free request never becomes a paid request (Convex path)", () => {
+  it("fallbackModelIds with a paid model on a free primary: dropped, the paid provider is never called", async () => {
+    openRouterDownGoogleUp();
+    await expect(convexModel(FREE, { fallbackModelIds: [PAID] }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("the deployment env list (AGENT_FALLBACK_MODELS) is held to the same rule", async () => {
+    openRouterDownGoogleUp();
+    process.env.AGENT_FALLBACK_MODELS = PAID;
+    const { configuredConvexModelFallbacks } = await import("../src/nodeagent/models/convexModel");
+    await expect(convexModel(FREE, { fallbackModelIds: configuredConvexModelFallbacks(FREE, process.env) }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("allowPaidFallback without a reservation budget (no maxCostUsd on next()) is still blocked", async () => {
+    openRouterDownGoogleUp();
+    await expect(convexModel(FREE, { fallbackModelIds: [PAID], allowPaidFallback: true }).next(TURN)).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("a finite maxCostUsd without allowPaidFallback is still blocked", async () => {
+    openRouterDownGoogleUp();
+    await expect(convexModel(FREE, { fallbackModelIds: [PAID] }).next({ ...TURN, maxCostUsd: 1 })).rejects.toBeInstanceOf(Error);
+    expect(paidCalls()).toEqual([]);
+  });
+
+  it("allowPaidFallback with a finite maxCostUsd: the paid candidate is estimated against the budget and then dispatched", async () => {
+    openRouterDownGoogleUp();
+    const step = await convexModel(FREE, { fallbackModelIds: [PAID], allowPaidFallback: true }).next({ ...TURN, maxCostUsd: 1 });
+    expect(step.text).toBe("ok");
+    expect(paidCalls()).toHaveLength(1);
+  });
+
+  it("a paid primary keeps its paid fallback with no flag (cost class preserved, not narrowed)", async () => {
+    openRouterDownGoogleUp();
+    // PAID is Google, which is up; make the fallback list start from a model that fails: an OpenRouter paid model.
+    const step = await convexModel("qwen/qwen3.7-plus", { fallbackModelIds: [PAID] }).next(TURN);
+    expect(step.text).toBe("ok");
+    expect(calls.map((c) => c.provider)).toEqual(["openrouter", "google"]);
+  });
+});
+
+describe("the spend meter stays honest past its record cap (A.0.3 receipt honesty)", () => {
+  it("request 4097 is counted and priced but has no row, and the shortfall is a number a receipt can carry", async () => {
+    openRouterDownGoogleUp();
+    const meter = createSpendMeter(10_000);
+    const m = model(PAID, { dispatch: { maxRetries: 0, crossModelFallback: false }, meter });
+    for (let i = 0; i < MAX_DISPATCH_RECORDS + 1; i++) await m.next(TURN);
+    expect(meter.requests).toBe(MAX_DISPATCH_RECORDS + 1);
+    expect(meter.dispatches).toHaveLength(MAX_DISPATCH_RECORDS);
+    expect(meter.droppedDispatches).toBe(1);
+    // spentUsd covers all 4097 requests; the rows cover 4096 of them, so a cost taken from rows would understate by exactly one request.
+    const rowsUsd = meter.dispatches.reduce((sum, d) => sum + d.costUsd, 0);
+    expect(meter.spentUsd).toBeGreaterThan(rowsUsd);
+    expect(meter.spentUsd - rowsUsd).toBeCloseTo(meter.dispatches[0].costUsd, 12);
+  }, 30_000);
+
+  it("a run under the cap drops nothing", async () => {
+    openRouterDownGoogleUp();
+    const meter = createSpendMeter(10);
+    await model(PAID, { dispatch: { maxRetries: 0, crossModelFallback: false }, meter }).next(TURN);
+    expect(meter.droppedDispatches).toBe(0);
+    expect(meter.dispatches).toHaveLength(meter.requests);
+  });
+});
diff --git a/tests/modelKnownIds.test.ts b/tests/modelKnownIds.test.ts
new file mode 100644
index 00000000..f6d54e22
--- /dev/null
+++ b/tests/modelKnownIds.test.ts
@@ -0,0 +1,182 @@
+/**
+ * SPEC A.0.4 + A.0.10 - the fail-closed resolver refuses only ids the repo truly does not know.
+ *
+ * Persona: a banker opens the mobile app and picks "Claude Fable 5" (one of the six shipped picker choices); an
+ * evaluator runs `ladder:free --free-auto-top` and the benchmark with a frozen route. Failures to prevent:
+ *   1. the resolver treats "no price row" as "unknown", so a shipped or frozen id throws before it reaches the provider;
+ *   2. a concrete `:free` id the repo names is silently rewritten to `openrouter/free-auto`, so the run measures the
+ *      auto router under the concrete label.
+ * Every list below is read from its owning source, so a new id added there without a catalog entry fails here.
+ */
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { MODEL_REGISTRY } from "../src/landing/modelRegistry";
+import { allAgentLlmRoutes, OPENROUTER_TOP_PAID_AGENT_ROUTES, resolveRouteSet, SUPPORTED_MODEL_ROUTES } from "../scripts/benchmark/modelEvalConfig";
+import { DEFAULT_TOP_PAID_MODEL } from "../convex/modelDefaults";
+import { model } from "../src/nodeagent/models/adapter";
+import { chooseNodeAgentRoute, type NodeAgentTaskType } from "../src/nodeagent/core/adaptiveRouter";
+import { convexModel } from "../src/nodeagent/models/convexModel";
+import { getModelPricing, llmModelCatalog, lookupModelAlias, modelPricing, resolveModelAlias, UnknownModelError } from "../src/nodeagent/models/modelCatalog";
+import { OPENROUTER_FREE_AUTO_MODEL, OPENROUTER_KNOWN_FREE_IDS } from "../src/nodeagent/models/openRouterFreeModels";
+
+/** Frozen benchmark identity: the default of bankertoolbench-nodeagent-clean-sequential.mjs (SPEC A.2.9 freeze row). */
+const btbDefault = /const modelId = args\.modelId \?\? "([^"]+)"/.exec(readFileSync("scripts/bankertoolbench-nodeagent-clean-sequential.mjs", "utf8"))?.[1] ?? "";
+
+/** Every other FREEZE / DEFER id in SPEC A.2.9 that a resolver can reach. */
+const FROZEN_SITE_IDS = ["z-ai/glm-5.2", "moonshotai/kimi-k3", "gpt-5.4", "minimax/minimax-m3", "deepseek/deepseek-v4-flash", "gpt-5-mini", "google/gemini-3-flash-preview", "gemini-3.1-flash-lite", "z-ai/glm-4.7-flash", "cohere/north-mini-code:free"];
+
+const llmCatalogIds = Object.values(llmModelCatalog).flatMap((byTask) => Object.values(byTask).flat());
+
+function expectUnchanged(id: string) {
+  const resolved = resolveModelAlias(id);
+  expect(resolved, `resolveModelAlias(${id}) must not reroute`).toBe(lookupModelAlias(id));
+  if (lookupModelAlias(id) !== OPENROUTER_FREE_AUTO_MODEL) expect(resolved).not.toBe(OPENROUTER_FREE_AUTO_MODEL);
+  expect(model(id).name).toBe(resolved);
+  expect(convexModel(id).name).toBe(resolved);
+}
+
+/**
+ * SPEC-v9 section 1.2 wire ids, every transport (D1: an id in 1.2 is known). Typed here from the spec table on purpose:
+ * the spec lives outside this repo, so this is the one place a reader checks the transcription.
+ */
+const SPEC_1_2_WIRE_IDS = [
+  "claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5", "claude-fable-5-1",
+  "anthropic/claude-haiku-5.5", "anthropic/claude-sonnet-5.5", "anthropic/claude-opus-5.5", "anthropic/claude-fable-5.1",
+  "anthropic.claude-haiku-5-5", "anthropic.claude-sonnet-5-5", "anthropic.claude-opus-5-5", "anthropic.claude-fable-5-1",
+  "gemini-3.8-flash", "gemini-3.6-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.8-flash-tts", "gemini-3.8-live",
+  "google/gemini-3.8-flash", "google/gemini-3.6-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.1-pro-preview",
+  "gpt-6.1-sol", "openai/gpt-6.1-sol", "gpt-6-luna", "openai/gpt-6-luna", "gpt-5.4-mini", "openai/gpt-5.4-mini",
+  "moonshotai/kimi-k3", "z-ai/glm-5.3", "minimax/minimax-m3", "nvidia/nemotron-3-super-120b-a12b:free",
+  // the spec's 2026-10-10 live :free list
+  "apodex/apodex-1.1-mini:free", "dots-studio/dots-3-note-preview:free", "liquid/lfm-2.5-2.6b:free", "nvidia/nemotron-3.5-lightning:free",
+  "thinkingmachines/inkling-small:free", "poolside/laguna-s-2.1:free", "thinkingmachines/inkling:free", "poolside/laguna-xs-2.1:free",
+  "cohere/north-mini-code:free", "nvidia/nemotron-3.5-content-safety:free", "nvidia/nemotron-3-ultra-550b-a55b:free",
+  "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free", "google/gemma-4-26b-a4b-it:free", "google/gemma-4-31b-it:free",
+];
+
+describe("every id the repo ships, freezes or lists resolves as itself", () => {
+  it.each(OPENROUTER_TOP_PAID_AGENT_ROUTES.map((r) => r.route))("top-paid route %s (`model-eval-matrix --route-set top-paid` goes through model(id))", expectUnchanged);
+  it.each([...new Set(allAgentLlmRoutes().map((r) => r.route))])("agent route %s", expectUnchanged);
+  // Review round 6, defect 4: the benchmark lane labels its decision `openrouter/auto`, and main resolved it as itself.
+  const ROUTER_TASKS: NodeAgentTaskType[] = ["collaboration", "research", "private_consult", "analysis", "router", "spreadsheet", "finance", "benchmark"];
+  it.each(ROUTER_TASKS)("the model chooseNodeAgentRoute names for task %s (any risk, latency or free setting)", (task) => {
+    for (const risk of ["low", "medium", "high"] as const) for (const latency of ["interactive", "batch", "overnight"] as const) for (const freeAllowed of [true, false]) {
+      expectUnchanged(chooseNodeAgentRoute({ task, risk, latency, freeAllowed }).model);
+    }
+  });
+  // Review round 6, defect 4: the old regex hyphenated every dotted claude id. Every dotted claude id the catalog still prices or
+  // chains is kept (retired models stay valid for persisted rows), so each must still map to the hyphenated wire form.
+  it.each(Object.keys(modelPricing).filter((id) => /^claude-[a-z]+-[0-9]+\.[0-9]+$/.test(id)))("dotted retained id %s resolves to its hyphenated wire id and the wire id is priced", (id) => {
+    const wire = id.replace(/\./g, "-");
+    expect(resolveModelAlias(id)).toBe(wire);
+    expect(getModelPricing(wire), `${wire} has no price row`).not.toBeNull();
+  });
+  it.each(["top-paid", "supported", "champions", "free", "research", "collaboration"])("every id of route set %s", (set) => {
+    for (const id of resolveRouteSet(set)) expectUnchanged(id);
+  });
+  it.each(SPEC_1_2_WIRE_IDS)("SPEC section 1.2 wire id %s", expectUnchanged);
+
+  it("the BTB default was read from the frozen script", () => expect(btbDefault).toBe("gpt-4.1-mini"));
+
+  it.each(MODEL_REGISTRY.map((m) => m.id))("mobile picker choice %s", expectUnchanged);
+  it.each(SUPPORTED_MODEL_ROUTES.map((r) => r.route))("benchmark route %s", expectUnchanged);
+  it.each([...new Set(llmCatalogIds)])("tier-map id %s (Chat.tsx resolves all of these at render)", expectUnchanged);
+  it.each([...OPENROUTER_KNOWN_FREE_IDS])("known free id %s is never rerouted to the auto router", expectUnchanged);
+  it.each([btbDefault, `openai/${btbDefault}`, ...FROZEN_SITE_IDS])("frozen site id %s", expectUnchanged);
+
+  it("the spec's live :free list is known (13 of the 15 used to be rewritten)", () => {
+    for (const id of ["nvidia/nemotron-3-super-120b-a12b:free", "google/gemma-4-26b-a4b-it:free", "poolside/laguna-xs-2.1:free", "poolside/laguna-s-2.1:free", "liquid/lfm-2.5-2.6b:free"]) {
+      expect(resolveModelAlias(id)).toBe(id);
+    }
+    expect(OPENROUTER_KNOWN_FREE_IDS.size).toBeGreaterThanOrEqual(15);
+  });
+});
+
+describe("what is still refused or rerouted (A.0.10 is intact)", () => {
+  it.each(["gemini-9-flash-unknown", "acme/paid-unknown-model", "claude-opus-4.9", "gpt-9-unknown"])("%s throws", (id) => {
+    expect(() => resolveModelAlias(id)).toThrow(UnknownModelError);
+  });
+
+  it("an unknown free-looking id still resolves to the verified free route, a known one to itself", () => {
+    expect(resolveModelAlias("vendor/not-in-catalog:free")).toBe(OPENROUTER_FREE_AUTO_MODEL);
+    expect(resolveModelAlias("nvidia/nemotron-3-super-120b-a12b:free")).toBe("nvidia/nemotron-3-super-120b-a12b:free");
+  });
+});
+
+describe("SPEC-v9 D2: the top_paid default is the newest qualifying :free row of the recorded public OpenRouter list", () => {
+  const snapshot = JSON.parse(readFileSync("docs/eval/openrouter-free-models-2026-10-16.json", "utf8")) as {
+    fetchedAt: string; selected: string; rows: Array<{ id: string; created: number; contextLength: number; outputModalities: string[]; tools: boolean; toolChoice: boolean; structuredOutputs: boolean; expirationDate: string | null }>;
+  };
+
+  it("DEFAULT_TOP_PAID_MODEL is the row a re-selection by the stated criteria returns, and the snapshot records its fetch time", () => {
+    const qualifying = snapshot.rows
+      .filter((r) => r.tools && r.toolChoice && r.structuredOutputs && r.contextLength >= 256_000 && r.outputModalities.includes("text") && r.id.endsWith(":free"))
+      .sort((a, b) => b.created - a.created);
+    expect(qualifying[0].id).toBe(DEFAULT_TOP_PAID_MODEL);
+    expect(snapshot.selected).toBe(DEFAULT_TOP_PAID_MODEL);
+    expect(snapshot.fetchedAt).toBe("2026-10-16T11:32:04Z");
+  });
+
+  it("it resolves as itself, is a free route, and is never rerouted to the auto router", () => {
+    expectUnchanged(DEFAULT_TOP_PAID_MODEL);
+    expect(OPENROUTER_KNOWN_FREE_IDS.has(DEFAULT_TOP_PAID_MODEL)).toBe(true);
+  });
+});
+
+describe("SPEC-v9 D1: an operator-selected id in an eval or smoke script is passed through", () => {
+  // Persona: an evaluator runs `ladder:free --free-auto-top` or `benchmark/run.ts <id>` with a :free row picked from the live
+  // OpenRouter list, or a CLI id this catalog has never seen. origin/main measured it under its own label; the fail-closed
+  // resolver threw (unknown paid id) or measured the auto router under the concrete label (unknown :free id).
+  it.each(["openrouter/owl-alpha:free", "qwen/qwen3.9-coder:free", "acme/paid-unknown-model"])("model(%s, { operatorSelected }) keeps the id as written", (id) => {
+    expect(model(id, { operatorSelected: true }).name).toBe(id);
+  });
+
+  it("server code (no option) is unchanged: an unknown paid id throws, an unknown :free id goes to the verified free route", () => {
+    expect(() => model("acme/paid-unknown-model")).toThrow(UnknownModelError);
+    expect(model("qwen/qwen3.9-coder:free").name).toBe(OPENROUTER_FREE_AUTO_MODEL);
+  });
+
+  it("the alias table still applies to an operator-selected id", () => {
+    expect(model("claude-sonnet", { operatorSelected: true }).name).toBe(lookupModelAlias("claude-sonnet"));
+  });
+
+  it("convexModel keeps the same contract: an operator-selected unknown id is passed through, server code still throws", () => {
+    expect(convexModel("vendor/unknown-x", { operatorSelected: true }).name).toBe("vendor/unknown-x");
+    expect(convexModel("foo/bar:free", { operatorSelected: true }).name).toBe("foo/bar:free");
+    expect(convexModel("claude-sonnet", { operatorSelected: true }).name).toBe(lookupModelAlias("claude-sonnet"));
+    expect(() => convexModel("vendor/unknown-x")).toThrow(UnknownModelError);
+    expect(convexModel("foo/bar:free").name).toBe(OPENROUTER_FREE_AUTO_MODEL);
+  });
+
+  // Source pin: these are CLI entry points whose model id is typed by an operator (flag or env). Every call into the
+  // adapter or convexModel resolver must carry the option, wherever the call sits and however many lines it spans.
+  const OPERATOR_ENTRY_POINTS = [
+    "scripts/benchmark/run.ts", "scripts/proofloop-free-model-gauge.ts", "evals/ladder.ts", "scripts/spreadsheetbench-run.ts",
+    "evals/chatIntakeRuntime.ts", "evals/financeModelLive.ts", "evals/managedLockPerf.ts", "evals/professionalRuntimeLive.ts",
+    "scripts/halo-live-path-calibration.ts", "scripts/startup-diligence-provider-eval.ts", "scripts/sfn-nonbtb-nodeagent-runner.ts",
+    "src/eval/bankerToolBenchNodeAgentGeneral.ts",
+  ];
+  const resolverCalls = (src: string): string[] => {
+    const calls: string[] = [];
+    const callStart = /(?<![\w$])(?:\.)?(?:model|realModel|routedModel|convexModel)\(/g;
+    for (let m = callStart.exec(src); m; m = callStart.exec(src)) {
+      const lineStart = src.lastIndexOf("\n", m.index) + 1;
+      const prefix = src.slice(lineStart, m.index);
+      if (/^\s*(?:\/\/|\*|import\b|(?:export\s+)?(?:async\s+)?function\b)/.test(prefix) || (prefix.split("`").length - 1) % 2 === 1) continue; // comment, declaration, or inside a template string
+      let depth = 0;
+      let i = m.index + m[0].length - 1;
+      for (; i < src.length; i++) {
+        if (src[i] === "(") depth++;
+        else if (src[i] === ")" && --depth === 0) break;
+      }
+      calls.push(src.slice(m.index, i + 1));
+    }
+    return calls;
+  };
+
+  it.each(OPERATOR_ENTRY_POINTS)("%s passes operatorSelected on every resolver call", (file) => {
+    const calls = resolverCalls(readFileSync(file, "utf8"));
+    expect(calls.length, `${file}: no resolver call found, the pin is not looking at anything`).toBeGreaterThan(0);
+    for (const call of calls) expect(call, `${file}: ${call.slice(0, 80)}`).toContain("operatorSelected: true");
+  });
+});
diff --git a/tests/modelPricingAgreement.test.ts b/tests/modelPricingAgreement.test.ts
new file mode 100644
index 00000000..aedd2ac8
--- /dev/null
+++ b/tests/modelPricingAgreement.test.ts
@@ -0,0 +1,285 @@
+/**
+ * Pricing agreement (SPEC Part A rule A.0.6): every pricing source in NodeRoom is loaded and must agree on
+ * {inPerM, outPerM} per (id, transport).
+ *
+ * Pricing sources in this repo (enumerated; each is read below or excluded with its reason):
+ *   1. modelCatalog.modelPricing          - the only hand-typed table (every row added by the refresh carries pricingAsOf)
+ *   2. modelCatalog.getModelPricing       - accessor over (1)
+ *   3. adapter.priceRun / priceRequest / priceRequestStrict - the AI-SDK adapter's cost functions. `priceRun` prices usage
+ *      SUMMED over requests (base tier only); `priceRequest*` price ONE request (tier-aware); the ladder meter uses
+ *      priceRequestStrict
+ *   4. convexModel.convexPriceRun / convexPriceRequest - the Convex-safe model's aggregate and per-request cost functions
+ *   5. creditModel.estimateCostFor        - credit estimates (a private priceRun over (1), aggregate)
+ *   6. proofloopModelTracking             - estimateModelCostUsd over (1), aggregate
+ *   7. scripts/benchmark/run.ts           - pricingAtRunFor PREFERS the OpenRouter /models snapshot (priceFromOpenRouterInfo,
+ *      dated by that run's `fetchedAt` + `routeSnapshotId`, recorded on every row's pricingAtRun) and falls back to (1)
+ *      (catalogPricingAtRun) or a flagged $1/$5 `fallback_estimate`
+ *   8. scripts/proofloop-proxy-model-sweep.ts - prices from the live OpenRouter /models catalog fetched when the sweep
+ *      runs (dated `fetchedAt` per row); it has no fallback table
+ * Sources 7 and 8 own no table, but their per-token -> per-1M CONVERSION is code that can disagree with (1) (a x1e5 for
+ * a x1e6 is a tenfold undercharge), so both run on a dated OpenRouter /models fixture below and must produce the
+ * catalog's {inPerM, outPerM} for every OpenRouter-transport row. 7 is loaded through scripts/benchmark/pricingAtRun.ts
+ * (split out of run.ts, which runs the benchmark on import); 8 runs as the script itself in --dry-run.
+ * Chat.tsx price chips read (1). A new hand-typed table must be added here or deleted.
+ *
+ * Vendor list prices were read 2026-10-10 (model-defaults frontier.json, platform.claude.com + ai.google.dev pricing).
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { priceRequest, priceRequestStrict, priceRun, reserveDispatch, UnpricedModelError } from "../src/nodeagent/models/adapter";
+import { convexPriceRequest, convexPriceRun } from "../src/nodeagent/models/convexModel";
+import { CREDIT_MODE_SPECS, estimateCostFor } from "../src/nodeagent/core/creditModel";
+import { calculateRequestCost, getModelPricing, modelPricing } from "../src/nodeagent/models/modelCatalog";
+import { modelMaxOutputTokens } from "../src/nodeagent/models/outputTokens";
+import { proofloopModelCostFieldsForRun } from "../src/eval/proofloopModelTracking";
+import { catalogPricingAtRun, pricingAtRunFor, type RouteSnapshot } from "../scripts/benchmark/pricingAtRun";
+
+const PRICING_AS_OF = "2026-10-10";
+
+/** (canonical id, wire id per transport) -> vendor list price per 1M tokens. */
+type RefreshRow = {
+  canonical: string; transport: string; id: string; inPerM: number; outPerM: number;
+  /** Cache-read rate of the row's own tier (vendor page: Haiku 5.5 "Cache read $0.01 / $0.05"); `null` = the vendor page lists none, so the row must carry none. */
+  cachedInPerM?: number | null;
+  /** Rates for a prompt above `aboveInputTokens` (SPEC §1.3: claude-haiku-5-5 is $0.50/$2.50 above 100K). */
+  longContext?: { aboveInputTokens: number; inPerM: number; outPerM: number; cachedInPerM?: number };
+};
+const HAIKU_LONG = { aboveInputTokens: 100_000, inPerM: 0.50, outPerM: 2.50, cachedInPerM: 0.05 };
+const REFRESH_ROWS: RefreshRow[] = [
+  { canonical: "claude-haiku-5-5", transport: "anthropic", id: "claude-haiku-5-5", inPerM: 0.10, outPerM: 0.50, cachedInPerM: 0.01, longContext: HAIKU_LONG }, // <=100K-token tier
+  { canonical: "claude-haiku-5-5", transport: "openrouter", id: "anthropic/claude-haiku-5.5", inPerM: 0.10, outPerM: 0.50, cachedInPerM: 0.01, longContext: HAIKU_LONG },
+  { canonical: "claude-sonnet-5-5", transport: "anthropic", id: "claude-sonnet-5-5", inPerM: 2, outPerM: 10, cachedInPerM: 0.10 }, // frontier.json "cache read $0.10"
+  { canonical: "claude-sonnet-5-5", transport: "openrouter", id: "anthropic/claude-sonnet-5.5", inPerM: 2, outPerM: 10 },
+  { canonical: "claude-opus-5-5", transport: "anthropic", id: "claude-opus-5-5", inPerM: 4, outPerM: 20, cachedInPerM: 0.20 }, // frontier.json "cache read $0.20"
+  { canonical: "claude-opus-5-5", transport: "openrouter", id: "anthropic/claude-opus-5.5", inPerM: 4, outPerM: 20 },
+  // Intro price through 2026-12-31; $1.50 / $7.50 from 2027-01-01 (re-price then: NodeRoom CHANGELOG/server/model-defaults.md).
+  { canonical: "gemini-3.8-flash", transport: "google", id: "gemini-3.8-flash", inPerM: 0.75, outPerM: 3.75, cachedInPerM: 0.075 },
+  { canonical: "gemini-3.6-flash", transport: "google", id: "gemini-3.6-flash", inPerM: 0.75, outPerM: 3.75 },
+  { canonical: "gemini-3.5-flash-lite", transport: "google", id: "gemini-3.5-flash-lite", inPerM: 0.30, outPerM: 2.50, cachedInPerM: 0.03 },
+  // The id claude-opus-4.7 now resolves to (it used to be rewritten to 4-8). frontier.json lists only "$5 in / $25 out": no cached rate.
+  { canonical: "claude-opus-4-7", transport: "anthropic", id: "claude-opus-4-7", inPerM: 5, outPerM: 25, cachedInPerM: null },
+];
+
+const M = 1_000_000;
+
+describe("pricing sources agree per (id, transport)", () => {
+  for (const row of REFRESH_ROWS) {
+    it(`${row.canonical} on ${row.transport} (${row.id}) is $${row.inPerM}/$${row.outPerM} in every source`, () => {
+      const table = modelPricing[row.id];
+      const accessor = getModelPricing(row.id);
+      expect(table, "modelPricing row").toBeDefined();
+      expect(accessor).toBe(table);
+      expect({ inPerM: table.inputPer1M, outPerM: table.outputPer1M }).toEqual({ inPerM: row.inPerM, outPerM: row.outPerM });
+      expect(table.pricingAsOf).toBe(PRICING_AS_OF);
+      expect(table.longContext && { aboveInputTokens: table.longContext.aboveInputTokens, inPerM: table.longContext.inputPer1M, outPerM: table.longContext.outputPer1M, cachedInPerM: table.longContext.cachedInputPer1M }).toEqual(row.longContext);
+      if (row.cachedInPerM === null) expect(table.cachedInputPer1M, "the vendor page lists no cache-read rate").toBeUndefined();
+      else if (row.cachedInPerM !== undefined) expect(table.cachedInputPer1M, "cache-read rate of the row's own tier").toBe(row.cachedInPerM);
+
+      // Cost functions, probed at the base tier: 100K prompt tokens (the tier edge itself) or 100K output tokens,
+      // scaled to per-million, so the result IS the base per-million price whether or not the row is tiered.
+      const P = 100_000;
+      for (const [source, cost] of [["priceRun", priceRun], ["priceRequest", priceRequest], ["priceRequestStrict", priceRequestStrict], ["convexPriceRun", convexPriceRun], ["convexPriceRequest", convexPriceRequest]] as const) {
+        expect(cost(row.id, P, 0) * (M / P), `${source} input`).toBeCloseTo(row.inPerM, 9);
+        expect(cost(row.id, 0, M), `${source} output`).toBeCloseTo(row.outPerM, 9);
+      }
+      // Source 6 (proofloopModelTracking.estimateModelCostUsd, private) is reached through the exported cost-fields function with
+      // no reported cost: 100K in + 1M out must cost (100K x in + 1M x out) / 1M from the same row, aggregate (base tier).
+      const fields = proofloopModelCostFieldsForRun({ modelId: row.id, tokensIn: P, tokensOut: M });
+      expect(fields.costAccounting.source, `${row.id} proofloop estimate source`).toBe("catalog_estimate");
+      expect(fields.costUsd, "proofloopModelTracking").toBeCloseTo((P * row.inPerM + M * row.outPerM) / M, 7); // the source rounds to 8 decimals
+    });
+
+    if (row.longContext) {
+      const tier = row.longContext;
+      it(`${row.id} bills a prompt above ${tier.aboveInputTokens} tokens at $${tier.inPerM}/$${tier.outPerM} in every cost and reservation path`, () => {
+        const above = tier.aboveInputTokens + 1;
+        const out = 1_000;
+        const expectedLong = (above * tier.inPerM + out * tier.outPerM) / M;
+        const expectedBase = (tier.aboveInputTokens * row.inPerM + out * row.outPerM) / M;
+        // Per-REQUEST prices (a prompt above the edge is one request's prompt): the tier applies.
+        for (const [source, cost] of [["priceRequest", priceRequest], ["priceRequestStrict", priceRequestStrict], ["convexPriceRequest", convexPriceRequest], ["calculateRequestCost", calculateRequestCost]] as const) {
+          expect(cost(row.id, above, out), `${source} above the edge`).toBeCloseTo(expectedLong, 12);
+          expect(cost(row.id, tier.aboveInputTokens, out), `${source} at the edge (the lower tier includes it)`).toBeCloseTo(expectedBase, 12);
+        }
+        // Per-AGGREGATE prices: usage summed over requests has no single prompt, so no tier is ever inferred from it.
+        const expectedFlat = (above * row.inPerM + out * row.outPerM) / M;
+        for (const [source, cost] of [["priceRun", priceRun], ["convexPriceRun", convexPriceRun]] as const) {
+          expect(cost(row.id, above, out), `${source} on summed usage`).toBeCloseTo(expectedFlat, 12);
+        }
+        expect(proofloopModelCostFieldsForRun({ modelId: row.id, tokensIn: above, tokensOut: out }).costUsd, "proofloopModelTracking on summed usage").toBeCloseTo(expectedFlat, 7);
+        // Cache reads above the edge bill at the tier's own cache-read rate (was the tier INPUT rate: $0.50/M, not $0.05/M).
+        if (tier.cachedInPerM !== undefined) {
+          expect(calculateRequestCost(row.id, above, 0, true), "cached tokens above the edge").toBeCloseTo((above * tier.cachedInPerM) / M, 12);
+          expect(calculateRequestCost(row.id, tier.aboveInputTokens, 0, true), "cached tokens at the edge").toBeCloseTo((tier.aboveInputTokens * (row.cachedInPerM ?? 0)) / M, 12);
+        }
+        // Reservation: the review's case, 120K prompt + the 8192-token cap, must reserve $0.08048, not $0.016096.
+        const cap = modelMaxOutputTokens(row.id);
+        const reserve = reserveDispatch(row.id, 120_000, Number.POSITIVE_INFINITY);
+        expect(reserve).toBeCloseTo((120_000 * tier.inPerM + cap * tier.outPerM) / M, 12);
+        if (row.id === "claude-haiku-5-5") expect(reserve).toBeCloseTo(0.08048, 9);
+      });
+    }
+  }
+
+  it("two sub-100K requests whose prompts sum past 100K cost the sum of two base-tier requests, not one long-context request", () => {
+    // Review case: priceRun("claude-haiku-5-5", 120000, 2000) used to be $0.065 (tiered on the SUM) while the two settled
+    // 60K/1K requests cost $0.013 (5x overstatement).
+    const id = "claude-haiku-5-5";
+    const perRequest = priceRequest(id, 60_000, 1_000);
+    expect(perRequest).toBeCloseTo((60_000 * 0.10 + 1_000 * 0.50) / M, 12);
+    expect(2 * perRequest).toBeCloseTo(0.013, 9);
+    expect(convexPriceRequest(id, 60_000, 1_000) * 2).toBeCloseTo(0.013, 9);
+    for (const [source, cost] of [["priceRun", priceRun], ["convexPriceRun", convexPriceRun]] as const) {
+      expect(cost(id, 120_000, 2_000), `${source} on the summed usage`).toBeCloseTo(2 * perRequest, 12);
+    }
+    // One genuine 120K request is still billed at the tier.
+    expect(priceRequest(id, 120_000, 2_000)).toBeCloseTo((120_000 * 0.50 + 2_000 * 2.50) / M, 12);
+    expect(priceRequest(id, 120_000, 2_000)).toBeCloseTo(0.065, 9);
+  });
+
+  it("sources 7 and 8 (OpenRouter-snapshot readers) hold no hand-typed price table of their own", () => {
+    // pricingAtRun.ts keeps exactly one numeric price pair: the flagged `fallback_estimate` ($1/$5) for an id with no row anywhere.
+    const pricing = readFileSync("scripts/benchmark/pricingAtRun.ts", "utf8");
+    expect([...pricing.matchAll(/(?:input|output)Per1M:\s*\d/g)].length).toBe(2);
+    expect(pricing).toMatch(/source: "fallback_estimate",\s*inputPer1M: 1,\s*outputPer1M: 5,/);
+    expect(pricing).toMatch(/source: "openrouter_snapshot"/);
+    expect(readFileSync("scripts/benchmark/run.ts", "utf8")).toContain('from "./pricingAtRun"'); // run.ts reads the module under test, not a copy
+    const sweep = readFileSync("scripts/proofloop-proxy-model-sweep.ts", "utf8");
+    expect([...sweep.matchAll(/(?:input|output|cachedInput)Per1M:\s*\d/g)]).toEqual([]);
+    expect(sweep).toContain("fetchedAt");
+  });
+
+  describe("sources 7 and 8 on a dated OpenRouter /models fixture", () => {
+    // The OpenRouter /models response of 2026-10-10 (snapshot read for SPEC §1.2), USD per TOKEN as OpenRouter serves it.
+    // Literal strings on purpose: the per-token -> per-1M conversion is what these tests exercise.
+    const FIXTURE_FETCHED_AT = "2026-10-10T00:00:00.000Z";
+    const OPENROUTER_MODELS_2026_10_10 = {
+      data: [
+        { id: "anthropic/claude-haiku-5.5", context_length: 1_000_000, pricing: { prompt: "0.0000001", completion: "0.0000005", input_cache_read: "0.00000001" }, supported_parameters: ["tools"] },
+        { id: "anthropic/claude-sonnet-5.5", context_length: 1_000_000, pricing: { prompt: "0.000002", completion: "0.00001", input_cache_read: "0.0000001" }, supported_parameters: ["tools"] },
+        { id: "anthropic/claude-opus-5.5", context_length: 1_000_000, pricing: { prompt: "0.000004", completion: "0.00002", input_cache_read: "0.0000002" }, supported_parameters: ["tools"] },
+      ],
+    };
+    const openRouterRows = REFRESH_ROWS.filter((r) => r.transport === "openrouter");
+
+    it("the fixture covers every OpenRouter-transport refresh row", () => {
+      expect(openRouterRows.map((r) => r.id).sort()).toEqual(OPENROUTER_MODELS_2026_10_10.data.map((m) => m.id).sort());
+    });
+
+    it("source 7: benchmark/pricingAtRun prices each OpenRouter row from the snapshot at the catalog's {inPerM, outPerM}; the catalog fallback agrees too", () => {
+      const snapshot: RouteSnapshot = {
+        routeSnapshotId: "fixture-2026-10-10",
+        fetchedAt: FIXTURE_FETCHED_AT,
+        source: "openrouter",
+        modelsById: new Map(OPENROUTER_MODELS_2026_10_10.data.map((m) => [m.id, m])),
+      };
+      for (const row of REFRESH_ROWS) {
+        const table = modelPricing[row.id];
+        const fromCatalog = catalogPricingAtRun(row.id);
+        expect(fromCatalog.source, row.id).toBe("catalog");
+        expect({ inPerM: fromCatalog.inputPer1M, outPerM: fromCatalog.outputPer1M }, `${row.id} catalog fallback`).toEqual({ inPerM: table.inputPer1M, outPerM: table.outputPer1M });
+        if (row.transport !== "openrouter") continue;
+        const fromSnapshot = pricingAtRunFor(row.id, snapshot);
+        expect(fromSnapshot.source, row.id).toBe("openrouter_snapshot");
+        expect(fromSnapshot.routeSnapshotId).toBe("fixture-2026-10-10");
+        expect(fromSnapshot.inputPer1M, `${row.id} snapshot input`).toBeCloseTo(table.inputPer1M, 9);
+        expect(fromSnapshot.outputPer1M, `${row.id} snapshot output`).toBeCloseTo(table.outputPer1M, 9);
+        if (table.cachedInputPer1M !== undefined) expect(fromSnapshot.cachedInputPer1M, `${row.id} snapshot cache read`).toBeCloseTo(table.cachedInputPer1M, 9);
+      }
+    });
+
+    describe("source 8: scripts/proofloop-proxy-model-sweep.ts (--dry-run, the script itself)", () => {
+      let dir: string | undefined;
+      afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+        if (dir) rmSync(dir, { recursive: true, force: true });
+        dir = undefined;
+      });
+
+      it("records pricingAtRun per model at the catalog's {inPerM, outPerM}", async () => {
+        dir = mkdtempSync(join(tmpdir(), "pricing-sweep-"));
+        const { externalBenchmarkLocalTaskIds } = await import("../proofloop/benchmarks/common/local-tasks");
+        const out = join(dir, "sweep.json");
+        const requested: string[] = [];
+        vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+          requested.push(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+          return new Response(JSON.stringify(OPENROUTER_MODELS_2026_10_10), { status: 200, headers: { "content-type": "application/json" } });
+        });
+        vi.spyOn(console, "log").mockImplementation(() => {});
+        const argvBefore = process.argv;
+        const exitBefore = process.exitCode;
+        process.argv = ["node", "proofloop-proxy-model-sweep.ts", "--dry-run", "--allow-failures", "--id", externalBenchmarkLocalTaskIds()[0],
+          "--models", openRouterRows.map((r) => r.id).join(","),
+          "--json-out", out, "--md-out", join(dir, "sweep.md"), "--html-out", join(dir, "sweep.html"), "--adapter-out-root", join(dir, "runs")];
+        vi.resetModules();
+        try {
+          await import("../scripts/proofloop-proxy-model-sweep");
+        } finally {
+          process.argv = argvBefore;
+          process.exitCode = exitBefore;
+        }
+        expect(requested).toEqual(["https://openrouter.ai/api/v1/models"]);
+        const rows = JSON.parse(readFileSync(out, "utf8")).rows as Array<{ modelId: string; pricingAtRun: { inputPer1M: number; outputPer1M: number; cachedInputPer1M: number | null; fetchedAt: string } | null }>;
+        expect(rows.map((r) => r.modelId).sort()).toEqual(openRouterRows.map((r) => r.id).sort());
+        for (const row of rows) {
+          const table = modelPricing[row.modelId];
+          expect(row.pricingAtRun, row.modelId).not.toBeNull();
+          expect(row.pricingAtRun!.inputPer1M, `${row.modelId} input`).toBeCloseTo(table.inputPer1M, 9);
+          expect(row.pricingAtRun!.outputPer1M, `${row.modelId} output`).toBeCloseTo(table.outputPer1M, 9);
+          if (table.cachedInputPer1M !== undefined) expect(row.pricingAtRun!.cachedInputPer1M, `${row.modelId} cache read`).toBeCloseTo(table.cachedInputPer1M, 9);
+        }
+      }, 30_000);
+    });
+  });
+
+  it("the same model costs the same on its direct and OpenRouter transports", () => {
+    const byCanonical = new Map<string, Array<{ inPerM: number; outPerM: number }>>();
+    for (const r of REFRESH_ROWS) byCanonical.set(r.canonical, [...(byCanonical.get(r.canonical) ?? []), { inPerM: modelPricing[r.id].inputPer1M, outPerM: modelPricing[r.id].outputPer1M }]);
+    for (const [canonical, prices] of byCanonical) {
+      for (const p of prices) expect(p, canonical).toEqual(prices[0]);
+    }
+  });
+
+  it("credit estimates price their model from the same table (creditModel's private priceRun)", () => {
+    for (const mode of Object.keys(CREDIT_MODE_SPECS) as Array<keyof typeof CREDIT_MODE_SPECS>) {
+      const spec = CREDIT_MODE_SPECS[mode];
+      const price = getModelPricing(spec.model);
+      expect(price, `${mode} model ${spec.model} must be priced`).not.toBeNull();
+      const expected = (spec.inputTokensPerRun * price!.inputPer1M + spec.outputTokensPerRun * price!.outputPer1M) / M;
+      expect(estimateCostFor(mode).llmUsd).toBeCloseTo(expected, 3); // creditModel rounds to 4 decimals (round4)
+    }
+  });
+
+  // Retired ids kept for persisted rows. Their prices are origin/main's own dotted rows ("official docs, April 2026" in main's block header)
+  // moved to the hyphenated wire id; no vendor page was re-read, so the date is main's month, "2026-04", not a new day. Every source must
+  // still agree on them, under either spelling.
+  it.each([
+    { dotted: "claude-opus-4.1", id: "claude-opus-4-1", inPerM: 15, outPerM: 75, cachedInPerM: 1.5 },
+    { dotted: "claude-haiku-3.5", id: "claude-haiku-3-5", inPerM: 0.8, outPerM: 4, cachedInPerM: 0.08 },
+  ])("retired $id keeps origin/main's undated price in every source, under either spelling", ({ dotted, id, inPerM, outPerM, cachedInPerM }) => {
+    expect(modelPricing[id]).toMatchObject({ inputPer1M: inPerM, outputPer1M: outPerM, cachedInputPer1M: cachedInPerM });
+    expect(modelPricing[id].pricingAsOf, "A.0.6: dated with the month main's block header cites").toBe("2026-04");
+    const P = 100_000;
+    for (const name of [id, dotted]) {
+      for (const [source, cost] of [["priceRun", priceRun], ["priceRequest", priceRequest], ["priceRequestStrict", priceRequestStrict], ["convexPriceRun", convexPriceRun], ["convexPriceRequest", convexPriceRequest]] as const) {
+        expect(cost(name, P, 0) * (M / P), `${source} ${name} input`).toBeCloseTo(inPerM, 9);
+        expect(cost(name, 0, M), `${source} ${name} output`).toBeCloseTo(outPerM, 9);
+      }
+      expect(proofloopModelCostFieldsForRun({ modelId: name, tokensIn: P, tokensOut: M }).costUsd, `proofloopModelTracking ${name}`).toBeCloseTo((P * inPerM + M * outPerM) / M, 7);
+    }
+  });
+
+  it("every dated row in the table carries a parseable pricingAsOf", () => {
+    for (const [id, row] of Object.entries(modelPricing)) {
+      if (row.pricingAsOf !== undefined) expect(Number.isNaN(Date.parse(row.pricingAsOf)), id).toBe(false);
+    }
+  });
+
+  it("an id with no row is refused by the strict price and guessed only by the legacy ones", () => {
+    expect(() => priceRequestStrict("gemini-9.9-unpriced-test", 1, 1)).toThrow(UnpricedModelError);
+    expect(priceRun("gemini-9.9-unpriced-test", M, 0)).toBe(1); // legacy fallback, kept for unbudgeted callers
+  });
+});
diff --git a/tests/modelRefreshAgentWire.test.ts b/tests/modelRefreshAgentWire.test.ts
new file mode 100644
index 00000000..0390592f
--- /dev/null
+++ b/tests/modelRefreshAgentWire.test.ts
@@ -0,0 +1,179 @@
+// @vitest-environment edge-runtime
+/**
+ * 2026-10 model refresh (SPEC Part A A.0.6, review round 5 defect 5) - the DEFAULT_AGENT_MODEL call sites driven through
+ * their real handlers, not pinned by regular expressions over the source.
+ *
+ * Persona: a room member asks the room agent (public_ask), asks their private agent, or a queued job with no recorded
+ * model is picked up by the job runner. Each handler is run with a convex-test database behind a fake Convex ctx and a fake
+ * `fetch`. What is asserted is what reaches the wire: the model id in the request URL and the absence of sampling keys.
+ * A downstream substitution (for example modelNameForEgress always returning the file-egress model) fails here; the
+ * source-level pins in modelRefreshCallSites.test.ts only say where the default is spelled.
+ *
+ * No test here can reach a provider: `fetch` is replaced before any handler runs.
+ */
+import { convexTest } from "convex-test";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import schema from "../convex/schema";
+import { api } from "../convex/_generated/api";
+import { hashToken } from "../convex/lib";
+import { DEFAULT_AGENT_MODEL } from "../convex/modelDefaults";
+import workflowSchema from "../node_modules/@convex-dev/workflow/dist/component/schema.js";
+import workpoolSchema from "../node_modules/@convex-dev/workpool/dist/component/schema.js";
+
+const modules = import.meta.glob("../convex/**/*.ts");
+const workflowModules = import.meta.glob("../node_modules/@convex-dev/workflow/dist/component/**/*.js");
+const workpoolModules = import.meta.glob("../node_modules/@convex-dev/workpool/dist/component/**/*.js");
+delete (modules as Record<string, unknown>)["../convex/agent.ts"]; // imported directly below; convex-test cannot bundle it
+delete (modules as Record<string, unknown>)["../convex/agentJobRunner.ts"];
+delete (modules as Record<string, unknown>)["../convex/embeddingRunner.ts"];
+
+vi.setConfig({ testTimeout: 60_000 }); // the first import of convex/agent.ts pulls in the whole runtime graph
+
+type Seen = { url: string; body: Record<string, any> };
+const seen: Seen[] = [];
+function installFakeTransport(options: { firstCallTool?: string } = {}) {
+  seen.length = 0;
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    let body: Record<string, any> = {};
+    try { body = JSON.parse(typeof init?.body === "string" ? init.body : "{}"); } catch { /* not JSON */ }
+    seen.push({ url, body });
+    const part = options.firstCallTool && seen.length === 1
+      ? { functionCall: { name: options.firstCallTool, args: {} } }
+      : { text: "ok" };
+    const reply = { candidates: [{ content: { role: "model", parts: [part] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5, totalTokenCount: 15 } };
+    return new Response(JSON.stringify(reply), { status: 200, headers: { "content-type": "application/json" } });
+  });
+}
+
+const FORBIDDEN_SAMPLING_KEYS = ["temperature", "top_p", "top_k", "topP", "topK"];
+function expectNoSampling(body: Record<string, any>) {
+  for (const key of FORBIDDEN_SAMPLING_KEYS) expect(body, key).not.toHaveProperty(key);
+  for (const key of FORBIDDEN_SAMPLING_KEYS) expect(body.generationConfig ?? {}, `generationConfig.${key}`).not.toHaveProperty(key);
+}
+
+const ENV_KEYS = [
+  "AGENT_MODEL", "AGENT_RESEARCH_MODEL", "AGENT_FILE_EGRESS_MODEL", "AGENT_MODEL_FILE_EGRESS", "AGENT_TOP_PAID_MODEL", "AGENT_FALLBACK_MODEL",
+  "GOOGLE_GENERATIVE_AI_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY", "CREDITS_ENFORCED", "NODEAGENT_ALLOWED_PROVIDERS",
+  "PROVIDER_EGRESS_ALLOWED_PROVIDERS", "PROVIDER_EGRESS_REQUIRE_ALLOWLIST", "NODEROOM_PRODUCTION", "NODEROOM_FREE_ONLY",
+] as const;
+const savedEnv: Record<string, string | undefined> = {};
+beforeEach(() => {
+  for (const k of ENV_KEYS) { savedEnv[k] = process.env[k]; delete process.env[k]; }
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  for (const k of ENV_KEYS) { if (savedEnv[k] === undefined) delete process.env[k]; else process.env[k] = savedEnv[k]; }
+});
+
+const token = "0123456789abcdefghijklmnopqrstuvwxyzTOKEN";
+
+async function setupRoom() {
+  const t = convexTest(schema, modules);
+  t.registerComponent("workflow", workflowSchema, workflowModules);
+  t.registerComponent("workflow/workpool", workpoolSchema, workpoolModules);
+  const now = Date.now();
+  const roomId = await t.run((ctx) => ctx.db.insert("rooms", { code: "TWIRE", title: "Wire test", hostId: "", autoAllow: true, status: "live" as const, createdAt: now }));
+  const memberId = await t.run(async (ctx) => ctx.db.insert("members", { roomId, name: "Host", role: "host" as const, anon: false, color: "#111111", authTokenHash: await hashToken(token), lastSeenAt: now }));
+  const proof = { actor: { kind: "user" as const, id: String(memberId), name: "Host" }, token };
+  await t.run((ctx) => ctx.db.patch(roomId, { hostId: String(memberId) }));
+  await t.run((ctx) => ctx.db.insert("agentSessions", { roomId, agentId: "agent_room", agentName: "Room NodeAgent", scope: "public" as const, status: "idle" as const, lastAction: "started", updatedAt: now }));
+  const artifactId = await t.run((ctx) => ctx.db.insert("artifacts", { roomId, kind: "sheet" as const, title: "Sheet", version: 1, order: [], updatedAt: now }));
+  return { t, roomId, artifactId, proof };
+}
+
+/** A Convex ctx whose queries, mutations and actions run against the convex-test database. */
+function ctxFor(t: Awaited<ReturnType<typeof setupRoom>>["t"]) {
+  return {
+    runQuery: (ref: any, args: any) => t.query(ref, args),
+    runMutation: (ref: any, args: any) => t.mutation(ref, args),
+    runAction: (ref: any, args: any) => t.action(ref, args),
+  };
+}
+
+describe("runPrivateAgent (convex/agent.ts, AGENT_MODEL ?? DEFAULT_AGENT_MODEL)", () => {
+  it("with AGENT_MODEL unset the private consult goes to gemini-3.8-flash with no sampling keys", async () => {
+    const { t, roomId, proof } = await setupRoom();
+    const { runPrivateAgent } = await import("../convex/agent");
+    installFakeTransport();
+    const out = await (runPrivateAgent as any)._handler(ctxFor(t), { roomId, requester: proof, goal: "Summarise the room." });
+    expect(out).toMatchObject({ ok: true, model: "gemini-3.8-flash" });
+    expect(DEFAULT_AGENT_MODEL).toBe("gemini-3.8-flash");
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:generateContent");
+    expectNoSampling(seen[0].body);
+  });
+
+  it("AGENT_MODEL keeps its precedence", async () => {
+    process.env.AGENT_MODEL = "gemini-3.6-flash";
+    const { t, roomId, proof } = await setupRoom();
+    const { runPrivateAgent } = await import("../convex/agent");
+    installFakeTransport();
+    await (runPrivateAgent as any)._handler(ctxFor(t), { roomId, requester: proof, goal: "Summarise the room." });
+    expect(seen[0].url).toContain("/models/gemini-3.6-flash:generateContent");
+  });
+
+  it("an AGENT_MODEL the catalog does not know never reaches the wire", async () => {
+    process.env.AGENT_MODEL = "gemini-not-in-catalog";
+    const { t, roomId, proof } = await setupRoom();
+    const { runPrivateAgent } = await import("../convex/agent");
+    installFakeTransport();
+    await expect((runPrivateAgent as any)._handler(ctxFor(t), { roomId, requester: proof, goal: "Summarise the room." })).rejects.toMatchObject({ name: "UnknownModelError" });
+    expect(seen).toHaveLength(0);
+  });
+});
+
+describe("runRoomAgent public_ask (convex/agent.ts, AGENT_MODEL ?? DEFAULT_AGENT_MODEL)", () => {
+  it("with AGENT_MODEL unset the room agent records gemini-3.8-flash and its first model call carries that id and no sampling keys", async () => {
+    const { t, roomId, artifactId, proof } = await setupRoom();
+    const { runRoomAgent } = await import("../convex/agent");
+    installFakeTransport({ firstCallTool: "list_artifacts" }); // one real tool step, then a text answer: the run completes and its trace is recorded
+    const out = await (runRoomAgent as any)._handler(ctxFor(t), { roomId, artifactId, requester: proof, goal: "Say hello." });
+    expect(out.model).toBe("gemini-3.8-flash");
+    const detail = await t.query(api.agentJobs.detail, { jobId: out.jobId, requester: proof });
+    expect(detail?.job.modelPolicy).toBe("gemini-3.8-flash");
+    expect(seen.length).toBeGreaterThan(0);
+    for (const req of seen) {
+      expect(req.url).toContain("/models/gemini-3.8-flash:");
+      expectNoSampling(req.body);
+    }
+  });
+});
+
+describe("agentJobRunner.runFreeAutoJobSlice (a claimed job with no modelPolicy: AGENT_MODEL ?? DEFAULT_AGENT_MODEL)", () => {
+  async function queuedJobWithoutModel(setup: Awaited<ReturnType<typeof setupRoom>>) {
+    const { t, roomId, artifactId, proof } = setup;
+    const created = await t.mutation(api.agentJobs.createOrReuse, {
+      roomId, artifactId, requester: proof, goal: "Say hello.", entrypoint: "public_ask" as const, scope: "public_room" as const,
+      modelPolicy: "gemini-3.8-flash", idempotencyKey: "wire-no-model", approvalPolicy: "auto_commit_safe" as const,
+      evidencePolicy: "public_only" as const, autoAllow: true,
+    });
+    await t.run((ctx) => ctx.db.patch(created.jobId, { modelPolicy: "" })); // a legacy / unset policy: the runner picks its own default
+    return created.jobId;
+  }
+
+  it("with AGENT_MODEL unset the slice's model call carries gemini-3.8-flash and no sampling keys", async () => {
+    const setup = await setupRoom();
+    const jobId = await queuedJobWithoutModel(setup);
+    const { runFreeAutoJobSlice } = await import("../convex/agentJobRunner");
+    installFakeTransport({ firstCallTool: "list_artifacts" });
+    await (runFreeAutoJobSlice as any)._handler(ctxFor(setup.t), { jobId });
+    expect(seen.length).toBeGreaterThan(0);
+    for (const req of seen) {
+      expect(req.url).toContain("/models/gemini-3.8-flash:");
+      expectNoSampling(req.body);
+    }
+  });
+
+  it("AGENT_MODEL keeps its precedence", async () => {
+    process.env.AGENT_MODEL = "gemini-3.6-flash";
+    const setup = await setupRoom();
+    const jobId = await queuedJobWithoutModel(setup);
+    const { runFreeAutoJobSlice } = await import("../convex/agentJobRunner");
+    installFakeTransport({ firstCallTool: "list_artifacts" });
+    await (runFreeAutoJobSlice as any)._handler(ctxFor(setup.t), { jobId });
+    expect(seen[0].url).toContain("/models/gemini-3.6-flash:");
+  });
+});
diff --git a/tests/modelRefreshCallSites.test.ts b/tests/modelRefreshCallSites.test.ts
new file mode 100644
index 00000000..0630a17b
--- /dev/null
+++ b/tests/modelRefreshCallSites.test.ts
@@ -0,0 +1,73 @@
+/**
+ * 2026-10 model refresh (SPEC Part A §A.2.9, rule A.0.6) — the migrated DEFAULT_AGENT_MODEL call sites.
+ *
+ * The constant itself is pinned by tests/modelCatalogRefresh.test.ts. The first three sites below are DRIVEN through their
+ * real handlers by tests/modelRefreshAgentWire.test.ts and the stream route (streaming.ts) by tests/modelRefreshServerRoles.test.ts
+ * (fake Convex ctx + fake fetch: the emitted model and the absence of sampling keys), so a downstream substitution fails there; the regular expressions here only pin where the default
+ * is spelled (re-inlining a literal, dropping the env chain, a third copy). The Chat composer is a React closure and
+ * stays source-pinned.
+ *
+ *   convex/agent.ts:346          runRoomAgent (public_ask)   process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL
+ *   convex/agent.ts:783          runPrivateAgent             process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL
+ *   convex/agentJobRunner.ts:512 runFreeAutoJobSlice         claimed.modelPolicy || (free ? free-auto : AGENT_MODEL ?? DEFAULT_AGENT_MODEL)
+ *   convex/streaming.ts:68       createPrivateReplyStream    process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL (egress check)
+ *   src/ui/Chat.tsx:1690         composerModelSelection      specificModelPolicy || defaultSpecificModel || DEFAULT_AGENT_MODEL
+ */
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_AGENT_MODEL } from "../convex/modelDefaults";
+
+const read = (file: string) => readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+/** Source with line and block comments blanked, so a mention of an old id in prose is not mistaken for code. */
+const code = (file: string) => read(file).replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:])\/\/.*$/gm, "$1");
+const count = (haystack: string, needle: RegExp) => [...haystack.matchAll(new RegExp(needle.source, needle.flags.includes("g") ? needle.flags : `${needle.flags}g`))].length;
+const OLD_OR_OTHER_GEMINI_LITERAL = /["'`]gemini-3\.\d+(?:-flash)?(?:-lite)?["'`]/;
+
+describe("DEFAULT_AGENT_MODEL call sites (model refresh)", () => {
+  it("the constant is the refreshed id", () => {
+    expect(DEFAULT_AGENT_MODEL).toBe("gemini-3.8-flash");
+  });
+
+  it("convex/agent.ts:346 runRoomAgent (public_ask) falls back to DEFAULT_AGENT_MODEL, behind AGENT_RESEARCH_MODEL for research", () => {
+    const src = code("convex/agent.ts");
+    expect(src).toMatch(/const requestedModelName = a\.mode === "research"\s*\? \(process\.env\.AGENT_RESEARCH_MODEL \?\? "minimax\/minimax-m3"\)\s*: \(process\.env\.AGENT_MODEL \?\? DEFAULT_AGENT_MODEL\);/);
+    expect(src).toMatch(/agentModel\(modelNameForEgress\(requestedModelName, "public_ask", egressArtifacts\), \{ entrypoint: "public_ask" \}\)/);
+  });
+
+  it("convex/agent.ts:783 runPrivateAgent falls back to DEFAULT_AGENT_MODEL", () => {
+    const src = code("convex/agent.ts");
+    expect(src).toMatch(/agentModel\(modelNameForEgress\(process\.env\.AGENT_MODEL \?\? DEFAULT_AGENT_MODEL, "private_agent", egressArtifacts\), \{ entrypoint: "private_agent" \}\)/);
+    expect(count(src, /process\.env\.AGENT_MODEL \?\? DEFAULT_AGENT_MODEL/)).toBe(2); // exactly the two roles; a third copy would be a new, untested site
+    expect(src).not.toMatch(OLD_OR_OTHER_GEMINI_LITERAL);
+  });
+
+  it("convex/agentJobRunner.ts:512 runFreeAutoJobSlice resolves an unset modelPolicy through AGENT_MODEL ?? DEFAULT_AGENT_MODEL", () => {
+    const src = code("convex/agentJobRunner.ts");
+    expect(src).toMatch(/const modelPolicy = claimed\.modelPolicy \|\| \(entrypoint === "free" \? "openrouter\/free-auto" : process\.env\.AGENT_MODEL \?\? DEFAULT_AGENT_MODEL\);/);
+    expect(src).not.toMatch(OLD_OR_OTHER_GEMINI_LITERAL);
+  });
+
+  it("convex/streaming.ts:68 createPrivateReplyStream checks egress for the same default model the stream route sends", () => {
+    const src = code("convex/streaming.ts");
+    expect(src).toMatch(/assertProviderEgressAllowed\(\{\s*model: process\.env\.AGENT_MODEL \?\? DEFAULT_AGENT_MODEL,\s*entrypoint: "private_agent",/);
+    expect(src).not.toMatch(OLD_OR_OTHER_GEMINI_LITERAL);
+  });
+
+  it("src/ui/Chat.tsx:1690 composerModelSelection falls back to DEFAULT_AGENT_MODEL after the user's choice and the room default", () => {
+    const src = code("src/ui/Chat.tsx");
+    expect(src).toMatch(/\{ mode: "specific", modelPolicy: specificModelPolicy \|\| defaultSpecificModel \|\| DEFAULT_AGENT_MODEL \}/);
+    expect(src).toMatch(/import \{ DEFAULT_AGENT_MODEL \} from "\.\.\/\.\.\/convex\/modelDefaults";/);
+  });
+
+  it("every site imports the one constant from convex/modelDefaults (no local copy)", () => {
+    for (const [file, from] of [
+      ["convex/agent.ts", "./modelDefaults"],
+      ["convex/agentJobRunner.ts", "./modelDefaults"],
+      ["convex/streaming.ts", "./modelDefaults"],
+      ["src/ui/Chat.tsx", "../../convex/modelDefaults"],
+    ] as const) {
+      expect(code(file), file).toMatch(new RegExp(`import \\{[^}]*\\bDEFAULT_AGENT_MODEL\\b[^}]*\\} from "${from.replace(/[./]/g, "\\$&")}";`));
+      expect(code(file), file).not.toMatch(/(?:const|let|var)\s+DEFAULT_AGENT_MODEL\b/);
+    }
+  });
+});
diff --git a/tests/modelRefreshRequestShape.test.ts b/tests/modelRefreshRequestShape.test.ts
new file mode 100644
index 00000000..45659cf6
--- /dev/null
+++ b/tests/modelRefreshRequestShape.test.ts
@@ -0,0 +1,421 @@
+/**
+ * 2026-10 model refresh (SPEC Part A §A.2.9, rule A.0.6): one request-shape test per changed role.
+ *
+ * Each test builds a REAL provider request through the repo's own builder (convexModel's direct-HTTP
+ * steps, the AI-SDK adapter, aiSdkReasoner, the LangChain bridge) with a fake transport (`fetch`), then asserts
+ *   - the wire `model` string is the §1.2 id, written here as a literal on purpose (not imported from the code
+ *     under test), and
+ *   - the keys the §1.3 row forbids for that id are absent from the body.
+ * These assertions fail against the pre-refresh literals (gemini-3.5-flash, claude-haiku-4-5, claude-sonnet-4, ...).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { anthropicModel, judge, model as adapterModel } from "../src/nodeagent/models/adapter";
+import { convexModel } from "../src/nodeagent/models/convexModel";
+import { DEFAULT_TOP_PAID_MODEL } from "../convex/modelDefaults";
+import { aiSdkReasoner } from "../src/nodeagent/capture/reasoning";
+import { createLangChainAgentModel } from "../src/nodeagent/integrations/langchain";
+import { createPiAiAdapter } from "../src/nodeagent/models/piAiAdapter";
+import { defaultRouteForTask, chooseNodeAgentRoute } from "../src/nodeagent/core/adaptiveRouter";
+import { providerParserModelCandidates } from "../src/nodeagent/models/providerParserLive";
+import { getModelPricing, getProviderForModel, resolveModelAlias, UnknownModelError } from "../src/nodeagent/models/modelCatalog";
+import type { AgentTool } from "../src/nodeagent/core/types";
+
+type Seen = { url: string; headers: Record<string, string>; body: Record<string, any> };
+
+const NOOP_TOOL: AgentTool = {
+  name: "noop",
+  description: "does nothing",
+  schema: z.object({ note: z.string().optional() }),
+  execute: async () => ({ ok: true }),
+};
+
+/** Sampling / reasoning / prefill keys that the §1.3 rows for the 5.5 and 3.x ids reject or deprecate. */
+const FORBIDDEN_SAMPLING_KEYS = ["temperature", "top_p", "top_k", "topP", "topK", "frequency_penalty", "presence_penalty"];
+
+function anthropicOk(model: string) {
+  return { id: "msg_test", type: "message", role: "assistant", model, content: [{ type: "text", text: "ok" }], stop_reason: "end_turn", stop_sequence: null, usage: { input_tokens: 10, output_tokens: 5 } };
+}
+function geminiOk() {
+  return { candidates: [{ content: { role: "model", parts: [{ text: "ok" }] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 10, candidatesTokenCount: 5, totalTokenCount: 15 } };
+}
+function chatOk(model: string) {
+  return { id: "gen-test", model, choices: [{ index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" }], usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 } };
+}
+
+const seen: Seen[] = [];
+function installFakeTransport(respond: (req: Seen) => unknown) {
+  seen.length = 0;
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const raw = typeof init?.body === "string" ? init.body : "{}";
+    const req: Seen = { url, headers: Object.fromEntries(new Headers(init?.headers).entries()), body: JSON.parse(raw) };
+    seen.push(req);
+    return new Response(JSON.stringify(respond(req)), { status: 200, headers: { "content-type": "application/json" } });
+  });
+}
+
+function expectNoSamplingKeys(body: Record<string, any>) {
+  for (const key of FORBIDDEN_SAMPLING_KEYS) expect(body, key).not.toHaveProperty(key);
+  expect(body.generationConfig ?? {}, "generationConfig").not.toHaveProperty("temperature");
+  expect(body.generationConfig?.thinkingConfig ?? {}, "thinkingConfig").not.toHaveProperty("thinkingBudget");
+}
+
+const ENV_KEYS = [
+  "ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "GOOGLE_GENERATIVE_AI_API_KEY", "OPENROUTER_API_KEY",
+  "AGENT_MODEL", "AGENT_MODEL_MAX_OUTPUT_TOKENS", "AGENT_FALLBACK_MODEL", "AGENT_RESEARCH_MODEL", "AGENT_ROUTER_MODEL",
+  "PROVIDER_PARSER_GEMINI_MODEL", "PROVIDER_PARSER_OPENAI_MODEL", "PROVIDER_PARSER_ANTHROPIC_MODEL", "PROVIDER_PARSER_OPENROUTER_MODEL",
+] as const;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  for (const k of ENV_KEYS) { savedEnv[k] = process.env[k]; delete process.env[k]; }
+  process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+  process.env.OPENROUTER_API_KEY = "test-openrouter-key";
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+  for (const k of ENV_KEYS) { if (savedEnv[k] === undefined) delete process.env[k]; else process.env[k] = savedEnv[k]; }
+});
+
+describe("Claude 5.5 over the direct Anthropic HTTP step (convexModel.anthropicStep)", () => {
+  for (const id of ["claude-haiku-5-5", "claude-sonnet-5-5", "claude-opus-5-5"] as const) {
+    it(`${id}: wire id, no sampling/thinking/tool_choice/prefill, max_tokens floored at 2048`, async () => {
+      installFakeTransport(() => anthropicOk(id));
+      // A cap sized for 4.5 (1024) would truncate a 5.5 reply because thinking counts toward max_tokens.
+      process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS = "1024";
+      await convexModel(id).next({
+        system: "s",
+        messages: [{ role: "user", content: "hi" }],
+        tools: [NOOP_TOOL],
+        toolChoice: "required",
+      });
+      expect(seen).toHaveLength(1);
+      const { body, url } = seen[0];
+      expect(url).toBe("https://api.anthropic.com/v1/messages");
+      expect(body.model).toBe(id);
+      expectNoSamplingKeys(body);
+      expect(body).not.toHaveProperty("thinking"); // budget_tokens is a 400 on 5.5
+      expect(body).not.toHaveProperty("tool_choice"); // Sonnet/Opus 5.5 400 on forced choice; Haiku sends none either
+      expect(body.messages.at(-1).role).toBe("user"); // assistant prefill is a 400 on 5.5
+      expect(body.max_tokens).toBeGreaterThanOrEqual(2048);
+    });
+  }
+
+  // SPEC §1.3: where a forced tool_choice is replaced by `auto`, the tool definitions carry strict: true instead.
+  for (const c of [{ id: "claude-haiku-5-5", strict: undefined }, { id: "claude-sonnet-5-5", strict: true }, { id: "claude-opus-5-5", strict: true }] as const) {
+    it(`${c.id}: a required tool choice ${c.strict ? "ships strict tool definitions" : "keeps plain tool definitions (a forced choice is accepted)"}`, async () => {
+      installFakeTransport(() => anthropicOk(c.id));
+      await convexModel(c.id).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required" });
+      expect(seen[0].body.tools[0].strict).toBe(c.strict);
+      await convexModel(c.id).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "auto" });
+      expect(seen[1].body.tools[0].strict, "no downgrade happened, so no strict").toBeUndefined();
+    });
+  }
+
+  it("a pre-5.5 id keeps the configured cap (the floor is keyed to the 5.5 ids only)", async () => {
+    installFakeTransport(() => anthropicOk("claude-haiku-4-5"));
+    process.env.AGENT_MODEL_MAX_OUTPUT_TOKENS = "1024";
+    await convexModel("claude-haiku-4-5").next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen[0].body.max_tokens).toBe(1024);
+  });
+
+  it("reads response content blocks by type (a leading thinking block does not hide the text)", async () => {
+    installFakeTransport(() => ({
+      ...anthropicOk("claude-haiku-5-5"),
+      content: [{ type: "thinking", thinking: "hmm", signature: "sig" }, { type: "text", text: "answer" }],
+    }));
+    const step = await convexModel("claude-haiku-5-5").next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(step.text).toBe("answer");
+  });
+});
+
+describe("anthropic/claude-*-5.5 over OpenRouter (convexModel.openAiCompatibleStep)", () => {
+  it("anthropic/claude-sonnet-5.5 (an operator-set AGENT_TOP_PAID_MODEL): forced tool_choice is sent as auto", async () => {
+    installFakeTransport(() => chatOk("anthropic/claude-sonnet-5.5"));
+    await convexModel("anthropic/claude-sonnet-5.5").next({
+      system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required",
+    });
+    const { body, url } = seen[0];
+    expect(url).toBe("https://openrouter.ai/api/v1/chat/completions");
+    expect(body.model).toBe("anthropic/claude-sonnet-5.5");
+    expect(body.tool_choice).toBe("auto");
+    expectNoSamplingKeys(body);
+  });
+
+  it("opus 5.5 is downgraded the same way; haiku 5.5 accepts a forced choice and keeps it", async () => {
+    installFakeTransport(() => chatOk("x"));
+    const turn = { system: "s", messages: [{ role: "user" as const, content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required" as const };
+    await convexModel("anthropic/claude-opus-5.5").next(turn);
+    await convexModel("anthropic/claude-haiku-5.5").next(turn);
+    expect(seen.map((r) => [r.body.model, r.body.tool_choice])).toEqual([
+      ["anthropic/claude-opus-5.5", "auto"],
+      ["anthropic/claude-haiku-5.5", "required"],
+    ]);
+  });
+
+  it("the auto downgrade ships strict: true tool definitions; a kept forced choice does not", async () => {
+    installFakeTransport(() => chatOk("x"));
+    const turn = { system: "s", messages: [{ role: "user" as const, content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required" as const };
+    await convexModel("anthropic/claude-sonnet-5.5").next(turn);
+    await convexModel("anthropic/claude-opus-5.5").next(turn);
+    await convexModel("anthropic/claude-haiku-5.5").next(turn);
+    expect(seen.map((r) => [r.body.model, r.body.tools[0].function.strict])).toEqual([
+      ["anthropic/claude-sonnet-5.5", true],
+      ["anthropic/claude-opus-5.5", true],
+      ["anthropic/claude-haiku-5.5", undefined],
+    ]);
+  });
+});
+
+describe("top_paid code default (SPEC-v9 D2: nvidia/nemotron-3.5-super-vl:free) over OpenRouter", () => {
+  it("the id the top_paid route resolves to goes out as written, with a forced tool_choice and no sampling keys", async () => {
+    // The runner builds this model from job.modelPolicy, which defaultModelPolicyForRoute fills with DEFAULT_TOP_PAID_MODEL.
+    expect(DEFAULT_TOP_PAID_MODEL).toBe("nvidia/nemotron-3.5-super-vl:free");
+    installFakeTransport(() => chatOk("nvidia/nemotron-3.5-super-vl:free"));
+    await convexModel(DEFAULT_TOP_PAID_MODEL).next({
+      system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required",
+    });
+    expect(seen).toHaveLength(1);
+    const { body, url } = seen[0];
+    expect(url).toBe("https://openrouter.ai/api/v1/chat/completions");
+    expect(body.model).toBe("nvidia/nemotron-3.5-super-vl:free");
+    expect(body.tool_choice).toBe("required"); // §1.3 forbids forcing only on the Claude 5.5 ids
+    expectNoSamplingKeys(body);
+  });
+});
+
+describe("Claude 5.5 over the AI-SDK adapter (adapter.model, direct Anthropic)", () => {
+  const cases = [
+    { id: "claude-haiku-5-5", forcedAllowed: true, effort: "medium" },
+    { id: "claude-sonnet-5-5", forcedAllowed: false, effort: "high" },
+    { id: "claude-opus-5-5", forcedAllowed: false, effort: "medium" },
+  ] as const;
+  for (const c of cases) {
+    it(`${c.id}: wire id, explicit effort ${c.effort}, ${c.forcedAllowed ? "forced tool_choice kept" : "forced tool_choice downgraded"}, no sampling keys`, async () => {
+      // A forced tool_choice makes the SDK demand a tool call back, so answer with one.
+      installFakeTransport((req) => req.body.tool_choice?.type === "any"
+        ? { ...anthropicOk(c.id), content: [{ type: "tool_use", id: "tu_1", name: "noop", input: {} }], stop_reason: "tool_use" }
+        : anthropicOk(c.id));
+      await adapterModel(c.id).next({
+        system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required",
+      });
+      expect(seen).toHaveLength(1); // the AI SDK's own retry loop is pinned to 0
+      const { body, url } = seen[0];
+      expect(url).toMatch(/\/messages$/);
+      expect(body.model).toBe(c.id);
+      expectNoSamplingKeys(body);
+      expect(body).not.toHaveProperty("thinking");
+      expect(body.output_config?.effort).toBe(c.effort);
+      expect(body.max_tokens).toBe(8192);
+      if (c.forcedAllowed) expect(body.tool_choice?.type).toBe("any");
+      else expect(body.tool_choice?.type).toBe("auto");
+      // §1.3: `auto` replaces a forced choice together with strict tool definitions; Haiku keeps the forced choice, no strict.
+      expect(body.tools[0].strict).toBe(c.forcedAllowed ? undefined : true);
+    });
+  }
+
+  it("anthropicModel() defaults to claude-haiku-5-5 (was claude-haiku-4-5)", async () => {
+    installFakeTransport(() => anthropicOk("claude-haiku-5-5"));
+    const m = anthropicModel();
+    expect(m.name).toBe("claude-haiku-5-5");
+    await m.next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen[0].body.model).toBe("claude-haiku-5-5");
+  });
+});
+
+describe("capture reasoner (aiSdkReasoner)", () => {
+  it("defaults to claude-haiku-5-5 and sends no sampling keys", async () => {
+    installFakeTransport((req) => {
+      // generateObject answers either through a JSON tool or as text, depending on the SDK mode it picked.
+      const tool = (req.body.tools ?? []).find((t: any) => t?.name === "json");
+      return tool
+        ? { ...anthropicOk("claude-haiku-5-5"), content: [{ type: "tool_use", id: "tu_1", name: "json", input: { ok: true } }], stop_reason: "tool_use" }
+        : { ...anthropicOk("claude-haiku-5-5"), content: [{ type: "text", text: "{\"ok\":true}" }] };
+    });
+    const reasoner = aiSdkReasoner();
+    expect(reasoner.name).toBe("claude-haiku-5-5");
+    await reasoner.decide({
+      system: "s",
+      instruction: "decide",
+      context: { title: "t", url: "https://example.test", a11y: "tree" } as any,
+      schema: z.object({ ok: z.boolean() }),
+    });
+    expect(seen[0].body.model).toBe("claude-haiku-5-5");
+    expectNoSamplingKeys(seen[0].body);
+    expect(seen[0].body.output_config?.effort).toBe("medium"); // explicit §1.3 default for Haiku 5.5, not the vendor's
+  });
+
+  it("an explicit claude-sonnet-5-5 id sends effort high (the caller's id, not a default, picks the row)", async () => {
+    installFakeTransport(() => ({ ...anthropicOk("claude-sonnet-5-5"), content: [{ type: "text", text: "{\"ok\":true}" }] }));
+    await aiSdkReasoner("claude-sonnet-5-5").decide({
+      system: "s",
+      instruction: "decide",
+      context: { title: "t", url: "https://example.test", a11y: "tree" } as any,
+      schema: z.object({ ok: z.boolean() }),
+    });
+    expect(seen[0].body.model).toBe("claude-sonnet-5-5");
+    expect(seen[0].body.output_config?.effort).toBe("high");
+  });
+
+  // SPEC A.0.10 at the public boundary of the migrated capture/reasoning.ts:23 role: convex/capturesNode.ts `capture` hands a
+  // client-supplied modelId to aiSdkReasoner, and the provider is picked by prefix alone. Any room member could drive any
+  // Anthropic or OpenAI id; the resolver now refuses ids the catalog does not know before a request exists.
+  it.each(["claude-not-in-catalog-9", "gpt-not-in-catalog", "o3-not-in-catalog", "claude-opus-9"])("refuses the unknown id %s with zero requests", async (id) => {
+    installFakeTransport(() => ({ ...anthropicOk("claude-haiku-5-5"), content: [{ type: "text", text: "{\"ok\":true}" }] }));
+    let decided: Promise<unknown> | undefined;
+    expect(() => {
+      decided = aiSdkReasoner(id).decide({ system: "s", instruction: "decide", context: { title: "t", url: "https://example.test", a11y: "tree" } as any, schema: z.object({ ok: z.boolean() }) });
+    }).toThrow(UnknownModelError);
+    await decided?.catch(() => undefined);
+    expect(seen).toHaveLength(0);
+  });
+
+  // Review round 6, defect 2. An unknown id that LOOKS free resolves to `openrouter/free-auto`, which this Anthropic/OpenAI seam
+  // cannot serve. The guard used to throw the resolution away and send the raw string to whichever provider its prefix named.
+  it.each(["claude-not-in-catalog:free", "gpt-not-in-catalog-free", "gemini-3.8-flash:free", "foo/bar:free"])("refuses the free-looking unknown id %s with zero requests (not sent under its raw name)", async (id) => {
+    installFakeTransport(() => ({ ...anthropicOk("claude-haiku-5-5"), content: [{ type: "text", text: "{\"ok\":true}" }] }));
+    let decided: Promise<unknown> | undefined;
+    expect(() => {
+      decided = aiSdkReasoner(id).decide({ system: "s", instruction: "decide", context: { title: "t", url: "https://example.test", a11y: "tree" } as any, schema: z.object({ ok: z.boolean() }) });
+    }).toThrow("capture_reasoner_route_unsupported:openrouter/free-auto");
+    await decided?.catch(() => undefined);
+    expect(seen).toHaveLength(0);
+  });
+
+  it("dispatches the RESOLVED id: a dotted display id goes out in its hyphenated wire form", async () => {
+    installFakeTransport(() => ({ ...anthropicOk("claude-opus-4-8"), content: [{ type: "text", text: "{\"ok\":true}" }] }));
+    await aiSdkReasoner("claude-opus-4.8").decide({ system: "s", instruction: "decide", context: { title: "t", url: "https://example.test", a11y: "tree" } as any, schema: z.object({ ok: z.boolean() }) });
+    expect(seen[0].body.model).toBe("claude-opus-4-8");
+  });
+});
+
+describe("gemini-3.8-flash (the new DEFAULT_AGENT_MODEL)", () => {
+  it("AI-SDK adapter: wire id in the URL, output cap set, no temperature / thinkingBudget", async () => {
+    installFakeTransport(() => geminiOk());
+    await adapterModel("gemini-3.8-flash").next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:generateContent");
+    expectNoSamplingKeys(seen[0].body);
+    expect(seen[0].body.generationConfig?.maxOutputTokens).toBe(8192);
+  });
+
+  it("direct HTTP step: wire id in the URL, no temperature / thinkingBudget", async () => {
+    installFakeTransport(() => geminiOk());
+    await convexModel("gemini-3.8-flash").next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:generateContent");
+    expectNoSamplingKeys(seen[0].body);
+  });
+
+  // Review round 6, defect 1 (SPEC-v9 D1). Persona: an evaluator runs the startup-diligence provider eval with an id the catalog has
+  // never seen (`--model` or an env candidate). origin/main measured that id; the fail-closed resolver skipped it and measured
+  // gemini-3.8-flash instead. An operator-selected id reaches the wire as written; server code (no option) still refuses it.
+  it("convexModel({ operatorSelected }) sends an id the catalog does not know as written; without the option it throws before any request", async () => {
+    installFakeTransport(() => geminiOk());
+    await convexModel("gemini-not-in-catalog", { operatorSelected: true }).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-not-in-catalog:generateContent");
+    expect(() => convexModel("gemini-not-in-catalog")).toThrow(UnknownModelError);
+    expect(seen).toHaveLength(1);
+  });
+
+  // Review round 7, defect 2 (SPEC-v9 D1). Persona: an evaluator runs `evals/professionalLiveCatalog --model <id>` or sets JUDGE_MODEL to
+  // an id the catalog has never seen. origin/main sent that id; judge() used the strict resolver, so it threw, and a concrete `:free`
+  // id was rewritten to a different free model - the run was measured under the wrong label.
+  it("judge(id, prompt, { operatorSelected }) sends the id as written; without the option an unknown id throws before any request", async () => {
+    installFakeTransport(() => geminiOk());
+    await judge("gemini-not-in-catalog", "p", { operatorSelected: true });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-not-in-catalog:generateContent");
+    await expect(judge("gemini-not-in-catalog", "p")).rejects.toBeInstanceOf(UnknownModelError);
+    expect(seen).toHaveLength(1);
+    installFakeTransport(() => chatOk("acme/new-model:free"));
+    await judge("acme/new-model:free", "p", { operatorSelected: true });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toBe("https://openrouter.ai/api/v1/chat/completions");
+    expect(seen[0].body.model).toBe("acme/new-model:free");
+  });
+
+  // Review round 6, defect 4 (A.0.5 compatibility). The explicit alias table replaced a regex that hyphenated EVERY dotted
+  // claude id; the two retired ids it forgot went out dotted. Both are retired (the provider rejects either spelling), but a persisted
+  // row on one of them must produce the request main produced.
+  it.each([["claude-opus-4.1", "claude-opus-4-1"], ["claude-haiku-3.5", "claude-haiku-3-5"]])("retained dotted id %s goes out as %s on both Anthropic builders", async (id, wire) => {
+    installFakeTransport(() => anthropicOk(wire));
+    await convexModel(id).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    await adapterModel(id).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen.map((r) => r.body.model)).toEqual([wire, wire]);
+  });
+
+  it("pi-ai adapter default: next() puts gemini-3.8-flash on the wire, with no sampling keys (no pi-ai package: it wraps model())", async () => {
+    installFakeTransport(() => geminiOk());
+    const m = createPiAiAdapter();
+    expect(m.name).toBe("gemini-3.8-flash");
+    await m.next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:generateContent");
+    expectNoSamplingKeys(seen[0].body);
+    expect(getProviderForModel(m.name)).toBe("gemini");
+    expect(getModelPricing(m.name)).not.toBeNull();
+  });
+
+  it("pi-ai adapter keeps deriving the provider from an explicit modelName (A.0.4)", async () => {
+    installFakeTransport(() => geminiOk());
+    await createPiAiAdapter({ modelName: "gemini-3.6-flash" }).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [] });
+    expect(seen[0].url).toContain("/models/gemini-3.6-flash:generateContent");
+  });
+});
+
+describe("default ids at the changed sites", () => {
+  it("AGENT_MODEL-less routing lands on gemini-3.8-flash; the fast lane stays on the laddered route", () => {
+    expect(defaultRouteForTask("chat" as any)).toBe("gemini-3.8-flash");
+    expect(resolveModelAlias("auto")).toBe("gemini-3.8-flash");
+    // adaptiveRouter.ts fast lane moves only after docs/eval/ladder/model-refresh-noderoom.json exists.
+    expect(chooseNodeAgentRoute({ task: "chat", risk: "low", latency: "interactive" } as any).model).toBe("gemini-3.5-flash");
+  });
+
+  it("provider-parser candidate lists are the refreshed ones (no retired / unlisted ids)", () => {
+    expect(providerParserModelCandidates("gemini")).toEqual(["gemini-3.8-flash", "gemini-3.6-flash"]);
+    expect(providerParserModelCandidates("openai")).toEqual(["gpt-5.5", "gpt-5.4-mini"]);
+    expect(providerParserModelCandidates("anthropic")).toEqual(["claude-haiku-5-5", "claude-sonnet-5-5"]);
+    expect(providerParserModelCandidates("openrouter")).not.toContain("nex-agi/nex-n2-pro");
+    // caller preference and the env override still come first
+    expect(providerParserModelCandidates("gemini", "gemini-3.1-pro-preview", { PROVIDER_PARSER_GEMINI_MODEL: "x" } as any).slice(0, 2))
+      .toEqual(["gemini-3.1-pro-preview", "x"]);
+  });
+});
+
+describe("LangChain bridge tool_choice guard", () => {
+  function captured(modelName: string) {
+    const bound: Array<Record<string, unknown>> = [];
+    const chat = {
+      model: modelName,
+      bindTools(_tools: unknown[], config: Record<string, unknown>) {
+        bound.push(config);
+        return { invoke: async () => ({ content: "ok" }) };
+      },
+      invoke: async () => ({ content: "ok" }),
+    };
+    return { chat, bound };
+  }
+  it("sends tool_choice any for Haiku 5.5 and for 4.x; Sonnet/Opus 5.5 get no forced choice but strict tools", async () => {
+    const got: Record<string, unknown> = {};
+    for (const id of ["claude-haiku-5-5", "claude-haiku-4-5", "claude-sonnet-5-5", "claude-opus-5-5"]) {
+      const { chat, bound } = captured(id);
+      await createLangChainAgentModel(chat as any).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "required" });
+      got[id] = bound[0];
+    }
+    expect(got).toEqual({
+      "claude-haiku-5-5": { tool_choice: "any" },
+      "claude-haiku-4-5": { tool_choice: "any" },
+      "claude-sonnet-5-5": { strict: true }, // SPEC §1.3: forced choice -> auto + strict: true
+      "claude-opus-5-5": { strict: true },
+    });
+    // No forced choice requested: nothing is added for any id.
+    for (const id of ["claude-haiku-5-5", "claude-sonnet-5-5"]) {
+      const { chat, bound } = captured(id);
+      await createLangChainAgentModel(chat as any).next({ system: "s", messages: [{ role: "user", content: "hi" }], tools: [NOOP_TOOL], toolChoice: "auto" });
+      expect(bound[0], id).toEqual({});
+    }
+  });
+});
diff --git a/tests/modelRefreshServerRoles.test.ts b/tests/modelRefreshServerRoles.test.ts
new file mode 100644
index 00000000..f61d64d0
--- /dev/null
+++ b/tests/modelRefreshServerRoles.test.ts
@@ -0,0 +1,641 @@
+/**
+ * 2026-10 model refresh (SPEC Part A §A.2.9, rule A.0.6) — request-shape tests for the roles whose builders are
+ * server-side or script-side. Every test drives the repo's OWN builder with a fake transport (`fetch`) and asserts
+ * the wire id (written here as a literal on purpose) plus the keys the §1.3 row forbids:
+ *
+ *   - Gemini TTS         convex/http.ts  /voice/synthesize route -> synthesizeWithGemini
+ *   - private stream     convex/http.ts  /stream-private-reply route -> streamPrivateReplyText -> geminiStream
+ *                        (the route picks `process.env.AGENT_MODEL ?? DEFAULT_AGENT_MODEL`; nothing is injected)
+ *   - provider parser    providerParserLive.runLiveProviderParser with no model argument (the default candidate)
+ *   - judge scripts      the scripts themselves, executed with argv + fixtures; the request must name
+ *                        gemini-3.6-flash and carry no `temperature`
+ *   - .env.example       every example value this PR changed equals what the code defaults to
+ *
+ * No test here can reach a provider: `fetch` is replaced before any builder runs.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runLiveProviderParser, providerParserModelCandidates } from "../src/nodeagent/models/providerParserLive";
+import { DEFAULT_AGENT_MODEL } from "../convex/modelDefaults";
+
+type Seen = { url: string; headers: Record<string, string>; body: Record<string, any> };
+const seen: Seen[] = [];
+vi.setConfig({ testTimeout: 30_000 }); // the first import of convex/http.ts pulls in the Convex auth module graph
+
+function installFakeTransport(respond: (req: Seen) => Response | unknown) {
+  seen.length = 0;
+  vi.stubGlobal("fetch", async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const raw = typeof init?.body === "string" ? init.body : "{}";
+    let body: Record<string, any> = {};
+    try { body = JSON.parse(raw); } catch { /* not JSON (multipart / binary) */ }
+    const req: Seen = { url, headers: Object.fromEntries(new Headers(init?.headers).entries()), body };
+    seen.push(req);
+    const out = respond(req);
+    return out instanceof Response ? out : new Response(JSON.stringify(out), { status: 200, headers: { "content-type": "application/json" } });
+  });
+}
+
+const FORBIDDEN_SAMPLING_KEYS = ["temperature", "top_p", "top_k", "topP", "topK"];
+function expectNoSampling(body: Record<string, any>) {
+  for (const key of FORBIDDEN_SAMPLING_KEYS) expect(body, key).not.toHaveProperty(key);
+  for (const key of FORBIDDEN_SAMPLING_KEYS) expect(body.generationConfig ?? {}, `generationConfig.${key}`).not.toHaveProperty(key);
+}
+
+const ENV_KEYS = [
+  "AGENT_MODEL", "AGENT_FALLBACK_MODEL", "GOOGLE_GENERATIVE_AI_API_KEY", "GEMINI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY",
+  "VOICE_TTS_PROVIDER", "VOICE_TTS_PROVIDER_ORDER", "VOICE_GEMINI_TTS_MODEL", "VOICE_GEMINI_TTS_VOICE", "VOICE_GEMINI_TTS_API_REVISION",
+  "NODEROOM_FREE_ONLY", "VOICE_FREE_ONLY", "PROVIDER_PARSER_ALLOW_FILE_EGRESS", "PROVIDER_PARSER_GEMINI_MODEL",
+  "PROVIDER_PARSER_ANTHROPIC_MODEL", "GEMINI_JUDGE_MODEL", "GEMINI_UI_REVIEW_MODEL", "GEMINI_MEDIA_JUDGE_MODEL",
+  "GEMINI_SEO_VIDEO_JUDGE_MODEL", "JUDGE_MODEL", "NODEAGENT_ALLOWED_PROVIDERS", "PROVIDER_EGRESS_ALLOWED_PROVIDERS",
+  "PROVIDER_EGRESS_REQUIRE_ALLOWLIST", "NODEROOM_PRODUCTION", "STARTUP_DILIGENCE_PROVIDER_MODEL", "AGENT_RESEARCH_MODEL", "OPENROUTER_API_KEY",
+] as const;
+const savedEnv: Record<string, string | undefined> = {};
+beforeEach(() => {
+  for (const k of ENV_KEYS) { savedEnv[k] = process.env[k]; delete process.env[k]; }
+  process.env.GOOGLE_GENERATIVE_AI_API_KEY = "test-google-key";
+  process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+});
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  for (const k of ENV_KEYS) { if (savedEnv[k] === undefined) delete process.env[k]; else process.env[k] = savedEnv[k]; }
+});
+
+// ───────────────────────────── Gemini TTS ─────────────────────────────
+
+const TTS_MODEL = "gemini-3.8-flash-tts"; // SPEC §1.2; replaces gemini-3.1-flash-tts-preview (Google shutdown 2026-11-17)
+
+async function synthesizeThroughRoute(): Promise<Response> {
+  const http = (await import("../convex/http")).default;
+  const [route] = http.lookup("/voice/synthesize", "POST") as unknown as [{ _handler: (ctx: unknown, req: Request) => Promise<Response> }];
+  const request = new Request("https://example.convex.site/voice/synthesize", {
+    method: "POST",
+    body: JSON.stringify({ roomId: "room1", requester: { actor: { kind: "user", id: "u1", name: "Maya" }, token: "t" }, text: "NodeAgent is working." }),
+  });
+  return route._handler({ runQuery: async () => null }, request);
+}
+
+const pcmAudio = () => ({ candidates: [{ content: { parts: [{ inlineData: { mimeType: "audio/L16;codec=pcm;rate=24000", data: Buffer.from(new Uint8Array(480)).toString("base64") } }] } }] });
+
+describe("Gemini TTS (convex/http.ts synthesizeWithGemini, served by POST /voice/synthesize)", () => {
+  beforeEach(() => { process.env.VOICE_TTS_PROVIDER = "gemini"; });
+
+  it("sends the default request to gemini-3.8-flash-tts with the audio-modality config and no sampling keys", async () => {
+    installFakeTransport(() => pcmAudio());
+    const res = await synthesizeThroughRoute();
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Voice-TTS-Model")).toBe(TTS_MODEL);
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toBe(`https://generativelanguage.googleapis.com/v1beta/models/${TTS_MODEL}:generateContent`);
+    expect(seen[0].headers["x-goog-api-key"]).toBe("test-google-key");
+    expect(seen[0].body.model).toBe(TTS_MODEL);
+    expect(seen[0].body.generationConfig.responseModalities).toEqual(["AUDIO"]);
+    expect(seen[0].body.generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName).toBe("Kore");
+    expectNoSampling(seen[0].body);
+  });
+
+  it("VOICE_GEMINI_TTS_MODEL keeps its precedence over the code default", async () => {
+    process.env.VOICE_GEMINI_TTS_MODEL = "gemini-3.8-flash-tts-override";
+    installFakeTransport(() => pcmAudio());
+    await synthesizeThroughRoute();
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash-tts-override:generateContent");
+    expect(seen[0].body.model).toBe("gemini-3.8-flash-tts-override");
+  });
+});
+
+// ───────────────────────────── private stream ─────────────────────────────
+
+describe("private-reply stream (POST /stream-private-reply -> streamPrivateReplyText -> geminiStream)", () => {
+  async function drivePrivateStreamRoute() {
+    const appended: string[] = [];
+    // The route hands its generator to the persistent-text-streaming component; run that generator inline.
+    vi.doMock("../convex/streaming", () => ({
+      streamingComponent: {
+        stream: async (_ctx: unknown, _req: unknown, _id: string, generate: (c: unknown, r: unknown, i: string, append: (t: string) => Promise<void>) => Promise<void>) => {
+          await generate({ runMutation: async () => null }, _req, _id, async (t) => { appended.push(t); });
+          return new Response("streamed", { status: 200 });
+        },
+      },
+    }));
+    vi.resetModules();
+    const http = (await import("../convex/http")).default;
+    const [route] = http.lookup("/stream-private-reply", "POST") as unknown as [{ _handler: (ctx: unknown, req: Request) => Promise<Response> }];
+    const ctx = { runQuery: async () => ({ requesterName: "Maya", roomContext: "ctx", goal: "summarise", roomId: "r1", clientMsgId: "c1" }) };
+    const request = new Request("https://example.convex.site/stream-private-reply", {
+      method: "POST",
+      body: JSON.stringify({ streamId: "s1", requester: { actor: { kind: "user", id: "u1", name: "Maya" }, token: "t" } }),
+    });
+    const res = await route._handler(ctx, request);
+    vi.doUnmock("../convex/streaming");
+    return { res, appended };
+  }
+  const sse = (text: string) => new Response(`data: ${JSON.stringify({ candidates: [{ content: { parts: [{ text }] } }] })}\n\n`, { status: 200, headers: { "content-type": "text/event-stream" } });
+
+  it("with AGENT_MODEL unset the route streams from gemini-3.8-flash, with an output cap and no sampling keys", async () => {
+    installFakeTransport(() => sse("hello"));
+    const { res, appended } = await drivePrivateStreamRoute();
+    expect(res.status).toBe(200);
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:streamGenerateContent");
+    expect(seen[0].body.generationConfig.maxOutputTokens).toBeGreaterThan(0);
+    expectNoSampling(seen[0].body);
+    expect(appended.join("")).toBe("hello");
+    expect(DEFAULT_AGENT_MODEL).toBe("gemini-3.8-flash"); // the constant the route falls back to
+  });
+
+  it("AGENT_MODEL keeps its precedence over the default", async () => {
+    process.env.AGENT_MODEL = "gemini-3.6-flash";
+    installFakeTransport(() => sse("hi"));
+    await drivePrivateStreamRoute();
+    expect(seen[0].url).toContain("/models/gemini-3.6-flash:streamGenerateContent");
+  });
+
+  // SPEC A.0.10 at the migrated http.ts:176 role: `AGENT_MODEL ?? DEFAULT_AGENT_MODEL` names the id this stream sends.
+  // Before the guard an AGENT_MODEL the catalog does not know reached models/<id>:streamGenerateContent (convexModel() refuses it).
+  it("an AGENT_MODEL the catalog does not know never reaches the wire", async () => {
+    process.env.AGENT_MODEL = "gemini-not-in-catalog";
+    installFakeTransport(() => sse("hi"));
+    const { appended } = await drivePrivateStreamRoute(); // the route turns the refusal into visible text, never a silent 2xx void
+    expect(appended.join("")).toContain('unknown model id "gemini-not-in-catalog"');
+    expect(seen).toHaveLength(0);
+    const { streamPrivateReplyText } = await import("../convex/streamingModel");
+    await expect(streamPrivateReplyText("claude-not-in-catalog-9", "sys", "user", async () => undefined)).rejects.toMatchObject({ name: "UnknownModelError" }); // by name: the drive helper resets the module graph
+    expect(seen).toHaveLength(0);
+  });
+
+  // Review round 6 defect 2, then round 7. An unknown id that LOOKS free resolves to the internal sentinel `openrouter/free-auto`,
+  // which is not an OpenRouter model id (public /api/v1/models read 2026-10-17 lists `openrouter/free` and `openrouter/auto`).
+  // The stream has no free-model picker, so it refuses before any request: no raw name on the wire, no invalid sentinel either.
+  it.each(["gemini-3.8-flash:free", "foo/bar:free", "claude-not-in-catalog:free", "gpt-not-in-catalog-free", "openrouter/free-auto"])("the free-looking id %s is refused before any request", async (id) => {
+    process.env.OPENROUTER_API_KEY = "test-openrouter-key";
+    installFakeTransport(() => sse("hi"));
+    const { streamPrivateReplyText } = await import("../convex/streamingModel");
+    await expect(streamPrivateReplyText(id, "sys", "user", async () => undefined)).rejects.toThrow(/private_stream_free_auto_unsupported/);
+    expect(seen).toHaveLength(0);
+  });
+});
+
+// ───────────────────────────── provider parser ─────────────────────────────
+
+describe("provider parser (providerParserLive.runLiveProviderParser, default candidate)", () => {
+  const file = { storageId: "s1", artifactId: "a1", fileName: "diligence.pdf", mimeType: "application/pdf", size: 10 };
+  const extractionJson = JSON.stringify({ tables: [], evidence: [] });
+  beforeEach(() => { process.env.PROVIDER_PARSER_ALLOW_FILE_EGRESS = "1"; });
+
+  const run = (provider: "gemini" | "anthropic", model?: string) =>
+    runLiveProviderParser({ provider, file, source: { text: "ARR $12M" }, ...(model ? { model } : {}) });
+
+  it("gemini: the default candidate is gemini-3.8-flash on the wire, no sampling keys", async () => {
+    installFakeTransport(() => ({ candidates: [{ content: { role: "model", parts: [{ text: extractionJson }] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 5, candidatesTokenCount: 5, totalTokenCount: 10 } }));
+    const result = await run("gemini");
+    expect(result.model).toBe("gemini-3.8-flash");
+    expect(seen.length).toBeGreaterThan(0);
+    for (const req of seen) {
+      expect(req.url).toContain("/models/gemini-3.8-flash:generateContent");
+      expectNoSampling(req.body);
+    }
+  });
+
+  const anthropicText = (model: string) => ({ id: "msg_t", type: "message", role: "assistant", model, content: [{ type: "text", text: extractionJson }], stop_reason: "end_turn", stop_sequence: null, usage: { input_tokens: 5, output_tokens: 5 } });
+
+  for (const c of [
+    { label: "default candidate", model: undefined, wire: "claude-haiku-5-5", effort: "medium" },
+    { label: "second candidate", model: "claude-sonnet-5-5", wire: "claude-sonnet-5-5", effort: "high" },
+  ] as const) {
+    it(`anthropic ${c.label}: wire id ${c.wire}, explicit effort ${c.effort}, no sampling / thinking / prefill`, async () => {
+      installFakeTransport((req) => req.body.tool_choice?.type
+        ? { ...anthropicText(c.wire), content: [{ type: "tool_use", id: "tu_1", name: "json", input: { tables: [], evidence: [] } }], stop_reason: "tool_use" }
+        : anthropicText(c.wire));
+      const result = await run("anthropic", c.model);
+      expect(result.model).toBe(c.wire);
+      expect(seen.length).toBeGreaterThan(0);
+      for (const req of seen) {
+        expect(req.url).toMatch(/\/messages$/);
+        expect(req.body.model).toBe(c.wire);
+        expectNoSampling(req.body);
+        expect(req.body).not.toHaveProperty("thinking");
+        expect(req.body.output_config?.effort).toBe(c.effort);
+        expect(req.body.messages.at(-1).role).toBe("user");
+        // SPEC §1.3: Sonnet 5.5 and Opus 5.5 answer a forced tool_choice (any / a named tool) with 400. generateObject must use the
+        // native structured output (@ai-sdk/anthropic 3.0.120: output_config.format), never a forced `json` tool, so an SDK change
+        // that brings the tool back fails here. `max_tokens` is the SDK's own cap; a 4.5-sized (64K) cap truncates 5.5 replies.
+        expect(req.body.tool_choice, "no forced tool_choice").toBeUndefined();
+        expect(req.body.tools, "no json tool").toBeUndefined();
+        expect(req.body.output_config?.format?.type).toBe("json_schema");
+        expect(req.body.max_tokens).toBeGreaterThanOrEqual(64_000);
+      }
+    });
+  }
+
+  it("the default candidate lists are the refreshed ones", () => {
+    expect(providerParserModelCandidates("gemini")[0]).toBe("gemini-3.8-flash");
+    expect(providerParserModelCandidates("anthropic")[0]).toBe("claude-haiku-5-5");
+  });
+});
+
+// ───────────────────────────── judge scripts ─────────────────────────────
+
+const JUDGE_MODEL = "gemini-3.6-flash"; // what Google already serves under the deprecated 3.5 name (SPEC A.2.9 EXTRA rows)
+const FIXTURE_ROOT = resolve(".tmp-qa", "model-refresh-fixtures"); // .tmp-qa/ is gitignored
+const geminiGenerateContent = () => ({ candidates: [{ content: { role: "model", parts: [{ text: "{}" }] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1, totalTokenCount: 2 } });
+
+/**
+ * Execute a judge script's top level with `argv`, with `fetch` faked. The script is allowed to fail after it has
+ * sent its request (the canned answer is not a valid verdict); what matters is the request it built.
+ */
+async function runJudgeScript(load: () => Promise<unknown>, argv: string[], answer: () => unknown = geminiGenerateContent): Promise<Seen[]> {
+  installFakeTransport(answer);
+  vi.resetModules();
+  const argvBefore = process.argv;
+  process.argv = ["node", "judge-script", ...argv];
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(process, "exit").mockImplementation((() => undefined) as never); // `void run().catch(() => process.exit(1))` must not kill the worker
+  try { await load(); } catch { /* the canned answer is not a valid verdict */ }
+  // Scripts that fire `void run()` return before the request; wait for it.
+  for (let i = 0; i < 100 && seen.length === 0; i++) await new Promise((r) => setTimeout(r, 20));
+  process.argv = argvBefore;
+  return [...seen];
+}
+
+describe("Gemini judge scripts pin gemini-3.6-flash and send no temperature", () => {
+  let dir: string;
+  let png: string;
+  let mp4: string;
+  beforeEach(() => {
+    mkdirSync(FIXTURE_ROOT, { recursive: true });
+    dir = mkdtempSync(join(FIXTURE_ROOT, "judge-"));
+    png = join(dir, "shot.png");
+    mp4 = join(dir, "clip.mp4");
+    writeFileSync(png, Buffer.from("89504e470d0a1a0a", "hex"));
+    writeFileSync(mp4, Buffer.from("00000018667479706d703432", "hex"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  function expectJudgeRequest(requests: Seen[]) {
+    expect(requests.length, "the script sent a request").toBeGreaterThan(0);
+    for (const req of requests) {
+      expect(req.url).toContain(`/models/${JUDGE_MODEL}:generateContent`);
+      expectNoSampling(req.body);
+    }
+  }
+
+  it("scripts/design-qa/rubric-panel.ts (generateObject, four lenses)", async () => {
+    const requests = await runJudgeScript(() => import("../scripts/design-qa/rubric-panel"), [`--media=${png}`, `--out=${join(dir, "out.json")}`]);
+    expectJudgeRequest(requests);
+  });
+
+  it("scripts/gemini-visual-polish.ts (generateObject)", async () => {
+    const requests = await runJudgeScript(() => import("../scripts/gemini-visual-polish"), [`--media=${png}`, `--out=${join(dir, "out.json")}`]);
+    expectJudgeRequest(requests);
+  });
+
+  it("scripts/gemini-mp4-workflow-review.ts (generateObject)", async () => {
+    const requests = await runJudgeScript(() => import("../scripts/gemini-mp4-workflow-review"), [`--media=${mp4}`, `--out=${join(dir, "out.json")}`]);
+    expectJudgeRequest(requests);
+  });
+
+  it("skills/seo-qa/scripts/judge-video-gemini.ts (generateObject) and GEMINI_SEO_VIDEO_JUDGE_MODEL keeps precedence", async () => {
+    const requests = await runJudgeScript(() => import("../skills/seo-qa/scripts/judge-video-gemini"), ["--input", mp4, "--out-dir", join(dir, "out")]);
+    expectJudgeRequest(requests);
+    process.env.GEMINI_SEO_VIDEO_JUDGE_MODEL = "gemini-3.8-flash";
+    const overridden = await runJudgeScript(() => import("../skills/seo-qa/scripts/judge-video-gemini"), ["--input", mp4, "--out-dir", join(dir, "out")]);
+    expect(overridden[0]?.url).toContain("/models/gemini-3.8-flash:generateContent");
+  });
+
+  it("scripts/walkthroughs/judge-video.ts (raw fetch): model from GEMINI_JUDGE_MODEL ?? gemini-3.6-flash", async () => {
+    const episodeRel = join("..", ".tmp-qa", "model-refresh-fixtures", dir.split(/[\\/]/).at(-1)!); // episodes/<id> resolves under the fixture dir
+    mkdirSync(join(dir, "renders"), { recursive: true });
+    writeFileSync(join(dir, "renders", "short.mp4"), Buffer.from("00000018667479706d703432", "hex"));
+    const requests = await runJudgeScript(() => import("../scripts/walkthroughs/judge-video"), [episodeRel, "renders/short.mp4"]);
+    expectJudgeRequest(requests);
+    process.env.GEMINI_JUDGE_MODEL = "gemini-3.8-flash";
+    const overridden = await runJudgeScript(() => import("../scripts/walkthroughs/judge-video"), [episodeRel, "renders/short.mp4"]);
+    expect(overridden[0]?.url).toContain("/models/gemini-3.8-flash:generateContent");
+  });
+
+  it("the scripts that need ImageMagick / LibreOffice / benchmark workbooks cannot be executed here: their request builders are checked on the AST", async () => {
+    // judge-demo-gif.ts and judge-state-captures.ts decode GIF/PNG sets with ImageMagick, spreadsheetbench-chart-visual-grade.ts
+    // renders workbooks with LibreOffice and gemini-demo-media-judge.ts walks the tracked media tree. Parse each and assert that
+    // no object literal anywhere in the file carries a `temperature` property and that the pinned model literal is present.
+    const ts = await import("typescript");
+    const targets: Array<{ file: string; model: RegExp }> = [
+      { file: "scripts/judge-demo-gif.ts", model: /GEMINI_JUDGE_MODEL \?\? "gemini-3\.6-flash"/ },
+      { file: "scripts/judge-state-captures.ts", model: /GEMINI_JUDGE_MODEL \?\? "gemini-3\.6-flash"/ },
+      { file: "scripts/spreadsheetbench-chart-visual-grade.ts", model: /"gemini-3\.6-flash"/ },
+      { file: "scripts/gemini-demo-media-judge.ts", model: /"gemini-3\.6-flash"/ },
+    ];
+    for (const { file, model } of targets) {
+      const text = readFileSync(file, "utf8");
+      const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+      const temperatureProps: string[] = [];
+      const visit = (node: import("typescript").Node) => {
+        if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) {
+          const name = node.name.getText(source).replace(/["'`]/g, "");
+          if (/^temperature$/i.test(name)) temperatureProps.push(`${file}:${source.getLineAndCharacterOfPosition(node.getStart()).line + 1}`);
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(source);
+      expect(temperatureProps, `${file} sends temperature`).toEqual([]);
+      expect(model.test(text), `${file} pins ${JUDGE_MODEL}`).toBe(true);
+    }
+  });
+});
+
+// ───────────────── review round 2: every other model-bearing script, driven through a fake transport ─────────────────
+
+/**
+ * Run `body` with the process working directory switched to a fresh fixture directory. Scripts that resolve
+ * `process.cwd()` at import (ROOT, docs/..., .tmp-qa/...) then read and write ONLY inside it.
+ */
+async function inFixtureCwd<T>(body: (dir: string) => Promise<T>): Promise<T> {
+  mkdirSync(FIXTURE_ROOT, { recursive: true });
+  const dir = mkdtempSync(join(FIXTURE_ROOT, "cwd-"));
+  const before = process.cwd();
+  process.chdir(dir);
+  try { return await body(dir); } finally { process.chdir(before); rmSync(dir, { recursive: true, force: true }); }
+}
+
+const PNG = Buffer.from("89504e470d0a1a0a", "hex");
+const MP4 = Buffer.from("00000018667479706d703432", "hex");
+
+describe("Gemini scripts that need a fixture tree: the request names gemini-3.6-flash and carries no temperature", () => {
+  afterEach(() => { vi.doUnmock("node:child_process"); });
+
+  function expectJudgeRequest(requests: Seen[], model = JUDGE_MODEL) {
+    expect(requests.length, "the script sent a request").toBeGreaterThan(0);
+    for (const req of requests) {
+      expect(req.url).toContain(`/models/${model}:generateContent`);
+      expectNoSampling(req.body);
+    }
+  }
+
+  it("scripts/gemini-ui-review.ts (generateObject); GEMINI_UI_REVIEW_MODEL and --model keep their precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      const png = join(dir, "shot.png");
+      writeFileSync(png, PNG);
+      const args = [`--media=${png}`, `--out=${join(dir, "out.json")}`];
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/gemini-ui-review"), args));
+      process.env.GEMINI_UI_REVIEW_MODEL = "gemini-3.8-flash";
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/gemini-ui-review"), args), "gemini-3.8-flash");
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/gemini-ui-review"), [...args, "--model=gemini-3.5-flash-lite"]), "gemini-3.5-flash-lite");
+    });
+  });
+
+  it("scripts/eval/painJudge.ts (generateText); JUDGE_MODEL keeps its precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      mkdirSync(join(dir, "docs", "eval"), { recursive: true });
+      mkdirSync(join(dir, "docs", "screenshots"), { recursive: true });
+      writeFileSync(join(dir, "docs", "eval", "pain-rubric.json"), "[]");
+      writeFileSync(join(dir, "docs", "eval", "ladder-trace.txt"), "L1 ok");
+      for (const [, name] of readFileSync(resolve(__dirname, "../scripts/eval/painJudge.ts"), "utf8").matchAll(/\["([^"]+\.png)"/g)) writeFileSync(join(dir, "docs", "screenshots", name), PNG);
+      const verdicts = () => ({ candidates: [{ content: { role: "model", parts: [{ text: "[]" }] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1, totalTokenCount: 2 } });
+      const requests = await runJudgeScript(() => import("../scripts/eval/painJudge"), [], verdicts);
+      expectJudgeRequest(requests);
+      process.env.JUDGE_MODEL = "gemini-3.8-flash";
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/eval/painJudge"), [], verdicts), "gemini-3.8-flash");
+    });
+  });
+
+  it("scripts/judge-state-captures.ts (raw fetch, generationConfig has no temperature); GEMINI_JUDGE_MODEL keeps its precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      mkdirSync(join(dir, "docs", "qa", "state-captures"), { recursive: true });
+      writeFileSync(join(dir, "docs", "qa", "state-captures", "a.png"), PNG);
+      writeFileSync(join(dir, "docs", "qa", "state-captures", "manifest.json"), JSON.stringify({ captures: [{ surface: "sheet", state: "default", theme: "dark", width: 1280, file: "a.png", mustBeTrue: "renders" }] }));
+      const requests = await runJudgeScript(() => import("../scripts/judge-state-captures"), []);
+      expectJudgeRequest(requests);
+      expect(requests[0].body.generationConfig).toEqual({ responseMimeType: "application/json" });
+      process.env.GEMINI_JUDGE_MODEL = "gemini-3.8-flash";
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/judge-state-captures"), []), "gemini-3.8-flash");
+    });
+  });
+
+  it("scripts/judge-demo-gif.ts (raw fetch, generationConfig has no temperature); GEMINI_JUDGE_MODEL keeps its precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      mkdirSync(join(dir, "docs", "eval", "workflow-previews"), { recursive: true });
+      writeFileSync(join(dir, "docs", "eval", "workflow-previews", "demo.gif"), Buffer.from("GIF89a"));
+      // ImageMagick is not assumed on the test machine: answer `magick identify` / `magick -coalesce` the way it would for a one-frame GIF.
+      vi.doMock("node:child_process", async (importOriginal) => ({
+        ...(await importOriginal<typeof import("node:child_process")>()),
+        spawnSync: (_cmd: string, args: string[]) => {
+          if (args[0] === "identify") return { status: 0, stdout: "10\n", stderr: "" };
+          writeFileSync(String(args.at(-1)).replace("%04d", "0000"), PNG);
+          return { status: 0, stdout: "", stderr: "" };
+        },
+      }));
+      const requests = await runJudgeScript(() => import("../scripts/judge-demo-gif"), []);
+      expectJudgeRequest(requests);
+      expect(requests[0].body.generationConfig).toEqual({ responseMimeType: "application/json" });
+      process.env.GEMINI_JUDGE_MODEL = "gemini-3.8-flash";
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/judge-demo-gif"), []), "gemini-3.8-flash");
+    });
+  });
+
+  it("scripts/spreadsheetbench-chart-visual-grade.ts (generateObject, three chart images); GEMINI_MEDIA_JUDGE_MODEL keeps its precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      const workbook = join(dir, "book.xlsx");
+      writeFileSync(workbook, "x");
+      // The renderer (Excel COM + pdftoppm) is replaced by files; the model call is the part under test.
+      vi.doMock("node:child_process", async (importOriginal) => ({
+        ...(await importOriginal<typeof import("node:child_process")>()),
+        spawnSync: (cmd: string, args: string[]) => {
+          if (cmd === "powershell") writeFileSync(args[args.indexOf("-Pdf") + 1], "%PDF");
+          else if (cmd === "pdftoppm") writeFileSync(`${args.at(-1)}.png`, PNG);
+          return { status: 0, stdout: "", stderr: "" };
+        },
+      }));
+      const platform = Object.getOwnPropertyDescriptor(process, "platform")!;
+      Object.defineProperty(process, "platform", { value: "win32" }); // the script only renders through Excel COM
+      try {
+        const args = [`--candidate=${workbook}`, `--gold=${workbook}`, `--negative-candidate=${workbook}`, `--out-dir=${join(dir, "out")}`, `--tmp-dir=${join(dir, "tmp")}`];
+        expectJudgeRequest(await runJudgeScript(() => import("../scripts/spreadsheetbench-chart-visual-grade"), args));
+        process.env.GEMINI_MEDIA_JUDGE_MODEL = "gemini-3.8-flash";
+        expectJudgeRequest(await runJudgeScript(() => import("../scripts/spreadsheetbench-chart-visual-grade"), args), "gemini-3.8-flash");
+      } finally {
+        Object.defineProperty(process, "platform", platform);
+      }
+    });
+  });
+
+  it("scripts/gemini-demo-media-judge.ts (generateObject); GEMINI_MEDIA_JUDGE_MODEL keeps its precedence", async () => {
+    await inFixtureCwd(async (dir) => {
+      const mp4 = join(dir, "clip.mp4");
+      writeFileSync(mp4, MP4);
+      const args = [`--input=${mp4}`, `--out=${join(dir, "out")}`, "--run-id=t"];
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/gemini-demo-media-judge"), args));
+      process.env.GEMINI_MEDIA_JUDGE_MODEL = "gemini-3.8-flash";
+      expectJudgeRequest(await runJudgeScript(() => import("../scripts/gemini-demo-media-judge"), args), "gemini-3.8-flash");
+    });
+  });
+});
+
+describe("model defaults carried by library code and config", () => {
+  it("runSpreadsheetBenchChartVisualProbe reports gemini-3.6-flash by default; the option and GEMINI_MEDIA_JUDGE_MODEL keep their precedence", async () => {
+    const { runSpreadsheetBenchChartVisualProbe } = await import("../src/eval/spreadsheetBenchChartVisualProbe");
+    const probe = (extra: Record<string, unknown> = {}, env: Record<string, string> = {}) =>
+      runSpreadsheetBenchChartVisualProbe({ generatedAt: "2026-10-15T00:00:00.000Z", env: { GOOGLE_GENERATIVE_AI_API_KEY: "k", ...env }, rendererCommands: [], ...extra } as never).vlm.model;
+    delete process.env.GEMINI_MEDIA_JUDGE_MODEL;
+    expect(probe()).toBe(JUDGE_MODEL);
+    process.env.GEMINI_MEDIA_JUDGE_MODEL = "gemini-3.8-flash";
+    expect(probe()).toBe("gemini-3.8-flash");
+    expect(probe({ model: "gemini-3.5-flash-lite" })).toBe("gemini-3.5-flash-lite");
+  });
+
+  it("walkthrough-review: the shipped config and the CLI's built-in default both name gemini-3.6-flash", async () => {
+    const { runWalkthroughReview } = await import("../packages/walkthrough-review-cli/src/core");
+    expect(JSON.parse(readFileSync("walkthrough-review.config.json", "utf8")).defaultModel).toBe(JUDGE_MODEL);
+    await inFixtureCwd(async (dir) => {
+      mkdirSync(join(dir, "docs", "walkthroughs"), { recursive: true });
+      writeFileSync(join(dir, "docs", "walkthroughs", "clip.mp4"), MP4);
+      const run = (config: Record<string, unknown>, input: Record<string, unknown> = {}) => {
+        writeFileSync(join(dir, "wr.config.json"), JSON.stringify({ schemaVersion: 1, commands: {}, ...config }));
+        return runWalkthroughReview({ cwd: dir, configPath: "wr.config.json", dryRun: true, skipCapture: true, skipRender: true, skipGemini: true, media: "docs/walkthroughs/clip.mp4", logger: () => {}, ...input });
+      };
+      expect((await run({})).model).toBe(JUDGE_MODEL); // no defaultModel in the config: the CLI's own default
+      expect((await run({ defaultModel: "gemini-3.8-flash" })).model).toBe("gemini-3.8-flash");
+      expect((await run({ defaultModel: "gemini-3.8-flash" }, { model: "gemini-3.5-flash-lite" })).model).toBe("gemini-3.5-flash-lite");
+    });
+  });
+});
+
+describe("benchmark / smoke / eval scripts send the refreshed ids with the explicit effort", () => {
+  const anthropicMessage = (model: string) => ({ id: "msg_t", type: "message", role: "assistant", model, content: [{ type: "text", text: "OK" }], stop_reason: "end_turn", stop_sequence: null, usage: { input_tokens: 5, output_tokens: 5 } });
+  const generateContent = (text: string) => ({ candidates: [{ content: { role: "model", parts: [{ text }] }, finishReason: "STOP", index: 0 }], usageMetadata: { promptTokenCount: 5, candidatesTokenCount: 5, totalTokenCount: 10 } });
+  /** Answer by wire: Anthropic Messages, Google generateContent; anything else is an HTTP 404 the script reports and moves past. */
+  const respondByWire = (text = "OK") => (req: Seen) =>
+    req.url.includes("api.anthropic.com") ? anthropicMessage(String(req.body.model))
+      : req.url.includes("generativelanguage.googleapis.com") ? generateContent(text)
+        : new Response("{}", { status: 404 });
+
+  it("scripts/benchmark/probe.ts: claude-haiku/sonnet/opus-5-5 go out with their SPEC §1.3 effort and no sampling keys; gpt-6.1-sol reaches OpenAI by its wire id with no temperature", async () => {
+    process.env.OPENAI_API_KEY = "test-openai-key"; // without a key the AI SDK throws before any request, so the OpenAI row was never exercised
+    installFakeTransport(respondByWire());
+    vi.resetModules();
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    await import("../scripts/benchmark/probe");
+    const claude55 = seen.filter((r) => r.url.includes("api.anthropic.com") && /-5-5$/.test(String(r.body.model)));
+    expect(claude55.map((r) => r.body.model).sort()).toEqual(["claude-haiku-5-5", "claude-opus-5-5", "claude-sonnet-5-5"]);
+    const effort: Record<string, string> = { "claude-haiku-5-5": "medium", "claude-sonnet-5-5": "high", "claude-opus-5-5": "medium" };
+    for (const req of claude55) {
+      expect(req.body.output_config?.effort, String(req.body.model)).toBe(effort[String(req.body.model)]);
+      expectNoSampling(req.body);
+      expect(req.body).not.toHaveProperty("thinking");
+    }
+    expect(seen.some((r) => r.url.includes("/models/gemini-3.8-flash:generateContent"))).toBe(true);
+    expect(seen.some((r) => r.url.includes("/models/gemini-3.5-flash-lite:generateContent"))).toBe(true);
+    // SPEC §1.3 gpt-6.1-sol row: sampling removed (400), tools need the Responses API, so the plain probe goes to /v1/responses.
+    const sol = seen.filter((r) => r.url.includes("api.openai.com") && r.body.model === "gpt-6.1-sol");
+    expect(sol, "exactly one probe request names gpt-6.1-sol").toHaveLength(1);
+    expect(sol[0].url).toBe("https://api.openai.com/v1/responses");
+    expect(sol[0].headers.authorization).toBe("Bearer test-openai-key");
+    expectNoSampling(sol[0].body);
+    expect(sol[0].body).not.toHaveProperty("tools");
+  });
+
+  it("scripts/eval/providerParseSmoke.ts: the gemini default reaches Google (provider is \"gemini\", not \"google\"); claude-haiku-5-5 carries its effort", async () => {
+    const table = JSON.stringify({ tables: [{ title: "t", columns: ["Company"], rows: [["Acme"]] }] });
+    installFakeTransport((req) => req.url.includes("api.anthropic.com")
+      ? { ...anthropicMessage(String(req.body.model)), content: [{ type: "tool_use", id: "tu_1", name: "json", input: JSON.parse(table) }], stop_reason: "tool_use" }
+      : generateContent(table));
+    vi.resetModules();
+    const argvBefore = process.argv;
+    process.argv = ["node", "providerParseSmoke"]; // no model argument: the script's own defaults (gemini-3.8-flash, gpt-5.4-mini, claude-haiku-5-5); the OpenAI one has no key here and is reported as an error
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await import("../scripts/eval/providerParseSmoke");
+      for (let i = 0; i < 100 && !(seen.some((r) => r.url.includes("api.anthropic.com")) && seen.some((r) => r.url.includes("generativelanguage"))); i++) await new Promise((r) => setTimeout(r, 20));
+    } finally { process.argv = argvBefore; }
+    const google = seen.filter((r) => r.url.includes("generativelanguage.googleapis.com"));
+    expect(google.length, "the Gemini smoke reaches Google").toBeGreaterThan(0);
+    for (const req of google) { expect(req.url).toContain("/models/gemini-3.8-flash:generateContent"); expectNoSampling(req.body); }
+    expect(seen.some((r) => r.url.includes("api.openai.com")), "no Gemini id falls through to OpenAI").toBe(false);
+    const anthropic = seen.filter((r) => r.url.includes("api.anthropic.com"));
+    expect(anthropic.length).toBeGreaterThan(0);
+    for (const req of anthropic) { expect(req.body.model).toBe("claude-haiku-5-5"); expect(req.body.output_config?.effort).toBe("medium"); expectNoSampling(req.body); }
+  });
+
+  it("scripts/startup-diligence-provider-eval.ts: the Gemini candidate is gemini-3.8-flash, the Anthropic one claude-haiku-5-5", async () => {
+    const { runStartupDiligenceProviderEval } = await import("../scripts/startup-diligence-provider-eval");
+    installFakeTransport(respondByWire("not json")); // every candidate is attempted, then the aggregate error lists them in order
+    await expect(runStartupDiligenceProviderEval({ noWrite: true })).rejects.toThrow(/gemini-3\.8-flash[\s\S]*claude-haiku-5-5/);
+    expect(seen[0].url).toContain("/models/gemini-3.8-flash:");
+    const claude = seen.find((r) => r.url.includes("api.anthropic.com"));
+    expect(claude?.body.model).toBe("claude-haiku-5-5");
+    expectNoSampling(claude!.body);
+  });
+
+  // Review round 7, defect 1 (SPEC-v9 D1). Persona: an evaluator passes `--model gemini-not-in-catalog`. origin/main sent ONE request and
+  // reported that model. The contract eval then handed the provider's resolved id to agentJobs.createOrReuse, whose public boundary
+  // refuses an id outside the catalog (unknown_model_policy): the candidate loop swallowed that, paid for a second request to
+  // gemini-3.8-flash and reported the wrong model. The job now carries the catalog free route; the report names the model measured.
+  it("scripts/startup-diligence-provider-eval.ts: an operator --model the catalog does not know is the only request and the reported model", async () => {
+    const { runStartupDiligenceProviderEval } = await import("../scripts/startup-diligence-provider-eval");
+    const draft = JSON.stringify({
+      cellPayload: { kind: "CellPayload", value: "CardioNova is an AI triage workflow for hospital intake with $1.5M cash.", confidence: 0.8, status: "needs_review", evidence: [{ source: "intake", sourceRef: "cardionova-intake.pdf#page=1", quote: "AI triage workflow for hospital intake" }] },
+      finalText: "CardioNova summary written to the research row and queued for host review with evidence.",
+    });
+    installFakeTransport(respondByWire(draft));
+    const out = await runStartupDiligenceProviderEval({ model: "gemini-not-in-catalog", noWrite: true });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].url).toContain("/models/gemini-not-in-catalog:generateContent");
+    expect(out.errors).toEqual([]);
+    expect(out.providerGenerated.resolvedModel).toBe("gemini-not-in-catalog");
+    expect(JSON.stringify(out.report)).toContain("gemini-not-in-catalog");
+    expect(JSON.stringify(out.report)).not.toContain("gemini-3.8-flash");
+    expect(out.report.pass).toBe(true);
+  }, 60_000);
+});
+
+// ───────────────────────────── .env.example (SPEC §1.4 class N, "example") ─────────────────────────────
+
+describe(".env.example copies of changed defaults equal what the code defaults to", () => {
+  const envExample = readFileSync(".env.example", "utf8");
+  const value = (name: string): string => {
+    const match = envExample.match(new RegExp(`^${name}=(.*)$`, "m"));
+    expect(match, `${name} is present in .env.example`).not.toBeNull();
+    return match![1].trim();
+  };
+
+  it("NODEAGENT_FREE_AUTO_GOOGLE_MODEL is the default agent model", () => {
+    expect(value("NODEAGENT_FREE_AUTO_GOOGLE_MODEL")).toBe(DEFAULT_AGENT_MODEL);
+  });
+
+  it("VOICE_GEMINI_TTS_MODEL is the model synthesizeWithGemini sends when the variable is unset", async () => {
+    process.env.VOICE_TTS_PROVIDER = "gemini";
+    installFakeTransport(() => pcmAudio());
+    await synthesizeThroughRoute();
+    expect(value("VOICE_GEMINI_TTS_MODEL")).toBe(seen[0].body.model);
+    expect(value("VOICE_GEMINI_TTS_MODEL")).toBe(TTS_MODEL);
+  });
+
+  it("PROVIDER_PARSER_*_MODEL lists are the code's default candidate lists", () => {
+    for (const [provider, name] of [["gemini", "PROVIDER_PARSER_GEMINI_MODEL"], ["anthropic", "PROVIDER_PARSER_ANTHROPIC_MODEL"], ["openrouter", "PROVIDER_PARSER_OPENROUTER_MODEL"]] as const) {
+      expect(value(name).split(",").map((s) => s.trim()), name).toEqual(providerParserModelCandidates(provider, undefined, {}));
+    }
+    expect(value("PROVIDER_PARSER_OPENROUTER_MODEL")).not.toContain("nex-agi/nex-n2-pro"); // absent from the OpenRouter catalog
+  });
+
+  it("GEMINI_SEO_VIDEO_JUDGE_MODEL is the model the SEO judge script sends by default", async () => {
+    mkdirSync(FIXTURE_ROOT, { recursive: true });
+    const dir = mkdtempSync(join(FIXTURE_ROOT, "env-"));
+    try {
+      const mp4 = join(dir, "clip.mp4");
+      writeFileSync(mp4, Buffer.from("00000018667479706d703432", "hex"));
+      const requests = await runJudgeScript(() => import("../skills/seo-qa/scripts/judge-video-gemini"), ["--input", mp4, "--out-dir", join(dir, "out")]);
+      expect(requests[0]?.url).toContain(`/models/${value("GEMINI_SEO_VIDEO_JUDGE_MODEL")}:generateContent`);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("no deprecated, shut-down or unlisted id survives in the example file", () => {
+    for (const stale of ["gemini-3.5-flash", "gemini-3.1-flash-tts-preview", "claude-haiku-4-5", "nex-agi/nex-n2-pro", "gemini-2.5-flash"]) {
+      const lines = envExample.split(/\r?\n/).filter((l) => !l.startsWith("#") && l.includes(stale));
+      expect(lines, stale).toEqual([]);
+    }
+    expect(existsSync(".env.example")).toBe(true);
+  });
+});
diff --git a/tests/openAiTokenLimit.test.ts b/tests/openAiTokenLimit.test.ts
index a302a86a..aff4fdea 100644
--- a/tests/openAiTokenLimit.test.ts
+++ b/tests/openAiTokenLimit.test.ts
@@ -8,6 +8,12 @@ describe("OpenAI-compatible token limit params", () => {
     });
   });
 
+  it("uses max_completion_tokens for direct OpenAI gpt-6 models too (max_tokens is rejected on the gpt-5+ line)", () => {
+    // SPEC A.2.9 precondition: no gpt-6 id lands in NodeRoom in this PR, but the guard must not be the thing that 400s one.
+    expect(openAiCompatibleTokenLimitParam("gpt-6.1-sol", "https://api.openai.com/v1/chat/completions", 1024)).toEqual({ max_completion_tokens: 1024 });
+    expect(openAiCompatibleTokenLimitParam("gpt-6-luna", "https://openrouter.ai/api/v1/chat/completions", 1024)).toEqual({ max_tokens: 1024 });
+  });
+
   it("keeps max_tokens for OpenRouter and older direct chat models", () => {
     expect(openAiCompatibleTokenLimitParam("gpt-5.4-nano", "https://openrouter.ai/api/v1/chat/completions", 1024)).toEqual({
       max_tokens: 1024,
diff --git a/tests/openRouterFreeModels.test.ts b/tests/openRouterFreeModels.test.ts
index b31053ed..589c02d6 100644
--- a/tests/openRouterFreeModels.test.ts
+++ b/tests/openRouterFreeModels.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { priceRun } from "../src/nodeagent/models/adapter";
+import { DEFAULT_AGENT_MODEL } from "../convex/modelDefaults";
 import { getProviderForModel, resolveModelAlias } from "../src/nodeagent/models/modelCatalog";
 import {
   OPENROUTER_FREE_AUTO_MODEL,
@@ -226,7 +227,8 @@ describe("OpenRouter free auto routing", () => {
 
   it("keeps free-auto opt-in instead of hiding it behind generic aliases", () => {
     expect(resolveModelAlias("openrouter")).toBe("z-ai/glm-5.2");
-    expect(resolveModelAlias("auto")).toBe("gemini-3.5-flash");
+    // was "gemini-3.5-flash" (deprecated by Google 2026-10-08); the alias now follows the default-model constant.
+    expect(resolveModelAlias("auto")).toBe(DEFAULT_AGENT_MODEL);
     expect(resolveModelAlias("free")).toBe(OPENROUTER_FREE_AUTO_MODEL);
     expect(resolveModelAlias("free-auto")).toBe(OPENROUTER_FREE_AUTO_MODEL);
     expect(resolveModelAlias("kimi")).toBe("moonshotai/kimi-k2.7-code");
diff --git a/tests/phaseModel.test.ts b/tests/phaseModel.test.ts
index 3d2f4fa0..05f8ea38 100644
--- a/tests/phaseModel.test.ts
+++ b/tests/phaseModel.test.ts
@@ -70,9 +70,12 @@ describe("modelForFramePhase", () => {
 
   it("falls back when an artifact-aware egress gate rejects the phase override", () => {
     const env = { AGENT_ORCHESTRATOR_MODEL: "openrouter/free-auto" };
-    expect(authorizedModelForFramePhase("plan", "anthropic/claude-sonnet-4", () => false, env))
-      .toBe("anthropic/claude-sonnet-4");
-    expect(authorizedModelForFramePhase("plan", "anthropic/claude-sonnet-4", () => true, env))
+    // The fallback argument stands in for an operator-set AGENT_TOP_PAID_MODEL; claude-sonnet-4 retired 2026-06-15 (SPEC A.2.9), so the
+    // fixture follows the current wire id. The function under test only passes the argument through.
+    const TOP_PAID_FALLBACK = "anthropic/claude-sonnet-5.5";
+    expect(authorizedModelForFramePhase("plan", TOP_PAID_FALLBACK, () => false, env))
+      .toBe(TOP_PAID_FALLBACK);
+    expect(authorizedModelForFramePhase("plan", TOP_PAID_FALLBACK, () => true, env))
       .toBe("openrouter/free-auto");
   });
 
diff --git a/tests/privateArtifactVisibility.test.ts b/tests/privateArtifactVisibility.test.ts
index 206f3e80..5b1fc91d 100644
--- a/tests/privateArtifactVisibility.test.ts
+++ b/tests/privateArtifactVisibility.test.ts
@@ -148,7 +148,7 @@ describe("private artifact visibility", () => {
       goal: "Research this private upload",
       entrypoint: "public_ask" as const,
       scope: "public_room" as const,
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       idempotencyKey: "private-artifact-guest-job",
     })).rejects.toThrow(/artifact_not_visible/);
     await expect(t.mutation(api.agentJobs.startFreeAuto, {
diff --git a/tests/providerParserLive.test.ts b/tests/providerParserLive.test.ts
index 33f69d50..37a92b9f 100644
--- a/tests/providerParserLive.test.ts
+++ b/tests/providerParserLive.test.ts
@@ -25,10 +25,17 @@ describe("live provider parser helpers", () => {
   });
 
   it("prefers explicit and env models before defaults without duplicates", () => {
-    const candidates = providerParserModelCandidates("gemini", "gemini-3.5-flash", {
-      PROVIDER_PARSER_GEMINI_MODEL: "gemini-2.5-flash",
+    // Defaults were [3.5-flash, 3-flash-preview, 2.5-flash, 2.0-flash]; 2.5 expires on OpenRouter 2026-10-20 and 2.0 is
+    // shut down, so the defaults are [3.8-flash, 3.6-flash]. The env id is NOT a default (3.5-flash-lite), so its
+    // position proves the precedence: preferred first, then env, then the defaults. The preferred id is a default,
+    // so it also proves de-duplication.
+    const candidates = providerParserModelCandidates("gemini", "gemini-3.8-flash", {
+      PROVIDER_PARSER_GEMINI_MODEL: "gemini-3.5-flash-lite",
     });
-    expect(candidates.slice(0, 3)).toEqual(["gemini-3.5-flash", "gemini-2.5-flash", "gemini-3-flash-preview"]);
+    expect(candidates).toEqual(["gemini-3.8-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash"]);
+    // An env id that IS a default is listed once, at the env position.
+    expect(providerParserModelCandidates("gemini", "gemini-3.8-flash", { PROVIDER_PARSER_GEMINI_MODEL: "gemini-3.6-flash" }))
+      .toEqual(["gemini-3.8-flash", "gemini-3.6-flash"]);
   });
 
   it("redacts API key values from provider errors", () => {
diff --git a/tests/qaMatrix.test.ts b/tests/qaMatrix.test.ts
index 284aa1d7..5c04ab41 100644
--- a/tests/qaMatrix.test.ts
+++ b/tests/qaMatrix.test.ts
@@ -100,17 +100,25 @@ describe("production QA matrix", () => {
 
   it("keeps the Convex interactive fallback on a ladder-safe route", () => {
     const source = readFileSync(join(root, "convex/agent.ts"), "utf8");
-    const match = source.match(/AGENT_MODEL\s*\?\?\s*"([^"]+)"/);
-    expect(match, "convex/agent.ts must declare an explicit AGENT_MODEL fallback").toBeTruthy();
-    const fallback = match![1];
-    const route = matrix.modelLadder.routes.find((r) => r.modelRoute === fallback);
-    expect(route, `${fallback} is not recorded in the model ladder`).toBeTruthy();
-    expect([route!.l1, route!.l2, route!.l3, route!.l4], `${fallback} is not L1-L4 safe`).toEqual([
-      "PASS",
-      "PASS",
-      "PASS",
-      "PASS",
-    ]);
+    // The fallback is either a literal or, since the 2026-10 model refresh, the DEFAULT_AGENT_MODEL constant that
+    // convex/modelDefaults.ts owns. Both must resolve to an explicit id; the L1-L4 check below is unchanged.
+    // EVERY `AGENT_MODEL ?? <fallback>` in the file is checked (public_ask and private_agent), not just the first:
+    // reverting one of them to an unqualified literal must not be masked by the other.
+    const matches = [...source.matchAll(/AGENT_MODEL\s*\?\?\s*(?:"([^"]+)"|(DEFAULT_AGENT_MODEL))/g)];
+    expect(matches.length, "convex/agent.ts must declare an explicit AGENT_MODEL fallback at both the public_ask and private_agent roles").toBeGreaterThanOrEqual(2);
+    const constant = readFileSync(join(root, "convex/modelDefaults.ts"), "utf8").match(/export const DEFAULT_AGENT_MODEL\s*=\s*"([^"]+)"/)?.[1];
+    for (const match of matches) {
+      expect(match[1] || constant, "DEFAULT_AGENT_MODEL must be a string literal").toBeTruthy();
+      const fallback = (match[1] ?? constant)!;
+      const route = matrix.modelLadder.routes.find((r) => r.modelRoute === fallback);
+      expect(route, `${fallback} is not recorded in the model ladder`).toBeTruthy();
+      expect([route!.l1, route!.l2, route!.l3, route!.l4], `${fallback} is not L1-L4 safe`).toEqual([
+        "PASS",
+        "PASS",
+        "PASS",
+        "PASS",
+      ]);
+    }
   });
 
   it("publishes the generated QA cockpit from README", () => {
diff --git a/tests/roomWorkCache.test.ts b/tests/roomWorkCache.test.ts
index a18598ac..6d210dfa 100644
--- a/tests/roomWorkCache.test.ts
+++ b/tests/roomWorkCache.test.ts
@@ -207,7 +207,7 @@ describe("room-work entity/facet cache", () => {
       goal: "Room work agent_fill: Fill company_profile for CardioNova.",
       entrypoint: "room_work",
       scope: "public_room",
-      modelPolicy: "test-model",
+      modelPolicy: "z-ai/glm-5.2",
       idempotencyKey: key,
       mode: "research",
     });
diff --git a/tests/voiceHostedTtsProviders.test.ts b/tests/voiceHostedTtsProviders.test.ts
index 1a2c92cf..a3f4d51e 100644
--- a/tests/voiceHostedTtsProviders.test.ts
+++ b/tests/voiceHostedTtsProviders.test.ts
@@ -17,7 +17,8 @@ describe("hosted free-tier voice TTS providers", () => {
   it("wires the documented hosted TTS adapters without making OpenAI the free-only default", () => {
     expect(httpSource).toContain("synthesizeWithGemini");
     expect(httpSource).toContain("https://generativelanguage.googleapis.com/v1beta/models");
-    expect(httpSource).toContain("gemini-3.1-flash-tts-preview");
+    // was "gemini-3.1-flash-tts-preview" (Google shutdown 2026-11-17); vendor-named replacement, SPEC A.0.7 voice exception.
+    expect(httpSource).toContain("gemini-3.8-flash-tts");
     expect(httpSource).toContain(":generateContent");
     expect(httpSource).toContain('responseModalities: ["AUDIO"]');
     expect(httpSource).toContain("prebuiltVoiceConfig");
diff --git a/vitest.config.ts b/vitest.config.ts
index 3dbab5d1..0e7460fa 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -21,7 +21,7 @@ export default defineConfig({
           name: "node",
           environment: "node",
           pool: "forks",
-          include: ["tests/**/*.test.ts", "src/**/*.test.ts"],
+          include: ["tests/**/*.test.ts", "src/**/*.test.ts", "evals/**/*.test.ts"],
         },
       },
       {
diff --git a/walkthrough-review.config.json b/walkthrough-review.config.json
index c36bcede..81457c4c 100644
--- a/walkthrough-review.config.json
+++ b/walkthrough-review.config.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "defaultModel": "gemini-3.5-flash",
+  "defaultModel": "gemini-3.6-flash",
   "defaultBase": "https://noderoom.live",
   "envFile": ".env.local",
   "outputRoot": "docs/eval/walkthrough-review",