omp-llm-role 1.1.0 → 1.2.0

package/README.md

@@ -48,6 +48,16 @@ omp plugin install omp-llm-role@gott50-plugins
   session actually booted on the previous `default` selector (an explicit
   `omp --model X` is never clobbered), and only on a real change. Disable with
   `activateDefaultOnEmptySession=false`.
+- **Provider in the model display.** When the live session model carries a
+  provider pin — a hand-set `providerPin`, or the automatic pin the
+  `providerPinning` capability writes — the status line's model segment shows
+  the route next to the model name, e.g. `DeepSeek V4.1 Flash @coreweave/fp8`.
+  The suffix is applied on session start, refreshed when a fallback switches the
+  model, and re-derived at the start of every turn, so it self-heals after omp
+  silently restores the primary model following a fallback cooldown. An unpinned
+  model's display is unchanged, and the suffix is display-only: it rides the
+  model object's `name`, so attribution, usage recording and model comparison
+  are unaffected.
 - **Surgical writes.** Only managed role lines, managed chain keys, and the
   plugin-managed `task.disabledAgents` names change; comments, blank lines and
   unknown keys stay byte-identical, and a no-change run writes nothing.
@@ -126,7 +136,7 @@ Per-role knobs (`roles.<name>.*`):
 | `filters.minOutputTokens` | `0` (off) | Drop routes whose endpoint output ceiling is below this (tokens) |
 | `filters.maxPriceUsdPerM` | `0` (off) | Drop a model whose thinking-adjusted blend exceeds this ($/M) |
 | `thinking` | shipped level | Thinking level appended to the selector (`off`…`max`, `auto`) |
