@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/server/management/advisor-routes.ts

@@ -0,0 +1,202 @@
+/**
+ * GET / PUT /api/advisor/settings — the advisor sidecar's management surface.
+ *
+ * GET answers the RESOLVED settings (defaults applied, sources marked) plus availability, so the
+ * GUI/CLI show real runtime state rather than stored fields. PUT is a strict partial patch:
+ * unknown keys and wrong types are refused, values are validated against the same resolver the
+ * runtime reads, and the patch persists through the locked config writer with the snapshot-
+ * restore discipline used by PATCH /api/protocols/settings — a refused or failed write never
+ * leaves the live config serving a state the file does not hold.
+ */
+import { activateAdvisor } from "../../lib/advisor-activation";
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBodyOr } from "./body";
+import type { ManagementContext } from "./context";
+import {
+  ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+  ADVISOR_EFFORTS,
+  advisorContextSharingBlocked,
+  advisorRunnable,
+  isCurrentAdvisorContextSharingConsent,
+  isValidAdvisorEffort,
+  isValidAdvisorPolicy,
+  isValidAdvisorTaskLimit,
+  resolveAdvisorSettings,
+  type AdvisorEffort,
+  type AdvisorPolicy,
+} from "../../advisor/settings";
+import { advisorActivityStore } from "../../advisor/activity";
+
+const INVALID_BODY = Symbol("invalid-body");
+
+interface AdvisorPatch {
+  enabled?: boolean;
+  model?: string;
+  effort?: AdvisorEffort;
+  policy?: AdvisorPolicy;
+  timeoutMs?: number;
+  maxConsultationsPerTask?: number;
+  /** "v1" records current consent. null removes it. Enabling does not imply this field. */
+  contextSharingConsent?: typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION | null;
+  reset?: boolean;
+}
+
+type ParsedPatch = { ok: true; patch: AdvisorPatch } | { ok: false; code: string; message: string };
+
+const PATCH_KEYS = new Set(["enabled", "model", "effort", "policy", "timeoutMs", "maxConsultationsPerTask", "contextSharingConsent", "reset"]);
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Strict: unknown keys and wrong types are refused; messages name the field, never the value. */
+export function parseAdvisorSettingsPatch(body: unknown): ParsedPatch {
+  if (!isRec(body)) return { ok: false, code: "invalid_body", message: "body must be a JSON object" };
+  if (Object.keys(body).length === 0) return { ok: false, code: "empty_body", message: "body must set at least one supported advisor setting or reset" };
+  for (const key of Object.keys(body)) {
+    if (!PATCH_KEYS.has(key)) return { ok: false, code: "unknown_field", message: "body accepts only enabled, model, effort, policy, timeoutMs, maxConsultationsPerTask, contextSharingConsent and reset" };
+  }
+  const patch: AdvisorPatch = {};
+  if (body.reset !== undefined) {
+    if (body.reset !== true) return { ok: false, code: "invalid_reset", message: "reset must be true when present" };
+    if (Object.keys(body).length > 1) return { ok: false, code: "reset_with_fields", message: "reset must be the only field when present" };
+    patch.reset = true;
+    return { ok: true, patch };
+  }
+  if (body.enabled !== undefined) {
+    if (typeof body.enabled !== "boolean") return { ok: false, code: "invalid_enabled", message: "enabled must be a boolean" };
+    patch.enabled = body.enabled;
+  }
+  if (body.model !== undefined) {
+    // An empty or whitespace-only value is the supported "clear the model" state, not an error:
+    // the resolver defaults to an empty model and `advisorRunnable` requires a non-blank one. The
+    // only structural rules are the string type and the trimmed length bound.
+    if (typeof body.model !== "string" || body.model.trim().length > 200) {
+      return {
+        ok: false,
+        code: "invalid_model",
+        message: "model must be a string whose trimmed value is at most 200 characters; an empty value clears the advisor model",
+      };
+    }
+    patch.model = body.model.trim();
+  }
+  if (body.effort !== undefined) {
+    if (!isValidAdvisorEffort(body.effort)) {
+      return { ok: false, code: "invalid_effort", message: `effort must be one of ${ADVISOR_EFFORTS.join(", ")}` };
+    }
+    patch.effort = body.effort;
+  }
+  if (body.policy !== undefined) {
+    if (!isValidAdvisorPolicy(body.policy)) {
+      return { ok: false, code: "invalid_policy", message: 'policy must be "manual", "preflight" or "adaptive"' };
+    }
+    patch.policy = body.policy;
+  }
+  if (body.timeoutMs !== undefined) {
+    if (typeof body.timeoutMs !== "number" || !Number.isFinite(body.timeoutMs) || body.timeoutMs < 1_000 || body.timeoutMs > 600_000) {
+      return { ok: false, code: "invalid_timeout", message: "timeoutMs must be a number between 1000 and 600000" };
+    }
+    patch.timeoutMs = Math.floor(body.timeoutMs);
+  }
+  if (body.maxConsultationsPerTask !== undefined) {
+    if (!isValidAdvisorTaskLimit(body.maxConsultationsPerTask)) return { ok: false, code: "invalid_task_limit", message: "maxConsultationsPerTask must be an integer between 1 and 3" };
+    patch.maxConsultationsPerTask = body.maxConsultationsPerTask;
+  }
+  if (body.contextSharingConsent !== undefined) {
+    if (body.contextSharingConsent === null) {
+      patch.contextSharingConsent = null;
+    } else if (isCurrentAdvisorContextSharingConsent(body.contextSharingConsent)) {
+      patch.contextSharingConsent = body.contextSharingConsent;
+    } else {
+      return {
+        ok: false,
+        code: "invalid_context_sharing_consent",
+        message: `contextSharingConsent must be "${ADVISOR_CONTEXT_SHARING_CONSENT_VERSION}" or null`,
+      };
+    }
+  }
+  return { ok: true, patch };
+}
+
+function advisorInfo(config: ManagementContext["config"]): Record<string, unknown> {
+  const settings = resolveAdvisorSettings(config);
+  const warning = settings.enabled && settings.model.trim() === ""
+    ? "advisor_enabled_without_model"
+    : advisorContextSharingBlocked(settings)
+      ? "advisor_context_sharing_consent_required"
+      : undefined;
+  return {
+    settings,
+    runnable: advisorRunnable(settings),
+    // Enabled without a model cannot consult. Enabled with a model but without current
+    // consent must not send task context; the warning names that block.
+    ...(warning ? { warning } : {}),
+  };
+}
+
+function applyPatchInMemory(config: ManagementContext["config"], patch: AdvisorPatch): void {
+  if (patch.reset) {
+    delete config.advisor;
+    return;
+  }
+  const current: Rec = isRec(config.advisor) ? { ...config.advisor } : {};
+  if (patch.enabled !== undefined) current.enabled = patch.enabled;
+  if (patch.model !== undefined) current.model = patch.model;
+  if (patch.effort !== undefined) current.effort = patch.effort;
+  if (patch.policy !== undefined) current.policy = patch.policy;
+  if (patch.timeoutMs !== undefined) current.timeoutMs = patch.timeoutMs;
+  if (patch.maxConsultationsPerTask !== undefined) current.maxConsultationsPerTask = patch.maxConsultationsPerTask;
+  if (patch.contextSharingConsent === null) delete current.contextSharingConsent;
+  else if (patch.contextSharingConsent !== undefined) current.contextSharingConsent = patch.contextSharingConsent;
+  config.advisor = current as ManagementContext["config"]["advisor"];
+}
+
+function isConfigLockContention(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  if ((error as { code?: unknown }).code !== "CONFIG_MUTATION_LOCK_UNAVAILABLE") return false;
+  return (error as { cause?: { code?: unknown } }).cause?.code === "SQLITE_BUSY";
+}
+
+export async function handleAdvisorRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (url.pathname === "/api/advisor/activity" && req.method === "GET") {
+    return jsonResponse({ entries: advisorActivityStore(config).snapshot(), retention: "process", limit: 100 }, 200, req, config);
+  }
+  if (url.pathname !== "/api/advisor/settings") return null;
+
+  if (req.method === "GET") return jsonResponse(advisorInfo(config), 200, req, config);
+  if (req.method === "PUT") return putAdvisorSettings(ctx);
+  return null;
+}
+
+async function putAdvisorSettings(ctx: ManagementContext): Promise<Response> {
+  const { req, config } = ctx;
+
+  const body = await readManagementJsonBodyOr(req, INVALID_BODY);
+  const parsed = body === INVALID_BODY
+    ? { ok: false as const, code: "invalid_json", message: "body must be valid JSON" }
+    : parseAdvisorSettingsPatch(body);
+  if (!parsed.ok) return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config);
+
+  // Resolve the writer BEFORE touching the live config: a resolution failure must leave the
+  // in-memory config exactly as it was, not rely on the snapshot restore below.
+  // `deps.` first: route tests with an in-memory fixture must never write the real config.
+  const persist = ctx.deps.saveConfigPreservingClaudeCode
+    ?? (await import("../../config")).saveConfigPreservingClaudeCode;
+  const snapshot = isRec(config.advisor) ? { ...config.advisor } : undefined;
+  applyPatchInMemory(config, parsed.patch);
+  try {
+    persist(config);
+  } catch (error) {
+    // Undo in memory too: a live config that serves a state the file does not hold would
+    // mislead every GET until the next restart.
+    if (snapshot === undefined) delete config.advisor;
+    else config.advisor = snapshot as ManagementContext["config"]["advisor"];
+    return isConfigLockContention(error)
+      ? jsonResponse({ error: { code: "config_busy", message: "Another process is saving the configuration. Try again in a moment." } }, 409, req, config)
+      : jsonResponse({ error: { code: "write_failed", message: "The configuration could not be saved." } }, 500, req, config);
+  }
+  activateAdvisor(config);
+  return jsonResponse(advisorInfo(config), 200, req, config);
+}

