omp-llm-role 1.2.0 → 1.3.0

package/src/explorer/boot.ts

@@ -13,10 +13,13 @@
 
 import { execFile } from "node:child_process";
 import type { Server } from "node:http";
-import { enrichThinkingLevels, type CatalogEntry, type KeyAvailability } from "../availability.ts";
+import { join } from "node:path";
+import { enrichThinkingLevels, type CatalogEntry, type KeyAvailability, type Tier } from "../availability.ts";
 import type { RankData } from "../engine.ts";
 import { DEFAULT_ROLES, PLUGIN_SETTINGS_PATH } from "../settings.ts";
 import { agentDir } from "../state.ts";
+import { readUsageRows, type TokenProfile } from "../usage-ledger.ts";
+import type { PoolInputs } from "./pool.ts";
 import { readScopeRoles, resolveScope, resolveScopes, type Scope, type ScopeInputs } from "./scopes.ts";
 import { createExplorerServer } from "./server.ts";
 
@@ -49,6 +52,25 @@ export type ExplorerBootOpts = {
   reload(refresh: boolean): Promise<RankData>;
   /** Re-derive the key-availability overlay for `POST /api/refresh` (best-effort). */
   reloadAvailability?: () => Promise<KeyAvailability>;
+  /**
+   * The as-written pool's inputs (spec #81): the key's tier and the account's
+   * allowed-providers whitelist. Both are best-effort — an absent tier reads as
+   * `billed` (the ordinary account), and an absent/null whitelist leaves every
+   * route in place, so a failed harvest degrades to the raw pool instead of
+   * breaking the explorer.
+   */
+  tier?: Tier;
+  allowedProviders?: ReadonlySet<string> | null;
+  /** Re-derive the whitelist for `POST /api/refresh` (best-effort: a throw or a
+   *  null result degrades the as-written pool to no route pruning). */
+  reloadAllowedProviders?: () => Promise<ReadonlySet<string> | null>;
+  /** The user-set token profile the per-task price falls back to (the
+   *  `tokenProfile` setting); absent = unset. */
+  tokenProfile?: TokenProfile | null;
+  /** Dir holding the user-level usage ledger the per-task price resolves its
+   *  profile from (default: `agentDir()`, beside the plugin's other state). A
+   *  project scope reads its own `<root>/.omp` ledger instead. */
+  usageDir?: string;
   port?: number;
   /** Open the URL in the default browser (macOS only). */
   open?: boolean;
@@ -93,6 +115,11 @@ export async function startExplorer(opts: ExplorerBootOpts): Promise<ExplorerHan
   const scopeInputs: ScopeInputs = { userLockPath, cwd, registryDir: opts.registryDir };
   let rank = opts.rank;
   let availability = opts.availability;
+  // The as-written pool's mutable half: the whitelist is re-derived on refresh,
+  // the catalog and tier are boot-time facts. `null` = no pruning.
+  let allowed = opts.allowedProviders ?? null;
+  const tier = opts.tier ?? "billed";
+  const usageDir = opts.usageDir ?? agentDir();
   enrichThinkingLevels(rank.models, opts.catalog);
 
   // Scope resolution is boot's job: the user-level scope, the registry's
@@ -117,7 +144,22 @@ export async function startExplorer(opts: ExplorerBootOpts): Promise<ExplorerHan
       rank = await opts.reload(true);
       enrichThinkingLevels(rank.models, opts.catalog);
       if (opts.reloadAvailability) availability = await opts.reloadAvailability();
+      // Best-effort: the whitelist is account state, so a failed re-harvest must
+      // leave the explorer usable (routes unpruned) rather than fail the refresh.
+      if (opts.reloadAllowedProviders) {
+        try {
+          allowed = await opts.reloadAllowedProviders();
+        } catch {
+          allowed = null;
+        }
+      }
     },
