omp-llm-role 1.0.0 → 1.2.0

package/src/updater.ts

@@ -1,7 +1,11 @@
 /**
- * Orchestration (SPEC §6–9): rank today's models -> tier gate + catalog
+ * Orchestration: rank today's models -> tier gate + catalog
  * resolution -> per-role hysteresis -> fallback chains -> surgical config patch.
  *
+ * When the account's OpenRouter keyed catalog is active it is the
+ * availability source: allowed candidates skip the probe, key-blocked ones are
+ * pruned from the walk order, and only candidates in neither catalog are probed.
+ *
  * Every abort path notifies and returns `aborted` without touching config.yml.
  * A run with zero changes writes nothing (config mtime untouched) but still
  * stamps the day gate and appends a history row. Both entry points (the omp
@@ -10,12 +14,13 @@
  */
 
 import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { computeRankings, loadRankData, META_LEVELS, type Ranked, type RankData } from "./engine.ts";
-import { currentRankingId, enrichThinkingLevels, fetchKeyMeta, filterCatalog, probeModel, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyMeta, type ProbeVerdict } from "./availability.ts";
+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 { ConfigEditError, parseConfig, patchConfig, writeConfigAtomic, type ConfigPatch } from "./config-edit.ts";
-import { readPluginSettingsMap, resolveSettings, roleUniverse, type ResolvedSettings } from "./settings.ts";
+import { PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings, roleUniverse, type ResolvedSettings } from "./settings.ts";
 import { discoverAgentPins } from "./agent-pins.ts";
+import { registerProject } from "./project-registry.ts";
 import { agentDir, acquireLock, appendHistory, loadState, releaseLock, saveState } from "./state.ts";
 
 export type DecisionReason = "adopted" | "switched" | "switched-cost" | "kept-margin" | "kept-eligible" | "no-current";