-| `providerPin` | `""` (unset) | Pin the role's requests to one OpenRouter provider route (`@<slug>`, may be tiered like `deepinfra/fp8`). The role is then priced and gated by that route — its billed price and p50 throughput, not the `1/price²` blend — and a model with no matching route is ineligible |
+| `providerPin` | `""` (unset) | Pin the role's requests to one OpenRouter provider route (`@<slug>`, may be tiered like `deepinfra/fp8`). The role is then priced and gated by that route — its billed price and p50 throughput, not the `1/price²` blend — and a model with no matching route is ineligible. A manual pin **overrides** the automatic pin the `providerPinning` capability would write |
 | `cacheHitRate` | `0` (off) | Assumed cache-hit rate (0–1) for the role's input tokens; each route's effective input price becomes `h·cacheRead + (1−h)·input` before the 3:1 billed blend and the thinking factor. The `1/price²` weight basis stays the **listed** input price (the router's sort key), so a cheap cache on a lightly-weighted route cannot dominate; a route with no cache-read price keeps its full input price. `0`/absent = off (byte-identical ranking) |
 | `lambda` | derived | Explicit λ ($ per quality point) override |
 | `locked` | `false` | Leave the role alone: rank it but never rewrite its selector or chain (explorer toggle) |
@@ -142,7 +152,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` | A model is priced **and measured** on its own lab's route where one exists (DeepSeek's own endpoint, 94.5 % cache hit) — the route's billed price and its p50 throughput, so `q` moves too — falling back to the default blend otherwise |
+| `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 |
 | `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:
@@ -156,10 +166,13 @@ and otherwise when the global `features.<id>` is `true` — so a per-role `false
 beats a global `true`. The preset fills only knobs the role does not already
 set, and an explicit key is merged last, so it always wins. `providerPinning`'s
 recommended setting is a **soft per-model policy** (`preferOwnProvider`), not a
-hard `providerPin`: it re-prices a model on its own lab's route where one exists
-(the route's billed price **and** its p50 throughput, so `q` moves as well as
-`priceEff`) and never makes a model ineligible (the hard `providerPin` stays
-available by hand). `minContextTokens` is deliberately **not** part of `endpointCeilings` —
+hard `providerPin`: it prices a model on its **best route** (the max-`vfm` route
+— the value-for-money score, with the soft 50 tok/s floor — among the
+filter-passing, non-degraded, priced routes the account's
+allowed-providers whitelist permits) — the route's billed price
+**and** its p50 throughput, so `q` moves as well as `priceEff` — and never makes
+a model ineligible (the hard `providerPin` stays available by hand, and overrides
+the automatic choice). `minContextTokens` is deliberately **not** part of `endpointCeilings` —
 the complaint it would answer is an endpoint advertising a *fraction of the
 model's own window*, which an absolute token floor cannot express, so it stays a
 hand-set knob.
@@ -465,6 +478,13 @@ The plugin keeps only models the OpenRouter key can actually run:
   whitelist** is invisible to the key endpoint and the unauthenticated catalog, and a
   real request's 404 is the only reliable signal. Blocked candidates are excluded from
   selection and chains; a role with no clean candidate is left untouched.
+- **Allowed-providers whitelist** — the account's OpenRouter **allowed-providers
+  privacy whitelist** (openrouter.ai/settings/privacy) is learned once per run (a
+  canary request that bills no tokens) and every model's route pool is narrowed to
+  allowed providers before ranking, so a pin or a fallback hop is never written on a
+  provider the account cannot use. The run notes `OpenRouter allowed-providers
+  whitelist active — N providers; M routes pruned` (or `… whitelist: no whitelist`).
+  With no whitelist set — or when the harvest fails — nothing changes.
 - **Explorer key marking** — the explorer overlays every ranked model with a
   **usable** / **key-blocked** / **unknown** badge derived from the
   key-authenticated `GET /api/v1/models` (the account setting **"Filter the model
@@ -485,8 +505,10 @@ The plugin keeps only models the OpenRouter key can actually run:
   [docs/dev/quirks.md](docs/dev/quirks.md)).
 - **Provider whitelist.** The account's allowed-providers whitelist blocks many
   models, so the report's #1 and the written selector can differ — judge weights
-  on the reachable pool.
-- **Provider pinning opts out of auto-Exacto.** A `providerPin` writes a trailing
+  on the reachable pool. The updater prunes *routes* to the whitelist (see
+  Availability), but the report has no token and is not whitelist-aware.
+- **Provider pinning opts out of auto-Exacto.** A `providerPin` — or the
+  automatic pin the `providerPinning` capability writes — puts a trailing
   `@<slug>` on the selector, which omp applies as OpenRouter
   `provider: { only: [slug] }` routing. `only` is exclusive, so a pinned role's
   requests bypass OpenRouter's automatic Exacto tool routing (which routes tool

package/docs/dev/architecture.md

@@ -29,13 +29,14 @@ 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. `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, and the keyed-catalog availability primitive. 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`, `computeKeyAvailability`, `fetchKeyAvailability`, `catalogFromOmpModelsJson`, `THINKING_LEVELS`, and the `CatalogEntry`/`KeyMeta`/`Tier`/`ProbeVerdict`/`KeyAvailability` types. |
+| `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/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/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`, 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`. Owns `extDeps` (the extension's `Deps`) and the live-session model hook. 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/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. 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). |
 | `src/role-settings.ts` | The one validated role write path (validate → merge → backup → atomic write) and its removal half. Exports `validateRole`, `mergeExport`, `writeRoleSettings`, `mergeRemove`, `removeRoleSettings`, `timestamp`. Shared by the explorer's Export, `src/cli/create-role.ts`, `/create-agent` and `/remove-agent`. |
 | `src/role-archetypes.ts` | Purpose → weight archetype table (10 sets) + keyword fitting. Exports `ARCHETYPES`, `FALLBACK_ARCHETYPE`, `fitArchetype`, `archetypeById`, and the `Archetype`/`ArchetypeMatch` types. |
 | `src/agent-file.ts` | Agent `.md` rendering/placement. Exports `renderAgentFile`, `writeAgentFile`, `removeAgentFile`, `isReadOnlyTools`, `userAgentsDir`, `projectAgentsDir`, `READ_ONLY_TOOLS`, `RESERVED_AGENT_NAMES`, `AGENT_NAME_RE`, and the `AgentFileSpec`/`AgentWriteResult`/`AgentRemoveResult` types. |
@@ -116,7 +117,22 @@ The omp extension injects the production `Deps`; tests inject fakes.
    fetchKeyMeta(token)` → `tierGate` → `"billed" | "free" | "none"`; `"none"`
    aborts.
 5. **Catalog + probe.** `deps.getCatalog()` → `filterCatalog(catalog, tier)`;
-   `enrichThinkingLevels(rank.models, catalog)`. Per role, candidates are
+   `enrichThinkingLevels(rank.models, catalog)`.
+   **Whitelist prune.** The updater then harvests the account's
+   allowed-providers privacy whitelist once per run
+   (`deps.getAllowedProviders ? deps.getAllowedProviders(token, canaryModelId)
+   : fetchAllowedProviders(token, canaryModelId)`, a canary 404 that bills no
+   tokens) and, when it is non-null, replaces every model's route pool with the
+   routes whose `providerSlug` matches a whitelist entry (`providerAllowed`,
+   prefix match `slug === entry || slug.startsWith(entry + "/")`,
+   non-mutating). The prune is
+   the single change point — `roleRoute`, `bestRoute`, `rankedRoutes` and
+   `endpointFilteredModel` all read `m.routes` — so the soft basis, the auto-pin
+   and the fallback chains all become whitelist-aware. A `null` whitelist (no
+   whitelist set, harvest failed) leaves every pool untouched. The run notes
+   `OpenRouter allowed-providers whitelist active — N providers; M routes pruned`
+   (or `… whitelist: no whitelist`).
+   Per role, candidates are
    `resolveVariant`-resolved and then verified by a bounded `probeModel` walk
    (current selector first, then rank order; budget `PROBE_BUDGET = 12`; verdicts
    cached per run). Only the narrow no-allowed-providers 404 disqualifies; every
@@ -202,6 +218,7 @@ type Deps = {
   getSettings?(): Promise<Record<string, unknown>>;
   getKeyMeta?(token: string): Promise<KeyMeta>;
   probeModel?(token: string, catalogId: 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>;
 };
@@ -221,7 +238,11 @@ before `catalogFromOmpModelsJson`.
   `startExplorer`), `/create-agent` (architect → `createAgent` → in-process
   `runUpdater`), `/remove-agent` (`removeAgent` → in-process `runUpdater`),
   `/project-roles` (profile architect → `setupProject` → in-process
-  `runUpdater`), `session_shutdown` (closes the explorer handle).
+  `runUpdater`), `session_shutdown` (closes the explorer handle). The provider
+  display adds four event subscriptions — `session_start`,
+  `retry_fallback_applied`, `retry_fallback_succeeded` and `turn_start` — each
+  applying the live model's provider pin to its `name` (see
+  [`quirks.md`](quirks.md) for why `turn_start` is the self-healing hook).
 - **CLI**: `src/cli/llm-role-rank.ts` (report), `src/cli/create-role.ts`
   (authoring). The updater and explorer have no CLI shim — they run through
   `/refresh-roles` and `/explore-roles`.