package/src/server/management/agent-settings-routes.ts

@@ -1397,6 +1397,24 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
 
   // Claude Code inbound settings (GUI "Claude ON" toggle + Claude page).
+  if (url.pathname === "/api/claude-code/model-defaults" && (req.method === "GET" || req.method === "POST")) {
+    const { previewClaudeModelDefaults, applyClaudeModelDefaults, ModelDefaultsRecoveryError } = await import("../../claude/model-default-settings");
+    try {
+      if (req.method === "GET") return jsonResponse(previewClaudeModelDefaults(config.claudeCode?.tierModels));
+      let body: unknown;
+      try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+      if (!body || typeof body !== "object" || Array.isArray(body) || Object.keys(body).length !== 1 ||
+          !("fingerprint" in body) || typeof body.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(body.fingerprint)) {
+        return jsonResponse({ error: "fingerprint is required" }, 400);
+      }
+      return jsonResponse(applyClaudeModelDefaults(config.claudeCode?.tierModels, body.fingerprint));
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      if (error instanceof ModelDefaultsRecoveryError) return jsonResponse({ error: error.message, code: error.message, backupPath: error.backupPath }, 500);
+      const code = error instanceof Error && error.message === "settings_changed" ? "settings_changed" : "settings_unavailable";
+      return jsonResponse({ error: code, code }, code === "settings_changed" ? 409 : 500);
+    }
+  }
   if (url.pathname === "/api/claude-code" && req.method === "GET") {
     const models = await fetchAllModels(config);
     const { listCatalogNativeSlugs } = await import("../../codex/catalog");
@@ -1513,10 +1531,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     });
   }
   if (url.pathname === "/api/claude-code" && req.method === "PUT") {
-    // NOTE: model / tierModels / maxContextTokens / alwaysEnableEffort are
+    // NOTE: model / maxContextTokens / alwaysEnableEffort are
     // CONFIG-ONLY back-compat fields — the GUI no longer offers controls for them
-    // (default model is owned by Claude Code's /model picker; roster agents
-    // supersede tiers; auto-context supersedes the max-context pair; effort rides
+    // (default model is owned by Claude Code's /model picker;
+    // auto-context supersedes the max-context pair; effort rides
     // regardless on 2.1.207). PUT keeps validating them so hand-written configs
     // and older GUIs stay safe; GUI saves omit them and the spread preserves them.
     let parsedBody: unknown;
@@ -1835,7 +1853,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
     }
     if (body.tierModels !== undefined) {
-      // CONFIG-ONLY back-compat (GUI pickers removed — roster agents supersede tiers).
+      // Family defaults also serve third-party callers that request native tier aliases.
       if (body.tierModels === null) {
         delete next.tierModels;
       } else if (!isPlainObject(body.tierModels)) {

package/src/server/management/claude-desktop-picker-routes.ts

@@ -44,7 +44,7 @@ export function pickerPreferenceOn(config: Pick<OcxConfig, "claudeCode">): boole
 }
 
 const PICKER_BODY_KEYS = new Set(["enabled", "persist", "trustedLocally", "callerAddedTrust"]);
-/** Enable outcomes that are progress, not refusal: on, waiting for a Desktop restart, or for the keychain step. */
+/** Enable outcomes that are progress, not refusal: on, waiting for a Desktop restart, or for certificate trust. */
 const ENABLE_ACCEPTED = new Set(["active", "restart_required", "trust_pending"]);
 
 interface PickerRequestBody { enabled: boolean; persist: boolean; trustedLocally?: boolean; callerAddedTrust?: boolean }

package/src/server/management/combo-routes.ts

@@ -52,6 +52,15 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../../lib/debug-settings";
+import { mergeModelCapabilities, modelCapabilitiesConfigError } from "../../config/provider-validation";
+import { modelRecordValue } from "../../reasoning-effort";
+import { commitProviderPatch } from "./provider-patch-transaction";
+import { ConfigWritePublishedError } from "../../config/persist-unlocked";
+import {
+  customRowInputModalities,
+  isVisionSidecarConsumer,
+  modelAcceptsImageInput,
+} from "../../vision/eligibility";
 import type { OcxClaudeCodeConfig, OcxComboConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, OcxComboCooldownWaitPolicy } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
@@ -116,6 +125,43 @@ function sparseComboConfig<T extends {
   };
 }
 
