omp-llm-role 1.2.0 → 1.4.0

package/docs/dev/explorer.md

@@ -12,7 +12,9 @@ explorer never reimplements `value = q − λ·$/M`.
 | File | Role |
 |---|---|
 | `src/explorer/server.ts` | Zero-dependency `node:http` surface: static SPA + JSON API. Exports `createExplorerServer`, `ExplorerOpts`. |
-| `src/explorer/explain.ts` | Pure explanation layer (no I/O): rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets, and the keyed-catalog availability overlay. Exports `rankRows`, `explainModel`, `inverseCardinal`, `METRIC_META`, `WEIGHTABLE_METRICS`. |
+| `src/explorer/explain.ts` | Pure explanation layer (no I/O): rank rows with baseline deltas, per-model decomposition, inverse-cardinal targets, the keyed-catalog availability overlay, and the display-only per-task price. Exports `rankRows`, `explainModel`, `perTaskPrice`, `inverseCardinal`, `METRIC_META`, `WEIGHTABLE_METRICS`. |
+| `src/explorer/levers.ts` | Pure price-lever readouts (no I/O): the leader-flip threshold and the thinking level's effect on the leader, computed on the pool they are handed. Exports `leaderFlip`, `thinkingLevelEffect`, `LeaderFlip`, `ThinkingLevelRow`. |
+| `src/explorer/pool.ts` | The as-written pool (no I/O): the dataset filtered exactly as the updater filters it before ranking (catalog/tier gate + allowed-providers prune). Exports `asWrittenPool`, `PoolMode`, `PoolInputs`. |
 | `src/explorer/scopes.ts` | Scope resolution (no HTTP): the user-level scope, the registry's projects, and the session's project; the per-scope read; the dataset union. Exports `Scope`, `resolveScopes`, `defaultScopeId`, `resolveScope`, `readScopeRoles`, `unionRoles`. |
 | `src/explorer/boot.ts` | Shared launcher: bind/port fallback, scope resolution, browser open, close. Exports `startExplorer`, `EXPLORER_DEFAULT_PORT`, `ExplorerHandle`, `ExplorerBootOpts`. |
 | `src/project-registry.ts` | The global project registry (`llm-role-projects.json` in the agent dir): read/register/prune, atomic write. Exports `PROJECT_REGISTRY_FILE`, `readProjectRegistry`, `registerProject`. |
@@ -47,12 +49,29 @@ type ExplorerOpts = {
     availability: KeyAvailability;            // keyed-catalog overlay (re-derived on refresh)
   };
   refresh(): Promise<void>;                   // re-runs loadRankData({ refresh: true, roles, extraMetrics }) and swaps rank
+  // The as-written pool's inputs: the omp catalog, the key's tier, and the
+  // account's allowed-providers whitelist (null = no whitelist / harvest failed,
+  // which leaves every route in place). Re-derived per call, so a project's
+  // whitelist cannot leak into another scope's view.
+  getPoolInputs(): PoolInputs;
+  // The recorded usage rows the per-task price resolves its token profile from,
+  // for the request's active scope (a project scope reads its own `<root>/.omp`
+  // ledger). Optional: a host without a ledger supplies none.
+  getUsageRows?(scope: Scope): readonly UsageRow[];
+  // The user-set token profile the per-task column falls back to (the
+  // `tokenProfile` setting); null (the default) = unset.
+  tokenProfile?: TokenProfile | null;
 };
 ```
 
-The server holds the active scope id as mutable state (alongside the mutable
-`rank`/`availability`); `activeScope` resolves it per request, persisting the
-fallback when the active scope became unavailable.
+The server holds the active scope id **and the pool mode** as mutable state
+(alongside the mutable `rank`/`availability`); `activeScope` resolves the scope
+per request, persisting the fallback when the active scope became unavailable.
+`poolRank` applies the session's pool mode to the dataset before ranking — the
+`as-written` mode runs `asWrittenPool(rank, opts.getPoolInputs())`, the `raw`
+mode (the default, the historical behaviour) passes the fetch through. The pool
+mode is **never** applied to the export path, which validates a pin against the
+raw dataset.
 
 Endpoints:
 
@@ -62,8 +81,9 @@ Endpoints:
 | `GET /app.js`, `/style.css` | — | static asset (traversal-guarded) |
 | `GET /api/bootstrap` | — | `bootstrapPayload(opts, activeScope)` |
 | `POST /api/scope` | `{scope}` | switch the active scope, then the bootstrap payload (404 unknown id, 409 non-present) |
-| `POST /api/rank` | `{role, def}` | `{eligible, lambda, derivedLambda, rows, errors}` |
-| `POST /api/explain` | `{role, def, modelId}` | `explainModel(...)` spread + `errors` |
+| `POST /api/pool` | `{mode}` | switch the ranked pool (`"raw"` \| `"as-written"`), then the bootstrap payload (400 on any other mode) |
+| `POST /api/rank` | `{role, def}` | `{eligible, lambda, derivedLambda, rows, errors}` — each row carries the display-only `perTask` |
+| `POST /api/explain` | `{role, def, modelId}` | `explainModel(...)` spread + `leaderFlip` + `thinkingLevels` + `errors` |
 | `POST /api/export` | `{roles}` | `{ok:true, backupPath, roles, lockPath}` or `{ok:false, errors}` |
 | `POST /api/refresh` | — | `await opts.refresh()` (re-ranks and re-derives the availability overlay) then the bootstrap payload |
 
@@ -75,7 +95,9 @@ Endpoints:
   focus metrics over the resolved dataset), `levels` (`Object.keys(SUFFIX_LEVELS)`), `thinkingFactors`
   (per-level billed-blend multiplier from the engine's own `thinkingPriceFactor`,
   so the UI readout cannot drift), `fetchedAt`, `modelCount`, `orMatched`,
-  `orPriced`, `lockPath` (the **active scope's** lock file), `scopes` (id, label,
+  `orPriced`, `poolMode` (the ranked pool the counts describe — `"raw"` or
+  `"as-written"`), `tokenProfile` (the user-set per-task token profile, or
+  `null`), `lockPath` (the **active scope's** lock file), `scopes` (id, label,
   kind, present per known scope), `activeScope` (the active scope id),
   the active scope's global capability flags and the feature registry (the
   `FEATURES` rows: id, label, description, recommended bundle, buys), so the SPA
@@ -124,38 +146,71 @@ Pure, no I/O; all ranking math is delegated to `src/engine.ts`.
   declared?)`** merges the shipped table with a derived entry per external metric.
 - **`weightableMetrics(extra?)`** — the shipped keys plus any external metric in
   `extra`; exactly what the validator accepts.
