omp-llm-role 1.1.0 → 1.3.0

package/docs/dev/scoring.md

@@ -101,10 +101,13 @@ cache reads; the knob prices that, opt-in, without touching any shipped role.
 - `endpointFilteredModel(model, filters, cacheHitRate)` recomputes the blend when
   the role declares endpoint filters **or** a non-zero hit rate; the hit rate
   composes with the filters (filter the pool first, then cache-price it);
-- `roleEffectivePrice`/`routeEffectivePrice` is the single per-route accessor the
-  blend, the pinned-route path and `roleMetricValue` share; a pinned role prices
-  its route's cache-adjusted billed price, and `maxPriceUsdPerM` caps the
-  thinking-adjusted `priceEff` (the same cap as the blend path);
+- the route-price accessors — `routeInputPrice` (the cache-adjusted input term),
+  `routeEffectivePrice` (the billed 3:1 blend, which reuses the input accessor),
+  `routeOutputPrice`/`blendOutputPrice` (the inverse blend) — are what the
+  blend, the pinned-route path, `roleMetricValue` and the explorer's per-task
+  price share; a pinned role prices its route's cache-adjusted billed price, and
+  `maxPriceUsdPerM` caps the thinking-adjusted `priceEff` (the same cap as the
+  blend path);
 - `explainModel` mirrors all of it, carries `role.cacheHitRate`, and reports the
   cache-adjusted `cost.billedPrice`; the SPA cost line appends `· cache <rate>`
   when the rate is set;
@@ -137,12 +140,108 @@ route instead of the `1/price²` blend:
 - a model with **no matching route** is ineligible for that role
   (`providerPinDrops` → `Decision.pinBlocked`, rendered `; pin-blocked: …`);
   `explainModel` reports "no route matches the role's provider pin".
-- an **unpinned** role ignores `routes` entirely — the blend path is unchanged.
+- an **unpinned** role ignores `routes` entirely — the blend path is unchanged —
+  **unless** it sets the soft `preferOwnProvider` policy (the `providerPinning`
+  capability), which prices it on its **best route** (the max-value-for-money
+  candidate route; see *Route ordering* and *Capability presets*).
 
 The pin is a cost-and-throughput posture, not a quality edit: it moves the price
 axis to the route's billed price and the throughput axis to the route's p50,
 while every other weighted metric stays the model's own.
 
