omp-llm-role 1.0.0 → 1.2.0

package/src/role-archetypes.ts

@@ -16,6 +16,7 @@
  */
 
 import type { SuffixLevel } from "./engine.ts";
+import type { FeatureId } from "./features.ts";
 import { DEFAULT_ROLES } from "./settings.ts";
 
 export type Archetype = {
@@ -33,6 +34,14 @@ export type Archetype = {
   tools: string[];
   /** Require image input (`filters.image`). */
   image?: boolean;
+  /**
+   * Capability flags the archetype proposes for a role fitted to it. **No
+   * shipped archetype sets one**: a plugin-created role starts from nothing
+   * unless the user asks (`--feature`), so creating an agent never silently
+   * changes what the role ranks on. The field exists so a future archetype can
+   * propose a preset without a second mechanism.
+   */
+  features?: FeatureId[];
   /** Bullets for the generated agent body's `<criteria>` section. */
   criteria: string[];
 };
@@ -128,8 +137,9 @@ export const ARCHETYPES: readonly Archetype[] = [
     id: "design",
     label: "design specialist",
     keywords: ["design", "ui", "ux", "visual", "layout", "style", "css", "frontend", "mockup", "wireframe", "screenshot", "image", "logo", "brand", "accessib", "typograph"],
-    weights: { vision: 0.3, website: 0.2, general: 0.2, code: 0.1, price: 0.12, throughput: 0.08 },
-    required: ["general", "price", "throughput"],
+    // The shipped `designer` role's own weights: one canonical design weighting.
+    weights: DEFAULT_ROLES.designer.weights,
+    required: DEFAULT_ROLES.designer.required,
     thinking: "auto",
     tools: ["read", "grep", "glob", "find", "write", "edit"],
     image: true,

package/src/role-settings.ts

@@ -45,14 +45,36 @@ export function mergeExport(existing: unknown, dirty: Record<string, RoleDef>):
       if (Object.keys(nested).length === 0) delete plugin.roles;
     }
 
+    // An Export means "make this role's keys match this def", so a key the def
+    // no longer carries (a capability flag set back to inherit, a cleared knob,
+    // a dropped filter) is removed rather than left stale. Same prefix rule as
+    // `mergeRemove` below.
     const prefix = `roles.${name}`;
+    for (const key of Object.keys(plugin)) {
+      if (key === prefix || key.startsWith(`${prefix}.`)) delete plugin[key];
+    }
+
     plugin[`${prefix}.description`] = def.description;
     if (def.enabled !== undefined) plugin[`${prefix}.enabled`] = def.enabled;
     if (def.locked !== undefined) plugin[`${prefix}.locked`] = def.locked;
     plugin[`${prefix}.required`] = def.required;
     if (def.thinking !== undefined) plugin[`${prefix}.thinking`] = def.thinking;
+    if (def.providerPin !== undefined) plugin[`${prefix}.providerPin`] = def.providerPin;
+    if (def.preferOwnProvider !== undefined) plugin[`${prefix}.preferOwnProvider`] = def.preferOwnProvider;
+    if (def.cacheHitRate !== undefined) plugin[`${prefix}.cacheHitRate`] = def.cacheHitRate;
     if (def.lambda !== undefined) plugin[`${prefix}.lambda`] = def.lambda;
     if (def.filters?.image !== undefined) plugin[`${prefix}.filters.image`] = def.filters.image;
+    if (def.filters?.tools !== undefined) plugin[`${prefix}.filters.tools`] = def.filters.tools;
+    if (def.filters?.minContextTokens !== undefined) plugin[`${prefix}.filters.minContextTokens`] = def.filters.minContextTokens;
+    if (def.filters?.minOutputTokens !== undefined) plugin[`${prefix}.filters.minOutputTokens`] = def.filters.minOutputTokens;
+    if (def.filters?.maxPriceUsdPerM !== undefined) plugin[`${prefix}.filters.maxPriceUsdPerM`] = def.filters.maxPriceUsdPerM;
+    // The capability flags are written as flat dotted keys too, so omp's
+    // shallow settings merge keeps them and `mergeRemove`'s `roles.<name>.`
+    // prefix deletes them with the rest of the role. Both `true` and `false`
+    // are written: a per-role `false` is how a role opts out of a global flag.
+    if (def.features !== undefined) {
+      for (const [id, on] of Object.entries(def.features)) plugin[`${prefix}.features.${id}`] = on;
+    }
     for (const [metric, weight] of Object.entries(def.weights)) plugin[`${prefix}.weights.${metric}`] = weight;
   }
   return { lock };