package/docs/dev/ci.md

@@ -141,10 +141,21 @@ exit 1, so the command is safe to run unattended.
   is that version's CHANGELOG section. This is also the recovery path for a
   failed publish: the tag exists, so no new version is needed.
 
+  A successful `npm publish` is **not** immediately visible: npm prints "Your
+  package is being processed and may take a few minutes to become available",
+  and registry reads can serve the pre-publish packument for several minutes
+  (third-party mirrors such as jsDelivr lag longer). The step's log is the
+  discriminator — a direct publish prints `publishing to
+  https://registry.npmjs.org/ with tag latest`, `Signed provenance statement`
+  and `+ <pkg>@<version>`; a staged publish is a separate `npm stage publish`
+  and prints none of those.
+
   The dispatch resolves the workflow **from the ref**, so the tag's commit must
   contain `.github/workflows/ci.yml`. A tag cut before this workflow existed
   cannot be dispatched (`HTTP 422: Workflow does not have 'workflow_dispatch'
-  trigger`) — the recovery path only works for tags cut after it landed.
+  trigger`) — the recovery path only works for tags cut after it landed. The
+  workaround is to repoint the tag at a commit that contains the workflow (done
+  once, for `v1.1.0` → `4f78ce2`).
 
 `tests/ci.test.ts` asserts the offline half: the workflow's structure (jobs,
 triggers, permissions, the command it runs), the hook/workflow command parity,

package/docs/dev/current-state.md

@@ -1,15 +1,45 @@
-# Current state (2026-10-08)
+# Current state (2026-10-11)
 
 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
 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 ranking numbers
-below are the 2026-10-08 measurement (the input-price blend basis #21, the
-#17/#18/#19/#20 wave and the #34–#40 focus-axis/capability-flag work; see the top
-bullets) and are not re-derived on read.
+[`../../CHANGELOG.md`](../../CHANGELOG.md), not in this file. The model-level
+ranking numbers below are the 2026-10-09 measurement (the input-price blend basis
+#21, the #17/#18/#19/#20 wave and the #34–#40 focus-axis/capability-flag work);
+the provider-pin numbers are the 2026-10-11 measurement (spec #71; see the top
+bullet). Neither is re-derived on read.
 
+- Provider ordering: value-for-money route score (2026-10-11, spec #71): the
+  auto-pin route basis changed from the route's own value (`q_route −
+  λ·priceEff_route`) to a min/max-normalized **value-for-money score** `vfm =
+  wT·tNorm − wP·pNorm` (`wT = wTput/(wPrice+wTput)`, `wP =
+  wPrice/(wPrice+wTput)`; `tNorm`/`pNorm` min/max over the candidate set), with a
+  new **soft** `filters.preferredMinThroughput` floor (routes at or above sort
+  first; below-floor routes are kept and sorted last) that the `providerPinning`
+  preset sets to 50. `routeValue` is deleted. The model-level ranking is
+  unchanged — the report is not regenerated (the ranking CLI does not apply
+  capability features and no shipped role sets `preferOwnProvider`). Measured
+  2026-10-11 on the current endpoints cache with the live lock's expanded defs
+  (all four capabilities on, `cacheHitRate 0.9`; `deepseek/deepseek-v4.1-flash`,
+  11 allowed providers, 12 allowed routes):
+  `morph/fp8` ($0.0840,
+  103 tok/s) wins `default`, `smol`, `commit`, `task`, `advisor`; `coreweave/fp8`
+  ($0.1978, 185.5 tok/s) wins `slow`, `tiny`, `designer`; `decart/fp4` ($0.0639,
+  72 tok/s) wins `vision`, `plan`.
+
+- 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
+  `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.
 - 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
