omp-llm-role 1.1.0 → 1.3.0

package/README.md

@@ -48,11 +48,28 @@ 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.
   `~/.omp/agent/llm-role-state.json` snapshots the previous `modelRoles` block
   on every write as a rollback aid.
+- **Usage ledger.** The plugin appends one row per assistant turn (the model,
+  the role, the provider, the token counts and the cost) to
+  `llm-role-usage.jsonl` beside its other state — `<project>/.omp` in project
+  mode, `~/.omp/agent` otherwise. It is append-only, capped at the newest 2000
+  rows, and best-effort (a recording failure never breaks a session). The
+  explorer's `$/task` column reads it to learn your own token mix; nothing else
+  uses it.
 
 ## Roles
 
@@ -110,6 +127,7 @@ Global knobs:
 | `writeFallbackChains` | `true` | Write per-role fallback chains into `config.yml` |
 | `fallbackChainDepth` | `2` | Fallback models per role chain |
 | `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) |
 
 Per-role knobs (`roles.<name>.*`):
@@ -126,7 +144,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 +160,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 +174,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.
@@ -408,21 +429,31 @@ editing source and re-running the CLI.
   that scope's lock file — a project scope resolves as the project lock merged
   over the user-level lock, exactly what the updater ranks. A project whose lock
   file is gone is shown disabled. Switching with unsaved edits asks first.
+- **Pool toggle** — the header switches the ranked pool between **raw** (the
+  account-agnostic fetch) and **as-written** (the pool the updater actually
+  writes from: the catalog/tier gate plus your account's allowed-providers
+  whitelist). The as-written pool is what you will get, so its leader is the
+  model the next `/refresh-roles` will pick; the raw pool shows the
+  account-agnostic ranking. The toggle is best-effort (a failed whitelist fetch
+  degrades to the raw pool) and per-scope, and it never affects **Export** —
+  Export always writes the role you authored, from either pool.
 - **Role tabs** — every role the plugin knows: the nine omp built-in roles, the
   shipped opt-in `designer`, and any role present only in the lock file. Each
   tab is tinted by provenance — `default` (omp built-in), `plugin` (shipped but
   opt-in), `user` (lock-file only) — and a disabled role is muted and dashed.
   Selecting a disabled role still ranks its models.
 - **Rank table** — every eligible model for the selected role, with `value`,
-  `q`, `$/M` (effective, thinking-adjusted), `tok/s`, `ctx`, a `★` Pareto
+  `q`, `$/M` (effective, thinking-adjusted), **`$/task`** (what you actually pay
+  per task under your own token mix — see below), `tok/s`, `ctx`, a `★` Pareto
   marker, and a `Δ` column showing the rank delta against the role's effective
   def (what the plugin does today).
 - **Explain panel** — click a row for the full decomposition: each weighted
   metric's raw value → cardinal transform → renormalized weight → contribution,
   the cost block (`λ`, effective vs billed price, `penalty = λ·price`,
-  `value = q − penalty`), "why not higher" (the value gap to the model above
-  plus the per-metric target that would close it), and the models that dominate
-  it on (price, q).
+  `value = q − penalty`), the **per-task price** breakdown, "why not higher"
+  (the value gap to the model above plus the per-metric target that would close
+  it), the models that dominate it on (price, q), and the **Price levers**
+  section (below).
 - **Weight editor** — edit the role's description, weights, `required` set,
   `filters.image`, `thinking` level, and `λ` override live; the table re-ranks
   on every change. Weights are edited freely (no implicit rescaling): the `Σ`
@@ -444,8 +475,30 @@ editing source and re-running the CLI.
 - **Hover explanations** — every column header, metric name, role tab, and
   control carries a tooltip explaining its semantics.
 
+**The per-task price (`$/task`).** The `$/M` column is the reported price — the
+billed 3:1 input:output blend OpenRouter charges, scaled by the role's thinking
+factor. The `$/task` column is what *you* pay per task: your own input:output
+token mix applied to the role's priced route. The mix comes from the plugin's
+own recorded usage (the role's median per-turn counts, from the
+`llm-role-usage.jsonl` ledger the plugin appends to as you work), falling back
+to the `tokenProfile` setting when a role has no recorded usage. It is
+**display-only** — the ranking still sorts on `$/M` — and it reads `—` when no
+profile is available (no recorded usage and no `tokenProfile` set) or the model
+has no usable route price. A model that is cheaper per token but
+more verbose can cost more per task; this column is where that shows up.
+
+**The price levers.** The explain panel's **Price levers** section makes the
+price posture visible. The **leader flip** is the price weight `w*` at which a
+cheaper challenger overtakes the current leader, with the challenger named and
+the distance from your current weight — so you can see whether your price
+posture binds (a small bump flips the pick) or is slack. It is absent when no
+cheaper challenger exists. The **thinking level** table shows which model wins
+at each level, with the level's price factor — the factor multiplies the price
+axis, so it penalizes expensive models more, which is why `auto` favours the
+cheap model. Both readouts are computed on the pool you are viewing.
+
 The UI never reimplements the ranking math: the numbers on screen are exactly
-the numbers the plugin would use. The server binds `127.0.0.1` only (no auth)
+the numbers the plugin would use. The server binds `[IP_ADDRESS]` only (no auth)
 and serves the SPA with no build step and no external requests.
 
 ## Availability
@@ -465,6 +518,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 +545,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

@@ -25,24 +25,26 @@ the extension's `/refresh-roles`, `/explore-roles` and `/create-agent`.
 
 | File | Role / key exports |
 |---|---|
-| `src/engine.ts` | Ranking engine shared by CLI and plugin. Fetch/cache chain per source, cardinal transforms, value scoring. Exports `loadRankData`, `computeRankings`, `buildModels`, `rankRole`, `paretoFrontier`, `cardinalMetric`, `roleLambda`, `thinkingPriceFactor`, `CAPABILITY_FILL`, `SUFFIX_LEVELS`, `META_LEVELS`, `THINKING_TOKEN_OVERHEAD`, `parseFindData`, `parseModelPage`, `narrowEndpointRecord`, `buildOpenRouterEnrichment`, `applyOpenRouterData`, `hasEndpointFilters`, `routePassesEndpointFilters`, `modelPassesEndpointFilters`, `endpointFilterDrops`, `applyDesignPercentiles`, `applyWritingScores`, `extractFlight`, `extractJsonArray`, the cache readers/writers, and the `Model`/`RoleDef`/`Ranked`/`RankData`/`OpenRouterEndpointRecord` types. Re-exports `normalizeDesignId` and `parseWritingEvidence` from the benchmark-source registry. |
+| `src/engine.ts` | Ranking engine shared by CLI and plugin. Fetch/cache chain per source, cardinal transforms, value scoring. Exports `loadRankData`, `computeRankings`, `buildModels`, `rankRole`, `paretoFrontier`, `cardinalMetric`, `roleLambda`, `thinkingPriceFactor`, `CAPABILITY_FILL`, `SUFFIX_LEVELS`, `META_LEVELS`, `THINKING_TOKEN_OVERHEAD`, `parseFindData`, `parseModelPage`, `narrowEndpointRecord`, `buildOpenRouterEnrichment`, `applyOpenRouterData`, `hasEndpointFilters`, `routePassesEndpointFilters`, `modelPassesEndpointFilters`, `endpointFilterDrops`, the route-price accessors (`routeInputPrice`, `routeEffectivePrice`, `routeOutputPrice`, `blendOutputPrice`), `applyDesignPercentiles`, `applyWritingScores`, `extractFlight`, `extractJsonArray`, the cache readers/writers, and the `Model`/`RoleDef`/`Ranked`/`RankData`/`OpenRouterEndpointRecord` types. Re-exports `normalizeDesignId` and `parseWritingEvidence` from the benchmark-source registry. |
 | `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/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, 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/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`, 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/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/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). |
 | `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. |
 | `src/agent-architect.ts` | omp's in-process architects: the agent-creation architect (`/create-agent`, `/agents` hub) and the project-profile architect (`/project-roles`). Exports `generateAgentSpec`, `generateProjectProfile`, `parseAgentSpec`, `parseProjectProfile`, `extractJsonObject`, `extractAssistantText`, and the `ArchitectOptions`/`ProjectArchitectOptions` types. Imports `@oh-my-pi/pi-coding-agent` **dynamically** (inside the runner), so the module is importable under plain Node. |
 | `src/benchmark-author.ts` | Benchmark-source authoring for an unknown link: fetch the link, run an in-process architect (`src/prompts/benchmark-source-architect.md`) to propose a declarative source spec, and validate it. Imports `@oh-my-pi/pi-coding-agent` **dynamically** (inside the function). Exports `authorBenchmarkSource`, `parseSourceDeclarationJson`, and the `BenchmarkAuthorOptions` type. |
 | `src/benchmark-discovery.ts` | Judge-backed benchmark relevance for `/create-agent` discovery: one `noul` (yes/no probability) question per catalog candidate, batched into a single judgment through omp's configured `judge` role (TypeSafe jev or its fallback chain). Extension-only (imports `@oh-my-pi/pi-coding-agent` and its `./judgment` subpath — the deeper `./judgment/standalone` path does not resolve under omp's SDK injection). The SDK is imported dynamically so a resolution failure degrades to "no discovery" instead of failing the whole extension load. Exports `judgeBenchmarkRelevance`. |
