@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/server/index.ts

@@ -69,11 +69,6 @@ import { runDevinProviderMergeStartupMigration } from "../providers/devin-provid
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { StorageCleanupPolicy } from "../types";
-import {
-  MAX_CONFIGURABLE_INBOUND_BODY_BYTES,
-  MIN_CONFIGURABLE_INBOUND_BODY_BYTES,
-  resolveInboundBodyLimitBytes,
-} from "./request-decompress";
 import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
 export {
   clearThreadAccountMap,
@@ -116,7 +111,7 @@ import {
   type RequestLogEntry,
 } from "./request-log";
 import { sessionLaneIdFromRequest } from "./request-log-conversation";
-import { configureSharedSpendLedger, spendPolicyFromConfig } from "../lib/spend-reservation-ledger";
+import { setUsageLedgerRetention } from "./usage-ledger-retention";
 import { admitHttpWorkflowTurn, workflowDecisionRefusalResponse, type WorkflowRefusalLog } from "./workflow-refusal";
 export {
   addFinalRequestLog,
@@ -204,9 +199,18 @@ import {
 } from "../lib/package-tree-integrity";
 import { detectInstall } from "../update/index";
 import { createServeOptions, type ServerIngress } from "./index/serve-options";
-import { inspectStartupOwnership, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
+import { createClaudeInterceptLifecycle } from "./index/claude-intercept-lifecycle";
+import { inspectStartupOwnership, resolveInboundBodyLimitWithWarning, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
+import { acquireSpendLedgerServerLifecycle, recordFailedStartRollback, type SpendLedgerServerLifecycle } from "./index/spend-ledger-lifecycle";
+export { waitForFailedStartRollback } from "./index/spend-ledger-lifecycle";
 
 export function startServer(port?: number, deps: StartServerDeps = {}): Server<WsData> {
+  const spendLedgerLifecycle = acquireSpendLedgerServerLifecycle(getConfigDir());
+  try { return startServerWithSpendLedgerOwner(port, deps, spendLedgerLifecycle); }
+  catch (error) { recordFailedStartRollback(error, spendLedgerLifecycle.releaseAfterFailedStart()); throw error; }
+}
+
+function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartServerDeps, spendLedgerLifecycle: SpendLedgerServerLifecycle): Server<WsData> {
   const localAttestationSecret = deps.localAttestationSecret ?? createLocalAttestationSecret();
   // Captured before loadConfig() starts the optional ACL flight so stop() drains the same dir
   // even if OPENCODEX_HOME changes underneath a long-lived process.
@@ -299,12 +303,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   registerAppOwnedMemorySweepFallback();
   configureAppOwnedMemoryBudget(resolveAppOwnedMemoryBudgetBytes(config.appOwnedMemoryBudgetMb));
   enforceAppOwnedMemoryBudget();
-  // Operator token ceilings (#4546). Applied before the listener binds: the shared ledger is
-  // built on the first reservation, and a request arriving before this ran would build it with
-  // no policy and enforce nothing. An absent `spend` section resolves to the unconfigured
-  // default, which refuses nothing and opens no journal -- so on an install that never wrote
-  // the key this line changes no behaviour at all.
-  configureSharedSpendLedger(spendPolicyFromConfig(config.spend));
+  // Observe-only mode still journals physical sends, so every server owns before configuring.
+  spendLedgerLifecycle.configure(config.spend);
+  // After ownership: a second server on the same home is refused above, so the process running
+  // this line is the only one appending to usage.jsonl and the only one that may compact it.
+  setUsageLedgerRetention(config.usageLedgerMaxBytes);
   registerCodexCooldownRecoveryProbeWorker(config);
   // Issue #42 Phase 3: opt-in archived auto-cleanup (default OFF). Unref'd hourly
   // tick for daily/weekly; startup evaluation is fire-and-forget after listen.
@@ -625,26 +628,13 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   let server: Server<WsData>;
   let loopbackServer: Server<WsData> | null = null;
   let managementIngressServer: Server<WsData> | null = null;
-
-  // Resolved once, before any listener binds. The clamp is silent inside the resolver so it
-  // stays pure and per-request cheap; the operator is told here instead, once, because a
-  // config value that was quietly reduced is exactly the thing they would otherwise debug
-  // against the wrong limit.
-  const inboundBodyLimitBytes = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
-  const requestedInboundBodyLimit = config.maxInboundBodyBytes;
-  if (requestedInboundBodyLimit !== undefined
-    && requestedInboundBodyLimit > 0
-    && requestedInboundBodyLimit !== inboundBodyLimitBytes) {
-    console.warn(
-      `[server] maxInboundBodyBytes=${requestedInboundBodyLimit} is outside the supported range `
-      + `[${MIN_CONFIGURABLE_INBOUND_BODY_BYTES}, ${MAX_CONFIGURABLE_INBOUND_BODY_BYTES}]; `
-      + `using ${inboundBodyLimitBytes} bytes.`,
-    );
-  }
+  const claudeIntercept = createClaudeInterceptLifecycle<WsData>();
+  const inboundBodyLimitBytes = resolveInboundBodyLimitWithWarning(config);
 
   function ingressForServer(requestServer: Server<WsData>): ServerIngress {
     if (requestServer === loopbackServer) return "unauthenticated-loopback";
     if (requestServer === managementIngressServer) return "hub-management";
+    if (claudeIntercept.ownsListener(requestServer)) return "claude-intercept";
     return "public";
   }
   let backgroundLifecycle: ReturnType<typeof acquireServerBackgroundLifecycle> | null = null;
@@ -703,7 +693,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       get remoteWorkspaceStopping() { return remoteWorkspaceStopping; },
     });
 
-    server = Bun.serve<WsData>({ ...serveOptions, port: listenPort, hostname: bindHost });
+    server = spendLedgerLifecycle.track(Bun.serve<WsData>({ ...serveOptions, port: listenPort, hostname: bindHost }));
 
     // Both binds are one startup transaction (#1102). If the loopback bind fails after the
     // public one succeeded, leaving the public listener up would strand it: the CLI's port
@@ -711,11 +701,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     // accumulating listeners. Roll back and rethrow the original error instead.
     if (loopbackListenerPort !== null) {
       try {
-        loopbackServer = Bun.serve<WsData>({
+        loopbackServer = spendLedgerLifecycle.track(Bun.serve<WsData>({
           ...serveOptions,
           port: loopbackListenerPort,
           hostname: "127.0.0.1",
-        });
+        }));
       } catch (error) {
         try {
           // startServer is synchronous, so this rollback cannot await. Bun begins closing the
@@ -731,11 +721,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     }
     if (managementIngressPort !== null) {
       try {
-        managementIngressServer = Bun.serve<WsData>({
+        managementIngressServer = spendLedgerLifecycle.track(Bun.serve<WsData>({
           ...serveOptions,
           port: managementIngressPort,
           hostname: "127.0.0.1",
-        });
+        }));
       } catch (error) {
         // Preserve the management bind failure while synchronously initiating rollback of every
         // listener already opened in this startup transaction. startServer must not become async.
@@ -746,6 +736,10 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         throw new AuxiliaryListenerBindError("hub.managementIngress", managementIngressPort, "127.0.0.1", error);
       }
     }
+    claudeIntercept.start({
+      config, publicPort: server.port ?? listenPort, requestedPort: listenPort, maxRequestBodySize: inboundBodyLimitBytes,
+      dispatch: (req, requestServer) => serveOptions.fetch(req, requestServer),
+    });
   } catch (error) {
     unregisterQuotaAutoRefresh?.();
     userCostOverlayReconciler?.stop();
@@ -774,6 +768,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           ...(managementIngressRef
             ? [() => managementIngressRef.stop(closeActiveConnections)]
             : []),
+          () => claudeIntercept.stop(),
           async () => { await remoteWorkspaceShutdown?.(); },
           async () => {
             try {
@@ -783,16 +778,17 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             }
           },
         ],
-        async () => {
+        async listenersStopped => {
           try {
             await backgroundLifecycle.release();
             await releaseNativeMainStartupLifecycle(server);
           } finally {
             // icacls.exe from hardenConfigDir() holds the config dir open; a caller that
             // removes the dir right after stop() settles would hit EPERM/EBUSY on Windows
-            // otherwise. Runs even when an earlier release rejected — that rejection still
-            // propagates, but not before the child is drained.
-            await flushConfigDirHardening(startupConfigDir);
+            // otherwise. Config hardening still flushes when an earlier release rejects. The
+            // spend owner is retained when a listener stop failed because the socket may live.
+            try { if (listenersStopped) spendLedgerLifecycle.release(); }
+            finally { await flushConfigDirHardening(startupConfigDir); }
           }
         },
       );

package/src/server/lifecycle.ts

@@ -357,12 +357,12 @@ export function getServerListenPort(): number | undefined {
  *   caller sees the same result before a replacement binds the port. Swallowing it would let
  *   `drainAndShutdown` report success while a socket is still held.
  *
- * `always` runs after the listeners regardless of their outcome, and its own failure joins the
- * reported set rather than replacing it.
+ * `always` runs after the listeners regardless of their outcome and receives whether every
+ * listener stop succeeded. Its own failure joins the reported set rather than replacing it.
  */
 export async function runListenerShutdown(
   steps: Array<() => Promise<void>>,
-  always: () => Promise<void>,
+  always: (listenersStopped: boolean) => Promise<void>,
 ): Promise<void> {
   const failures: unknown[] = [];
   // Close admission and start connection-owner cleanup before waiting for any drain.
@@ -372,7 +372,7 @@ export async function runListenerShutdown(
     if (result.status === "rejected") failures.push(result.reason);
   }
   try {
-    await always();
+    await always(failures.length === 0);
   } catch (error) {
     failures.push(error);
   }

package/src/server/live-call-bindings.ts

@@ -9,6 +9,12 @@ export interface LiveCallBinding {
   upstreamCallId: string;
   joinStyle: "frameless-path" | "realtime-query";
   providerName: string;
+  /**
+   * The model this call settled on when it was created. A join names no model
+   * of its own, so this is what a per-key scope is judged against on reconnect
+   * — without it, a call created for one model could be rejoined as another.
+   */
+  model?: string;
   accountId?: string;
   chatgptAccountId?: string;
   keyedCredentialDigest?: string;

package/src/server/live.ts

@@ -44,7 +44,8 @@ import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
 import { resolveFirstUsableOpenAiSidecar, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
-import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "./auth-cors";
+import { admissionScopeDenial } from "./admission-model-scope";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId } from "./responses";
 import type { AdmissionLease } from "../lib/admission";
@@ -550,6 +551,62 @@ async function readRequestBodyCapped(req: Request, maxBytes: number): Promise<Ar
   }
 }
 
+/**
+ * Who is asking and for which live model, as far as a per-key scope is concerned.
+ *
+ * This path has no router to resolve a destination, so the model is read where
+ * the client states it — the call-create session, or a standalone socket's own
+ * query — and the provider is whichever OpenAI upstream this relay settles on.
+ * `model` is undefined when nobody stated one: a call-create that sends no
+ * session model, or a join onto a call this compatibility path never recorded.
+ */
+export interface LiveScopeDestination {
+  admission?: DataPlaneAdmission;
+  model: string | undefined;
+}
+
+/**
+ * The live model a call-create body names, or undefined when it names none.
+ *
+ * Both inbound shapes carry it at `session.model` — JSON directly, multipart in
+ * the `session` field — and this path relays the body upstream unchanged, so
+ * the string is the destination rather than a selector the proxy rewrites. A
+ * body that states nothing readable leaves the model to the upstream, which is
+ * a destination no model list can describe.
+ */
+export async function liveCallCreateModel(body: ArrayBuffer, contentType: string): Promise<string | undefined> {
+  try {
+    let session: unknown;
+    if (contentType.toLowerCase().includes("multipart/form-data")) {
+      const form = await new Response(body, { headers: { "content-type": contentType } }).formData();
+      const raw = form.get("session");
+      session = typeof raw === "string" ? JSON.parse(raw) : undefined;
+    } else {
+      session = (JSON.parse(new TextDecoder().decode(body)) as { session?: unknown } | null)?.session;
+    }
+    const model = (session as { model?: unknown } | null | undefined)?.model;
+    return typeof model === "string" && model.trim() ? model.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The model a sideband upgrade is for, or undefined when the request names none.
+ *
+ * A standalone session states it in the query it forwards. A join names nothing
+ * of its own: the call it attaches to chose a model at create time, and only a
+ * recorded binding can say which. This compatibility path keeps no such record,
+ * so a native join is undefined here and the external path in `audio-live.ts`
+ * supplies the model its binding stored.
+ */
+export function liveSidebandModel(target: LiveSidebandTarget): string | undefined {
+  if (target.style === "realtime-standalone" || target.style === "frameless-standalone") {
+    return new URLSearchParams(target.query).get("model")?.trim() || undefined;
+  }
+  return undefined;
+}
+
 /**
  * Resolve OpenAI/ChatGPT auth + headers for live HTTP or sideband WebSocket relays.
  * Shared by call-create and sideband so pool token override stays consistent.
@@ -559,6 +616,7 @@ export async function resolveLiveRelay(
   config: OcxConfig,
   logCtx: RequestLogContext,
   turnAdmissionLease?: AdmissionLease,
+  destination?: LiveScopeDestination,
 ): Promise<LiveRelayTarget | Response> {
   try {
     validateForwardAdmissionCredential(req.headers, config);
@@ -624,8 +682,22 @@ export async function resolveLiveRelay(
 
   // Client protocol headers first so provider/auth headers below always win on conflict.
   const headers: Record<string, string> = clientProtocolHeaders(req.headers);
+  const scopedModel = destination?.model;
   if (forward) {
     const { provider } = forward;
+    // The upstream is settled here and voice bills it for whatever model this
+    // request carries. Refuse before any of it is sent, and give back the probe
+    // lease the resolution took. A join states no model and this path keeps no
+    // record of the call it attaches to, so a key with a model list is refused
+    // there rather than admitted against an assumed default.
+    const denial = admissionScopeDenial(config, destination?.admission, scopedModel, {
+      providerName: forward.providerName,
+      modelId: scopedModel,
+    });
+    if (denial) {
+      forward.releaseProbeLease?.();
+      return denial;
+    }
     if (provider.headers) Object.assign(headers, provider.headers);
     for (const [name, value] of forward.headers) headers[name] = value;
     logCtx.model = "gpt-live";
@@ -640,6 +712,11 @@ export async function resolveLiveRelay(
   if (forwardAuthError) return forwardAuthError;
   if (candidates.keyed) {
     const { provider, apiKey, providerName } = candidates.keyed;
+    const denial = admissionScopeDenial(config, destination?.admission, scopedModel, {
+      providerName,
+      modelId: scopedModel,
+    });
+    if (denial) return denial;
     if (provider.headers) Object.assign(headers, provider.headers);
     headers.authorization = `Bearer ${apiKey}`;
     logCtx.provider = providerName;
@@ -663,13 +740,17 @@ export async function handleLive(
   config: OcxConfig,
   logCtx: RequestLogContext,
   turnAdmissionLease?: AdmissionLease,
+  admission?: DataPlaneAdmission,
 ): Promise<Response> {
   const inboundContentType = req.headers.get("content-type") ?? "application/octet-stream";
   const inboundBodyOrError = await readRequestBodyCapped(req, LIVE_REQUEST_MAX_BYTES);
   if (inboundBodyOrError instanceof Response) return inboundBodyOrError;
   const inboundBody = inboundBodyOrError;
 
-  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease);
+  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease, {
+    admission,
+    model: await liveCallCreateModel(inboundBody, inboundContentType),
+  });
   if (relay instanceof Response) return relay;
 
   const headers: Record<string, string> = { ...relay.headers };
@@ -766,8 +847,12 @@ export async function resolveLiveSidebandUpgrade(
   logCtx: RequestLogContext,
   target: LiveSidebandTarget,
   turnAdmissionLease?: AdmissionLease,
+  admission?: DataPlaneAdmission,
 ): Promise<{ headers: Record<string, string>; upstreamWsUrl: string; recordOutcome?: LiveRelayTarget["recordOutcome"] } | Response> {
-  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease);
+  const relay = await resolveLiveRelay(req, config, logCtx, turnAdmissionLease, {
+    admission,
+    model: liveSidebandModel(target),
+  });
   if (relay instanceof Response) return relay;
   return {
     headers: relay.headers,

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

@@ -1,3 +1,4 @@
+import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
@@ -131,6 +132,17 @@ function persistDesktopProfileField(
   return { ok: true };
 }
 
+async function persistDesktopModeField(
+  config: OcxConfig,
+  desktopMode: "first-party" | "gateway",
+): Promise<{ ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" }> {
+  const { recordClaudeDesktopMode } = await import("../../claude/desktop-first-party");
+  const outcome = mutatePersistedConfig(persisted => recordClaudeDesktopMode(persisted, desktopMode));
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  recordClaudeDesktopMode(config, desktopMode);
+  return { ok: true };
+}
+
 export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
   return {
     currentBytes: grokApplyFlight?.bytes ?? 0,
@@ -1002,7 +1014,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
     try {
       // #859: the CLI delegates here so the registry is built in the serving
-      // process. Accept an optional mode; default stays static for back-compat.
+      // 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 {
@@ -1011,12 +1025,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         rethrowManagementBodyTooLarge(error);
         return jsonResponse({ error: "invalid JSON body" }, 400);
       }
+      const { resolveClaudeDesktopApplyMode, applyDesktopFirstParty, captureDesktopFirstPartyRollback, removeDesktopFirstParty } = await import("../../claude/desktop-first-party");
       const requested = (parsed as { mode?: unknown } | null)?.mode;
+      let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(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 static, hybrid, or discovery" }, 400);
+          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
@@ -1032,6 +1051,60 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
         }
       }
+      if (desktopMode === "first-party") {
+        const { setIntegrationEnabled } = await import("../../codex/desired-state");
+        const desired = setIntegrationEnabled("claude-desktop", true);
+        if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
+        mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
+        const { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } = await import("../../claude/desktop-3p");
+        const rollback = captureDesktopFirstPartyRollback(config);
+        const applied = 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.reason === "foreign_env" || applied.reason === "intercept_disabled" ? 409 : 500);
+        }
+        // Remove the gateway only after the replacement env was written.
+        const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+        const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
+        let gatewayRemoved = false;
+        if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+          const removed = (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint, replaceWhileEnabled: true });
+          if (!removed.ok) {
+            const restored = removed.changed || !applied.changed || rollback();
+            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."
+                : "The gateway profile could not be removed safely, so first-party mode was not applied.",
+              code: "claude_desktop_gateway_removal_failed",
+              ...(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");
+        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,
+          ...(modeSaved.ok ? {} : { warning: `First-party env was applied, but the mode marker was not saved (${modeSaved.reason}).` }),
+        });
+      }
       const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const desired = setIntegrationEnabled("claude-desktop", true);
       if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
@@ -1083,42 +1156,31 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         nativeContextLimits(latest),
       );
       if (!result.written) return jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500);
+      const committed = persistCommittedDesktopGateway(config, state.profile, result.fingerprint);
+      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 = removeDesktopFirstParty();
+      if (!firstPartyRemoved.ok) {
+        return jsonResponse({
+          error: `Claude Code settings could not be parsed (${firstPartyRemoved.path}); first-party cleanup remains incomplete after gateway apply.`,
+          code: "claude_desktop_first_party_refused", reason: firstPartyRemoved.reason,
+          applied: true, saved: committed.ok, mode: "gateway", path: result.path,
+          ...(modeWarning ? { warning: modeWarning } : {}),
+        }, 500);
+      }
       const { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
-      const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
-        platform: deps.platform ?? process.platform,
-      });
+      const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({ platform: deps.platform ?? process.platform });
       const policyWarning = claudeDesktopPolicyWarning(policyState);
-      // Persist applied fingerprint + timestamp so GUI can show saved-vs-applied state.
-      if (result.fingerprint) {
-        // The Desktop write already landed, so a failed bookkeeping save is not
-        // an apply failure: report the miss instead of claiming a clean apply.
-        const marked = persistDesktopProfileField(config, {
-          ...state.profile,
-          appliedFingerprint: result.fingerprint,
-          appliedAt: new Date().toISOString(),
-        });
-        if (!marked.ok) {
-          return jsonResponse({
-            ok: true,
-            applied: true,
-            saved: false,
-            path: result.path,
-            fingerprint: result.fingerprint,
-            warning: [
-              `Claude Desktop was applied, but the applied marker was not saved (${marked.reason}).`,
-              policyWarning,
-            ].filter(Boolean).join(" "),
-          });
-        }
-      }
+      const warning = [modeWarning, policyWarning].filter(Boolean).join(" ");
       return jsonResponse({
         ok: true,
-        saved: true,
+        mode: "gateway",
+        saved: committed.ok,
         applied: true,
         path: result.path,
         fingerprint: result.fingerprint,
         policyState,
-        ...(policyWarning ? { warning: policyWarning } : {}),
+        ...(warning ? { warning } : {}),
       });
     } catch (error) {
       rethrowManagementBodyTooLarge(error);
@@ -1131,21 +1193,39 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     try {
       const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const { inspectDesktop3pConfigLibrary } = await import("../../claude/desktop-3p");
+      const { resolveClaudeDesktopApplyMode, inspectDesktopFirstParty } = await import("../../claude/desktop-first-party");
+      const { getClaudeInterceptState } = await import("../../claude/intercept/runtime");
       const persisted = loadConfig();
       const savedFingerprint = persisted.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
       const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
       const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
-      const applied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      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);
+      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,
+        proxyPort: intercept?.proxyPort ?? firstPartySeen.proxyPort,
+        caCertPath: firstPartySeen.caCertPath,
+      };
+      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 && observed.kind === "gateway_drifted";
+      const stale = desiredEnabled && (mode === "first-party" ? firstPartySeen.stale : observed.kind === "gateway_drifted");
       const { getDesktopHealth } = await import("../../claude/desktop-health");
       const { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
       const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
         platform: deps.platform ?? process.platform,
       });
-      const policy = claudeDesktopPolicyHealth(policyState);
+      // 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,
@@ -1153,14 +1233,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         policy,
       };
       const policyConflict = desiredEnabled && !policy.ok;
-      const baseDrift = desiredEnabled ? !applied || stale : applied || observed.kind === "unsafe";
+      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" : null
-          : applied ? "desired_off_gateway_selected" : null;
+          ? !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,
+        firstParty,
         installed: observed.kind !== "not_installed",
         observedKind: observed.kind,
         applied,