@@ -73,26 +103,33 @@ bullets) and are not re-derived on read.
   `src/features.ts`) is the single source of truth and `expandFeatures` the
   single precedence implementation (`effective def = shipped default ⊕
   preset(enabled flags) ⊕ explicit user keys`; a per-role `false` beats a global
-  `true`; an explicit knob always wins). Grounding on the 2026-10-07 cache
-  (`default` role, 142 eligible):
+  `true`; an explicit knob always wins). Grounding on the 2026-10-09 cache
+  (`default` role, 146 eligible; the `providerPinning` row is re-measured on the
+  2026-10-11 cache):
 
   | Flag | Recommended settings | Measured effect |
   |---|---|---|
-  | `endpointCeilings` | `filters.tools: true`, `filters.minOutputTokens: 16384` | 142 → 132 eligible, leader unchanged (`deepseek-v4.1-flash`, 0.579 $/M) |
-  | `cachePricing` | `cacheHitRate: 0.5` | 142 eligible, leader unchanged, its `priceEff` 0.579 → 0.508 (−12 %) |
-  | `providerPinning` | `preferOwnProvider: true` | per-model policy, never changes eligibility; 51 of 149 routed models match under a slug-prefix rule (33 exact, 17 prefix, 1 display-org), 10 of 25 orgs match for no model |
-  | `costCap` | `filters.maxPriceUsdPerM: 10` | 142 → 135 eligible (the top ≈5 %), leader unchanged; pool p90 7.8, p95 8.9 $/M, every leader 0.58–0.85 $/M |
+  | `endpointCeilings` | `filters.tools: true`, `filters.minOutputTokens: 16384` | 146 → 135 eligible, leader unchanged (`deepseek-v4.1-flash`, 0.37 $/M) |
+  | `cachePricing` | `cacheHitRate: 0.5` | 146 eligible, leader unchanged, its `priceEff` 0.3732 → 0.3522 (−5.6 %) |
+  | `providerPinning` | `preferOwnProvider: true`, `filters.preferredMinThroughput: 50` | per-model policy, never changes eligibility; prices each model on its **best route** (max `vfm` among the filter-passing, non-degraded, priced routes, cap-respecting; the soft 50 tok/s floor sorts below-floor routes last; ties by slug then id) — 144 of 144 routed models have a candidate route (2026-10-11), so the soft basis covers the whole routed field |
+  | `costCap` | `filters.maxPriceUsdPerM: 10` | 146 → 137 eligible (the top ≈6 %), leader unchanged; pool p90 7.8, p95 11.1 $/M, every leader 0.20–3.71 $/M |
 
   `providerPinning`'s recommended setting is a **soft per-model policy**
   (`preferOwnProvider`), not a hard `providerPin`: a hard pin would make a model
