Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(architecture): record the preflight chain walk and hop decision
Jack Rudenko3cc05d8e21d0
diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.mdindex c98b7377..3fa0ef25 100644--- a/ai-docs/architecture/adapters.md+++ b/ai-docs/architecture/adapters.md@@ -713,6 +713,27 @@ before the subscription 401 rule. An `"Invalid API key."` 401 or 403 is still a`FallbackCandidate.provider` now carries the claudish provider uid. `isRetryableError` used toreceive the candidate's DISPLAY name, and `isSubscriptionProvider("Kimi Coding")` is false.+### The hop decision is one function (`handlers/shared/hop-decision.ts`)++What `FallbackHandler.handle` does after a hop that did not answer `ok` is the pure function+`decideHopFailure`, with `isRetryableError`, `isSubscriptionCredentialRejection` and `isProvider`+beside it (`fallback-handler.ts` re-exports them). Its reasons, in the handler's order:+`recovery-hold`, `stream-failure`, `credential-hold` (stop, response verbatim);+`subscription-credential-rejected` (advance, announced); `retryable` (advance) and `non-retryable`+(stop); and `thrown` (advance), which the handler's `catch` asks for. It lives in its own module so+the probe can import it without loading `composed-handler.ts`: `probeLink` sets+`ProbeResult.chainAction` from it, and MCP `preflight` walks a model's routing chain by it+(`mcp-sessions.md`). A second copy of the rule is how preflight once said "drop or replace" for a+model whose later hop served (D6). `handle()` now reads the error body from a clone before deciding,+also for the three verbatim stops; each is claudish's own small JSON body and is still returned as is.++A probe pins one hop, so no `FallbackHandler` catches a hop that throws: the `/v1/messages` route's+catch answers 500 with the error text (a pinned hop's throw never reaches `app.onError`, measured).+That 500 carries `x-claudish-unhandled-error: 1` when the resolved handler itself threw, and so does+`app.onError`'s; `probeLink` maps the marker to `advance / thrown`, which is what the runtime does+with a throw inside a chain. A malformed body or a terminal routing failure is not marked. The header+changes nothing for Claude Code (same status, body and envelope).+## The catalog's endpoint contract has two halves (v9.0.7)> **Superseded (10.5.0).** The gate, the name rule and the model-level `tokenParam` readdiff --git a/ai-docs/architecture/mcp-sessions.md b/ai-docs/architecture/mcp-sessions.mdindex 3f57c422..4a3c4e52 100644--- a/ai-docs/architecture/mcp-sessions.md+++ b/ai-docs/architecture/mcp-sessions.md@@ -409,6 +409,31 @@ of the PROVIDER, not the model, so the same bare name can be free through a planor billed per token depending on which credential is present — which is preciselywhat a caller cannot see from the model id.+**`preflight` judges a model by its ROUTING CHAIN** (`providers/preflight-chain.ts`). It used to+plan with `route()` and probe only the primary, so a model whose first hop failed got "❌" and+"Drop or replace before running" even when a later hop served it (six models behind one expired Zen+Go key on 2026-10-21; `model-failures-2026-10-21.md`, D6). Now `preflightModel` takes the kept hops+from `explainRoute` → `probeTargets` (the chain `--probe` shows, in order) and probes each until one+is live. A failed hop is followed by `ProbeResult.chainAction`, which `probeLink` sets with+`decideHopFailure`, the SAME function `FallbackHandler` uses (`adapters.md`): advance, or stop here+because a real request would stop here too (a connection fault, a stream failure, a credential hold+on a metered hop). Two walker defaults stop rather than guess: a non-live result with no+`chainAction` (`no-decision`, e.g. `key-missing`), and a probe that throws (`probe-error`). A native+Claude name is never probed (the third outcome). Metered hops are probed like any other: a configured+key is consent, and the runtime would use that hop.++Output contract: the table's Provider, Billing and Model spec describe the SERVING hop; Status is+`✅ live · hop i/n`, `❌ <state> · chain stops at hop i/n` or `❌ every hop failed (n)`, with+` (+k untried)`; every failed hop is listed under "Failed hops:" with its probe spec, billing word+and where the chain went; "Drop or replace before running" lists only models no hop serves. The+billing counts follow the serving hop.++Cost: at most one probe per kept hop, stopping at the first live one, so a model whose first hop+serves costs what it always did. `timeout_ms` applies PER HOP; the worst case per model is hops ×+`timeout_ms`, carried by `heartbeat: true` and a progress message per hop+(`preflight: <model> · hop i/n`). Preflight models a FRESH chain: `FallbackHandler` starts at its+`lastSuccessIndex` in a long-lived proxy, preflight always at hop 1, which is what a new session sees.+**The polling verbs are the frozen mod contract v1** (`pane/contract.ts`, summarised in`pane-session.md`): `list_sessions` answers `{contract_version, capabilities, sessions}` with one`SessionRow` per session (state, reason, `reason_detail`, tokens, `cost_usd`, tool calls, turns, `idle_seconds`,