omp-llm-role 1.1.0 → 1.2.0

package/docs/dev/scoring.md

@@ -137,12 +137,60 @@ route instead of the `1/price²` blend:
 - a model with **no matching route** is ineligible for that role
   (`providerPinDrops` → `Decision.pinBlocked`, rendered `; pin-blocked: …`);
   `explainModel` reports "no route matches the role's provider pin".
-- an **unpinned** role ignores `routes` entirely — the blend path is unchanged.
+- an **unpinned** role ignores `routes` entirely — the blend path is unchanged —
+  **unless** it sets the soft `preferOwnProvider` policy (the `providerPinning`
+  capability), which prices it on its **best route** (the max-value-for-money
+  candidate route; see *Route ordering* and *Capability presets*).
 
 The pin is a cost-and-throughput posture, not a quality edit: it moves the price
 axis to the route's billed price and the throughput axis to the route's p50,
 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.
+
+- **Candidates.** A route is a candidate when it is non-degraded (`status === 0`),
+  passes `routePassesEndpointFilters(route, def.filters)`, carries a usable billed
+  price, and (when `filters.maxPriceUsdPerM > 0`) a thinking-adjusted price at or
+  below the cap. The allowed-providers whitelist is applied upstream by pruning
+  `m.routes` (see *Whitelist-aware route selection*).
+- **The score.** Each candidate is scored
+  `vfm = wT·tNorm − wP·pNorm`, where `tNorm`/`pNorm` are the route's p50
+  throughput and cache-adjusted billed price **min/max-normalized over the
+  candidate set** (`tNorm = (tput − tMin)/(tMax − tMin)`, `pNorm = (priceEff −
+  pMin)/(pMax − pMin)`; a zero span normalizes to 0), and `wT =
+  wTput/(wPrice+wTput)`, `wP = wPrice/(wPrice+wTput)`. Sort desc; ties break by
+  `providerSlug` then `id`, so a re-run is deterministic. A route with no p50 uses
+  the model's blended throughput (an absent p50 is unknown, not slow).
+- **The soft floor.** `filters.preferredMinThroughput` (tok/s; `0`/absent = off)
+  is a **preference, not a gate**: routes at or above the floor sort before
+  routes below it, and the score orders within each band. A below-floor route is
+  **never dropped** — it stays a last-resort candidate.
+- **`routeValue` is deleted.** The old `q(route p50) − λ·route price` route sort
+  key is gone; the score above is the only route basis. (The model-level
+  `value = q − λ·priceEff` is unchanged — see *`λ` and `value`*.)
+
+### Whitelist-aware route selection
+
+The updater narrows every model's route pool to the account's
+**allowed-providers privacy whitelist** before ranking (data-sources.md,
+*OpenRouter — allowed-providers whitelist*; architecture.md, *Data flow*). The
+prune is the single change point — `roleRoute`, `bestRoute`, `rankedRoutes` and
+`endpointFilteredModel` all read `m.routes` — so every route consumer above is
+whitelist-aware: a hard `providerPin` on a blocked provider matches no route and
+drops the model (`providerPinDrops`), the soft `preferOwnProvider` basis prices
+each model on its best **allowed** route, the endpoint-filtered blend is computed
+over the allowed pool, and the fallback chains carry only allowed routes. A
+`null` whitelist (no whitelist set, harvest failed) leaves every pool untouched,
+so the ranking is byte-identical to today. The whitelist is a route-selection
+filter, not a re-pricing: the role-independent `1/price²` blend (`m.price`/
+`m.throughput`) is left as the account-agnostic expected value, and a model with
+no allowed route keeps that blend (the soft basis never drops a model).
+
 ## Capability presets (feature flags)
 
 One named flag per opt-in capability (`features.<id>` global,
@@ -164,44 +212,55 @@ no flags the resolved roles are byte-identical to `DEFAULT_ROLES`. The effective
 def is what `rankRole`/`explainModel` see; the authored def (flags + explicit
 keys) is what the explorer edits and exports.
 
-What each recommendation does to the ranking math (grounded on the 2026-10-07
-cache, `default` role, 142 eligible):
+What each recommendation does to the ranking math (grounded on the 2026-10-09
+cache, `default` role, 146 eligible; the `providerPinning` bullet is re-measured
+on the 2026-10-11 cache):
 
 - **`endpointCeilings`** (`filters.tools: true`, `filters.minOutputTokens:
   16384`) drops tool-incapable routes and routes whose output ceiling is below
-  16 384 tokens from the priced pool (see *Endpoint filters*): 142 → 132
-  eligible, leader unchanged (`deepseek-v4.1-flash`, 0.579 $/M). 16 384 is the
+  16 384 tokens from the priced pool (see *Endpoint filters*): 146 → 135
+  eligible, leader unchanged (`deepseek-v4.1-flash`, 0.37 $/M). 16 384 is the
   video's own threshold (19 endpoints cap output at or below it).
 - **`cachePricing`** (`cacheHitRate: 0.5`) reprices the role on a cache-heavy
-  loop's invoice (see *Cache-read pricing*): 142 eligible, leader unchanged, its
-  `priceEff` 0.579 → 0.508 (−12 %). 0.5 is the low end of the measured
+  loop's invoice (see *Cache-read pricing*): 146 eligible, leader unchanged, its
+  `priceEff` 0.3732 → 0.3522 (−5.6 %). 0.5 is the low end of the measured
   third-party range (51–69 %), so the preset never over-credits a cache.
-- **`providerPinning`** (`preferOwnProvider: true`) prices a model on its own
-  lab's route where one exists, falling back to the default `1/price²` blend
-  otherwise. 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. The lab
-  match is a **slug prefix on the model's `orgId`** (exact, or `orgId` + `/`),
-  with the display `org` as a second try; there is no alias map in v1. Measured
-  coverage: 51 of the 149 routed models resolve to one of their own lab's routes
-  (33 on an exact slug match, 17 on an `orgId` prefix, 1 on the display-`org`
-  fallback), and 10 of 25 orgs match for no model (`zai-org` —
-  its lab route slug is `z-ai` — `google`, `qwen`, `inclusionai`, `nvidia`,
-  `microsoft`, `bytedance`, `thinking-machines`, `ibm`,
-  `gryphe`). An unmatched model keeps the blend, so the capability
-  **under-delivers rather than mis-pins**, and it **never changes eligibility**
-  (unlike the hard `providerPin`, which drops a model with no matching route).
-  The resolved route is the same basis a hard pin uses, so the preference moves
-  the **throughput** axis as well as the billed price — a role that routes to the
-  lab's endpoint gets that endpoint's p50 tok/s, not the blend's. Measured on the
-  2026-10-07 cache, the `default` leader's `priceEff` rises 0.579 → 0.975 while
-  its `value` *rises* 0.8132 → 0.8172, because its own lab route's p50 throughput
-  is higher than the blend's, so `q` moves too. That is deliberate (the pin path
-  has always priced and measured on the pinned route); a role that wants the
-  blend's throughput should leave the flag off.
+- **`providerPinning`** (`{ preferOwnProvider: true, filters: {
+  preferredMinThroughput: 50 } }`) prices a model on its **best route** — the
+  max-value-for-money candidate route (see *Route ordering*: the `vfm` score
+  desc, with the soft 50 tok/s floor sorting below-floor routes last) among the
+  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
+  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`)
+  is `rankedRoutes(model, def)[0]` (see *Route ordering* for the candidate
+  criteria and the score). The basis is **soft**: a model with no
+  candidate route keeps the blend and is never dropped, so the capability
+  **never changes eligibility** (unlike the hard `providerPin`, which drops a
+  model with no matching route). The `maxPriceUsdPerM` gate is **basis-independent**:
+  with no hard pin it caps the model's own blend price, not the soft route's, so
+  the flag can neither add nor drop a model; the candidate-route cap filter only
+  keeps the written pin at or below the cap. Measured coverage on the 2026-10-11 cache: all
+  144 routed models have a candidate route (the old own-lab slug-prefix rule
+  matched only 51 of 149), so the capability covers the whole routed field. The
+  resolved route is the same basis a hard pin uses, so the preference moves the
+  **throughput** axis as well as the billed price — a role that routes to the
+  best endpoint gets that endpoint's p50 tok/s, not the blend's. Measured on the
+  2026-10-11 cache (`rankRole` over the full model set), the `default` leader is
+  `deepseek-v4.1-flash` either way: the blend prices it at `priceEff` 0.2317 /
+  `value` 0.8056 / `q` 0.8069, while the soft best-route basis prices it at
+  `priceEff` 0.1187 / `value` 0.8092 / `q` 0.8099 on its best route `decart/fp4`
+  ($0.0639 billed, 72 tok/s). The soft route is cheaper than the blend, so
+  `priceEff` falls and `value` rises; `q` moves too because the route's p50
+  throughput replaces the blend's. That is deliberate (the pin path has always
+  priced and measured on the pinned route); a role that wants the blend's
+  throughput should leave the flag off.
 - **`costCap`** (`filters.maxPriceUsdPerM: 10`) drops the priciest tail of the
-  eligible pool: 142 → 135 (the top ≈5 %), leader unchanged. The pool's p90 is
-  7.8 and p95 8.9 $/M, and every role leader sits at 0.58–0.85 $/M, so the
+  eligible pool: 146 → 137 (the top ≈6 %), leader unchanged. The pool's p90 is
+  7.8 and p95 11.1 $/M, and every role leader sits at 0.20–3.71 $/M, so the
   preset never excludes today's leader.
 
 **Interaction with the switch hysteresis.** `switchMargin`/`priceSwitchFraction`
@@ -242,7 +301,10 @@ A model ranks for a role only when:
 - `minContextTokens` filters the **endpoint** `context_length`, not the
   model-level `context`;
 - `maxPriceUsdPerM` caps the thinking-adjusted `priceEff` (the price the role
-  actually pays), not the bare billed blend;
+  actually pays), not the bare billed blend. For a **pinned** role that is the
+  pin route's price; for a soft `preferOwnProvider` role it is the model's own
+  blend price (basis-independent, so the flag cannot change eligibility), while
+  the candidate-route filter keeps the auto-pin at or below the cap;
 - a role that declares `tools`/`minContextTokens`/`minOutputTokens` is **priced**
   on the surviving pool: `endpointFilteredModel` recomputes `price`/`throughput`
   as the `1/price²` blend over the routes that clear the filters
@@ -252,8 +314,9 @@ A model ranks for a role only when:
 
 `endpointFilterDrops(def, models)` lists the ranking ids the gate removed (they
 pass every other eligibility gate but have no capable route) for the decision
-log. `resolveSettings` validates all four; no shipped role sets an endpoint
-filter. Filters apply before ranking eligibility so percentile norms stay on the
+log. `resolveSettings` validates the four endpoint-filter keys plus the soft
+`filters.preferredMinThroughput`; no shipped role sets an endpoint filter.
+Filters apply before ranking eligibility so percentile norms stay on the
 unfiltered pool.
 
 ## Pareto frontier (★)

package/docs/dev/testing.md

@@ -52,28 +52,45 @@ passing.
     equal sets → no-filter; empty → unavailable; a keyed id absent from public →
     no-filter; aliases collapse; two parallel GETs, one authenticated; never
     throws.
-11. **Endpoint ceilings** (`endpoint-ceilings.test.ts`) — the narrower reads
+11. **Allowed-providers whitelist** (`allowed-providers.test.ts`,
+    `whitelist.test.ts`) — `fetchAllowedProviders` parses the 404 body's
+    "permits only:" list into a set and returns `null` for a 200, a 404 without
+    the clause, or a transport throw, with the canary request shape (POST,
+    bearer, `provider.only`, `max_tokens: 1`); the updater prunes every model's
+    route pool to allowed providers before ranking, so a blocked best route
+    falls to the next-best allowed route as the auto-pin, the chain carries only
+    allowed routes, a bare entry matches a tiered slug by prefix, the notify line
+    reports the active whitelist and the pruned count (or "no whitelist"), and a
+    `null` whitelist reproduces today's output byte-for-byte.
+12. **Endpoint ceilings** (`endpoint-ceilings.test.ts`) — the narrower reads
     context/output/tools, a missing field is null; a failing route drops, a null
     field is kept; a model with no capable route is ineligible; a filtered role
     is priced on the surviving pool; `maxPriceUsdPerM` caps the thinking-adjusted
     price.
-12. **Route pricing (provider pin)** (`route-pricing.test.ts`) — a pinned role
+13. **Route pricing (provider pin)** (`route-pricing.test.ts`) — a pinned role
     prices the matching route, not the blend; a tiered pin matches verbatim;
     `maxPriceUsdPerM` caps the route price; throughput is the route p50 with a
     blend fallback; no matching route → ineligible; the `@<slug>` selector and
-    chain carry the pin; a pin matching no route leaves the role unchanged.
-13. **Thinking price** (`thinking-price.test.ts`) — bare/off unadjusted; a level
+    chain carry the pin; a pin matching no route leaves the role unchanged. The
+    route-ordering score (spec #71): `rankedRoutes` orders by the value-for-money
+    score `vfm = wT·tNorm − wP·pNorm` (a throughput-heavy role picks a faster
+    route than a price-heavy role); the soft `filters.preferredMinThroughput`
+    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.
+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;
     catalog `thinking[]` wins over the OR flag; meta levels never gate.
-14. **OpenRouter blend** (`openrouter-blend.test.ts`) — price/throughput are the
+15. **OpenRouter blend** (`openrouter-blend.test.ts`) — price/throughput are the
     `1/price²`-weighted means over the page routes; flex/priority/degraded/free/
     `:batch` stay out; throughput renormalizes; the find-row fallback; the weight
     follows the input price.
-15. **Writing metric** (`writing.test.ts`) — `parseWritingEvidence` keys finite
+16. **Writing metric** (`writing.test.ts`) — `parseWritingEvidence` keys finite
     scores and rejects junk; `applyWritingScores` fills uncovered models; a
     covered model ranks above an uncovered one.
-16. **Benchmark sources** (`benchmark-sources.test.ts`) — `resolveBenchmarkSource`
+17. **Benchmark sources** (`benchmark-sources.test.ts`) — `resolveBenchmarkSource`
     maps an llm-stats benchmark page, a bare id, the writing leaderboard and a
     Design Arena link, `null` for an unknown host; `normalizeMetricKey` is
     dot-free; `parseBenchmarkPayload` reads the llm-stats `entries[]` and writing
@@ -91,7 +108,7 @@ passing.
     fields, `scoreMax`, join) and a metric colliding with a shipped key is
     rejected; `dryRunDeclaration` reports coverage/leader and rejects a zero-join;
     `extractBenchmarkLinks` pulls URLs from prose.
-17. **Agent creation** (`create-agent.test.ts`) — a purpose fits the expected
+18. **Agent creation** (`create-agent.test.ts`) — a purpose fits the expected
     archetype; a `--weights` set violating Σ(non-price) = 1 − w_price is refused;
     an existing agent file without `--force` is refused and writes no role;
     `--dry-run` writes neither file; an architect `spec` replaces the
@@ -99,46 +116,51 @@ passing.
     share, is a no-op for the archetype's own specialist set, and keeps both
     invariants; the nine-axis gate (the maintenance, provenance and cross-source
     axes are annotations, never a drop).
-18. **Agent removal** (`remove-agent.test.ts`) — the role's lock-file keys and the
+19. **Agent removal** (`remove-agent.test.ts`) — the role's lock-file keys and the
     agent file are deleted (backup written); a shipped default role, a reserved
     name and an invalid name are refused; nothing-to-remove errors; `--dry-run`
     writes nothing; the updater drops `modelRoles.<n>` and the plugin-managed
     `task.disabledAgents` entry.
-19. **Agent pins / disable** (`agent-pins.test.ts`, `agent-disable.test.ts`) —
+20. **Agent pins / disable** (`agent-pins.test.ts`, `agent-disable.test.ts`) —
     `parseAgentPin` takes the first `@role`; `discoverAgentPins` scans the three
     scopes, most specific wins; the sync is not day-gated; an unrelated entry
     keeps its position; an unknown role is never added.
-20. **Role enable / lock** (`role-enable.test.ts`, `role-lock.test.ts`) —
+21. **Role enable / lock** (`role-enable.test.ts`, `role-lock.test.ts`) —
     disabling drops the role from the resolved set and its `modelRoles` line; a
     locked role is not switched and its chain survives the prune; unlocking
     restores the switch.
-21. **Settings** (`settings.test.ts`, `settings-schema.test.ts`) — opt-in roles;
+22. **Settings** (`settings.test.ts`, `settings-schema.test.ts`) — opt-in roles;
     `priceSwitchFraction` range; flat/nested merge; `required` as string or
     array; an external metric key is weightable, a dotted one rejected;
-    `package.json` `omp.settings` deep-equals `deriveSettingsSchema()`.
-22. **Explorer** (`explorer.test.ts`, `explorer-scopes.test.ts`) — rank deltas;
+    `package.json` `omp.settings` deep-equals `deriveSettingsSchema()`. The
+    `providerPinning` preset sets `preferOwnProvider: true` +
+    `filters.preferredMinThroughput: 50` (the registry row and the expanded def
+    agree), an explicit `filters.preferredMinThroughput` beats the preset, and
+    the schema carries the `roles.<role>.filters.preferredMinThroughput` row
+    (number, min 0, default 0).
+23. **Explorer** (`explorer.test.ts`, `explorer-scopes.test.ts`) — rank deltas;
     contributions sum to `q`; `inverseCardinal` round-trips; Export preserves
     siblings and normalizes nested roles; the scope switcher; the availability
     overlay.
-23. **Project scope** (`project-updater.test.ts`, `project-setup.test.ts`,
+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;
     `setupProject` add/drop/keep, `--dry-run`, `--force`; the command is
     registered.
-24. **Session model** (`session-model.test.ts`) — the hook fires only after a real
+25. **Session model** (`session-model.test.ts`) — the hook fires only after a real
     write on a real `default` change; a dry run and a kept default skip it; a
     throwing hook is contained.
-25. **Docs** (`docs.test.ts`) — every relative markdown link resolves; no
+26. **Docs** (`docs.test.ts`) — every relative markdown link resolves; no
     reference to a moved doc; the CHANGELOG shape; `package.json` `files` entries
     exist; the README has no dev-only headings.
-26. **Architect provenance** (`architect-provenance.test.ts`) — the vendored
+27. **Architect provenance** (`architect-provenance.test.ts`) — the vendored
     prompt header matches `ARCHITECT_PROMPT_VERSION` and the version named in
     [`agent-authoring.md`](agent-authoring.md).
-27. **Architect retry** (`agent-architect.test.ts`) — a malformed architect
+28. **Architect retry** (`agent-architect.test.ts`) — a malformed architect
     response is retried once and the parsed spec returned; an always-malformed
     run throws carrying the raw output; a `run()` failure propagates with no
     retry.
-28. **Error reporting** (`error-report.test.ts`) — `reportUnexpectedError`
+29. **Error reporting** (`error-report.test.ts`) — `reportUnexpectedError`
     through its one entry point with fully injected deps: `off` → no fetch, no
     ledger write, `action: "off"`; `auto` + token → exactly one create whose body
     carries the fingerprint marker, plugin version, runtime, platform, label and
@@ -166,17 +188,42 @@ passing.
     aborts under one label differ; the in-process guard; and a ledger that
     tolerates junk and truncates a pathological stack — including a multi-byte
     one — to the 64 KB **byte** budget.
-29. **CI/CD** (`ci.test.ts`) — the workflow parses and declares both jobs with
+30. **CI/CD** (`ci.test.ts`) — the workflow parses and declares both jobs with
     `release` needing `test`; the `test` job's command is identical to the
     pre-commit hook's; the tag trigger covers every CHANGELOG tag link and the
     package version; `.node-version` is the file the workflow reads; the release
-    job declares `id-token: write` and references no npm token; the four
-    lockstep version fields agree; no tracked file lives under `cache/`; and
+    job declares `id-token: write` and references no npm token; the release job
+    runs the `notes` guard before `npm publish` and both steps name the same
+    notes file; the four lockstep version fields agree; no tracked file lives
+    under `cache/`; and
     `scripts/release.ts` against fixture repos — `due`'s exit codes, `notes`'s
     five refusals and its exact section body, `cut --dry-run` writing nothing,
     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
+    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.
+32. **Provider display** (`provider-display.test.ts`,
+    `provider-display-wiring.test.ts`) — `providerPinOf` reads the single
+    `openRouterRouting.only[0]` (else `vercelGatewayRouting`), preferring
+    OpenRouter, and returns null for a missing/empty/multi-entry block or a
+    non-string entry; `providerPinOfSelector` parses the trailing `@<slug>` with
+    and without a thinking suffix and returns null without one;
+    `withProviderSuffix` appends, strips a previous suffix, is idempotent, and
+    returns the base name for a null pin; `applyProviderDisplay` mutates a
+    record's `name` and no-ops on a non-record or a non-string name. The wiring
+    (a fake `pi`/`ctx` recording handlers) suffixes the live model on
+    `session_start`, applies the pin parsed from `event.to` on
+    `retry_fallback_applied` (falling back to the live model's routing block),
+    applies the pin from `event.model` on `retry_fallback_succeeded`, re-derives
+    from the live model on `turn_start` (the silent-restore case), strips when
+    neither source carries a pin, never calls `pi.setModel`, and contains a
+    throwing live-model read.
 
 ## Live checks
 

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

@@ -134,6 +134,62 @@ gating — that this plugin never reads (zero occurrences in `src/`, `web/`,
 `tests/`). The plugin's `features.<id>` keys are plugin settings, not omp
 feature flags; do not merge the two.
 
+## The provider-pin auto-configuration (spec #58)
+
+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:
+
+```
+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.
+
+**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:
+
+1. the same model on **every** gate-passing route except the pinned best, 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
+(`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
+**preference, not a gate** — it sorts below-floor routes last but never drops
+them, so a below-floor route still appears in the chain. The allowed-providers
+whitelist is not a `rankedRoutes` filter: the updater prunes each model's route
+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).
+
+**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.
+
 ## State, history, lock
 
 All under the agent dir (`agentDir()` in `src/state.ts`), next to the config