omp-llm-role 1.2.0 → 1.3.0

package/README.md

@@ -63,6 +63,13 @@ omp plugin install omp-llm-role@gott50-plugins
   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
 
@@ -120,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>.*`):
@@ -421,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 `Σ`
@@ -457,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

package/docs/dev/architecture.md

@@ -25,16 +25,17 @@ 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, 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`. Also subscribes to `session_start`, `retry_fallback_applied`, `retry_fallback_succeeded` and `turn_start` to keep the live model's display name suffixed with its provider pin (`src/provider-display.ts`); each handler mutates the live model's `name` in place and never calls `pi.setModel` (which would wipe omp's in-flight fallback state and clobber the thinking level). Owns `extDeps` (the extension's `Deps`) and the live-session model hook. Every unexpected command-handler throw and every `runUpdater` defect is routed through `src/error-report.ts`: `reportCommandError` for the six command-handler catch sites and `reportDefect` for a `runUpdater` result whose `defect` is set — each keeps the pre-existing one-line warning and adds the reporting module's own lines. |
+| `src/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`. |
@@ -43,7 +44,7 @@ the extension's `/refresh-roles`, `/explore-roles` and `/create-agent`.
 | `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. |
 
@@ -51,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
 

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

package/docs/dev/current-state.md

@@ -1,4 +1,4 @@
-# Current state (2026-10-11)
+# 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
@@ -6,11 +6,46 @@ 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 model-level
-ranking numbers below are the 2026-10-09 measurement (the input-price blend basis
-#21, the #17/#18/#19/#20 wave and the #34–#40 focus-axis/capability-flag work);
-the provider-pin numbers are the 2026-10-11 measurement (spec #71; see the top
+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 =
@@ -653,18 +688,18 @@ bullet). Neither is 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`).
-- 408 llm-stats models; OpenRouter matched 155/408 (throughput), 153 priced (the
-  2026-10-08 snapshot read 155/407 — the daily cache moved, not the code; the
+- 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.810), `smol` DeepSeek-V4.1-Flash (0.729),
-  `slow` DeepSeek-V4.1-Flash (0.832), `vision` DeepSeek-V4.1-Flash (0.730),
-  `plan` Muse Spark 1.3 (0.793), `commit` DeepSeek-V4.1-Flash (0.762), `tiny`
-  Muse Spark 1.1 (0.791), `task` DeepSeek-V4.1-Flash (0.754), `advisor`
-  Muse Spark 1.3 (0.787), `designer` DeepSeek-V4.1-Flash (0.787).
+  `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/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,28 +146,48 @@ 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
@@ -156,6 +198,15 @@ Pure, no I/O; all ranking math is delegated to `src/engine.ts`.
   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 +253,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 +313,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 +360,24 @@ 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).
+  `autoPin` (read-only — the manual field is the only way to set one). 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,35 @@ 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.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 +200,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.2.0`).
+- **Next release: none owed.** `## [Unreleased]` is empty — the 1.2.0 cut moved
+  its entries under `## [1.2.0] - 2026-10-12`; 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;
@@ -191,6 +194,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,