Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs: record the availability spelling rule and the route-table gate's blind spots

Jack Rudenko8dfcfb79646e
diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.md
index 88140201..ff330179 100644
--- a/ai-docs/architecture/routing.md
+++ b/ai-docs/architecture/routing.md
@@ -75,7 +75,8 @@ project rules and nothing else.
window, then provider name.
3. **Append the fallback hop** (below).
4. Credential filter (unchanged).
-5. Availability filter (unchanged) — only a POSITIVE "not-served" removes anything.
+5. Availability filter — only a POSITIVE "not-served" removes anything, and it asks each
+ provider in that provider's own spelling (see below).
6. Primary + fallbacks.
**No catalog means local only.** With no readable catalog a bare name returns a no-route naming
@@ -93,6 +94,41 @@ Each claim's namespace is ALSO owned by a metered sibling defined EARLIER in
auto-detection unchanged — two claimants on one namespace is now fine, because the function
that picked a single winner (`getProviderForModel`) no longer exists.
+**The availability filter must ask in the provider's OWN spelling.** A provider that encodes
+knobs into its model ids never lists a bare canonical id: Devin's dynamic models catalog holds
+`swe-1-7`, `swe-1-7-medium` and `swe-1-7-lightning`, never `swe-1.7`. Its transport maps the
+requested name onto one of those through `expandSelection` (`providers/model-resolvers/`) when
+it sends. `providerServesModel` therefore resolves through the same resolver BEFORE comparing,
+so the filter and the transport answer the same question. Until 2026-09-23 it compared the raw
+string, answered "not-served" for every canonical id Devin carries, and "not-served" is the one
+verdict allowed to remove a candidate: a bare `swe-1.7` lost its Devin hop and went to the
+OpenRouter fallback ("swe-1.7 is not a valid model ID"), and the explicit `[email protected]` was
+refused outright, since `routeExplicit` runs the same check. A provider with no registered
+resolver gets its id back unchanged, so this costs every other provider nothing. A new
+knob-encoding provider needs a resolver entry, or the filter will deny it by spelling.
+
+## Changing anything that decides a chain: the route-table gate
+
+A passing suite does not show a routing change is safe. It asserts the routes someone thought to
+write down, and a silent removal hides in the ones nobody did.
+`scripts/route-table-snapshot.ts capture|diff` pins the resolved chain of EVERY catalog model
+through the real `route()`, before and after, and classifies each difference. Capture before the
+change; after is too late. Both snapshots must be on the same catalog generation.
+
+The gate has two measured blind spots, and a clean diff means "nothing changed for the models
+this machine can see", never "nothing changed":
+
+- **Credentials.** It runs on this machine's keys. Filtering virtual providers out of the gatherer
+ removed `native-anthropic` from every `claude-*` chain, and the diff reported nothing, because
+ this machine sets no `ANTHROPIC_API_KEY` and the hop was already being dropped. Two routing tests
+ that set the key caught it.
+- **Scope.** It walks catalog models only. The Devin spelling fix above changed routing for names
+ a dynamic subscription serves and the catalog does not publish, and the catalog held no `swe-*`
+ model at all, so the diff showed no change. The reproduction was the evidence.
+
+Run the suite as the complement: the gate covers breadth the suite cannot, and the suite covers
+credential states and non-catalog names the gate cannot.
+
## Default Provider Configuration (v7.0.0+)
`defaultProvider` names the **fallback hop** — the last position in a gathered chain. It is a
diff --git a/ai-docs/release.md b/ai-docs/release.md
index 3ce98383..cd7b2670 100644
--- a/ai-docs/release.md
+++ b/ai-docs/release.md
@@ -125,9 +125,12 @@ Two constraints hold regardless of who authorises:
shared with the main checkout and every sibling worktree. Never `git stash`
during a release; use a WIP commit.
-TODO — not settled by detection, and worth answering on the next release:
-- whether a failed magmux download from `MadAppGang/magmux` should block a release
- or pin to a known-good magmux tag instead of `latest`.
+SETTLED 2026-09-23 — the magmux source. The build keeps downloading the LATEST
+release of `MadAppGang/magmux`; it is not pinned to a known-good tag. A failed
+download, or a latest release missing a platform asset, BLOCKS the release: the
+build job fails before anything publishes, which is the intended behaviour and
+needs no workflow change. Decided by the repository owner when asked during the
+v10.0.2 release. Preflight checks it by listing the latest release's assets.
SETTLED 2026-09-15 — the two `displayWidth` tests in
`packages/cli/src/tui/viz/color.test.ts`. They were NOT flaky and must NOT be