-| `src/agent-create.ts` | `/create-agent` core: purpose → archetype → validated role → agent `.md`, plus the shared input parser and report formatter both hosts use. Exports `createAgent`, `resolveRole`, `parseCreateAgentInput` (flag form or free text), `parseCreateAgentArgs`, `tokenizeArgs`, `extractBenchmarks`, `extractBenchmarkLinks`, `applyFocusBenchmarks`, `assessFocusMetric`, `belowBarReason`, `focusCoverageOk`, `countMetricCoverage`, `discoverBenchmarks`, `checkWeightMath`, `formatBenchmarks`, `formatArchetypes`, `formatCreateAgentReport`, `CREATE_AGENT_USAGE`, and the request/result types (incl. `FocusMetricAssessment`/`FocusCoverageEntry`/`FocusAssessor`). |
+| `src/agent-create.ts` | `/create-agent` core: purpose → archetype → validated role → agent `.md`, plus the shared input parser and report formatter both hosts use. Exports `createAgent`, `resolveRole`, `parseCreateAgentInput` (flag form or free text), `parseCreateAgentArgs`, `tokenizeArgs`, `extractBenchmarks`, `extractBenchmarkLinks`, `applyFocusBenchmarks`, `assessFocusMetric`, `belowBarReason`, `focusCoverageOk`, `countMetricCoverage`, `quantile` (the repo's one quantile convention — the focus-axis dispersion stats and the usage ledger's per-turn median), `discoverBenchmarks`, `checkWeightMath`, `formatBenchmarks`, `formatArchetypes`, `formatCreateAgentReport`, `CREATE_AGENT_USAGE`, and the request/result types (incl. `FocusMetricAssessment`/`FocusCoverageEntry`/`FocusAssessor`). |
 | `src/agent-remove.ts` | `/remove-agent` core: delete an agent `.md` and its role, plus the shared flag parser and report formatter. Exports `removeAgent`, `parseRemoveAgentArgs`, `formatRemoveAgentReport`, `REMOVE_AGENT_USAGE`, and the request/result types. Refuses shipped default roles. |
 | `src/project-setup.ts` | `/project-roles` core: a discovered `ProjectProfile` → a project-scoped role set (kept shipped roles, dropped ones, new fitted roles) written to the project plugin settings lock file, plus the project agents for the new roles. All-or-nothing (every check — names, metrics, weight math, the `--force` gate, agent-file collisions — before any write), `--dry-run`. Exports `setupProject`, `parseProjectRolesArgs`, `parseRolesSpec`, `applyProfileOverrides`, `formatProjectRolesReport`, `PROJECT_ROLES_USAGE`, and the `ProjectProfile`/`ProposedRole`/`SetupProjectOpts`/`SetupProjectResult` types (the result carries an `archetypes` map). The plan report prints the capability flags each new role will author (`features: <id>=<on>`). Dual-runtime safe (no SDK import); the extension command does the LLM work and calls it. |
 
