@bitkyc08/opencodex 2.68.0 → 2.69.0-preview.20260928

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

@@ -1558,7 +1558,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       catch { return jsonResponse({ error: "Claude settings are unreadable", code: "unreadable" }, 500); }
       type FirstPartyMutation =
         | { refusal: { error: string; code: "intercept_disabled" | "intercept_unavailable" } }
-        | { claudeCode: OcxConfig["claudeCode"]; previous: { present: boolean; value: boolean }; pinnedMode: "first-party" | "gateway" | undefined };
+        | { claudeCode: OcxConfig["claudeCode"]; previous: { present: boolean; value: boolean };
+            pinnedMode: "first-party" | "gateway" | undefined; retainedAmbiguous: boolean };
       let outcome: ReturnType<typeof mutatePersistedConfig<FirstPartyMutation>>;
       try {
         outcome = mutatePersistedConfig<FirstPartyMutation>(persisted => {
@@ -1573,14 +1574,23 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         const before = structuredClone(persisted);
         const previous = { present: Object.hasOwn(persisted.claudeCode ?? {}, "cliFirstParty"),
           value: persisted.claudeCode?.cliFirstParty === true };
-        const pinnedMode = body.cliFirstParty && persisted.claudeCode?.desktopMode === undefined
-          ? resolveClaudeDesktopMode(before, observeClaudeDesktopMode(before)) : undefined;
+        // Pin the mode Desktop resolves to *after* this mutation: while cliFirstParty is set the
+        // shared env is suppressed as Desktop evidence, so an opt-out observed with the flag still
+        // on would pin gateway and disconnect a Desktop install that predates the marker.
+        const observedBefore = structuredClone(before);
+        if (!body.cliFirstParty) delete observedBefore.claudeCode?.cliFirstParty;
+        const pinnedMode = persisted.claudeCode?.desktopMode === undefined
+          ? resolveClaudeDesktopMode(before, observeClaudeDesktopMode(observedBefore)) : undefined;
         const nextBlock = { ...(persisted.claudeCode ?? {}) };
         if (body.cliFirstParty) nextBlock.cliFirstParty = true;
         else delete nextBlock.cliFirstParty;
         if (pinnedMode) nextBlock.desktopMode = pinnedMode;
         commitClaudeCodeBlock(persisted, nextBlock);
-        return { changed: true, value: { claudeCode: structuredClone(persisted.claudeCode), previous, pinnedMode } };
+        // An opt-out that pins first-party from the shared env cannot tell whether that env was
+        // Desktop's or a hand-configured CLI-only one; the env is retained (Desktop keeps its
+        // route) and the caller is warned so it can pin gateway explicitly to release it.
+        const retainedAmbiguous = !body.cliFirstParty && previous.value && pinnedMode === "first-party";
+        return { changed: true, value: { claudeCode: structuredClone(persisted.claudeCode), previous, pinnedMode, retainedAmbiguous } };
         });
       } catch { return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500); }
       if (outcome.status === "unavailable") return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500);
@@ -1630,7 +1640,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const residual = !finalDesired.desktop && !finalDesired.cli
         && readFirstPartyProxyStatus(config, bound?.proxyPort ?? null) !== "none";
       return jsonResponse({ ok: true, enabled: config.claudeCode?.enabled !== false,
-        cliFirstParty: body.cliFirstParty, warnings: residual ? ["settings_residual"] : [] });
+        cliFirstParty: body.cliFirstParty,
+        warnings: [
+          ...(committed.retainedAmbiguous ? ["shared_proxy_retained"] : []),
+          ...(residual ? ["settings_residual"] : []),
+        ] });
     }
     for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
       const section = body[field];

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

@@ -244,9 +244,11 @@ 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, ...target }) =>
-        lastResort ? { ...target, lastResort: true } : target,
-      ),
+      targets: normalizedBase.targets.map(({ lastResort, modelProfile, ...target }) => ({
+        ...target,
+        ...(lastResort ? { lastResort: true } : {}),
+        ...(modelProfile ? { modelProfile } : {}),
+      })),
       ...(normalizedAlias ? { alias: normalizedAlias } : {}),
       ...(normalizedNativeAlias ? { nativeAlias: true } : {}),
       ...(normalizedDisplayName ? { displayName: normalizedDisplayName } : {}),

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

