@bitkyc08/opencodex 2.63.0-preview.20260923 → 2.64.0-preview.20260923

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

@@ -1,4 +1,5 @@
 import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
+import { captureDesktopAppliedMarker, commitDesktopAppliedMarker } from "../../claude/desktop-applied-marker";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
@@ -231,18 +232,22 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }).kind;
       if (["not_installed", "no_owned_state", "foreign", "unsafe", "broken"].includes(afterKind)) return;
       const routed = filterCatalogVisibleModels(allModels, current).map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
+      const writtenProfile = current.claudeCode.desktopProfile;
+      const markerBaseline = captureDesktopAppliedMarker(writtenProfile);
       const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
         current.port ?? 10100,
         [...desktopVisibleNativeSlugs(current)],
         routed,
         current.apiKeys?.[0]?.key,
         "static",
-        current.claudeCode.desktopProfile,
+        writtenProfile,
         nativeContextLimits(current),
       );
       if (result.written && result.fingerprint) {
-        current.claudeCode = { ...current.claudeCode, desktopProfile: { ...current.claudeCode.desktopProfile, appliedFingerprint: result.fingerprint, appliedAt: new Date().toISOString() } };
-        saveConfigPreservingClaudeCode(current);
+        const marked = commitDesktopAppliedMarker(markerBaseline, result.fingerprint);
+        if (marked.status === "unavailable" || marked.value === false) {
+          console.warn("[claude-desktop] provider-change applied marker skipped");
+        }
       }
     } catch { /* best-effort */ }
   }
@@ -985,9 +990,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     let body: { profile?: unknown };
     try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     try {
-      const { parseDesktopProfile, reconcileDesktopProfile } = await import("../../claude/desktop-profile");
+      const { parseDesktopProfile, preserveDesktopAppliedState, reconcileDesktopProfile, sameProfileContent } = await import("../../claude/desktop-profile");
       const parsed = parseDesktopProfile(body.profile);
-      const current = await buildClaudeDesktopState(config);
+      const initial = loadConfig();
+      const current = await buildClaudeDesktopState(initial);
       const availableRoutes = new Set(current.models.filter(item => item.available).map(item => item.route));
       for (const route of Object.keys(parsed.assignments)) {
         if (!current.profile.assignments[route] && !availableRoutes.has(route)) {
@@ -1008,9 +1014,39 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           throw new Error(`현재 사용할 수 없는 모델은 기본값으로 지정할 수 없습니다: ${nextDefault}`);
         }
       }
-      const state = await buildClaudeDesktopState(config, parsed);
-      config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconcileDesktopProfile(state.profile, state.models) };
-      saveConfigPreservingClaudeCode(config);
+      // Applied markers are server-owned bookkeeping. Discard client copies, then
+      // restore the trusted markers only if the desired profile stayed identical.
+      const editable = { version: 1 as const, assignments: parsed.assignments, defaults: parsed.defaults };
+      const state = await buildClaudeDesktopState(initial, editable);
+      const rebuilt = reconcileDesktopProfile(state.profile, state.models);
+      const expectedProfile = initial.claudeCode?.desktopProfile;
+      const outcome = mutatePersistedConfig<OcxConfig["claudeCode"] | null>(persisted => {
+        const latest = persisted.claudeCode?.desktopProfile;
+        if ((latest == null) !== (expectedProfile == null)
+          || (latest && expectedProfile && !sameProfileContent(latest, expectedProfile))) {
+          return { changed: false, value: null };
+        }
+        persisted.claudeCode = {
+          ...(persisted.claudeCode ?? {}),
+          desktopProfile: preserveDesktopAppliedState(latest ?? current.profile, rebuilt),
+        };
+        return { changed: true, value: structuredClone(persisted.claudeCode) };
+      });
+      if (outcome.status === "unavailable" && outcome.reason !== "conflict") {
+        return jsonResponse({ error: "Claude Desktop profile could not be saved (config " + outcome.reason + ")" }, 500);
+      }
+      if (outcome.status === "unavailable" || outcome.value === null) {
+        return jsonResponse({ error: "Claude Desktop profile changed during save" }, 409);
+      }
+      adoptPersistedClaudeCode(config, outcome.value);
+      // An unarmed live snapshot may prefer its old marker during reconciliation.
+      // Pin the field this route just committed while leaving other live leaves intact.
+      if (outcome.value?.desktopProfile) {
+        config.claudeCode = {
+          ...(config.claudeCode ?? {}),
+          desktopProfile: structuredClone(outcome.value.desktopProfile),
+        };
+      }
       const saved = await buildClaudeDesktopState(config);
       const runtimePort = Number(url.port) || config.port;
       return jsonResponse({ ok: true, ...saved, port: runtimePort });