-  with no matching route ineligible and empty ~2/3 of a role's pool, so the
-  policy re-prices a model on its own lab's route where one exists and falls back
-  to the `1/price²` blend otherwise. `minContextTokens` is deliberately not in
-  the `endpointCeilings` bundle (an absolute floor cannot express the video's
-  fraction-of-the-model's-own-window complaint). The flags are settable from
-  `create-role.ts`, `/create-agent`, `/project-roles` (`--feature`/
-  `--list-features`) and the explorer's Features panel; the ranking numbers are
-  unchanged until a flag is turned on.
+  with no matching route ineligible and empty most of a role's pool, so the
+  policy prices a model on its **best route** — the max-`vfm` route (the
+  value-for-money score, with the soft 50 tok/s floor sorting below-floor routes
+  last) among the filter-passing, non-degraded, priced routes (thinking-adjusted
+  price ≤ `maxPriceUsdPerM`; ties by slug then id) — and falls back to the
+  `1/price²` blend only when the model has no candidate route. The basis is soft:
+  it never changes eligibility, and on the 2026-10-11 cache every one of the 144
+  routed models has a candidate route, so the capability covers the whole routed
+  field (the old own-lab slug-prefix rule matched only 51 of 149). `minContextTokens`
+  is deliberately not in the `endpointCeilings` bundle (an absolute floor cannot
+  express the video's fraction-of-the-model's-own-window complaint). The flags
+  are settable from `create-role.ts`, `/create-agent`, `/project-roles`
+  (`--feature`/`--list-features`) and the explorer's Features panel; the ranking
+  numbers are unchanged until a flag is turned on.
 
 - Cross-source axis (2026-10-07, issue #38): the focus-metric gate gained the
   cross-source axis — the zeroeval per-benchmark payload's **second, independent**
@@ -616,18 +653,18 @@ bullets) and are not re-derived on read.
   0.663, margin 0.039 > `switchMargin`), because the incumbent has no Design
   Arena data and takes the neutral fill while MiMo carries a measured 0.97.
   The other nine roles are untouched (only `designer` weights `website`).
