omp-llm-role 1.3.0 → 1.4.0

package/README.md

@@ -126,6 +126,7 @@ Global knobs:
 | `priceSwitchFraction` | `0.5` | Inside the margin, adopt a challenger at least this fraction cheaper (0.5 = half the $/M); `0` disables |
 | `writeFallbackChains` | `true` | Write per-role fallback chains into `config.yml` |
 | `fallbackChainDepth` | `2` | Fallback models per role chain |
+| `fallbackQualityFloor` | `0.9` | A cheaper-or-equal fallback must retain at least this fraction of the chosen model's quality; `0` disables |
 | `activateDefaultOnEmptySession` | `true` | Reapply the new `default` selector to an empty session's active model |
 | `tokenProfile` | unset | `{ inputTokens, outputTokens }` per task for the explorer's `$/task` column, used when a role has no recorded usage. Display-only; the recorded usage takes precedence. Unset = the column reads `—` |
 | `errorReporting` | `off` | Opt-in reporting of **unexpected** plugin errors as GitHub issues on `Gott50/omp-llm-role`; one of `off`, `ask`, `auto` (see below) |
@@ -160,7 +161,7 @@ defaults.
 |---|---|---|
 | `endpointCeilings` | `filters.tools: true`, `filters.minOutputTokens: 16384` | Routes that cannot call tools and routes whose output ceiling is below 16 384 tokens leave the pool — a reasoning model is not cut off mid-thought |
 | `cachePricing` | `cacheHitRate: 0.5` | The role is priced on a cache-heavy agent loop's invoice (the endpoint's `cacheReadPrice` blended in) rather than the sticker price |
-| `providerPinning` | `preferOwnProvider: true`, `filters.preferredMinThroughput: 50` | Each request is bound to the model's **best provider route** — the max-value-for-money route (the `vfm` score, with a soft 50 tok/s floor that deprioritizes a pathologically slow route without dropping it) — the selector gains `@<slug>` — and the fallback chain carries the primary model on every gate-passing route except the pinned best, then each fallback model on every gate-passing route, so a down provider fails over to another provider of the same model before the chain switches models. The model is priced **and measured** on that route (its billed price and p50 throughput, so `q` moves too), falling back to the default blend only when it has no candidate route |
+| `providerPinning` | `preferOwnProvider: true`, `filters.preferredMinThroughput: 50` | Each request is bound to a provider route **that OpenRouter actually serves**: the updater walks the model's value-for-money route order (the `vfm` score, with a soft 50 tok/s floor that deprioritizes a pathologically slow route without dropping it) and **probes each candidate with a one-token request bound to it** (`provider: { only: [slug] }`), pinning the first route the request does not reject and **dropping the pin** (bare selector, OpenRouter's own routing) when no candidate is routable — so a role never 404s on a route the endpoints data still called healthy. The selector gains `@<slug>`, and the fallback chain carries the primary model on every gate-passing route except the pinned one, then each of the next `fallbackChainDepth` fallback models on every gate-passing route — each drawn from the role's own ranking below the primary, the cheaper-or-equal ones that keep at least `fallbackQualityFloor` of its quality first, then the pricier — so a down provider fails over to another provider of the same model before the chain switches models, and a failover never silently multiplies the spend or drops the role onto a much weaker model. The model is priced **and measured** on its score-max route (its billed price and p50 throughput, so `q` moves too), falling back to the default blend only when it has no candidate route |
 | `costCap` | `filters.maxPriceUsdPerM: 10` | The priciest tail of the eligible pool leaves it, so the pick cannot be an expensive outlier |
 
 Precedence is one rule:

package/docs/dev/architecture.md

@@ -29,12 +29,12 @@ the extension's `/refresh-roles`, `/explore-roles` and `/create-agent`.
 | `src/benchmark-sources.ts` | The benchmark-source registry: the single source of truth for which sources exist, what metric each feeds, and how to fetch/parse/join each. Exports `BENCHMARK_SOURCES` (the shipped static sources), `resolveBenchmarkSource`, `declaredSourceForLink`, `sourceForMetric`, `parseBenchmarkPayload`, `parseBenchmarkPayloadMeta`, `loadBenchmarkScores`, `applyBenchmarkScores`, `joinBenchmarkScores`, `normalizeMetricKey`, `externalMetricKey`, `normalizeDesignId`, `parseWritingEvidence`, `parseLlmStatsBenchmark`, `parseBenchmarkCatalog`, `loadBenchmarkCatalog`, `cachedSourceInfo`, `catalogMetric`, `SHIPPED_CATALOG_METRICS`, the declarative-source surface (`SourceDeclaration`, `validateDeclaration`, `parseSourceDeclaration`, `loadDeclaredSources`, `saveDeclaredSource`, `declaredSourcesPath`, `declarationToSource`, `executeDeclaration`, `llmStatsBenchmarkDeclaration`, `genericBenchmarkSource`, `dryRunDeclaration`), the fetch helpers (`fetchJson`, `fetchText`), and the `BenchmarkSource`/`JoinRule`/`BenchmarkScores`/`BenchmarkPayloadMeta`/`FocusSourceInfo`/`BenchmarkCatalogEntry`/`DeclarationDryRun` types. Imports `engine.ts` for types only, so there is no runtime cycle. |
 | `src/settings.ts` | Shipped defaults and the settings merge/validate path. Exports `DEFAULT_ROLES`, `DEFAULT_SETTINGS`, `SHIPPED_AGENTS`, `KNOWN_METRICS`, `isKnownMetric` (a shipped key or an external `<ns>:<local>`), `PLUGIN_SETTINGS_PATH`, `ACTIVATE_DEFAULT_KEY`, `deriveSettingsSchema`, `readPluginSettingsMap`, `resolveSettings`, `roleUniverse`, `deepMergeInto`, `findProjectAnchor`, `projectLockPath`, and the `ResolvedSettings`/`PluginSettingSchema`/`UniverseEntry`/`RoleKind` types. `ResolvedSettings` carries `tokenProfile` (`{ inputTokens, outputTokens } | null`, default `null`) — the user-set per-task token profile the explorer's per-task price falls back to when a role has no recorded usage; validated to finite numbers ≥ 0, schema rows `tokenProfile.inputTokens`/`tokenProfile.outputTokens`. `readPluginSettingsMap` merges the project lock file (`projectLockPath(cwd)` = `<cwd>/.omp/plugins/omp-plugins.lock.json`, omp's project dir with **no walk-up**) over the user-level one; `findProjectAnchor` (the walk-up `.omp`/`.git` anchor) is kept only for the `/project-roles` divergence warning. |
 | `src/agent-pins.ts` | Agent → pinned-role derivation. Exports `parseAgentPin` (first `@<role>` in the `model:` frontmatter) and `discoverAgentPins` (scans the shipped, user and project agent dirs; project > user > plugin). Drives the `task.disabledAgents` sync. |
