Skip to content

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.md
index 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 to
receive 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` read
diff --git a/ai-docs/architecture/mcp-sessions.md b/ai-docs/architecture/mcp-sessions.md
index 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 plan
or billed per token depending on which credential is present — which is precisely
what 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`,