package/src/server/management/anthropic-reset-grant-routes.ts

@@ -0,0 +1,252 @@
+/**
+ * Management API for Anthropic OAuth usage-limit reset grants.
+ *
+ *   GET  /api/anthropic/reset-grants?accountId=...        read one account's grants
+ *   POST /api/anthropic/reset-grants/consume              spend one grant
+ *
+ * Spending uses the user's own subscription benefit, so the POST requires the
+ * dashboard session principal (AGENTS.md, "User-consent actions"); the admin token
+ * alone is refused. Responses carry fixed codes and fixed messages only: no
+ * upstream body, exception text, token, organization id, or email. Nothing here
+ * logs. Lazy-loaded by `handleAnthropicResetGrantRoutesOnDemand` in
+ * management-api.ts so the core request path never imports it.
+ */
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import { getValidAccessSnapshotForAccount } from "../../oauth";
+import { captureOAuthAccountSelection, listAccounts } from "../../oauth/store";
+import {
+  ANTHROPIC_RESET_GRANT_ID_RE,
+  AnthropicResetGrantError,
+  AnthropicResetGrantUnknownOutcome,
+  anthropicResetGrantBlocker,
+  claimAnthropicResetGrant,
+  fetchAnthropicOrganizationUuid,
+  fetchAnthropicResetGrantStatus,
+} from "../../providers/anthropic-reset-grants";
+import {
+  AnthropicResetLedgerError,
+  anthropicOrgDigest,
+  anthropicResetOperationExists,
+  beginAnthropicResetOperation,
+  pendingAnthropicResetOperation,
+  releaseAnthropicResetLease,
+  settleAnthropicResetOperation,
+} from "../../providers/anthropic-reset-grant-ledger";
+
+const PROVIDER = "anthropic";
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const MESSAGES = {
+  method_not_allowed: "Method not allowed",
+  session_required: "Spending a reset requires a dashboard session.",
+  invalid_json: "Request body must be JSON.",
+  invalid_grant_id: "grantId is missing or malformed.",
+  invalid_operation_id: "operationId must be a UUIDv4.",
+  no_account: "No matching Anthropic OAuth account.",
+  auth_failed: "Sign in to this Anthropic account again.",
+  upstream_unavailable: "Anthropic did not return the reset-grant status.",
+  grant_not_usable: "This reset grant cannot be used right now.",
+  operation_identity_mismatch: "This operation belongs to another account or grant.",
+  in_flight: "This reset is still being processed.",
+  unresolved_prior_operation: "An earlier reset attempt for this grant is not confirmed yet.",
+  unknown_outcome_expired: "This attempt can no longer be retried; re-read the account.",
+  unknown_outcome: "The reset did not answer; its outcome is unknown.",
+  journal_write_failed: "The reset answered but could not be recorded; its outcome is unknown here.",
+  ledger_busy: "The reset journal is busy. Nothing was used.",
+  ledger_unavailable: "The reset journal is unavailable. Nothing was used.",
+  ledger_capacity: "The reset journal is full. Nothing was used.",
+} as const;
+type ErrorCode = keyof typeof MESSAGES;
+
+export interface AnthropicResetGrantRouteDeps {
+  fetchFn?: typeof globalThis.fetch;
+  journalPath?: string;
+  now?: () => number;
+  listAccountIds: () => string[];
+  activeAccountId: () => string | null;
+  accessTokenFor: (accountId: string) => Promise<string>;
+}
+
+const defaultDeps: AnthropicResetGrantRouteDeps = {
+  listAccountIds: () => listAccounts(PROVIDER).map(account => account.id),
+  activeAccountId: () => captureOAuthAccountSelection(PROVIDER)?.accountId ?? null,
+  accessTokenFor: async accountId =>
+    (await getValidAccessSnapshotForAccount(PROVIDER, accountId, { requireUsableAccount: true })).accessToken,
+};
+
+function fail(ctx: ManagementContext, status: number, code: ErrorCode, extra: Record<string, unknown> = {}): Response {
+  return jsonResponse({ error: { code, message: MESSAGES[code], ...extra } }, status, ctx.req, ctx.config);
+}
+
+function ledgerFailure(ctx: ManagementContext, error: unknown): Response {
+  if (error instanceof AnthropicResetLedgerError && error.code === "busy") return fail(ctx, 503, "ledger_busy");
+  return fail(ctx, 503, "ledger_unavailable");
+}
+
+function readFailure(ctx: ManagementContext, error: unknown): Response {
+  if (error instanceof AnthropicResetGrantError && error.code === "auth") return fail(ctx, 401, "auth_failed");
+  return fail(ctx, 502, "upstream_unavailable");
+}
+
+function resolveAccountId(deps: AnthropicResetGrantRouteDeps, requested: unknown): string | null {
+  const ids = deps.listAccountIds();
+  if (typeof requested === "string" && requested.trim() !== "") {
+    return ids.includes(requested.trim()) ? requested.trim() : null;
+  }
+  const active = deps.activeAccountId();
+  return active && ids.includes(active) ? active : ids[0] ?? null;
+}
+
+async function tokenFor(deps: AnthropicResetGrantRouteDeps, accountId: string): Promise<string | null> {
+  try {
+    return await deps.accessTokenFor(accountId);
+  } catch {
+    return null;
+  }
+}
+
+async function handleRead(ctx: ManagementContext, deps: AnthropicResetGrantRouteDeps): Promise<Response> {
+  const accountId = resolveAccountId(deps, ctx.url.searchParams.get("accountId") ?? undefined);
+  if (!accountId) return fail(ctx, 400, "no_account");
+  const accessToken = await tokenFor(deps, accountId);
+  if (!accessToken) return fail(ctx, 401, "auth_failed");
+  let status;
+  try {
+    status = await fetchAnthropicResetGrantStatus({ accessToken, fetchFn: deps.fetchFn });
+  } catch (error) {
+    return readFailure(ctx, error);
+  }
+  let pendingOperation = null;
+  let journalAvailable = true;
+  try {
+    pendingOperation = pendingAnthropicResetOperation(accountId, { journalPath: deps.journalPath, now: deps.now?.() });
+  } catch {
+    journalAvailable = false;
+  }
+  return jsonResponse({ accountId, ...status, pendingOperation, journalAvailable }, 200, ctx.req, ctx.config);
+}
+
+async function handleConsume(ctx: ManagementContext, deps: AnthropicResetGrantRouteDeps): Promise<Response> {
+  if (ctx.principal !== "gui-session") return fail(ctx, 403, "session_required");
+  let body: Record<string, unknown>;
+  try {
+    const parsed = await ctx.req.json() as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return fail(ctx, 400, "invalid_json");
+    body = parsed as Record<string, unknown>;
+  } catch {
+    return fail(ctx, 400, "invalid_json");
+  }
+  const { grantId, operationId } = body;
+  if (typeof grantId !== "string" || !ANTHROPIC_RESET_GRANT_ID_RE.test(grantId)) return fail(ctx, 400, "invalid_grant_id");
+  if (typeof operationId !== "string" || !UUID_V4_RE.test(operationId)) return fail(ctx, 400, "invalid_operation_id");
+  if (typeof body.accountId !== "string") return fail(ctx, 400, "no_account");
+  const accountId = resolveAccountId(deps, body.accountId);
+  if (!accountId) return fail(ctx, 400, "no_account");
+
+  const accessToken = await tokenFor(deps, accountId);
+  if (!accessToken) return fail(ctx, 401, "auth_failed");
+  let organizationUuid: string;
+  try {
+    organizationUuid = await fetchAnthropicOrganizationUuid({ accessToken, fetchFn: deps.fetchFn });
+  } catch (error) {
+    return readFailure(ctx, error);
+  }
+  const ledger = { journalPath: deps.journalPath, now: deps.now?.() };
+
+  // A new operation must pass the spend gate on a fresh read. A same-id retry of
+  // an open record skips it: that attempt was already gated, and upstream
+  // answers a repeated request id for itself.
+  let known: boolean;
+  try {
+    known = anthropicResetOperationExists(operationId, ledger);
+  } catch (error) {
+    return ledgerFailure(ctx, error);
+  }
+  if (!known) {
+    let status;
+    try {
+      status = await fetchAnthropicResetGrantStatus({ accessToken, fetchFn: deps.fetchFn });
+    } catch (error) {
+      return readFailure(ctx, error);
+    }
+    const blocker = anthropicResetGrantBlocker(status, grantId);
+    if (blocker) return fail(ctx, 409, "grant_not_usable", { reason: blocker });
+  }
+
+  let begin;
+  try {
+    begin = beginAnthropicResetOperation(
+      { operationId, accountId, grantId, orgDigest: anthropicOrgDigest(organizationUuid) },
+      { journalPath: deps.journalPath, now: deps.now?.() },
+    );
+  } catch (error) {
+    return ledgerFailure(ctx, error);
+  }
+  switch (begin.kind) {
+    case "replay":
+      return jsonResponse(
+        { code: begin.code, replayed: true, resetsLeft: begin.resetsLeft, accountId, grantId, operationId },
+        200, ctx.req, ctx.config,
+      );
+    case "identity-mismatch": return fail(ctx, 409, "operation_identity_mismatch");
+    case "in-flight": return fail(ctx, 409, "in_flight");
+    case "expired": return fail(ctx, 409, "unknown_outcome_expired");
+    case "unresolved-prior": return fail(ctx, 409, "unresolved_prior_operation", { pendingOperationId: begin.operationId });
+    case "capacity": return fail(ctx, 503, "ledger_capacity");
+    case "execute": break;
+  }
+
+  let answer;
+  try {
+    answer = await claimAnthropicResetGrant({
+      accessToken, organizationUuid, grantId, requestId: operationId, fetchFn: deps.fetchFn,
+    });
+  } catch {
+    try {
+      releaseAnthropicResetLease(operationId, { journalPath: deps.journalPath, now: deps.now?.() });
+    } catch { /* the lease expires on its own */ }
+    return fail(ctx, 502, "unknown_outcome", { operationId, grantId });
+  }
+  let settled;
+  try {
+    settled = settleAnthropicResetOperation(
+      { operationId, code: answer.code, resetsLeft: answer.resetsLeft },
+      { journalPath: deps.journalPath, now: deps.now?.() },
+    );
+  } catch {
+    // Fail closed: the caller must not read this as a durable result.
+    return fail(ctx, 500, "journal_write_failed", { operationId, grantId });
+  }
+  // Report what the journal holds. An overlapping same-id attempt may have
+  // settled first; its answer is the canonical one.
+  const replayed = settled.code !== answer.code || settled.resetsLeft !== answer.resetsLeft;
+  return jsonResponse(
+    {
+      code: settled.code,
+      replayed,
+      resetsLeft: settled.resetsLeft,
+      cleared: replayed ? [] : answer.cleared,
+      accountId,
+      grantId,
+      operationId,
+    },
+    200, ctx.req, ctx.config,
+  );
+}
+
+export async function handleAnthropicResetGrantRoutes(
+  ctx: ManagementContext,
+  deps: AnthropicResetGrantRouteDeps = defaultDeps,
+): Promise<Response | null> {
+  const { pathname } = ctx.url;
+  if (pathname === "/api/anthropic/reset-grants") {
+    if (ctx.req.method !== "GET") return fail(ctx, 405, "method_not_allowed");
+    return handleRead(ctx, deps);
+  }
+  if (pathname === "/api/anthropic/reset-grants/consume") {
+    if (ctx.req.method !== "POST") return fail(ctx, 405, "method_not_allowed");
+    return handleConsume(ctx, deps);
+  }
+  return null;
+}