-- **`rankRows(def, models, baseline, availability?)`** — `rankRole(def, models)` +
+- **`rankRows(def, models, baseline, availability?, profile?)`** — `rankRole(def, models)` +
   `paretoFrontier`, annotating each row with `baselineRank`/`delta`
   (`baselineRank − rank`; positive = moved up) against the effective role's
   ranking. Rows carry `priceEff` (the thinking-adjusted price the ranking
   penalized), `parts`, `missing` (weighted non-price metrics whose raw value is
-  null), `frontier`, and `key` — the availability overlay verdict
+  null), `frontier`, `key` — the availability overlay verdict
   (`usable`/`blocked`/`unknown`), orthogonal to `missing` and to the eligibility
-  gates. `availability` is optional and pure (no I/O); omitted or inactive ⇒
-  every row reads `unknown`.
+  gates — and `perTask` (the display-only dollars-per-task, or `null`).
+  `availability` and `profile` are optional and pure (no I/O); omitted or
+  inactive ⇒ every row reads `unknown` / `perTask: null`. Neither affects the
+  ranking order or the deltas.
 - **`inverseCardinal(metric, t)`** — inverse of `cardinalMetric` for the "what
   would it take" targets: `index` → `t*80 − 20`; `throughput` → `10 * 30**t`
   (null outside `[0,1]`, because the forward transform clamps); everything else
   (benchmark, percentile, price) → identity. See *Open defect* below for the
   `gpqa` exception.
-- **`explainModel(def, models, modelId, roleName, availability?)`** — the full
+- **`perTaskPrice(model, def, profile)`** — the display-only dollars-per-task:
+  `p_in` is the role's priced route's input price (cache-adjusted by the role's
+  `cacheHitRate`, `routeInputPrice`) and `p_out` that same route's output price —
+  the inverse 3:1 blend of it (`routeOutputPrice`), never re-derived here — and
+  the output term is scaled by the role's thinking factor
+  (`thinkingAdjustedPrice(model, def, 1)`, so the per-task price and the row's
+  `priceEff` cannot disagree). When the role prices on the `1/price²` blend
+  (`roleRoute` returns `null`) the model's billed blend and the input blend over
+  the routes that survive the role's endpoint filters stand in — the same pool the
+  ranking prices on, so `p_in` and the billed blend never mix two route pools.
+  `null` when there is no usable route price — **absent, never a silent
+  zero**. The SPA renders `—` in both cases: no token profile resolves (no
+  recorded usage and no `tokenProfile` set), **or** the model has no usable
+  route price (e.g. every route pruned by the as-written whitelist — the model
+  still ranks on its blend price, but the per-task column has no route to
+  price). It never feeds the ranking's sort key, `value`, or the explanation's
+  `cost` block.
+- **`explainModel(def, models, modelId, roleName, availability?, profile?)`** — the full
   decomposition, or the eligibility gates it failed (same gates `rankRole`
   applies, same order: missing required, image filter, no billed price). On
   success: `contributions`
   (raw → cardinal `t` → renormalized weight → contribution → share of `q`, with
   a `fillNote` when the value is a capability fill), `cost` (`priceEff`, the
   cache-adjusted billed price, λ, penalty, `q`, `value`), `role.cacheHitRate`,
