omp-llm-role 1.2.0 → 1.4.0

package/src/extension.ts

@@ -20,7 +20,8 @@ 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 { catalogFromOmpModelsJson, fetchKeyAvailability, splitThinkingSuffix, 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";
@@ -30,7 +31,9 @@ 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));
@@ -109,6 +112,93 @@ function applyProviderDisplayFor(ctx: ExtContext, selector?: string): void {
   }
 }
 
+/**
+ * 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;
+}
+
 /**
  * Apply a concrete selector (with thinking suffix) to the live session model
  * via the ExtensionAPI surface (`pi.setModel`/`pi.setThinkingLevel` — probed
@@ -461,6 +551,14 @@ export default function (pi: ExtensionAPI) {
     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) => {
@@ -508,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,
@@ -515,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,

package/src/settings.ts

@@ -16,6 +16,7 @@ import { dirname, join } from "node:path";
 import { SUFFIX_LEVELS, type RoleDef } from "./engine.ts";
 import { FEATURES, expandFeatures, featureById } from "./features.ts";
 import { isRecord } from "./guards.ts";
+import type { TokenProfile } from "./usage-ledger.ts";
 
 /** User-level plugin settings lock file (the explorer's read/export target and
  * the default source for `readPluginSettingsMap`). */
@@ -234,6 +235,13 @@ export type ResolvedSettings = {
   priceSwitchFraction: number;
   writeFallbackChains: boolean;
   fallbackChainDepth: number;
+  /**
+   * Quality floor for the fallback chain's cheaper-or-equal candidates: a
+   * candidate priced at or below the chosen model qualifies only if it retains
+   * at least this fraction of the chosen model's `q`. 0 disables the floor (any
+   * cheaper-or-equal candidate qualifies); 1 requires an exact quality match.
+   */
+  fallbackQualityFloor: number;
   roles: Record<string, RoleDef>;
   activateDefaultOnEmptySession: boolean;
   /** Opt-in reporting of unexpected plugin errors as GitHub issues on the
@@ -244,6 +252,9 @@ export type ResolvedSettings = {
   /** Global capability flags (`features.<id>`); a role's `features.<id>` overrides
    * the global in either direction. Expanded per role by `resolveSettings`. */
   features: Record<string, boolean>;
+  /** Per-task token mix for the per-task price, used when the role has no
+   *  recorded usage. `null` = no profile (the per-task price is absent). */
+  tokenProfile: TokenProfile | null;
 };
 
 export const DEFAULT_SETTINGS: ResolvedSettings = {
@@ -251,10 +262,12 @@ export const DEFAULT_SETTINGS: ResolvedSettings = {
   priceSwitchFraction: 0.5,
   writeFallbackChains: true,
   fallbackChainDepth: 2,
+  fallbackQualityFloor: 0.9,
   roles: DEFAULT_ROLES,
   activateDefaultOnEmptySession: true,
   errorReporting: "off",
   features: {},
+  tokenProfile: null,
 };
 
 /** One row of the plugin's settings schema (omp's `PluginSettingSchema`): the
@@ -301,6 +314,14 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       min: 0,
       step: 1,
     },
+    fallbackQualityFloor: {
+      type: "number",
+      description: "Quality floor for a cheaper-or-equal fallback: the fraction of the chosen model's quality it must retain (0 disables)",
+      default: DEFAULT_SETTINGS.fallbackQualityFloor,
+      min: 0,
+      max: 1,
+      step: 0.001,
+    },
     activateDefaultOnEmptySession: {
       type: "boolean",
       description: "Reapply the new default selector to an empty session's active model",
@@ -312,6 +333,16 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       default: DEFAULT_SETTINGS.errorReporting,
       values: ["off", "ask", "auto"],
     },
+    "tokenProfile.inputTokens": {
+      type: "number",
+      description: "Input tokens per task for the per-task price (used when the role has no recorded usage)",
+      min: 0,
+    },
+    "tokenProfile.outputTokens": {
+      type: "number",
+      description: "Output tokens per task for the per-task price (used when the role has no recorded usage)",
+      min: 0,
+    },
   };
   for (const row of FEATURES) {
     schema[`features.${row.id}`] = {
@@ -564,6 +595,9 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
   if (!Number.isInteger(merged.fallbackChainDepth) || merged.fallbackChainDepth < 0) {
     errors.push(`fallbackChainDepth: must be an integer >= 0, got ${JSON.stringify(merged.fallbackChainDepth)}`);
   }
+  if (typeof merged.fallbackQualityFloor !== "number" || !Number.isFinite(merged.fallbackQualityFloor) || merged.fallbackQualityFloor < 0 || merged.fallbackQualityFloor > 1) {
+    errors.push(`fallbackQualityFloor: must be a number in [0, 1], got ${JSON.stringify(merged.fallbackQualityFloor)}`);
+  }
   if (typeof merged.activateDefaultOnEmptySession !== "boolean") {
     errors.push(
       `${ACTIVATE_DEFAULT_KEY}: must be a boolean, got ${JSON.stringify(merged.activateDefaultOnEmptySession)}`,
@@ -573,6 +607,22 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
     errors.push(`errorReporting: must be one of off, ask, auto, got ${JSON.stringify(merged.errorReporting)}`);
   }
 
+  // The per-task token profile: null (no profile), or a record whose two counts
+  // are finite numbers >= 0. One error string per violation.
+  const tokenProfile: unknown = merged.tokenProfile;
+  if (tokenProfile !== null) {
+    if (!isRecord(tokenProfile)) {
+      errors.push(`tokenProfile: must be null or an object with inputTokens/outputTokens, got ${JSON.stringify(tokenProfile)}`);
+    } else {
+      for (const key of ["inputTokens", "outputTokens"] as const) {
+        const v = tokenProfile[key];
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+          errors.push(`tokenProfile.${key}: must be a number >= 0, got ${JSON.stringify(v)}`);
+        }
+      }
+    }
+  }
+
   // Global capability flags (`features.<id>`): an unknown id or a non-boolean
   // value aborts the run (a typo must never silently do nothing). A non-record
   // `features` is reset so the per-role expansion below always gets a map.

package/src/updater.ts

@@ -15,8 +15,8 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { autoPinApplies, bestRoute, computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, rankedRoutes, type Ranked, type RankData, type RoleDef } from "./engine.ts";
-import { currentRankingId, enrichThinkingLevels, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, providerAllowed, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
+import { autoPinApplies, computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, rankedRoutes, type Ranked, type RankData, type RoleDef } from "./engine.ts";
+import { currentRankingId, enrichThinkingLevels, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, probeRoute, providerAllowed, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
 import { ConfigEditError, parseConfig, patchConfig, writeConfigAtomic, type ConfigPatch } from "./config-edit.ts";
 import { PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings, roleUniverse, type ResolvedSettings } from "./settings.ts";
 import { discoverAgentPins } from "./agent-pins.ts";
@@ -41,6 +41,15 @@ export type Decision = {
   /** Ranking ids dropped by the role's provider pin (no route matching the pin) —
    * recorded like a probe-blocked candidate. */
   pinBlocked: string[];
+  /** Provider slugs the auto-pin's route probe rejected on the chosen model, in
+   * walk order — rendered `; route-blocked: …`. Slugs, not ids: the sibling
+   * `blocked` holds catalog ids and `pinBlocked` ranking ids. Empty when no
+   * probe ran. */
+  routeBlockedSlugs: string[];
+  /** True when the auto-pin applies and the model has gate-passing routes but
+   * every candidate was rejected (or the route-probe budget ran out): the
+   * selector stays bare and OpenRouter routes the request itself. */
+  pinDropped: boolean;
   /** Availability source for this role's selection: the keyed-catalog fast path or the probe walk. */
   availabilitySource: "keyed-catalog" | "probe";
   /** Candidates pruned as key-blocked (present in the public catalog, absent from the keyed one). */
@@ -68,10 +77,18 @@ export type Trigger = "session-start" | "manual";
 /** A ranked model resolved to a concrete catalog id. */
 type Candidate = { ranked: Ranked; catalogId: string };
 
-/** Per managed role: its bare chain key, role suffix, provider pin, the pool it
- * was chosen from, and the inputs the auto-pin chain builder needs (the expanded
- * def for `rankedRoutes`, and whether the pin was auto-derived). */
-type ChainPlan = { key: string; suffix: string | undefined; pin: string; pool: Candidate[]; chosenIdx: number; def: RoleDef; autoPin: boolean };
+/** Per managed role: its bare chain key, role suffix, provider pin, the
+ * candidates its chain's fallback models are drawn from, the chosen model's
+ * index in that list, and the inputs the auto-pin chain builder needs (the
+ * expanded def for `rankedRoutes`, and whether the pin was auto-derived).
+ * `candidates` is the role's ranked candidate list minus the candidates no
+ * chain entry may name (key-blocked, probe-blocked) — not the probe-clean pool
+ * — so the chain can reach a cheaper-or-equal model ranked below the probe
+ * window. `pinnedSlug` is the route the auto-pin wrote — undefined for a manual
+ * pin, for a dropped pin and with the capability off — so the chain builder can
+ * exclude the pinned route by slug rather than by its position in the route
+ * order. */
+type ChainPlan = { key: string; suffix: string | undefined; pin: string; pinnedSlug: string | undefined; candidates: Candidate[]; chosenIdx: number; def: RoleDef; autoPin: boolean };
 
 export type Deps = {
   getToken(): Promise<string>;
@@ -83,6 +100,13 @@ export type Deps = {
   getSettings?(): Promise<Record<string, unknown>>;
   getKeyMeta?(token: string): Promise<KeyMeta>;
   probeModel?(token: string, catalogId: string): Promise<ProbeVerdict>;
+  /**
+   * DI seam like `probeModel`; production defaults to the real `probeRoute`.
+   * One-token completion bound to a single provider route (`provider.only`), the
+   * auto-pin's routability gate: OpenRouter's routing table can exclude a route
+   * its endpoints API still lists as healthy.
+   */
+  probeRoute?(token: string, catalogId: string, providerSlug: string): Promise<ProbeVerdict>;
   /** DI seam like `getKeyMeta`/`probeModel`; production defaults to `fetchKeyAvailability` (never throws). */
   getKeyAvailability?(token: string): Promise<KeyAvailability>;
   /**
@@ -106,6 +130,12 @@ const CONFLICT_RETRIES = 3;
 /** Per-role cap on allowlist probe requests (budget against pathological all-blocked pools). */
 const PROBE_BUDGET = 12;
 
+/** Per-role cap on route-probe requests for the auto-pin walk (budget against a
+ * pathological route pool: a fully blocked model with dozens of routes must not
+ * turn the daily update into a long probe walk). Hitting the cap with no clean
+ * candidate drops the pin, exactly as an all-blocked pool does. */
+export const ROUTE_PROBE_BUDGET = 12;
+
 function mtimeOf(path: string): number {
   try {
     return statSync(path).mtimeMs;
@@ -120,9 +150,11 @@ function decisionLine(d: Decision): string {
   const blocked = d.blocked.length > 0 ? `; blocked: ${d.blocked.join(", ")}` : "";
   const endpoint = d.endpointBlocked.length > 0 ? `; endpoint-blocked: ${d.endpointBlocked.join(", ")}` : "";
   const pin = d.pinBlocked.length > 0 ? `; pin-blocked: ${d.pinBlocked.join(", ")}` : "";
+  const routes = d.routeBlockedSlugs.length > 0 ? `; route-blocked: ${d.routeBlockedSlugs.join(", ")}` : "";
+  const dropped = d.pinDropped ? "; pin dropped (no routable route)" : "";
   return d.from === d.to
-    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`
-    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`;
+    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin}${routes}${dropped})`
+    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin}${routes}${dropped})`;
 }
 
 /**
@@ -212,8 +244,13 @@ function writePatch(configPath: string, dir: string, patch: ConfigPatch): { stat
  * behavior applies. omp resolves the project dir as `<cwd>/.omp` with no
  * walk-up, so the plugin's project-scope read must use the same dir (not the
  * walk-up anchor `findProjectAnchor` returns).
+ *
+ * Exported as the one home for "where this session's plugin state lives": the
+ * updater scopes config/state/history/lock to it, and the extension records the
+ * usage ledger there too, so a project's usage is separate from the user-level
+ * profile.
  */
-function resolveProjectDir(): string | null {
+export function resolveProjectDir(): string | null {
   const projectDir = join(process.cwd(), ".omp");
   const raw = readPluginSettingsMap({ global: join(projectDir, "plugins", "omp-plugins.lock.json"), project: null });
   return Object.keys(raw).length > 0 ? projectDir : null;
@@ -367,6 +404,10 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
     const pinUnmatched: string[] = [];
     const probe = deps.probeModel ?? probeModel;
     const probeVerdicts = new Map<string, ProbeVerdict>();
+    const routeProbe = deps.probeRoute ?? probeRoute;
+    /** Route verdicts, cached by `catalogId@slug` across roles: a route shared by
+     * several roles is probed once per run. */
+    const routeVerdicts = new Map<string, ProbeVerdict>();
     for (const [role, def] of Object.entries(settings.roles)) {
       // Locked: no ranking, no probe, no decision, no selector/chain write.
       if (lockedRoles.has(role)) continue;
@@ -478,14 +519,50 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // `splitUpstreamRouting` parses the trailing `@<slug>` and applies
       // `compat.openRouterRouting = { only: [slug] }`.
       //
-      // Auto-pin (spec #58): with the soft `preferOwnProvider` capability on and
-      // no manual pin, the chosen model's best route by the role's own value
-      // rides as that suffix, so the price the ranking assumed is the price the
-      // request pays. A manual `providerPin` is a hard gate and always wins; a
-      // model with no candidate route keeps default routing (bare selector).
+      // Auto-pin (spec #58, routability-verified by spec #90): with the soft
+      // `preferOwnProvider` capability on and no manual pin, the best route the
+      // probe accepts rides as that suffix. That candidate is the route the role
+      // was priced on, so the price the ranking assumed is the price the request
+      // pays — but only while the walk does not skip the candidate; a skipped
+      // candidate means the route that replaced it pays, at its own price. A
+      // manual `providerPin` is a hard gate and always wins; a model with no
+      // gate-passing route keeps default routing (bare selector).
+      //
+      // The route order is the one the fallback chain already uses
+      // (`rankedRoutes`). Every candidate is probed with `provider: { only:
+      // [slug] }`, because OpenRouter's endpoints API can list a route as
+      // healthy while its routing table excludes it — the failure the endpoints
+      // data cannot see. A `blocked` route is skipped, `unknown` counts as
+      // usable (a transient blip must never unpin a role), and a pool with no
+      // clean candidate drops the pin: the selector stays bare and OpenRouter
+      // routes the request itself instead of 404ing on an unroutable `@<slug>`.
       const manualPin = def.providerPin;
-      const autoRoute = autoPinApplies(def) ? bestRoute(chosen.ranked.model, def) : null;
-      const pinSlug = manualPin ?? autoRoute?.providerSlug;
+      const autoRoutes = autoPinApplies(def) ? rankedRoutes(chosen.ranked.model, def) : [];
+      // No gate-passing route means nothing to pin and nothing to drop: the bare
+      // selector is default routing, not a dropped pin.
+      const hasAutoRoutes = autoRoutes.length > 0;
+      const routeBlockedSlugs: string[] = [];
+      let autoSlug: string | undefined;
+      let routeProbesSpent = 0;
+      for (const r of autoRoutes) {
+        const key = `${chosen.catalogId}@${r.providerSlug}`;
+        let verdict = routeVerdicts.get(key);
+        if (verdict === undefined) {
+          if (routeProbesSpent >= ROUTE_PROBE_BUDGET) break;
+          verdict = await routeProbe(token, chosen.catalogId, r.providerSlug);
+          routeVerdicts.set(key, verdict);
+          routeProbesSpent++;
+        }
+        if (verdict === "blocked") {
+          // Deduped: two routes can share a provider slug (the chain collapses
+          // them too), and the decision line should not list one slug twice.
+          if (!routeBlockedSlugs.includes(r.providerSlug)) routeBlockedSlugs.push(r.providerSlug);
+          continue;
+        }
+        autoSlug = r.providerSlug;
+        break;
+      }
+      const pinSlug = manualPin ?? autoSlug;
       const pin = pinSlug !== undefined ? `@${pinSlug}` : "";
       const chosenRow = rowById.get(chosen.catalogId);
       // Append only a level the model's catalog thinking[] actually supports —
@@ -504,16 +581,28 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         blocked: blockedForRole,
         endpointBlocked: endpointFilterDrops(def, rank.models),
         pinBlocked: providerPinDrops(def, rank.models),
+        routeBlockedSlugs,
+        pinDropped: hasAutoRoutes && autoSlug === undefined,
         availabilitySource: availability.active ? "keyed-catalog" : "probe",
         keyBlockedCount,
       });
 
       // Fallback chain inputs for every managed role: the bare key (a chain key
-      // matches the active model id, never a level) plus the pool the chosen model
-      // came from. Values are built after the loop, once every key claim is known.
+      // matches the active model id, never a level) plus the candidate list the
+      // chain's fallback models are drawn from. Values are built after the loop,
+      // once every key claim is known.
       if (settings.writeFallbackChains) {
         const key = suffix !== undefined && finalSelector.endsWith(`:${suffix}`) ? finalSelector.slice(0, -(suffix.length + 1)) : finalSelector;
-        chainPlanByRole[role] = { key, suffix, pin, pool, chosenIdx: pool.indexOf(chosen), def, autoPin: autoRoute !== null };
+        // The chain's fallback models come from the role's whole ranked
+        // candidate list, so a cheaper-or-equal model ranked below the probe
+        // window can be chained. Only the candidates the probe walk would never
+        // accept are dropped — key-blocked (the account's key cannot use them)
+        // and probe-verdict-blocked (present in the public catalog but not for
+        // this key). An unprobed candidate stays: the chain's deeper entries are
+        // no longer required to be probe-verified. The chosen model passed both
+        // predicates, so it is always in the list and `chosenIdx` is never -1.
+        const chainCandidates = candidates.filter((c) => !keyBlocked(c) && probeVerdicts.get(c.catalogId) !== "blocked");
+        chainPlanByRole[role] = { key, suffix, pin, pinnedSlug: autoSlug, candidates: chainCandidates, chosenIdx: chainCandidates.indexOf(chosen), def, autoPin: hasAutoRoutes };
       }
     }
 
@@ -534,13 +623,18 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       for (const d of decisions) {
         const plan = chainPlanByRole[d.role];
         const suffix = claims[plan.key] === 1 ? plan.suffix : undefined;
-        // Cost-aware ordering: prefer fallbacks priced at or below the chosen
-        // model (a fallback should not cost more than the primary), then fill any
-        // remaining depth with the next-best by value.
-        const after = plan.pool.slice(plan.chosenIdx + 1);
-        const chosenPrice = plan.pool[plan.chosenIdx].ranked.priceEff;
-        const cheaper = after.filter((p) => p.ranked.priceEff <= chosenPrice);
-        const pricier = after.filter((p) => p.ranked.priceEff > chosenPrice);
+        // Cost-aware ordering with a quality floor: prefer fallbacks priced at or
+        // below the chosen model that still retain `fallbackQualityFloor` of its
+        // quality (a failover must not silently drop the role onto a much weaker
+        // model), then fill any remaining depth with the next-best by value. The
+        // floor and the `after` set both key off the chosen model — the leader on
+        // a fresh pick, the kept current candidate on a kept role — and the floor
+        // never filters the pricier set, so a cheap-but-weak candidate set cannot
+        // starve the chain.
+        const after = plan.candidates.slice(plan.chosenIdx + 1);
+        const chosen = plan.candidates[plan.chosenIdx];
+        const cheaper = after.filter((p) => p.ranked.priceEff <= chosen.ranked.priceEff && p.ranked.q >= chosen.ranked.q * settings.fallbackQualityFloor);
+        const pricier = after.filter((p) => p.ranked.priceEff > chosen.ranked.priceEff);
         const chainPool = [...cheaper, ...pricier].slice(0, settings.fallbackChainDepth);
         // A chain value's thinking level is appended only when the target's
         // catalog entry advertises support (or the level is a meta level).
@@ -551,7 +645,7 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         const values: string[] = [];
         if (plan.autoPin) {
           // Auto-pin chain (spec #58, expanded by #69): every gate-passing route
-          // of the primary model (all but the pinned best), then every
+          // of the primary model except the pinned route, then every
           // gate-passing route of each fallback model, in the role's
           // value-for-money score order (`rankedRoutes`, spec #71) — every entry
           // bound to its route's provider, so a down primary
@@ -559,12 +653,17 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
           // than a different model. `rankedRoutes` already applies every gate
           // (non-degraded, endpoint filters, usable billed price, the
           // maxPriceUsdPerM cap, the allowed-providers whitelist), so the chain
-          // carries exactly the routes the role can use. The dedup below
-          // collapses two routes that share a provider slug (same chain value),
-          // so the chain length is (R_primary − 1) + Σ R_fallback over distinct
-          // gate-passing provider slugs.
-          const chosenCandidate = plan.pool[plan.chosenIdx];
-          for (const r of rankedRoutes(chosenCandidate.ranked.model, plan.def).slice(1)) {
+          // carries exactly the routes the role can use. The pin is excluded by
+          // slug, not by position: the route probe can pin a route other than
+          // the score leader, and with a dropped pin no route is excluded at
+          // all. The dedup below collapses two routes that share a provider slug
+          // (same chain value), so the chain length is (R_primary − 1) + Σ
+          // R_fallback over distinct gate-passing provider slugs (R_primary with
+          // no pin). Only the pinned route is probe-verified: one unroutable
+          // chain entry is survivable, omp fails over.
+          const chosenCandidate = plan.candidates[plan.chosenIdx];
+          for (const r of rankedRoutes(chosenCandidate.ranked.model, plan.def)) {
+            if (r.providerSlug === plan.pinnedSlug) continue;
             values.push(`openrouter/${chosenCandidate.catalogId}@${r.providerSlug}${levelFor(chosenCandidate.catalogId)}`);
           }
           for (const p of chainPool) {