-- 407 llm-stats models; OpenRouter matched 155/407 (throughput), 153 priced (the
-  2026-10-07 snapshot read 150/400 — the daily cache moved, not the code; the
+- 408 llm-stats models; OpenRouter matched 155/408 (throughput), 153 priced (the
+  2026-10-08 snapshot read 155/407 — the daily cache moved, not the code; the
   #34–#40 axes and flags leave every ranking byte-identical until a flag is
   turned on).
 - Eligible per role: 146 (vision 75, designer 89, image-input filter).
 - Value-ranking leaders (this report, thinking-adjusted prices; the *ranking*
   leaders, before the account's provider whitelist drops the blocked ones):
-  `default` DeepSeek-V4.1-Flash (0.808), `smol` Muse Spark 1.1 (0.687),
-  `slow` Muse Spark 1.3 (0.832), `vision` Qwen3.8 Flash (0.731), `plan`
-  Muse Spark 1.3 (0.795), `commit` Muse Spark 1.1 (0.725), `tiny`
-  Mercury 2 (0.797), `task` DeepSeek-V4.1-Flash (0.749), `advisor`
-  Muse Spark 1.3 (0.786), `designer` DeepSeek-V4.1-Flash (0.761).
+  `default` DeepSeek-V4.1-Flash (0.810), `smol` DeepSeek-V4.1-Flash (0.729),
+  `slow` DeepSeek-V4.1-Flash (0.832), `vision` DeepSeek-V4.1-Flash (0.730),
+  `plan` Muse Spark 1.3 (0.793), `commit` DeepSeek-V4.1-Flash (0.762), `tiny`
+  Muse Spark 1.1 (0.791), `task` DeepSeek-V4.1-Flash (0.754), `advisor`
+  Muse Spark 1.3 (0.787), `designer` DeepSeek-V4.1-Flash (0.787).
 - Thinking-adjusted pricing landed (2026-09-27): the suffix table moved into
   `DEFAULT_ROLES` as a per-role `thinking` field, and the price axis scales by
   the level's factor for thinking-capable models — `slow` (`:max`, ×7.86)

package/docs/dev/data-sources.md

@@ -159,8 +159,11 @@ probability proportional to `1/price²`). The weight basis is the **input
 
 A role with a `providerPin` does **not** use this blend: it prices the
 model's matching route directly — the route's billed 3:1 price and its p50
-throughput (scoring.md, *Route-aware pricing*). The blend is the unpinned
-default.
+throughput (scoring.md, *Route-aware pricing*). A role with the soft
+`preferOwnProvider` policy (the `providerPinning` capability) likewise prices
+each model on its **best route** rather than the blend, falling back to the blend
+only when the model has no candidate route (scoring.md, *Capability presets*).
+The blend is the default for every other model.
 
 ## OpenRouter — key metadata (tier gate)
 
@@ -180,8 +183,8 @@ freeUsable   = free_model_daily_requests.remaining > 0
 billed → billed variants only (exclude `:free`, `:batch`); else free → `:free`
 variants only (exclude `:batch`); else `"none"` aborts the run. The key endpoint
 carries **no** model/provider restriction field — the account's allowed-providers
-whitelist is invisible to it (see the keyed catalog below and the probe in
-[`architecture.md`](architecture.md)).
+whitelist is invisible to it (see the allowed-providers whitelist below and the
+probe in [`architecture.md`](architecture.md)).
 
 ## OpenRouter — keyed catalog (availability)
 
@@ -202,6 +205,32 @@ makes the Bearer-authenticated catalog a per-key allowlist.
   every consumer re-fetches, and `fetchKeyAvailability` **never throws** (a failure
   degrades to `unavailable` with empty sets, so the probe walk / `unknown` marks stand).
 
+## OpenRouter — allowed-providers whitelist (availability)
+
+The account's **allowed-providers privacy whitelist**
+(openrouter.ai/settings/privacy) restricts which provider routes a request may
+use. It is invisible to `/api/v1/key` and to the catalog endpoints; the only
+place it appears is the 404 body of a request that fails because of it.
+
+- **URL**: `POST https://openrouter.ai/api/v1/chat/completions` with
+  `provider.only: ["__omp-llm-role-canary__"]` (a nonexistent provider slug) on a
+  valid catalog model. `fetchAllowedProviders(token, modelId, fetchImpl?)`
+  (`src/availability.ts`) issues it.
+- **Signal**: the 404 body names the whitelist after "permits only:" — the
+  message is parsed into a `Set<string>` of bare lab names (`coreweave`,
+  `baseten`, …). A non-404 response, a body without the clause (no whitelist
+  set), or any transport/shape failure returns `null`. The canary 404s, so it
+  bills no tokens.
+- **Match rule**: a route's `providerSlug` is allowed when it equals a whitelist
+  entry or starts with `<entry>/` — the whitelist carries bare lab names while
+  route slugs are tiered (`coreweave/fp8`, `baseten/fp8`).
+- **Consumer**: the updater harvests it **once per run** (with a valid catalog
+  model id) and prunes every model's route pool to allowed providers before
+  ranking (architecture.md, *Data flow*). It is **not cached to disk** — every
+  run re-learns it, so a privacy-setting change takes effect on the next refresh
+  — and `fetchAllowedProviders` **never throws** (a failure degrades to `null`,
+  which leaves every route pool untouched).
+
 ## Design Arena — design quality
 
 Two routes, never averaged (same Elo family; mean diff −1.0 website … −5.1 svg,

package/docs/dev/explorer.md

@@ -99,8 +99,12 @@ Endpoints:
   expansion the preview would omit the preset the baseline includes and every
   row's Δ would be a lie. The posted def is the **authored** def (flags + explicit
   keys); the expansion is applied only for the ranking call, never persisted.
-- `handleExport` calls `writeRoleSettings(activeScope.lockPath, body.roles)` and
-  returns its result verbatim plus the written `lockPath`.
+- `handleExport` validates every dirty role first — `validateRole` plus a
+  **provider-pin check**: a `providerPin` that matches no route in the loaded
+  dataset is rejected (`role "<name>": provider pin "<slug>" matches no route in
+  the loaded dataset`) before any write, so an exported role cannot carry an
+  unroutable pin. It then calls `writeRoleSettings(activeScope.lockPath,
+  body.roles)` and returns its result verbatim plus the written `lockPath`.
 - Unknown `/api/*` → 404; wrong method → 405; non-API non-GET → 405.
 - `readBody` caps at `MAX_BODY = 1 MiB` (413); `readJson` → 400 on invalid JSON.
 - `serveStatic` resolves against `webDir` and rejects traversal (`full` must be
@@ -144,7 +148,12 @@ Pure, no I/O; all ranking math is delegated to `src/engine.ts`.
   `gapAbove`/`gapToTop`/`above`, `closing` (the
   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), and the availability overlay `key`/`keyReason`
+  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`
+  route (scoring.md, *Route ordering*), when the role sets
+  `preferOwnProvider` and carries no manual `providerPin`, else `null`), 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`.
 
@@ -277,7 +286,16 @@ a scraped third-party site, so the DOM is built with
   changes call `scheduleRecompute()` (120 ms debounce).
 - **Explain**: `selectModel(id)` → `POST /api/explain {role, def, modelId}` →
   `renderExplain()` (composition table, cost line, "why not higher",
-  dominators, and the availability line).
+  dominators, and the availability 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).
+- **Provider pin field**: the editor renders a text input for
+  `roles.<role>.providerPin` (a tiered slug like `deepinfra/fp8` is kept
+  verbatim; empty clears the key, resuming the automatic choice). It is the
+  manual override of the auto-pin; Export rejects a slug that matches no route in
+  the loaded dataset (see *Export path*).
 - **Availability overlay**: each row's `key` renders as a three-state badge in
   the `key` column; the **hide key-blocked** checkbox beside the filter/top-n
   controls drops `blocked` rows from the table (a client-side filter — the

package/docs/dev/quirks.md

@@ -146,6 +146,22 @@ things that only bite someone changing or debugging the code.
   update (or a `link` to a changed tree), a session that was already running
   still executes the module it loaded at start; a write from that stale code can
   revert a newer write. Restart the session after updating the plugin.
+- **omp's restore-to-primary is silent to extensions.** After a fallback
+  cooldown, omp restores the primary model at prompt admission
+  (`#maybeRestoreRetryFallbackPrimary`) with **no** session event, and
+  `model_changed` is not delivered to extensions — so a display derived from the
+  fallback events alone would keep the fallback's provider pin after a restore.
+  The provider display (`src/provider-display.ts`) therefore re-derives the pin
+  from the live model on `turn_start`, which *is* extension-delivered and fires
+  after the restore. The same re-derive covers a manual `/model` change (with a
+  one-turn lag). The primary and a fallback may be the same registry object
+  (same model id, different route), so the strip-then-append is idempotent and
+  reads the pin from the live model's routing block, never a cached value.
+  `retry_fallback_applied`/`retry_fallback_succeeded` are also emitted for
+  **advisor** fallbacks, where only the advisor's model changes and the session
+  model is untouched, so the event's selector is trusted only when it names the
+  live session model (`liveModelIsSelector`); otherwise the pin is re-derived
+  from the live model's routing block.
 - **Testing a registered slash command needs `--mode rpc` or a TUI** — `omp -p`
   (print mode) sends a leading `/name` as a *prompt* to the model, so the handler
   never runs and `ctx.ui.notify` is a no-op anyway. RPC mode does dispatch them:
@@ -154,6 +170,22 @@ things that only bite someone changing or debugging the code.
   stderr; `get_available_commands` confirms registration. Verified this way for
   `/create-agent` and `/explore-roles` (omp 18.4.8).
 
+## Repository plumbing
+
+- **The https credential cannot *introduce* a workflow change.** `origin` is
+  https and its credential is a `gh` OAuth token with scopes
+  `admin:public_key, gist, read:org, repo` — no `workflow` — so a push that adds
+  or modifies `.github/workflows/*` is rejected ("refusing to allow an OAuth App
+  to create or update workflow … without `workflow` scope"), and the REST
+  contents API is rejected the same way. The check is a diff against the ref's
+  base, not a property of the ref: a new branch or tag whose commit already
+  contains the workflow, with `main` also containing it, pushes fine over https
+  (verified 2026-10-08). So only the commit that lands a workflow edit needs the
+  SSH route — `git push git@github.com:Gott50/omp-llm-role.git main` — and
+  because that bypasses the `origin` remote it leaves `refs/remotes/origin/main`
+  stale, which makes `scripts/release.ts cut` refuse ("HEAD is not origin/main")
+  until `git fetch origin` runs.
+
 ## Historical
 
 - **Bare roles were priced as if thinking were free** (fixed 2026-09-30).

package/docs/dev/releasing.md

@@ -116,14 +116,35 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
 
 ## Status
 
-- **CI/CD landed 2026-10-08** (`fa7e546`): every pull request and every `main`
-  push runs the suite on GitHub (verified green on PR #57 and on the `main`
-  push), and a `v*` tag 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. The first real
-  CD run still needs the one-time trusted-publisher registration and a route
-  for the legacy `v1.1.0` tag; see [`ci.md`](ci.md).
-- **1.1.0 cut 2026-10-08** (`c013918`, tagged `v1.1.0`). `package.json` and
+- **CI/CD landed 2026-10-08** (`fa7e546`, docs follow-ups `4f78ce2`, `1d20ef9`,
+  `9244fdc`, `3c0125a`): every pull request and every `main` push runs the suite
+  on GitHub (verified green on PR #57 and on the `main` pushes), and a `v*` tag
+  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.1.0 published by CD 2026-10-09** (run 37897647817,
+  `gh workflow run ci.yml --ref v1.1.0`): the guard and the npm floor passed,
+  `npm publish` completed over OIDC trusted publishing with a provenance
+  attestation (`npm audit signatures`: 0 invalid, 0 missing), and the GitHub
+  Release was created with the 1.1.0 CHANGELOG section as its body
+  (`https://github.com/Gott50/omp-llm-role/releases/tag/v1.1.0`). Verified:
+  `dist-tags.latest` = `1.1.0`, npm's `gitHead` = `4f78ce2` (the tag's commit),
+  `_npmUser` = `GitHub Actions` carrying the trusted-publisher OIDC config, the
+  provenance statement in the transparency log at
+  `https://search.sigstore.dev/?logIndex=3159690884`, and the tarball is 56
+  files / 308.4 kB. The `v1.1.0` tag was repointed to
+  `4f78ce2` first — its original commit predates the workflow file, so the
+  dispatch was rejected (see [`ci.md`](ci.md)).
+- **npm route smoke-tested for 1.1.0** (2026-10-09, omp 18.8.6, throwaway
+  `HOME`, cwd outside the real home tree): `omp plugin install omp-llm-role`
+  installed 1.1.0 from the registry (`omp plugin doctor`: 4 ok, 0 warnings,
+  0 errors) and the 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`, and answered.
+- **1.1.0 cut 2026-10-08** (`c013918`, tagged `v1.1.0` — repointed to `4f78ce2`,
+  see the publish bullet). `package.json` and
   `.omp-plugin/marketplace.json` bumped in lockstep (plus `package-lock.json`
   via `npm install --package-lock-only` — the repo keeps it in lockstep, see
   `8811309`), `## [Unreleased]` renamed to `## [1.1.0] - 2026-10-08`, and the
@@ -141,26 +162,6 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
   `modelRoles` (9 roles), `retry.fallbackChains` and
   `task.disabledAgents: [designer]` into that HOME's `config.yml`, landed
   `llm-role-state.json` + `llm-role-history.jsonl`, and the session answered.
-  The npm route has **not** been smoke-tested for 1.1.0 — it is still serving
-  1.0.0.
-- **npm publish pending a valid token.** The `~/.npmrc` token is rejected
-  (`npm whoami` → 401 "your authentication token seems to be invalid",
-  `npm publish` → 404 on `PUT /omp-llm-role`), so `omp-llm-role@1.1.0` is not
-  on the registry yet, `dist-tags.latest` still points at `1.0.0`, and **npm's
-  `gitHead` for 1.1.0 does not exist yet** — the tag currently stands on its
-  own. The token is the only credential source (no repo `.npmrc`, no
-  `/opt/homebrew/etc/npmrc`, no `NPM_TOKEN` in the environment or the shell
-  profiles, no keychain entry) and it is a literal value, not a `${NPM_TOKEN}`
-  indirection, so the cause is a rejected/revoked/expired token — **not** the
-  2026-07-31 GAT restriction, which covers account/org/package-management
-  actions and not `whoami`, and not direct publish either (that loss is
-  targeted January 2027). `npm ping` and `npm owner ls` still succeed because
-  they are unauthenticated reads. Fix: the release workflow — OIDC trusted
-  publishing, no token — once the trusted publisher is registered (see
-  [`ci.md`](ci.md)). The tag was cut before the publish (the documented order is
-  publish-then-tag) precisely so the pinned git ref and the changelog link
-  resolve meanwhile; that also means the tag's commit predates the workflow
-  file, so the workflow cannot be dispatched against it.
 - **1.0.0 on all three channels** (2026-10-03): `omp-llm-role@1.0.0` on npm
   (`dist-tags.latest` = `1.0.0`), tagged `v1.0.0` at `fe98b76` (npm's
   `gitHead`); all three routes verified end-to-end against the real URLs
@@ -169,7 +170,7 @@ path, plus `marketplace update` + `upgrade` to a bumped catalog version), and
   landed the three daily caches in the installed copy.
 - **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; `latest` still points at
-  `1.0.0`, so it does not affect installs.
+  published 2026-10-03). It is not from this tree and does not affect installs
+  (`latest` is `1.1.0`).
 - **Next release: one owed.** `## [Unreleased]` carries the CI/CD entry; the
   number comes from the Unreleased scope, not from the open issues.