+interface VisionSidecarTarget {
+  provider: string;
+  model: string;
+}
+
+/**
+ * Request-only PUT field: combo members to declare text-only so the Vision Sidecar
+ * covers them when the combo accepts images. Every entry must be an exact target of
+ * the submitted combo, and the whole field is validated before any config mutation.
+ * Nothing from here is persisted under config.combos.
+ */
+function parseVisionSidecarTargets(
+  raw: unknown,
+  comboTargetKeys: ReadonlySet<string>,
+): { targets?: VisionSidecarTarget[]; error?: string } {
+  if (raw === undefined) return {};
+  if (!Array.isArray(raw)) return { error: "visionSidecarTargets must be an array" };
+  const seen = new Set<string>();
+  const targets: VisionSidecarTarget[] = [];
+  for (const entry of raw) {
+    if (!isPlainRecord(entry)) return { error: "visionSidecarTargets entries must be objects" };
+    const provider = typeof entry.provider === "string" ? entry.provider.trim() : "";
+    const model = typeof entry.model === "string" ? entry.model.trim() : "";
+    if (!provider || !model) {
+      return { error: "visionSidecarTargets entries must have nonblank provider and model" };
+    }
+    const key = `${provider}/${model}`;
+    if (!comboTargetKeys.has(key)) {
+      return { error: `visionSidecarTargets entry "${key}" is not a target of this combo` };
+    }
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push({ provider, model });
+  }
+  return { targets };
+}
+
 export async function handleComboRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
 
