talon-agent 3.33.2 → 3.33.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.33.2",
+  "version": "3.33.4",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -68,8 +68,8 @@
     "test:integration": "vitest run --reporter=verbose --reporter=json --outputFile=integration-results.json src/__tests__/integration/talon-mcp-functional.test.ts",
     "test:integration:all": "vitest run --reporter=verbose src/__tests__/integration/",
     "test:claude:backend": "vitest run --reporter=verbose --reporter=json --outputFile=claude-backend-results.json src/__tests__/integration/claude-live-discovery.test.ts",
-    "test:kilo:backend": "vitest run --reporter=verbose --reporter=json --outputFile=kilo-backend-results.json src/__tests__/integration/kilo-live-discovery.test.ts",
-    "test:opencode:backend": "vitest run --reporter=verbose --reporter=json --outputFile=opencode-backend-results.json src/__tests__/integration/opencode-live-discovery.test.ts",
+    "test:kilo:backend": "vitest run --reporter=verbose --reporter=json --outputFile=kilo-backend-results.json src/__tests__/integration/kilo-live-discovery.test.ts src/__tests__/integration/kilo-real-bootstrap.test.ts",
+    "test:opencode:backend": "vitest run --reporter=verbose --reporter=json --outputFile=opencode-backend-results.json src/__tests__/integration/opencode-live-discovery.test.ts src/__tests__/integration/opencode-real-bootstrap.test.ts",
     "test:codex:backend": "vitest run --reporter=verbose --reporter=json --outputFile=codex-backend-results.json src/__tests__/integration/codex-live-discovery.test.ts",
     "test:openai-agents:backend": "vitest run --reporter=verbose --reporter=json --outputFile=openai-agents-backend-results.json src/__tests__/integration/openai-agents-live-discovery.test.ts",
     "build:sql": "tsx scripts/embed-sql.ts",
@@ -142,14 +142,14 @@
     "@types/node": "^26.0.0",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/write-file-atomic": "^4.0.3",
-    "@vitest/coverage-v8": "^4.1.3",
+    "@vitest/coverage-v8": "^5.0.0",
     "dependency-cruiser": "^18.1.0",
     "fast-check": "^4.6.0",
     "knip": "^6.3.1",
     "oxlint": "^1.59.0",
     "prettier": "^3.8.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.3"
