omp-llm-role 1.1.0 → 1.3.0

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
@@ -26,12 +30,15 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { extname, resolve, sep } from "node:path";
 import type { KeyAvailability } from "../availability.ts";
 import { loadDeclaredSources } from "../benchmark-sources.ts";
-import { SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { pinnedRoute, SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
 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,19 +303,42 @@ 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> {
   const body = await readJson(req);
   if (!isRecord(body) || !isRecord(body.roles)) throw new HttpError(400, "expected { roles: object }");
   const scope = activeScope(opts, session);
-  const result = writeRoleSettings(scope.lockPath, body.roles as unknown as Record<string, RoleDef>);
+  const dirty = body.roles as unknown as Record<string, RoleDef>;
+  // A manual provider pin must name a route the loaded dataset actually has, or
+  // the exported role would be unroutable. Validate before any write; the
+  // plugin's own validator (empty/@/:) still runs, so both error sets surface.
+  const state = opts.getState(scope);
+  const errors: string[] = [];
+  for (const [name, def] of Object.entries(dirty)) {
+    errors.push(...validateRole(name, def));
+    if (def.providerPin === undefined) continue;
+    const known = state.rank.models.some((m) => pinnedRoute(m, def.providerPin) !== null);
+    if (!known) errors.push(`role "${name}": provider pin "${def.providerPin}" matches no route in the loaded dataset`);
+  }
+  if (errors.length > 0) return sendJson(res, 200, { ok: false, errors });
+  const result = writeRoleSettings(scope.lockPath, dirty);
   if (!result.ok) return sendJson(res, 200, { ok: false, errors: result.errors });
   sendJson(res, 200, { ok: true, backupPath: result.backupPath, roles: result.roles, lockPath: scope.lockPath });
 }
@@ -273,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);
@@ -294,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");
   }