+    getPoolInputs: (): PoolInputs => ({ catalog: opts.catalog, tier, allowed }),
+    // The ledger follows the plugin's state location: a project scope keeps its
+    // usage in its own `<root>/.omp`, so its per-task column never mixes with
+    // the user-level profile.
+    getUsageRows: (scope) => readUsageRows(scope.kind === "project" && scope.root !== undefined ? join(scope.root, ".omp") : usageDir),
+    tokenProfile: opts.tokenProfile ?? null,
   });
   // Optional detach (extension only): never hold the host process open on the
   // server's account, so a short-lived `omp -p` run cannot hang.

package/src/explorer/explain.ts

@@ -15,8 +15,9 @@
 import { assessFocusMetric, type FocusMetricAssessment } from "../agent-create.ts";
 import { type KeyAvailability } from "../availability.ts";
 import { cachedSourceInfo, sourceForMetric, type SourceDeclaration } from "../benchmark-sources.ts";
-import { autoPinApplies, BENCHMARK_CHANCE, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, thinkingAdjustedPrice, type Model, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { autoPinApplies, BENCHMARK_CHANCE, blendOutputPrice, blendRoutePool, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, routeInputPrice, routeOutputPrice, routePassesEndpointFilters, thinkingAdjustedPrice, type Model, type OpenRouterEndpointRecord, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
 import { KNOWN_METRICS } from "../settings.ts";
+import { type TokenProfile } from "../usage-ledger.ts";
 
 // ---------------------------------------------------------------------------
 // Metric metadata (the UI's picklists and formula legends)
@@ -126,6 +127,79 @@ export function focusAssessments(
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Per-task price (display-only)
+// ---------------------------------------------------------------------------
+
+/** The per-task price of one model under a role: the role's priced route's input
+ * and output prices applied to the role's token profile, with the output term
+ * scaled by the role's thinking factor. Display-only — it never feeds the
+ * ranking's sort key, `value`, or the explanation's `cost` block. */
+export type PerTaskPrice = {
+  inputTokens: number;
+  outputTokens: number;
+  /** the route's input price, $/M (cache-adjusted by the role's cache-hit rate) */
+  inputPrice: number;
+  /** the route's output price, $/M (derived from the billed blend and the input price) */
+  outputPrice: number;
+  /** the role's thinking factor (1 for a bare role) */
+  thinkingFactor: number;
+  /** dollars per task */
+  total: number;
+};
+
+/** The model's blended input price: the 1/weightPrice²-weighted mean of the
+ * routes' cache-adjusted input prices (`routeInputPrice`) — the same weighting
+ * `blendRoutePool` uses (the router's sort key), so price each route at its input
+ * price and read the blend back. The cache-hit rate must reach this term too, or
+ * `p_out` would mix a cache-adjusted billed blend with an unadjusted input price. */
+function blendedInputPrice(routes: readonly OpenRouterEndpointRecord[], cacheHitRate: number): number | null {
+  const priced = routes.map((r) => ({ ...r, price: routeInputPrice(r, cacheHitRate) }));
+  return blendRoutePool(priced, 0).price;
+}
+
+/** The per-task price of `model` under `def` for a token profile: `p_in` is the
+ * role's priced route's input price (cache-adjusted), `p_out` its output price
+ * (the inverse 3:1 blend of the same route, `routeOutputPrice`), and the output
+ * term is scaled by the role's thinking factor. 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). */
+export function perTaskPrice(model: Model, def: RoleDef, profile: TokenProfile): PerTaskPrice | null {
+  const cacheHitRate = def.cacheHitRate ?? 0;
+  // A role with endpoint filters prices on the routes that survive them; a model
+  // whose every route fails is ineligible (the ranking drops it), so its per-task
+  // price is absent, not the unfiltered blend.
+  const em = endpointFilteredModel(model, def.filters, cacheHitRate);
+  if (em === null) return null;
+  const route = roleRoute(model, def);
+  let inputPrice: number | null;
+  let outputPrice: number | null;
+  if (route !== null) {
+    // The role prices this model on one route: that route's own input and output
+    // prices, the same pair the billed blend comes from.
+    inputPrice = routeInputPrice(route, cacheHitRate);
+    outputPrice = routeOutputPrice(route, cacheHitRate);
+  } else {
+    // The 1/price² blend case: the billed blend `em` is priced on and the input
+    // blend over exactly the routes it blended — the endpoint-filtered pool, never
+    // the model's full route list (a dropped route's input price belongs to no
+    // route's output price).
+    const pool = (model.routes ?? []).filter((r) => routePassesEndpointFilters(r, def.filters));
+    inputPrice = blendedInputPrice(pool, cacheHitRate);
+    outputPrice = inputPrice === null || em.price === null ? null : blendOutputPrice(em.price, inputPrice);
+  }
+  if (inputPrice === null || outputPrice === null) return null;
+  // The same gated factor the ranking applies: `thinkingAdjustedPrice(model, def, 1)`
+  // is 1 unless the model actually runs at the role's level, so the per-task price
+  // and the row's `priceEff` can never disagree for a non-thinking model.
+  const thinkingFactor = thinkingAdjustedPrice(model, def, 1);
+  const total = (profile.inputTokens * inputPrice + profile.outputTokens * outputPrice * thinkingFactor) / 1e6;
+  return { inputTokens: profile.inputTokens, outputTokens: profile.outputTokens, inputPrice, outputPrice, thinkingFactor, total };
+}
+
 // ---------------------------------------------------------------------------
 // Rank rows (table data with baseline deltas)
 // ---------------------------------------------------------------------------
@@ -156,6 +230,9 @@ export type RankRow = {
   baselineRank: number | null;
   /** baselineRank − rank; positive = moved up */
   delta: number | null;
+  /** dollars per task under the role's token profile, or null when no profile
+   * was supplied or the model has no usable route price. Display-only. */
+  perTask: number | null;
 };
 
 /** The availability overlay verdict for one model id: `"usable"` when the keyed
@@ -172,8 +249,9 @@ function keyVerdict(availability: KeyAvailability | undefined, id: string): "usa
 /** Rank `models` under `def`, annotating each row with its rank delta against
  * `baseline` (the effective role's ranking, i.e. what the plugin does today) and
  * its keyed-catalog availability overlay. Ranking order, deltas, and every other
- * field are unaffected by `availability`. */
-export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], availability?: KeyAvailability): RankRow[] {
+ * field are unaffected by `availability` or `profile`; `profile` only fills the
+ * display-only `perTask` column. */
+export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], availability?: KeyAvailability, profile?: TokenProfile | null): RankRow[] {
   const ranked = rankRole(def, models);
   const frontier = paretoFrontier(ranked);
   const baselineRank = new Map<string, number>();
@@ -200,6 +278,7 @@ export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], avai
       rank,
       baselineRank: b,
       delta: b == null ? null : b - rank,