@@ -30,6 +35,16 @@ export type Decision = {
   currentValue: number | null;
   /** Catalog ids probed blocked (provider allowlist) while selecting this role. */
   blocked: string[];
+  /** Ranking ids dropped by the role's endpoint capability filters (no capable
+   * standard-tier route) — recorded like a probe-blocked candidate. */
+  endpointBlocked: string[];
+  /** Ranking ids dropped by the role's provider pin (no route matching the pin) —
+   * recorded like a probe-blocked candidate. */
+  pinBlocked: string[];
+  /** 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). */
+  keyBlockedCount: number;
 };
 
 export type RunResult = {
@@ -38,6 +53,14 @@ export type RunResult = {
   /** Final selector the run chose for the `default` role, when that role was decided. */
   defaultSelector?: string;
   aborted?: string;
+  /**
+   * Set only on an unexpected exception abort (a bug): the `ConfigEditError` /
+   * catch-all path. Unset on every enumerated environment abort (settings
+   * invalid, ranking data unavailable, tier `none`, lock, conflict, key-fetch
+   * failure) — those are conditions, not defects. The extension reads this to
+   * decide whether to file a report.
+   */
+  defect?: string;
 };
 
 export type Trigger = "session-start" | "manual";
@@ -45,6 +68,11 @@ 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 };
+
 export type Deps = {
   getToken(): Promise<string>;
   getCatalog(): Promise<CatalogEntry[]>;
@@ -55,6 +83,15 @@ export type Deps = {
   getSettings?(): Promise<Record<string, unknown>>;
   getKeyMeta?(token: string): Promise<KeyMeta>;
   probeModel?(token: string, catalogId: string): Promise<ProbeVerdict>;
+  /** DI seam like `getKeyMeta`/`probeModel`; production defaults to `fetchKeyAvailability` (never throws). */
+  getKeyAvailability?(token: string): Promise<KeyAvailability>;
+  /**
+   * DI seam like `getKeyAvailability`; production defaults to
+   * `fetchAllowedProviders` (never throws). Returns the account's
+   * allowed-providers privacy whitelist, or null when there is none (or the
+   * harvest failed) — a null result leaves every route pool untouched.
+   */
+  getAllowedProviders?(token: string, modelId: string): Promise<Set<string> | null>;
   /**
    * Host coupling (extension only): apply a concrete selector to the live
    * session model. Receives the final `default` selector (with thinking
@@ -81,13 +118,15 @@ function decisionLine(d: Decision): string {
   const from = d.from ?? "(unset)";
   const scores = `value ${d.value.toFixed(3)}, best ${d.bestValue.toFixed(3)}${d.currentValue == null ? "" : `, was ${d.currentValue.toFixed(3)}`}`;
   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(", ")}` : "";
   return d.from === d.to
-    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked})`
-    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked})`;
+    ? `@${d.role}: kept ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`
+    : `@${d.role}: ${from} -> ${d.to} (${d.reason}; ${scores}${blocked}${endpoint}${pin})`;
 }
 
 /**
- * Cost-side escape from the hysteresis margin (SPEC §7). `switchMargin` is a
+ * Cost-side escape from the hysteresis margin. `switchMargin` is a
  * flat band on `value`, so it can veto a switch worth up to `switchMargin / λ`
  * $/M while the incumbent is only marginally better — e.g. a role at λ 0.003
  * refuses up to $7/M of savings. A challenger inside that band is adopted when
@@ -167,6 +206,19 @@ function writePatch(configPath: string, dir: string, patch: ConfigPatch): { stat
   }
 }
 
+/**
+ * The project dir omp reads for the current session (`<cwd>/.omp`), or null when
+ * the project carries no `omp-llm-role` settings entry — then the global
+ * 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).
+ */
+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;
+}
+
 export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?: boolean; dryRun?: boolean }): Promise<RunResult> {
   const notifyAll = trigger !== "session-start" || opts?.dryRun === true;
   const abort = (lines: string[]): RunResult => {
@@ -174,9 +226,19 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
     return { decisions: [], wrote: false, aborted: lines[0] };
   };
   try {
-    const state = loadState();
+    // Project-aware resolution (issue #27): when the project has its own role
+    // config, the whole run — config, state, history, lock — is scoped to
+    // `<cwd>/.omp`; otherwise the global agent dir is used exactly as before.
+    const projectDir = resolveProjectDir();
+    // Register the project in the global registry (issue #28) immediately after
+    // resolution and before any early return, so a day-stamped no-op session
+    // start still records it. Dry runs register nothing. The registry lives in
+    // the global agent dir, never the project's `.omp`.
+    if (projectDir !== null && opts?.dryRun !== true) registerProject(dirname(projectDir));
+    const dir = projectDir ?? agentDir();
+    const state = loadState(dir);
     const today = deps.nowUtcDay();
-    const raw = (await deps.getSettings?.()) ?? readPluginSettingsMap();
+    const raw = (await deps.getSettings?.()) ?? readPluginSettingsMap(projectDir !== null ? { global: PLUGIN_SETTINGS_PATH, project: projectLockPath() } : undefined);
     const { settings, errors } = resolveSettings(raw);
     if (errors.length > 0) return abort([`omp-llm-role settings invalid, no write:`, ...errors.map((e) => `  ${e}`)]);
 
@@ -189,7 +251,6 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         .map(([n]) => n),
     );
 
-    const dir = agentDir();
     const configPath = join(dir, "config.yml");
     const agentDisables = agentDisablePatch(raw, settings, state.managedDisabledAgents);
     const nextManagedDisabled = agentDisables.agentDisableAdds;
@@ -216,8 +277,17 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       return abort([`omp-llm-role: ranking data unavailable, no write: ${err instanceof Error ? err.message : err}`]);
     }
 