+    "vitest": "^5.0.0"
   },
   "overrides": {
     "@anthropic-ai/sdk": "^0.104.1",

package/src/backend/builtins.ts

@@ -0,0 +1,16 @@
+/**
+ * Register every built-in backend with the registry.
+ *
+ * Each backend's `factory.ts` calls `registerBackend` as a side effect of
+ * being imported, so "loading" is importing. One list, used by the
+ * daemon's bootstrap, by `talon doctor` (which runs standalone and needs
+ * the factories' doctor checks), and by tests that exercise the registry.
+ * Adding a backend is adding a line here.
+ */
+export async function loadBuiltinBackends(): Promise<void> {
+  await import("./claude-sdk/factory.js");
+  await import("./opencode/factory.js");
+  await import("./kilo/factory.js");
+  await import("./codex/factory.js");
+  await import("./openai-agents/factory.js");
+}

package/src/backend/claude-sdk/doctor.ts

@@ -0,0 +1,108 @@
+/**
+ * `talon doctor` checks for the Claude SDK backend: the CLI binary, and —
+ * only for the backend actually serving chats, since it spawns a probe —
+ * the models pinned in config against the static catalog.
+ */
+
+import type {
+  DoctorCheck,
+  DoctorConfigSlice,
+} from "../../core/doctor-types.js";
+import { getModels } from "../../core/models/catalog.js";
+import { binaryOnPath } from "../../util/binary-on-path.js";
+import { resolveModel } from "./model-provider.js";
+import { registerClaudeModelsStatic } from "./models/discovery.js";
+import { CLAUDE_MODELS_STATIC } from "./models/static.js";
+
+export async function claudeDoctorChecks(
+  config: DoctorConfigSlice | undefined,
+  isActive: boolean,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+  if (config?.claudeBinary) {
+    checks.push(
+      binaryOnPath(config.claudeBinary)
+        ? {
+            label: "Claude Code binary",
+            status: "ok",
+            detail: config.claudeBinary,
+          }
+        : {
+            label: "Claude Code binary not found",
+            status: "fail",
+            detail: config.claudeBinary,
+          },
+    );
+  } else {
+    checks.push(
+      binaryOnPath("claude")
+        ? { label: "Claude Code installed", status: "ok" }
+        : { label: "Claude Code not found", status: "fail" },
+    );
+  }
+  // Model resolution spawns a probe — worth it for the backend actually
+  // serving chats, wasteful for one nobody is using.
+  if (isActive) checks.push(...(await checkConfiguredModels(config)));
+  return checks;
+}
+
+/**
+ * Validate models pinned in config against the static catalog. A model
+ * that has been withdrawn from the catalog (it happens: deprecations,
+ * policy pulls) makes every turn silently run the backend default while
+ * the config keeps naming the dead id — this check is where that finally
+ * becomes visible. Claude-only: this catalog is a static import; other
+ * backends need a live server and are audited at boot instead
+ * (core/engine/model-audit.ts).
+ */
+async function checkConfiguredModels(
+  config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+  const targets: Array<{ key: string; model?: string; backendId?: string }> = [
+    { key: "model", model: config?.model, backendId: config?.backend },
+    {
+      key: "heartbeatModel",
+      model: config?.heartbeatModel,
+      backendId: config?.heartbeatBackend ?? config?.backend,
+    },
+  ];
+  try {
+    // Doctor runs standalone — live SDK model discovery hasn't happened,
+    // so the registry may be empty. Seed the static catalog (the same
+    // list the setup wizard offers) so alias pins like "opus" resolve.
+    // The static list is a snapshot: a model can exist upstream and not
+    // here, which is why findings are warn-level, never fail.
+    if (getModels("anthropic").length === 0) {
+      registerClaudeModelsStatic(CLAUDE_MODELS_STATIC);
+    }
+    for (const { key, model, backendId } of targets) {
+      if (!model || model === "default") continue;
+      if ((backendId ?? "claude") !== "claude") continue;
+      const res = await resolveModel(model);
+      if (res.kind === "exact") {
+        checks.push({
+          label: `Model (${key}): ${model} → ${res.model.displayName}`,
+          status: "ok",
+        });
+      } else if (res.kind === "ambiguous") {
+        checks.push({
+          label: `Model (${key}): "${model}" is ambiguous`,
+          status: "warn",
+          detail: res.matches.map((m) => m.displayName).join(", "),
+          issue: true,
+        });
+      } else {
+        checks.push({
+          label: `Model (${key}): "${model}" not selectable on claude`,
+          status: "warn",
+          detail: "turns silently run the backend default — update config.json",
+          issue: true,
+        });
+      }
+    }
+  } catch {
+    /* catalog unavailable — skip, never break doctor */
+  }
+  return checks;
+}

package/src/backend/claude-sdk/factory.ts

@@ -43,6 +43,7 @@ import {
 import { waitForMcpServersReady } from "./mcp-ready.js";
 
 import * as modelProvider from "./model-provider.js";
+import { claudeDoctorChecks } from "./doctor.js";
 
 const claudeSdkFactory: BackendFactory = {
   // The config schema uses `"claude"` for backward compatibility with
@@ -50,6 +51,7 @@ const claudeSdkFactory: BackendFactory = {
   // no migration is needed.
   id: "claude",
   label: "Anthropic",
+  doctor: (config, isActive) => claudeDoctorChecks(config, isActive),
 
   async init(config, ctx) {
     await initClaudeAgent(config, ctx.getBridgePort);

package/src/backend/codex/doctor.ts

@@ -0,0 +1,50 @@
+/**
+ * `talon doctor` checks for the Codex backend: the CLI binary and how it
+ * will authenticate.
+ */
+
+import type {
+  DoctorCheck,
+  DoctorConfigSlice,
+} from "../../core/doctor-types.js";
+import { binaryOnPath } from "../../util/binary-on-path.js";
+import { detectCodexAuth } from "./auth.js";
+
+export async function codexDoctorChecks(
+  config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+  if (!binaryOnPath("codex")) {
+    checks.push({
+      label: "Codex CLI not found",
+      status: "fail",
+      detail: "npm i -g @openai/codex",
+    });
+    return checks;
+  }
+  checks.push({ label: "Codex CLI installed", status: "ok" });
+  const auth = detectCodexAuth({
+    codexApiKey: config?.codexApiKey,
+    openaiApiKey: config?.openaiApiKey,
+    openaiBaseUrl: config?.openaiBaseUrl,
+  });
+  for (const diagnostic of auth.diagnostics) {
+    checks.push({ label: diagnostic, status: "warn" });
+  }
+  if (auth.mode !== "none") {
+    checks.push({
+      label: "Codex auth",
+      status: "ok",
+      detail: auth.baseUrl ? `${auth.source} (${auth.baseUrl})` : auth.source,
+    });
+  } else {
+    checks.push({
+      label: "Codex auth missing",
+      status: "warn",
+      detail:
+        "set CODEX_API_KEY, TALON_CODEX_KEY, codexApiKey, or run `codex login`",
+      issue: true,
+    });
+  }
+  return checks;
+}

package/src/backend/codex/factory.ts

@@ -7,6 +7,7 @@
  */
 
 import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
+import { codexDoctorChecks } from "./doctor.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
@@ -41,6 +42,7 @@ import {
 const codexFactory: BackendFactory = {
   id: "codex",
   label: "Codex",
+  doctor: (config) => codexDoctorChecks(config),
 
   async init(config, ctx) {
     initCodexAgent(config, ctx.getBridgePort, ctx.frontendName);

package/src/backend/openai-agents/doctor.ts

@@ -0,0 +1,51 @@
+/**
+ * `talon doctor` checks for the OpenAI Agents backend: the SDK is bundled,
+ * so this is about the API key and which endpoint it will talk to.
+ */
+
+import type {
+  DoctorCheck,
+  DoctorConfigSlice,
+} from "../../core/doctor-types.js";
+
+export async function openAIAgentsDoctorChecks(
+  config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [
+    { label: "OpenAI Agents SDK bundled", status: "ok" },
+  ];
+  const hasEnvKey = Boolean(process.env.OPENAI_API_KEY);
+  const hasCfgKey = Boolean(config?.openaiApiKey);
+  if (hasEnvKey || hasCfgKey) {
+    const sources: string[] = [];
+    if (hasEnvKey) sources.push("OPENAI_API_KEY env");
+    if (hasCfgKey) sources.push("openaiApiKey in talon.json");
+    checks.push({
+      label: "OpenAI Agents auth",
+      status: "ok",
+      detail: sources.join(", "),
+    });
+  } else {
+    checks.push({
+      label: "OpenAI Agents auth missing",
+      status: "warn",
+      detail: "set OPENAI_API_KEY or openaiApiKey in talon.json",
+      issue: true,
+    });
+  }
+  const envBase = process.env.OPENAI_BASE_URL;
+  const cfgBase = config?.openaiBaseUrl;
+  if (envBase || cfgBase) {
+    checks.push({
+      label: "OpenAI-compatible endpoint",
+      status: "ok",
+      detail: envBase ? `env (${envBase})` : `config (${cfgBase})`,
+    });
+  } else {
+    checks.push({
+      label: "Endpoint: api.openai.com (default)",
+      status: "info",
+    });
+  }
+  return checks;
+}

package/src/backend/openai-agents/factory.ts

@@ -10,6 +10,7 @@
  */
 
 import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
+import { openAIAgentsDoctorChecks } from "./doctor.js";
 import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
@@ -39,6 +40,7 @@ import {
 const openAIAgentsFactory: BackendFactory = {
   id: "openai-agents",
   label: "OpenAI Agents",
+  doctor: (config) => openAIAgentsDoctorChecks(config),
 
   async init(config, ctx) {
     initOpenAIAgentsAgent(config, ctx.getBridgePort, ctx.frontendName);

package/src/backend/remote-server/factory.ts

@@ -26,6 +26,7 @@ import {
 } from "../../core/agent-runtime/capabilities.js";
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import type { TalonConfig } from "../../util/config.js";
+import { binaryOnPath } from "../../util/binary-on-path.js";
 import { log } from "../../util/log.js";
 import { handlerToEvents } from "../shared/handler-to-events.js";
 import type { QueryParams, QueryResult } from "../shared/handler-types.js";
@@ -64,6 +65,22 @@ export function createRemoteBackendFactory(
   return {
     id,
     label,
+    // The SDK ships as an npm dep but only talks to a server it spawns from
+    // the CLI of the same name (`cross-spawn` → PATH lookup). A present
+    // package with an absent binary fails at the first turn with a bare
+    // ENOENT, so doctor checks what actually gets executed.
+    async doctor() {
+      return [
+        binaryOnPath(id)
+          ? { label: `${label} CLI installed`, status: "ok" }
+          : {
+              label: `${label} CLI not found`,
+              status: "fail",
+              detail: `the ${label} SDK spawns \`${id}\` — install it or this backend cannot start`,
+              issue: true,
+            },
+      ];
+    },
     async init(config, ctx) {
       inputs.init(config, ctx.getBridgePort, ctx.frontendName);
       log("bot", `Backend: ${label} (${inputs.sdkPackage})`);

package/src/bootstrap.ts

@@ -171,14 +171,11 @@ export async function initBackendAndDispatcher(
 ): Promise<BackendAndDispatcherResult> {
   const frontends = normalizeFrontends(frontend);
 
-  // Register all built-in backends via side-effect import. Adding a new
-  // backend is now strictly additive: drop a `factory.ts` under the new
-  // backend dir and import it here. No conditionals here change.
-  await import("./backend/claude-sdk/factory.js");
-  await import("./backend/opencode/factory.js");
-  await import("./backend/kilo/factory.js");
-  await import("./backend/codex/factory.js");
-  await import("./backend/openai-agents/factory.js");
+  // Register all built-in backends. Adding a new backend is strictly
+  // additive: drop a `factory.ts` under the new backend dir and list it in
+  // backend/builtins.ts. No conditionals here change.
+  const { loadBuiltinBackends } = await import("./backend/builtins.js");
+  await loadBuiltinBackends();
 
   const {
     initBackendPool,

package/src/cli/doctor.ts

@@ -20,6 +20,10 @@ export async function runDoctor(): Promise<void> {
   printBanner();
   console.log(`  ${pc.bold("Environment check")}\n`);
   const { collectDoctorReport } = await import("../core/doctor.js");
+  // Doctor composes each backend's own checks off the registry, and the
+  // CLI runs standalone — nothing else has registered them yet.
+  const { loadBuiltinBackends } = await import("../backend/builtins.js");
+  await loadBuiltinBackends();
   const hasConfigFile = existsSync(CONFIG_FILE);
   const report = await collectDoctorReport({
     config: hasConfigFile ? loadConfig() : undefined,

package/src/core/agent-runtime/backend-registry.ts

@@ -30,6 +30,7 @@
  */
 
 import type { Backend } from "./capabilities.js";
+import type { DoctorCheck, DoctorConfigSlice } from "../doctor-types.js";
 import type { TalonConfig } from "../../util/config.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
@@ -77,6 +78,17 @@ export interface BackendFactory {
   label: string;
   /** Initialise the backend; called exactly once per Talon process. */
   init(config: TalonConfig, ctx: BackendInitContext): Promise<BackendInstance>;
+  /**
+   * `talon doctor` checks for this backend — binary, auth, catalog probes.
+   * `isActive` is true for the backend serving chats; probes that cost a
+   * process spawn (model resolution) should run only then. Doctor composes
+   * whatever is registered, so a backend without this slot is reported as
+   * having nothing to check rather than silently skipped.
+   */
+  doctor?(
+    config: DoctorConfigSlice | undefined,
+    isActive: boolean,
+  ): Promise<DoctorCheck[]>;
 }
 
 // ── State ───────────────────────────────────────────────────────────────────

package/src/core/doctor-types.ts

@@ -0,0 +1,82 @@
+/**
+ * The doctor's data shapes, on their own so a backend factory can declare
+ * its checks (`BackendFactory.doctor`) without importing the collector —
+ * `core/doctor.ts` reads the registry, so the types living there would
+ * close a cycle. Checks are pure data (label / status / detail); renderers
+ * decide presentation.
+ */
+
+type DoctorStatus = "ok" | "warn" | "fail" | "info";
+
+export interface DoctorCheck {
+  label: string;
+  status: DoctorStatus;
+  detail?: string;
+  /**
+   * Counts toward the issue total even when status is "warn" — used
+   * for soft failures like missing backend auth where the bot still
+   * starts but a backend won't work.
+   */
+  issue?: boolean;
+  /**
+   * A backend that is configured but not serving chats. Renderers group
+   * these away from the environment so a handful of idle providers can't
+   * bury the checks that describe the running deployment.
+   */
+  inactive?: boolean;
+}
+
+/** One embedded native module: provenance plus a live self-test result. */
+export interface NativeModuleCheck {
+  name: string;
+  /** Source language ("Rust", "Zig", "C", "C++", "Gleam"). */
+  language: string;
+  /** Compile target ("wasm32-unknown-unknown", "wasm32-freestanding", "JavaScript"). */
+  target: string;
+  /** Embedded artifact size, when the module ships as wasm bytes. */
+  sizeBytes?: number;
+  ok: boolean;
+  /** Failure detail when !ok. */
+  note?: string;
+}
+
+export interface DoctorReport {
+  checks: DoctorCheck[];
+  native: NativeModuleCheck[];
+  /** Failed checks + warn-with-issue checks + failed native modules. */
+  issues: number;
+}
+
+/**
+ * The slice of config doctor reads. Both the CLI's local Config and
+ * TalonConfig satisfy this structurally.
+ */
+export interface DoctorConfigSlice {
+  frontend: string | string[];
+  backend?: string;
+  /** Backends config exposes. Empty / absent means every registered one. */
+  enabledBackends?: string[];
+  model?: string;
+  heartbeatModel?: string;
+  heartbeatBackend?: string;
+  botToken?: string;
+  teamsWebhookUrl?: string;
+  discord?: { botToken?: string };
+  whatsapp?: object;
+  claudeBinary?: string;
+  codexApiKey?: string;
+  openaiApiKey?: string;
+  openaiBaseUrl?: string;
+  mempalace?: {
+    enabled?: boolean;
+    pythonPath?: string;
+    version?: string;
+  };
+  playwright?: {
+    enabled?: boolean;
+    browser?: string;
+    endpoint?: string;
+    endpointFile?: string;
+  };
+  github?: { enabled?: boolean; imageTag?: string };
+}

package/src/core/doctor.ts

@@ -13,84 +13,22 @@
 
 import { existsSync } from "node:fs";
 import { stat } from "node:fs/promises";
-import { execFileSync } from "node:child_process";
 import { NATIVE_MODULES } from "../native/registry.js";
 import { dirs } from "../util/paths.js";
-
-type DoctorStatus = "ok" | "warn" | "fail" | "info";
-
-export interface DoctorCheck {
-  label: string;
-  status: DoctorStatus;
-  detail?: string;
-  /**
-   * Counts toward the issue total even when status is "warn" — used
-   * for soft failures like missing backend auth where the bot still
-   * starts but a backend won't work.
-   */
-  issue?: boolean;
-  /**
-   * A backend that is configured but not serving chats. Renderers group
-   * these away from the environment so a handful of idle providers can't
-   * bury the checks that describe the running deployment.
-   */
-  inactive?: boolean;
-}
-
-/** One embedded native module: provenance plus a live self-test result. */
-export interface NativeModuleCheck {
-  name: string;
-  /** Source language ("Rust", "Zig", "C", "C++", "Gleam"). */
-  language: string;
-  /** Compile target ("wasm32-unknown-unknown", "wasm32-freestanding", "JavaScript"). */
-  target: string;
-  /** Embedded artifact size, when the module ships as wasm bytes. */
-  sizeBytes?: number;
-  ok: boolean;
-  /** Failure detail when !ok. */
-  note?: string;
-}
-
-export interface DoctorReport {
-  checks: DoctorCheck[];
-  native: NativeModuleCheck[];
-  /** Failed checks + warn-with-issue checks + failed native modules. */
-  issues: number;
-}
-
-/**
- * The slice of config doctor reads. Both the CLI's local Config and
- * TalonConfig satisfy this structurally.
- */
-export interface DoctorConfigSlice {
-  frontend: string | string[];
-  backend?: string;
-  /** Backends config exposes. Empty / absent means every registered one. */
-  enabledBackends?: string[];
-  model?: string;
-  heartbeatModel?: string;
-  heartbeatBackend?: string;
-  botToken?: string;
-  teamsWebhookUrl?: string;
-  discord?: { botToken?: string };
-  whatsapp?: object;
-  claudeBinary?: string;
-  codexApiKey?: string;
-  openaiApiKey?: string;
-  openaiBaseUrl?: string;
-  mempalace?: {
-    enabled?: boolean;
-    pythonPath?: string;
-    version?: string;
-  };
-  playwright?: {
-    enabled?: boolean;
-    browser?: string;
-    endpoint?: string;
-    endpointFile?: string;
-  };
-  github?: { enabled?: boolean; imageTag?: string };
-}
+import { getBackend, listBackends } from "./agent-runtime/backend-registry.js";
+import type {
+  DoctorCheck,
+  DoctorConfigSlice,
+  DoctorReport,
+  NativeModuleCheck,
+} from "./doctor-types.js";
+
+export type {
+  DoctorCheck,
+  DoctorConfigSlice,
+  DoctorReport,
+  NativeModuleCheck,
+} from "./doctor-types.js";
 
 function errorNote(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
@@ -230,85 +168,6 @@ async function checkNamespaceDir(): Promise<DoctorCheck> {
   };
 }
 
-function binaryOnPath(name: string): boolean {
-  try {
-    const lookupCmd = process.platform === "win32" ? "where" : "which";
-    execFileSync(lookupCmd, [name], { stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Validate models pinned in config against the Claude backend's static
- * catalog. A model that has been withdrawn from the catalog (it
- * happens: deprecations, policy pulls) makes every turn silently run
- * the backend default while the config keeps naming the dead id —
- * this check is where that finally becomes visible. Claude-only: this
- * catalog is a static import; other backends need a live server and
- * are audited at boot instead (core/engine/model-audit.ts).
- */
-async function checkClaudeConfiguredModels(
-  config: DoctorConfigSlice | undefined,
-): Promise<DoctorCheck[]> {
-  const checks: DoctorCheck[] = [];
-  const targets: Array<{ key: string; model?: string; backendId?: string }> = [
-    { key: "model", model: config?.model, backendId: config?.backend },
-    {
-      key: "heartbeatModel",
-      model: config?.heartbeatModel,
-      backendId: config?.heartbeatBackend ?? config?.backend,
-    },
-  ];
-  try {
-    const { resolveModel } =
-      await import("../backend/claude-sdk/model-provider.js");
-    // Doctor runs standalone — live SDK model discovery hasn't happened,
-    // so the registry may be empty. Seed the static catalog (the same
-    // list the setup wizard offers) so alias pins like "opus" resolve.
-    // The static list is a snapshot: a model can exist upstream and not
-    // here, which is why findings are warn-level, never fail.
-    const { getModels } = await import("./models/catalog.js");
-    if (getModels("anthropic").length === 0) {
-      const [{ registerClaudeModelsStatic }, { CLAUDE_MODELS_STATIC }] =
-        await Promise.all([
-          import("../backend/claude-sdk/models/discovery.js"),
-          import("../backend/claude-sdk/models/static.js"),
-        ]);
-      registerClaudeModelsStatic(CLAUDE_MODELS_STATIC);
-    }
-    for (const { key, model, backendId } of targets) {
-      if (!model || model === "default") continue;
-      if ((backendId ?? "claude") !== "claude") continue;
-      const res = await resolveModel(model);
-      if (res.kind === "exact") {
-        checks.push({
-          label: `Model (${key}): ${model} → ${res.model.displayName}`,
-          status: "ok",
-        });
-      } else if (res.kind === "ambiguous") {
-        checks.push({
-          label: `Model (${key}): "${model}" is ambiguous`,
-          status: "warn",
-          detail: res.matches.map((m) => m.displayName).join(", "),
-          issue: true,
-        });
-      } else {
-        checks.push({
-          label: `Model (${key}): "${model}" not selectable on claude`,
-          status: "warn",
-          detail: "turns silently run the backend default — update config.json",
-          issue: true,
-        });
-      }
-    }
-  } catch {
-    /* catalog unavailable — skip, never break doctor */
-  }
-  return checks;
-}
-
 /**
  * Native plugin runtimes (MemPalace's venv, Playwright's browser build,
  * GitHub's Docker image) — the artifacts the provisioners own. The
@@ -337,17 +196,12 @@ async function checkPluginRuntimes(
   return checks;
 }
 
-/** Every backend id doctor knows how to inspect. */
-const KNOWN_BACKENDS = [
-  "claude",
-  "codex",
-  "kilo",
-  "opencode",
-  "openai-agents",
-] as const;
-
 /**
- * Binary / auth checks across every backend the config exposes.
+ * Binary / auth checks across every backend the config exposes, each
+ * supplied by its own factory (`BackendFactory.doctor`) — doctor composes
+ * whatever is registered and hardcodes nothing about any backend. The
+ * caller must have loaded the factories (`loadBuiltinBackends`); an active
+ * backend that is not registered is reported as such, loudly.
  *
  * Only the active one counts toward the issue total; the rest are reported
  * so a switch doesn't have to be the thing that discovers a backend can't
@@ -361,11 +215,11 @@ async function checkBackend(
   const active = config?.backend ?? "claude";
   const exposed = config?.enabledBackends?.length
     ? config.enabledBackends
-    : [...KNOWN_BACKENDS];
+    : listBackends().map((b) => b.id);
 
   const checks = await checkOneBackend(active, config, true);
   for (const id of exposed) {
-    if (id === active || !KNOWN_BACKENDS.includes(id as never)) continue;
+    if (id === active || !getBackend(id)) continue;
     // An idle backend's missing binary is a heads-up, not a fault of this
     // deployment: downgrade it and keep it out of the issue count.
     for (const check of await checkOneBackend(id, config, false)) {
@@ -385,121 +239,35 @@ async function checkOneBackend(
   config: DoctorConfigSlice | undefined,
   isActive: boolean,
 ): Promise<DoctorCheck[]> {
-  const checks: DoctorCheck[] = [];
-
-  if (backend === "claude") {
-    if (config?.claudeBinary) {
-      checks.push(
-        binaryOnPath(config.claudeBinary)
-          ? {
-              label: "Claude Code binary",
-              status: "ok",
-              detail: config.claudeBinary,
-            }
-          : {
-              label: "Claude Code binary not found",
-              status: "fail",
-              detail: config.claudeBinary,
-            },
-      );
-    } else {
-      checks.push(
-        binaryOnPath("claude")
-          ? { label: "Claude Code installed", status: "ok" }
-          : { label: "Claude Code not found", status: "fail" },
-      );
-    }
-    // Model resolution spawns a probe — worth it for the backend actually
-    // serving chats, wasteful for one nobody is using.
-    if (isActive) checks.push(...(await checkClaudeConfiguredModels(config)));
-  } else if (backend === "codex") {
-    if (!binaryOnPath("codex")) {
-      checks.push({
-        label: "Codex CLI not found",
+  const factory = getBackend(backend);
+  if (!factory) {
+    const known = listBackends().map((b) => b.id);
+    return [
+      {
+        label: `Backend "${backend}" is not registered`,
         status: "fail",
-        detail: "npm i -g @openai/codex",
-      });
-      return checks;
-    }
-    checks.push({ label: "Codex CLI installed", status: "ok" });
-    const { detectCodexAuth } = await import("../backend/codex/auth.js");
-    const auth = detectCodexAuth({
-      codexApiKey: config?.codexApiKey,
-      openaiApiKey: config?.openaiApiKey,
-      openaiBaseUrl: config?.openaiBaseUrl,
-    });
-    for (const diagnostic of auth.diagnostics) {
-      checks.push({ label: diagnostic, status: "warn" });
-    }
-    if (auth.mode !== "none") {
-      checks.push({
-        label: "Codex auth",
-        status: "ok",
-        detail: auth.baseUrl ? `${auth.source} (${auth.baseUrl})` : auth.source,
-      });
-    } else {
-      checks.push({
-        label: "Codex auth missing",
-        status: "warn",
-        detail:
-          "set CODEX_API_KEY, TALON_CODEX_KEY, codexApiKey, or run `codex login`",
+        detail: known.length
+          ? `known: ${known.join(", ")}`
+          : "no backends loaded — call loadBuiltinBackends() first",
         issue: true,
-      });
-    }
-  } else if (backend === "kilo" || backend === "opencode") {
-    // The SDK ships as an npm dep but only talks to a server it spawns from
-    // the CLI of the same name (`cross-spawn` → PATH lookup). A present
-    // package with an absent binary fails at the first turn with a bare
-    // ENOENT, so check what actually gets executed.
-    const label = backend === "kilo" ? "Kilo" : "OpenCode";
-    checks.push(
-      binaryOnPath(backend)
-        ? { label: `${label} CLI installed`, status: "ok" }
-        : {
-            label: `${label} CLI not found`,
-            status: "fail",
-            detail: `the ${label} SDK spawns \`${backend}\` — install it or this backend cannot start`,
-            issue: true,
-          },
-    );
-  } else if (backend === "openai-agents") {
-    checks.push({ label: "OpenAI Agents SDK bundled", status: "ok" });
-    const hasEnvKey = Boolean(process.env.OPENAI_API_KEY);
-    const hasCfgKey = Boolean(config?.openaiApiKey);
-    if (hasEnvKey || hasCfgKey) {
-      const sources: string[] = [];
-      if (hasEnvKey) sources.push("OPENAI_API_KEY env");
-      if (hasCfgKey) sources.push("openaiApiKey in talon.json");
-      checks.push({
-        label: "OpenAI Agents auth",
-        status: "ok",
-        detail: sources.join(", "),
-      });
-    } else {
-      checks.push({
-        label: "OpenAI Agents auth missing",
+      },
+    ];
+  }
+  if (!factory.doctor) {
+    return [{ label: `${factory.label}: no doctor checks`, status: "info" }];
+  }
+  try {
+    return await factory.doctor(config, isActive);
+  } catch (err) {
+    return [
+      {
+        label: `${factory.label} doctor check errored`,
         status: "warn",
-        detail: "set OPENAI_API_KEY or openaiApiKey in talon.json",
-        issue: true,
-      });
-    }
-    const envBase = process.env.OPENAI_BASE_URL;
-    const cfgBase = config?.openaiBaseUrl;
-    if (envBase || cfgBase) {
-      checks.push({
-        label: "OpenAI-compatible endpoint",
-        status: "ok",
-        detail: envBase ? `env (${envBase})` : `config (${cfgBase})`,
-      });
-    } else {
-      checks.push({
-        label: "Endpoint: api.openai.com (default)",
-        status: "info",
-      });
-    }
+        detail: errorNote(err),
+        issue: isActive,
+      },
+    ];
   }
-
-  return checks;
 }
 
 /**

package/src/plugins/github/provision.ts

@@ -26,7 +26,7 @@ import { dirs } from "../../util/paths.js";
  * The github-mcp-server image tag Talon runs. Bump deliberately, with
  * the canary workflow green — see .github/workflows/native-provision.yml.
  */
-export const GITHUB_MCP_PINNED_TAG = "v1.11.0";
+export const GITHUB_MCP_PINNED_TAG = "v1.12.1";
 
 const GITHUB_MCP_IMAGE = "ghcr.io/github/github-mcp-server";
 

package/src/util/binary-on-path.ts

@@ -0,0 +1,12 @@
+import { execFileSync } from "node:child_process";
+
+/** Whether `name` resolves on PATH (`which` / `where`), without running it. */
+export function binaryOnPath(name: string): boolean {
+  try {
+    const lookupCmd = process.platform === "win32" ? "where" : "which";
+    execFileSync(lookupCmd, [name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}