@@ -176,6 +222,9 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
     const requestedCombo: Record<string, unknown> = body.combo;
     const effectiveCombo = {
       ...requestedCombo,
+      ...(!Object.hasOwn(requestedCombo, "allowMeteredTargets") && previous?.allowMeteredTargets === true
+        ? { allowMeteredTargets: true }
+        : {}),
       ...(!Object.hasOwn(requestedCombo, "cooldownMs") && previous?.cooldownMs !== undefined
         ? { cooldownMs: previous.cooldownMs }
         : {}),
@@ -203,7 +252,7 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
               // A non-record entry stays as the client sent it so comboConfigError reports it.
               // Reading `lastResort` off it here would throw in place of that structured 400.
               if (!isPlainRecord(target)) return target;
-              if (Object.hasOwn(target, "lastResort")) return target;
+              if (["lastResort", "metered"].every(key => Object.hasOwn(target, key))) return target;
               const rawProvider = target.provider;
               const rawModel = target.model;
               if (typeof rawProvider !== "string" || typeof rawModel !== "string") return target;
@@ -214,7 +263,13 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
               const before = previous.targets.find(
                 candidate => candidate.provider === provider && candidate.model === model,
               );
-              return before?.lastResort ? { ...target, lastResort: true } : target;
+              // `metered` is carried the same way: dropping it on a GUI round-trip would open a
+              // pay-per-use target to every issued key.
+              return {
+                ...target,
+                ...(!Object.hasOwn(target, "lastResort") && before?.lastResort ? { lastResort: true } : {}),
+                ...(!Object.hasOwn(target, "metered") && before?.metered ? { metered: true } : {}),
+              };
             }),
           }
         : {}),