+### Route ordering (the value-for-money score)
+
+`rankedRoutes(model, def)` (`src/engine.ts`) is the one function that orders a
+model's candidate routes; `bestRoute` is `rankedRoutes[0]`, and `roleRoute` (the
+route `rankRole` prices the model on) and the updater's auto-pin both read it, so
+the priced route, the written pin and the fallback chain move together.
+
+- **Candidates.** A route is a candidate when it is non-degraded (`status === 0`),
+  passes `routePassesEndpointFilters(route, def.filters)`, carries a usable billed
+  price, and (when `filters.maxPriceUsdPerM > 0`) a thinking-adjusted price at or
+  below the cap. The allowed-providers whitelist is applied upstream by pruning
+  `m.routes` (see *Whitelist-aware route selection*).
+- **The score.** Each candidate is scored
+  `vfm = wT·tNorm − wP·pNorm`, where `tNorm`/`pNorm` are the route's p50
+  throughput and cache-adjusted billed price **min/max-normalized over the
+  candidate set** (`tNorm = (tput − tMin)/(tMax − tMin)`, `pNorm = (priceEff −
+  pMin)/(pMax − pMin)`; a zero span normalizes to 0), and `wT =
+  wTput/(wPrice+wTput)`, `wP = wPrice/(wPrice+wTput)`. Sort desc; ties break by
+  `providerSlug` then `id`, so a re-run is deterministic. A route with no p50 uses
+  the model's blended throughput (an absent p50 is unknown, not slow).
+- **The soft floor.** `filters.preferredMinThroughput` (tok/s; `0`/absent = off)
+  is a **preference, not a gate**: routes at or above the floor sort before
+  routes below it, and the score orders within each band. A below-floor route is
+  **never dropped** — it stays a last-resort candidate.
+- **`routeValue` is deleted.** The old `q(route p50) − λ·route price` route sort
+  key is gone; the score above is the only route basis. (The model-level
+  `value = q − λ·priceEff` is unchanged — see *`λ` and `value`*.)
+
+### Whitelist-aware route selection
+
+The updater narrows every model's route pool to the account's
+**allowed-providers privacy whitelist** before ranking (data-sources.md,
+*OpenRouter — allowed-providers whitelist*; architecture.md, *Data flow*). The
+prune is the single change point — `roleRoute`, `bestRoute`, `rankedRoutes` and
+`endpointFilteredModel` all read `m.routes` — so every route consumer above is
+whitelist-aware: a hard `providerPin` on a blocked provider matches no route and
+drops the model (`providerPinDrops`), the soft `preferOwnProvider` basis prices
+each model on its best **allowed** route, the endpoint-filtered blend is computed
+over the allowed pool, and the fallback chains carry only allowed routes. A
+`null` whitelist (no whitelist set, harvest failed) leaves every pool untouched,
+so the ranking is byte-identical to today. The whitelist is a route-selection
+filter, not a re-pricing: the role-independent `1/price²` blend (`m.price`/
+`m.throughput`) is left as the account-agnostic expected value, and a model with
+no allowed route keeps that blend (the soft basis never drops a model).
+
+## Price levers (the explorer's readouts)
+
+Two readouts make the price posture visible (spec #81). Both are pure
+(`src/explorer/levers.ts`), computed on the pool the explorer is viewing, and
+reuse the engine's own `roleLambda`/`rankRole`/`SUFFIX_LEVELS`/
+`thinkingPriceFactor` — never a re-derivation.
+
+### The leader-flip threshold
+
+The price weight at which a **cheaper** challenger overtakes the value leader.
+Let `L = rankRole(def, models)[0]` (the value leader). For every challenger `X`
+with `pEff_X < pEff_L` (strictly cheaper), the flip λ is
+`(q_L − q_X)/(pEff_L − pEff_X)`; the threshold is the minimum over those
+challengers:
+
+```
+λ* = min over cheaper challengers X of (q_L − q_X)/(pEff_L − pEff_X)
+w* = 20·λ* / (1 + 20·λ*)
+```
+
+`w*` is the inverse of `roleLambda`'s `λ = w/(1−w)/20` (`P_REF_USD = 20`). The
+readout reports the role's current `wPrice`, the flip `w*`, the distance
+`w* − wPrice`, and the challenger that would take over. **No cheaper challenger
+⇒ `null`** — the readout is absent, never invented. The degenerate case (the
+value leader is also the quality leader, where the naive
+`(q_QL − q_VL)/(p_QL − p_VL)` is `0/0`) is handled by this same min formula: it
+is *undefined*, not zero.
+
+**Exactness.** The threshold is exact when the role's price basis is
+weight-independent — the `1/price²` blend, or a hard `providerPin`. Under the
+soft `preferOwnProvider` basis the route choice itself moves with the price
+weight, so the threshold is a **first-order estimate**: measured on `smol`,
+moving `w` from 0.45 to 0.9586 moves the leader's route `coreweave/fp8 →
+decart/fp4`, so the flip is approximate there.
+
+### The thinking level's effect
+
+`thinkingLevelEffect(def, models)` re-ranks the role at each thinking level and
+reports the leader per level, with the level's price factor
+`thinkingPriceFactor(level) = (1 + 3·0.25 + THINKING_TOKEN_OVERHEAD[level]) /
+(1 + 3·0.25)`. It is **inert for a bare role** (no thinking level) — the readout
+is `null`. The factor is a **price-sensitivity amplifier, not a hidden cost**: it
+is multiplicative on `priceEff`, so it penalizes expensive models more in
+absolute λ-units — which is why `auto` favours the cheap model. On the user's
+live `default` def: `off` → Gemini 4 Argon $2.99, `auto` → Gemini 4 Argon $5.55,
+`high` → DeepSeek-V4.1-Flash $0.17. The readout shows this effect; it never
+frames the level as a cost to remove.
+
 ## Capability presets (feature flags)
 
 One named flag per opt-in capability (`features.<id>` global,
@@ -164,44 +263,55 @@ no flags the resolved roles are byte-identical to `DEFAULT_ROLES`. The effective
 def is what `rankRole`/`explainModel` see; the authored def (flags + explicit
 keys) is what the explorer edits and exports.
 
-What each recommendation does to the ranking math (grounded on the 2026-10-07
-cache, `default` role, 142 eligible):
+What each recommendation does to the ranking math (grounded on the 2026-10-09
+cache, `default` role, 146 eligible; the `providerPinning` bullet is re-measured
+on the 2026-10-11 cache):
 
 - **`endpointCeilings`** (`filters.tools: true`, `filters.minOutputTokens:
   16384`) drops tool-incapable routes and routes whose output ceiling is below
-  16 384 tokens from the priced pool (see *Endpoint filters*): 142 → 132
-  eligible, leader unchanged (`deepseek-v4.1-flash`, 0.579 $/M). 16 384 is the
+  16 384 tokens from the priced pool (see *Endpoint filters*): 146 → 135
+  eligible, leader unchanged (`deepseek-v4.1-flash`, 0.37 $/M). 16 384 is the
   video's own threshold (19 endpoints cap output at or below it).
 - **`cachePricing`** (`cacheHitRate: 0.5`) reprices the role on a cache-heavy
-  loop's invoice (see *Cache-read pricing*): 142 eligible, leader unchanged, its
-  `priceEff` 0.579 → 0.508 (−12 %). 0.5 is the low end of the measured
+  loop's invoice (see *Cache-read pricing*): 146 eligible, leader unchanged, its
+  `priceEff` 0.3732 → 0.3522 (−5.6 %). 0.5 is the low end of the measured
   third-party range (51–69 %), so the preset never over-credits a cache.
-- **`providerPinning`** (`preferOwnProvider: true`) prices a model on its own
-  lab's route where one exists, falling back to the default `1/price²` blend
-  otherwise. It is a **per-model policy, not a scalar** — the sensible pin
-  differs per model, so the bundle carries a policy field evaluated against the
-  model's own routes at rank time, not a slug baked into the lock file. The lab
-  match is a **slug prefix on the model's `orgId`** (exact, or `orgId` + `/`),
-  with the display `org` as a second try; there is no alias map in v1. Measured
-  coverage: 51 of the 149 routed models resolve to one of their own lab's routes
-  (33 on an exact slug match, 17 on an `orgId` prefix, 1 on the display-`org`
-  fallback), and 10 of 25 orgs match for no model (`zai-org` —
-  its lab route slug is `z-ai` — `google`, `qwen`, `inclusionai`, `nvidia`,
-  `microsoft`, `bytedance`, `thinking-machines`, `ibm`,
-  `gryphe`). An unmatched model keeps the blend, so the capability
-  **under-delivers rather than mis-pins**, and it **never changes eligibility**
-  (unlike the hard `providerPin`, which drops a model with no matching route).
-  The resolved route is the same basis a hard pin uses, so the preference moves
-  the **throughput** axis as well as the billed price — a role that routes to the
-  lab's endpoint gets that endpoint's p50 tok/s, not the blend's. Measured on the
-  2026-10-07 cache, the `default` leader's `priceEff` rises 0.579 → 0.975 while
-  its `value` *rises* 0.8132 → 0.8172, because its own lab route's p50 throughput
-  is higher than the blend's, so `q` moves too. That is deliberate (the pin path
-  has always priced and measured on the pinned route); a role that wants the
-  blend's throughput should leave the flag off.
+- **`providerPinning`** (`{ preferOwnProvider: true, filters: {
+  preferredMinThroughput: 50 } }`) prices a model on its **best route** — the
+  max-value-for-money candidate route (see *Route ordering*: the `vfm` score
+  desc, with the soft 50 tok/s floor sorting below-floor routes last) among the
+  routes that pass the role's endpoint filters and the account's
+  allowed-providers whitelist (see *Whitelist-aware route selection*) — falling
+  back to
+  the default `1/price²` blend only when the model has no candidate route. It is
+  a **per-model policy, not a scalar** — the sensible pin differs per model, so
+  the bundle carries a policy field evaluated against the model's own routes at
+  rank time, not a slug baked into the lock file. `bestRoute` (`src/engine.ts`)
+  is `rankedRoutes(model, def)[0]` (see *Route ordering* for the candidate
+  criteria and the score). The basis is **soft**: a model with no
+  candidate route keeps the blend and is never dropped, so the capability
+  **never changes eligibility** (unlike the hard `providerPin`, which drops a
+  model with no matching route). The `maxPriceUsdPerM` gate is **basis-independent**:
+  with no hard pin it caps the model's own blend price, not the soft route's, so
+  the flag can neither add nor drop a model; the candidate-route cap filter only
+  keeps the written pin at or below the cap. Measured coverage on the 2026-10-11 cache: all
+  144 routed models have a candidate route (the old own-lab slug-prefix rule
+  matched only 51 of 149), so the capability covers the whole routed field. The
+  resolved route is the same basis a hard pin uses, so the preference moves the
+  **throughput** axis as well as the billed price — a role that routes to the
+  best endpoint gets that endpoint's p50 tok/s, not the blend's. Measured on the
+  2026-10-11 cache (`rankRole` over the full model set), the `default` leader is
+  `deepseek-v4.1-flash` either way: the blend prices it at `priceEff` 0.2317 /
+  `value` 0.8056 / `q` 0.8069, while the soft best-route basis prices it at
+  `priceEff` 0.1187 / `value` 0.8092 / `q` 0.8099 on its best route `decart/fp4`
+  ($0.0639 billed, 72 tok/s). The soft route is cheaper than the blend, so
+  `priceEff` falls and `value` rises; `q` moves too because the route's p50
+  throughput replaces the blend's. That is deliberate (the pin path has always
+  priced and measured on the pinned route); a role that wants the blend's
+  throughput should leave the flag off.
 - **`costCap`** (`filters.maxPriceUsdPerM: 10`) drops the priciest tail of the
-  eligible pool: 142 → 135 (the top ≈5 %), leader unchanged. The pool's p90 is
-  7.8 and p95 8.9 $/M, and every role leader sits at 0.58–0.85 $/M, so the
+  eligible pool: 146 → 137 (the top ≈6 %), leader unchanged. The pool's p90 is
+  7.8 and p95 11.1 $/M, and every role leader sits at 0.20–3.71 $/M, so the
   preset never excludes today's leader.
 
 **Interaction with the switch hysteresis.** `switchMargin`/`priceSwitchFraction`
@@ -242,7 +352,10 @@ A model ranks for a role only when:
 - `minContextTokens` filters the **endpoint** `context_length`, not the
   model-level `context`;
 - `maxPriceUsdPerM` caps the thinking-adjusted `priceEff` (the price the role
-  actually pays), not the bare billed blend;
+  actually pays), not the bare billed blend. For a **pinned** role that is the
+  pin route's price; for a soft `preferOwnProvider` role it is the model's own
+  blend price (basis-independent, so the flag cannot change eligibility), while
+  the candidate-route filter keeps the auto-pin at or below the cap;
 - a role that declares `tools`/`minContextTokens`/`minOutputTokens` is **priced**
   on the surviving pool: `endpointFilteredModel` recomputes `price`/`throughput`
   as the `1/price²` blend over the routes that clear the filters
@@ -252,8 +365,9 @@ A model ranks for a role only when:
 
 `endpointFilterDrops(def, models)` lists the ranking ids the gate removed (they
 pass every other eligibility gate but have no capable route) for the decision
-log. `resolveSettings` validates all four; no shipped role sets an endpoint
-filter. Filters apply before ranking eligibility so percentile norms stay on the
+log. `resolveSettings` validates the four endpoint-filter keys plus the soft
+`filters.preferredMinThroughput`; no shipped role sets an endpoint filter.
+Filters apply before ranking eligibility so percentile norms stay on the
 unfiltered pool.
 
 ## Pareto frontier (★)

package/docs/dev/testing.md

@@ -52,28 +52,45 @@ passing.
     equal sets → no-filter; empty → unavailable; a keyed id absent from public →
     no-filter; aliases collapse; two parallel GETs, one authenticated; never
     throws.
-11. **Endpoint ceilings** (`endpoint-ceilings.test.ts`) — the narrower reads
+11. **Allowed-providers whitelist** (`allowed-providers.test.ts`,
+    `whitelist.test.ts`) — `fetchAllowedProviders` parses the 404 body's
+    "permits only:" list into a set and returns `null` for a 200, a 404 without
+    the clause, or a transport throw, with the canary request shape (POST,
+    bearer, `provider.only`, `max_tokens: 1`); the updater prunes every model's
+    route pool to allowed providers before ranking, so a blocked best route
+    falls to the next-best allowed route as the auto-pin, the chain carries only
+    allowed routes, a bare entry matches a tiered slug by prefix, the notify line
+    reports the active whitelist and the pruned count (or "no whitelist"), and a
+    `null` whitelist reproduces today's output byte-for-byte.
+12. **Endpoint ceilings** (`endpoint-ceilings.test.ts`) — the narrower reads
     context/output/tools, a missing field is null; a failing route drops, a null
     field is kept; a model with no capable route is ineligible; a filtered role
     is priced on the surviving pool; `maxPriceUsdPerM` caps the thinking-adjusted
     price.
-12. **Route pricing (provider pin)** (`route-pricing.test.ts`) — a pinned role
+13. **Route pricing (provider pin)** (`route-pricing.test.ts`) — a pinned role
     prices the matching route, not the blend; a tiered pin matches verbatim;
     `maxPriceUsdPerM` caps the route price; throughput is the route p50 with a
     blend fallback; no matching route → ineligible; the `@<slug>` selector and
-    chain carry the pin; a pin matching no route leaves the role unchanged.
-13. **Thinking price** (`thinking-price.test.ts`) — bare/off unadjusted; a level
+    chain carry the pin; a pin matching no route leaves the role unchanged. The
+    route-ordering score (spec #71): `rankedRoutes` orders by the value-for-money
+    score `vfm = wT·tNorm − wP·pNorm` (a throughput-heavy role picks a faster
+    route than a price-heavy role); the soft `filters.preferredMinThroughput`
+    floor sorts a below-floor route last **without dropping it**; a route with no
+    p50 uses the model's blended throughput (for both the score and the floor
+    check); equal scores break by `providerSlug` then `id`; `explainModel`'s
+    `autoPin` is the score-max route.
+14. **Thinking price** (`thinking-price.test.ts`) — bare/off unadjusted; a level
     scales only thinking-capable models; the frontier uses the effective price;
     `resolveSettings` validates thinking and rejects the legacy `suffixes` map;
     catalog `thinking[]` wins over the OR flag; meta levels never gate.
-14. **OpenRouter blend** (`openrouter-blend.test.ts`) — price/throughput are the
+15. **OpenRouter blend** (`openrouter-blend.test.ts`) — price/throughput are the
     `1/price²`-weighted means over the page routes; flex/priority/degraded/free/
     `:batch` stay out; throughput renormalizes; the find-row fallback; the weight
     follows the input price.
-15. **Writing metric** (`writing.test.ts`) — `parseWritingEvidence` keys finite
+16. **Writing metric** (`writing.test.ts`) — `parseWritingEvidence` keys finite
     scores and rejects junk; `applyWritingScores` fills uncovered models; a
     covered model ranks above an uncovered one.
-16. **Benchmark sources** (`benchmark-sources.test.ts`) — `resolveBenchmarkSource`
+17. **Benchmark sources** (`benchmark-sources.test.ts`) — `resolveBenchmarkSource`
     maps an llm-stats benchmark page, a bare id, the writing leaderboard and a
     Design Arena link, `null` for an unknown host; `normalizeMetricKey` is
     dot-free; `parseBenchmarkPayload` reads the llm-stats `entries[]` and writing
@@ -91,7 +108,7 @@ passing.
     fields, `scoreMax`, join) and a metric colliding with a shipped key is
     rejected; `dryRunDeclaration` reports coverage/leader and rejects a zero-join;
     `extractBenchmarkLinks` pulls URLs from prose.
-17. **Agent creation** (`create-agent.test.ts`) — a purpose fits the expected
+18. **Agent creation** (`create-agent.test.ts`) — a purpose fits the expected
     archetype; a `--weights` set violating Σ(non-price) = 1 − w_price is refused;
     an existing agent file without `--force` is refused and writes no role;
     `--dry-run` writes neither file; an architect `spec` replaces the
@@ -99,46 +116,58 @@ passing.
     share, is a no-op for the archetype's own specialist set, and keeps both
     invariants; the nine-axis gate (the maintenance, provenance and cross-source
     axes are annotations, never a drop).
-18. **Agent removal** (`remove-agent.test.ts`) — the role's lock-file keys and the
+19. **Agent removal** (`remove-agent.test.ts`) — the role's lock-file keys and the
     agent file are deleted (backup written); a shipped default role, a reserved
     name and an invalid name are refused; nothing-to-remove errors; `--dry-run`
     writes nothing; the updater drops `modelRoles.<n>` and the plugin-managed
     `task.disabledAgents` entry.
-19. **Agent pins / disable** (`agent-pins.test.ts`, `agent-disable.test.ts`) —
+20. **Agent pins / disable** (`agent-pins.test.ts`, `agent-disable.test.ts`) —
     `parseAgentPin` takes the first `@role`; `discoverAgentPins` scans the three
     scopes, most specific wins; the sync is not day-gated; an unrelated entry
     keeps its position; an unknown role is never added.
-20. **Role enable / lock** (`role-enable.test.ts`, `role-lock.test.ts`) —
+21. **Role enable / lock** (`role-enable.test.ts`, `role-lock.test.ts`) —
     disabling drops the role from the resolved set and its `modelRoles` line; a
     locked role is not switched and its chain survives the prune; unlocking
     restores the switch.
-21. **Settings** (`settings.test.ts`, `settings-schema.test.ts`) — opt-in roles;
+22. **Settings** (`settings.test.ts`, `settings-schema.test.ts`) — opt-in roles;
     `priceSwitchFraction` range; flat/nested merge; `required` as string or
     array; an external metric key is weightable, a dotted one rejected;
-    `package.json` `omp.settings` deep-equals `deriveSettingsSchema()`.
-22. **Explorer** (`explorer.test.ts`, `explorer-scopes.test.ts`) — rank deltas;
+    `package.json` `omp.settings` deep-equals `deriveSettingsSchema()`. The
+    `providerPinning` preset sets `preferOwnProvider: true` +
+    `filters.preferredMinThroughput: 50` (the registry row and the expanded def
+    agree), an explicit `filters.preferredMinThroughput` beats the preset, and
+    the schema carries the `roles.<role>.filters.preferredMinThroughput` row
+    (number, min 0, default 0). The `tokenProfile` setting (spec #81) defaults to
+    `null`, accepts a record with finite `inputTokens`/`outputTokens` ≥ 0, and
+    rejects a non-record or a negative/non-finite field; the schema carries the
+    `tokenProfile.inputTokens`/`tokenProfile.outputTokens` rows (number, min 0).
+23. **Explorer** (`explorer.test.ts`, `explorer-scopes.test.ts`) — rank deltas;
     contributions sum to `q`; `inverseCardinal` round-trips; Export preserves
     siblings and normalizes nested roles; the scope switcher; the availability
-    overlay.
-23. **Project scope** (`project-updater.test.ts`, `project-setup.test.ts`,
+    overlay. The per-task price (spec #81): `rankRows`/`explainModel` fill
+    `perTask` from a supplied profile and leave it `null` without one; the
+    `POST /api/pool` toggle returns the gated/pruned dataset in `as-written` mode
+    and the full one in `raw`; the bootstrap payload carries `poolMode` and
+    `tokenProfile`; the explain response carries `leaderFlip`/`thinkingLevels`.
+24. **Project scope** (`project-updater.test.ts`, `project-setup.test.ts`,
     `project-roles-command.test.ts`) — project mode scopes config/state/history/
     lock to `<cwd>/.omp`; the day gate is per scope; the registry write;
     `setupProject` add/drop/keep, `--dry-run`, `--force`; the command is
     registered.
-24. **Session model** (`session-model.test.ts`) — the hook fires only after a real
+25. **Session model** (`session-model.test.ts`) — the hook fires only after a real
     write on a real `default` change; a dry run and a kept default skip it; a
     throwing hook is contained.
-25. **Docs** (`docs.test.ts`) — every relative markdown link resolves; no
+26. **Docs** (`docs.test.ts`) — every relative markdown link resolves; no
     reference to a moved doc; the CHANGELOG shape; `package.json` `files` entries
     exist; the README has no dev-only headings.
-26. **Architect provenance** (`architect-provenance.test.ts`) — the vendored
+27. **Architect provenance** (`architect-provenance.test.ts`) — the vendored
     prompt header matches `ARCHITECT_PROMPT_VERSION` and the version named in
     [`agent-authoring.md`](agent-authoring.md).
-27. **Architect retry** (`agent-architect.test.ts`) — a malformed architect
+28. **Architect retry** (`agent-architect.test.ts`) — a malformed architect
     response is retried once and the parsed spec returned; an always-malformed
     run throws carrying the raw output; a `run()` failure propagates with no
     retry.
-28. **Error reporting** (`error-report.test.ts`) — `reportUnexpectedError`
+29. **Error reporting** (`error-report.test.ts`) — `reportUnexpectedError`
     through its one entry point with fully injected deps: `off` → no fetch, no
     ledger write, `action: "off"`; `auto` + token → exactly one create whose body
     carries the fingerprint marker, plugin version, runtime, platform, label and
@@ -166,17 +195,64 @@ passing.
     aborts under one label differ; the in-process guard; and a ledger that
     tolerates junk and truncates a pathological stack — including a multi-byte
     one — to the 64 KB **byte** budget.
-29. **CI/CD** (`ci.test.ts`) — the workflow parses and declares both jobs with
+30. **CI/CD** (`ci.test.ts`) — the workflow parses and declares both jobs with
     `release` needing `test`; the `test` job's command is identical to the
     pre-commit hook's; the tag trigger covers every CHANGELOG tag link and the
     package version; `.node-version` is the file the workflow reads; the release
-    job declares `id-token: write` and references no npm token; the four
-    lockstep version fields agree; no tracked file lives under `cache/`; and
+    job declares `id-token: write` and references no npm token; the release job
+    runs the `notes` guard before `npm publish` and both steps name the same
+    notes file; the four lockstep version fields agree; no tracked file lives
+    under `cache/`; and
     `scripts/release.ts` against fixture repos — `due`'s exit codes, `notes`'s
     five refusals and its exact section body, `cut --dry-run` writing nothing,
     and `cut` bumping the four fields, cutting the changelog, committing and
     tagging while refusing a dirty tree, an existing tag, an empty
     `## [Unreleased]` and a HEAD that is not `origin/main`.
+31. **Auto-pin** (`auto-pin.test.ts`) — the selector gains the best route's
+    `@<slug>`; the chain carries every gate-passing route of the primary (all but
+    the pinned best) then of each fallback model, in score order (the `vfm` route
+    score desc, spec #71), deduped by
+    provider slug; a degraded / over-`maxPriceUsdPerM` / endpoint-filter-failing /
+    whitelist-blocked route is excluded; the manual pin wins and the no-pin path
+    is bare; a re-run is idempotent and a pin change prunes the old key.
+32. **Provider display** (`provider-display.test.ts`,
+    `provider-display-wiring.test.ts`) — `providerPinOf` reads the single
+    `openRouterRouting.only[0]` (else `vercelGatewayRouting`), preferring
+    OpenRouter, and returns null for a missing/empty/multi-entry block or a
+    non-string entry; `providerPinOfSelector` parses the trailing `@<slug>` with
+    and without a thinking suffix and returns null without one;
+    `withProviderSuffix` appends, strips a previous suffix, is idempotent, and
+    returns the base name for a null pin; `applyProviderDisplay` mutates a
+    record's `name` and no-ops on a non-record or a non-string name. The wiring
+    (a fake `pi`/`ctx` recording handlers) suffixes the live model on
+    `session_start`, applies the pin parsed from `event.to` on
+    `retry_fallback_applied` (falling back to the live model's routing block),
+    applies the pin from `event.model` on `retry_fallback_succeeded`, re-derives
+    from the live model on `turn_start` (the silent-restore case), strips when
+    neither source carries a pin, never calls `pi.setModel`, and contains a
+    throwing live-model read.
+33. **Usage ledger** (`usage-ledger.test.ts`, `usage-ledger-wiring.test.ts`) —
+    `appendUsageRow` writes one row with the expected fields; `readUsageRows`
+    degrades to `[]` on a missing/malformed file and skips an unparseable or
+    wrongly-shaped line; the cap holds (the newest `USAGE_LEDGER_CAP` rows
+    survive a compaction); `roleTokenProfile` is the role's median per-turn
+    counts (or `null` with no rows) and `resolveTokenProfile` prefers the
+    recorded usage over the setting. The wiring (a fake `pi`/`ctx` with a
+    `sessionManager.getBranch()`) records one row per assistant turn on
+    `turn_end` and `session_shutdown`, dedupes by `ts|model` so the two hooks
+    cannot double-record, writes into `resolveProjectDir() ?? agentDir()`, and
+    contains a throwing branch read.
+34. **Explorer price levers** (`explorer-levers.test.ts`) — `leaderFlip` returns
+    the min-λ threshold over the strictly cheaper challengers, the current
+    `wPrice`, the distance and the challenger; `null` when no cheaper challenger
+    exists; the degenerate case (value leader = quality leader) is handled by the
+    same min formula, not `0/0`. `thinkingLevelEffect` returns one row per level
+    with the engine's own factor and the leader at that level, and `null` for a
+    bare role.
+35. **As-written pool** (`explorer-pool.test.ts`) — `asWrittenPool` applies the
+    catalog/tier gate (`resolveVariant`) and the allowed-providers prune
+    (`providerAllowed`), leaves the routes untouched on a `null` whitelist,
+    yields an empty pool on `tier: "none"`, and never mutates its input.
 
 ## Live checks
 
@@ -197,6 +273,18 @@ passing.
   derived metadata.
 - **Agent removal** — `/remove-agent --name <n>` in a session deletes both
   artifacts and the updater pass removes the config entries.
+- **Explorer pool / per-task / levers** — `/explore-roles` in a session with a
+  recorded usage ledger: confirm the header's pool toggle switches the table
+  between the raw and as-written pools (the model count and the leader change),
+  the `$/task` column renders a value (or `—` with no profile), and the explain
+  panel shows the per-task breakdown and the **Price levers** section (the
+  leader-flip line and the per-level leader table). Verify in headless Chromium
+  (the SPA is not unit-tested).
+- **Usage ledger** — run a real omp turn, then confirm `llm-role-usage.jsonl`
+  gained one row per assistant turn (the model, the role, the provider, the
+  token counts, the cost) in the plugin's state dir (`<project>/.omp` in project
+  mode, `agentDir()` otherwise), and that the explorer's `$/task` column then
+  fills for that role. A session with no completed turn writes no rows.
 - **CI/CD** — push a branch and open a PR (or push to `main`) and `gh run watch`
   the `test` job green; push a tag that disagrees with the package version and
   confirm the `release` job fails in the `notes` guard *before* any publish;

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

@@ -134,6 +134,73 @@ gating — that this plugin never reads (zero occurrences in `src/`, `web/`,
 `tests/`). The plugin's `features.<id>` keys are plugin settings, not omp
 feature flags; do not merge the two.
 
+**`tokenProfile` (spec #81).** A global setting (`tokenProfile.inputTokens` /
+`tokenProfile.outputTokens`, flat dotted keys like the rest) — the per-task
+token profile the explorer's `$/task` column falls back to when a role has no
+recorded usage. `null` (the default) = unset, and the column reads `—`. It is
+validated to `null` or a record whose two fields are finite numbers ≥ 0
+(`tokenProfile: must be null or an object with inputTokens/outputTokens` /
+`tokenProfile.<key>: must be a number >= 0`). It is **display-only**: it never
+feeds the ranking, the reported `$/M` price, or any write. The recorded usage
+takes precedence over it (`resolveTokenProfile`), so once a role has ledger rows
+the setting is ignored for that role.
+
+## The provider-pin auto-configuration (spec #58)
+
+When a role's **expanded** def sets `preferOwnProvider: true` (the
+`providerPinning` capability's recommended bundle) and carries **no** manual
+`providerPin`, the updater binds the role's requests to the chosen model's best
+route by writing that route's provider slug as the selector's `@<slug>` suffix:
+
+```
+openrouter/<id>@<slug>:<level>
+```
+
+omp's `splitUpstreamRouting` parses the trailing `@<slug>` and applies
+`compat.openRouterRouting = { only: [slug] }`, so the price the ranking assumed
+is the price the request pays. The slug is `bestRoute(chosenModel, def)`'s
+`providerSlug` — the max-value-for-money candidate route (see scoring.md,
+*Route ordering*). The pin is re-derived on every run, so it follows the ranking when the
+chosen model changes. A manual `roles.<role>.providerPin` **wins** over the
+automatic choice and stays a **hard** gate (a model with no matching route is
+ineligible); clearing it resumes the automatic choice.
+
+**Chain shape.** The primary's chain key is the selector minus the trailing
+`:level` — so it **includes** the pin (`openrouter/<id>@<slug>`). Its values, in
+order:
+
+1. the same model on **every** gate-passing route except the pinned best, in
+   score order (the `vfm` route score desc — see scoring.md, *Route ordering*),
+2. then, for each of the `fallbackChainDepth` fallback models, that model on
+   **every** gate-passing route, in score order.
+
+Length = `(R_primary − 1) + Σ R_fallback`, where `R` is the number of distinct
+gate-passing provider slugs for that model — data-driven, not a fixed cap.
+Entries dedup by chain value, so two routes sharing a provider slug collapse to
+one. Every entry carries the same `@<slug>` suffix (and the role's thinking level
+where the target advertises it). A model with no gate-passing route contributes
+nothing. The gates are the engine's `rankedRoutes` set: non-degraded
+(`status === 0`), the endpoint capability filters (`tools` / `minContextTokens` /
+`minOutputTokens`), a usable billed price, and the `maxPriceUsdPerM` cap
+(thinking-adjusted). The soft `filters.preferredMinThroughput` floor is a
+**preference, not a gate** — it sorts below-floor routes last but never drops
+them, so a below-floor route still appears in the chain. The allowed-providers
+whitelist is not a `rankedRoutes` filter: the updater prunes each model's route
+pool to allowed providers before ranking, which is what makes `rankedRoutes`
+whitelist-aware. The probe walk target is unchanged (`1 + fallbackChainDepth` —
+it counts models, not routes).
+
+**Prune on a pin change.** Because the chain key includes the pin, a pin change
+changes the key; the updater's chain prune (`state.pluginWrittenChainKeys`) drops
+the old key so a stale pinned chain does not linger.
+
+**No-ops.** The auto-pin writes nothing when: the capability is off
+(`preferOwnProvider` not `true`); a manual `providerPin` is set; the role is
+locked or disabled; the selector is not an OpenRouter selector; the model has no
+route data; no route passes the role's endpoint filters; or the best route has no
+usable billed price. With the capability off the written config is byte-identical
+to before.
+
 ## State, history, lock
 
 All under the agent dir (`agentDir()` in `src/state.ts`), next to the config
@@ -153,6 +220,7 @@ settings entry the global behavior is unchanged.
 |---|---|---|
 | `llm-role-state.json` | `{ lastRunDay, managedRoles, roleLastSelector, pluginWrittenChainKeys, previousModelRoles, managedDisabledAgents }` | day gate, managed-role set, last selectors, plugin-owned chain keys, pre-write `modelRoles` snapshot, **managed `task.disabledAgents` names** |
 | `llm-role-history.jsonl` | one JSON row per completed run: `{ ts, trigger, keyMeta{isFreeTier, limitRemaining, creditsRemaining}, decisions[] }` | append-only decision log |
+| `llm-role-usage.jsonl` | one JSON row per assistant turn: `{ ts, role, model, provider, input, output, cacheRead, cacheWrite, cost }` | the per-role usage ledger (spec #81) the explorer's per-task price resolves its token profile from |
 | `llm-role-projects.json` | `{ projects: [{ root, lastUsed }] }` | the plugin's memory of the projects where `/project-roles` was used (the explorer's scope list) |
 | `.llm-role-refresh.lock` | `O_EXCL` create, holds `"<pid> <iso>"` | serializes concurrent session starts; stale (> 60 s) locks are unlinked and retried once |
 | `llm-role-error-reports.json` | `{ reports: [{ fingerprint, label, title, firstSeen, lastSeen, createdDay?, offeredDay?, count, action, issueNumber?, issueUrl? }], dayCount: { day, count } }` | what the opt-in `errorReporting` path filed, offered or suppressed |
@@ -185,6 +253,24 @@ settings entry the global behavior is unchanged.
   that feeds the 3-creations-per-day cap. Nothing is written when
   `errorReporting` is `off`.
 
+- `llm-role-usage.jsonl` is the per-role usage ledger (spec #81,
+  `src/usage-ledger.ts`). Unlike the two ledgers above it is **not** global: it
+  follows the plugin's state location — `<cwd>/.omp` in project mode,
+  `agentDir()` otherwise — so a project's usage stays separate from the
+  user-level profile. The extension records one row per assistant turn on
+  `turn_end` and `session_shutdown` (the backstop for a headless one-turn run),
+  read from `sessionManager.getBranch()` — the same entries the session jsonl
+  persists — into `resolveProjectDir() ?? agentDir()`, deduped by `ts|model` so
+  the two hooks cannot double-record. The file is **append-only** (a crash never
+  corrupts it) and **bounded**: `appendUsageRow` compacts to the newest
+  `USAGE_LEDGER_CAP = 2000` rows via a temp file + atomic rename, so a crash
+  mid-compaction leaves the original intact. Recording is **best-effort** — a
+  failure never breaks a session, and `appendUsageRow` never throws. Reading is
+  tolerant: a missing, unreadable or malformed file degrades to `[]`, and an
+  unparseable or wrongly-shaped line is skipped. The explorer reads the active
+  scope's ledger (a project scope its own `<root>/.omp`), so the per-task column
+  follows the scope.
+
 - `previousModelRoles` is the full snapshot of the last `modelRoles` block
   **before** the plugin changed it — a manual rollback aid; there is no rollback
   command.