package/src/settings.ts

@@ -3,7 +3,7 @@
  * overrides from the omp plugin settings map.
  *
  * Source of truth (decision D1): `~/.omp/plugins/omp-plugins.lock.json` ->
- * `settings["omp-llm-role"]`, with `<anchor>/.omp/plugins/omp-plugins.lock.json`
+ * `settings["omp-llm-role"]`, with `<cwd>/.omp/plugins/omp-plugins.lock.json`
  * merged under it (project wins). Keys are flat and dotted
  * (`roles.slow.weights.code=0.2`, written by `omp plugin config omp-llm-role
  * --set=k=v`) and are nested here; a `config` key holding JSON is accepted as a
@@ -14,6 +14,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 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";
 
 /** User-level plugin settings lock file (the explorer's read/export target and
@@ -23,7 +24,7 @@ export const PLUGIN_SETTINGS_PATH = join(homedir(), ".omp", "plugins", "omp-plug
 export const DEFAULT_ROLES: Record<string, RoleDef> = {
   default: {
     description: "Main workhorse: strong general coding-agent quality, sane cost",
-    weights: { general: 0.3221, reasoning: 0.1705, code: 0.1705, agents: 0.1137, tool_calling: 0.0947, throughput: 0.0285, price: 0.1 },
+    weights: { general: 0.4926, code: 0.1705, agents: 0.1137, tool_calling: 0.0947, throughput: 0.0285, price: 0.1 },
     required: ["general", "price", "throughput"],
     // `auto`, not bare: the session default is `auto` (config.yml
     // `defaultThinkingLevel`), so a bare selector runs at auto effort while
@@ -32,13 +33,13 @@ export const DEFAULT_ROLES: Record<string, RoleDef> = {
   },
   smol: {
     description: "Fast lightweight model: cheap and quick, still competent",
-    weights: { price: 0.3, throughput: 0.28, general: 0.2, code: 0.12, tool_calling: 0.1 },
+    weights: { price: 0.45, throughput: 0.22, general: 0.1571, code: 0.0943, tool_calling: 0.0786 },
     required: ["general", "price", "throughput"],
     thinking: "off",
   },
   slow: {
     description: "Most capable model for hard problems; cost and speed as tiebreakers",
-    weights: { general: 0.26, reasoning: 0.26, code: 0.18, agents: 0.13, math: 0.08, throughput: 0.04, price: 0.05 },
+    weights: { general: 0.60, code: 0.18, agents: 0.13, throughput: 0.04, price: 0.05 },
     required: ["general", "price", "throughput"],
     thinking: "high",
   },
@@ -50,8 +51,19 @@ export const DEFAULT_ROLES: Record<string, RoleDef> = {
     filters: { image: true },
   },
   plan: {
-    description: "Planning: reasoning, math, long-context coherence",
-    weights: { reasoning: 0.3129, general: 0.2542, long_context: 0.1369, math: 0.1369, throughput: 0.0391, price: 0.12 },
+    description: "Planning: reasoning and long-context coherence, priced so the cheapest capable planner wins",
+    // 2026-10-03 (issue #16): `price` raised 0.12 → 0.25 so the cost posture
+    // binds on the *reachable* pool — the pool the selector is chosen from.
+    // Measured reachable leader-flip w_price 0.2175 (Hy4 preview →
+    // DeepSeek-V4.1-Flash) vs full-pool 0.311 (Muse Spark 1.3 → Qwen3.8 Flash),
+    // so 0.25 flips the actionable decision while leaving the full-pool #1
+    // unchanged. Non-price weights rescaled by (1−0.25)/(1−0.12) = 0.852273:
+    // general 0.704 → 0.6, long_context 0.1369 → 0.116676, throughput 0.0391 →
+    // 0.033324 (Σ(non-price) = 0.75 = 1 − price). `q` is unchanged by the
+    // rescale; only λ moves (0.00682 → 0.016667). The reachable flip lands on a
+    // model whose `long_context` is imputed (capability fill 0.195, not
+    // measured) — see Scoring rule 6.
+    weights: { general: 0.6, long_context: 0.116676, throughput: 0.033324, price: 0.25 },
     required: ["reasoning", "general", "price", "throughput"],
     // `auto`, not `medium`: no reachable planning candidate lists `medium` in its
     // catalog thinking[], so a `medium` pin silently writes bare (the session
@@ -60,7 +72,7 @@ export const DEFAULT_ROLES: Record<string, RoleDef> = {
   },
   commit: {
     description: "Commit messages: cheap and fast with decent general quality",
-    weights: { price: 0.35, throughput: 0.27, general: 0.28, code: 0.1 },
+    weights: { price: 0.45, throughput: 0.2285, general: 0.2369, code: 0.0846 },
     required: ["general", "price", "throughput"],
     thinking: "off",
   },
@@ -90,14 +102,15 @@ export const DEFAULT_ROLES: Record<string, RoleDef> = {
     // lottery at 76% coverage); `long_context` is kept (the most independent
     // capability axis, r 0.739/0.767 with reasoning/general) and is now
     // capability-filled at 0.195 like `website` (src/engine.ts CAPABILITY_FILL),
-    // so its 44.7% coverage no longer penalizes. `reasoning`↔`general` stay
-    // collinear (r 0.972) but the independent axes now carry more. `price` is
+    // so its 44.7% coverage no longer penalizes. `reasoning`↔`general` were
+    // collinear (r 0.972) and are now merged into `general` (2026-10-03, issue
+    // #13), so the independent axes carry more. `price` is
     // raised to 0.20 (λ 0.0125) because the advisor fires on every primary turn
     // *and* every `task` subagent turn (config.yml task.agentAdvisor.task: on),
     // so spend is ~2× a per-turn count; `throughput` is raised to 0.1049 because
     // `syncBacklog: "1"` lets a slow advisor stall the primary up to 30s.
     // Non-price weights sum to 0.80 = 1 − price, as the (w/qW) blend requires.
-    weights: { reasoning: 0.3498, general: 0.2449, long_context: 0.1004, price: 0.2, throughput: 0.1049 },
+    weights: { general: 0.5947, long_context: 0.1004, price: 0.2, throughput: 0.1049 },
     required: ["reasoning", "general", "price", "throughput"],
     // `auto`, matching `plan`: the same model (Hy4 preview) runs both roles, so
     // pricing advisor bare while plan is `auto` understated advisor by 1.857×.
@@ -115,7 +128,7 @@ export const DEFAULT_ROLES: Record<string, RoleDef> = {
     // role is disabled (an unresolved `@x` is a literal pattern, so a bare
     // `@designer` would hard-fail — the chain is what keeps the agent spawnable).
     enabled: false,
-    weights: { general: 0.26, code: 0.10, vision: 0.18, throughput: 0.13, price: 0.15, website: 0.18 },
+    weights: { general: 0.26, code: 0.06, vision: 0.18, throughput: 0.15, price: 0.17, website: 0.18 },
     required: ["general", "price", "throughput"],
     // `auto` for the same reason as `plan`: nothing in the designer pool lists
     // `medium`, and `auto` is a meta level written as-is at the same overhead.
@@ -135,7 +148,7 @@ export const SHIPPED_AGENTS: string[] = ["designer"];
 
 
 /**
- * Metrics a role weight/required entry may name (SPEC §7).
+ * Metrics a role weight/required entry may name.
  *
  * The six raw llm-stats benchmark pass rates (`gpqa`, `aime`, `swe_bench`,
  * `arc_agi`, `terminal_bench`, `tau_bench`) are weightable too: they are already
@@ -155,6 +168,10 @@ export const KNOWN_METRICS: Record<string, true> = {
   vision: true,
   tool_calling: true,
   long_context: true,
+  index_communication: true,
+  index_finance: true,
+  index_healthcare: true,
+  index_legal: true,
   mrcr: true,
   website: true,
   writing: true,
@@ -164,6 +181,21 @@ export const KNOWN_METRICS: Record<string, true> = {
   arc_agi: true,
   terminal_bench: true,
   tau_bench: true,
+  simpleqa_score: true,
+  hle_score: true,
+  mmmu_score: true,
+  mmmu_pro_score: true,
+  mmmlu_score: true,
+  browsecomp_score: true,
+  swe_bench_pro_score: true,
+  mcp_atlas_score: true,
+  apex_agents_score: true,
+  osworld_score: true,
+  scicode_score: true,
+  screenspot_pro_score: true,
+  charxiv_r_score: true,
+  frontiermath_score: true,
+  toolathlon_score: true,
   price: true,
   throughput: true,
 };
@@ -181,7 +213,7 @@ export function isKnownMetric(name: string): boolean {
 }
 
 /**
- * Live-session coupling (SPEC §6 session-start semantics): after the day-gated
+ * Live-session coupling: after the day-gated
  * session-start write, a freshly started session whose conversation is still
  * empty had its active model resolved from the pre-write config. Reapply the
  * new `default` selector to the session's active model so the user's first
@@ -192,7 +224,7 @@ export const ACTIVATE_DEFAULT_KEY = "activateDefaultOnEmptySession";
 export type ResolvedSettings = {
   switchMargin: number;
   /**
-   * Cost-side escape hatch from `switchMargin` (SPEC §7): the margin is a flat
+   * Cost-side escape hatch from `switchMargin`: the margin is a flat
    * band on `value`, so a role with a loose posture (small λ) can refuse a
    * switch worth up to `switchMargin/λ` $/M. When a challenger sitting inside
    * the margin undercuts the incumbent's effective price by at least this
@@ -204,6 +236,14 @@ export type ResolvedSettings = {
   fallbackChainDepth: number;
   roles: Record<string, RoleDef>;
   activateDefaultOnEmptySession: boolean;
+  /** Opt-in reporting of unexpected plugin errors as GitHub issues on the
+   *  plugin's own tracker: `off` (default) never files, `ask` shows the exact
+   *  payload and files on confirmation (degrading to a prefilled URL when the
+   *  session has no UI), `auto` files without asking. */
+  errorReporting: "off" | "ask" | "auto";
+  /** 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>;
 };
 
 export const DEFAULT_SETTINGS: ResolvedSettings = {
@@ -213,6 +253,8 @@ export const DEFAULT_SETTINGS: ResolvedSettings = {
   fallbackChainDepth: 2,
   roles: DEFAULT_ROLES,
   activateDefaultOnEmptySession: true,
+  errorReporting: "off",
+  features: {},
 };
 
 /** One row of the plugin's settings schema (omp's `PluginSettingSchema`): the
@@ -264,7 +306,20 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       description: "Reapply the new default selector to an empty session's active model",
       default: DEFAULT_SETTINGS.activateDefaultOnEmptySession,
     },
+    errorReporting: {
+      type: "enum",
+      description: "File unexpected plugin errors as GitHub issues (off, ask, auto)",
+      default: DEFAULT_SETTINGS.errorReporting,
+      values: ["off", "ask", "auto"],
+    },
   };
+  for (const row of FEATURES) {
+    schema[`features.${row.id}`] = {
+      type: "boolean",
+      description: row.description,
+      default: false,
+    };
+  }
   for (const [name, def] of Object.entries(DEFAULT_ROLES)) {
     const p = `roles.${name}`;
     schema[`${p}.enabled`] = {
@@ -283,6 +338,30 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       default: def.thinking ?? "auto",
       values: Object.keys(SUFFIX_LEVELS),
     };
+    schema[`${p}.providerPin`] = {
+      type: "string",
+      description: `Provider slug the ${name} role's requests are pinned to (OpenRouter @<slug> routing; empty = default routing)`,
+    };
+    schema[`${p}.cacheHitRate`] = {
+      type: "number",
+      description: `Assumed cache-hit rate (0–1) for ${name}'s input tokens; blends each route's cache-read price before the 3:1 blend (0 = off)`,
+      default: def.cacheHitRate ?? 0,
+      min: 0,
+      max: 1,
+      step: 0.01,
+    };
+    for (const row of FEATURES) {
+      schema[`${p}.features.${row.id}`] = {
+        type: "boolean",
+        description: `Enable the ${row.label} capability for the ${name} role`,
+        default: false,
+      };
+    }
+    schema[`${p}.preferOwnProvider`] = {
+      type: "boolean",
+      description: `Bind ${name} requests to each model's best provider route (soft preference; never drops a model)`,
+      default: false,
+    };
     schema[`${p}.required`] = {
       type: "string",
       description: `Comma-separated metrics a model must have to rank for ${name}`,
@@ -293,6 +372,35 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       description: `Restrict the ${name} pool to image-capable models`,
       default: def.filters?.image ?? false,
     };
+    schema[`${p}.filters.tools`] = {
+      type: "boolean",
+      description: `Restrict the ${name} pool to models with a tool-capable route`,
+      default: def.filters?.tools ?? false,
+    };
+    schema[`${p}.filters.minContextTokens`] = {
+      type: "number",
+      description: `Drop ${name} routes whose endpoint context is below this (tokens; 0 = off)`,
+      default: def.filters?.minContextTokens ?? 0,
+      min: 0,
+    };
+    schema[`${p}.filters.minOutputTokens`] = {
+      type: "number",
+      description: `Drop ${name} routes whose endpoint output ceiling is below this (tokens; 0 = off)`,
+      default: def.filters?.minOutputTokens ?? 0,
+      min: 0,
+    };
+    schema[`${p}.filters.maxPriceUsdPerM`] = {
+      type: "number",
+      description: `Drop ${name} models whose role-priced blend exceeds this ($/M; 0 = off)`,
+      default: def.filters?.maxPriceUsdPerM ?? 0,
+      min: 0,
+    };
+    schema[`${p}.filters.preferredMinThroughput`] = {
+      type: "number",
+      description: `Soft throughput floor for ${name} routes (tok/s; 0 = off) — a below-floor route sorts last but is never dropped`,
+      default: def.filters?.preferredMinThroughput ?? 0,
+      min: 0,
+    };
     schema[`${p}.lambda`] = {
       type: "number",
       description: `Explicit λ ($ per quality point) override for ${name}`,
@@ -338,9 +446,12 @@ function setNested(target: Record<string, unknown>, path: string[], value: unkno
   else node[leaf] = value;
 }
 
-/** Nearest ancestor dir (or cwd itself) containing a `.omp` or `.git` anchor; null when none. */
-function findProjectAnchor(): string | null {
-  let dir = process.cwd();
+/** Nearest ancestor dir (or `cwd` itself) containing a `.omp` or `.git` anchor; null when none.
+ * Exported for the `/project-roles` divergence warning: omp reads `<cwd>/.omp` with no
+ * walk-up, so a session launched in a subdirectory has an anchor that differs from the dir
+ * omp actually reads. */
+export function findProjectAnchor(cwd: string = process.cwd()): string | null {
+  let dir = cwd;
   for (;;) {
     if (existsSync(join(dir, ".omp")) || existsSync(join(dir, ".git"))) return dir;
     const parent = dirname(dir);
@@ -349,15 +460,26 @@ function findProjectAnchor(): string | null {
   }
 }
 
+/** The project plugin settings lock file omp reads for `cwd`:
+ * `<cwd>/.omp/plugins/omp-plugins.lock.json`. omp resolves the project dir as
+ * `<cwd>/.omp` with no walk-up, so the project-scope read must use the same dir
+ * (not the walk-up anchor `findProjectAnchor` returns). */
+export function projectLockPath(cwd: string = process.cwd()): string {
+  return join(cwd, ".omp", "plugins", "omp-plugins.lock.json");
+}
+
 /**
  * Read the raw `settings["omp-llm-role"]` map: user-level lock file, with the
- * project-anchor lock file merged over it. Missing files (or missing settings
+ * project lock file (`<cwd>/.omp/plugins/omp-plugins.lock.json`, omp's project
+ * dir with no walk-up) merged over it. Missing files (or missing settings
  * entries) yield {}; unparseable lock files warn and yield {}.
  */
-export function readPluginSettingsMap(paths?: { global?: string; project?: string }): Record<string, unknown> {
+export function readPluginSettingsMap(paths?: { global?: string; project?: string | null }): Record<string, unknown> {
   const globalPath = paths?.global ?? PLUGIN_SETTINGS_PATH;
-  const anchor = paths?.project === undefined ? findProjectAnchor() : null;
-  const projectPath = paths?.project ?? (anchor ? join(anchor, ".omp", "plugins", "omp-plugins.lock.json") : null);
+  // omp reads the project dir as `<cwd>/.omp` with no walk-up, so the default
+  // project source is that dir's lock file (not the walk-up anchor). A missing
+  // file yields {} and the global path stands alone.
+  const projectPath = paths?.project === undefined ? projectLockPath() : paths?.project;
 
   const read = (path: string): Record<string, unknown> => {
     let parsed: unknown;
@@ -423,7 +545,7 @@ function mergeRawSettings(raw: Record<string, unknown>): { merged: ResolvedSetti
 
 /**
  * Deep-merge the raw settings map over the shipped defaults and validate the
- * result (SPEC §7). Roles whose resolved `weights` is null are dropped (explicit
+ * result. Roles whose resolved `weights` is null are dropped (explicit
  * opt-out). Never mutates the defaults. One error string per violation; an empty
  * error list means the settings are valid.
  */
@@ -447,6 +569,22 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
       `${ACTIVATE_DEFAULT_KEY}: must be a boolean, got ${JSON.stringify(merged.activateDefaultOnEmptySession)}`,
     );
   }
+  if (merged.errorReporting !== "off" && merged.errorReporting !== "ask" && merged.errorReporting !== "auto") {
+    errors.push(`errorReporting: must be one of off, ask, auto, got ${JSON.stringify(merged.errorReporting)}`);
+  }
+
+  // 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.
+  if (!isRecord(merged.features)) {
+    errors.push(`features: must be an object, got ${JSON.stringify(merged.features)}`);
+    merged.features = {};
+  } else {
+    for (const [id, v] of Object.entries(merged.features)) {
+      if (featureById(id) === null) errors.push(`features.${id} is not a known capability`);
+      if (typeof v !== "boolean") errors.push(`features.${id}: must be a boolean, got ${JSON.stringify(v)}`);
+    }
+  }
 
   for (const [name, rdef] of Object.entries(merged.roles)) {
     if (!isRecord(rdef)) {
@@ -508,8 +646,19 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
     }
     if (rdef.filters !== undefined) {
       if (!isRecord(rdef.filters)) errors.push(`role ${name}: filters must be an object`);
-      else if (rdef.filters.image !== undefined && typeof rdef.filters.image !== "boolean") {
-        errors.push(`role ${name}: filters.image must be a boolean`);
+      else {
+        if (rdef.filters.image !== undefined && typeof rdef.filters.image !== "boolean") {
+          errors.push(`role ${name}: filters.image must be a boolean`);
+        }
+        if (rdef.filters.tools !== undefined && typeof rdef.filters.tools !== "boolean") {
+          errors.push(`role ${name}: filters.tools must be a boolean`);
+        }
+        for (const key of ["minContextTokens", "minOutputTokens", "maxPriceUsdPerM", "preferredMinThroughput"] as const) {
+          const v = rdef.filters[key];
+          if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) {
+            errors.push(`role ${name}: filters.${key} must be a number ≥ 0`);
+          }
+        }
       }
     }
     if (rdef.thinking !== undefined && (typeof rdef.thinking !== "string" || !(rdef.thinking in SUFFIX_LEVELS))) {
@@ -522,7 +671,45 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
         delete rdef.lambda;
       }
     }
+    if (rdef.cacheHitRate !== undefined) {
+      if (typeof rdef.cacheHitRate !== "number" || !Number.isFinite(rdef.cacheHitRate) || rdef.cacheHitRate < 0 || rdef.cacheHitRate > 1) {
+        errors.push(`role ${name}: cacheHitRate must be a number in [0, 1]`);
+        delete rdef.cacheHitRate;
+      }
+    }
+    // providerPin is a provider slug (may be tiered like `deepinfra/fp8`); `@`
+    // and `:` are the selector's own delimiters, so they cannot appear in it.
+    if (rdef.providerPin !== undefined) {
+      if (
+        typeof rdef.providerPin !== "string" ||
+        rdef.providerPin.length === 0 ||
+        rdef.providerPin.includes("@") ||
+        rdef.providerPin.includes(":")
+      ) {
+        errors.push(`role ${name}: providerPin must be a non-empty string without "@" or ":"`);
+        delete rdef.providerPin;
+      }
+    }
+    // Per-role capability flags (`roles.<role>.features.<id>`): an unknown id or
+    // a non-boolean value aborts the run, naming the role and the key.
+    if (rdef.features !== undefined) {
+      if (!isRecord(rdef.features)) {
+        errors.push(`role ${name}: features must be an object`);
+        delete rdef.features;
+      } else {
+        for (const [id, v] of Object.entries(rdef.features)) {
+          if (featureById(id) === null) errors.push(`role ${name}: features.${id} is not a known capability`);
+          if (typeof v !== "boolean") errors.push(`role ${name}: features.${id} must be a boolean, got ${JSON.stringify(v)}`);
+        }
+      }
+    }
+    if (rdef.preferOwnProvider !== undefined && typeof rdef.preferOwnProvider !== "boolean") {
+      errors.push(`role ${name}: preferOwnProvider must be a boolean, got ${JSON.stringify(rdef.preferOwnProvider)}`);
+    }
     if (rdef.description === undefined) rdef.description = "";
+    // The resolved def is the EFFECTIVE def: the authored def with the enabled
+    // flags' recommended knobs filled in (explicit keys win; `features` stripped).
+    merged.roles[name] = expandFeatures(rdef, merged.features);
   }
 
   return { settings: merged, errors };

package/src/state.ts

@@ -1,6 +1,6 @@
 /**
  * Plugin state, history, and the refresh lock — all under the omp agent dir,
- * next to the config.yml they describe (SPEC §8).
+ * next to the config.yml they describe.
  *
  * - `llm-role-state.json` — day gate, managed roles, last selectors, chain keys
  *   the plugin owns, and the pre-write `modelRoles` snapshot (manual rollback aid).