-    const token = await deps.getToken();
-    const keyMeta = (await deps.getKeyMeta?.(token)) ?? (await fetchKeyMeta(token));
+    // A key-fetch failure (a missing/expired token, an OpenRouter outage) is an
+    // enumerated environment abort, not a defect: notify-only, `defect` unset.
+    // The message text is unchanged from the catch-all it used to reach.
+    let token: string;
+    let keyMeta: KeyMeta;
+    try {
+      token = await deps.getToken();
+      keyMeta = (await deps.getKeyMeta?.(token)) ?? (await fetchKeyMeta(token));
+    } catch (err) {
+      return abort([`omp-llm-role: aborted, no write: ${err instanceof Error ? err.message : String(err)}`]);
+    }
     const tier = tierGate(keyMeta);
     if (tier === "none") {
       return abort([
@@ -228,6 +298,10 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
 
     const catalog = await deps.getCatalog();
     const eligible = filterCatalog(catalog, tier);
+    // Keyed-catalog availability: fetched once per run and shared
+    // across roles. Never throws — an unavailable allowlist degrades to the
+    // probe walk with no abort path.
+    const availability = await (deps.getKeyAvailability?.(token) ?? fetchKeyAvailability(token));
     const rowById = new Map(eligible.map((c) => [c.id, c]));
     enrichThinkingLevels(rank.models, catalog);
 
@@ -239,15 +313,58 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
     }
     const current = parseConfig(configText);
 
-    // Per-role selection: rank -> tier/catalog filter -> probe gate ->
-    // hysteresis -> suffix. The probe walk verifies candidates with one-token
-    // completions because the key's allowed-providers privacy whitelist is
-    // invisible to /api/v1/key and the catalog endpoints (SPEC §5 addendum).
+    // Per-role selection: rank -> tier/catalog filter -> availability gate ->
+    // hysteresis -> suffix. When the keyed catalog is active it classifies
+    // candidates without a request (allowed -> clean, key-blocked -> pruned);
+    // the probe walk still verifies candidates in neither catalog with
+    // one-token completions, because the key's allowed-providers privacy
+    // whitelist is otherwise invisible to /api/v1/key and the catalog
+    // endpoints.
     const decisions: Decision[] = [];
     const notes: string[] = [];
+    if (availability.active) {
+      notes.push(
+        `omp-llm-role: OpenRouter keyed catalog active — ${availability.keyedCount}/${availability.publicCount} models allowed; key-blocked candidates are pruned from the probe walk (up to ${PROBE_BUDGET} probes/role saved)`,
+      );
+    } else {
+      notes.push(
+        `omp-llm-role: OpenRouter keyed catalog ${availability.reason === "no-filter" ? "not filtering" : "unavailable"} — enable OpenRouter → Settings → "Filter the model catalog for API keys" to skip probing key-blocked models; the probe walk is still in use`,
+      );
+    }
+
+    // Allowed-providers privacy whitelist (spec #65): harvested once per run
+    // with a valid catalog model id (the canary 404s, so it bills no tokens).
+    // The whitelist is invisible to /api/v1/key and the catalog endpoints, so a
+    // route on a provider outside it would be written into config.yml and 404
+    // at request time. Pruning every model's route pool to allowed providers
+    // before ranking makes the soft basis, the auto-pin and the fallback chains
+    // whitelist-aware through the single `m.routes` seam. A null result (no
+    // whitelist set / harvest failed) leaves the pools untouched.
+    const canaryModelId = eligible[0]?.id;
+    const allowed =
+      canaryModelId === undefined
+        ? null
+        : await (deps.getAllowedProviders ? deps.getAllowedProviders(token, canaryModelId) : fetchAllowedProviders(token, canaryModelId));
+    if (allowed !== null) {
+      let prunedCount = 0;
+      const pruned = rank.models.map((m) => {
+        const routes = m.routes;
+        if (routes === undefined) return m;
+        const kept = routes.filter((r) => providerAllowed(allowed, r.providerSlug));
+        prunedCount += routes.length - kept.length;
+        return { ...m, routes: kept };
+      });
+      rank = { ...rank, models: pruned };
+      notes.push(
+        `omp-llm-role: OpenRouter allowed-providers whitelist active — ${allowed.size} providers; ${prunedCount} routes pruned`,
+      );
+    } else {
+      notes.push(`omp-llm-role: OpenRouter allowed-providers whitelist: no whitelist`);
+    }
     const poolByRole: Record<string, Candidate[]> = {};
-    /** Per managed role: its bare chain key, role suffix, and the pool it was chosen from. */
-    const chainPlanByRole: Record<string, { key: string; suffix: string | undefined; pool: Candidate[]; chosenIdx: number }> = {};
+    const chainPlanByRole: Record<string, ChainPlan> = {};
+    /** Roles whose `providerPin` matched no route: left unchanged, their current chain preserved. */
+    const pinUnmatched: string[] = [];
     const probe = deps.probeModel ?? probeModel;
     const probeVerdicts = new Map<string, ProbeVerdict>();
     for (const [role, def] of Object.entries(settings.roles)) {
@@ -259,12 +376,41 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         const catalogId = resolveVariant(ranked.model.id, eligible, tier);
         if (catalogId !== null) candidates.push({ ranked, catalogId });
       }
-      if (candidates.length === 0) continue; // nothing eligible — role untouched
+      if (candidates.length === 0) {
+        // A pin that matches no route must never silently unpin: leave the role
+        // unchanged (no selector write, no chain write) and say so. The ranking
+        // already drops route-less models for a pinned role, so an empty pool
+        // here means the pin matched nothing.
+        if (def.providerPin !== undefined) {
+          notes.push(`@${role}: providerPin "${def.providerPin}" matches no route — role untouched`);
+          pinUnmatched.push(role);
+        }
+        continue; // nothing eligible — role untouched
+      }
 
       const currentSelector = current.modelRoles[role] ?? null;
       const currentId = currentSelector === null ? null : currentRankingId(currentSelector);
       const currentIdx = currentId === null ? -1 : candidates.findIndex((c) => c.ranked.model.id === currentId);
 
+      // Keyed-catalog fast path: when the account's OpenRouter
+      // filter is on, membership in the keyed catalog is authoritative — an
+      // allowed candidate is clean without a probe, and a key-blocked one is
+      // pruned from the walk order entirely. Pruning (not pre-seeding a
+      // "blocked" verdict) is load-bearing: the budget counts candidates
+      // *examined*, so a pre-seeded blocked candidate would still consume it
+      // and reproduce the all-blocked-pool failure this path exists to fix.
+      const keyBlocked = (c: Candidate) => availability.active && availability.blocked.has(c.ranked.model.id);
+      if (availability.active) {
+        for (const c of candidates) {
+          if (availability.allowed.has(c.ranked.model.id)) probeVerdicts.set(c.catalogId, "ok");
+        }
+      }
+      const keyBlockedCount = candidates.filter(keyBlocked).length;
+      // A key-blocked current candidate is not the walk's current: it will
+      // never be kept, so the stop condition must not demand extra clean
+      // candidates beyond it.
+      const currentWalkIdx = currentIdx >= 0 && !keyBlocked(candidates[currentIdx]) ? currentIdx : -1;
+
       // Probe walk: current candidate first (hysteresis must see it), then rank
       // order. It stops only when 1 + chain depth clean candidates exist AND —
       // when the current candidate is clean — `fallbackChainDepth` clean
@@ -273,9 +419,9 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // the graceful degradation); verdicts cached across roles.
       const target = 1 + settings.fallbackChainDepth;
       const order: number[] = [];
-      if (currentIdx >= 0) order.push(currentIdx);
+      if (currentWalkIdx >= 0) order.push(currentWalkIdx);
       for (let i = 0; i < candidates.length; i++) {
-        if (i !== currentIdx) order.push(i);
+        if (i !== currentWalkIdx && !keyBlocked(candidates[i])) order.push(i);
       }
       const probed: number[] = [];
       const blockedForRole: string[] = [];
@@ -294,9 +440,9 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
           blockedForRole.push(id);
         } else {
           cleanCount++;
-          if (currentIdx >= 0 && idx > currentIdx) cleanAfterCurrent++;
+          if (currentWalkIdx >= 0 && idx > currentWalkIdx) cleanAfterCurrent++;
         }
-        const currentClean = currentIdx >= 0 && probeVerdicts.get(candidates[currentIdx].catalogId) !== "blocked";
+        const currentClean = currentWalkIdx >= 0 && probeVerdicts.get(candidates[currentWalkIdx].catalogId) !== "blocked";
         if (cleanCount >= target && (!currentClean || cleanAfterCurrent >= settings.fallbackChainDepth)) break;
       }
       const pool = probed