-  `gapAbove`/`gapToTop`/`above`, `closing` (the
+  `perTask` (the `PerTaskPrice` breakdown, or `null` when no profile was
+  supplied or the model has no usable route price), `gapAbove`/`gapToTop`/`above`, `closing` (the
   per-metric raw target that would close the gap, via `inverseCardinal`, with
   unreachable/extrapolated notes), `dominators` (models both cheaper and at
   least as good on `q`, top 3), `ownProvider` (true when the model was priced on
-  the soft best route rather than the blend), `autoPin` (the provider slug the
-  updater would write — `bestRoute(model, def)?.providerSlug`, the max-`vfm`
+  the soft best route rather than the blend), `autoPin` (the **candidate** route's
+  provider slug — `bestRoute(model, def)?.providerSlug`, the max-`vfm`
   route (scoring.md, *Route ordering*), when the role sets
-  `preferOwnProvider` and carries no manual `providerPin`, else `null`), and the
+  `preferOwnProvider` and carries no manual `providerPin`, else `null` — the
+  first route the updater's daily walk tries, **not** a promise of the written
+  pin: the updater probes it and skips to the next route when OpenRouter does not
+  serve it, or drops the pin entirely when none is routable; writes-and-state.md,
+  *The provider-pin auto-configuration*), and the
   availability overlay `key`/`keyReason`
   (the same verdict as `rankRows`, plus the reason it reads that way). It mirrors
   `rankRole`'s capability fill so the contributions sum exactly to `q`.
+- **`leaderFlip(def, models)`** / **`thinkingLevelEffect(def, models)`**
+  (`src/explorer/levers.ts`) — the two price-lever readouts, computed on the pool
+  they are handed (so the readout and the ranking above it agree). `leaderFlip`
+  returns the price weight at which a cheaper challenger overtakes the value
+  leader (`{ wPrice, flipW, distance, challenger }`), or `null` when no cheaper
+  challenger exists. `thinkingLevelEffect` returns one `{ level, factor, leader }`
+  row per thinking level, or `null` for a bare role. Both reuse the engine's own
+  `roleLambda`/`rankRole`/`SUFFIX_LEVELS`/`thinkingPriceFactor`; the formulas are
+  in [`scoring.md`](scoring.md).
 
 ## Shared boot path (`src/explorer/boot.ts`)
 
@@ -202,6 +257,22 @@ launcher `/explore-roles` uses.
   factor on the omp catalog; `refresh()` re-runs `opts.reload(true)`,
   re-enriches, and — when `opts.reloadAvailability` is supplied — re-derives the
   availability overlay.
+- **As-written pool inputs.** `ExplorerBootOpts` carries `tier` (default
+  `"billed"`), `allowedProviders` (`null` = no pruning), and
+  `reloadAllowedProviders` (re-derived on `refresh()`). `getPoolInputs()` returns
+  `{ catalog: opts.catalog, tier, allowed }` per call, so a project's whitelist
+  cannot leak into another scope's view. Both are **best-effort**: an absent tier
+  reads as `billed`, and a failed re-harvest (`reloadAllowedProviders` throwing
+  or returning `null`) degrades the as-written pool to no route pruning rather
+  than failing the refresh. `/explore-roles` builds them in-process from the
+  session's OpenRouter key (the canary must be a **catalog** slug, not a ranking
+  id).
+- **Usage ledger.** `getUsageRows(scope)` reads the active scope's ledger: a
+  project scope reads its own `<root>/.omp` ledger, the user scope reads
+  `usageDir` (default `agentDir()`), so a project's usage never mixes with the
+  user-level profile. Re-read per call, so a turn recorded while the explorer is
+  open shows up without a restart. `tokenProfile` is the user-set fallback the
+  per-task column uses when a role has no recorded usage.
 - `opts.availability` is the boot-time keyed-catalog overlay; `getState(scope)`
   returns it on every request, so `/api/rank` and `/api/explain` annotate rows
   without a second fetch. It is scope-independent and carried across switches
@@ -246,12 +317,23 @@ a scraped third-party site, so the DOM is built with
 `textContent`/`createElement` only (the `el()` helper).
 
 - **Boot**: `boot()` → `GET /api/bootstrap` → `applyBootstrap(data)`, which fills
