UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,926 lines • 121 kB
import { prepareClaudeCodePatch } from "./claude-code-settings-patch";
import { beginCodexCliSelectionParentWriteAsync, withCodexCliSelectionParentWriteAsync,
  CodexCliSelectionMutationBusyError, type CodexCliSelectionAsyncParentWrite } from "../../codex/cli-update-selection-gate";
import { readConfigForAdmittedMutation } from "../../config/persisted-mutation";
import { mirrorDesiredEnabledOntoSnapshot, persistDesktopModeField, persistDesktopProfileField } from "./claude-desktop-config-writers";
import { getConfigDir as configRoot, withConfigDirHardeningSettled as settleConfigRoot } from "../../config/paths";
import { WindowsSecretAclSettleTimeoutError } from "../../lib/windows-secret-acl";
import { ensureManagementClaudeIntercept, interceptStartRefusal, interceptStatus } from "./claude-intercept-routes";
import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
import { captureDesktopAppliedMarker, commitDesktopAppliedMarker } from "../../claude/desktop-applied-marker";
import { isPassiveRead } from "../../lib/passive-read";
import { captureHomeRouteDefaultsBeforeHomeSwitch } from "../../routing/home-route-capture";
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import { dirname } from "node:path";
import { prepareCodexHome } from "../../codex/prepared-home";
import { codexHomeIsAbsent } from "../../codex/codex-home-owner";
import type { CatalogModel } from "../../codex/catalog";
import { catalogModelSlug, filterCatalogVisibleModels, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
import { mergeModelPinnedEfforts, modelPinnedEffortsConfigError } from "../../config/provider-validation";
import { MULTI_AGENT_SURFACE_ADVISORY_VERSION, multiAgentSurfaceAdvisory, resolveMultiAgentMode } from "../../config/multi-agent-surface";
import { isPlaintextV2AgentMessagesEnabled } from "../../config/multi-agent-surface";
import { captureConfigTopLevelRollback, parsedConfigRebaseDeletionKeys, projectConfigRebaseProvenance } from "../../config/rebase-provenance";
import { ConfigWritePublishedError } from "../../config/persist-unlocked";
import { anthropicSidecarPatchError } from "../../config/schema/anthropic-account-pool";
import { agyAcpUnattendedTargetIssues } from "../../config/schema/agy-acp-references";
import { isAnthropicInstanceId } from "../../providers/anthropic-instance-id";
import {
  adoptPersistedClaudeCode,
  DEFAULT_SUBAGENT_MODELS,
  codexAutoStartEnabled,
  deleteConfigTopLevelKey,
  hasOwnProvider,
  isValidProviderName,
  loadConfig,
  multiAgentGuidanceEnabled,
  mutatePersistedConfig,
  providerBaseUrlConfigError,
  providerHeadersConfigError,
  saveConfigPreservingClaudeCode,
  subagentDefaultSyncEffective,
  validateConfigCandidate,
} from "../../config";
import {
  clearLoginState,
  getLoginStatus,
  isPublicOAuthProvider,
  listOAuthProviders,
  startLoginFlow,
  submitManualLoginCode,
  upsertOAuthProvider,
} from "../../oauth";
import { removeCredential } from "../../oauth/store";
import { providerDestinationResolvedError } from "../../lib/destination-policy";
import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
import { deriveProviderPresets } from "../../providers/derive";
import { providerCodexAccountMode } from "../../providers/registry";
import { hasRoutedSlug, routedSlug, slugEquals } from "../../providers/slug-codec";
import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import { clearThreadAccountMap } from "../../codex/routing";
import { primeCodexPoolQuotas } from "../../codex/auth-api";
import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
import { resolveCodexHomeDir } from "../../codex/home";
import { siblingOfLivePort } from "../../codex/sibling-start";
import { MULTI_AGENT_MODE_HINT_RECOMMENDATION } from "../../codex/multi-agent-mode-policy";
import { readUsageEntries } from "../../usage/log";
import { getUsageDebugLogEntries } from "../../usage/debug";
import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
import { getProviderRegistryEntry } from "../../providers/registry";
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
import {
  clearDebugSettings,
  clearDebugSetting,
  getDebugSettings,
  setDebugSettings,
  type DebugFlag,
} from "../../lib/debug-settings";
import type { OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
import {
  visionCandidateRows,
  visionDescriberIsProvablyBlind,
  visionDescriberRejection,
} from "./vision-sidecar-options";
import {
  webSearchCandidateRows,
  webSearchModelIsRejected,
  webSearchModelRejection,
  sidecarAnthropicPoolOptions,
  sidecarSettingsAfterPatch,
  sidecarOptionsAuth,
  type WebSearchBackend,
} from "./web-search-sidecar-options";
import { drainAndShutdown } from "../lifecycle";
import { inheritedAnthropicInstance } from "../../sidecar/auth";
import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
import type { PersistedUsageAttempt } from "../../usage/log";
import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
import { applySystemEnvToggle } from "../system-env";

import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchInitializedModels as fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
import { readManagementJsonBody, readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";

const GROK_APPLY_JOIN_MS = 120_000;
export const GROK_APPLY_TERMINAL_MS = 10 * 60_000;
const grokApplyEncoder = new TextEncoder();
let grokApplyFlight: { startedAt: number; promise: Promise<unknown>; bytes: number } | null = null;
let grokApplyHighWaterBytes = 0;
let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | null = null;

class GrokApplyBusyError extends Error {}

export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
  return {
    currentBytes: grokApplyFlight?.bytes ?? 0,
    highWaterBytes: grokApplyHighWaterBytes,
    active: grokApplyFlight ? 1 : 0,
  };
}

function runGrokApplyFlight(): Promise<unknown> {
  const at = grokApplyTestHooks?.now?.() ?? Date.now();
  const current = grokApplyFlight;
  if (current) {
    const age = at - current.startedAt;
    if (age < GROK_APPLY_JOIN_MS) return current.promise;
    if (age <= GROK_APPLY_TERMINAL_MS) return Promise.reject(new GrokApplyBusyError("grok_apply_busy"));
    // A permanently hung operation must not monopolize the singleton forever. Its
    // eventual finally is identity-checked, so it cannot clear a replacement flight.
    if (grokApplyFlight === current) grokApplyFlight = null;
  }

  const flight = { startedAt: at, promise: Promise.resolve() as Promise<unknown>, bytes: 0 };
  flight.promise = (grokApplyTestHooks?.run ?? (async () => {
    const [{ syncGrokConfig }, { readRuntimePort }] = await Promise.all([
      import("../../grok/sync"),
      import("../../config/process-state"),
    ]);
    const currentConfig = loadConfig();
    const runtime = readRuntimePort(process.pid);
    const port = runtime?.port ?? currentConfig.port;
    const hostname = runtime?.hostname ?? currentConfig.hostname;
    flight.bytes = grokApplyEncoder.encode(JSON.stringify(currentConfig)).byteLength
      + grokApplyEncoder.encode(hostname ?? "").byteLength;
    grokApplyHighWaterBytes = Math.max(grokApplyHighWaterBytes, flight.bytes);
    return syncGrokConfig(port, currentConfig, hostname !== undefined ? { hostname } : {});
  }))().finally(() => {
    if (grokApplyFlight === flight) grokApplyFlight = null;
  });
  grokApplyFlight = flight;
  return flight.promise;
}

export function runGrokApplyFlightForTests(): Promise<unknown> {
  return runGrokApplyFlight();
}

export function setGrokApplyFlightTestHooks(
  hooks: { now?: () => number; run?: () => Promise<unknown> } | null,
): void {
  grokApplyTestHooks = hooks;
  grokApplyFlight = null;
  grokApplyHighWaterBytes = 0;
}
import { managementInferencePort, type ManagementContext } from "./context";

async function injectionModelOptions(config: OcxConfig, models: readonly CatalogModel[]) {
  const disabled = new Set(config.disabledModels ?? []);
  const { listCatalogNativeSlugs } = await import("../../codex/catalog");
  const nativeModels = listCatalogNativeSlugs()
    .filter(slug => !disabled.has(slug))
    .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
  const routedModels = uniqueCatalogModelsForPublicList([...models])
    .map(m => ({ provider: m.provider, model: m.id, namespaced: catalogModelSlug(m) }))
    .filter(m => ![...disabled].some(stored => (
      stored === m.namespaced || slugEquals(stored, m.provider, m.model)
    )));
  return [...nativeModels, ...routedModels];
}

/**
 * The GET /api/injection-model body. `routed` is the discovered routed catalog, or `null` in a
 * passive read (a Remote Link Child's, #6959). That body lists the native
 * options and the current pick, which is all a read-only Child shows.
 */
export async function injectionModelView(config: OcxConfig, routed: readonly CatalogModel[] | null) {
  const { CODEX_REASONING_LEVELS } = await import("../../reasoning-effort");
  const available = await injectionModelOptions(config, routed ?? []);
  const picked = config.injectionModel;
  if (routed === null && picked && !available.some(option => option.namespaced === picked)) {
    const slash = picked.indexOf("/");
    available.push(slash > 0
      ? { provider: picked.slice(0, slash), model: picked.slice(slash + 1), namespaced: picked }
      : { provider: "openai", model: picked, namespaced: picked });
  }
  return {
    multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
    syncCodexSubagentDefaults: subagentDefaultSyncEffective(config),
    model: config.injectionModel ?? null,
    effort: config.injectionEffort ?? null,
    prompt: config.injectionPrompt ?? null,
    efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
    available,
  };
}

export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
  try { return await handleAgentSettingsRoutesImpl(ctx); }
  catch (error) {
    if (error instanceof CodexCliSelectionMutationBusyError) return jsonResponse({ error: error.message, retryable: true }, 503);
    if (!(error instanceof WindowsSecretAclSettleTimeoutError)) throw error;
    return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
  }
}

async function handleAgentSettingsRoutesImpl(ctx: ManagementContext): Promise<Response | null> {
  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;

  /** Best-effort Desktop 3P config auto-reconcile when providers change. */
  async function autoApplyDesktopBestEffort(): Promise<void> {
    if (siblingOfLivePort() !== null) return;
    try {
      const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
      const admitted = loadConfig();
      if (!claudeDesktopIntegrationEnabled(admitted)) return;
      // A first-party Desktop must never get a gateway profile written and selected behind it.
      const { observeClaudeDesktopMode, resolveClaudeDesktopMode } = await import("../../claude/desktop-first-party");
      if (resolveClaudeDesktopMode(admitted, observeClaudeDesktopMode(admitted)) === "first-party") return;
      if (admitted.claudeCode?.desktopAutoApply === false) return;
      if (!admitted.claudeCode?.desktopProfile) return;
      const { inspectDesktop3pConfigLibrary, writeDesktop3pConfig } = await import("../../claude/desktop-3p");
      const beforeKind = inspectDesktop3pConfigLibrary({
        appliedFingerprint: admitted.claudeCode.desktopProfile.appliedFingerprint ?? null,
      }).kind;
      if (["not_installed", "no_owned_state", "foreign", "unsafe", "broken"].includes(beforeKind)) return;
      const { filterCatalogVisibleModels, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
      const allModels = await (deps.fetchAllModels ?? fetchAllModels)(admitted);
      if (siblingOfLivePort() !== null) return;
      // Serialized with Desktop mode transitions: a first-party switch cannot interleave with this write.
      const { runPickerTransition } = await import("./claude-desktop-picker-routes");
      await runPickerTransition(admitted, () => settleConfigRoot(configRoot(), () => {
        if (siblingOfLivePort() !== null) return undefined;
        const current = readConfigForAdmittedMutation();
        // This is the real guard: the catalog await admits a concurrent explicit OFF.
        if (!claudeDesktopIntegrationEnabled(current)) return undefined;
        // …and a concurrent switch to first-party.
        if (resolveClaudeDesktopMode(current, observeClaudeDesktopMode(current)) === "first-party") return undefined;
        if (current.claudeCode?.desktopAutoApply === false || !current.claudeCode?.desktopProfile) return undefined;
        const afterKind = inspectDesktop3pConfigLibrary({
          appliedFingerprint: current.claudeCode.desktopProfile.appliedFingerprint ?? null,
        }).kind;
        if (["not_installed", "no_owned_state", "foreign", "unsafe", "broken"].includes(afterKind)) return undefined;
        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)(
          // Live bound port, not config: a CLI override or ephemeral bind must not strand Desktop (#6598).
          managementInferencePort({ config: current, deps }) ?? 10100,
          [...desktopVisibleNativeSlugs(current)],
          routed,
          current.apiKeys?.[0]?.key,
          "static",
          writtenProfile,
          nativeContextLimits(current),
        );
        if (result.written && result.fingerprint) {
          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 */ }
  }

  // multi_agent_v2 surface toggle. GET reports the flag + the agents.max_threads
  // boot conflict; PUT flips it via the official `codex features` CLI and RESYNCS
  // the catalog so multi-agent surface metadata stays fresh. The catalog build
  // itself never writes config — this endpoint is the only server-side mutation
  // surface for the flag.
  if (url.pathname === "/api/v2" && req.method === "GET") {
    const {
      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads,
      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
      getMultiAgentModeHintText,
    } = await import("../../codex/features");
    const enabled = isMultiAgentV2Enabled();
    return jsonResponse({
      enabled,
      agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
      maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
      // Resolved, not raw: a hand-edited unsupported value survives config parsing, and the
      // advisory below already reports the resolved surface. Two answers would disagree.
      multiAgentMode: resolveMultiAgentMode(config),
      multiAgentSurfaceAdvisory: multiAgentSurfaceAdvisory(config),
      keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
      plaintextAgentMessagesEnabled: isPlaintextV2AgentMessagesEnabled(config),
      supportsPlaintextV2Mode: true,
      agentsEnabled: getAgentsEnabled(),
      agentsMaxDepth: getAgentsMaxDepth(),
      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
      multiAgentModeHintText: getMultiAgentModeHintText(),
      multiAgentModeHintRecommendation: MULTI_AGENT_MODE_HINT_RECOMMENDATION,
      // max_depth is V1-only upstream; this is the global-flag statement, derived
      // server-side so no client can present it as an effective V2 limit.
      // 'v2-plaintext' keeps the flag off but still runs the V2 surface through
      // catalog pins, so the V1 limit does not apply there either.
      agentsMaxDepthAppliesWhenV2Disabled: !enabled && resolveMultiAgentMode(config) !== "v2-plaintext",
    });
  }
  if (url.pathname === "/api/v2" && req.method === "PUT") {
    let body: {
      enabled?: unknown;
      maxConcurrentThreadsPerSession?: unknown;
      multiAgentMode?: unknown;
      keepNativeChatGptOnV1?: unknown;
      agentsEnabled?: unknown;
      agentsMaxDepth?: unknown;
      subagentDeveloperInstructions?: unknown;
      multiAgentModeHintText?: unknown;
      multiAgentSurfaceAdvisoryAcknowledged?: unknown;
      plaintextAgentMessagesAcknowledged?: unknown;
    };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const wantsFlag = body.enabled !== undefined;
    const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
    const wantsMode = body.multiAgentMode !== undefined;
    const wantsKeepNative = body.keepNativeChatGptOnV1 !== undefined;
    const wantsAgentsEnabled = body.agentsEnabled !== undefined;
    const wantsMaxDepth = body.agentsMaxDepth !== undefined;
    const wantsSubagentInstructions = body.subagentDeveloperInstructions !== undefined;
    const wantsModeHintText = body.multiAgentModeHintText !== undefined;
    const wantsAdvisoryAck = body.multiAgentSurfaceAdvisoryAcknowledged !== undefined;
    const wantsPlaintextAck = body.plaintextAgentMessagesAcknowledged !== undefined;
    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsKeepNative && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions && !wantsModeHintText && !wantsAdvisoryAck) {
      return jsonResponse({ error: "body must set enabled, multiAgentMode, keepNativeChatGptOnV1, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, subagentDeveloperInstructions, multiAgentModeHintText, and/or multiAgentSurfaceAdvisoryAcknowledged" }, 400);
    }
    if (wantsFlag && typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
    if (wantsMode && body.multiAgentMode !== "v1" && body.multiAgentMode !== "default" && body.multiAgentMode !== "v2" && body.multiAgentMode !== "v2-plaintext") {
      return jsonResponse({ error: "body.multiAgentMode must be 'v1', 'default', 'v2', or 'v2-plaintext'" }, 400);
    }
    if (wantsKeepNative && typeof body.keepNativeChatGptOnV1 !== "boolean") {
      return jsonResponse({ error: "body.keepNativeChatGptOnV1 must be a boolean" }, 400);
    }
    if (wantsThreads && (typeof body.maxConcurrentThreadsPerSession !== "number" || !Number.isSafeInteger(body.maxConcurrentThreadsPerSession) || body.maxConcurrentThreadsPerSession < 1)) {
      return jsonResponse({ error: "body.maxConcurrentThreadsPerSession must be a safe integer >= 1" }, 400);
    }
    // Validate every new field BEFORE any write, so each 400 leaves config untouched.
    // null unsets the key; "" is a meaningful value for instructions and must not be
    // collapsed by a falsy check. The i32 preflight mirrors the upstream Option<i32>
    // contract — out-of-range would otherwise surface as a mid-sequence write failure.
    if (wantsAgentsEnabled && body.agentsEnabled !== null && typeof body.agentsEnabled !== "boolean") {
      return jsonResponse({ error: "body.agentsEnabled must be a boolean or null" }, 400);
    }
    if (wantsMaxDepth && body.agentsMaxDepth !== null
        && (typeof body.agentsMaxDepth !== "number" || !Number.isInteger(body.agentsMaxDepth)
            || body.agentsMaxDepth < -2_147_483_648 || body.agentsMaxDepth > 2_147_483_647)) {
      return jsonResponse({ error: "body.agentsMaxDepth must be an integer within signed i32 range, or null" }, 400);
    }
    if (wantsSubagentInstructions && body.subagentDeveloperInstructions !== null && typeof body.subagentDeveloperInstructions !== "string") {
      return jsonResponse({ error: "body.subagentDeveloperInstructions must be a string or null" }, 400);
    }
    // null unsets the upstream key (effort-derived policy resumes); an empty/whitespace
    // string is rejected because codex-rs treats any present hint as an override that
    // suppresses even the Ultra-derived Proactive message (Option<String>, no blank
    // special-case in effective_multi_agent_mode).
    if (wantsModeHintText && body.multiAgentModeHintText !== null
        && (typeof body.multiAgentModeHintText !== "string" || body.multiAgentModeHintText.trim().length === 0)) {
      return jsonResponse({ error: "body.multiAgentModeHintText must be a non-empty string or null" }, 400);
    }
    // A boolean, and only `true` acknowledges. `false` is an explicit no-op so a client
    // that always sends the field cannot un-answer an advisory it already dismissed.
    if (wantsAdvisoryAck && typeof body.multiAgentSurfaceAdvisoryAcknowledged !== "boolean") {
      return jsonResponse({ error: "body.multiAgentSurfaceAdvisoryAcknowledged must be a boolean" }, 400);
    }
    if (wantsPlaintextAck && typeof body.plaintextAgentMessagesAcknowledged !== "boolean") {
      return jsonResponse({ error: "body.plaintextAgentMessagesAcknowledged must be a boolean" }, 400);
    }
    const mode = wantsMode ? body.multiAgentMode as "v1" | "default" | "v2" | "v2-plaintext" : undefined;
    const readModePlan = () => {
      const effectiveMode = mode ?? config.multiAgentMode ?? "default";
      const effectiveKeepNative = wantsKeepNative
        ? body.keepNativeChatGptOnV1 === true
        : config.keepNativeChatGptOnV1 === true;
      const hybridPinActive = effectiveMode === "v2" && effectiveKeepNative;
      const pinDrivenV2 = hybridPinActive || effectiveMode === "v2-plaintext";
      const pinConflict = effectiveMode === "v2-plaintext"
        ? "body.enabled=true conflicts with multiAgentMode 'v2-plaintext': Codex's global multi_agent_v2 override outranks catalog pins"
        : "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins";
      const modeFlag = mode === "v2" ? !hybridPinActive : mode === "v1" || mode === "v2-plaintext" ? false : undefined;
      if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
        return jsonResponse({
          error: pinDrivenV2
            ? pinConflict
            : `body.enabled conflicts with multiAgentMode '${mode}'`,
        }, 400);
      }
      if (wantsFlag && body.enabled === true && pinDrivenV2) {
        return jsonResponse({
          error: pinConflict,
        }, 400);
      }
      // Recheck consent against the admitted state as well as the initial snapshot.
      if (mode === "v2-plaintext" && resolveMultiAgentMode(config) !== "v2-plaintext"
          && body.plaintextAgentMessagesAcknowledged !== true) {
        return jsonResponse({ error: "body.multiAgentMode 'v2-plaintext' requires plaintextAgentMessagesAcknowledged === true: native v2 collaboration messages are delivered as plaintext on the canonical ChatGPT route" }, 400);
      }
      const requestedFlag = wantsFlag
        ? body.enabled as boolean
        : modeFlag ?? (wantsKeepNative && hybridPinActive ? false : undefined);
      return { effectiveMode, requestedFlag };
    };
    const initialPlan = readModePlan();
    if (initialPlan instanceof Response) return initialPlan;
    const {
      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
      getMultiAgentModeHintText, probeCodexSupportsModeHint, setAgentsEnabled, setAgentsMaxDepth,
      setSubagentDeveloperInstructions, setMultiAgentModeHintText, MODE_HINT_UNSUPPORTED_ERROR,
      activeCodexConfigPath,
    } = await import("../../codex/features");
    // Probe the capability before any combined-request mutation. The scalar writer
    // repeats this check, but doing it here prevents an earlier flag/mode/agents
    // write from landing before an unsupported runtime returns 502.
    if (wantsModeHintText && body.multiAgentModeHintText !== null
        && await withCodexCliSelectionParentWriteAsync(probeCodexSupportsModeHint, { signal: req.signal }) === false) {
      return jsonResponse({ error: `writing multiAgentModeHintText failed: ${MODE_HINT_UNSUPPORTED_ERROR}` }, 502);
    }
    const warnings: string[] = [];
    let requestedFlag: boolean | undefined;
    /*
     * One held section for every config.toml write this PUT makes — the
     * feature transition plus each scalar edit. Individually-locked writers
     * would let a foreign write land between them and leave a half-applied
     * combination on disk; the lock is released before the post-write readers
     * and catalog converge below.
     */
    const needsCodexConfigWrites = initialPlan.requestedFlag !== undefined || wantsThreads
      || wantsAgentsEnabled || wantsMaxDepth || wantsSubagentInstructions || wantsModeHintText;
    if (needsCodexConfigWrites && codexHomeIsAbsent(dirname(activeCodexConfigPath()))) {
      return jsonResponse({ error: `config.toml not readable at ${activeCodexConfigPath()}` }, 502);
    }
    const { acquireConfigWriteLock, releaseConfigWriteLock, configWriteLockFailureMessage } = await import("../../codex/config-write-lock");
    const { runCodexFeaturesCommand } = await import("../../cli/v2");
    const configWriteLock = needsCodexConfigWrites ? await acquireConfigWriteLock(activeCodexConfigPath()) : null;
    if (configWriteLock !== null && !configWriteLock.ok) {
      return jsonResponse({ error: configWriteLockFailureMessage(configWriteLock), retryable: configWriteLock.error === "locked" }, 502);
    }
    const heldWriteLock = configWriteLock !== null && configWriteLock.ok ? configWriteLock.handle : undefined;
    let selectionWrite: CodexCliSelectionAsyncParentWrite | undefined;
    try {
      if (wantsFlag || wantsMode || wantsThreads || wantsKeepNative || (wantsModeHintText && body.multiAgentModeHintText !== null)) {
        selectionWrite = await beginCodexCliSelectionParentWriteAsync({ signal: req.signal });
        if (!selectionWrite.entered) return jsonResponse({ error: "codex_cli_selection_busy", retryable: true }, 503);
      }
      const commit = () => {
        const currentPlan = readModePlan();
        if (currentPlan instanceof Response) return currentPlan;
        const { effectiveMode } = currentPlan;
        requestedFlag = currentPlan.requestedFlag;
        if (requestedFlag !== undefined && !heldWriteLock) return jsonResponse({ error: "Multi-agent configuration changed during admission", code: "config_changed" }, 409);
        if (requestedFlag !== undefined || wantsThreads) {
          const targetFlag = requestedFlag ?? isMultiAgentV2Enabled();
          const toggle = deps.toggleCodexMultiAgentV2
            ?? ((enabled, env, validate) => runCodexFeaturesCommand(enabled ? "enable" : "disable", "multi_agent_v2", env, validate));
          const result = transitionMultiAgentV2(targetFlag, toggle, {
            ...(wantsThreads ? { threadLimit: body.maxConcurrentThreadsPerSession as number } : {}),
            heldConfigWriteLock: heldWriteLock,
          });
          if (!result.ok) return jsonResponse({ error: `multi_agent_v2 transition failed: ${result.error}`, ...(result.retryable === false ? { retryable: false } : {}) }, 502);
          if (result.changed && result.threadLimit !== null) warnings.push(`Thread limit ${result.threadLimit} preserved for ${targetFlag ? "v2" : "v1"}.`);
        }
        if (wantsMode) {
          if (mode === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
          else config.multiAgentMode = mode;
          saveConfigPreservingClaudeCode(config);
          warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
          if (mode === "v2-plaintext" && config.keepNativeChatGptOnV1 === true) {
            warnings.push("keepNativeChatGptOnV1 is stored but inactive under 'v2-plaintext': ChatGPT-native rows are pinned on v2.");
          }
        }
        if (wantsKeepNative) {
          if (body.keepNativeChatGptOnV1 === true) config.keepNativeChatGptOnV1 = true;
          else deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
          saveConfigPreservingClaudeCode(config);
          warnings.push(body.keepNativeChatGptOnV1 === true
            ? (effectiveMode === "v2"
              ? "ChatGPT-native models stay on v1 while other models use v2. Applies to new sessions."
              : effectiveMode === "v2-plaintext"
              ? "keepNativeChatGptOnV1 is stored but inactive under 'v2-plaintext': ChatGPT-native rows are pinned on v2. Applies to new sessions."
              : "keepNativeChatGptOnV1 is stored but inactive until multi-agent mode is v2. Applies to new sessions.")
            : "ChatGPT-native models follow the selected v1/v2/base surface. Applies to new sessions.");
        }
        // Written after the mode, so a landed acknowledgement implies the mode write it was
        // sent with already landed. The converse does not hold: this writer throws rather than
        // reporting, exactly as the mode write above it does, so a failure here surfaces the
        // mode change with the advisory still raised. That is the benign direction — the
        // operator is asked again — and it is why this is not claimed as a transaction.
        if (wantsAdvisoryAck && body.multiAgentSurfaceAdvisoryAcknowledged === true) {
          config.multiAgentSurfaceAdvisoryVersion = MULTI_AGENT_SURFACE_ADVISORY_VERSION;
          saveConfigPreservingClaudeCode(config);
        }
        // New-key scalar writes: each writer is individually atomic, so apply them in
        // sequence after the transition. A failure here is a persistence failure (the
        // writers' ok:false result or a throw from the underlying atomic write helper),
        // reported as 502 naming the failed key plus the writes that already landed.
        // NOTE: do not name that helper literally here — tests/providers/xai/grok-writer-boundary.test.ts
        // asserts this route file contains no direct write primitive, and matches on the
        // symbol name even inside a comment.
        const scalarWrites: Array<{ field: string; run: () => { ok: true; changed: boolean } | { ok: false; error: string } }> = [];
        if (wantsAgentsEnabled) scalarWrites.push({ field: "agentsEnabled", run: () => setAgentsEnabled(body.agentsEnabled as boolean | null, undefined, heldWriteLock) });
        if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => setAgentsMaxDepth(body.agentsMaxDepth as number | null, undefined, heldWriteLock) });
        if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => setSubagentDeveloperInstructions(body.subagentDeveloperInstructions as string | null, undefined, heldWriteLock) });
        if (wantsModeHintText) scalarWrites.push({ field: "multiAgentModeHintText", run: () => setMultiAgentModeHintText(body.multiAgentModeHintText as string | null, undefined, heldWriteLock) });
        const landed: string[] = [];
        for (const write of scalarWrites) {
          try {
            const result = write.run();
            if (!result.ok) {
              return jsonResponse({ error: `writing ${write.field} failed: ${result.error}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
            }
            landed.push(write.field);
          } catch (err) {
            const message = err instanceof Error ? err.message : String(err);
            return jsonResponse({ error: `writing ${write.field} failed: ${message}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
          }
        }
        return null;
      };
      const writeRefusal = await settleConfigRoot(configRoot(), () => selectionWrite ? selectionWrite.commit(commit) : commit());
      if (writeRefusal) return writeRefusal;
    } finally {
      selectionWrite?.exit();
      if (heldWriteLock) releaseConfigWriteLock(heldWriteLock);
    }
    // Derived from fresh post-write readers (readConfigText is uncached): upstream
    // lets an enabled multi_agent_v2 feature override [agents].enabled = false, so
    // warn rather than reject — silently accepting would imply multi-agent is off.
    if (getAgentsEnabled() === false && isMultiAgentV2Enabled()) {
      warnings.push("agents.enabled = false has no effect while features.multi_agent_v2 is enabled; upstream keeps V2 active.");
    }
    const catalogRefresh = await convergeCodexCatalog();
    if (requestedFlag !== undefined) warnings.push("Applies to new sessions; restart the Codex app or wait out its picker cache to see the ladder change.");
    const enabled = isMultiAgentV2Enabled();
    return jsonResponse({
      ok: true,
      enabled,
      agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
      maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
      multiAgentMode: resolveMultiAgentMode(config),
      multiAgentSurfaceAdvisory: multiAgentSurfaceAdvisory(config),
      keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
      plaintextAgentMessagesEnabled: isPlaintextV2AgentMessagesEnabled(config),
      supportsPlaintextV2Mode: true,
      agentsEnabled: getAgentsEnabled(),
      agentsMaxDepth: getAgentsMaxDepth(),
      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
      multiAgentModeHintText: getMultiAgentModeHintText(),
      multiAgentModeHintRecommendation: MULTI_AGENT_MODE_HINT_RECOMMENDATION,
      agentsMaxDepthAppliesWhenV2Disabled: !enabled && resolveMultiAgentMode(config) !== "v2-plaintext",
      warnings,
      catalogRefresh,
    });
  }

  // default_mode_request_user_input feature toggle (Codex Auth page). GET reads the
  // flag from $CODEX_HOME/config.toml; PUT flips it via the official `codex features`
  // CLI so the TOML edit stays upstream-owned and format-preserving.
  if (url.pathname === "/api/codex-auth/features/default-mode-request-user-input" && req.method === "GET") {
    const { isDefaultModeRequestUserInputEnabled, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY } = await import("../../codex/features");
    return jsonResponse({
      enabled: isDefaultModeRequestUserInputEnabled(),
      key: DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY,
    });
  }
  if (url.pathname === "/api/codex-auth/features/default-mode-request-user-input" && req.method === "PUT") {
    let parsedBody: unknown;
    try {
      parsedBody = await readManagementJsonBody(req);
    } catch (error) {
      rethrowManagementBodyTooLarge(error);
      return jsonResponse({ error: "invalid JSON body" }, 400);
    }
    if (!parsedBody || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
      return jsonResponse({ error: "body must be a JSON object" }, 400);
    }
    const body = parsedBody as { enabled?: unknown };
    if (typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
    const { isDefaultModeRequestUserInputEnabled, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, activeCodexConfigPath } = await import("../../codex/features");
    const selectionWrite = await beginCodexCliSelectionParentWriteAsync({ signal: req.signal });
    if (!selectionWrite.entered) return jsonResponse({ error: "codex_cli_selection_busy", retryable: true }, 503);
    try {
      const before = isDefaultModeRequestUserInputEnabled();
      let toggle = deps.toggleDefaultModeRequestUserInput;
      if (!toggle) {
        try {
          const { codexFeaturesInvocation, runCodexFeaturesCommand } = await import("../../cli/v2");
          const action = body.enabled ? "enable" : "disable";
          const invocation = selectionWrite.commit(() => codexFeaturesInvocation(action, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, process.platform, { requireAvailable: true }));
          toggle = (_enabled, env, validate) => runCodexFeaturesCommand(action, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, env, validate, invocation);
        } catch (error) {
          if (error instanceof CodexCliSelectionMutationBusyError) throw error;
          return jsonResponse({ error: `default_mode_request_user_input toggle failed: ${error instanceof Error ? error.message : String(error)}` }, 502);
        }
      }
      // Keep selection ownership across the config-lock await and the whole
      // synchronous child execution: an updater must not replace this command.
      const { acquireConfigWriteLock, releaseConfigWriteLock, configWriteLockFailureMessage, runConfigWriteChild, ConfigWriteDestinationChanged } = await import("../../codex/config-write-lock");
      const configPath = activeCodexConfigPath();
      // Preserve native home creation only after executable resolution succeeds.
      selectionWrite.commit(() => prepareCodexHome(dirname(configPath)));
      const configLock = await acquireConfigWriteLock(configPath);
      if (!configLock.ok) {
        return jsonResponse({ error: configWriteLockFailureMessage(configLock), retryable: configLock.error === "locked" }, 502);
      }
      let toggleError: string | null = null;
      let destinationChanged = false;
      try {
        selectionWrite.commit(() => runConfigWriteChild(configPath, configLock.handle, (env, validate) => toggle!(body.enabled as boolean, env, validate)));
      } catch (error) {
        if (error instanceof CodexCliSelectionMutationBusyError) throw error;
        destinationChanged = error instanceof ConfigWriteDestinationChanged;
        const err = error as { stderr?: unknown; message?: string };
        const raw = err.stderr;
        const stderrText = typeof raw === "string"
          ? raw.trim()
          : raw instanceof Uint8Array ? new TextDecoder().decode(raw).trim() : "";
        toggleError = stderrText || (err.message ?? String(error));
      } finally {
        releaseConfigWriteLock(configLock.handle);
      }
      if (destinationChanged) return jsonResponse({ error: toggleError, retryable: false }, 502);
      const enabled = isDefaultModeRequestUserInputEnabled();
      if (toggleError !== null || enabled !== body.enabled) {
        const reason = toggleError
          ?? `postcondition failed - the installed Codex build may not know the ${DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY} flag yet`;
        return jsonResponse({ error: `default_mode_request_user_input toggle failed: ${reason}` }, 502);
      }
      const warnings: string[] = [];
      if (enabled !== before) {
        warnings.push("Applies to new sessions; restart the Codex app or wait out its picker cache to see the change.");
      }
      return jsonResponse({ ok: true, enabled, changed: enabled !== before, warnings });
    } finally { selectionWrite.exit(); }
  }

  // Subagent prompt injection model: single native or routed model whose info is
  // dynamically injected into the v1 proactive prompt, plus an optional reasoning
  // effort the prompt tells the agent to pass to spawn_agent. GET returns the current
  // picks + available models/efforts; PUT sets or clears them.
  if (url.pathname === "/api/injection-model" && req.method === "GET") {
    return jsonResponse(await injectionModelView(config, isPassiveRead() ? null : await fetchAllModels(config)));
  }
  // Read-only: sizes the described delegated work and proposes a model and effort from the
  // same options GET offers. The page applies an accepted proposal through the PUT below.
  if (url.pathname === "/api/injection-model/suggest" && req.method === "POST") {
    let body: unknown;
    try { body = await readManagementJsonBody(req); } catch (error) {
      rethrowManagementBodyTooLarge(error);
      return jsonResponse({ error: "invalid JSON body" }, 400);
    }
    const { work, model } = (body ?? {}) as { work?: unknown; model?: unknown };
    const { ROLE_INSTRUCTIONS_EXCERPT_CHARS } = await import("../../codex/role-sizing");
    if (typeof work !== "string" || work.trim() === "" || work.length > ROLE_INSTRUCTIONS_EXCERPT_CHARS) {
      return jsonResponse({ error: `work must be a nonblank string of at most ${ROLE_INSTRUCTIONS_EXCERPT_CHARS} characters`, code: "invalid_work" }, 400);
    }
    if (model !== undefined && typeof model !== "string") {
      return jsonResponse({ error: "model must be a string", code: "invalid_model" }, 400);
    }
    const { proposeDelegationModel, NoSizingModelError } = await import("./codex-role-auto-assign");
    const models = await (deps.fetchAllModels ?? fetchAllModels)(config);
    try {
      return jsonResponse(await proposeDelegationModel({
        config,
        work: work.trim(),
        offered: (await injectionModelOptions(config, models)).map(option => option.namespaced),
        ...(typeof model === "string" ? { sizingModel: model } : {}),
        models,
        ...(deps.completeCodexRoleSizing ? { completeRoleSizing: deps.completeCodexRoleSizing } : {}),
      }));
    } catch (error) {
      if (error instanceof NoSizingModelError) return jsonResponse({ error: error.message, code: "no_sizing_model" }, 409);
      throw error;
    }
  }
  if (url.pathname === "/api/injection-model" && req.method === "PUT") {
    let parsedBody: unknown;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) {
      rethrowManagementBodyTooLarge(error);
      return jsonResponse({ error: "invalid JSON body" }, 400);
    }
    if (!parsedBody || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
      return jsonResponse({ error: "body must be a JSON object" }, 400);
    }
    const body = parsedBody as {
      multiAgentGuidanceEnabled?: unknown;
      syncCodexSubagentDefaults?: unknown;
      model?: unknown;
      effort?: unknown;
      prompt?: unknown;
    };
    const { isCodexReasoningEffort } = await import("../../reasoning-effort");

    let nextEnabled: OcxConfig["multiAgentGuidanceEnabled"];
    let nextSyncCodexSubagentDefaults: boolean | undefined;
    let nextModel: OcxConfig["injectionModel"];
    let nextEffort: OcxConfig["injectionEffort"];
    let nextPrompt: OcxConfig["injectionPrompt"];

    if ("multiAgentGuidanceEnabled" in body) {
      if (typeof body.multiAgentGuidanceEnabled !== "boolean") {
        return jsonResponse({ error: "multiAgentGuidanceEnabled must be a boolean" }, 400);
      }
      nextEnabled = body.multiAgentGuidanceEnabled;
    }
    if ("syncCodexSubagentDefaults" in body) {
      if (typeof body.syncCodexSubagentDefaults !== "boolean") {
        return jsonResponse({ error: "syncCodexSubagentDefaults must be a boolean" }, 400);
      }
      nextSyncCodexSubagentDefaults = body.syncCodexSubagentDefaults;
    }
    if ("model" in body) {
      if (body.model === null || body.model === "") nextModel = undefined;
      else if (typeof body.model === "string" && body.model.trim().length > 0) nextModel = body.model;
      else return jsonResponse({ error: "model must be a nonblank string or null" }, 400);
    }
    if ("effort" in body) {
      if (body.effort === null || body.effort === "") nextEffort = undefined;
      else if (typeof body.effort === "string" && isCodexReasoningEffort(body.effort)) {
        nextEffort = body.effort;
      } else {
        return jsonResponse({ error: `unknown reasoning effort "${String(body.effort)}"` }, 400);
      }
    }
    if ("prompt" in body) {
      if (typeof body.prompt === "string" && body.prompt.trim().length > 0) nextPrompt = body.prompt;
      else if (body.prompt === null || body.prompt === "") nextPrompt = undefined;
      else return jsonResponse({ error: "prompt must be a string or null" }, 400);
    }
    const refusal = await settleConfigRoot(configRoot(), () => {
      if (!("multiAgentGuidanceEnabled" in body)) nextEnabled = config.multiAgentGuidanceEnabled;
      if (!("syncCodexSubagentDefaults" in body)) nextSyncCodexSubagentDefaults = subagentDefaultSyncEffective(config);
      if (!("model" in body)) nextModel = config.injectionModel;
      if (!("effort" in body)) nextEffort = config.injectionEffort;
      if (!("prompt" in body)) nextPrompt = config.injectionPrompt;
      // Clearing the model always clears model-dependent settings before sync/effort gates.
      if (!nextModel) {
        nextEffort = undefined;
        nextSyncCodexSubagentDefaults = false;
      }
      if (body.syncCodexSubagentDefaults === true && !nextModel?.trim()) {
        return jsonResponse({ error: "syncCodexSubagentDefaults requires an injection model" }, 400);
      }
      if (nextSyncCodexSubagentDefaults && nextEffort !== undefined && !isCodexReasoningEffort(nextEffort)) {
        return jsonResponse({ error: "syncCodexSubagentDefaults requires a supported Codex reasoning effort" }, 400);
      }
      if (nextSyncCodexSubagentDefaults) {
        const issue = agyAcpUnattendedTargetIssues({ ...config, injectionModel: nextModel, syncCodexSubagentDefaults: true })
          .find(({ path }) => path[0] === "injectionModel");
        if (issue) return jsonResponse({ error: `injectionModel: ${issue.message}` }, 400);
      }

      config.multiAgentGuidanceEnabled = nextEnabled;
      if (nextSyncCodexSubagentDefaults) config.syncCodexSubagentDefaults = true;
      else deleteConfigTopLevelKey(config, "syncCodexSubagentDefaults");
      if (nextModel) config.injectionModel = nextModel;
      else deleteConfigTopLevelKey(config, "injectionModel");
      if (nextEffort) config.injectionEffort = nextEffort;
      else deleteConfigTopLevelKey(config, "injectionEffort");
      if (nextPrompt) config.injectionPrompt = nextPrompt;
      else deleteConfigTopLevelKey(config, "injectionPrompt");

      saveConfigPreservingClaudeCode(config);
      return null;
    });
    if (refusal) return refusal;
    return jsonResponse({
      ok: true,
      multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
      syncCodexSubagentDefaults: subagentDefaultSyncEffective(config),
      model: config.injectionModel ?? null,
      effort: config.injectionEffort ?? null,
      prompt: config.injectionPrompt ?? null,
    });
  }

  // Hard reasoning-effort caps (devlog/260710_subagent_effort_intercept): a global ceiling and a
  // sub-agent-only ceiling, enforced per-request in handleResponses (src/server/effort-policy.ts).
  // Key semantics per field: absent -> unchanged; null/"" -> clear; ladder value -> set; else 400.
  if (url.pathname === "/api/effort-caps" && req.method === "GET") {
    const { CODEX_REASONING_LEVELS } = await import("../../reasoning-effort");
    return jsonResponse({
      effortCap: config.effortCap ?? null,
      subagentEffortCap: config.subagentEffortCap ?? null,
      modelPinnedEfforts: config.modelPinnedEfforts ?? {},
      efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
    });
  }
  if (url.pathname === "/api/effort-caps" && req.method === "PUT") {
    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)) {
      return jsonResponse({ error: "effort caps body must be a plain object" }, 400);
    }
    const patch = body as Record<string, unknown>;
    const { isCodexReasoningEffort } = await import("../../reasoning-effort");
    const prepare = () => {
      const draft = { ...projectConfigRebaseProvenance(config) };
      const touched: (keyof OcxConfig)[] = [];
      for (const key of ["effortCap", "subagentEffortCap"] as const) {
        if (!Object.hasOwn(patch, key)) continue;
        const value = patch[key];
        if (value === null || value === "") deleteConfigTopLevelKey(draft, key);
        else if (typeof value === "string" && isCodexReasoningEffort(value)) draft[key] = value;
        else return jsonResponse({ error: "caps must be valid reasoning efforts or null" }, 400);
        touched.push(key);
      }
      if (Object.hasOwn(patch, "modelPinnedEfforts")) {
        const error = modelPinnedEffortsConfigError(patch.modelPinnedEfforts, "modelPinnedEfforts", true);
        if (error) return jsonResponse({ error }, 400);
        const pins = mergeModelPinnedEfforts(config.modelPinnedEfforts, patch.modelPinnedEfforts);
        if (pins) draft.modelPinnedEfforts = pins;
        else deleteConfigTopLevelKey(draft, "modelPinnedEfforts");
        touched.push("modelPinnedEfforts");
      }
      const validation = validateConfigCandidate(draft);
      if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
      if (touched.some(key => !Object.hasOwn(draft, key)) && config.configRebaseProvenance !== undefined
        && parsedConfigRebaseDeletionKeys(config) === null) {
        return jsonResponse({ error: "unsupported config deletion provenance" }, 409);
      }
      const projected = projectConfigRebaseProvenance(draft);
      touched.push("configRebaseProvenance");
      return { touched, projected };
    };
    const checked = prepare();
    if (checked instanceof Response) return checked;
    const refusal = await settleConfigRoot(configRoot(), () => {
      const prepared = prepare();
      if (prepared instanceof Response) return prepared;
      const { touched, projected } = prepared;
      const rollback = captureConfigTopLevelRollback(config, touched);
      try {
        for (const key of touched) {
          if (Object.hasOwn(projected, key)) Object.defineProperty(config, key, {
            value: projected[key], writable: true, enumerable: true, configurable: true,
          });
          else deleteConfigTopLevelKey(config, key);
        }
        (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
      } catch (error) {
        rollback();
        throw error;
      }
      return null;
    });
    if (refusal) return refusal;
    return jsonResponse({
      ok: true,
      effortCap: config.effortCap ?? null,
      subagentEffortCap: config.subagentEffortCap ?? null,
      ...(config.modelPinnedEfforts ? { modelPinnedEfforts: config.modelPinnedEfforts } : {}),
    });
  }

  if (url.pathname === "/api/subagent-models") {
    const { handleSubagentModelRoutes } = await import("./subagent-model-routes");
    return handleSubagentModelRoutes(ctx, autoApplyDesktopBestEffort);
  }

  // Priority-ordered subagent model fallback chain for quota-aware spawn routing.
  if (url.pathname === "/api/subagent-model-fallback" && req.method === "GET") {
    const models = await fetchAllModels(config);
    const disabled = new Set(config.disabledModels ?? []);
    const { listCatalogNativeSlugs } = await import("../../codex/catalog");
    const visibleRouted = [...new Set(models
      .filter(m => ![...disabled].some(stored =>
        stored === catalogModelSlug(m) || slugEquals(stored, m.provider, m.id)
      ))
      .map(catalogModelSlug))];
    const available = [
      ...listCatalogNativeSlugs().filter(ns => !disabled.has(ns)),
      ...visibleRouted,
    ];
    return jsonResponse({
      models: config.subagentModelFallback ?? [],
      pollMs: config.subagentModelFallbackPollMs ?? 60_000,
      available,
    });
  }
  if (url.pathname === "/api/subagent-model-fallback" && req.method === "PUT") {
    let body: { models?: unknown; pollMs?: 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)) {
      return jsonResponse({ error: "invalid JSON body" }, 400);
    }
    let nextModels: OcxConfig["subagentModelFallback"];
    let nextPollMs: OcxConfig["subagentModelFallbackPollMs"];
    if ("models" in body) {
      if (!Array.isArray(body.models)) return jsonResponse({ error: "models must be an array" }, 400);
      const models: string[] = [];
      for (let i = 0; i < body.models.length; i++) {
        const entry = body.models[i];
        if (typeof entry !== "string" || entry.trim().length === 0) {
          return jsonResponse({
            error: `models[${i}] must be a non-empty string`,
            index: i,
            value: entry,
          }, 400);
        }
        models.push(entry.trim());
      }
      nextModels = models.length > 0 ? models : undefined;
    }
    if ("pollMs" in body) {
      const pollMs = body.pollMs;
      if (pollMs === null || pollMs === "") nextPollMs = undefined;
      else if (typeof pollMs === "number" && Number.isInteger(pollMs) && pollMs >= 5_000 && pollMs <= 600_000) {
        nextPollMs = pollMs;
      } else {
        return jsonResponse({ error: "pollMs must be an integer between 5000 and 600000" }, 400);
      }
    }
    await settleConfigRoot(configRoot(), () => {
      if (!("models" in body)) nextModels = config.subagentModelFallback;
      if (!("pollMs" in body)) nextPollMs = config.subagentModelFallbackPollMs;
      if (nextModels !== undefined) config.subagentModelFallback = nextModels;
      else deleteConfigTopLevelKey(config, "subagentModelFallback");
      if (nextPollMs !== undefined) config.subagentModelFallbackPollMs = nextPollMs;
      else deleteConfigTopLevelKey(config, "subagentModelFallbackPollMs");
      saveConfigPreservingClaudeCode(config);
    });
    return jsonResponse({
      ok: true,
      models: config.subagentModelFallback ?? [],
      pollMs: config.subagentModelFallbackPollMs ?? 60_000,
    });
  }

  // Grok Build: view of the managed fence in ~/.grok/config.toml plus the candidate
  // catalog and the user's selection. The fence itself is still written ONLY by
  // injectGrokConfig — the write routes below carry no path/host/port/body input.
  if (url.pathname === "/api/grok" && req.method === "GET") {
    try {
      const { readGrokStatus } = await import("../../grok/status");
      // `candidates` is the full visible catalog the fence WOULD carry, so the page can
      // show a switch for a model the user has already excluded. Aliases come from
      // `status.models` — the writer's output — never computed client-side.
      return jsonResponse({
        ...readGrokStatus(),
        candidates: await fetchGrokCandidateModels(config),
        excluded: config.grokExcludedModels ?? [],
      });
    } catch (error) {
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }

  // Writes CONFIG only. ~/.grok/config.toml is still written exclusively by
  // injectGrokConfig, through the apply route below — this route cannot touch that file.
  if (url.pathname === "/api/grok/selection" && req.method === "PUT") {
    let body: { excluded?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const raw = body.excluded;
    if (!Array.isArray(raw) || raw.some(entry => typeof entry !== "string" || entry.length === 0)) {
      return jsonResponse({ error: "excluded must be an array of model ids" }, 400);
    }
    // Dedupe + sort so the stored list is stable, and cap it so a hostile client
    // cannot grow config.json without bound.
    const excluded = [...new Set(raw as string[])].sort();
    if (excluded.length > 2000) return jsonResponse({ error: "excluded list is too large" }, 400);
    await settleConfigRoot(configRoot(), () => {
      if (excluded.length === 0) deleteConfigTopLevelKey(config, "grokExcludedModels");
      else config.grokExcludedModels = excluded;
      saveConfigPreservingClaudeCode(config);
    });
    return jsonResponse({ ok: true, excluded });
  }

  // Re-runs the SAME sync the CLI runs. All guards (no-grok-home, non-loopback refusal,
  // orphaned marker, backup, alias reservation) live in injectGrokConfig and are not
  // duplicated here. Accepts no body: every input comes from persisted state.
  if (url.pathname === "/api/grok/apply" && req.method === "POST") {
    try {
      const result = await runGrokApplyFlight() as Awaited<ReturnType<typeof import("../../grok/sync")["syncGrokConfig"]>>;
      // A policy skip (non-loopback, no ~/.grok) is not a server error: report it as a
      // result the page can explain rather than a 500 the user cannot act on.
      return jsonResponse({
        ok: result.ok,
        changed: result.changed,
        message: result.message,
        ...(result.skippedReason ? { skippedReason: result.skippedReason } : {}),
      }, result.ok ? 200 : 500);
    } catch (error) {
      if (error instanceof GrokApplyBusyError) return jsonResponse({ error: "grok_apply_busy" }, 409);
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }

  // Claude Desktop profile: routed/native model assignments for the Desktop 3P config.
  if (url.pathname === "/api/claude-desktop" && req.method === "GET") {
    try {
      const state = await buildClaudeDesktopState(config);
      const runtimePort = managementInferencePort(ctx);
      return jsonResponse({ ...state, port: runtimePort });
    } catch (error) {
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }
  if (url.pathname === "/api/claude-desktop" && req.method === "PUT") {
    let body: { profile?: unknown; visibility?: unknown };
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    try {
      const { parseDesktopProfile, preserveDesktopAppliedState, reconcileDesktopProfile, sameProfileContent } = await import("../../claude/desktop-profile");
      const parsed = parseDesktopProfile(body.profile);
      const initial = loadConfig();
      const current = await buildClaudeDesktopState(initial);
      // #7702: absent keeps the stored selection, null clears it (list every model).
      const { parseDesktopModelVisibility, desktopRouteVisible, readDesktopModelVisibility, sameDesktopModelVisibility } = await import("../../claude/desktop-model-visibility");
      const visibility = body.visibility === undefined || body.visibility === null ? body.visibility : parseDesktopModelVisibility(body.visibility);
      if (visibility && !current.models.some(model => model.available && desktopRouteVisible(visibility, model.route))) {
        throw new Error("Claude Desktop needs at least one visible available model");
      }
      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)) {
          throw new Error(`현재 사용할 수 없는 모델은 추가할 수 없습니다: ${route}`);
        }
      }
      for (const model of current.models.filter(item => !item.available)) {
        const before = current.profile.assignments[model.route];
        const after = parsed.assignments[model.route];
        if (after !== undefined && JSON.stringify(before) !== JSON.stringify(after)) {
          throw new Error(`현재 사용할 수 없는 모델은 옮길 수 없습니다: ${model.route}`);
        }
      }
      for (const family of ["opus", "fable", "sonnet", "haiku"] as const) {
        const nextDefault = parsed.defaults[family];
        const target = nextDefault ? current.models.find(model => model.route === nextDefault) : undefined;
        if (target && !target.available && current.profile.defaults[family] !== nextDefault) {
          throw new Error(`현재 사용할 수 없는 모델은 기본값으로 지정할 수 없습니다: ${nextDefault}`);
        }
      }
      // 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 = await settleConfigRoot(configRoot(), () => {
        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 };
          }
          if (visibility !== undefined && !sameDesktopModelVisibility(
            readDesktopModelVisibility(persisted.claudeCode), readDesktopModelVisibility(initial.claudeCode),
          )) return { changed: false, value: null };
          persisted.claudeCode = {
            ...(persisted.claudeCode ?? {}),
            desktopProfile: preserveDesktopAppliedState(latest ?? current.profile, rebuilt),
          };
          if (visibility) persisted.claudeCode.desktopModelVisibility = visibility;
          else if (visibility === null) delete persisted.claudeCode.desktopModelVisibility;
          return { changed: true, value: structuredClone(persisted.claudeCode) };
        });
        if (outcome.status !== "unavailable" && outcome.value !== null) {
          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),
            };
          }
          if (visibility !== undefined && config.claudeCode) {
            if (outcome.value?.desktopModelVisibility) config.claudeCode.desktopModelVisibility = structuredClone(outcome.value.desktopModelVisibility);
            else delete config.claudeCode.desktopModelVisibility;
          }
        }
        return outcome;
      });
      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);
      }
      const saved = await buildClaudeDesktopState(config);
      const runtimePort = managementInferencePort(ctx);
      return jsonResponse({ ok: true, ...saved, port: runtimePort });
    } catch (error) {
      if (error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }
  if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
    let committedIntent = false, savedProfile = false, pickerDisabled = false;
    let appliedMode: "first-party" | "gateway" | undefined, appliedPath = "", modeCommitted = false;
    try {
      // #859: the CLI delegates here so the registry is built in the serving
      // process. `mode` selects the Desktop mode: `first-party` (default when the
      // install has no gateway profile) or `gateway`; the legacy gateway shapes
      // (static/hybrid/discovery) still select gateway with that library layout.
      let mode: "static" | "hybrid" | "discovery" = "static";
      let parsed: unknown;
      try {
        parsed = await readOptionalManagementJsonBody(req);
      } catch (error) {
        rethrowManagementBodyTooLarge(error);
        return jsonResponse({ error: "invalid JSON body" }, 400);
      }
      const { resolveClaudeDesktopApplyMode, observeClaudeDesktopMode, applyDesktopFirstParty, withFirstPartySecretsSettled, captureDesktopFirstPartyRollback, rollbackDesktopFirstPartySettled, removeDesktopFirstPartySettled } = await import("../../claude/desktop-first-party");
      const requested = (parsed as { mode?: unknown } | null)?.mode;
      let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config, observeClaudeDesktopMode(config));
      if (requested !== undefined) {
        if (requested === "static" || requested === "hybrid" || requested === "discovery") {
          mode = requested;
          desktopMode = "gateway";
        } else if (requested === "gateway" || requested === "first-party") {
          desktopMode = requested;
        } else {
          return jsonResponse({ error: "mode must be first-party, gateway, static, hybrid, or discovery" }, 400);
        }
      }
      // #859: a delegated CLI apply carries the profile it just saved — the
      // daemon's own config can be older, and building state from it would
      // apply (and persist) the stale profile over the newer one.
      const bodyProfile = (parsed as { profile?: unknown } | null)?.profile;
      let profileOverride: Parameters<typeof buildClaudeDesktopState>[1];
      if (bodyProfile !== undefined) {
        const { parseDesktopProfile } = await import("../../claude/desktop-profile");
        try {
          profileOverride = parseDesktopProfile(bodyProfile);
        } catch (error) {
          return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
        }
      }
      if (desktopMode === "first-party") {
        const refusal = interceptStartRefusal(ctx);
        if (refusal) return refusal;
        const started = await ensureManagementClaudeIntercept(ctx);
        if (!started.ok) return jsonResponse({ ...started, code: started.reason }, 409);
        const { claudeInterceptProxyPort } = await import("../../claude/intercept/runtime");
        const configured = claudeInterceptProxyPort(config, config.port ?? 10100);
        if (started.state.proxyPort !== configured) return jsonResponse({ ok: false, code: "port_mismatch", bound: started.state.proxyPort, configured }, 409);
        const { setHomeIntegrationEnabled } = await import("../../routing/home-route-capture");
        const desired = await withFirstPartySecretsSettled(configRoot(), () => {
          const result = setHomeIntegrationEnabled("claude-desktop", true);
          if (result.ok) mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
          return result;
        });
        if (!desired.ok) return "path" in desired ? jsonResponse({ ...desired, code: desired.reason }, 500)
          : jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
        committedIntent = true;
        const { pickerPreferenceOn, pickerStatusFor, runPickerTransition } = await import("./claude-desktop-picker-routes");
        // The whole switch runs under the picker lock, in today's order: env first, then gateway cleanup.
        return await runPickerTransition(config, async ops => {
          const { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } = await import("../../claude/desktop-3p");
          let rollback!: ReturnType<typeof captureDesktopFirstPartyRollback>;
          const { getConfigDir } = await import("../../config/paths");
          const applied = await withFirstPartySecretsSettled(getConfigDir(), () => { rollback = captureDesktopFirstPartyRollback(config); return applyDesktopFirstParty(config); });
          if (!applied.ok) {
            const { firstPartyRefusalMessage } = await import("./native-integration-routes");
            return jsonResponse({
              error: firstPartyRefusalMessage(applied.reason, applied.path),
              code: "claude_desktop_first_party_refused",
              reason: applied.reason,
              path: applied.path,
              ...(applied.diagnostic ? { diagnostic: applied.diagnostic } : {}),
            }, applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? 409 : 500);
          }
          appliedMode = "first-party"; appliedPath = applied.path;
          let gatewayRemoved = false;
          try {
          // Remove the gateway only after the replacement env was written.
          const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
          const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
          if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
            let removed: ReturnType<typeof removeDesktop3pStandardPivot>;
            try { removed = await settleConfigRoot(configRoot(), () => (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: readConfigForAdmittedMutation().claudeCode?.desktopProfile?.appliedFingerprint ?? null, replaceWhileEnabled: true })); }
            catch (error) {
              removed = { ok: false, changed: false, kind: "write_failed", libraryPath: library.libraryPath,
                reason: error instanceof WindowsSecretAclSettleTimeoutError ? "acl_settlement_timeout" : "desktop_mutation_failed" };
            }
            if (!removed.ok) {
              const restored = removed.changed || !applied.changed || await rollbackDesktopFirstPartySettled(getConfigDir(), rollback).catch(() => false);
              if (!removed.changed && restored && applied.changed) appliedMode = undefined;
              const modeSaved = !removed.changed || (await persistDesktopModeField(config, "first-party")).ok;
              const warning = [restored ? "" : "first-party settings rollback did not complete",
                modeSaved ? "" : "first-party is active but its mode marker was not saved"].filter(Boolean).join("; ");
              return jsonResponse({
                error: removed.kind === "cleanup_incomplete"
                  ? "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; the first-party connection remains active."
                  : !restored ? "The gateway profile could not be removed and first-party settings rollback did not complete; the mode switch is incomplete."
                  : "The gateway profile could not be removed safely, so first-party mode was not applied.",
                code: "claude_desktop_gateway_removal_failed",
                desiredEnabled: true, saved: removed.changed && modeSaved, applied: removed.changed || !restored || !applied.changed,
                ...(warning ? { warning } : {}),
                reason: removed.reason ?? removed.kind,
                ...(removed.residualPaths ? { residualPaths: removed.residualPaths } : {}),
              }, removed.kind === "cleanup_incomplete" ? 500 : 409);
            }
            gatewayRemoved = removed.changed;
          }
          const modeSaved = await persistDesktopModeField(config, "first-party");
          modeCommitted = modeSaved.ok;
          const { firstPartyAccountRisk } = await import("../../claude/desktop-risk");
          // Picker mode is on by default in first-party; only a committed mode turns it on.
          const picker = modeSaved.ok && pickerPreferenceOn(loadConfig())
            ? await ops.enableLocked({ persist: false, context: "server" })
            : await pickerStatusFor(loadConfig());
          if (modeSaved.ok) await syncClaudeAgentDefsBestEffort();
          return jsonResponse({
            ok: true,
            mode: "first-party",
            saved: modeSaved.ok,
            applied: true,
            changed: applied.changed || gatewayRemoved,
            gatewayRemoved,
            path: applied.path,
            proxyPort: applied.proxyPort,
            caCertPath: applied.env.NODE_EXTRA_CA_CERTS,
            riskWarning: firstPartyAccountRisk(),
            picker,
            ...(modeSaved.ok ? {} : { warning: `First-party env was applied, but the mode marker was not saved (${modeSaved.reason}).` }),
          });
          } catch {
            const retained = gatewayRemoved || modeCommitted;
            const restored = retained || !applied.changed || await rollbackDesktopFirstPartySettled(getConfigDir(), rollback).catch(() => false);
            return jsonResponse({ error: "First-party mode follow-up did not complete", code: "claude_desktop_gateway_removal_failed",
              desiredEnabled: true, saved: modeCommitted, applied: retained || !restored || !applied.changed,
              warning: retained ? "First-party settings remain applied."
                : restored ? "First-party settings were rolled back; Desktop enable intent remains saved." : "first-party settings rollback did not complete" }, 500);
          }
        });
      }
      const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
      const { setHomeIntegrationEnabled } = await import("../../routing/home-route-capture");
      const desired = await settleConfigRoot(configRoot(), () => {
          const result = setHomeIntegrationEnabled("claude-desktop", true);
          if (result.ok) mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
          return result;
        });
      if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
      committedIntent = true;
      // Disk now says ON; the reused server snapshot must agree, or the native
      // GET reports OFF and a later whole-snapshot save undoes this transition.
      const expectedProfile = structuredClone(loadConfig().claudeCode?.desktopProfile);
      const state = await buildClaudeDesktopState(config, profileOverride);
      // `setIntegrationEnabled` above wrote desired ON to DISK; it does not touch
      // this long-lived server snapshot. Saving the snapshot wholesale would carry
      // its stale `clientIntegrations` back over that write and turn the enable
      // action into an immediate self-cancelling OFF — the guard below would then
      // refuse the apply it was asked to perform. Persist ONLY the profile field.
      const profileSaved = await persistDesktopProfileField(config, state.profile, expectedProfile);
      if (!profileSaved.ok) {
        return jsonResponse({
          error: `Claude Desktop profile could not be saved (${profileSaved.reason}); nothing was applied.`,
          saved: false,
          applied: false,
          desiredEnabled: true,
        }, profileSaved.reason === "conflict" ? 409 : 500);
      }
      savedProfile = true;
      const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
      const { desktopVisibleNativeSlugs } = await import("../../codex/catalog");
      const routed = state.models
        .filter(model => model.available && !model.route.startsWith("native/"))
        .map(model => {
          const slash = model.route.indexOf("/");
          return { provider: model.route.slice(0, slash), id: model.route.slice(slash + 1), contextWindow: model.contextWindow };
        });
      const { runPickerTransition } = await import("./claude-desktop-picker-routes");
      const outcome = await runPickerTransition(config, async ops => {
        // State construction can await catalog work; never write from the stale
        // config captured before that await if another request turned Desktop off.
        let latest = loadConfig();
        if (!claudeDesktopIntegrationEnabled(latest)) {
          return { response: jsonResponse({
            error: "Claude Desktop apply was cancelled because the desired state changed to off.",
            code: "claude_desktop_apply_skipped",
            reason: "desired_state_changed",
            desiredEnabled: false,
            saved: true,
            applied: false,
          }, 409) };
        }
        // Picker mode belongs to first-party: stop terminating claude.ai before the gateway lands.
        const pickerOff = await ops.disableLocked({ persist: false });
        pickerDisabled = true;
        const result = await settleConfigRoot(configRoot(), () => {
          latest = readConfigForAdmittedMutation();
          if (!claudeDesktopIntegrationEnabled(latest) || JSON.stringify(latest.claudeCode?.desktopProfile) !== JSON.stringify(state.profile)) return null;
          return (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
          managementInferencePort({ config: latest, deps }),
          [...desktopVisibleNativeSlugs(latest)],
          routed,
          latest.apiKeys?.[0]?.key,
          mode,
          state.profile,
          nativeContextLimits(latest),
        ); });
        if (result === null) return { response: jsonResponse({ error: "Desktop configuration changed during apply", code: "config_changed", saved: true, applied: false }, 409) };
        if (!result.written) return { response: jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500) };
        appliedMode = "gateway"; appliedPath = result.path;
        const committed = await settleConfigRoot(configRoot(), () => persistCommittedDesktopGateway(config, state.profile, result.fingerprint)).catch(() => {
          return { ok: false, reason: "unavailable" } as const;
        });
        modeCommitted = committed.ok;
        const modeWarning = committed.ok ? undefined : `Gateway applied, but its mode/profile state was not saved (${committed.reason}).`;
        // The durable marker describes the committed gateway even if old-mode cleanup fails.
        const firstPartyRemoved = await removeDesktopFirstPartySettled(loadConfig);
        if (!firstPartyRemoved.ok) {
          return { response: jsonResponse({
            error: `Claude Code first-party settings cleanup did not complete (${firstPartyRemoved.path}); the gateway was applied.`,
            code: "claude_desktop_first_party_refused", reason: firstPartyRemoved.reason,
            applied: true, saved: committed.ok, mode: "gateway", path: result.path,
            ...(modeWarning ? { warning: modeWarning } : {}),
          }, 500) };
        }
        return { result, committed, modeWarning, pickerOff, firstPartyRemoved };
      });
      if (outcome.response) return outcome.response;
      const { result, committed, modeWarning, pickerOff, firstPartyRemoved } = outcome as Exclude<typeof outcome, { response: Response }>;
      const { claudeDesktopPolicyWarning, getCachedClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
      const policyState = deps.probeClaudeDesktopPolicy
        ? await deps.probeClaudeDesktopPolicy({ platform: deps.platform ?? process.platform })
        : await getCachedClaudeDesktopPolicy({ platform: deps.platform ?? process.platform });
      const policyWarning = claudeDesktopPolicyWarning(policyState);
      const pickerWarning = pickerOff.residual?.length
        ? `Picker mode cleanup is incomplete (${pickerOff.residual.join(", ")}); run ocx claude desktop picker off.`
        : undefined;
      const warning = [modeWarning, policyWarning, pickerWarning,
        firstPartyRemoved.retainedFor === "cli"
          ? "Shared first-party settings remain for Claude Code CLI." : undefined].filter(Boolean).join(" ");
      return jsonResponse({
        ok: true,
        mode: "gateway",
        saved: committed.ok,
        applied: true,
        path: result.path,
        fingerprint: result.fingerprint,
        policyState,
        ...(warning ? { warning } : {}),
      });
    } catch (error) {
      rethrowManagementBodyTooLarge(error);
      if (committedIntent || error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({
        error: error instanceof WindowsSecretAclSettleTimeoutError ? "Config-directory ACL settlement timed out" : "Desktop apply did not complete", code: "write_failed",
        ...(error instanceof WindowsSecretAclSettleTimeoutError ? { diagnostic: { stage: "ca", cause: "ETIMEDOUT" } } : {}),
        ...(committedIntent ? { desiredEnabled: true, saved: appliedMode ? modeCommitted : savedProfile, applied: appliedMode !== undefined,
          ...(appliedMode ? { mode: appliedMode, path: appliedPath } : {}),
          warning: `Desktop enable intent${savedProfile ? " and profile were" : " was"} saved; Desktop ${appliedMode ? "was applied but follow-up did not complete" : "was not applied"}.${pickerDisabled ? " Picker disable was already attempted." : ""}` } : {}),
      }, 500);
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }

  // Desktop applied-state + health status.
  if (url.pathname === "/api/claude-desktop/status" && req.method === "GET") {
    try {
      const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
      const { inspectDesktop3pConfigLibrary } = await import("../../claude/desktop-3p");
      const { resolveClaudeDesktopApplyMode, inspectDesktopFirstParty, observeClaudeDesktopMode } = await import("../../claude/desktop-first-party");
      const { getClaudeInterceptState } = await import("../../claude/intercept/runtime");
      const { DESKTOP_PICKER_ID_SUGGESTIONS, readInterceptBindings } = await import("../../claude/intercept/model-bindings");
      const persisted = loadConfig();
      const savedFingerprint = persisted.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
      const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
      const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
      const gatewayApplied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
      // A gateway profile on disk is what Desktop actually runs, whatever the saved mode says.
      const mode = gatewayApplied ? "gateway" : resolveClaudeDesktopApplyMode(persisted, observeClaudeDesktopMode(persisted));
      const firstPartySeen = inspectDesktopFirstParty(persisted);
      const intercept = getClaudeInterceptState();
      const firstParty = {
        settingsState: firstPartySeen.settings.kind,
        applied: firstPartySeen.applied,
        stale: firstPartySeen.stale,
        interceptEnabled: firstPartySeen.interceptEnabled,
        interceptRunning: intercept !== null,
        ...interceptStatus(ctx),
        proxyPort: intercept?.proxyPort ?? firstPartySeen.proxyPort,
        caCertPath: firstPartySeen.caCertPath,
        // What the running proxy routes with right now (live config), not the file on disk.
        modelBindings: readInterceptBindings(config.claudeCode),
        pickerSuggestions: [...DESKTOP_PICKER_ID_SUGGESTIONS],
        // Picker mode: the controller's view while it runs, else the static offline status.
        picker: await (await import("./claude-desktop-picker-routes")).pickerStatusFor(persisted),
      };
      const applied = mode === "first-party" ? firstPartySeen.applied : gatewayApplied;
      // "Needs update" is only meaningful while the integration is wanted. When the
      // durable switch is OFF, a leftover drifted profile is residue to clear — not
      // a stale apply the operator should refresh.
      const stale = desiredEnabled && (mode === "first-party" ? firstPartySeen.stale : observed.kind === "gateway_drifted");
      const { getDesktopHealth } = await import("../../claude/desktop-health");
      const { claudeDesktopPolicyHealth, getCachedClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
      const policyState = deps.probeClaudeDesktopPolicy
        ? await deps.probeClaudeDesktopPolicy({ platform: deps.platform ?? process.platform })
        : await getCachedClaudeDesktopPolicy({ platform: deps.platform ?? process.platform });
      // Managed-policy conflicts only matter for the gateway profile; first-party mode never
      // touches Desktop's own configuration.
      const policy = claudeDesktopPolicyHealth(mode === "first-party" ? "absent" : policyState);
      const health = {
        ...getDesktopHealth(),
        ok: policy.ok,
        status: policy.status,
        policy,
      };
      const policyConflict = desiredEnabled && !policy.ok;
      const firstPartyResidue = mode === "gateway" && (firstPartySeen.applied || firstPartySeen.stale);
      const baseDrift = desiredEnabled
        ? !applied || stale || firstPartyResidue
        : applied || gatewayApplied || firstPartySeen.applied || firstPartySeen.stale || observed.kind === "unsafe";
      const driftReason = policyConflict
        ? policy.state === "present" ? "managed_policy_present" : "managed_policy_unknown"
        : desiredEnabled
          ? !applied ? "desired_on_not_current" : stale ? "profile_drift" : firstPartyResidue ? "first_party_residue" : null
          : gatewayApplied ? "desired_off_gateway_selected" : firstPartySeen.applied || firstPartySeen.stale ? "desired_off_first_party_env" : null;
      return jsonResponse({
        desiredEnabled,
        mode,
        // Shown wherever first-party is selected or its env is still applied (account-risk notice).
        riskWarning: mode === "first-party" || firstPartySeen.applied || firstPartySeen.stale
          ? (await import("../../claude/desktop-risk")).firstPartyAccountRisk()
          : null,
        firstParty,
        installed: observed.kind !== "not_installed",
        observedKind: observed.kind,
        applied,
        appliedAt: persisted.claudeCode?.desktopProfile?.appliedAt ?? null,
        savedFingerprint,
        onDiskFingerprint: observed.fingerprint ?? null,
        configPath: observed.selectedProfilePath,
        // The list Desktop runs now (#7702), so the dashboard can count and diff against it.
        appliedModels: gatewayApplied ? (await import("../../claude/desktop-model-visibility")).readAppliedDesktopModels(observed.selectedProfilePath) : null,
        stale,
        // Tri-state by ID match, independent of profile health: null =
        // undeterminable (no/unreadable metadata or no appliedId); a readable
        // appliedId with no owned entry is a KNOWN false. Predates the inspector.
        activeProfile: observed.ownedProfileActive,
        drift: baseDrift || policyConflict,
        driftReason,
        health,
      });
    } catch (error) {
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }

  // First-party model bindings: Claude Desktop Code tab picker id -> opencodex route, honoured
  // only on the claude-intercept ingress (src/claude/intercept/model-bindings.ts).
  if (url.pathname === "/api/claude-desktop/first-party-bindings" && req.method === "PUT") {
    let body: unknown;
    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    try {
      const { applyInterceptBindingPatch, parseInterceptBindingPatch, readInterceptBindings } = await import("../../claude/intercept/model-bindings");
      const patch = parseInterceptBindingPatch(body);
      if ("error" in patch) return jsonResponse({ error: patch.error }, 400);
      // Same route vocabulary the Desktop profile and the dashboard use, native routes included.
      const state = await buildClaudeDesktopState(config);
      const availableRoutes = new Set(state.models.filter(model => model.available).map(model => model.route));
      let rejection: string | null = null;
      const outcome = await settleConfigRoot(configRoot(), () => {
        const outcome = mutatePersistedConfig<OcxConfig["claudeCode"]>(persisted => {
        const current = readInterceptBindings(persisted.claudeCode);
        const next = applyInterceptBindingPatch(current, patch, availableRoutes);
        if (!next.ok) {
          rejection = next.error;
          return { changed: false, value: persisted.claudeCode };
        }
        if (!next.changed) return { changed: false, value: structuredClone(persisted.claudeCode) };
        const claudeCode = { ...(persisted.claudeCode ?? {}) };
        const intercept = { ...(claudeCode.intercept ?? {}) };
        if (Object.keys(next.bindings).length > 0) intercept.modelMap = next.bindings;
        else delete intercept.modelMap;
        if (Object.keys(intercept).length > 0) claudeCode.intercept = intercept;
        else delete claudeCode.intercept;
        persisted.claudeCode = claudeCode;
        return { changed: true, value: structuredClone(persisted.claudeCode) };
      });
        if (!rejection && outcome.status !== "unavailable") {
      adoptPersistedClaudeCode(config, outcome.value);
      // Pin the committed leaf: an unarmed live snapshot may otherwise keep its old intercept block.
      const committedIntercept = outcome.value?.intercept;
      const liveClaudeCode = { ...(config.claudeCode ?? {}) };
      if (committedIntercept) liveClaudeCode.intercept = structuredClone(committedIntercept);
      else delete liveClaudeCode.intercept;
      config.claudeCode = liveClaudeCode;
        }
        return outcome;
      });
      if (rejection) return jsonResponse({ error: rejection }, 400);
      if (outcome.status === "unavailable") {
        return jsonResponse({ error: `First-party bindings could not be saved (config ${outcome.reason})` }, outcome.reason === "conflict" ? 409 : 500);
      }
      return jsonResponse({ ok: true, modelBindings: readInterceptBindings(config.claudeCode) });
    } catch (error) {
      if (error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
      return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
    }
  }

  // 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);
      }
      // Fresh admission after the body await: a nested Claude home shares the config-root ACL flight.
      const fingerprint = body.fingerprint;
      const { withConfigDirHardeningSettled } = await import("../../config/paths"), { claudeConfigDir } = await import("../../claude/auth-detect");
      return jsonResponse(await withConfigDirHardeningSettled(claudeConfigDir(), () => applyClaudeModelDefaults(config.claudeCode?.tierModels, 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 { buildClaudeContextWindows, effectiveModelEnv, nativeClaudePassthroughFor, probeClaudeCodeVersionForTierFill } = await import("../../claude/context-windows");
    const { visibleNativeSlugs } = await import("../../codex/catalog");
    // Auto is a RESOLUTION, recomputed per request — never stored state. Detection is
    // daemon-side, so it cannot see a key exported only in the user's terminal; the
    // GUI labels the badge with detectionScope for exactly that reason.
    const { defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens, resolveClaudeKeychainPresence } = await import("../../claude/auth-detect");
    const { authModeIntent, resolveClaudeAuthMode } = await import("../../claude/auth-mode");
    // Awaited, never spawned synchronously: a blocked Keychain lookup must not stall /healthz (#8161).
    const keychainPresence = await resolveClaudeKeychainPresence(config.claudeCode?.authMode);
    const authDetection = detectClaudeAuth(defaultAuthDetectDeps(process.env, ownAdmissionTokens(config), keychainPresence));
    const resolvedAuthMode = resolveClaudeAuthMode(config, authDetection);
    const contextWindows = buildClaudeContextWindows(
      [...visibleNativeSlugs(config)],
      models,
      nativeContextLimits(config),
      nativeClaudePassthroughFor(config.claudeCode, resolvedAuthMode.markerMode),
    );
    const launchState = {
      enabled: config.claudeCode?.enabled !== false,
      forceAvailable: [...visibleNativeSlugs(config), ...filterCatalogVisibleModels(models, config).map(catalogModelSlug)],
      contextWindows,
    };
    // The launcher probes its own CLI. Only the dashboard snapshot needs the daemon's version.
    if (url.searchParams.get("view") === "launch") return jsonResponse(launchState);
    const { listCatalogNativeSlugs } = await import("../../codex/catalog");
    const { claudeCodeAlias, claudeCodeNativeAlias } = await import("../../claude/alias");
    const disabled = new Set(config.disabledModels ?? []);
    const availableRouted = models.filter(m => !hasRoutedSlug(disabled, m.provider, m.id));
    const available = [
      ...listCatalogNativeSlugs().filter(ns => !disabled.has(ns)),
      // Claude-facing values stay RAW native selectors (resolved inbound via routeModel,
      // which accepts the raw full-slash form); only the disabled check goes tolerant.
      ...availableRouted.map(m => `${m.provider}/${m.id}`),
    ];
    const aliases: { id: string; display_name: string }[] = [];
    // Resolved once, not per model: with the global fast switch on, Claude Code discovers the
    // fast identity, so the dashboard must list the same id rather than the umbrella one.
    const cursorFastIdFor = config.fastMode === true
      ? (await import("../../adapters/cursor/catalog")).cursorFastIdFor
      : undefined;
    for (const slug of listCatalogNativeSlugs()) {
      // Readable CLI-surface alias with hash fallback (devlog 050 / audit 051 #2) —
      // the same shared helper the /v1/models ?ids=cli path uses.
      if (!disabled.has(slug)) aliases.push({ id: claudeCodeNativeAlias(slug), display_name: `${slug} (native)` });
    }
    for (const m of availableRouted) {
      const listedId = (m.provider === "cursor" ? cursorFastIdFor?.(m.id) : undefined) ?? m.id;
      aliases.push({ id: claudeCodeAlias(m.provider, listedId), display_name: `${listedId} (${m.provider})` });
    }
    const claudeCodeVersion = await probeClaudeCodeVersionForTierFill(config.claudeCode, contextWindows);
    const webSearchOverride = config.claudeCode?.webSearchSidecar;
    const visionOverride = config.claudeCode?.visionSidecar;
    const helperParent = config.claudeCode?.model?.includes("/") ? config.claudeCode.model.split("/")[0] : undefined;
    const helperVision = { ...config.visionSidecar, ...visionOverride };
    // Same pool the runtime picks (vision/plan.ts preferredVisionBackend): explicit, else inherited
    // from the Claude model's instance, so a usable inherited Pool 2 reports the Anthropic backend.
    const helperVisionInstance = helperVision.anthropicInstance ?? inheritedAnthropicInstance(config, helperParent);
    const helperVisionBackend = helperVision.backend ?? (sidecarOptionsAuth(config, helperVisionInstance).isAnthropicAuth ? "anthropic" : "openai");
    const { firstPartyDesired, readFirstPartyProxyStatus } = await import("../../claude/first-party-settings");
    const { observeClaudeDesktopMode } = await import("../../claude/desktop-first-party");
    const { claudeInterceptEnabled, getClaudeInterceptState } = await import("../../claude/intercept/runtime");
    const desired = firstPartyDesired(config, observeClaudeDesktopMode(config));
    const bound = (deps.getClaudeInterceptState ?? getClaudeInterceptState)();
    const eligible = claudeInterceptEnabled(config);
    const sharedProxy = readFirstPartyProxyStatus(config, bound?.proxyPort ?? null);
    return jsonResponse({
      ...launchState,
      cliFirstParty: config.claudeCode?.cliFirstParty === true,
      cliFirstPartyApplied: config.claudeCode?.cliFirstParty === true && sharedProxy === "live",
      desktopFirstParty: desired.desktop,
      ...interceptStatus(ctx),
      interceptEligible: eligible,
      interceptRunning: bound !== null && eligible,
      sharedProxy,
      // Three-state intent (devlog 260726_claude_auth_auto): an absent key is AUTO, not
      // subscription. The old coercion made every save convert an untouched auto config
      // into a sticky manual subscription with no way back.
      authMode: authModeIntent(config),
      /** Does the opencodex dummy marker get injected — NOT a claim about native auth. */
      markerMode: resolvedAuthMode.markerMode,
      authModeOrigin: resolvedAuthMode.origin,
      ...(resolvedAuthMode.foundBy ? { authFoundBy: resolvedAuthMode.foundBy } : {}),
      authDetectionUnknown: authDetection.presence === "unknown",
      // Separate axis: with an admission key configured a token is injected regardless
      // of mode, so the GUI must never present subscription as "no token anywhere".
      admissionKeyActive: (config.apiKeys?.length ?? 0) > 0,
      detectionScope: "daemon",
      model: config.claudeCode?.model ?? "",
      smallFastModel: config.claudeCode?.smallFastModel ?? "",
      tierModels: config.claudeCode?.tierModels ?? {},
      modelMap: config.claudeCode?.modelMap ?? {},
      classifierModel: config.claudeCode?.classifierModel ?? "",
      classifierFallbacks: config.claudeCode?.classifierFallbacks ?? [],
      systemEnv: config.claudeCode?.systemEnv === true,
      autoConnectSupported: (ctx.deps.platform ?? process.platform) === "darwin",
      maxContextTokens: config.claudeCode?.maxContextTokens ?? null,
      alwaysEnableEffort: config.claudeCode?.alwaysEnableEffort === true,
      autoContext: config.claudeCode?.autoContext !== false,
      autoCompactWindow: config.claudeCode?.autoCompactWindow ?? null,
      contextAccounting: config.claudeCode?.contextAccounting === "200k" ? "200k" : "1m",
      blockedSkills: config.claudeCode?.blockedSkills ?? null,
      injectAgents: config.claudeCode?.injectAgents !== false,
      nativePassthrough: config.claudeCode?.nativePassthrough !== false,
      sidecarPools: {
        webSearchSidecar: sidecarAnthropicPoolOptions(config, { ...config.webSearchSidecar, ...webSearchOverride }, helperParent),
        visionSidecar: sidecarAnthropicPoolOptions(config, { ...helperVision, backend: helperVisionBackend }, helperParent),
      },
      ...(webSearchOverride && Object.keys(webSearchOverride).length > 0
        ? { webSearchSidecar: { enabled: webSearchOverride.enabled, backend: webSearchOverride.backend, model: webSearchOverride.model, ...(webSearchOverride.anthropicInstance ? { anthropicInstance: webSearchOverride.anthropicInstance } : {}) } }
        : {}),
      ...(visionOverride && Object.keys(visionOverride).length > 0
        ? { visionSidecar: { enabled: visionOverride.enabled, backend: visionOverride.backend, model: visionOverride.model, ...(visionOverride.anthropicInstance ? { anthropicInstance: visionOverride.anthropicInstance } : {}) } }
        : {}),
      fastMode: config.fastMode,
      effectiveModelEnv: effectiveModelEnv(config.claudeCode, contextWindows, undefined, claudeCodeVersion),
      available,
      aliases,
      port: config.port,
    });
  }
  if (url.pathname === "/api/claude-code" && req.method === "PUT") {
    // 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;
    // 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;
    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
    const isPlainObject = (value: unknown): value is Record<string, unknown> => {
      if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
      const prototype = Object.getPrototypeOf(value);
      return prototype === Object.prototype || prototype === null;
    };
    if (!isPlainObject(parsedBody)) return jsonResponse({ error: "body must be an object" }, 400);
    const body = parsedBody as { enabled?: unknown; cliFirstParty?: unknown; authMode?: unknown; model?: unknown; smallFastModel?: unknown; modelMap?: unknown; classifierModel?: unknown; classifierFallbacks?: unknown; systemEnv?: unknown; fastMode?: unknown; maxContextTokens?: unknown; alwaysEnableEffort?: unknown; tierModels?: unknown; autoContext?: unknown; autoCompactWindow?: unknown; contextAccounting?: unknown; blockedSkills?: unknown; injectAgents?: unknown; nativePassthrough?: unknown; webSearchSidecar?: unknown; visionSidecar?: unknown };
    if (body.cliFirstParty !== undefined && typeof body.cliFirstParty !== "boolean")
      return jsonResponse({ error: "cliFirstParty must be a boolean" }, 400);
    if (body.cliFirstParty !== undefined && Object.keys(body).length !== 1)
      return jsonResponse({ error: "cliFirstParty must be sent alone", code: "cli_first_party_not_alone" }, 400);
    if (body.cliFirstParty !== undefined) {
      const { claudeInterceptEnabled, claudeInterceptProxyPort, getClaudeInterceptState } = await import("../../claude/intercept/runtime");
      const { captureDesktopFirstPartyRollback, inspectDesktopFirstParty, observeClaudeDesktopMode, resolveClaudeDesktopMode, withFirstPartySecretsSettled } = await import("../../claude/desktop-first-party");
      const { firstPartyDesired, readFirstPartyProxyStatus, reconcileClaudeFirstPartySettings } = await import("../../claude/first-party-settings");
      const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
      let bound = (deps.getClaudeInterceptState ?? getClaudeInterceptState)();
      if (body.cliFirstParty) {
        const startRefusal = interceptStartRefusal(ctx);
        if (startRefusal) return startRefusal;
        const started = await ensureManagementClaudeIntercept(ctx);
        if (!started.ok) return jsonResponse({ ...started, code: started.reason }, 409);
        bound = started.state;
        const targetPort = claudeInterceptProxyPort(config, config.port ?? 10100);
        if (targetPort !== bound.proxyPort) return jsonResponse({
          error: `Claude intercept port mismatch (configured ${targetPort}, bound ${bound.proxyPort})`,
          code: "port_mismatch", bound: bound.proxyPort, configured: targetPort,
        }, 409);
        let inspection: ReturnType<typeof inspectDesktopFirstParty>["settings"];
        try { inspection = inspectDesktopFirstParty(config).settings; }
        catch { return jsonResponse({ error: "Claude settings are unreadable", code: "unreadable" }, 500); }
        if (inspection.kind === "foreign") return jsonResponse({ error: "Claude settings env is foreign", code: "foreign_env" }, 409);
        if (inspection.kind === "unreadable") return jsonResponse({ error: "Claude settings are unreadable", code: "unreadable" }, 500);
      }
      let restoreSettings: (() => boolean) | undefined;
      try { if (body.cliFirstParty) restoreSettings = captureDesktopFirstPartyRollback(config); }
      catch { return jsonResponse({ error: "Claude settings are unreadable", code: "unreadable" }, 500); }
      type FirstPartyMutation =
        | { refusal: { error: string; code: "disabled" | "port_mismatch"; bound?: number; configured?: number } }
        | { claudeCode: OcxConfig["claudeCode"]; previous: { present: boolean; value: boolean };
            pinnedMode: "first-party" | "gateway" | undefined; retainedAmbiguous: boolean };
      let outcome: ReturnType<typeof mutatePersistedConfig<FirstPartyMutation>>;
      try {
        outcome = await settleConfigRoot(configRoot(), () => {
        const outcome = mutatePersistedConfig<FirstPartyMutation>(persisted => {
        if (body.cliFirstParty) {
          if (!claudeInterceptEnabled(persisted)) return { changed: false, value: {
            refusal: { error: "Claude intercept is disabled", code: "disabled" as const } } };
          const persistedPort = claudeInterceptProxyPort(persisted, persisted.port ?? 10100);
          if (bound === null || persistedPort !== bound.proxyPort) return { changed: false, value: {
            refusal: { error: `Claude intercept port mismatch (configured ${persistedPort}, bound ${bound?.proxyPort ?? "none"})`,
              code: "port_mismatch" as const, bound: bound?.proxyPort, configured: persistedPort } } };
        }
        const before = structuredClone(persisted);
        const previous = { present: Object.hasOwn(persisted.claudeCode ?? {}, "cliFirstParty"),
          value: persisted.claudeCode?.cliFirstParty === true };
        // 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);
        // 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 } };
        });
        if (outcome.status !== "unavailable" && !("refusal" in outcome.value)) {
          const committed = outcome.value;
      adoptPersistedClaudeCode(config, committed.claudeCode);
      const live = { ...(config.claudeCode ?? {}) };
      if (body.cliFirstParty) live.cliFirstParty = true; else delete live.cliFirstParty;
      if (committed.pinnedMode) live.desktopMode = committed.pinnedMode;
      config.claudeCode = live;
        }
        return outcome;
      });
      } catch (error) { return jsonResponse({ error: "Could not save Claude settings", code: "write_failed",
        ...(error instanceof WindowsSecretAclSettleTimeoutError ? { diagnostic: { stage: "ca", cause: "ETIMEDOUT" } } : {}) }, 500); }
      if (outcome.status === "unavailable") return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500);
      const committed = outcome.value;
      if ("refusal" in committed) return jsonResponse(committed.refusal, 409);
      let result: ReturnType<typeof reconcileClaudeFirstPartySettings> | undefined;
      const { getConfigDir, withConfigDirHardeningSettled } = await import("../../config/paths");
      try { result = await withFirstPartySecretsSettled(getConfigDir(), () => {
        if (body.cliFirstParty) restoreSettings = captureDesktopFirstPartyRollback(config);
        return (deps.reconcileClaudeFirstPartySettings ?? reconcileClaudeFirstPartySettings)(config,
          firstPartyDesired(config, observeClaudeDesktopMode(config))); }); }
      catch { /* An unexpected settings failure is mapped after conditional rollback. */ }
      if (!result?.ok) {
        let settingsRestored = true;
        if (body.cliFirstParty) {
          try { settingsRestored = result?.reason === "ca_unavailable" || await withConfigDirHardeningSettled(getConfigDir(), () => restoreSettings?.() ?? false); } catch { settingsRestored = false; }
          let rollback: ReturnType<typeof mutatePersistedConfig<OcxConfig["claudeCode"]>>;
          try {
            rollback = await settleConfigRoot(configRoot(), () => mutatePersistedConfig(persisted => {
            const block = { ...(persisted.claudeCode ?? {}) };
            if (block.cliFirstParty === true) {
              if (committed.previous.present) block.cliFirstParty = committed.previous.value;
              else delete block.cliFirstParty;
            }
            if (committed.pinnedMode && block.desktopMode === committed.pinnedMode)
              delete block.desktopMode;
            persisted.claudeCode = block;
            return { changed: true, value: structuredClone(block) };
            }));
          } catch { return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed", cliFirstParty: true,
            warnings: ["settings_rollback_incomplete"] }, 500); }
          if (rollback.status === "unavailable") return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed", cliFirstParty: true,
            warnings: ["settings_rollback_incomplete"] }, 500);
          adoptPersistedClaudeCode(config, rollback.value);
        }
        const code = result?.reason ?? "write_failed";
        return jsonResponse({ error: "Claude first-party reconciliation failed", code,
          ...(result?.diagnostic ? { diagnostic: result.diagnostic } : {}),
          ...(!body.cliFirstParty && code === "unreadable"
            ? { cliFirstParty: false, warnings: ["settings_residual"] } : {}),
          ...(body.cliFirstParty && !settingsRestored
            ? { warnings: ["settings_rollback_incomplete"] } : {}) },
          code === "intercept_disabled" || code === "foreign_env" ? 409 : 500);
      }
      const finalDesired = firstPartyDesired(config, observeClaudeDesktopMode(config));
      const residual = !finalDesired.desktop && !finalDesired.cli
        && readFirstPartyProxyStatus(config, bound?.proxyPort ?? null) !== "none";
      await syncClaudeAgentDefsBestEffort();
      return jsonResponse({ ok: true, enabled: config.claudeCode?.enabled !== false,
        nativePassthrough: config.claudeCode?.nativePassthrough !== false,
        cliFirstParty: body.cliFirstParty,
        warnings: [
          ...(committed.retainedAmbiguous ? ["shared_proxy_retained"] : []),
          ...(residual ? ["settings_residual"] : []),
        ] });
    }
    const checked = prepareClaudeCodePatch(config, body);
    if (checked instanceof Response) return checked;
    const evidenceState = JSON.stringify(config);
    const visionPatch = body.visionSidecar;
    const webPatch = body.webSearchSidecar;
    const visionEvidence = isPlainObject(visionPatch) && typeof visionPatch.model === "string" && visionPatch.model !== ""
      ? await visionCandidateRows({ ...config, visionSidecar: { ...config.visionSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.visionSidecar, visionPatch) } }) : undefined;
    const webEvidence = isPlainObject(webPatch) && (webPatch.model !== undefined || webPatch.backend !== undefined || webPatch.anthropicInstance !== undefined)
      ? await webSearchCandidateRows({ ...config, webSearchSidecar: { ...config.webSearchSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.webSearchSidecar, webPatch) } }) : undefined;
    const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
    const refusal = await settleConfigRoot(configRoot(), () => {
      if ((visionEvidence || webEvidence) && JSON.stringify(config) !== evidenceState) return jsonResponse({ error: "Sidecar validation state changed during discovery", code: "config_changed" }, 409);
      const instanceError = anthropicSidecarPatchError(config, body, true);
      if (instanceError) return jsonResponse({ error: instanceError }, 400);
      for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
        const section = body[field] as Record<string, unknown> | null | undefined;
        if (section === undefined || section === null) continue;
        // Vision override only: reject a model we can prove is blind. Unknown ids stay
        // allowed. Shares one policy module with /api/sidecar-settings so the two
        // gates cannot drift.
        if (field === "visionSidecar" && typeof section.model === "string" && section.model !== "") {
          const requested = section.model;
          const candidates = visionEvidence!;
          const hint = section.backend === "anthropic" || section.backend === "openai"
            || section.backend === "routed"
            ? section.backend
            : config.claudeCode?.visionSidecar?.backend;
          // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
          const effectiveBackend = hint ?? "openai";
          const namespaced = requested.includes("/");
          if (namespaced && effectiveBackend !== "routed") {
            return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
          }
          if (!namespaced && effectiveBackend === "routed") {
            return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
          }
          if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
            return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
          }
        }
        // Web-search override: membership gate (#2188). The executor set is closed,
        // so an id outside (runnable candidates ∪ auth slots) can never run. Same
        // module as /api/sidecar-settings — a gate on one route and a stale copy on
        // the other is no gate at all.
        if (field === "webSearchSidecar"
          && (section.model !== undefined || section.backend !== undefined || section.anthropicInstance !== undefined)) {
          const stored = config.claudeCode?.webSearchSidecar;
          // Validate against the SUBMITTED backend across the whole union, not
          // just openai/anthropic (#2457). allowedBackends above already refused
          // unknown literals; Array.includes does not narrow, hence the cast.
          // null keeps its own meaning here — drop the override and inherit the
          // global backend — which is deliberately NOT the sidecar-settings rule.
          const submittedBackend = section.backend;
          const effectiveBackend = typeof submittedBackend === "string"
            ? submittedBackend as WebSearchBackend
            : submittedBackend === null
              ? config.webSearchSidecar?.backend ?? "openai"
              : stored?.backend ?? config.webSearchSidecar?.backend ?? "openai";
          const effectiveModel = section.model === ""
            ? config.webSearchSidecar?.model
            : typeof section.model === "string"
              ? section.model
              : stored?.model ?? config.webSearchSidecar?.model;
          const candidates = webEvidence!;
          if (effectiveModel && webSearchModelIsRejected(effectiveBackend, effectiveModel, candidates)) {
            return jsonResponse(webSearchModelRejection(
              "webSearchSidecar.model",
              effectiveBackend,
              effectiveModel,
              candidates,
            ), 400);
          }
        }
      }
      const prepared = prepareClaudeCodePatch(config, body);
      if (prepared instanceof Response) return prepared;
      const { next, nextFastMode } = prepared;
      // The Claude toggle is this Home's alone: freeze what Children inherit before it moves, and
      // refuse before anything changes when that cannot be saved.
      const captureRefused = body.enabled !== undefined ? captureHomeRouteDefaultsBeforeHomeSwitch() : null;
      if (captureRefused) return jsonResponse({ error: captureRefused.message, code: "route_intent_unavailable" }, captureRefused.retryable ? 409 : 500);
      const rollback = captureConfigTopLevelRollback(config, body.fastMode === undefined
        ? ["claudeCode"] : ["claudeCode", "fastMode"]);
      try {
        if (body.fastMode !== undefined) config.fastMode = nextFastMode;
        commitClaudeCodeBlock(config, next);
        saveConfigPreservingClaudeCode(config);
      } catch (error) {
        if (!(error instanceof ConfigWritePublishedError)) rollback();
        throw error;
      }
      return null;
    });
    if (refusal) return refusal;
    const warnings: string[] = [];
    // authMode changes must reconcile the injected system env too: switching back to
    // Subscription has to remove the opencodex-owned dummy ANTHROPIC_AUTH_TOKEN
    // (audit R1 blocker #1/#2, devlog 260720_claude_authmode_persist). Model slots and
    // levers feed the same injection, so a changed or cleared slot must not linger in
    // launchd until the next restart.
    const systemEnvInputs = ["systemEnv", "authMode", "model", "smallFastModel", "tierModels",
      "maxContextTokens", "alwaysEnableEffort", "autoContext", "autoCompactWindow", "contextAccounting"] as const;
    if (systemEnvInputs.some(field => body[field] !== undefined)) {
      try {
        await applySystemEnvToggle(config, config.port);
      } catch (err) {
        warnings.push(`Failed to apply system environment setting: ${err instanceof Error ? err.message : String(err)}`);
      }
    }
    // Keep the file-backed live registry symmetric: OFF prunes immediately, while
    // ON and config changes restore definitions without requiring a restart.
    await syncClaudeAgentDefsBestEffort();
    return jsonResponse({ ok: true, enabled: config.claudeCode?.enabled !== false,
      nativePassthrough: config.claudeCode?.nativePassthrough !== false, warnings });
  }
  return null;
}