package/src/server/management/codex-prompt-routes.ts

@@ -403,7 +403,11 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
     }
     if (typeof body.title !== "string") return fail(ctx, "invalid_body", 400, "title must be a string");
     if (typeof body.body !== "string") return fail(ctx, "invalid_body", 400, "body must be a string");
-    return settle(ctx, writeBaseVariant({ id, title: body.title, body: body.body }, revision, paths(ctx)));
+    const normalized = normalizeBody(body.body);
+    if (utf8Bytes(normalized) > MAX_BODY_BYTES) {
+      return fail(ctx, "body_too_large", 400, `base variant exceeds ${MAX_BODY_BYTES} bytes`);
+    }
+    return settle(ctx, writeBaseVariant({ id, title: body.title, body: normalized }, revision, paths(ctx)));
   }
 
   if (url.pathname === "/api/codex-prompt/adopt" && req.method === "POST") {

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

@@ -22,6 +22,7 @@ import {
   providerHeadersConfigError,
   saveConfigPreservingClaudeCode,
 } from "../../config";
+import { captureDesktopAppliedMarker, commitDesktopAppliedMarker } from "../../claude/desktop-applied-marker";
 import {
   clearLoginState,
   getLoginStatus,
@@ -219,18 +220,27 @@ export async function syncEnabledClientIntegrations(
       if (claudeDesktopIntegrationEnabled(latest)) {
         const routed = filterCatalogVisibleModels(models, latest)
           .map(model => ({ provider: model.provider, id: model.id, contextWindow: model.contextWindow }));
+        const writtenProfile = latest.claudeCode?.desktopProfile;
+        const markerBaseline = captureDesktopAppliedMarker(writtenProfile);
         const r = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
           port,
           [...desktopVisibleNativeSlugs(latest)],
           routed,
           latest.apiKeys?.[0]?.key,
           "static",
-          latest.claudeCode?.desktopProfile,
+          writtenProfile,
           nativeContextLimits(latest),
         );
-        out.push(r.written
-          ? { client: "claude-desktop", ok: true, changed: true }
-          : { client: "claude-desktop", ok: false, reason: r.reason ?? "Claude Desktop write failed" });
+        if (!r.written || !r.fingerprint) {
+          out.push({ client: "claude-desktop", ok: false, reason: r.reason ?? "Claude Desktop write failed" });
+        } else {
+          const marked = commitDesktopAppliedMarker(markerBaseline, r.fingerprint);
+          out.push(marked.status === "unavailable"
+            ? { client: "claude-desktop", ok: false, reason: "Claude Desktop applied marker was not saved (" + marked.reason + ")" }
+            : marked.value === false
+            ? { client: "claude-desktop", ok: false, reason: "Claude Desktop desired profile changed during sync; applied marker skipped" }
+            : { client: "claude-desktop", ok: true, changed: true });
+        }
       }
     } catch (error) {
       out.push({ client: "claude-desktop", ok: false, reason: error instanceof Error ? error.message : String(error) });

package/src/server/management/oauth-account-routes.ts

@@ -147,8 +147,16 @@ function validateKeyName(
   return { value };
 }
 
+function metaMuseConsentRequired(provider: string, principal: ManagementContext["principal"]): Response | null {
+  if (provider !== "meta-muse" || principal === "gui-session") return null;
+  return jsonResponse({
+    error: "Meta Muse login requires acknowledgement in the OpenCodex dashboard.",
+    code: "oauth_consent_required",
+  }, 403);
+}
+
 export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<Response | null> {
-  const { req, url, config, deps, syncClaudeAgentDefsBestEffort } = ctx;
+  const { req, url, config, deps, principal, syncClaudeAgentDefsBestEffort } = ctx;
 
   if (url.pathname === "/api/accounts/events" && req.method === "GET") {
     const { accountSelectionStream } = await import("./account-selection-stream");
@@ -172,6 +180,12 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; addAccount?: boolean; accountId?: string; reauth?: boolean; openBrowser?: unknown };
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    // Muse may import a local Keychain credential or start a device grant; add-account
+    // and reauth skip the import. All management login paths require the dashboard
+    // principal before credential acquisition. A raw token proves administration,
+    // not acknowledgement; caller-supplied headers are not consent evidence.
+    const consentRequired = metaMuseConsentRequired(provider, principal);
+    if (consentRequired) return consentRequired;
     const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, provider);
     if (namespaceCollision) return jsonResponse({ error: namespaceCollision }, 409);
     const accountId = body.accountId?.trim();
@@ -242,6 +256,8 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const body = await readManagementJsonBodyOr(req, {}) as { provider?: string; input?: string; code?: string };
     const provider = (body.provider ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
+    const consentRequired = metaMuseConsentRequired(provider, principal);
+    if (consentRequired) return consentRequired;
     const input = typeof body.input === "string" ? body.input : typeof body.code === "string" ? body.code : "";
     // Authorization responses are measured in hundreds of bytes; never accept the
     // generic management-body allowance here.

package/src/server/management/provider-overwrite-carry.ts

@@ -0,0 +1,164 @@
+import { nonBlankStringArrayConfigError, normalizeNonBlankStringArray } from "../../config/provider-validation";
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * What a provider save keeps (#5563).
+ *
+ * `POST /api/providers` with an existing name replaces the stored row with a candidate built from
+ * the request. The dashboard form cannot send the fields below, so a save that omits them used
+ * to drop them from a custom provider, or reset them to the registry seed through
+ * `enrichProviderFromCatalog` for a registry provider. The live-config reconcile cannot restore
+ * them afterwards: the disk row equals its baseline, so the three-way merge keeps the value the
+ * save wrote.
+ *
+ * These five settings record how one upstream behaves. An overwrite that keeps the destination
+ * carries each one the request omits, including an explicit `[]` or `false`. An overwrite that
+ * moves the provider to another destination carries none of them: they describe the previous
+ * upstream, and registry enrichment already fills what is known about the new one. The same
+ * destination rule gates the stored `apiKeyPool`, whose keys were issued for the previous
+ * destination. A value the request sends always wins, and the rest of the old row is never merged
+ * into the candidate.
+ */
+export const PROVIDER_COMPAT_CARRY_FIELDS = [
+  "preserveReasoningContentModels",
+  "requiresReasoningPlaceholderModels",
+  "foldDeveloperRoleToSystem",
+  "reasoningWireFormat",
+  "omitReasoningEffortWithToolsModels",
+] as const satisfies readonly (keyof OcxProviderConfig)[];
+
+export type ProviderCompatCarryField = typeof PROVIDER_COMPAT_CARRY_FIELDS[number];
+
+/** The only `reasoningWireFormat` value the adapters understand. */
+export const PROVIDER_REASONING_WIRE_FORMATS: readonly NonNullable<OcxProviderConfig["reasoningWireFormat"]>[] = [
+  "gateway-object",
+];
+
+/**
+ * Request ownership, sampled before `enrichProviderFromCatalog`. After enrichment "the client
+ * omitted this" and "the registry supplied it" look the same.
+ */
+export interface ProviderOverwriteSample {
+  readonly submitted: ReadonlySet<ProviderCompatCarryField>;
+  readonly namesAuthMode: boolean;
+}
+
+export function sampleProviderOverwrite(provider: object): ProviderOverwriteSample {
+  return {
+    submitted: new Set(PROVIDER_COMPAT_CARRY_FIELDS.filter(field => Object.hasOwn(provider, field))),
+    namesAuthMode: Object.hasOwn(provider, "authMode"),
+  };
+}
+
+function normalizedDestinationUrl(value: unknown): string {
+  if (typeof value !== "string") return "";
+  const trimmed = value.trim();
+  try {
+    const url = new URL(trimmed);
+    return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}${url.search}`;
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+}
+
+/**
+ * Whether an overwrite keeps the provider on the same upstream: same adapter, same base URL
+ * (scheme and host compared case-insensitively, trailing slashes ignored) and, when the request
+ * names one, the same auth mode. The dashboard form sends `authMode` only for key and forward
+ * auth, so an omitted value is not evidence of a move; a stored row without `authMode` is a
+ * key-auth row.
+ */
+export function providerOverwriteKeepsDestination(
+  candidate: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode">,
+  stored: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode"> | undefined,
+  sample: ProviderOverwriteSample,
+): boolean {
+  if (!stored) return false;
+  if ((candidate.adapter ?? "").trim() !== (stored.adapter ?? "").trim()) return false;
+  if (normalizedDestinationUrl(candidate.baseUrl) !== normalizedDestinationUrl(stored.baseUrl)) return false;
+  if (sample.namesAuthMode && (candidate.authMode ?? "key") !== (stored.authMode ?? "key")) return false;
+  return true;
+}
+
+/**
+ * Carry the stored compatibility settings the request omitted. `live` must be the row read after
+ * the route's DNS await, so a PATCH that saved one of them during the wait is kept.
+ */
+export function carryProviderCompatFields(
+  candidate: OcxProviderConfig,
+  live: OcxProviderConfig | undefined,
+  sample: ProviderOverwriteSample,
+): void {
+  if (!live || !providerOverwriteKeepsDestination(candidate, live, sample)) return;
+  const target = candidate as unknown as Record<string, unknown>;
+  for (const field of PROVIDER_COMPAT_CARRY_FIELDS) {
+    if (sample.submitted.has(field)) continue;
+    const stored = live[field];
+    if (stored === undefined) continue;
+    target[field] = Array.isArray(stored) ? [...stored] : stored;
+  }
+}
+
+const REASONING_LIST_FIELDS = ["preserveReasoningContentModels", "requiresReasoningPlaceholderModels"] as const;
+
+/**
+ * Type checks for a POST that does send one of the settings. `omitReasoningEffortWithToolsModels`
+ * is already checked by `providerManagementConfigError`.
+ */
+export function providerCompatFieldConfigError(provider: Record<string, unknown>): string | null {
+  for (const field of REASONING_LIST_FIELDS) {
+    const error = nonBlankStringArrayConfigError(provider[field], field);
+    if (error) return error;
+  }
+  const fold = provider.foldDeveloperRoleToSystem;
+  if (fold !== undefined && typeof fold !== "boolean") return "foldDeveloperRoleToSystem must be a boolean";
+  const wire = provider.reasoningWireFormat;
+  if (wire !== undefined && !PROVIDER_REASONING_WIRE_FORMATS.includes(wire as never)) {
+    return `reasoningWireFormat must be one of: ${PROVIDER_REASONING_WIRE_FORMATS.join(", ")}`;
+  }
+  return null;
+}
+
+/**
+ * PATCH branches for the settings the field mask did not know. `null` clears a field. For the two
+ * reasoning lists an empty array is kept rather than deleted: it is the explicit opt-out that stops
+ * the registry seed from filling the field back in (see the note under OAUTH_RECONCILE_FIELDS in
+ * src/oauth/index.ts).
+ */
+export function applyProviderCompatPatchFields(
+  rawBody: Record<string, unknown>,
+  next: OcxProviderConfig,
+): { touched: boolean } | { error: string } {
+  let touched = false;
+  for (const field of REASONING_LIST_FIELDS) {
+    if (!Object.hasOwn(rawBody, field)) continue;
+    const value = rawBody[field];
+    if (value === null) {
+      delete next[field];
+    } else {
+      const error = nonBlankStringArrayConfigError(value, field);
+      if (error) return { error };
+      next[field] = normalizeNonBlankStringArray(value as string[]);
+    }
+    touched = true;
+  }
+  if (Object.hasOwn(rawBody, "foldDeveloperRoleToSystem")) {
+    const value = rawBody.foldDeveloperRoleToSystem;
+    if (value === null) delete next.foldDeveloperRoleToSystem;
+    else if (typeof value === "boolean") next.foldDeveloperRoleToSystem = value;
+    else return { error: "foldDeveloperRoleToSystem must be a boolean" };
+    touched = true;
+  }
+  if (Object.hasOwn(rawBody, "reasoningWireFormat")) {
+    const value = rawBody.reasoningWireFormat;
+    if (value === null) {
+      delete next.reasoningWireFormat;
+    } else {
+      const format = PROVIDER_REASONING_WIRE_FORMATS.find(candidate => candidate === value);
+      if (!format) return { error: `reasoningWireFormat must be one of: ${PROVIDER_REASONING_WIRE_FORMATS.join(", ")}` };
+      next.reasoningWireFormat = format;
+    }
+    touched = true;
+  }
+  return { touched };
+}