@@ -280,6 +335,54 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
       if (routeError) return jsonResponse({ error: issue ? `combo "${otherId}": ${routeError}` : routeError }, 400);
     }
     const normalized = normalizeComboConfig(effectiveCombo as unknown as OcxComboConfig);
+    const sidecarParsed = parseVisionSidecarTargets(
+      body.visionSidecarTargets,
+      new Set(normalized.targets.map((target) => `${target.provider}/${target.model}`)),
+    );
+    if (sidecarParsed.error) return jsonResponse({ error: sidecarParsed.error }, 400);
+    const sidecarPatches = new Map<string, Record<string, { inputModalities: string[] }>>();
+    if (sidecarParsed.targets?.length) {
+      if (normalized.imageInput === "disabled") {
+        return jsonResponse({ error: "visionSidecarTargets requires imageInput not disabled" }, 400);
+      }
+      for (const { provider, model } of sidecarParsed.targets) {
+        const providerRow = config.providers?.[provider];
+        if (!providerRow) {
+          return jsonResponse({ error: `visionSidecarTargets entry "${provider}/${model}" has no configured provider` }, 400);
+        }
+        // A text-only declaration would HIDE a real capability; never overwrite one.
+        if (modelAcceptsImageInput(config, { provider, id: model }) === true) {
+          return jsonResponse({ error: `visionSidecarTargets entry "${provider}/${model}" already accepts image input` }, 400);
+        }
+        // Already a consumer through any runtime source (exact declaration, custom row,
+        // noVisionModels, legacy record, registry enrichment): the catalog already
+        // advertises image for it. Writing the declaration again would be a no-op write.
+        if (isVisionSidecarConsumer(config, provider, model)) continue;
+        // Read the declaration the way the runtime does: exact capability axis, then the
+        // operator's custom row, then the provider's per-model modality hint. A row without
+        // text (audio-only) cannot be widened by the sidecar, and writing ["text"] on the
+        // capability axis would silently override that declaration.
+        const capabilityRow = Object.hasOwn(providerRow.modelCapabilities ?? {}, model)
+          ? providerRow.modelCapabilities?.[model] : undefined;
+        const declared = capabilityRow?.inputModalities
+          ?? customRowInputModalities(config, provider, model)
+          ?? modelRecordValue(providerRow.modelInputModalities, model);
+        if (declared !== undefined && !declared.includes("text")) {
+          return jsonResponse({ error: `visionSidecarTargets entry "${provider}/${model}" is declared without text input; the Vision Sidecar cannot cover it` }, 400);
+        }
+        const patch = sidecarPatches.get(provider) ?? {};
+        patch[model] = { inputModalities: ["text"] };
+        sidecarPatches.set(provider, patch);
+      }
+      for (const [providerName, patch] of sidecarPatches) {
+        // Validate the map that will be persisted, not just the patch: a provider already at
+        // the modelCapabilities cap would otherwise save an oversized map that load-time
+        // sanitization truncates, silently dropping the new text-only declaration.
+        const merged = mergeModelCapabilities(config.providers?.[providerName]?.modelCapabilities, patch);
+        const error = modelCapabilitiesConfigError(patch) ?? (merged ? modelCapabilitiesConfigError(merged) : null);
+        if (error) return jsonResponse({ error: `visionSidecarTargets for provider "${providerName}": ${error}` }, 400);
+      }
+    }
     // Persist only non-default identity/capability fields so config stays sparse.
     // Capability defaults (`imageInput`, `reasoningEffortMode`) go through the same
     // helper the GET/PUT responses use, so the wire shape and the stored shape cannot drift.