@@ -304,7 +450,8 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         .sort((a, b) => a - b)
         .map((idx) => candidates[idx]);
       if (pool.length === 0) {
-        notes.push(`@${role}: no probe-clean candidate among ${probed.length} probed (blocked: ${blockedForRole.join(", ")}) — role untouched`);
+        const keyed = availability.active ? `key-blocked: ${keyBlockedCount}, ` : "";
+        notes.push(`@${role}: no probe-clean candidate among ${probed.length} probed (${keyed}blocked: ${blockedForRole.join(", ")}) — role untouched`);
         continue;
       }
       poolByRole[role] = pool;
@@ -326,12 +473,26 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       }
 
       const suffix = def.thinking;
+      // A provider pin rides as the selector's `@<slug>` suffix, before the
+      // thinking level (`openrouter/<id>@<slug>:<level>`) — omp's
+      // `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).
+      const manualPin = def.providerPin;
+      const autoRoute = autoPinApplies(def) ? bestRoute(chosen.ranked.model, def) : null;
+      const pinSlug = manualPin ?? autoRoute?.providerSlug;
+      const pin = pinSlug !== undefined ? `@${pinSlug}` : "";
       const chosenRow = rowById.get(chosen.catalogId);
       // Append only a level the model's catalog thinking[] actually supports —
       // omp clamps unsupported levels, so an unsupported pin would run at a
       // different effort than the role intends (and than the ranking priced).
       const appendSuffix = suffix !== undefined && chosenRow !== undefined && (META_LEVELS[suffix] === true || chosenRow.thinking.includes(suffix));
