feat(model-capabilities): add maintenance guardrails

src/cli/doctor/checks/model-resolution-details.ts

@@ -4,6 +4,10 @@ import { getOpenCodeCacheDir } from "../../../shared"
 import type { AvailableModelsInfo, ModelResolutionInfo, OmoConfig } from "./model-resolution-types"
 import { formatModelWithVariant, getCategoryEffectiveVariant, getEffectiveVariant } from "./model-resolution-variant"
 
+function formatCapabilityResolutionLabel(mode: string | undefined): string {
+  return mode ?? "unknown"
+}
+
 export function buildModelResolutionDetails(options: {
   info: ModelResolutionInfo
   available: AvailableModelsInfo
@@ -37,7 +41,7 @@ export function buildModelResolutionDetails(options: {
       agent.effectiveModel,
       getEffectiveVariant(agent.name, agent.requirement, options.config)
     )
-    details.push(`  ${marker} ${agent.name}: ${display}`)
+    details.push(`  ${marker} ${agent.name}: ${display} [capabilities: ${formatCapabilityResolutionLabel(agent.capabilityDiagnostics?.resolutionMode)}]`)
   }
   details.push("")
   details.push("Categories:")
@@ -47,7 +51,7 @@ export function buildModelResolutionDetails(options: {
       category.effectiveModel,
       getCategoryEffectiveVariant(category.name, category.requirement, options.config)
     )
-    details.push(`  ${marker} ${category.name}: ${display}`)
+    details.push(`  ${marker} ${category.name}: ${display} [capabilities: ${formatCapabilityResolutionLabel(category.capabilityDiagnostics?.resolutionMode)}]`)
   }
   details.push("")
   details.push("● = user override, ○ = provider fallback")

src/cli/doctor/checks/model-resolution-types.ts

@@ -1,3 +1,4 @@
+import type { ModelCapabilitiesDiagnostics } from "../../../shared/model-capabilities"
 import type { ModelRequirement } from "../../../shared/model-requirements"
 
 export interface AgentResolutionInfo {
@@ -7,6 +8,7 @@ export interface AgentResolutionInfo {
   userVariant?: string
   effectiveModel: string
   effectiveResolution: string
+  capabilityDiagnostics?: ModelCapabilitiesDiagnostics
 }
 
 export interface CategoryResolutionInfo {
@@ -16,6 +18,7 @@ export interface CategoryResolutionInfo {
   userVariant?: string
   effectiveModel: string
   effectiveResolution: string
+  capabilityDiagnostics?: ModelCapabilitiesDiagnostics
 }
 
 export interface ModelResolutionInfo {

src/cli/doctor/checks/model-resolution.test.ts

@@ -129,6 +129,19 @@ describe("model-resolution check", () => {
       expect(visual!.userOverride).toBe("google/gemini-3-flash-preview")
       expect(visual!.userVariant).toBe("high")
     })
+
+    it("attaches snapshot-backed capability diagnostics for built-in models", async () => {
+      const { getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({})
+      const sisyphus = info.agents.find((a) => a.name === "sisyphus")
+
+      expect(sisyphus).toBeDefined()
+      expect(sisyphus!.capabilityDiagnostics).toMatchObject({
+        resolutionMode: "snapshot-backed",
+        snapshot: { source: "bundled-snapshot" },
+      })
+    })
   })
 
   describe("checkModelResolution", () => {
@@ -162,6 +175,23 @@ describe("model-resolution check", () => {
       expect(result.details!.some((d) => d.includes("Categories:"))).toBe(true)
       // Should have legend
       expect(result.details!.some((d) => d.includes("user override"))).toBe(true)
+      expect(result.details!.some((d) => d.includes("capabilities: snapshot-backed"))).toBe(true)
+    })
+
+    it("collects warnings when configured models rely on compatibility fallback", async () => {
+      const { collectCapabilityResolutionIssues, getModelResolutionInfoWithOverrides } = await import("./model-resolution")
+
+      const info = getModelResolutionInfoWithOverrides({
+        agents: {
+          oracle: { model: "custom/unknown-llm" },
+        },
+      })
+
+      const issues = collectCapabilityResolutionIssues(info)
+
+      expect(issues).toHaveLength(1)
+      expect(issues[0]?.title).toContain("compatibility fallback")
+      expect(issues[0]?.description).toContain("oracle=custom/unknown-llm")
     })
   })
 

src/cli/doctor/checks/model-resolution.ts

@@ -1,4 +1,5 @@
 import { AGENT_MODEL_REQUIREMENTS, CATEGORY_MODEL_REQUIREMENTS } from "../../../shared/model-requirements"
+import { getModelCapabilities } from "../../../shared/model-capabilities"
 import { CHECK_IDS, CHECK_NAMES } from "../constants"
 import type { CheckResult, DoctorIssue } from "../types"
 import { loadAvailableModelsFromCache } from "./model-resolution-cache"
@@ -7,16 +8,36 @@ import { buildModelResolutionDetails } from "./model-resolution-details"
 import { buildEffectiveResolution, getEffectiveModel } from "./model-resolution-effective-model"
 import type { AgentResolutionInfo, CategoryResolutionInfo, ModelResolutionInfo, OmoConfig } from "./model-resolution-types"
 
-export function getModelResolutionInfo(): ModelResolutionInfo {
-  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => ({
-    name,
-    requirement,
-    effectiveModel: getEffectiveModel(requirement),
-    effectiveResolution: buildEffectiveResolution(requirement),
-  }))
+function parseProviderModel(value: string): { providerID: string; modelID: string } | null {
+  const slashIndex = value.indexOf("/")
+  if (slashIndex <= 0 || slashIndex === value.length - 1) {
+    return null
+  }
 
-  const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
-    ([name, requirement]) => ({
+  return {
+    providerID: value.slice(0, slashIndex),
+    modelID: value.slice(slashIndex + 1),
+  }
+}
+
+function attachCapabilityDiagnostics<T extends AgentResolutionInfo | CategoryResolutionInfo>(entry: T): T {
+  const parsed = parseProviderModel(entry.effectiveModel)
+  if (!parsed) {
+    return entry
+  }
+
+  return {
+    ...entry,
+    capabilityDiagnostics: getModelCapabilities({
+      providerID: parsed.providerID,
+      modelID: parsed.modelID,
+    }).diagnostics,
+  }
+}
+
+export function getModelResolutionInfo(): ModelResolutionInfo {
+  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) =>
+    attachCapabilityDiagnostics({
       name,
       requirement,
       effectiveModel: getEffectiveModel(requirement),
@@ -24,6 +45,16 @@ export function getModelResolutionInfo(): ModelResolutionInfo {
     })
   )
 
+  const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
+    ([name, requirement]) =>
+      attachCapabilityDiagnostics({
+        name,
+        requirement,
+        effectiveModel: getEffectiveModel(requirement),
+        effectiveResolution: buildEffectiveResolution(requirement),
+      })
+  )
+
   return { agents, categories }
 }
 
@@ -31,34 +62,60 @@ export function getModelResolutionInfoWithOverrides(config: OmoConfig): ModelRes
   const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => {
     const userOverride = config.agents?.[name]?.model
     const userVariant = config.agents?.[name]?.variant
-    return {
+    return attachCapabilityDiagnostics({
       name,
       requirement,
       userOverride,
       userVariant,
       effectiveModel: getEffectiveModel(requirement, userOverride),
       effectiveResolution: buildEffectiveResolution(requirement, userOverride),
-    }
+    })
   })
 
   const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
     ([name, requirement]) => {
       const userOverride = config.categories?.[name]?.model
       const userVariant = config.categories?.[name]?.variant
-      return {
+      return attachCapabilityDiagnostics({
         name,
         requirement,
         userOverride,
         userVariant,
         effectiveModel: getEffectiveModel(requirement, userOverride),
         effectiveResolution: buildEffectiveResolution(requirement, userOverride),
-      }
+      })
     }
   )
 
   return { agents, categories }
 }
 
+export function collectCapabilityResolutionIssues(info: ModelResolutionInfo): DoctorIssue[] {
+  const issues: DoctorIssue[] = []
+  const allEntries = [...info.agents, ...info.categories]
+  const fallbackEntries = allEntries.filter((entry) => {
+    const mode = entry.capabilityDiagnostics?.resolutionMode
+    return mode === "alias-backed" || mode === "heuristic-backed" || mode === "unknown"
+  })
+
+  if (fallbackEntries.length === 0) {
+    return issues
+  }
+
+  const summary = fallbackEntries
+    .map((entry) => `${entry.name}=${entry.effectiveModel} (${entry.capabilityDiagnostics?.resolutionMode ?? "unknown"})`)
+    .join(", ")
+
+  issues.push({
+    title: "Configured models rely on compatibility fallback",
+    description: summary,
+    severity: "warning",
+    affects: fallbackEntries.map((entry) => entry.name),
+  })
+
+  return issues
+}
+
 export async function checkModels(): Promise<CheckResult> {
   const config = loadOmoConfig() ?? {}
   const info = getModelResolutionInfoWithOverrides(config)
@@ -75,6 +132,8 @@ export async function checkModels(): Promise<CheckResult> {
     })
   }
 
+  issues.push(...collectCapabilityResolutionIssues(info))
+
   const overrideCount =
     info.agents.filter((agent) => Boolean(agent.userOverride)).length +
     info.categories.filter((category) => Boolean(category.userOverride)).length