@@ -295,9 +398,10 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
       // would add a noise key to every target of every combo, including ones that never use
       // the policy (#5736). Only the opt-in value is stored, matching how the combo-level
       // policy is handled in sparseComboConfig.
-      targets: normalizedBase.targets.map(({ lastResort, modelProfile, ...target }) => ({
+      targets: normalizedBase.targets.map(({ lastResort, metered, modelProfile, ...target }) => ({
         ...target,
         ...(lastResort ? { lastResort: true } : {}),
+        ...(metered ? { metered: true } : {}),
         ...(modelProfile ? { modelProfile } : {}),
       })),
       ...(normalizedAlias ? { alias: normalizedAlias } : {}),
@@ -340,58 +444,80 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
       const targetError = shadowCallTargetError({ ...config, combos: nextCombos }, migratedShadowTarget);
       if (targetError) return jsonResponse({ error: targetError }, 400);
     }
-    config.combos = nextCombos;
-    if (migratedModels.size > 0) {
-      const migrateReference = (model: string): string => migratedModels.get(model) ?? model;
-      const migrateAgentReference = (model: string): string => {
-        const migrated = migrateReference(model);
-        if (migrated !== model) shouldSyncClaudeAgentDefs = true;
-        return migrated;
-      };
-      if (config.subagentModels) {
-        config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
-      }
-      if (config.injectionModel && migratedModels.has(config.injectionModel)) {
-        config.injectionModel = migrateReference(config.injectionModel);
-      }
-      if (config.shadowCallIntercept?.model && migratedModels.has(config.shadowCallIntercept.model)) {
-        config.shadowCallIntercept = {
-          ...config.shadowCallIntercept,
-          model: migrateReference(config.shadowCallIntercept.model),
-        };
-      }
-      if (config.claudeCode) {
-        const claudeCode = { ...config.claudeCode };
-        for (const field of ["model", "smallFastModel"] as const) {
-          if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
-        }
-        if (claudeCode.tierModels) {
-          claudeCode.tierModels = Object.fromEntries(
-            Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
-          );
+    // One atomic transaction: a failed save must restore the combo, the capability
+    // declarations, and every migrated reference together, never partially.
+    try {
+      commitProviderPatch(config, () => {
+        config.combos = nextCombos;
+        if (migratedModels.size > 0) {
+          const migrateReference = (model: string): string => migratedModels.get(model) ?? model;
+          const migrateAgentReference = (model: string): string => {
+            const migrated = migrateReference(model);
+            if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+            return migrated;
+          };
+          if (config.subagentModels) {
+            config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+          }
+          if (config.injectionModel && migratedModels.has(config.injectionModel)) {
+            config.injectionModel = migrateReference(config.injectionModel);
+          }
+          if (config.shadowCallIntercept?.model && migratedModels.has(config.shadowCallIntercept.model)) {
+            config.shadowCallIntercept = {
+              ...config.shadowCallIntercept,
+              model: migrateReference(config.shadowCallIntercept.model),
+            };
+          }
+          if (config.claudeCode) {
+            const claudeCode = { ...config.claudeCode };
+            for (const field of ["model", "smallFastModel"] as const) {
+              if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+            }
+            if (claudeCode.tierModels) {
+              claudeCode.tierModels = Object.fromEntries(
+                Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+              );
+            }
+            if (claudeCode.modelMap) {
+              claudeCode.modelMap = Object.fromEntries(
+                Object.entries(claudeCode.modelMap).map(([source, model]) => [source, migrateAgentReference(model)]),
+              );
+            }
+            if (claudeCode.intercept?.modelMap) {
+              claudeCode.intercept = {
+                ...claudeCode.intercept,
+                modelMap: Object.fromEntries(
+                  Object.entries(claudeCode.intercept.modelMap).map(([pickerId, route]) => [pickerId, migrateAgentReference(route)]),
+                ),
+              };
+            }
+            config.claudeCode = claudeCode;
+          }
         }
-        if (claudeCode.modelMap) {
-          claudeCode.modelMap = Object.fromEntries(
-            Object.entries(claudeCode.modelMap).map(([source, model]) => [source, migrateAgentReference(model)]),
-          );
+        if (oldDisabledSelectors.size > 0 && config.disabledModels) {
+          config.disabledModels = [...new Set(config.disabledModels.map(model => (
+            oldDisabledSelectors.has(model) ? newDisabledModel : model
+          )))];
         }
-        if (claudeCode.intercept?.modelMap) {
-          claudeCode.intercept = {
-            ...claudeCode.intercept,
-            modelMap: Object.fromEntries(
-              Object.entries(claudeCode.intercept.modelMap).map(([pickerId, route]) => [pickerId, migrateAgentReference(route)]),
-            ),
-          };
+        for (const [providerName, patch] of sidecarPatches) {
+          const provider = config.providers?.[providerName];
+          if (!provider) continue;
+          const capabilities = mergeModelCapabilities(provider.modelCapabilities, patch);
+          // Re-check under the config lock: a concurrent edit may have grown the map since
+          // the pre-check, and an oversized map must never be published.
+          if (capabilities && modelCapabilitiesConfigError(capabilities)) {
+            throw new Error("modelCapabilities would exceed its limit");
+          }
+          if (capabilities === undefined) delete provider.modelCapabilities;
+          else provider.modelCapabilities = capabilities;
         }
-        config.claudeCode = claudeCode;
+      }, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
+    } catch (error) {
+      if (!(error instanceof ConfigWritePublishedError)) {
+        return jsonResponse({ error: "combo could not be saved" }, 500);
       }
+      throw error;
     }
-    if (oldDisabledSelectors.size > 0 && config.disabledModels) {
-      config.disabledModels = [...new Set(config.disabledModels.map(model => (
-        oldDisabledSelectors.has(model) ? newDisabledModel : model
-      )))];
-    }
-    saveConfigPreservingClaudeCode(config);
     reconcileLiveStateStores();
     clearComboSelectionState(id);
     clearComboTargetCooldowns(id);

package/src/server/management/companion-routes.ts

@@ -27,6 +27,10 @@ function response(): Response {
 }
 
 export async function handleCompanionRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname === "/api/advisor/settings" || ctx.url.pathname === "/api/advisor/activity") {
+    const { handleAdvisorRoutes } = await import("./advisor-routes");
+    return handleAdvisorRoutes(ctx);
+  }
   if (ctx.url.pathname === "/api/companion/open-in-browser" && ctx.req.method === "POST") {
     let body: unknown;
     try {