-      const finalSelector = `openrouter/${chosen.catalogId}${appendSuffix ? `:${suffix}` : ""}`;
+      const finalSelector = `openrouter/${chosen.catalogId}${pin}${appendSuffix ? `:${suffix}` : ""}`;
       decisions.push({
         role,
         from: currentSelector,
@@ -341,6 +502,10 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         bestValue: best.ranked.value,
         currentValue: currentEntry?.ranked.value ?? null,
         blocked: blockedForRole,
+        endpointBlocked: endpointFilterDrops(def, rank.models),
+        pinBlocked: providerPinDrops(def, rank.models),
+        availabilitySource: availability.active ? "keyed-catalog" : "probe",
+        keyBlockedCount,
       });
 
       // Fallback chain inputs for every managed role: the bare key (a chain key
@@ -348,7 +513,7 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // came 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, pool, chosenIdx: pool.indexOf(chosen) };
+        chainPlanByRole[role] = { key, suffix, pin, pool, chosenIdx: pool.indexOf(chosen), def, autoPin: autoRoute !== null };
       }
     }
 
@@ -377,19 +542,49 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         const cheaper = after.filter((p) => p.ranked.priceEff <= chosenPrice);
         const pricier = after.filter((p) => p.ranked.priceEff > chosenPrice);
         const chainPool = [...cheaper, ...pricier].slice(0, settings.fallbackChainDepth);
-        chainUpserts[plan.key] = [
-          ...new Set(chainPool.map((p) => {
-            const row = rowById.get(p.catalogId);
-            const level = suffix !== undefined && row !== undefined && (META_LEVELS[suffix] === true || row.thinking.includes(suffix)) ? `:${suffix}` : "";
-            return `openrouter/${p.catalogId}${level}`;
-          })),
-        ].filter((v) => v !== plan.key);
+        // A chain value's thinking level is appended only when the target's
+        // catalog entry advertises support (or the level is a meta level).
+        const levelFor = (catalogId: string): string => {
+          const row = rowById.get(catalogId);
+          return suffix !== undefined && row !== undefined && (META_LEVELS[suffix] === true || row.thinking.includes(suffix)) ? `:${suffix}` : "";
+        };
+        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
+          // 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
+          // provider falls back to the same model on another provider rather
+          // 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)) {
+            values.push(`openrouter/${chosenCandidate.catalogId}@${r.providerSlug}${levelFor(chosenCandidate.catalogId)}`);
+          }
+          for (const p of chainPool) {
+            for (const r of rankedRoutes(p.ranked.model, plan.def)) {
+              values.push(`openrouter/${p.catalogId}@${r.providerSlug}${levelFor(p.catalogId)}`);
+            }
+          }
+        } else {
+          // Manual pin (every value carries it) or no pin (bare values).
+          for (const p of chainPool) values.push(`openrouter/${p.catalogId}${plan.pin}${levelFor(p.catalogId)}`);
+        }
+        chainUpserts[plan.key] = [...new Set(values)].filter((v) => v !== plan.key);
         referenced.add(plan.key);
       }
       // Locked roles keep their current chain: the plugin neither rewrites nor
       // prunes it, so its key must count as referenced. A chain key is the
       // current selector minus a trailing `:level` (chain keys are level-free).
-      for (const role of lockedRoles) {
+      // A role whose pin matched no route is likewise left unchanged, so its
+      // current chain must survive the prune.
+      for (const role of [...lockedRoles, ...pinUnmatched]) {
         const sel = current.modelRoles[role];
         if (sel === undefined) continue;
         const colon = sel.lastIndexOf(":");
@@ -414,7 +609,7 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       const previousRoles = res.status === "written" && res.before !== null ? parseConfig(res.before).modelRoles : null;
 
       state.lastRunDay = today;
-      state.managedRoles = [...decisions.map((d) => d.role), ...lockedRoles];
+      state.managedRoles = [...decisions.map((d) => d.role), ...lockedRoles, ...pinUnmatched];
       state.managedDisabledAgents = nextManagedDisabled;
       for (const d of decisions) state.roleLastSelector[d.role] = d.to;
       if (settings.writeFallbackChains) state.pluginWrittenChainKeys = [...referenced];
@@ -466,7 +661,9 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
   } catch (err) {
     const message = err instanceof ConfigEditError ? `config edit refused: ${err.message}` : err instanceof Error ? err.message : String(err);
     deps.notify([`omp-llm-role: aborted, no write: ${message}`]);
-    return { decisions: [], wrote: false, aborted: message };
+    // An exception escaping the run is a defect (a bug), unlike the enumerated
+    // environment aborts above: mark it so the extension can report it.
+    return { decisions: [], wrote: false, aborted: message, defect: message };
   }
 }