-  `state` (`scopes`, `activeScope`, `universe`, `effective` = each entry's `def`,
+  `state` (`scopes`, `activeScope`, `poolMode`, `tokenProfile`, `universe`,
+  `effective` = each entry's `def`,
   `defs` = a structuredClone of it, `defaults`, `metrics`, `metricMeta`,
   `focusAssessments`, `levels`, `thinkingFactors`, `lockPath`, `availability`),
   renders the header/roles/table, and selects the previously selected role when
   the new scope has it, else the first role. `boot()` then wires the
   filter/topn/hide-key-blocked/export/copy/download controls.
+- **Pool toggle**: the header renders a `#pool` `<select>` (`raw` / `as-written`)
+  from `state.poolMode`. Changing it confirms first when there are unsaved edits
+  (mirroring the scope switcher), then `POST /api/pool {mode}` and
+  `applyBootstrap` on the returned payload — so the header's model count, the
+  table, the focus assessments and the two readouts all describe the pool the
+  user is now looking at. The toggle is **session-level** state — the server
+  holds one pool mode, kept across scope switches (not persisted) — while the
+  pool *inputs* are re-derived per call, so a project's whitelist never leaks
+  into another scope's view. Export is unaffected: it always
+  writes the authored def, never the pool.
 - **Scope switcher**: the header renders a `#scope` `<select>` from
   `state.scopes` (the user-level scope plus every known project); a scope whose
   lock file is gone is `disabled` with a reason `title`. Changing the selection
@@ -282,15 +364,36 @@ a scraped third-party site, so the DOM is built with
 - **Recompute**: `selectRole` → `renderRoles`/`renderEditor`/`renderExplain` +
   `recompute()`. `recompute()` → `POST /api/rank {role, def}` → `state.rows`,
   `lambda`, `derivedLambda`, `errors`; re-renders the table and readouts, and
-  reloads the explain panel if the selected model is still present. Editor
-  changes call `scheduleRecompute()` (120 ms debounce).
+  reloads the explain panel if the selected model is still present. The table
+  gains a **`$/task`** column (`r.perTask`, rendered `—` when `null`), beside the
+  `$/M` column. Editor changes call `scheduleRecompute()` (120 ms debounce).
 - **Explain**: `selectModel(id)` → `POST /api/explain {role, def, modelId}` →
-  `renderExplain()` (composition table, cost line, "why not higher",
-  dominators, and the availability line). The cost line appends `· best route`
+  `renderExplain()` (composition table, cost line, **per-task price** line, "why
+  not higher", dominators, the **Price levers** section, and the availability
+  line). The cost line appends `· best route`
   when the model was priced on the soft best route (`ownProvider`), and a
   **pin line** shows the pin in force: `pin: <slug> (manual)` when the edited def
-  carries a `providerPin`, else `auto pin: <slug>` from the explanation's
-  `autoPin` (read-only — the manual field is the only way to set one).
+  carries a `providerPin`, else `auto pin (candidate): <slug>` from the
+  explanation's `autoPin` (read-only — the manual field is the only way to set
+  one). The label says *candidate* on purpose: the value is the first route the
+  updater's value-ordered walk *tries*, not a promise of the written pin — the
+  updater probes that route and skips to the next when OpenRouter does not serve
+  it, or drops the pin entirely (bare selector) when none is routable, so the
+  written pin can be a later route or absent altogether (spec #90;
+  writes-and-state.md, *The provider-pin auto-configuration*). The explorer is
+  read-only and offline and cannot probe, so it names the candidate and says so
+  in the tooltip. The candidate equals the written pin when every route probes
+  clean; with the account's allowed-providers whitelist active, the panel and the
+  written pin agree only on the **as-written** pool, which applies the same prune
+  the updater applies before walking (in the raw pool the panel can name a route
+  the prune removes). The
+  per-task line shows the breakdown (`<in> in × $<p_in>/M + <out> out ×
+  $<p_out>/M × <factor> = $<total>`), or `— (no token profile — record usage or
+  set tokenProfile)` when `perTask` is `null`. The **Price levers** section
+  renders the leader-flip line (`w* = <flipW> · now <wPrice> · distance
+  <±distance> (<ratio>)`) and a per-level table of the thinking level's effect on
+  the leader; each is omitted when the server sends `null` (no cheaper
+  challenger, or a bare role).
 - **Provider pin field**: the editor renders a text input for
   `roles.<role>.providerPin` (a tiered slug like `deepinfra/fp8` is kept
   verbatim; empty clears the key, resuming the automatic choice). It is the

package/docs/dev/releasing.md

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

package/docs/dev/scoring.md

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

package/docs/dev/testing.md

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