+      perTask: profile == null ? null : perTaskPrice(r.model, def, profile)?.total ?? null,
     };
   });
 }
@@ -275,6 +354,10 @@ export type Explanation =
       role: { name: string; lambda: number; derivedLambda: number; wPrice: number; qW: number; thinking: SuffixLevel | undefined; cacheHitRate: number };
       contributions: Contribution[];
       cost: { priceEff: number; billedPrice: number; lambda: number; penalty: number; q: number; value: number };
+      /** the per-task price breakdown under the role's token profile, or null
+       * when no profile was supplied or the model has no usable route price.
+       * Display-only — never part of `cost` or the ranking. */
+      perTask: PerTaskPrice | null;
       gapAbove: number | null;
       gapToTop: number;
       above: { id: string; name: string; value: number } | null;
@@ -284,8 +367,9 @@ export type Explanation =
 
 /** Full decomposition of one model's rank for a role, or the eligibility gates it
  * failed (same gates `rankRole` applies, listed in the same order). The eligible
- * branch also carries the keyed-catalog availability overlay (`key`/`keyReason`). */
-export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = "", availability?: KeyAvailability): Explanation {
+ * branch also carries the keyed-catalog availability overlay (`key`/`keyReason`)
+ * and, when a token `profile` is supplied, the display-only per-task price. */
+export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = "", availability?: KeyAvailability, profile?: TokenProfile | null): Explanation {
   const model = models.find((m) => m.id === modelId);
   if (!model) return { eligible: false, reasons: ["model not found in today's dataset"] };
 
@@ -424,6 +508,7 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
     role: { name: roleName, lambda, derivedLambda, wPrice, qW, thinking: def.thinking, cacheHitRate },
     contributions,
     cost: { priceEff: self.priceEff, billedPrice: route !== null ? routeEffectivePrice(route, cacheHitRate) ?? eff.price : eff.price, lambda, penalty: lambda * self.priceEff, q: self.q, value: self.value },
+    perTask: profile == null ? null : perTaskPrice(model, def, profile),
     gapAbove,
     gapToTop,
     above,

package/src/explorer/levers.ts

@@ -0,0 +1,100 @@
+/**
+ * Price-lever readouts for the ranking explorer: the leader-flip threshold (the
+ * price weight at which a cheaper challenger overtakes the value leader) and the
+ * thinking level's effect on the leader.
+ *
+ * Both are pure and computed on the pool they are handed, so the caller decides
+ * raw vs as-written. The math is the engine's own — `roleLambda`, `rankRole`,
+ * `SUFFIX_LEVELS` and `thinkingPriceFactor` are reused, never re-derived.
+ */
+
+import {
+  rankRole,
+  SUFFIX_LEVELS,
+  thinkingPriceFactor,
+  type Model,
+  type Ranked,
+  type RoleDef,
+  type SuffixLevel,
+} from "../engine.ts";
+
+/** The price weight at which a cheaper challenger overtakes the value leader. */
+export type LeaderFlip = {
+  /** the role's current price weight */
+  wPrice: number;
+  /** the price weight at which a cheaper challenger overtakes */
+  flipW: number;
+  /** `flipW − wPrice` */
+  distance: number;
+  challenger: { id: string; name: string; value: number; priceEff: number };
+};
+
+/**
+ * The price weight at which a cheaper challenger overtakes the value leader, or
+ * `null` when no cheaper challenger exists (the readout is absent, never
+ * invented).
+ *
+ * `λ* = min over cheaper challengers X of (q_L − q_X)/(pEff_L − pEff_X)`, then
+ * `w* = 20·λ* ÷ (1 + 20·λ*)` — the inverse of `roleLambda`'s
+ * `λ = w/(1−w)/20`. 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.
+ *
+ * The threshold is exact when the role's price basis is weight-independent (the
+ * 1/price² blend, or a hard `providerPin`). With the soft `preferOwnProvider`
+ * basis the route choice itself moves with the price weight, so the threshold is
+ * a first-order estimate.
+ */
+export function leaderFlip(def: RoleDef, models: Model[]): LeaderFlip | null {
+  const ranked = rankRole(def, models);
+  const leader = ranked[0];
+  if (leader === undefined) return null;
+  let best: { lambda: number; challenger: Ranked } | null = null;
+  for (const x of ranked) {
+    if (!(x.priceEff < leader.priceEff)) continue; // cheaper challengers only
+    const lambda = (leader.q - x.q) / (leader.priceEff - x.priceEff);
+    if (best === null || lambda < best.lambda) best = { lambda, challenger: x };
+  }
+  if (best === null) return null;
+  const wPrice = def.weights.price ?? 0;
+  const flipW = (20 * best.lambda) / (1 + 20 * best.lambda);
+  return {
+    wPrice,
+    flipW,
+    distance: flipW - wPrice,
+    challenger: {
+      id: best.challenger.model.id,
+      name: best.challenger.model.name,
+      value: best.challenger.value,
+      priceEff: best.challenger.priceEff,
+    },
+  };
+}
+
+/** One thinking level's effect on the ranking: the level, its price factor, and
+ * the leader at that level (`null` when the level ranks nothing). */
+export type ThinkingLevelRow = {
+  level: SuffixLevel;
+  factor: number;
+  leader: { id: string; name: string; value: number } | null;
+};
+
+/**
+ * The leader at each thinking level, with the level's price factor, or `null`
+ * for a bare role (`def.thinking === undefined` — a role with no thinking level
+ * is unaffected).
+ *
+ * The factor is a price-sensitivity amplifier, not a hidden cost: it multiplies
+ * `priceEff`, so it penalizes expensive models more in absolute λ-units.
+ */
+export function thinkingLevelEffect(def: RoleDef, models: Model[]): ThinkingLevelRow[] | null {
+  if (def.thinking === undefined) return null;
+  return (Object.keys(SUFFIX_LEVELS) as SuffixLevel[]).map((level) => {
+    const leader = rankRole({ ...def, thinking: level }, models)[0];
+    return {
+      level,
+      factor: thinkingPriceFactor(level),
+      leader: leader === undefined ? null : { id: leader.model.id, name: leader.model.name, value: leader.value },
+    };
+  });
+}

package/src/explorer/pool.ts

@@ -0,0 +1,46 @@
+/**
+ * The as-written pool: the explorer's dataset filtered exactly as the updater
+ * filters it before ranking (spec #81). Two filters, both sourced from the
+ * availability primitives so the two pools cannot drift:
+ *
+ * 1. the catalog/tier gate — `filterCatalog(catalog, tier)`, then keep only
+ *    models whose ranking id resolves to a tier-eligible entry
+ *    (`resolveVariant`), mirroring `src/updater.ts:300` + `:376`;
+ * 2. the allowed-providers whitelist prune — each kept model's routes are
+ *    filtered to allowed providers (`providerAllowed`), mirroring
+ *    `src/updater.ts:349-357`. A null whitelist (no whitelist set / harvest
+ *    failed) leaves the routes untouched.
+ *
+ * Pure: the input `RankData` and its models are never mutated. The fetch
+ * metadata (`fetchedAt`, `source`, `orMatched`, `orPriced`) describes the fetch,
+ * not the pool, and is carried through unchanged.
+ */
+
+import { filterCatalog, providerAllowed, resolveVariant, type CatalogEntry, type Tier } from "../availability.ts";
+import type { RankData } from "../engine.ts";
+
+/** Which dataset the explorer ranks: the raw fetch, or the pool the updater writes from. */
+export type PoolMode = "raw" | "as-written";
+
+/** The inputs the as-written pool needs beyond the ranking data: the omp catalog,
+ * the key's tier, and the account's allowed-providers whitelist (`null` = no
+ * whitelist / harvest failed). */
+export type PoolInputs = { catalog: CatalogEntry[]; tier: Tier; allowed: ReadonlySet<string> | null };
+
+/** The as-written pool: `rank` with the catalog/tier gate and the
+ * allowed-providers prune applied. `tier: "none"` yields an empty pool. */
+export function asWrittenPool(rank: RankData, inputs: PoolInputs): RankData {
+  const tier = inputs.tier;
+  const eligible = filterCatalog(inputs.catalog, tier);
+  const gated = tier === "none" ? [] : rank.models.filter((m) => resolveVariant(m.id, eligible, tier) !== null);
+  const allowed = inputs.allowed;
+  const models =
+    allowed === null
+      ? gated
+      : gated.map((m) => {
+          const routes = m.routes;
+          if (routes === undefined) return m;
+          return { ...m, routes: routes.filter((r) => providerAllowed(allowed, r.providerSlug)) };
+        });
+  return { ...rank, models };
+}

package/src/explorer/server.ts

@@ -10,9 +10,13 @@
  *                             capability flags, and the feature registry
  *   POST /api/scope        -> { scope } -> switch the active scope, return the
  *                             new bootstrap payload
- *   POST /api/rank         -> { role, def } -> rows with baseline deltas and a
- *                             per-row `key` badge (usable/blocked/unknown)
- *   POST /api/explain      -> { role, def, modelId } -> full decomposition
+ *   POST /api/pool         -> { mode } -> switch the ranked pool (raw vs
+ *                             as-written), return the new bootstrap payload
+ *   POST /api/rank         -> { role, def } -> rows with baseline deltas, a
+ *                             per-row `key` badge (usable/blocked/unknown), and
+ *                             the display-only per-task price
+ *   POST /api/explain      -> { role, def, modelId } -> full decomposition plus
+ *                             the two price-lever readouts
  *   POST /api/export       -> { roles } -> validated, backed-up write of the
  *                             active scope's lock file
  *   POST /api/refresh      -> refetch the dataset, return the bootstrap payload
@@ -31,7 +35,10 @@ import { expandFeatures, FEATURES } from "../features.ts";
 import { isRecord } from "../guards.ts";
 import { validateRole, writeRoleSettings } from "../role-settings.ts";
 import { KNOWN_METRICS, type UniverseEntry } from "../settings.ts";
+import { resolveTokenProfile, type TokenProfile, type UsageRow } from "../usage-ledger.ts";
 import { explainModel, focusAssessments, metricMetaFor, rankRows, weightableMetrics } from "./explain.ts";
+import { leaderFlip, thinkingLevelEffect } from "./levers.ts";
+import { asWrittenPool, type PoolInputs, type PoolMode } from "./pool.ts";
 import type { Scope } from "./scopes.ts";
 
 export type ExplorerOpts = {
@@ -63,10 +70,33 @@ export type ExplorerOpts = {
   };
   /** Re-runs loadRankData({ refresh: true }) and swaps the snapshot. */
   refresh(): Promise<void>;
+  /**
+   * The inputs the `as-written` pool ranks with: 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 can never 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, so a project's usage never leaks into the user-level
+   * view. Optional: a host without a ledger supplies none, and the profile falls
+   * back to `tokenProfile` (or stays absent). Re-read per call, so a turn
+   * recorded while the explorer is open shows up without a restart.
+   */
+  getUsageRows?(scope: Scope): readonly UsageRow[];
+  /**
+   * The user-set token profile — the fallback when a role has no recorded usage
+   * (the `tokenProfile` setting). `null` (the default) = unset.
+   */
+  tokenProfile?: TokenProfile | null;
 };
 
-/** Per-server mutable state: the active scope id (null = the default scope). */
-type ExplorerSession = { activeScopeId: string | null };
+/** Per-server mutable state: the active scope id (null = the default scope) and
+ * the ranked pool. Both are session state, so a scope switch and a refresh keep
+ * them (the pool inputs themselves are re-derived per call). */
+type ExplorerSession = { activeScopeId: string | null; poolMode: PoolMode };
 
 const MIME: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
@@ -157,8 +187,18 @@ function activeScope(opts: ExplorerOpts, session: ExplorerSession): Scope {
   return scope;
 }
 
-function bootstrapPayload(opts: ExplorerOpts, scope: Scope): object {
+/** The dataset the session's pool mode ranks: the raw fetch, or the
+ * gated+pruned pool the updater writes from. Applied before ranking, never to
+ * the export path (which validates a pin against the raw dataset). */
+function poolRank(opts: ExplorerOpts, session: ExplorerSession, rank: RankData): RankData {
+  return session.poolMode === "as-written" ? asWrittenPool(rank, opts.getPoolInputs()) : rank;
+}
+
+function bootstrapPayload(opts: ExplorerOpts, session: ExplorerSession, scope: Scope): object {
   const state = opts.getState(scope);
+  // Every count and assessment below describes the pool the user is looking at,
+  // so the header's model count matches the table's rows.
+  const rank = poolRank(opts, session, state.rank);
   // The metric universe the UI may weight: the shipped keys plus any external
   // metric a resolved role weights, with a derived metadata entry for each.
   const external = new Set<string>();
@@ -170,7 +210,7 @@ function bootstrapPayload(opts: ExplorerOpts, scope: Scope): object {
   // Five-axis assessment of each role's focus metrics, over the same resolved
   // dataset the updater ranks on (so the explorer and the updater agree).
   const focus = Object.fromEntries(
-    Object.entries(state.roles).map(([role, def]) => [role, focusAssessments(state.rank.models, def, declared)]),
+    Object.entries(state.roles).map(([role, def]) => [role, focusAssessments(rank.models, def, declared)]),
   );
   return {
     roles: state.roles,
@@ -185,10 +225,14 @@ function bootstrapPayload(opts: ExplorerOpts, scope: Scope): object {
     focusAssessments: focus,
     levels: Object.keys(SUFFIX_LEVELS),
     thinkingFactors: thinkingFactors(),
-    fetchedAt: state.rank.fetchedAt,
-    modelCount: state.rank.models.length,
-    orMatched: state.rank.orMatched,
-    orPriced: state.rank.orPriced,
+    fetchedAt: rank.fetchedAt,
+    modelCount: rank.models.length,
+    orMatched: rank.orMatched,
+    orPriced: rank.orPriced,
+    // The ranked pool the counts above describe; the SPA's header toggle reads it.
+    poolMode: session.poolMode,
+    // The user-set token profile the per-task column falls back to (null = unset).
+    tokenProfile: opts.tokenProfile ?? null,
     availability: {
       active: state.availability.active,
       reason: state.availability.reason,
@@ -210,7 +254,16 @@ async function handleScope(req: IncomingMessage, res: ServerResponse, opts: Expl
   if (scope === undefined) throw new HttpError(404, `unknown scope: ${body.scope}`);
   if (!scope.present) throw new HttpError(409, `scope unavailable: ${body.scope}`);
   session.activeScopeId = scope.id;
-  sendJson(res, 200, bootstrapPayload(opts, scope));
+  sendJson(res, 200, bootstrapPayload(opts, session, scope));
+}
+
+async function handlePool(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
+  const body = await readJson(req);
+  if (!isRecord(body) || (body.mode !== "raw" && body.mode !== "as-written")) {
+    throw new HttpError(400, 'expected { mode: "raw" | "as-written" }');
+  }
+  session.poolMode = body.mode;
+  sendJson(res, 200, bootstrapPayload(opts, session, activeScope(opts, session)));
 }
 
 async function handleRank(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
@@ -220,7 +273,9 @@ async function handleRank(req: IncomingMessage, res: ServerResponse, opts: Explo
   }
   const role = body.role;
   const authored = body.def as unknown as RoleDef;
-  const state = opts.getState(activeScope(opts, session));
+  const scope = activeScope(opts, session);
+  const state = opts.getState(scope);
+  const rank = poolRank(opts, session, state.rank);
   // The posted def is AUTHORED (flags + explicit keys); expand it with the
   // scope's global flags so the preview matches the resolved baseline
   // (`state.roles[role]`) — otherwise every row's Δ would be a lie.
@@ -229,8 +284,8 @@ async function handleRank(req: IncomingMessage, res: ServerResponse, opts: Explo
   // role against its effective def (shipped defaults merged with its overrides) so
   // selecting it still shows deltas, not an empty baseline.
   const baselineDef = state.roles[role] ?? state.universe[role]?.def ?? state.defaults[role];
-  const baseline = baselineDef ? rankRole(baselineDef, state.rank.models) : [];
-  const rows = rankRows(def, state.rank.models, baseline, state.availability);
+  const baseline = baselineDef ? rankRole(baselineDef, rank.models) : [];
+  const rows = rankRows(def, rank.models, baseline, state.availability, resolveTokenProfile(role, opts.getUsageRows?.(scope) ?? [], opts.tokenProfile ?? null));
   sendJson(res, 200, {
     eligible: rows.length,
     lambda: roleLambda(def),
@@ -248,12 +303,22 @@ async function handleExplain(req: IncomingMessage, res: ServerResponse, opts: Ex
     throw new HttpError(400, "expected { role: string, def: object, modelId: string }");
   }
   const authored = body.def as unknown as RoleDef;
-  const state = opts.getState(activeScope(opts, session));
+  const scope = activeScope(opts, session);
+  const state = opts.getState(scope);
+  const rank = poolRank(opts, session, state.rank);
   // Same expansion as handleRank: the posted def is authored, the baseline is
   // resolved, so the preview must apply the scope's global flags first.
   const def = expandFeatures(authored, state.features ?? {});
-  const explanation = explainModel(def, state.rank.models, body.modelId, body.role, state.availability);
-  sendJson(res, 200, { ...explanation, errors: validateRole(body.role, authored) });
+  const explanation = explainModel(def, rank.models, body.modelId, body.role, state.availability, resolveTokenProfile(body.role, opts.getUsageRows?.(scope) ?? [], opts.tokenProfile ?? null));
+  // The two price-lever readouts are role-level, so they ride beside the
+  // per-model decomposition — computed on the active pool, so the readout and
+  // the ranking above it agree.
+  sendJson(res, 200, {
+    ...explanation,
+    leaderFlip: leaderFlip(def, rank.models),
+    thinkingLevels: thinkingLevelEffect(def, rank.models),
+    errors: validateRole(body.role, authored),
+  });
 }
 
 async function handleExport(req: IncomingMessage, res: ServerResponse, opts: ExplorerOpts, session: ExplorerSession): Promise<void> {
@@ -286,12 +351,16 @@ async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerO
   if (path.startsWith("/api/")) {
     if (path === "/api/bootstrap") {
       if (method !== "GET") return sendText(res, 405, "method not allowed");
-      return sendJson(res, 200, bootstrapPayload(opts, activeScope(opts, session)));
+      return sendJson(res, 200, bootstrapPayload(opts, session, activeScope(opts, session)));
     }
     if (path === "/api/scope") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
       return handleScope(req, res, opts, session);
     }
+    if (path === "/api/pool") {
+      if (method !== "POST") return sendText(res, 405, "method not allowed");
+      return handlePool(req, res, opts, session);
+    }
     if (path === "/api/rank") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
       return handleRank(req, res, opts, session);
@@ -307,7 +376,7 @@ async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerO
     if (path === "/api/refresh") {
       if (method !== "POST") return sendText(res, 405, "method not allowed");
       await opts.refresh();
-      return sendJson(res, 200, bootstrapPayload(opts, activeScope(opts, session)));
+      return sendJson(res, 200, bootstrapPayload(opts, session, activeScope(opts, session)));
     }
     return sendText(res, 404, "not found");
   }
@@ -317,7 +386,9 @@ async function handle(req: IncomingMessage, res: ServerResponse, opts: ExplorerO
 }
 
 export function createExplorerServer(opts: ExplorerOpts): Server {
-  const session: ExplorerSession = { activeScopeId: null };
+  // `raw` is the historical behaviour, so a fresh server ranks exactly what it
+  // ranked before the pool toggle existed.
+  const session: ExplorerSession = { activeScopeId: null, poolMode: "raw" };
   return createServer((req, res) => {
     handle(req, res, opts, session).catch((err: unknown) => {
       if (res.headersSent) {