-| `src/availability.ts` | Key tier gate, catalog filter, variant resolution, provider-allowlist probe, the keyed-catalog availability primitive, and the allowed-providers whitelist harvest. The keyed source is the Bearer-authenticated `GET /api/v1/models` (the account setting "Filter the model catalog for API keys" makes it a per-key allowlist; set membership is the only signal), shared by the explorer and the updater's companion fast path. Exports `fetchKeyMeta`, `tierGate`, `filterCatalog`, `rankingIdOf`, `currentRankingId`, `resolveVariant`, `enrichThinkingLevels`, `probeModel`, `fetchAllowedProviders`, `providerAllowed`, `computeKeyAvailability`, `fetchKeyAvailability`, `catalogFromOmpModelsJson`, `THINKING_LEVELS`, and the `CatalogEntry`/`KeyMeta`/`Tier`/`ProbeVerdict`/`KeyAvailability` types. |
+| `src/availability.ts` | Key tier gate, catalog filter, variant resolution, the model probe, the auto-pin's route probe, the keyed-catalog availability primitive, and the allowed-providers whitelist harvest. The keyed source is the Bearer-authenticated `GET /api/v1/models` (the account setting "Filter the model catalog for API keys" makes it a per-key allowlist; set membership is the only signal), shared by the explorer and the updater's companion fast path. Exports `fetchKeyMeta`, `tierGate`, `filterCatalog`, `rankingIdOf`, `currentRankingId`, `resolveVariant`, `enrichThinkingLevels`, `probeModel`, `probeRoute` (the same one-token completion plus `provider: { only: [slug] }` — the auto-pin's routability gate; spec #90), `fetchAllowedProviders`, `providerAllowed`, `computeKeyAvailability`, `fetchKeyAvailability`, `catalogFromOmpModelsJson`, `THINKING_LEVELS`, and the `CatalogEntry`/`KeyMeta`/`Tier`/`ProbeVerdict`/`KeyAvailability` types. |
 | `src/config-edit.ts` | Surgical line-oriented YAML patch for `modelRoles` + `retry.fallbackChains` + `task.disabledAgents`, plus the atomic writer. Exports `parseConfig`, `patchConfig`, `writeConfigAtomic`, `ConfigEditError`, and the `ConfigPatch` type. No runtime YAML dependency. |
 | `src/state.ts` | State/history/lock files under the agent dir, and agent-dir resolution. Exports `agentDir`, `loadState`, `saveState`, `appendHistory`, `acquireLock`, `releaseLock`, `freshState`, and the `PluginState` type (which carries `managedDisabledAgents` — the `task.disabledAgents` names the plugin added). |
 | `src/usage-ledger.ts` | The per-role usage ledger (spec #81): an append-only jsonl file (`llm-role-usage.jsonl`, cap `USAGE_LEDGER_CAP = 2000` rows) beside the plugin's other state, one row per assistant turn. Exports `UsageRow`, `TokenProfile`, `USAGE_LEDGER_FILE`, `USAGE_LEDGER_CAP`, `appendUsageRow` (best-effort, never throws), `readUsageRows` (tolerant: missing/malformed → `[]`), `roleTokenProfile` (the role's median per-turn input/output counts via `agent-create.ts`'s `quantile` — the repo's one quantile convention — or `null`), and `resolveTokenProfile` (recorded usage → the `tokenProfile` setting → `null`). The caller owns the dir; the extension records into `resolveProjectDir() ?? agentDir()`, the explorer reads the active scope's dir. |
 | `src/error-report.ts` | Opt-in reporting of **unexpected** plugin errors as GitHub issues on `Gott50/omp-llm-role` (the `errorReporting` setting). The plugin's only GitHub client and the only home for a fingerprint, a redaction rule, the agent-dir ledger (`ERROR_REPORT_LEDGER_FILE`) and the issue body. **Entry point:** `reportUnexpectedError(input, deps)` — the feature's one test seam (per-call input + fully injected `deps`; tests supply a fake `fetch`, clock, env, dir and token resolver). Also exports `defaultErrorReportDeps()` (production deps: resolved settings, global `fetch`, real clock, `agentDir`, the shipped manifest, `gh auth token`, the OS opener) and `resetErrorReportGuard()` (the in-process dedupe guard's test hook). Never throws, never rejects; a no-op when `errorReporting` is `off`. |
-| `src/updater.ts` | Orchestration: rank → tier gate → probe → hysteresis → chains → agent-disable sync → config write. Exports `runUpdater`, `resolveProjectDir` (the project scope's `<cwd>/.omp` when it carries a non-empty `omp-llm-role` settings entry, else `null` — the same test the explorer's scope resolution and the extension's usage-ledger dir use), the `Deps`/`Decision`/`RunResult`/`Trigger`/`DecisionReason` types. Resolves the project scope (`<cwd>/.omp` when it carries an `omp-llm-role` settings entry) and scopes the config/state/history/lock to it. `agentDisablePatch` also removes a previously-managed `task.disabledAgents` name whose agent file is gone. `RunResult.defect` is set on the exception-abort paths only (a `ConfigEditError`/self-check mismatch and the catch-all throw); the enumerated environment aborts leave it unset. |
+| `src/updater.ts` | Orchestration: rank → tier gate → model probe → hysteresis → auto-pin route probe → chains → agent-disable sync → config write. Exports `runUpdater`, `resolveProjectDir` (the project scope's `<cwd>/.omp` when it carries a non-empty `omp-llm-role` settings entry, else `null` — the same test the explorer's scope resolution and the extension's usage-ledger dir use), the `Deps`/`Decision`/`RunResult`/`Trigger`/`DecisionReason` types. Resolves the project scope (`<cwd>/.omp` when it carries an `omp-llm-role` settings entry) and scopes the config/state/history/lock to it. `agentDisablePatch` also removes a previously-managed `task.disabledAgents` name whose agent file is gone. `RunResult.defect` is set on the exception-abort paths only (a `ConfigEditError`/self-check mismatch and the catch-all throw); the enumerated environment aborts leave it unset. |
 | `src/extension.ts` | omp extension entry (default export). Registers `session_start` (awaited day-gated run), `/refresh-roles`, `/explore-roles` (in-process explorer), `/create-agent` (architect + benchmark-link resolution + catalog discovery), `/remove-agent`, `/project-roles` (profile architect + `setupProject` + in-process updater), and `session_shutdown`. Also subscribes to `session_start`, `retry_fallback_applied`, `retry_fallback_succeeded` and `turn_start` to keep the live model's display name suffixed with its provider pin (`src/provider-display.ts`); each handler mutates the live model's `name` in place and never calls `pi.setModel` (which would wipe omp's in-flight fallback state and clobber the thinking level). Owns `extDeps` (the extension's `Deps`) and the live-session model hook. Records the per-role usage ledger (spec #81) on `turn_end` and `session_shutdown` — one row per assistant turn read from `sessionManager.getBranch()`, into `resolveProjectDir() ?? agentDir()`, deduped by `ts|model` so the two hooks cannot double-record. Every unexpected command-handler throw and every `runUpdater` defect is routed through `src/error-report.ts`: `reportCommandError` for the six command-handler catch sites and `reportDefect` for a `runUpdater` result whose `defect` is set — each keeps the pre-existing one-line warning and adds the reporting module's own lines. |
 | `src/guards.ts` | The package's one type guard: `isRecord`. |
 | `src/provider-display.ts` | The provider display (spec #77): keep the live session model's `name` suffixed with its upstream provider pin, so omp's model segment renders e.g. `DeepSeek V4.1 Flash @coreweave/fp8`. Pure and dual-runtime (no SDK import). Exports `providerPinOf` (the single `compat.openRouterRouting.only[0]`, else `compat.vercelGatewayRouting.only[0]`; null unless exactly one non-empty string), `providerPinOfSelector` (the trailing `@<slug>` of a selector, after stripping a thinking suffix), `withProviderSuffix` (strip any previous ` @<slug>` then append, idempotent), and `applyProviderDisplay` (mutate a record's `name`; no-op otherwise). |
@@ -145,20 +145,39 @@ The omp extension injects the production `Deps`; tests inject fakes.
 6. **Hysteresis.** `no-current` → adopt; ineligible current → `adopted`; best
    beats current by `switchMargin` → `switched`; inside the margin but
    `cheaperInsideMargin` → `switched-cost`; else `kept-margin` / `kept-eligible`.
-7. **Suffix.** Append `roles.<role>.thinking` only when the chosen catalog row's
+7. **Route pin (auto-pin).** With the `providerPinning` capability on and no
+   manual `providerPin`, the chosen model's `rankedRoutes` order is walked and
+   each candidate is probed with `probeRoute` (a one-token completion bound to
+   the slug; optional seam `deps.probeRoute?`, DI like `probeModel`); the first
+   route that is not `blocked` becomes the `@<slug>` pin. `unknown` counts as
+   usable; a model whose every candidate is rejected (or whose probe budget ran
+   out) drops the pin — the selector stays bare and `Decision.pinDropped` is set.
+   Verdicts are cached per run by `catalogId@slug`; the walk spends at most
+   `ROUTE_PROBE_BUDGET = 12` new probes per role. It never runs for a manual pin,
+   a locked or disabled role, a non-OpenRouter selector or a model with no
+   candidate route. Contract:
+   [`writes-and-state.md`](writes-and-state.md), *The provider-pin
+   auto-configuration*.
+8. **Suffix.** Append `roles.<role>.thinking` only when the chosen catalog row's
    `thinking[]` includes the level (meta levels `off`/`auto` need only a
    non-empty list).
-8. **Chains.** For every managed role, `chainUpserts` (bare key → next
-   `fallbackChainDepth` probe-clean candidates, suffixed per target) and
-   `chainPrunes` (plugin-written keys no longer referenced). A key claimed by
-   more than one role stays level-free.
-9. **Config patch.** `writePatch` acquires the refresh lock, reads `config.yml`,
-   `patchConfig` (surgical, self-checked), `writeConfigAtomic` (mtime-guarded
-   tmp+rename, 3 conflict retries). Zero changes → no write, no mtime change.
-10. **State + history.** `saveState` (day gate, managed roles, last selectors,
+9. **Chains.** For every managed role, `chainUpserts` (bare key → the next
+   `fallbackChainDepth` fallback models drawn from the role's ranked candidate
+   list below the chosen model — the cheaper-or-equal candidates that retain at
+   least `fallbackQualityFloor` of its `q` first, then the pricier ones, each
+   bucket in value order, truncated to the depth — suffixed per target) and
+   `chainPrunes` (plugin-written keys no longer referenced). The list is the
+   ranked candidate list minus the key-blocked and probe-`blocked` candidates; an
+   unprobed candidate stays eligible, so the chain can reach a cheaper-or-equal
+   model below the probe window (writes-and-state.md, *Which models are
+   chained*). A key claimed by more than one role stays level-free.
+10. **Config patch.** `writePatch` acquires the refresh lock, reads `config.yml`,
+    `patchConfig` (surgical, self-checked), `writeConfigAtomic` (mtime-guarded
+    tmp+rename, 3 conflict retries). Zero changes → no write, no mtime change.
+11. **State + history.** `saveState` (day gate, managed roles, last selectors,
     plugin-written chain keys, managed `task.disabledAgents` names, previous
     `modelRoles` snapshot) and `appendHistory` (one row per completed run).
-11. **Live-session coupling.** When `default` actually changed and
+12. **Live-session coupling.** When `default` actually changed and
     `activateDefaultOnEmptySession` is set, `deps.applySessionModel?.(selector,
     previous)` hands the new selector to the host (extension only).
 
@@ -221,6 +240,7 @@ type Deps = {
   getSettings?(): Promise<Record<string, unknown>>;
   getKeyMeta?(token: string): Promise<KeyMeta>;
   probeModel?(token: string, catalogId: string): Promise<ProbeVerdict>;
+  probeRoute?(token: string, catalogId: string, providerSlug: string): Promise<ProbeVerdict>;
   getAllowedProviders?(token: string, modelId: string): Promise<Set<string> | null>;
   // Host coupling (extension only): apply a concrete selector to the live session model.
   applySessionModel?(selector: string, previous: string | null): Promise<void>;

package/docs/dev/current-state.md

@@ -1,4 +1,4 @@
-# Current state (2026-10-18)
+# Current state (2026-10-19)
 
 Dated snapshot of the ranking and the landed work as of the date in the heading —
 matched/priced/eligible counts, per-role leaders, the open defects, and the
@@ -6,12 +6,77 @@ per-issue work log below. It is refreshed by
 regenerating the report (`node src/cli/llm-role-rank.ts --out docs/llm-role-rankings.md`) and
 copying the new numbers here; release prose belongs in
 [`../../CHANGELOG.md`](../../CHANGELOG.md), not in this file. The model-level
-ranking numbers below are the 2026-10-18 measurement (the input-price blend basis
-#21, the #17/#18/#19/#20 wave, the #34–#40 focus-axis/capability-flag work, and
+ranking numbers below are the 2026-10-19 measurement (regenerated at the 1.3.0
+cut; byte-identical to the 2026-10-18 one apart from the report's date line —
+the input-price blend basis #21, the #17/#18/#19/#20 wave, the #34–#40
+focus-axis/capability-flag work, and
 spec #81's explorer surfaces — the ranking CLI itself is unchanged); the
 provider-pin numbers are the 2026-10-11 measurement (spec #71; see the top
 bullet). Neither is re-derived on read.
 
+- Fallback chain quality floor (2026-10-19, spec #95): a role's fallback chain no
+  longer only reorders the probe window — that window is `1 + fallbackChainDepth`
+  models, the same size as the chain, so the reorder could never reach a cheaper
+  model at rank 4 or deeper. The chain's fallback **models** now come from the
+  role's whole ranked candidate list below the chosen model: the
+  **cheaper-or-equal** ones first — a candidate qualifies only if it retains at
+  least `fallbackQualityFloor` (a new setting, default `0.9`; `0` disables the
+  floor, `1` requires an exact quality match) of the chosen model's own `q`, so a
+  failover never silently drops the role onto a much weaker model — then the
+  pricier ones, each bucket in value order, truncated to `fallbackChainDepth`.
+  Key-blocked and probe-`blocked` candidates are excluded; an **unprobed**
+  candidate stays eligible, so the chain can reach a cheaper-or-equal model ranked
+  below the probe window (chain entries are never probe-verified — spec #90). A
+  candidate priced exactly at the chosen model's price whose `q` is below the
+  floor lands in neither bucket and is dropped. The floor gates **chain
+  membership only**: the primary choice, the hysteresis decision, the ranking, the
+  probe walk's stop condition and budget, the chain key, the route expansion, the
+  thinking levels and the prune-on-pin-change are all unchanged, as are the
+  manual-`providerPin` and no-pin paths. Measured on the 2026-10-19 caches with
+  the live resolved defs (`fallbackQualityFloor` 0.9, depth 2): `slow`, `vision`
+  and `task` gain cheaper fallbacks, the other seven roles are byte-identical, and
+  no role is degraded. That is the **per-role** effect: in the written config only
+  the `vision` key changes, because `deepseek-v4.1-flash@coreweave/fp8` is claimed
+  by seven roles and carries the last claimer's chain (the shared-key behaviour
+  spec #95 leaves out of scope). The ranking numbers are unchanged — the chain is a
+  write-side shape, not a ranking input — so `docs/llm-role-rankings.md` is not
+  regenerated and the dated numbers below stand as written; the suite grew
+  652 → 666.
+
+- Routability-verified auto-pin (2026-10-19, spec #90): the `providerPinning`
+  auto-pin no longer writes the score-max route blind. The daily update walks the
+  chosen model's `vfm` route order and probes each candidate with a one-token
+  completion bound to it (`provider: { only: [slug] }`), because OpenRouter's
+  endpoints API can list a route as healthy — non-degraded, a full
+  `supported_parameters` list, 100 % uptime — while its routing table excludes it:
+  the live config's `deepseek/deepseek-v4.1-flash@relace` passed every gate and
+  then 404'd on every request, including every fallback revert. Only the narrow
+  no-allowed-providers 404 skips a route; a timeout, a 5xx, a 429 and a 404 with
+  any other body are `unknown` and count as usable, so a transient blip never
+  unpins a role. Verdicts are cached per run by `catalogId@slug`, and the walk is
+  capped at `ROUTE_PROBE_BUDGET = 12` probes per role. When no candidate is
+  routable the pin is **dropped** — the selector stays bare and OpenRouter routes
+  the request itself — and the run notes name the rejected slugs
+  (`; route-blocked: …`), plus the dropped pin (`; pin dropped (no routable
+  route)`) when none survived. The fallback chain keeps its shape
+  (the primary contributes every gate-passing route except the pinned **slug** —
+  see the chain bullet below), and **chain entries are not probed**: one
+  unroutable entry is survivable, omp fails over. A manual
+  `roles.<role>.providerPin` stays a hard gate: never probed, never replaced. The
+  explorer's auto-pin line now reads as a **candidate** — the first route the walk
+  tries, not a promise of the written pin. The ranking numbers are unchanged — the
+  probe is a write-side gate, not a ranking input, and neither the ranking CLI nor
+  `docs/llm-role-rankings.md` changed; the suite grew 631 → 652.
+
+- Release 1.3.0 (2026-10-19, cut `55416d4`, tag `v1.3.0`): the spec #81 explorer
+  surfaces ship. The report was regenerated at the cut and is **unchanged** from
+  the 2026-10-18 measurement — matched 149/408, priced 148, eligible 140
+  (vision 73, designer 87), the same ten leaders — so the numbers below stand as
+  written. The cut also carried the #89 fix: the pre-commit hook and
+  `tests/ci.test.ts` now scrub `GIT_*` from every child process, so the suite's
+  temp-repo git calls can no longer target the real repository (suite 630 →
+  631).
+
 - Explorer as-written pool, per-task price, and price levers (2026-10-18, spec
   #81): the explorer gains a **pool toggle** (raw vs as-written), a **per-task
   price column**, and two **price-lever readouts**. The as-written pool applies
@@ -66,15 +131,21 @@ bullet). Neither is re-derived on read.
 
 - Auto-pin chain expansion (2026-10-10, issue #69): with `providerPinning` on,
   the fallback chain no longer stops at three providers per model — the primary
-  model contributes every gate-passing route except the pinned best, then each
-  `fallbackChainDepth` fallback model contributes every gate-passing route, in
-  score order (the `vfm` route score — spec #71 replaced the original
-  route-value order) and deduped by provider slug, so a down provider fails over
-  to another provider of the same model before the chain switches models. Chain
-  length is data-driven (`(R_primary − 1) + Σ R_fallback`) instead of the fixed
+  model contributes every gate-passing route **except the pinned route** (the
+  exclusion is by pinned slug, not by position: spec #90's probe can pin a route
+  other than the score leader, so the leader rides as a chain entry, and a dropped
+  pin excludes nothing), then each `fallbackChainDepth` fallback model contributes
+  every gate-passing route, in score order (the `vfm` route score — spec #71
+  replaced the original route-value order) and deduped by provider slug, so a down
+  provider fails over to another provider of the same model before the chain
+  switches models. Chain length is data-driven (`(R_primary − 1) + Σ R_fallback`,
+  or `R_primary + Σ R_fallback` with a dropped pin) instead of the fixed
   `2 + 3·fallbackChainDepth`; the manual-`providerPin` and no-pin paths are
-  unchanged. The ranking numbers are unchanged — the chain is a write-side
-  shape, not a ranking input.
+  unchanged. Which `fallbackChainDepth` **models** each chain falls back to was
+  the probe window until spec #95, which draws them from the role's ranked
+  candidate list below the chosen model with the quality floor (see the top
+  bullet) — the route expansion above is unchanged. The ranking numbers are
+  unchanged — the chain is a write-side shape, not a ranking input.
 - Opt-in error reporting (2026-10-08, issue #48): a new `errorReporting` setting
   (`off` — the default — `ask`, `auto`) turns a genuinely unexpected failure — a
   command handler throwing, or a `runUpdater` abort whose `RunResult.defect` is

package/docs/dev/explorer.md

@@ -191,10 +191,14 @@ Pure, no I/O; all ranking math is delegated to `src/engine.ts`.
   per-metric raw target that would close the gap, via `inverseCardinal`, with
   unreachable/extrapolated notes), `dominators` (models both cheaper and at
   least as good on `q`, top 3), `ownProvider` (true when the model was priced on
-  the soft best route rather than the blend), `autoPin` (the provider slug the
-  updater would write — `bestRoute(model, def)?.providerSlug`, the max-`vfm`
+  the soft best route rather than the blend), `autoPin` (the **candidate** route's
+  provider slug — `bestRoute(model, def)?.providerSlug`, the max-`vfm`
   route (scoring.md, *Route ordering*), when the role sets
-  `preferOwnProvider` and carries no manual `providerPin`, else `null`), and the
+  `preferOwnProvider` and carries no manual `providerPin`, else `null` — the
+  first route the updater's daily walk tries, **not** a promise of the written
+  pin: the updater probes it and skips to the next route when OpenRouter does not
+  serve it, or drops the pin entirely when none is routable; writes-and-state.md,
+  *The provider-pin auto-configuration*), and the
   availability overlay `key`/`keyReason`
   (the same verdict as `rankRows`, plus the reason it reads that way). It mirrors
   `rankRole`'s capability fill so the contributions sum exactly to `q`.
@@ -369,8 +373,20 @@ a scraped third-party site, so the DOM is built with
   line). The cost line appends `· best route`
   when the model was priced on the soft best route (`ownProvider`), and a
   **pin line** shows the pin in force: `pin: <slug> (manual)` when the edited def
-  carries a `providerPin`, else `auto pin: <slug>` from the explanation's
-  `autoPin` (read-only — the manual field is the only way to set one). The
+  carries a `providerPin`, else `auto pin (candidate): <slug>` from the
+  explanation's `autoPin` (read-only — the manual field is the only way to set
+  one). The label says *candidate* on purpose: the value is the first route the
+  updater's value-ordered walk *tries*, not a promise of the written pin — the
+  updater probes that route and skips to the next when OpenRouter does not serve
+  it, or drops the pin entirely (bare selector) when none is routable, so the
+  written pin can be a later route or absent altogether (spec #90;
+  writes-and-state.md, *The provider-pin auto-configuration*). The explorer is
+  read-only and offline and cannot probe, so it names the candidate and says so
+  in the tooltip. The candidate equals the written pin when every route probes
+  clean; with the account's allowed-providers whitelist active, the panel and the
+  written pin agree only on the **as-written** pool, which applies the same prune
+  the updater applies before walking (in the raw pool the panel can name a route
+  the prune removes). The
   per-task line shows the breakdown (`<in> in × $<p_in>/M + <out> out ×
   $<p_out>/M × <factor> = $<total>`), or `— (no token profile — record usage or
   set tokenProfile)` when `perTask` is `null`. The **Price levers** section

package/docs/dev/releasing.md

@@ -122,6 +122,39 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
   push publishes to npm over OIDC and creates the GitHub Release. The guard was
   verified with a negative control — tag `v0.0.1` against version `1.1.0` failed
   in `notes` before any publish.
+- **1.3.0 published by CD 2026-10-19** (run 39222193609, tag push): the guard
+  and the npm floor passed, `npm publish` completed over OIDC trusted publishing
+  with a provenance attestation (`npm audit signatures`: 1 package has a
+  verified attestation), and the GitHub Release was created with the 1.3.0
+  CHANGELOG section as its body
+  (`https://github.com/Gott50/omp-llm-role/releases/tag/v1.3.0`). Verified:
+  `dist-tags.latest` = `1.3.0`, npm's `gitHead` = `55416d4` (the tag's commit),
+  and the publish step's log carries the direct-publish signature (`Publishing
+  to https://registry.npmjs.org/ with tag latest and default access`, `Signed
+  provenance statement`, `+ omp-llm-role@1.3.0`). The cut (`55416d4`, tagged
+  `v1.3.0`) bumped the four lockstep fields, renamed `## [Unreleased]` to
+  `## [1.3.0] - 2026-10-19`, and regenerated the report (408 models, matched
+  149/408, priced 148 — byte-identical to the 2026-10-18 report apart from its
+  date line; `docs/dev/current-state.md` refreshed to the same measurement).
+  The cut also carried the #89 fix (the `GIT_*` scrub in the pre-commit hook and
+  `tests/ci.test.ts`), so the release commit went through the hook with the real
+  repository untouched.
+- **1.3.0 install routes smoke-tested** (2026-10-19, omp 18.12.2, throwaway
+  `HOME`s, cwd outside the real home tree): npm
+  (`omp plugin install omp-llm-role`), git
+  (`omp plugin install github:Gott50/omp-llm-role`) and marketplace
+  (`omp plugin marketplace add Gott50/omp-llm-role` +
+  `omp plugin install omp-llm-role@gott50-plugins`) each installed 1.3.0
+  (`omp plugin doctor`: 4 ok / 0 warnings / 0 errors for npm and git; the
+  marketplace install's one warning is the expected
+  `package_manifest: Not created yet`, and it landed at
+  `…/cache/plugins/gott50-plugins___omp-llm-role___1.3.0`). Each post-install
+  session run (`omp -p "say ok"` with `OPENROUTER_API_KEY` from
+  `omp token openrouter`) wrote `modelRoles` (9 roles),
+  `retry.fallbackChains` and `task.disabledAgents: [designer]` into that HOME's
+  `config.yml`, landed `llm-role-state.json` + `llm-role-history.jsonl` +
+  `llm-role-usage.jsonl` (the spec #81 ledger, live for the first time), and
+  answered.
 - **1.2.0 published by CD 2026-10-12** (run 38299141569, tag push): the guard
   and the npm floor passed, `npm publish` completed over OIDC trusted publishing
   with a provenance attestation (`npm audit signatures`: 1 package has a
@@ -200,7 +233,7 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
 - **Stray registry placeholder.** The registry also carries a `0.0.0-stage`
   version ("Temporary package placeholder for staged publishing", 334 B,
   published 2026-10-03). It is not from this tree and does not affect installs
-  (`latest` is `1.2.0`).
-- **Next release: none owed.** `## [Unreleased]` is empty — the 1.2.0 cut moved
-  its entries under `## [1.2.0] - 2026-10-12`; the number comes from the
+  (`latest` is `1.3.0`).
+- **Next release: none owed.** `## [Unreleased]` is empty — the 1.3.0 cut moved
+  its entries under `## [1.3.0] - 2026-10-19`; the number comes from the
   Unreleased scope, not from the open issues.

package/docs/dev/scoring.md

@@ -152,9 +152,22 @@ while every other weighted metric stays the model's own.
 ### Route ordering (the value-for-money score)
 
 `rankedRoutes(model, def)` (`src/engine.ts`) is the one function that orders a
-model's candidate routes; `bestRoute` is `rankedRoutes[0]`, and `roleRoute` (the
-route `rankRole` prices the model on) and the updater's auto-pin both read it, so
-the priced route, the written pin and the fallback chain move together.
+model's candidate routes; `bestRoute` is `rankedRoutes[0]`, and both `roleRoute`
+(the route `rankRole` prices the model on) and the updater's auto-pin read that
+one order. The priced route is the score-max candidate; the **written pin is the
+first route in that order the route probe does not reject** (writes-and-state.md,
+*The provider-pin auto-configuration*), so the two can differ — the probe is a
+routability check on the write side only and never feeds the ranking. The
+fallback chain follows the pin: it excludes the route the pin names (by slug, not
+by position) and, with a dropped pin, excludes none. Which **models** the chain
+falls back to is a separate choice (spec #95): its `fallbackChainDepth` fallback
+models come from the role's **ranked candidate list** below the chosen model —
+the cheaper-or-equal candidates that retain at least `fallbackQualityFloor` of
+its `q` first, then the pricier ones, each bucket in value order, truncated to
+the depth — **not** from the probe window, so the chain can reach a
+cheaper-or-equal model ranked below the `1 + fallbackChainDepth` window the walk
+probes (key-blocked and probe-`blocked` candidates are excluded; unprobed ones
+stay eligible — writes-and-state.md, *The provider-pin auto-configuration*).
 
 - **Candidates.** A route is a candidate when it is non-degraded (`status === 0`),
   passes `routePassesEndpointFilters(route, def.filters)`, carries a usable billed
@@ -283,7 +296,11 @@ on the 2026-10-11 cache):
   routes that pass the role's endpoint filters and the account's
   allowed-providers whitelist (see *Whitelist-aware route selection*) — falling
   back to
-  the default `1/price²` blend only when the model has no candidate route. It is
+  the default `1/price²` blend only when the model has no candidate route. The
+  **written** pin is the first route in that same order the route probe does not
+  reject (spec #90; writes-and-state.md, *The provider-pin auto-configuration*) —
+  the probe is a routability gate on the write side, so the priced (score-max)
+  route and the written pin can differ. It is
   a **per-model policy, not a scalar** — the sensible pin differs per model, so
   the bundle carries a policy field evaluated against the model's own routes at
   rank time, not a slug baked into the lock file. `bestRoute` (`src/engine.ts`)

package/docs/dev/testing.md

@@ -34,17 +34,38 @@ passing.
    best; cost override (`switched-cost`); `priceSwitchFraction: 0` keeps the
    margin in charge; an inside-margin challenger short of the fraction stays
    kept; the day gate.
-6. **Chain pruning** (`chain-pruning.test.ts`) — plugin-written stale keys
-   removed; owner-written keys preserved; `writeFallbackChains: false`; a role
-   that left the managed set is pruned; the chain prefers candidates at or below
-   the chosen price.
+6. **Chain pruning + the quality floor** (`chain-pruning.test.ts`,
+   `chain-quality-floor.test.ts`) — plugin-written stale keys removed;
+   owner-written keys preserved; `writeFallbackChains: false`; a role that left
+   the managed set is pruned; the chain prefers candidates at or below the chosen
+   price. The floor (spec #95): a cheaper rank-4 candidate that clears the floor
+   becomes the first fallback where the pricier rank 2/3 do not, even though the
+   probe walk never reaches it; a cheap primary whose cheaper-or-equal candidates
+   are all below the floor keeps the next-best-by-value models;
+   `fallbackQualityFloor: 0` admits any cheaper-or-equal candidate and `1` only an
+   exactly-equal-quality one; an equal-priced sub-floor candidate is in neither
+   bucket and is dropped; a key-blocked cheaper candidate never enters the chain;
+   the chain stops at `fallbackChainDepth` in the cheaper set's value order; the
+   manual-pin path and the auto-pin chain shape are unchanged; an out-of-range
+   floor is a settings error that writes nothing; and a `kept-margin` role's chain
+   is built from the kept model's `q` and the candidates below it, with the
+   selector and the decision reason unaffected.
 7. **Chain suffixes** (`chain-suffix.test.ts`) — chain values carry the role's
    suffix, the key stays bare; an entry without thinking support gets no suffix;
    two roles on one model share a level-free chain.
 8. **Probe gate** (`probe-gate.test.ts`) — 200 → ok; the no-allowed-providers 404
    → blocked; any other failure → usable; blocked best → next adopted; blocked
-   current → replaced; chains contain only probe-clean candidates; verdicts
-   cached across roles; all-blocked → role untouched.
+   current → replaced; a probe-`blocked` candidate never enters a chain
+   (`fallback chains contain only probe-clean candidates`); verdicts cached across
+   roles; all-blocked → role untouched with a note. Spec #95 changed what the
+   chain's model set is built from: "blocked candidates beyond a kept current do
+   not count toward chain depth" was **deleted** (it encoded the removed
+   probe-window membership rule), "walk fills a kept role's chain to full depth
+   with probe-clean entries" was **renamed** to "a kept role's chain is filled to
+   full depth from the candidates below the kept model", and a new "the chain
+   reaches a cheaper candidate the walk never probes" pins that an **unprobed**
+   cheap candidate is chained while the walk still stops at
+   `1 + fallbackChainDepth` clean candidates.
 9. **Keyed catalog** (`keyed-catalog.test.ts`) — key-blocked candidates pruned
    from the walk; only candidates in neither catalog are probed; key-blocked
    never in a chain; no-filter/unavailable degrade to the probe walk.
@@ -78,7 +99,8 @@ passing.
     floor sorts a below-floor route last **without dropping it**; a route with no
     p50 uses the model's blended throughput (for both the score and the floor
     check); equal scores break by `providerSlug` then `id`; `explainModel`'s
-    `autoPin` is the score-max route.
+    `autoPin` is the score-max route — the auto-pin's first **candidate**, which
+    the updater probes before writing it (spec #90).
 14. **Thinking price** (`thinking-price.test.ts`) — bare/off unadjusted; a level
     scales only thinking-capable models; the frontier uses the effective price;
     `resolveSettings` validates thinking and rejects the legacy `suffixes` map;
@@ -149,6 +171,10 @@ passing.
     `POST /api/pool` toggle returns the gated/pruned dataset in `as-written` mode
     and the full one in `raw`; the bootstrap payload carries `poolMode` and
     `tokenProfile`; the explain response carries `leaderFlip`/`thinkingLevels`.
+    The auto-pin indicator (spec #90): `explainModel`'s `autoPin` is the route the
+    updater's walk pins when every route probes clean, and it deliberately differs
+    from the written pin when the walk skips a blocked leader — the panel names
+    the *candidate*.
 24. **Project scope** (`project-updater.test.ts`, `project-setup.test.ts`,
     `project-roles-command.test.ts`) — project mode scopes config/state/history/
     lock to `<cwd>/.omp`; the day gate is per scope; the registry write;
@@ -208,13 +234,30 @@ passing.
     and `cut` bumping the four fields, cutting the changelog, committing and
     tagging while refusing a dirty tree, an existing tag, an empty
     `## [Unreleased]` and a HEAD that is not `origin/main`.
-31. **Auto-pin** (`auto-pin.test.ts`) — the selector gains the best route's
-    `@<slug>`; the chain carries every gate-passing route of the primary (all but
-    the pinned best) then of each fallback model, in score order (the `vfm` route
+31. **Auto-pin** (`auto-pin.test.ts`) — the selector gains the `@<slug>` of the
+    first route in the role's `vfm` order that the route probe does not reject
+    (spec #90): a `blocked` leader pins the next route and records the skipped
+    slug (`routeBlockedSlugs`); `unknown` is usable and stays pinned; every route
+    blocked writes a bare selector and sets `pinDropped`; the notify lines carry
+    `; route-blocked: …` and `; pin dropped (no routable route)`; an all-blocked
+    pool issues at most `ROUTE_PROBE_BUDGET` probes; a verdict cached for one role
+    is reused by another; two blocked routes sharing a provider slug are recorded
+    once; and the capability off, a manual pin, a locked role, a disabled role and
+    a model with no gate-passing route never consult the probe (a throwing stub
+    proves it) and leave the config byte-identical. The chain carries every
+    gate-passing route of the primary except the pinned **slug** (not the pinned
+    position) then of each fallback model, in score order (the `vfm` route
     score desc, spec #71), deduped by
     provider slug; a degraded / over-`maxPriceUsdPerM` / endpoint-filter-failing /
-    whitelist-blocked route is excluded; the manual pin wins and the no-pin path
-    is bare; a re-run is idempotent and a pin change prunes the old key.
+    whitelist-blocked route is excluded; the manual pin wins (its chain is the
+    fallback models only, every value carrying the manual slug) and the no-pin
+    path is bare (fallback models only); a re-run is idempotent and a pin change
+    prunes the old key. Since spec #95 the chain's fallback **models** come from
+    the ranked candidate list below the chosen model with the quality floor
+    (item 6) rather than the probe window, so the fixtures price each route at its
+    model's own price plus its position — routes all priced `1..n` would collapse
+    every model to one effective price and the floor would drop the weaker
+    fallbacks at equal price.
 32. **Provider display** (`provider-display.test.ts`,
     `provider-display-wiring.test.ts`) — `providerPinOf` reads the single
     `openRouterRouting.only[0]` (else `vercelGatewayRouting`), preferring
@@ -253,6 +296,13 @@ passing.
     catalog/tier gate (`resolveVariant`) and the allowed-providers prune
     (`providerAllowed`), leaves the routes untouched on a `null` whitelist,
     yields an empty pool on `tier: "none"`, and never mutates its input.
+36. **Route probe** (`route-probe.test.ts`) — `probeRoute` sends the exact
+    one-token completion shape (POST, bearer, `max_tokens: 1`, `provider: { only:
+    [slug] }`): 200 → `ok`; the no-allowed-providers 404 → `blocked`; a 404 with
+    any other body, a 5xx, a 429 and a transport throw → `unknown` (usable). The
+    walk that consumes it (skip a `blocked` route, accept `unknown`, drop the pin
+    when nothing is clean, the per-role budget, the cross-role verdict cache) is
+    covered by the auto-pin cases above.
 
 ## Live checks
 

package/docs/dev/writes-and-state.md

@@ -145,41 +145,128 @@ feeds the ranking, the reported `$/M` price, or any write. The recorded usage
 takes precedence over it (`resolveTokenProfile`), so once a role has ledger rows
 the setting is ignored for that role.
 
-## The provider-pin auto-configuration (spec #58)
+## The provider-pin auto-configuration (spec #58, routability-verified by #90)
 
 When a role's **expanded** def sets `preferOwnProvider: true` (the
 `providerPinning` capability's recommended bundle) and carries **no** manual
-`providerPin`, the updater binds the role's requests to the chosen model's best
-route by writing that route's provider slug as the selector's `@<slug>` suffix:
+`providerPin`, the updater binds the role's requests to one provider route by
+writing that route's slug as the selector's `@<slug>` suffix:
 
 ```
 openrouter/<id>@<slug>:<level>
 ```
 
 omp's `splitUpstreamRouting` parses the trailing `@<slug>` and applies
-`compat.openRouterRouting = { only: [slug] }`, so the price the ranking assumed
-is the price the request pays. The slug is `bestRoute(chosenModel, def)`'s
-`providerSlug` — the max-value-for-money candidate route (see scoring.md,
-*Route ordering*). The pin is re-derived on every run, so it follows the ranking when the
-chosen model changes. A manual `roles.<role>.providerPin` **wins** over the
-automatic choice and stays a **hard** gate (a model with no matching route is
-ineligible); clearing it resumes the automatic choice.
+`compat.openRouterRouting = { only: [slug] }`. The pin is the best route **the
+probe accepts**, which is the route the role was priced on — the route the walk
+tries first — so the price the ranking assumed is the price the request pays
+*only while the walk does not skip that candidate*; a skipped candidate means the
+route that replaced it pays, at its own price. The pin is re-derived on every
+run, so it follows the ranking when the chosen model changes.
+
+**The walk — the pin is probed before it is written.** The slug is **not** the
+score-max route unconditionally: the updater walks the role's route order
+(`rankedRoutes(chosenModel, def)` — the `vfm` order the chain also uses; see
+scoring.md, *Route ordering*) and probes each candidate with `probeRoute`: a
+one-token completion carrying `provider: { only: [slug] }`, the same request
+skeleton and the same narrow no-allowed-providers pattern as `probeModel`. The
+verdict vocabulary is `probeModel`'s:
+
+- `blocked` — the narrow no-allowed-providers 404 — skips the route and the walk
+  continues to the next candidate;
+- `ok` and **`unknown` are both usable**. A non-404 status (a 429, a 5xx), a 404
+  whose body does not carry the pattern, and a transport throw (a timeout, a
+  connection reset) are all `unknown`: a transient blip must never silently unpin
+  a role, and a rate limit is omp's runtime-fallback domain, not this plugin's.
+
+Verdicts are cached per run by `catalogId@slug`, so a route shared by several
+roles is probed once, and the walk is capped per role at **`ROUTE_PROBE_BUDGET =
+12`** *new* probes (cached verdicts are free) — a pathological pool must not turn
+the daily update into a long probe walk.
+
+**Why a real request.** OpenRouter's endpoints API and its routing table
+disagree: an endpoint can list `status: 0` with a full `supported_parameters`
+list and 100 % uptime, pass the whitelist gate and carry a usable billed price,
+and still 404 for `provider.only` — and the exclusion is dynamic (the same
+request can succeed minutes later). The routing table is visible only in the 404
+body of a request that failed, so a request is the only reliable signal. This is
+exactly the failure the endpoint gates cannot see (spec #90: the live config held
+`deepseek/deepseek-v4.1-flash@relace`, which 404'd on every revert).
+
+**No routable candidate → no pin.** If every candidate is `blocked` (or the
+budget runs out with no clean candidate), no pin is written: the selector stays
+**bare** and OpenRouter routes the request itself, instead of omp failing on an
+unroutable `@<slug>`. `Decision.pinDropped` is true in that case (see *State,
+history, lock*), and the run notes it.
+
+A manual `roles.<role>.providerPin` **wins** over the automatic choice and stays
+a **hard** gate (a model with no matching route is ineligible). It is **never
+probed and never replaced** — the probe applies only to the route the capability
+itself chooses; clearing the manual pin resumes the automatic choice.
 
 **Chain shape.** The primary's chain key is the selector minus the trailing
-`:level` — so it **includes** the pin (`openrouter/<id>@<slug>`). Its values, in
-order:
+`:level` — so it **includes** the pin (`openrouter/<id>@<slug>`, or the bare
+`openrouter/<id>` when the pin was dropped). Its values, in order:
 
-1. the same model on **every** gate-passing route except the pinned best, in
+1. the same model on **every** gate-passing route except the pinned route, in
    score order (the `vfm` route score desc — see scoring.md, *Route ordering*),
 2. then, for each of the `fallbackChainDepth` fallback models, that model on
    **every** gate-passing route, in score order.
 
-Length = `(R_primary − 1) + Σ R_fallback`, where `R` is the number of distinct
-gate-passing provider slugs for that model — data-driven, not a fixed cap.
-Entries dedup by chain value, so two routes sharing a provider slug collapse to
-one. Every entry carries the same `@<slug>` suffix (and the role's thinking level
-where the target advertises it). A model with no gate-passing route contributes
-nothing. The gates are the engine's `rankedRoutes` set: non-degraded
+**Which models are chained (spec #95).** The `fallbackChainDepth` fallback
+**models** come from the role's whole **ranked candidate list** — the
+tier-eligible ranking rows, in value order — not from the probe window (which is
+`1 + fallbackChainDepth` models, the same size as the chain, so a reorder of it
+can never reach a cheaper model at rank 4 or deeper). Two classes of candidate
+are excluded, with the same predicates the probe walk uses: **key-blocked**
+models (the account's key cannot use them) and models whose probe verdict is
+`blocked`. An **unprobed** candidate stays — the chain's deeper entries are
+never probe-verified (they are not a new class: chain entries are already
+route-level unprobed, and omp fails over on an unroutable entry). `after` is
+that list **below the chosen model** — the leader on a fresh pick, the kept
+current candidate on a kept role (`kept-eligible` / `kept-margin`) — so the
+`after` set and the floor both key off the model the selector actually names —
+the previous `pool.slice(chosenIdx + 1)` keyed off the same index in the
+probe-clean pool — and candidates ranked above the chosen are never chained. The
+set is then split:
+
+```
+cheaper = after where priceEff <= chosen.priceEff AND q >= chosen.q · fallbackQualityFloor
+pricier = after where priceEff > chosen.priceEff            (never floor-filtered)
+chain   = [...cheaper, ...pricier].slice(0, fallbackChainDepth)
+```
+
+so a cheaper-or-equal fallback keeps the role's quality (the floor is a fraction
+of the chosen model's **own** `q`, so it reads the same on every role's quality
+scale) and a cheap-but-weak candidate set cannot starve the chain (the pricier
+bucket always fills any remaining depth with the next-best by value). Both
+buckets keep value order, so a cheaper candidate deep in the ranking is reached
+only when fewer than `fallbackChainDepth` cheaper-or-equal candidates clear the
+floor — a bounded search, not a cheapest-first sort. A candidate priced exactly
+at the chosen model's price whose `q` is below the floor is in **neither** bucket
+and drops out. `fallbackQualityFloor` (a number in `[0, 1]`, default `0.9`; `0`
+disables the floor, `1` requires an exact quality match — validated, never
+silently clamped) is documented in the README's settings table. The floor gates
+**chain membership only**: the primary choice, the hysteresis decision, the
+ranking, the probe walk's stop condition and budget, the chain key, the route
+expansion, the thinking levels, the dedup and the prune-on-pin-change are all
+unchanged.
+
+The exclusion is **by pinned slug, not by position**: the probe can pin a route
+other than the score leader (so the leader rides as a fallback entry while the
+pinned route does not), and with a **dropped pin** (the auto-pin applied, but no
+candidate was routable) **no** route is excluded — the primary contributes every
+gate-passing route. Length = `(R_primary − 1) + Σ R_fallback`, or `R_primary + Σ
+R_fallback` with a dropped pin, where `R` is the number of distinct gate-passing
+provider slugs for that model — data-driven, not a fixed cap. Entries dedup by
+chain value, so two routes sharing a provider slug collapse to one. Every entry
+carries the same `@<slug>` suffix (and the role's thinking level where the target
+advertises it).
+**Chain entries are not probed** — only the primary pin is: the chain carries
+many routes and one unroutable entry is survivable (omp fails over), so probing
+it would multiply the request cost for no benefit (out of scope, spec #90). A
+model with no gate-passing route contributes nothing. The gates are the engine's
+`rankedRoutes` set: non-degraded
 (`status === 0`), the endpoint capability filters (`tools` / `minContextTokens` /
 `minOutputTokens`), a usable billed price, and the `maxPriceUsdPerM` cap
 (thinking-adjusted). The soft `filters.preferredMinThroughput` floor is a
@@ -190,16 +277,28 @@ pool to allowed providers before ranking, which is what makes `rankedRoutes`
 whitelist-aware. The probe walk target is unchanged (`1 + fallbackChainDepth` —
 it counts models, not routes).
 
+**Outside the auto-pin.** The chosen model contributes nothing when the auto-pin
+does not apply: with a manual `providerPin` (`autoPinApplies` is false, so the
+route probe does not run either) or with the capability off, the chain carries
+**one entry per `fallbackChainDepth` fallback model** —
+`openrouter/<fallbackId>@<manualSlug>` with a manual pin, the bare
+`openrouter/<fallbackId>` with none — each with the role's thinking level where
+the target advertises it, and no route of the chosen model at all.
+
 **Prune on a pin change.** Because the chain key includes the pin, a pin change
 changes the key; the updater's chain prune (`state.pluginWrittenChainKeys`) drops
 the old key so a stale pinned chain does not linger.
 
-**No-ops.** The auto-pin writes nothing when: the capability is off
-(`preferOwnProvider` not `true`); a manual `providerPin` is set; the role is
-locked or disabled; the selector is not an OpenRouter selector; the model has no
-route data; no route passes the role's endpoint filters; or the best route has no
-usable billed price. With the capability off the written config is byte-identical
-to before.
+**No-ops.** The auto-pin writes nothing — and **the route probe is never
+consulted** — when: the capability is off (`preferOwnProvider` not `true`); a
+manual `providerPin` is set; the role is locked or disabled; the selector is not
+an OpenRouter selector; the model has no route data; no route passes the role's
+endpoint filters; or no candidate has a usable billed price (the last three leave
+`rankedRoutes` empty, so there is no candidate to probe, and `pinDropped` stays
+false — the pin is simply absent). The case where the model *has* candidates but
+none is routable is different: that is the **dropped pin** above — still no pin,
+but recorded (`pinDropped`). With the capability off the written config is
+byte-identical to before.
 
 ## State, history, lock
 
@@ -294,7 +393,13 @@ settings entry the global behavior is unchanged.
   ids the role's endpoint filters dropped (no capable standard-tier route), rendered
   `; endpoint-blocked: …` on the decision line; `pinBlocked[]` records the ranking ids
   the role's provider pin dropped (no route matching the pin), rendered
-  `; pin-blocked: …`.
+  `; pin-blocked: …`. `routeBlockedSlugs[]` records the provider slugs the auto-pin's
+  route probe rejected on the chosen model, in walk order and deduped by slug
+  (two routes of one model can share a slug), rendered `; route-blocked: …`;
+  `pinDropped` is `true` when the auto-pin applies and the model has gate-passing
+  routes but no candidate survived the probe (or the `ROUTE_PROBE_BUDGET` ran
+  out), rendered `; pin dropped (no routable route)` — the selector is bare in
+  that case. Both are empty/false when no probe ran.
 - Role removal (`/remove-agent`) goes through `removeRoleSettings` in
   `src/role-settings.ts` — the same validate/backup/atomic-write path as
   `writeRoleSettings`, deleting the role's flat dotted keys and any nested entry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-llm-role",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "omp plugin: daily model-role updater driven by llm-stats/OpenRouter rankings",
   "license": "MIT",
@@ -63,6 +63,14 @@
         "min": 0,
         "step": 1
       },
+      "fallbackQualityFloor": {
+        "type": "number",
+        "description": "Quality floor for a cheaper-or-equal fallback: the fraction of the chosen model's quality it must retain (0 disables)",
+        "default": 0.9,
+        "min": 0,
+        "max": 1,
+        "step": 0.001
+      },
       "activateDefaultOnEmptySession": {
         "type": "boolean",
         "description": "Reapply the new default selector to an empty session's active model",

package/src/availability.ts

@@ -89,8 +89,8 @@ export type ProbeVerdict = "ok" | "blocked" | "unknown";
 const OPENROUTER_COMPLETIONS_URL = "https://openrouter.ai/api/v1/chat/completions";
 
 /** POST a one-token completion to OpenRouter with the shared request skeleton
- * (Bearer auth, JSON body, 20s timeout). Shared by `probeModel` and
- * `fetchAllowedProviders`. */
+ * (Bearer auth, JSON body, 20s timeout). Shared by `probeModel`, `probeRoute`
+ * and `fetchAllowedProviders`. */
 function completionRequest(token: string, body: unknown, fetchImpl: typeof fetch): Promise<Response> {
   return fetchImpl(OPENROUTER_COMPLETIONS_URL, {
     method: "POST",
@@ -110,6 +110,20 @@ function errorMessage(body: unknown): string {
  * whitelist (or a data-policy toggle) leaves a model without a runnable endpoint. */
 const BLOCKED_RE = /no allowed providers/i;
 
+/**
+ * The verdict a probe response carries, shared by `probeModel` and `probeRoute`
+ * so the model probe and the route probe cannot drift apart: a 2xx is `ok`, the
+ * narrow no-allowed-providers 404 is `blocked`, and everything else is
+ * `unknown` (usable) — any other status (a 429, a 5xx), a 404 with any other
+ * body, an unparseable body. Never throws.
+ */
+async function verdictOf(res: Response): Promise<ProbeVerdict> {
+  if (res.ok) return "ok";
+  if (res.status !== 404) return "unknown";
+  const body: unknown = await res.json().catch(() => null);
+  return BLOCKED_RE.test(errorMessage(body)) ? "blocked" : "unknown";
+}
+
 /**
  * One-token completion probe: the only reliable signal for
  * account-level provider restrictions — neither `/api/v1/key` nor the catalog
@@ -121,11 +135,30 @@ const BLOCKED_RE = /no allowed providers/i;
 export async function probeModel(token: string, catalogId: string, fetchImpl: typeof fetch = fetch): Promise<ProbeVerdict> {
   try {
     const res = await completionRequest(token, { model: catalogId, messages: [{ role: "user", content: "ok" }], max_tokens: 1 }, fetchImpl);
-    if (res.ok) return "ok";
-    if (res.status !== 404) return "unknown";
-    const body: unknown = await res.json().catch(() => null);
-    const message = errorMessage(body);
-    return BLOCKED_RE.test(message) ? "blocked" : "unknown";
+    return await verdictOf(res);
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * One-token completion bound to a single provider route (`provider.only`), the
+ * same request skeleton as `probeModel` plus the route pin. The endpoints API
+ * and OpenRouter's routing table disagree — an endpoint can list `status: 0`
+ * with 100% uptime and still 404 — so a real request is the only reliable
+ * signal for whether a route is routable. Only the narrow no-allowed-providers
+ * 404 blocks a route; a non-404 status, a 404 with any other body and a
+ * transport throw are all "unknown" and count as usable, exactly as
+ * `probeModel` does. Never throws.
+ */
+export async function probeRoute(token: string, catalogId: string, providerSlug: string, fetchImpl: typeof fetch = fetch): Promise<ProbeVerdict> {
+  try {
+    const res = await completionRequest(
+      token,
+      { model: catalogId, messages: [{ role: "user", content: "ok" }], max_tokens: 1, provider: { only: [providerSlug] } },
+      fetchImpl,
+    );
+    return await verdictOf(res);
   } catch {
     return "unknown";
   }

package/src/explorer/explain.ts

@@ -347,9 +347,11 @@ export type Explanation =
        * `preferOwnProvider` preference, no hard pin) rather than the 1/price²
        * blend — the panel shows WHY the price is what it is. */
       ownProvider: boolean;
-      /** the automatic pin: the model's best route's provider slug when the role
-       * prefers a bound route and carries no manual pin, else null. Read-only in
-       * the UI; a manual `providerPin` overrides it. */
+      /** the automatic pin's candidate: the model's best route's provider slug —
+       * the first route the updater's walk tries — when the role prefers a bound
+       * route and carries no manual pin, else null. The probe can skip to a later
+       * route or drop the pin, so this is the candidate, not the written pin.
+       * Read-only in the UI; a manual `providerPin` overrides it. */
       autoPin: string | null;
       role: { name: string; lambda: number; derivedLambda: number; wPrice: number; qW: number; thinking: SuffixLevel | undefined; cacheHitRate: number };
       contributions: Contribution[];
@@ -389,9 +391,12 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
   const route = roleRoute(model, def);
   // The model is priced on the soft best route (not a hard pin, not the blend).
   const ownProvider = pinRoute === null && route !== null;
-  // The automatic pin the updater would write: the model's best route's slug,
-  // only when the role prefers a bound route and carries no manual pin. Reuses the
-  // already-computed `route` (the same best route) instead of recomputing it.
+  // The automatic pin's CANDIDATE route: the model's best route's slug — the
+  // first route the updater's walk tries — only when the role prefers a bound
+  // route and carries no manual pin. The updater probes that candidate and can
+  // pin a later route (or drop the pin entirely), so this is what the walk tries
+  // first, not a promise of the written pin. Reuses the already-computed `route`
+  // (the same best route) instead of recomputing it.
   const autoPin = autoPinApplies(def) ? route?.providerSlug ?? null : null;
   const missingRequired = def.required.filter((k) => roleMetricValue(eff, k, pinRoute, cacheHitRate) == null);
   if (missingRequired.length > 0) reasons.push(`missing required metric(s): ${missingRequired.join(", ")}`);

package/src/settings.ts

@@ -235,6 +235,13 @@ export type ResolvedSettings = {
   priceSwitchFraction: number;
   writeFallbackChains: boolean;
   fallbackChainDepth: number;
+  /**
+   * Quality floor for the fallback chain's cheaper-or-equal candidates: a
+   * candidate priced at or below the chosen model qualifies only if it retains
+   * at least this fraction of the chosen model's `q`. 0 disables the floor (any
+   * cheaper-or-equal candidate qualifies); 1 requires an exact quality match.
+   */
+  fallbackQualityFloor: number;
   roles: Record<string, RoleDef>;
   activateDefaultOnEmptySession: boolean;
   /** Opt-in reporting of unexpected plugin errors as GitHub issues on the
@@ -255,6 +262,7 @@ export const DEFAULT_SETTINGS: ResolvedSettings = {
   priceSwitchFraction: 0.5,
   writeFallbackChains: true,
   fallbackChainDepth: 2,
+  fallbackQualityFloor: 0.9,
   roles: DEFAULT_ROLES,
   activateDefaultOnEmptySession: true,
   errorReporting: "off",
@@ -306,6 +314,14 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       min: 0,
       step: 1,
     },
+    fallbackQualityFloor: {
+      type: "number",
+      description: "Quality floor for a cheaper-or-equal fallback: the fraction of the chosen model's quality it must retain (0 disables)",
+      default: DEFAULT_SETTINGS.fallbackQualityFloor,
+      min: 0,
+      max: 1,
+      step: 0.001,
+    },
     activateDefaultOnEmptySession: {
       type: "boolean",
       description: "Reapply the new default selector to an empty session's active model",
@@ -579,6 +595,9 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
   if (!Number.isInteger(merged.fallbackChainDepth) || merged.fallbackChainDepth < 0) {
     errors.push(`fallbackChainDepth: must be an integer >= 0, got ${JSON.stringify(merged.fallbackChainDepth)}`);
   }
+  if (typeof merged.fallbackQualityFloor !== "number" || !Number.isFinite(merged.fallbackQualityFloor) || merged.fallbackQualityFloor < 0 || merged.fallbackQualityFloor > 1) {
+    errors.push(`fallbackQualityFloor: must be a number in [0, 1], got ${JSON.stringify(merged.fallbackQualityFloor)}`);
+  }
   if (typeof merged.activateDefaultOnEmptySession !== "boolean") {
     errors.push(
       `${ACTIVATE_DEFAULT_KEY}: must be a boolean, got ${JSON.stringify(merged.activateDefaultOnEmptySession)}`,

package/src/updater.ts

@@ -15,8 +15,8 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { autoPinApplies, bestRoute, computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, rankedRoutes, type Ranked, type RankData, type RoleDef } from "./engine.ts";
-import { currentRankingId, enrichThinkingLevels, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, providerAllowed, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
+import { autoPinApplies, computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, rankedRoutes, type Ranked, type RankData, type RoleDef } from "./engine.ts";
+import { currentRankingId, enrichThinkingLevels, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, probeRoute, providerAllowed, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
 import { ConfigEditError, parseConfig, patchConfig, writeConfigAtomic, type ConfigPatch } from "./config-edit.ts";
 import { PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings, roleUniverse, type ResolvedSettings } from "./settings.ts";
 import { discoverAgentPins } from "./agent-pins.ts";
@@ -41,6 +41,15 @@ export type Decision = {
   /** Ranking ids dropped by the role's provider pin (no route matching the pin) —
    * recorded like a probe-blocked candidate. */
   pinBlocked: string[];
+  /** Provider slugs the auto-pin's route probe rejected on the chosen model, in
+   * walk order — rendered `; route-blocked: …`. Slugs, not ids: the sibling
+   * `blocked` holds catalog ids and `pinBlocked` ranking ids. Empty when no
+   * probe ran. */
+  routeBlockedSlugs: string[];
+  /** True when the auto-pin applies and the model has gate-passing routes but
+   * every candidate was rejected (or the route-probe budget ran out): the
+   * selector stays bare and OpenRouter routes the request itself. */
+  pinDropped: boolean;
   /** Availability source for this role's selection: the keyed-catalog fast path or the probe walk. */
   availabilitySource: "keyed-catalog" | "probe";
   /** Candidates pruned as key-blocked (present in the public catalog, absent from the keyed one). */
@@ -68,10 +77,18 @@ export type Trigger = "session-start" | "manual";
 /** A ranked model resolved to a concrete catalog id. */
 type Candidate = { ranked: Ranked; catalogId: string };
 
-/** Per managed role: its bare chain key, role suffix, provider pin, the pool it
- * was chosen from, and the inputs the auto-pin chain builder needs (the expanded
- * def for `rankedRoutes`, and whether the pin was auto-derived). */
-type ChainPlan = { key: string; suffix: string | undefined; pin: string; pool: Candidate[]; chosenIdx: number; def: RoleDef; autoPin: boolean };
+/** Per managed role: its bare chain key, role suffix, provider pin, the
+ * candidates its chain's fallback models are drawn from, the chosen model's
+ * index in that list, and the inputs the auto-pin chain builder needs (the
+ * expanded def for `rankedRoutes`, and whether the pin was auto-derived).
+ * `candidates` is the role's ranked candidate list minus the candidates no
+ * chain entry may name (key-blocked, probe-blocked) — not the probe-clean pool
+ * — so the chain can reach a cheaper-or-equal model ranked below the probe
+ * window. `pinnedSlug` is the route the auto-pin wrote — undefined for a manual
+ * pin, for a dropped pin and with the capability off — so the chain builder can
+ * exclude the pinned route by slug rather than by its position in the route
+ * order. */
+type ChainPlan = { key: string; suffix: string | undefined; pin: string; pinnedSlug: string | undefined; candidates: Candidate[]; chosenIdx: number; def: RoleDef; autoPin: boolean };
 
 export type Deps = {
   getToken(): Promise<string>;
@@ -83,6 +100,13 @@ export type Deps = {
   getSettings?(): Promise<Record<string, unknown>>;
   getKeyMeta?(token: string): Promise<KeyMeta>;
   probeModel?(token: string, catalogId: string): Promise<ProbeVerdict>;
+  /**
+   * DI seam like `probeModel`; production defaults to the real `probeRoute`.
+   * One-token completion bound to a single provider route (`provider.only`), the
+   * auto-pin's routability gate: OpenRouter's routing table can exclude a route
+   * its endpoints API still lists as healthy.
+   */
+  probeRoute?(token: string, catalogId: string, providerSlug: string): Promise<ProbeVerdict>;
   /** DI seam like `getKeyMeta`/`probeModel`; production defaults to `fetchKeyAvailability` (never throws). */
   getKeyAvailability?(token: string): Promise<KeyAvailability>;
   /**
@@ -106,6 +130,12 @@ const CONFLICT_RETRIES = 3;
 /** Per-role cap on allowlist probe requests (budget against pathological all-blocked pools). */
 const PROBE_BUDGET = 12;
 
+/** Per-role cap on route-probe requests for the auto-pin walk (budget against a
+ * pathological route pool: a fully blocked model with dozens of routes must not
+ * turn the daily update into a long probe walk). Hitting the cap with no clean
+ * candidate drops the pin, exactly as an all-blocked pool does. */
+export const ROUTE_PROBE_BUDGET = 12;
+
 function mtimeOf(path: string): number {
   try {
     return statSync(path).mtimeMs;
@@ -120,9 +150,11 @@ function decisionLine(d: Decision): string {
   const blocked = d.blocked.length > 0 ? `; blocked: ${d.blocked.join(", ")}` : "";
   const endpoint = d.endpointBlocked.length > 0 ? `; endpoint-blocked: ${d.endpointBlocked.join(", ")}` : "";
   const pin = d.pinBlocked.length > 0 ? `; pin-blocked: ${d.pinBlocked.join(", ")}` : "";
+  const routes = d.routeBlockedSlugs.length > 0 ? `; route-blocked: ${d.routeBlockedSlugs.join(", ")}` : "";
+  const dropped = d.pinDropped ? "; pin dropped (no routable route)" : "";
   return d.from === d.to
-    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`
-    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`;
+    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin}${routes}${dropped})`
+    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin}${routes}${dropped})`;
 }
 
 /**
@@ -372,6 +404,10 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
     const pinUnmatched: string[] = [];
     const probe = deps.probeModel ?? probeModel;
     const probeVerdicts = new Map<string, ProbeVerdict>();
+    const routeProbe = deps.probeRoute ?? probeRoute;
+    /** Route verdicts, cached by `catalogId@slug` across roles: a route shared by
+     * several roles is probed once per run. */
+    const routeVerdicts = new Map<string, ProbeVerdict>();
     for (const [role, def] of Object.entries(settings.roles)) {
       // Locked: no ranking, no probe, no decision, no selector/chain write.
       if (lockedRoles.has(role)) continue;
@@ -483,14 +519,50 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // `splitUpstreamRouting` parses the trailing `@<slug>` and applies
       // `compat.openRouterRouting = { only: [slug] }`.
       //
-      // Auto-pin (spec #58): with the soft `preferOwnProvider` capability on and
-      // no manual pin, the chosen model's best route by the role's own value
-      // rides as that suffix, so the price the ranking assumed is the price the
-      // request pays. A manual `providerPin` is a hard gate and always wins; a
-      // model with no candidate route keeps default routing (bare selector).
+      // Auto-pin (spec #58, routability-verified by spec #90): with the soft
+      // `preferOwnProvider` capability on and no manual pin, the best route the
+      // probe accepts rides as that suffix. That candidate is the route the role
+      // was priced on, so the price the ranking assumed is the price the request
+      // pays — but only while the walk does not skip the candidate; a skipped
+      // candidate means the route that replaced it pays, at its own price. A
+      // manual `providerPin` is a hard gate and always wins; a model with no
+      // gate-passing route keeps default routing (bare selector).
+      //
+      // The route order is the one the fallback chain already uses
+      // (`rankedRoutes`). Every candidate is probed with `provider: { only:
+      // [slug] }`, because OpenRouter's endpoints API can list a route as
+      // healthy while its routing table excludes it — the failure the endpoints
+      // data cannot see. A `blocked` route is skipped, `unknown` counts as
+      // usable (a transient blip must never unpin a role), and a pool with no
+      // clean candidate drops the pin: the selector stays bare and OpenRouter
+      // routes the request itself instead of 404ing on an unroutable `@<slug>`.
       const manualPin = def.providerPin;
-      const autoRoute = autoPinApplies(def) ? bestRoute(chosen.ranked.model, def) : null;
-      const pinSlug = manualPin ?? autoRoute?.providerSlug;
+      const autoRoutes = autoPinApplies(def) ? rankedRoutes(chosen.ranked.model, def) : [];
+      // No gate-passing route means nothing to pin and nothing to drop: the bare
+      // selector is default routing, not a dropped pin.
+      const hasAutoRoutes = autoRoutes.length > 0;
+      const routeBlockedSlugs: string[] = [];
+      let autoSlug: string | undefined;
+      let routeProbesSpent = 0;
+      for (const r of autoRoutes) {
+        const key = `${chosen.catalogId}@${r.providerSlug}`;
+        let verdict = routeVerdicts.get(key);
+        if (verdict === undefined) {
+          if (routeProbesSpent >= ROUTE_PROBE_BUDGET) break;
+          verdict = await routeProbe(token, chosen.catalogId, r.providerSlug);
+          routeVerdicts.set(key, verdict);
+          routeProbesSpent++;
+        }
+        if (verdict === "blocked") {
+          // Deduped: two routes can share a provider slug (the chain collapses
+          // them too), and the decision line should not list one slug twice.
+          if (!routeBlockedSlugs.includes(r.providerSlug)) routeBlockedSlugs.push(r.providerSlug);
+          continue;
+        }
+        autoSlug = r.providerSlug;
+        break;
+      }
+      const pinSlug = manualPin ?? autoSlug;
       const pin = pinSlug !== undefined ? `@${pinSlug}` : "";
       const chosenRow = rowById.get(chosen.catalogId);
       // Append only a level the model's catalog thinking[] actually supports —
@@ -509,16 +581,28 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         blocked: blockedForRole,
         endpointBlocked: endpointFilterDrops(def, rank.models),
         pinBlocked: providerPinDrops(def, rank.models),
+        routeBlockedSlugs,
+        pinDropped: hasAutoRoutes && autoSlug === undefined,
         availabilitySource: availability.active ? "keyed-catalog" : "probe",
         keyBlockedCount,
       });
 
       // Fallback chain inputs for every managed role: the bare key (a chain key
-      // matches the active model id, never a level) plus the pool the chosen model
-      // came from. Values are built after the loop, once every key claim is known.
+      // matches the active model id, never a level) plus the candidate list the
+      // chain's fallback models are drawn from. Values are built after the loop,
+      // once every key claim is known.
       if (settings.writeFallbackChains) {
         const key = suffix !== undefined && finalSelector.endsWith(`:${suffix}`) ? finalSelector.slice(0, -(suffix.length + 1)) : finalSelector;
-        chainPlanByRole[role] = { key, suffix, pin, pool, chosenIdx: pool.indexOf(chosen), def, autoPin: autoRoute !== null };
+        // The chain's fallback models come from the role's whole ranked
+        // candidate list, so a cheaper-or-equal model ranked below the probe
+        // window can be chained. Only the candidates the probe walk would never
+        // accept are dropped — key-blocked (the account's key cannot use them)
+        // and probe-verdict-blocked (present in the public catalog but not for
+        // this key). An unprobed candidate stays: the chain's deeper entries are
+        // no longer required to be probe-verified. The chosen model passed both
+        // predicates, so it is always in the list and `chosenIdx` is never -1.
+        const chainCandidates = candidates.filter((c) => !keyBlocked(c) && probeVerdicts.get(c.catalogId) !== "blocked");
+        chainPlanByRole[role] = { key, suffix, pin, pinnedSlug: autoSlug, candidates: chainCandidates, chosenIdx: chainCandidates.indexOf(chosen), def, autoPin: hasAutoRoutes };
       }
     }
 
@@ -539,13 +623,18 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       for (const d of decisions) {
         const plan = chainPlanByRole[d.role];
         const suffix = claims[plan.key] === 1 ? plan.suffix : undefined;
-        // Cost-aware ordering: prefer fallbacks priced at or below the chosen
-        // model (a fallback should not cost more than the primary), then fill any
-        // remaining depth with the next-best by value.
-        const after = plan.pool.slice(plan.chosenIdx + 1);
-        const chosenPrice = plan.pool[plan.chosenIdx].ranked.priceEff;
-        const cheaper = after.filter((p) => p.ranked.priceEff <= chosenPrice);
-        const pricier = after.filter((p) => p.ranked.priceEff > chosenPrice);
+        // Cost-aware ordering with a quality floor: prefer fallbacks priced at or
+        // below the chosen model that still retain `fallbackQualityFloor` of its
+        // quality (a failover must not silently drop the role onto a much weaker
+        // model), then fill any remaining depth with the next-best by value. The
+        // floor and the `after` set both key off the chosen model — the leader on
+        // a fresh pick, the kept current candidate on a kept role — and the floor
+        // never filters the pricier set, so a cheap-but-weak candidate set cannot
+        // starve the chain.
+        const after = plan.candidates.slice(plan.chosenIdx + 1);
+        const chosen = plan.candidates[plan.chosenIdx];
+        const cheaper = after.filter((p) => p.ranked.priceEff <= chosen.ranked.priceEff && p.ranked.q >= chosen.ranked.q * settings.fallbackQualityFloor);
+        const pricier = after.filter((p) => p.ranked.priceEff > chosen.ranked.priceEff);
         const chainPool = [...cheaper, ...pricier].slice(0, settings.fallbackChainDepth);
         // A chain value's thinking level is appended only when the target's
         // catalog entry advertises support (or the level is a meta level).
@@ -556,7 +645,7 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         const values: string[] = [];
         if (plan.autoPin) {
           // Auto-pin chain (spec #58, expanded by #69): every gate-passing route
-          // of the primary model (all but the pinned best), then every
+          // of the primary model except the pinned route, then every
           // gate-passing route of each fallback model, in the role's
           // value-for-money score order (`rankedRoutes`, spec #71) — every entry
           // bound to its route's provider, so a down primary
@@ -564,12 +653,17 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
           // than a different model. `rankedRoutes` already applies every gate
           // (non-degraded, endpoint filters, usable billed price, the
           // maxPriceUsdPerM cap, the allowed-providers whitelist), so the chain
-          // carries exactly the routes the role can use. The dedup below
-          // collapses two routes that share a provider slug (same chain value),
-          // so the chain length is (R_primary − 1) + Σ R_fallback over distinct
-          // gate-passing provider slugs.
-          const chosenCandidate = plan.pool[plan.chosenIdx];
-          for (const r of rankedRoutes(chosenCandidate.ranked.model, plan.def).slice(1)) {
+          // carries exactly the routes the role can use. The pin is excluded by
+          // slug, not by position: the route probe can pin a route other than
+          // the score leader, and with a dropped pin no route is excluded at
+          // all. The dedup below collapses two routes that share a provider slug
+          // (same chain value), so the chain length is (R_primary − 1) + Σ
+          // R_fallback over distinct gate-passing provider slugs (R_primary with
+          // no pin). Only the pinned route is probe-verified: one unroutable
+          // chain entry is survivable, omp fails over.
+          const chosenCandidate = plan.candidates[plan.chosenIdx];
+          for (const r of rankedRoutes(chosenCandidate.ranked.model, plan.def)) {
+            if (r.providerSlug === plan.pinnedSlug) continue;
             values.push(`openrouter/${chosenCandidate.catalogId}@${r.providerSlug}${levelFor(chosenCandidate.catalogId)}`);
           }
           for (const p of chainPool) {

package/web/app.js

@@ -185,6 +185,7 @@ const TIPS = {
   focusCrossSource: "Cross-source: the zeroeval per-entry price/context compared against the plugin's own price/context for the models carrying the metric (the median relative divergence, within a 0.5 tolerance). The speed figure is informational only (rps vs tok/s). An annotation, never a gate — it never feeds the 1/price² blend; unknown means no model joined or the payload carried none of the four fields.",
   imageFilter: "Require image input (filters.image) — the gate that shrinks the vision role's eligible set.",
   providerPin: "Hard provider pin: the OpenRouter provider slug this role's requests are routed to (a tiered slug like deepinfra/fp8 is accepted verbatim). Setting it opts the role out of the automatic best-route pin; empty = default OpenRouter routing.",
+  autoPin: "Automatic provider pin (candidate): this model's best route by the role's value-for-money score — the first route the updater's daily run tries. The updater probes that route with a one-token request bound to it (provider: { only: [slug] }) and skips to the next route when OpenRouter does not serve it, dropping the pin entirely (bare selector, OpenRouter's own routing) when none is routable — so the pin that gets written can be a later route, or absent.",
   features: "Opt-in capability presets (issue #40). Each flag applies the plugin's recommended settings for that capability to this role; an explicit knob value always wins. Export writes the flag, not the expanded values, so a future change to the recommendation keeps reaching the role.",
   featureState: "inherit = use the global flag (features.<id> in the lock file); on/off = a per-role override (roles.<role>.features.<id>) that beats the global in either direction.",
   featureKnob: "An individual knob the capability's recommended bundle fills. Leave it at inherit to take the recommendation; set a value to override it (an explicit value always wins over the flag).",
@@ -562,7 +563,12 @@ function renderExplain() {
   if (manualPin) {
     panel.append(el("p", { class: "sub pin-line", "data-tip": TIPS.providerPin, text: "pin: " + manualPin + " (manual)" }));
   } else if (ex.autoPin) {
-    panel.append(el("p", { class: "sub pin-line", "data-tip": TIPS.providerPin, text: "auto pin: " + ex.autoPin }));
+    // The candidate route — the first route the updater's value-ordered walk
+    // tries — not a promise of the written pin: the updater probes it and skips
+    // to the next route when OpenRouter does not serve it, or drops the pin
+    // entirely when none is routable (spec #90). Read-only, offline: the
+    // explorer cannot probe, so it names the candidate and says so in the tip.
+    panel.append(el("p", { class: "sub pin-line", "data-tip": TIPS.autoPin, text: "auto pin (candidate): " + ex.autoPin }));
   }
 
   panel.append(el("h3", { "data-tip": TIPS.composition, text: "Value composition" }));