@@ -50,9 +52,11 @@ the extension's `/refresh-roles`, `/explore-roles` and `/create-agent`.
 
 | File | Role / key exports |
 |---|---|
-| `src/explorer/boot.ts` | Shared explorer launcher: bind/port fallback, lock-file roles, browser open, close. Exports `startExplorer`, `EXPLORER_DEFAULT_PORT`, and the `ExplorerHandle`/`ExplorerBootOpts` types. Used by `/explore-roles`. |
-| `src/explorer/server.ts` | Zero-dependency HTTP surface (static SPA + JSON API). Exports `createExplorerServer` and the `ExplorerOpts` type. Endpoints: `GET /api/bootstrap` (carries `focusAssessments`), `POST /api/rank`, `POST /api/explain`, `POST /api/export`, `POST /api/refresh`. |
-| `src/explorer/explain.ts` | Pure explanation layer: rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets, and the nine-axis focus assessment. Exports `rankRows`, `explainModel`, `inverseCardinal`, `focusMetricsOf`, `focusAssessments`, `METRIC_META`, `metricMeta`, `metricMetaFor`, `weightableMetrics`, and the `RankRow`/`Explanation`/`Contribution`/`Closing`/`MetricMeta` types. |
+| `src/explorer/boot.ts` | Shared explorer launcher: bind/port fallback, lock-file roles, browser open, close. Exports `startExplorer`, `EXPLORER_DEFAULT_PORT`, and the `ExplorerHandle`/`ExplorerBootOpts` types. Used by `/explore-roles`. `ExplorerBootOpts` carries the as-written pool's inputs (`tier`, `allowedProviders`, `reloadAllowedProviders`), the `tokenProfile` fallback, and `usageDir` (the user-level ledger dir; a project scope reads its own `<root>/.omp` ledger). |
+| `src/explorer/server.ts` | Zero-dependency HTTP surface (static SPA + JSON API). Exports `createExplorerServer` and the `ExplorerOpts` type. Endpoints: `GET /api/bootstrap` (carries `focusAssessments`, `poolMode`, `tokenProfile`), `POST /api/scope`, `POST /api/pool` (switch the ranked pool, raw vs as-written), `POST /api/rank` (rows carry the display-only `perTask`), `POST /api/explain` (carries `leaderFlip`/`thinkingLevels`), `POST /api/export`, `POST /api/refresh`. `ExplorerOpts` gains `getPoolInputs()` and the optional `getUsageRows(scope)`/`tokenProfile` seams. |
+| `src/explorer/explain.ts` | Pure explanation layer: rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets, the nine-axis focus assessment, and the display-only per-task price. Exports `rankRows`, `explainModel`, `perTaskPrice`, `inverseCardinal`, `focusMetricsOf`, `focusAssessments`, `METRIC_META`, `metricMeta`, `metricMetaFor`, `weightableMetrics`, and the `RankRow`/`Explanation`/`Contribution`/`Closing`/`MetricMeta`/`PerTaskPrice` types. `rankRows`/`explainModel` take a trailing optional `profile?: TokenProfile \| null`; `RankRow.perTask` and `Explanation.perTask` are `null` when no profile resolves or the model has no usable route price. |
+| `src/explorer/levers.ts` | Pure price-lever readouts (spec #81): the leader-flip threshold and the thinking level's effect on the leader, both computed on the pool they are handed. Exports `leaderFlip`, `thinkingLevelEffect`, and the `LeaderFlip`/`ThinkingLevelRow` types. Reuses the engine's `roleLambda`/`rankRole`/`SUFFIX_LEVELS`/`thinkingPriceFactor` — never re-derives the math. |
+| `src/explorer/pool.ts` | The as-written pool (spec #81): the explorer's dataset filtered exactly as the updater filters it before ranking — the catalog/tier gate (`filterCatalog` + `resolveVariant`) and the allowed-providers whitelist prune (`providerAllowed`). Pure (never mutates its input). Exports `asWrittenPool`, and the `PoolMode`/`PoolInputs` types. |
 
 ### Assets and non-code
 
@@ -116,7 +120,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 +221,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 +241,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

@@ -21,6 +21,15 @@ ref must be green first. `test` runs **exactly** the command the local
 pre-commit hook runs (`.githooks/pre-commit`), and `tests/ci.test.ts` fails when
 the two drift apart — "green locally" and "green in CI" cannot diverge.
 
+The hook scrubs `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` and
+`GIT_OBJECT_DIRECTORY` before running the suite, and `tests/ci.test.ts` scrubs
+the same variables from every child process it spawns. Git exports `GIT_DIR` to
+every hook, and `GIT_DIR` overrides `cwd` — so without the scrub the test file's
+temp-repo `git init`/`config`/`add`/`commit` calls target the **real**
+repository, rewriting its config and moving a branch (issue #89). The test file
+carries the scrub because a test that shells out to git must not depend on its
+caller's environment; the hook carries it as defence in depth.
+
 The Node version comes from `.node-version` at the repo root (the exact local
 toolchain; bumping it is a normal commit). `engines` is deliberately not in
 `package.json`: the plugin executes inside omp's runtime, so an `engines` field
@@ -141,10 +150,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,80 @@
-# Current state (2026-10-08)
+# Current state (2026-10-18)
 
 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-18 measurement (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.
 
+- 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
+  the same two filters the updater applies before ranking — the catalog/tier gate
+  and the allowed-providers whitelist prune — so the leader the user sees is the
+  model the updater will write (the raw pool's leader differed from the config's
+  for 6 of 10 roles). The per-task price is `inputTokens·p_in +
+  outputTokens·p_out·thinkingFactor` over the role's priced route, using the
+  plugin's own recorded per-role usage (the median per-turn counts) or the
+  `tokenProfile` setting; it is **display-only** — the price axis stays `$/M`
+  (issue #32's verdict stands) and the reported `$/M` keeps its billed 3:1 blend.
+  The readouts are the leader-flip threshold (`λ* = min over cheaper challengers
+  X of (q_L − q_X)/(pEff_L − pEff_X)`, `w* = 20λ*/(1+20λ*)`) and the thinking
+  level's effect on the leader. A new append-only, capped, best-effort
+  **usage ledger** (`llm-role-usage.jsonl`, one row per assistant turn) follows
+  the plugin's state dir (`<project>/.omp` in project mode, `agentDir()`
+  otherwise). The ranking numbers are unchanged — the ranking CLI does not apply
+  the pool toggle, and the per-task price never feeds the sort key.
+- Provider display (2026-10-12, spec #77): when the live session model carries a
+  provider pin (a hand-set `providerPin`, or the automatic pin the
+  `providerPinning` capability writes), the plugin keeps the model object's
+  `name` suffixed with the route, so omp's status-line model segment renders
+  e.g. `DeepSeek V4.1 Flash @coreweave/fp8`. The suffix is applied on session
+  start, refreshed on the two fallback events, and re-derived at every
+  `turn_start` — the re-derive is what heals the display after omp silently
+  restores the primary model following a fallback cooldown (no session event is
+  emitted), and it also covers a manual `/model` change with a one-turn lag. An
+  event's selector is trusted only when it names the live session model, so an
+  advisor fallback (the same events, the advisor's model) re-derives from the
+  live model instead of stamping the advisor's pin onto the session.
+  Display-only: the suffix rides the model object's `name`, so attribution,
+  usage recording and model comparison are unaffected. The ranking numbers are
+  unchanged.
+
+- 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 +138,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 +688,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 149/408 (throughput), 148 priced (the
+  2026-10-09 snapshot read 155/408 — 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).
+- Eligible per role: 140 (vision 73, designer 87, 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.807), `smol` DeepSeek-V4.1-Flash (0.706),
+  `slow` Gemini 4 Argon (0.834), `vision` Gemini 4 Argon (0.732),
+  `plan` Muse Spark 1.3 (0.789), `commit` DeepSeek-V4.1-Flash (0.736), `tiny`
+  Mercury 2 (0.797), `task` DeepSeek-V4.1-Flash (0.750), `advisor`
+  Muse Spark 1.3 (0.785), `designer` DeepSeek-V4.1-Flash (0.772).
 - 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,