@@ -304,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) {

package/src/extension.ts

@@ -20,16 +20,20 @@ import { generateAgentSpec, generateProjectProfile } from "./agent-architect.ts"
 import { authorBenchmarkSource } from "./benchmark-author.ts";
 import { applyBenchmarkScores, BENCHMARK_ENTRY_CAP, cachedSourceInfo, declarationToSource, declaredSourceForLink, dryRunDeclaration, fetchJson, loadBenchmarkCatalog, loadBenchmarkScores, loadDeclaredSources, resolveBenchmarkSource, saveDeclaredSource, sourceForMetric, validateDeclaration, type BenchmarkCatalogEntry, type BenchmarkPayloadMeta, type BenchmarkSource, type SourceDeclaration } from "./benchmark-sources.ts";
 import { judgeBenchmarkRelevance } from "./benchmark-discovery.ts";
-import { THINKING_LEVELS, catalogFromOmpModelsJson, fetchKeyAvailability, type KeyAvailability } from "./availability.ts";
+import { catalogFromOmpModelsJson, currentRankingId, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, splitThinkingSuffix, tierGate, type KeyAvailability, type Tier } from "./availability.ts";
+import { parseConfig } from "./config-edit.ts";
 import { loadRankData, rankRole, type Model } from "./engine.ts";
 import { defaultErrorReportDeps, reportUnexpectedError, type ErrorReportInput } from "./error-report.ts";
 import { formatFeatures } from "./features.ts";
 import { startExplorer, type ExplorerHandle } from "./explorer/boot.ts";
 import { resolveScopes, unionRoles } from "./explorer/scopes.ts";
 import { isRecord } from "./guards.ts";
+import { applyProviderDisplay, providerPinOf, providerPinOfSelector } from "./provider-display.ts";
 import { applyProfileOverrides, formatProjectRolesReport, parseProjectRolesArgs, PROJECT_ROLES_USAGE, setupProject, type ProjectProfile } from "./project-setup.ts";
 import { DEFAULT_ROLES, findProjectAnchor, KNOWN_METRICS, PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings } from "./settings.ts";
-import { runUpdater, type Deps } from "./updater.ts";
+import { agentDir } from "./state.ts";
+import { resolveProjectDir, runUpdater, type Deps } from "./updater.ts";
+import { appendUsageRow, readUsageRows, type UsageRow } from "./usage-ledger.ts";
 
 /** SPA directory shipped beside this extension (repo `web/`). */
 const WEB_DIR = fileURLToPath(new URL("../web", import.meta.url));
@@ -71,17 +75,128 @@ function hasEmptyConversation(ctx: ExtContext): boolean {
   return true;
 }
 
-/** True when the live session model resolves from the old default selector (same provider/id, any level). */
-function sessionBootedOnOldDefault(ctx: ExtContext, oldSelector: string): boolean {
+/**
+ * True when `selector` names the live session model: the selector's base
+ * (thinking suffix stripped) resolves to a model with the same `provider` and
+ * `id` as `ctx.models.current()`. Any thinking level or provider pin is
+ * ignored. Used both to detect a session booted on the old default role and to
+ * decide whether a fallback event's selector is authoritative for the session
+ * (advisor fallbacks emit the same events with the advisor's selector).
+ */
+function liveModelIsSelector(ctx: ExtContext, selector: string): boolean {
   const current = ctx.models?.current();
-  const colon = oldSelector.lastIndexOf(":");
-  const level = colon !== -1 && oldSelector.slice(colon + 1) in THINKING_LEVELS ? oldSelector.slice(colon + 1) : null;
-  const base = level === null ? oldSelector : oldSelector.slice(0, oldSelector.length - level.length - 1);
-  const oldModel = ctx.models?.resolve(base);
-  if (current === undefined || current === null || oldModel === undefined || oldModel === null) return false;
-  if (typeof current !== "object" || typeof oldModel !== "object") return false;
-  if (!("provider" in current) || !("id" in current) || !("provider" in oldModel) || !("id" in oldModel)) return false;
-  return current.provider === oldModel.provider && current.id === oldModel.id;
+  const { base } = splitThinkingSuffix(selector);
+  const target = ctx.models?.resolve(base);
+  if (current === undefined || current === null || target === undefined || target === null) return false;
+  if (typeof current !== "object" || typeof target !== "object") return false;
+  if (!("provider" in current) || !("id" in current) || !("provider" in target) || !("id" in target)) return false;
+  return current.provider === target.provider && current.id === target.id;
+}
+
+/**
+ * Apply the provider display suffix to the live session model (spec #77).
+ * `selector` is the event's authoritative selector string when the event
+ * carries one; the live model's routing block is the fallback. The event's
+ * selector is trusted only when it names the live session model — the fallback
+ * events are also emitted for advisor fallbacks, where only the advisor's model
+ * changes and the session model is untouched. Contained: a throw must not tear
+ * down the session or escape into omp's dispatch.
+ */
+function applyProviderDisplayFor(ctx: ExtContext, selector?: string): void {
+  try {
+    const live = ctx.models?.current();
+    const eventPin = typeof selector === "string" && liveModelIsSelector(ctx, selector) ? providerPinOfSelector(selector) : null;
+    applyProviderDisplay(live, eventPin ?? providerPinOf(live));
+  } catch {
+    // display-only; never let a failure escape into omp's dispatch
+  }
+}
+
+/**
+ * Append one usage-ledger row per assistant turn in the session's branch
+ * (spec #81). The branch is the session's own record — the same entries the
+ * session jsonl persists — so each row carries the model, the provider, and the
+ * usage block omp billed. Rows already in the ledger (same timestamp + model)
+ * are skipped, so firing this on several events cannot double-record a turn.
+ *
+ * The ledger follows the plugin's state location: a project session records into
+ * `<cwd>/.omp`, so a project's usage stays separate from the user-level profile
+ * (the same dir the updater writes config/state/history to, and the same dir the
+ * role map is read from).
+ *
+ * Best-effort: a recording failure never breaks a session (and `appendUsageRow`
+ * never throws either).
+ */
+function recordUsage(ctx: ExtContext): void {
+  try {
+    const branch = ctx.sessionManager?.getBranch();
+    if (branch === undefined) return;
+    const dir = resolveProjectDir() ?? agentDir();
+    const roleByModel = configuredRoles(dir);
+    const seen = new Set(readUsageRows(dir).map((row) => `${row.ts}|${row.model}`));
+    for (const entry of branch) {
+      const row = usageRowOf(entry, roleByModel);
+      if (row === null) continue;
+      const key = `${row.ts}|${row.model}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      appendUsageRow(dir, row);
+    }
+  } catch {
+    // best-effort: the ledger never owns a session's fate
+  }
+}
+
+/**
+ * The config's role→selector map inverted to model slug → role: a turn's
+ * `message.model` names the selector's ranking id, and `currentRankingId`
+ * strips the provider prefix, the `@pin`, and the `:level` from the configured
+ * selector, so the two join. The first role wins when two share a model; an
+ * unreadable config maps nothing, so every row's role is "".
+ */
+function configuredRoles(dir: string): Map<string, string> {
+  const byModel = new Map<string, string>();
+  let text: string;
+  try {
+    text = readFileSync(join(dir, "config.yml"), "utf8");
+  } catch {
+    return byModel;
+  }
+  for (const [role, selector] of Object.entries(parseConfig(text).modelRoles)) {
+    const id = currentRankingId(selector);
+    if (id !== "" && !byModel.has(id)) byModel.set(id, role);
+  }
+  return byModel;
+}
+
+/**
+ * The ledger row for one session branch entry: an assistant message carrying a
+ * usage block. Null for every other entry (user turns, tool results, custom
+ * entries) and for a message with no usage to record.
+ */
+function usageRowOf(entry: unknown, roleByModel: ReadonlyMap<string, string>): UsageRow | null {
+  if (!isRecord(entry) || entry.type !== "message") return null;
+  const message = entry.message;
+  if (!isRecord(message) || message.role !== "assistant" || typeof message.model !== "string") return null;
+  const usage = message.usage;
+  if (!isRecord(usage)) return null;
+  const cost = isRecord(usage.cost) ? usage.cost.total : 0;
+  return {
+    ts: typeof entry.timestamp === "string" ? entry.timestamp : new Date().toISOString(),
+    role: roleByModel.get(currentRankingId(message.model)) ?? "",
+    model: message.model,
+    provider: typeof message.provider === "string" ? message.provider : "",
+    input: usageNumber(usage.input),
+    output: usageNumber(usage.output),
+    cacheRead: usageNumber(usage.cacheRead),
+    cacheWrite: usageNumber(usage.cacheWrite),
+    cost: usageNumber(cost),
+  };
+}
+
+/** A usage field as a finite number; an absent field records 0. */
+function usageNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
 /**
@@ -97,10 +212,8 @@ function makeApplySessionModel(pi: ExtensionAPI, ctx: ExtContext, notify: (lines
     if (ctx.agent.kind !== "main") return;
     if (!hasEmptyConversation(ctx)) return;
     if (previous === null) return; // first run ever wrote a fresh default; the session predates no old role
-    if (!sessionBootedOnOldDefault(ctx, previous)) return;
-    const colon = selector.lastIndexOf(":");
-    const level = colon !== -1 && selector.slice(colon + 1) in THINKING_LEVELS ? selector.slice(colon + 1) : null;
-    const base = level === null ? selector : selector.slice(0, selector.length - level.length - 1);
+    if (!liveModelIsSelector(ctx, previous)) return;
+    const { base, level } = splitThinkingSuffix(selector);
     const model = ctx.models?.resolve(base);
     if (model === undefined || model === null) {
       notify([`omp-llm-role: session model not updated — "${base}" matches no available model`]);
@@ -418,6 +531,34 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  // Provider display (spec #77): keep the live model's name suffixed with its
+  // provider pin. Never pi.setModel — that would wipe omp's in-flight fallback
+  // state and clobber the thinking level; mutate the live model's name only.
+  // Registered after the updater so the session-start pin reflects the model
+  // the run just selected.
+  pi.on("session_start", async (_event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx);
+  });
+  pi.on("retry_fallback_applied", async (event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx, event.to);
+  });
+  pi.on("retry_fallback_succeeded", async (event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx, event.model);
+  });
+  // Self-healing hook: omp restores the primary after a fallback cooldown with
+  // no session event, so re-derive the pin from the live model before each turn.
+  pi.on("turn_start", async (_event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx);
+  });
+
+  // Usage ledger (spec #81): one row per assistant turn, read from the session
+  // branch. turn_end records the turn that just finished; session_shutdown is
+  // the backstop for a headless one-turn run (a short-lived `omp -p` may exit
+  // before another turn_end). The file-side dedupe makes the second hook
+  // harmless.
+  pi.on("turn_end", async (_event, ctx: ExtContext) => recordUsage(ctx));
+  pi.on("session_shutdown", async (_event, ctx: ExtContext) => recordUsage(ctx));
+
   pi.registerCommand("refresh-roles", {
     description: "Refresh model roles from today's llm-stats/OpenRouter rankings",
     handler: async (_args, ctx: ExtContext) => {
@@ -465,6 +606,31 @@ export default function (pi: ExtensionAPI) {
             ? fetchKeyAvailability(token)
             : { active: false, reason: "unavailable", allowed: new Set(), blocked: new Set(), publicCount: 0, keyedCount: 0, fetchedAt: new Date().toISOString() };
         };
+        // Best-effort account-scoped inputs for the as-written pool: the key's
+        // tier gates the catalog, and the allowed-providers whitelist prunes the
+        // routes the account cannot call. The canary must be a CATALOG slug
+        // (`eligible[0].id`) — a ranking id 400s before the whitelist body, so
+        // the harvest would silently return nothing. Any failure (no key, an
+        // unreachable endpoint, no whitelist) degrades the pool to the raw
+        // dataset instead of blocking Explorer boot.
+        const loadPoolInputs = async (): Promise<{ tier: Tier; allowed: ReadonlySet<string> | null }> => {
+          const token = await ctx.modelRegistry.getApiKeyForProvider("openrouter").catch(() => undefined);
+          if (!token) return { tier: "billed", allowed: null };
+          let tier: Tier = "billed";
+          try {
+            tier = tierGate(await fetchKeyMeta(token));
+          } catch {
+            // an unreachable key endpoint leaves the ordinary account's tier
+          }
+          const canary = filterCatalog(catalog, tier)[0]?.id;
+          if (canary === undefined) return { tier, allowed: null };
+          try {
+            return { tier, allowed: await fetchAllowedProviders(token, canary) };
+          } catch {
+            return { tier, allowed: null };
+          }
+        };
+        const pool = await loadPoolInputs();
         explorer = await startExplorer({
           webDir: WEB_DIR,
           cwd: ctx.cwd,
@@ -472,6 +638,13 @@ export default function (pi: ExtensionAPI) {
           catalog,
           availability: await loadAvailability(),
           reloadAvailability: loadAvailability,
+          tier: pool.tier,
+          allowedProviders: pool.allowed,
+          reloadAllowedProviders: async () => (await loadPoolInputs()).allowed,
+          tokenProfile: resolveSettings(readPluginSettingsMap({ global: PLUGIN_SETTINGS_PATH, project: projectLockPath(ctx.cwd) })).settings.tokenProfile,
+          // The user-level ledger (the project scopes read their own
+          // `<root>/.omp` ledger, so the per-task column follows the scope).
+          usageDir: agentDir(),
           reload: (refresh) => loadRankData({ refresh, roles: explorerRoles(), extraMetrics: Object.keys(KNOWN_METRICS) }),
           port,
           open,