@@ -1,4 +1,4 @@
-import { compactionRoutingSchema } from "../../config/schema/leaf-validators";
+import { compactionRoutingSchema, memoryModelsSchema } from "../../config/schema/leaf-validators";
 import { compactionRecoverySchema } from "../../config/schema/compaction-recovery";
 import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
 import type { IntegrationClientId } from "../../integrations/registry";
@@ -272,7 +272,7 @@ export async function syncEnabledClientIntegrations(
     },
     config,
     port,
-  }, ["mcode", "pi", "aside", "raycast", "omo", "cline"]));
+  }, ["mcode", "pi", "aside", "raycast", "omo", "cline", "droid"]));
 
   return out;
 }
@@ -374,6 +374,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopSwitches: describeCodexDesktopSwitches(config, await observedCodexDesktopSwitchApply()),
       compactionRouting: config.compactionRouting ?? null,
       compactionRecovery: config.compactionRecovery ?? null,
+      // Absent means both phases keep their existing routes; the GUI renders that as "Off".
+      memoryModels: config.memoryModels ?? null,
       startupHealth: await readStartupHealthSnapshot(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -467,6 +469,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexClientCompaction?: unknown;
       compactionRouting?: unknown;
       compactionRecovery?: unknown;
+      memoryModels?: unknown;
     };
     if (body.codexAutoStart === undefined
       && body.streamMode === undefined
@@ -479,8 +482,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       && body.codexMainAccountHardLock === undefined
       && body.codexDesktopAuthless === undefined
       && body.codexClientCompaction === undefined
-      && body.compactionRouting === undefined && body.compactionRecovery === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, fastRows, codexMainAccountHardLock, codexDesktopAuthless, codexClientCompaction, compactionRouting, or compactionRecovery" }, 400);
+      && body.compactionRouting === undefined
+      && body.compactionRecovery === undefined
+      && body.memoryModels === undefined) {
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, fastRows, codexMainAccountHardLock, codexDesktopAuthless, codexClientCompaction, compactionRouting, compactionRecovery, or memoryModels" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
@@ -518,6 +523,12 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (compactionRouting != null && !compactionRouting.success) {
       return jsonResponse({ error: "compactionRouting requires a model, an optional valid reasoningEffort, and optional non-repeating triggers drawn from \"manual\" and \"auto\"" }, 400);
     }
+    const memoryModels = body.memoryModels == null
+      ? body.memoryModels
+      : memoryModelsSchema.safeParse(body.memoryModels);
+    if (memoryModels != null && !memoryModels.success) {
+      return jsonResponse({ error: "memoryModels requires a nonblank model and an optional declared reasoningEffort per configured phase, and no other fields" }, 400);
+    }
     let quotaAutoRefreshChange: { id: string; window: "fiveHour" | "weekly"; enabled: boolean } | undefined;
     if (body.codexQuotaAutoRefresh !== undefined) {
       if (!isPlainRecord(body.codexQuotaAutoRefresh)) {
@@ -547,7 +558,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     )) {
       return jsonResponse({ error: `appOwnedMemoryBudgetMb must be an integer from ${MIN_APP_OWNED_MEMORY_BUDGET_MB} to ${MAX_APP_OWNED_MEMORY_BUDGET_MB}` }, 400);
     }
-    const restoreCompactionRouting = captureConfigTopLevelRollback(config, ["compactionRouting", "compactionRecovery"]);
+    const restoreCompactionRouting = captureConfigTopLevelRollback(config, ["compactionRouting", "compactionRecovery", "memoryModels"]);
     const previousSettings = {
       codexAutoStart: config.codexAutoStart,
       hasCodexAutoStart: Object.hasOwn(config, "codexAutoStart"),
@@ -620,6 +631,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       else if (compactionRouting?.success) config.compactionRouting = compactionRouting.data;
       if (compactionRecovery === null) deleteConfigTopLevelKey(config, "compactionRecovery");
       else if (compactionRecovery?.success) config.compactionRecovery = compactionRecovery.data;
+      // Null clears both phases; the GUI sends that when neither row names a model.
+      if (memoryModels === null) deleteConfigTopLevelKey(config, "memoryModels");
+      else if (memoryModels?.success) config.memoryModels = memoryModels.data;
       if (quotaAutoRefreshChange) {
         const { id, window, enabled } = quotaAutoRefreshChange;
         const setting = { ...(config.codexQuotaAutoRefresh?.[id] ?? {}) };
@@ -722,6 +736,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopSwitches,
       compactionRouting: config.compactionRouting ?? null,
       compactionRecovery: config.compactionRecovery ?? null,
+      // The panel re-reads its own save response, so a missing block would render both
+      // phases as "Off" while the server kept them.
+      memoryModels: config.memoryModels ?? null,
       codexMainAccountHardLock: isMainAccountHardLockEnabled(config),
       mainAccountHardLock: getMainAccountHardLockStatus(config),
       startupHealth: await readStartupHealthSnapshot(config),
@@ -772,7 +789,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
   }
 
   if (url.pathname === "/api/update/run" && req.method === "POST") {
-    const { normalizeUpdateChannel, startUpdateJob, UpdateJobError } = await import("../../update/job");
+    const { normalizeUpdateChannel, startUpdateJob, UpdateJobError, spawnGuiUpdateWorker } = await import("../../update/job");
     let body: { tag?: unknown; restart?: unknown };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (body.tag !== undefined && body.tag !== "latest" && body.tag !== "preview") {
@@ -785,8 +802,17 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       const channel = normalizeUpdateChannel(body.tag as string | undefined);
       const { packageRefresh } = await import("../../update/refresh-scheduler");
       const checked = await (deps.checkPackageUpdate ?? packageRefresh.check)(channel);
+      // Resolve the systemd-scope launcher before spawning: the first request
+      // would otherwise run up to four sequential five-second probes inside
+      // spawnSync on the shared event loop.
+      const { resolveSystemdRunAsync } = await import("../../update/worker-launch");
+      const systemdRun = process.platform === "linux" && process.env.INVOCATION_ID
+        ? await resolveSystemdRunAsync()
+        : undefined;
       return jsonResponse({ ok: true, job: startUpdateJob(channel, body.restart !== false, {
         checkForUpdateFn: () => checked,
+        spawnWorkerFn: (jobId, runChannel, runRestart) =>
+          spawnGuiUpdateWorker(jobId, runChannel, runRestart, { resolveSystemdRun: () => systemdRun }),
       }) });
     } catch (err) {
       if (err instanceof UpdateJobError) {

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

@@ -11,9 +11,17 @@ import { shouldInjectApiAuthHeader } from "../../codex/loopback-target";
  * be handed back to the GUI and CLI as if it were real, and the offline `ocx models add` path
  * already refuses it. Validate at ingress so all three paths agree.
  */
-const ALLOWED_INPUT_MODALITIES = new Set(["text", "image", "audio"]);
+/**
+ * The modalities a declaration may carry. `video` is missing on purpose: the wire carries text
+ * and image parts, so advertising it would be a promise no request path can keep.
+ */
+type DeclaredInputModality = NonNullable<ModelCapabilities["inputModalities"]>[number];
+
+// A plain string set on purpose: the lookup runs against unvalidated input, and the enum lives in
+// the return type below, where the cast is the validator's stated guarantee.
+const ALLOWED_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "image", "audio"]);
 
-function readInputModalities(raw: unknown): { values?: string[]; error?: string } {
+function readInputModalities(raw: unknown): { values?: DeclaredInputModality[]; error?: string } {
   if (raw === undefined) return {};
   if (!Array.isArray(raw)) return { error: "inputModalities must be an array" };
   // Reject non-strings rather than filtering them out. Dropping them silently accepted a
@@ -28,7 +36,7 @@ function readInputModalities(raw: unknown): { values?: string[]; error?: string
   if (rejected.length > 0) {
     return { error: `unsupported input modality: ${rejected.join(", ")} (allowed: text, image, audio)` };
   }
-  return { values: raw as string[] };
+  return { values: raw as DeclaredInputModality[] };
 }
 
 /**
@@ -108,6 +116,9 @@ import { encodedModelIdCollides, routedSlug, slugEquals } from "../../providers/
 import { knownModelIdsForProvider } from "../../router";
 import { effectiveModelAliases, MODEL_ALIAS_PATTERN } from "../../providers/default-aliases";
 import { isValidModelDiscoveryModelId } from "../../providers/model-discovery-limits";
+import { commitProviderPatch } from "./provider-patch-transaction";
+import { ConfigWritePublishedError } from "../../config/persist-unlocked";
+import type { CatalogDisposition } from "../../codex/convergence-types";
 import { comboPublicModelId } from "../../combos/types";
 import { COMBO_NAMESPACE, comboDisabledModelSelectors, comboModelId, preservesPhysicalComboProvider } from "../../combos";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
@@ -131,7 +142,7 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../../lib/debug-settings";
-import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, ProviderCostOverlay } from "../../types";
+import type { ModelCapabilities, OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, ProviderCostOverlay } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
@@ -157,7 +168,7 @@ import type {
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
 import type { ManagementContext } from "./context";
-import { listManagementModelRows, loadExportModels } from "./model-rows";
+import { effectiveModelReasoningEfforts, inheritedModelReasoningEfforts, listManagementModelRows, loadExportModels } from "./model-rows";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import {
@@ -545,9 +556,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       if (!(error instanceof ClientPathError)) throw error;
       return jsonResponse({ error: error.message }, 400, req, config);
     }
-    if (requested === "raycast" && shouldInjectApiAuthHeader(config)) {
+    if ((requested === "raycast" || requested === "droid") && shouldInjectApiAuthHeader(config)) {
       return jsonResponse({
-        error: "Raycast export requires an unauthenticated loopback destination; this listener requires an admission header Raycast cannot supply.",
+        error: `${requested === "droid" ? "Factory Droid" : "Raycast"} export requires an unauthenticated loopback destination; this listener requires an admission header the client cannot supply.`,
         reason: "non_loopback",
       }, 400, req, config);
     }
@@ -733,6 +744,220 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     return jsonResponse(config.customModels ?? []);
   }
 
+  /*
+   * Per-model overrides for a routed row, addressed by provider + upstream model id.
+   *
+   * Deliberately not a custom model. A custom model is a row the operator declares; this edits
+   * facts about a row that already exists, through the provider-level per-model maps the runtime
+   * already reads. Creating a custom model to change one field would replace the row's identity
+   * and its discovery provenance, which is the opposite of what an edit means.
+   *
+   * Every field is optional and `null` CLEARS the declaration rather than writing a default: that
+   * is what hands the fact back to the registry, the catalog and the provider, instead of pinning
+   * today's answer as an override that silently outlives the data it came from.
+   *
+   * Display name is not here on purpose. The row already has a dedicated editor for it
+   * (PUT /api/providers/{provider}/model-display-names) with its own provenance display; a second
+   * control writing the same key is two statements that can drift, and this endpoint's job is the
+   * capability axes nothing else edits.
+   */
+  if (url.pathname === "/api/model-settings" && req.method === "PUT") {
+    let parsedBody: unknown;
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid model settings request" }, 400);
+    const body = parsedBody;
+    for (const key of Object.keys(body)) {
+      if (!["provider", "modelId", "contextWindow", "inputModalities", "reasoningEfforts", "defaultReasoningEffort"].includes(key)) {
+        return jsonResponse({ error: `unknown model settings field: ${key}` }, 400);
+      }
+    }
+    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
+    const modelId = typeof body.modelId === "string" ? body.modelId : "";
+    if (!provider || !modelId) return jsonResponse({ error: "provider and modelId are required" }, 400);
+    if (!isValidModelDiscoveryModelId(modelId) || ["__proto__", "constructor", "prototype"].includes(modelId)) {
+      return jsonResponse({ error: "modelId must be an exact non-reserved model id" }, 400);
+    }
+    if (!isValidProviderName(provider) || !hasOwnProvider(config.providers, provider)) {
+      return jsonResponse({ error: "unknown model settings provider" }, 400);
+    }
+    // "openai" is the native passthrough lane and "combo" is a synthetic row: neither is a
+    // provider whose per-model maps the runtime consults for these facts.
+    if (provider === "openai" || provider === "combo") {
+      return jsonResponse({ error: "model settings are only available for routed providers" }, 400);
+    }
+
+    const providerConfig = { ...config.providers[provider] };
+    const storedLadder = providerConfig.modelReasoningEfforts?.[modelId];
+
+    let contextWindow: number | null | undefined;
+    if (body.contextWindow !== undefined) {
+      if (body.contextWindow === null) contextWindow = null;
+      else if (typeof body.contextWindow === "number" && Number.isSafeInteger(body.contextWindow) && body.contextWindow > 0) {
+        contextWindow = body.contextWindow;
+      } else return jsonResponse({ error: "contextWindow must be a positive safe integer or null" }, 400);
+    }
+    let modalities: DeclaredInputModality[] | null | undefined;
+    if (body.inputModalities !== undefined) {
+      if (body.inputModalities === null) modalities = null;
+      else {
+        const parsed = readInputModalities(body.inputModalities);
+        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
+        // An empty array means "cleared", exactly like null: a model that accepts no modality at
+        // all is not a state this surface can express, and storing [] would advertise text-only
+        // through a value the catalog then has to special-case.
+        // Deduplicated before the unchanged check and before the write: `["text","text"]` against
+        // a stored `["text","image"]` passes a length test and an every-member test, so the
+        // operator's edit would be dropped as a no-op; when it did differ, the duplicates would be
+        // persisted as submitted.
+        const unique = parsed.values ? [...new Set(parsed.values)] : [];
+        modalities = unique.length > 0 ? unique : null;
+      }
+    }
+    let ladder: string[] | null | undefined;
+    if (body.reasoningEfforts !== undefined) {
+      if (body.reasoningEfforts === null) ladder = null;
+      else {
+        const parsed = readReasoningEfforts(body.reasoningEfforts);
+        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
+        ladder = parsed.values ?? [];
+      }
+    }
+    /*
+     * Validated against the ladder this write leaves behind, not the one that happens to be stored:
+     * a caller replacing both in one request must not be rejected for the value it is replacing, and
+     * a default-only request must be judged against the ladder the model actually resolves — which
+     * may be the provider-level, registry, native or catalog one, not only a per-model entry.
+     * `inheritedModelReasoningEfforts` is what the clear case leaves behind: it removes the model's
+     * entry from a copy before resolving, so it answers the post-write state.
+     */
+    const resultingLadder = ladder === undefined
+      ? (Array.isArray(storedLadder) ? storedLadder : effectiveModelReasoningEfforts(config, provider, modelId))
+      : (ladder ?? inheritedModelReasoningEfforts(config, provider, modelId));
+    const defaultEffort = readDefaultReasoningEffort(body.defaultReasoningEffort, resultingLadder);
+    if (defaultEffort.error) return jsonResponse({ error: defaultEffort.error }, 400);
+
+    let changed = false;
+    const writePerModel = (
+      key: "modelContextWindows" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts",
+      value: unknown,
+    ) => {
+      if (value === undefined) return;
+      const bag = providerConfig as unknown as Record<string, unknown>;
+      const record: Record<string, unknown> = Object.assign(Object.create(null), (bag[key] as Record<string, unknown> | undefined) ?? {});
+      const present = Object.prototype.hasOwnProperty.call(record, modelId);
+      if (value === null) {
+        if (!present) return;
+        delete record[modelId];
+        changed = true;
+      } else {
+        if (present && JSON.stringify(record[modelId]) === JSON.stringify(value)) return;
+        record[modelId] = value;
+        changed = true;
+      }
+      // An emptied map is removed rather than left as {}. The maps are optional config fields, and
+      // an empty one is indistinguishable from a configured-but-blank state to every reader.
+      if (Object.keys(record).length === 0) delete bag[key];
+      else bag[key] = record;
+    };
+    writePerModel("modelContextWindows", contextWindow);
+    writePerModel("modelReasoningEfforts", ladder);
+    if (body.defaultReasoningEffort !== undefined) {
+      writePerModel("modelDefaultReasoningEfforts", defaultEffort.value === undefined ? null : defaultEffort.value);
+    } else if (ladder !== undefined) {
+      /*
+       * A ladder write can strand a stored default that the model can no longer select, and the
+       * catalog would then publish a default outside its own ladder. The caller said nothing about
+       * the default, so only one that cannot survive is cleared. With `ladder === null` the override
+       * is gone and the ladder to test against is the inherited one — read from the config after the
+       * write, which no longer carries the removed entry.
+       */
+      const storedDefault = providerConfig.modelDefaultReasoningEfforts?.[modelId];
+      const nextConfig = { ...config, providers: { ...config.providers, [provider]: providerConfig } };
+      const effectiveLadder = ladder ?? effectiveModelReasoningEfforts(nextConfig, provider, modelId);
+      if (typeof storedDefault === "string" && !(effectiveLadder ?? []).includes(storedDefault)) {
+        writePerModel("modelDefaultReasoningEfforts", null);
+      }
+    }
+    if (modalities !== undefined) {
+      const capabilities = Object.assign(Object.create(null), providerConfig.modelCapabilities ?? {}) as NonNullable<typeof providerConfig.modelCapabilities>;
+      const row = { ...(capabilities[modelId] ?? {}) };
+      const declared = Array.isArray(row.inputModalities) ? [...row.inputModalities] : undefined;
+      const unchanged = modalities === null
+        ? declared === undefined
+        : declared !== undefined
+          && declared.length === modalities.length
+          && modalities.every(modality => declared.includes(modality));
+      if (!unchanged) {
+        changed = true;
+        if (modalities === null) delete row.inputModalities;
+        else row.inputModalities = modalities;
+        if (Object.keys(row).length === 0) delete capabilities[modelId];
+        else capabilities[modelId] = row;
+        if (Object.keys(capabilities).length === 0) delete providerConfig.modelCapabilities;
+        else providerConfig.modelCapabilities = capabilities;
+      }
+      /*
+       * The legacy `modelInputModalities` record is the fallback `declaredModelInputModalities` and the
+       * router read once the capability entry is gone. A clear that left its exact entry behind would
+       * report "restored" while the old declaration stayed in force. Only the exact key is removed: a
+       * family or case-folded key covers other models too, and stays a provider-level declaration.
+       */
+      const legacy = providerConfig.modelInputModalities;
+      if (modalities === null && legacy && Object.hasOwn(legacy, modelId)) {
+        const next: Record<string, string[]> = Object.assign(Object.create(null), legacy);
+        delete next[modelId];
+        changed = true;
+        if (Object.keys(next).length === 0) delete providerConfig.modelInputModalities;
+        else providerConfig.modelInputModalities = next;
+      }
+    }
+
+    const hasOverrides = [providerConfig.modelContextWindows, providerConfig.modelReasoningEfforts,
+      providerConfig.modelDefaultReasoningEfforts, providerConfig.modelInputModalities]
+      .some(map => map !== undefined && Object.hasOwn(map, modelId))
+      || providerConfig.modelCapabilities?.[modelId]?.inputModalities !== undefined;
+    const state = {
+      ok: true as const,
+      provider,
+      modelId,
+      hasOverrides,
+      contextWindow: providerConfig.modelContextWindows?.[modelId] ?? null,
+      inputModalities: providerConfig.modelCapabilities?.[modelId]?.inputModalities ?? null,
+      reasoningEfforts: providerConfig.modelReasoningEfforts?.[modelId] ?? null,
+      defaultReasoningEffort: providerConfig.modelDefaultReasoningEfforts?.[modelId] ?? null,
+    };
+    // A no-op can still retain stored declarations; `hasOverrides` reports that independently.
+    if (!changed) return jsonResponse({ ...state, changed: false, saved: false,
+      catalogRefresh: { status: "skipped", reason: "not-requested", retryable: false } });
+    let publicationError = false;
+    try {
+      commitProviderPatch(config, () => { config.providers[provider] = providerConfig; }, persistConfig);
+    } catch (error) {
+      if (!(error instanceof ConfigWritePublishedError)) {
+        return jsonResponse({ error: "model settings could not be saved" }, 500);
+      }
+      publicationError = true;
+    }
+    /*
+     * Drop this provider's live `/models` cache before converging.
+     *
+     * The gather bakes the resolved hints into the rows it caches, and on a cache hit it re-applies
+     * the config through `clampObservedModelLimits`, where a configured window may only LOWER the
+     * observed one. A raised or cleared override would therefore keep reading back the previous
+     * answer for the whole TTL, and a cleared modality or ladder would keep the baked one. Clearing
+     * the entry is what makes the save visible on the next read, the same reason
+     * `PUT /api/provider-context-caps` clears it per affected provider.
+     */
+    clearModelCache(provider);
+    let catalogRefresh: CatalogDisposition;
+    if (publicationError) catalogRefresh = { status: "skipped", reason: "not-requested", retryable: true };
+    else {
+      try { catalogRefresh = await convergeCodexCatalog(); }
+      catch { catalogRefresh = { status: "failed", reason: "internal", phase: "gather", retryable: true, partialWrite: false }; }
+    }
+    return jsonResponse({ ...state, changed: true, saved: true, catalogRefresh });
+  }
+
   if (url.pathname === "/api/custom-models" && req.method === "POST") {
     let parsedBody: unknown;
     try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }