@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/server/index.ts

@@ -20,10 +20,14 @@ import {
 import { reconcileOAuthProviders } from "../oauth";
 import { invalidateCodexModelsCache } from "../codex/catalog";
 import { startMemoryWatchdog } from "./memory-watchdog";
+import { setStorageCleanupPolicyLiveSink } from "../storage/policy";
+import { setStorageCleanupPolicyJobLiveApply } from "../storage/policy-job";
+import { scheduleStorageCleanupStartupRun, startStorageCleanupScheduler } from "../storage/policy-scheduler";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { runAlibabaRegionStartupMigration } from "../providers/alibaba-region-startup";
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
+import type { StorageCleanupPolicy } from "../types";
 import {
   CodexAccountCooldownError,
   cooldownErrorMessage,
@@ -52,6 +56,8 @@ export {
   drainAndShutdown,
   getActiveTurnCount,
   isDraining,
+  isRecyclingForExit,
+  markRecyclingForExit,
   registerTurn,
   trackStreamLifetime,
   unregisterTurn,
@@ -98,8 +104,10 @@ export {
 import {
   assertServerAuthConfig,
   corsHeaders,
+  managementCorsHeaders,
   hasValidApiAuth,
   isAllowedRequestOrigin,
+  isAllowedManagementOrigin,
   isApiAuthRequired,
   isLoopbackHostname,
   jsonResponse,
@@ -108,6 +116,7 @@ import {
   safeConfigDTO,
   setCorsOrigin,
   withCors,
+  withManagementCors,
 } from "./auth-cors";
 export {
   assertServerAuthConfig,
@@ -129,6 +138,7 @@ import { handleImages } from "./images";
 import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
 import { handleSearch } from "./search";
 import { fetchAllModels, handleManagementAPI, VERSION } from "./management-api";
+import { initializeManagementAuthState, issueGuiSession, requireManagementAuth } from "./management-auth";
 
 const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
 const WEBSOCKET_IDLE_TIMEOUT_SECONDS = 0;
@@ -220,14 +230,16 @@ function attachLiveSidebandUpstream(ws: ServerWebSocket<WsData>): void {
 // Source invariant for tests/passthrough-abort.test.ts after the pure module split:
 // if (isEventStream && upstreamResponse.body) {
 // const repairConfig = route.provider.responsesItemIdRepair;
-// #314 gated shape (win32-no-repair only; default OFF on the bundled known-bad runtime):
+// const needsClientRewrite = imageGenCallAliases.size > 0
+// #314 gated shape (win32-no-client-rewrite only; default OFF on the bundled known-bad runtime):
 // decideEagerRelay(config.streamMode ?? "auto")
 // relaySseEagerBounded(upstreamResponse.body, turnAc,
+// new Response(eagerBody,
 // Default shape (tee + background inspection):
 // upstreamResponse.body.tee()
 // const repairedBody = hasResponsesItemIdRepair(repairConfig)
 // process.platform === "win32"
-// && !hasResponsesItemIdRepair(repairConfig)
+// && !needsClientRewrite
 // ? nativeBody
 // relaySseWithFailedTail(repairedBody, upstream)
 // new Response(clientBody
@@ -242,6 +254,7 @@ export function startServer(port?: number) {
   const config = runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig()));
   applyProxyEnv(config);
   assertServerAuthConfig(config);
+  const managementAuth = initializeManagementAuthState(config);
   // Refresh OAuth provider presets (models/noReasoningModels) from the registry so a proxy update
   // adding/dropping models reaches existing configs on start — not just fresh installs.
   reconcileOAuthProviders(config);
@@ -288,6 +301,16 @@ export function startServer(port?: number) {
   // #314: warn-only RSS observability (unref'd, idempotent — safe under repeated
   // startServer(0) in tests). Snapshot surfaces via GET /api/system/memory.
   startMemoryWatchdog();
+  // 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.
+  // Heavy work runs in a Worker via the single-flight job controller.
+  // Keep live config.policy in sync when background runs advance nextRun/lastRun.
+  const applyPolicy = (policy: StorageCleanupPolicy) => {
+    config.storageCleanupPolicy = policy;
+  };
+  setStorageCleanupPolicyLiveSink(applyPolicy);
+  setStorageCleanupPolicyJobLiveApply(applyPolicy);
+  startStorageCleanupScheduler();
 
   const listenPort = port ?? config.port ?? 10100;
   setCorsOrigin(listenPort);
@@ -296,7 +319,8 @@ export function startServer(port?: number) {
   // resolves localhost→127.0.0.1): on Windows `localhost` resolves ::1-first, but the injected URL
   // is 127.0.0.1, so binding literal "localhost" would reintroduce the F4 refusal. Wildcards
   // (0.0.0.0/::) and specific hosts are left untouched so intentional exposure is preserved.
-  const bindHost = /^localhost$/i.test(config.hostname ?? "") ? "127.0.0.1" : (config.hostname ?? "127.0.0.1");
+  const configuredHost = config.hostname?.trim();
+  const bindHost = !configuredHost || /^localhost$/i.test(configuredHost) ? "127.0.0.1" : configuredHost;
 
   // Codex treats empty / non-JSON 503 bodies as "Unknown error" (#452). Keep Retry-After and
   // the server_is_overloaded code so clients can back off, but always return a JSON envelope.
@@ -319,10 +343,17 @@ export function startServer(port?: number) {
       markActivity(`${req.method} ${url.pathname}`);
 
       if (req.method === "OPTIONS") {
-        if (!isAllowedRequestOrigin(req, config)) {
+        const managementPreflight = url.pathname.startsWith("/api/");
+        const allowed = managementPreflight
+          ? isAllowedManagementOrigin(req, config)
+          : isAllowedRequestOrigin(req, config);
+        if (!allowed) {
           return new Response(null, { status: 403, headers: corsHeaders() });
         }
-        return new Response(null, { status: 204, headers: corsHeaders(req, config) });
+        return new Response(null, {
+          status: 204,
+          headers: managementPreflight ? managementCorsHeaders(req, config) : corsHeaders(req, config),
+        });
       }
 
       // Responses WebSocket (phase 120.2). Codex upgrades the same /v1/responses path; auth is
@@ -358,10 +389,11 @@ export function startServer(port?: number) {
       }
 
       if (url.pathname.startsWith("/api/")) {
-        const apiAuthError = requireApiAuth(req, config, "management");
-        if (apiAuthError) return withCors(apiAuthError, req, config);
+        const apiAuthError = requireManagementAuth(req, managementAuth, config);
+        if (apiAuthError) return withManagementCors(apiAuthError, req, config);
         const mgmtResponse = await handleManagementAPI(req, url, config);
-        if (mgmtResponse) return withCors(mgmtResponse, req, config);
+        if (mgmtResponse) return withManagementCors(mgmtResponse, req, config);
+        return withManagementCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
       }
 
       if (url.pathname === "/v1/models" && req.method === "GET") {
@@ -484,6 +516,36 @@ export function startServer(port?: number) {
         return withCors(response, req, config);
       }
 
+      if (req.method === "GET" && url.pathname.startsWith("/v1/opencodex/artifacts/")) {
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return withCors(apiAuthError, req, config);
+        if (!isAllowedRequestOrigin(req, config)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
+        }
+        const id = decodeURIComponent(url.pathname.slice("/v1/opencodex/artifacts/".length));
+        const { resolveArtifactPath } = await import("../images/artifacts");
+        const artifactPath = resolveArtifactPath(id);
+        if (!artifactPath) {
+          return withCors(formatErrorResponse(404, "not_found", "artifact not found"), req, config);
+        }
+        const file = Bun.file(artifactPath);
+        const ext = artifactPath.split(".").pop()?.toLowerCase();
+        const contentType =
+          ext === "png" ? "image/png"
+            : ext === "jpg" || ext === "jpeg" ? "image/jpeg"
+              : ext === "webp" ? "image/webp"
+                : ext === "gif" ? "image/gif"
+                  : "application/octet-stream";
+        return withCors(new Response(file, {
+          status: 200,
+          headers: {
+            "content-type": contentType,
+            "cache-control": "private, max-age=3600",
+            "x-content-type-options": "nosniff",
+          },
+        }), req, config);
+      }
+
       if (url.pathname === "/v1/alpha/search" && req.method === "POST") {
         disableResponsesRequestTimeout(req, requestServer);
         if (isDraining()) {
@@ -675,7 +737,10 @@ export function startServer(port?: number) {
         return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
       }
 
-      const guiFile = serveGuiFile(url.pathname);
+      const guiSessionCandidate = req.method === "GET" && (url.pathname === "/" || !url.pathname.includes("."))
+        ? issueGuiSession(req, config, managementAuth)
+        : null;
+      const guiFile = serveGuiFile(url.pathname, undefined, guiSessionCandidate ?? undefined);
       if (guiFile) return guiFile;
       if (url.pathname === "/" && req.method === "GET") {
         return jsonResponse(rootFallbackPayload());
@@ -876,5 +941,8 @@ export function startServer(port?: number) {
       .catch(() => {});
   }
 
+  // Opt-in storage policy (default OFF). Never blocks listen; cancellable on shutdown.
+  scheduleStorageCleanupStartupRun();
+
   return server;
 }

package/src/server/lifecycle.ts

@@ -1,4 +1,10 @@
 import { flushResponseState } from "../responses/state";
+import { setStorageCleanupPolicyLiveSink } from "../storage/policy";
+import {
+  abortStorageCleanupPolicyJob,
+  setStorageCleanupPolicyJobLiveApply,
+} from "../storage/policy-job";
+import { stopStorageCleanupScheduler } from "../storage/policy-scheduler";
 
 // ---------------------------------------------------------------------------
 // Active turn tracking + graceful shutdown drain
@@ -6,6 +12,7 @@ import { flushResponseState } from "../responses/state";
 
 const activeTurns = new Set<AbortController>();
 let draining = false;
+let recyclingForExit = false;
 let _serverRef: ReturnType<typeof Bun.serve> | undefined;
 
 export function setServerRef(server: ReturnType<typeof Bun.serve> | undefined): void { _serverRef = server; }
@@ -14,6 +21,18 @@ export function registerTurn(ac: AbortController): void { activeTurns.add(ac); }
 export function unregisterTurn(ac: AbortController): void { activeTurns.delete(ac); }
 export function isDraining(): boolean { return draining; }
 export function getActiveTurnCount(): number { return activeTurns.size; }
+/** Live listen port of the Bun server, when started. */
+export function getServerListenPort(): number | undefined {
+  const port = _serverRef?.port;
+  return typeof port === "number" && port > 0 ? port : undefined;
+}
+/**
+ * Mark this process as a recycle (dashboard drain-and-restart). Exit cleanup
+ * must keep Codex/Grok/system-env injection so the replacement process inherits
+ * a working fence — unlike an intentional `ocx stop` teardown.
+ */
+export function markRecyclingForExit(): void { recyclingForExit = true; }
+export function isRecyclingForExit(): boolean { return recyclingForExit; }
 
 export function trackStreamLifetime(
   body: ReadableStream<Uint8Array>,
@@ -67,7 +86,12 @@ export async function drainAndShutdown(
   }
   // Debounced replay-state snapshot may still be pending; flush so the last completed turn's
   // previous_response_id chain survives the restart this shutdown is usually part of.
-  flushResponseState();
+  await flushResponseState();
+  // Tear down opt-in storage policy timers / worker / live-config sink so they cannot fire after stop.
+  stopStorageCleanupScheduler();
+  abortStorageCleanupPolicyJob();
+  setStorageCleanupPolicyLiveSink(null);
+  setStorageCleanupPolicyJobLiveApply(null);
   s?.stop(true);
   draining = false;
 }

package/src/server/live.ts

@@ -197,42 +197,92 @@ export function parseLiveSidebandTarget(pathname: string, searchParams: URLSearc
   return null;
 }
 
+/**
+ * True for the loopback hosts plaintext development servers listen on.
+ * `URL.hostname` keeps the brackets on IPv6, so both forms are accepted.
+ */
+function isLoopbackHost(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  return lower === "localhost" || lower.endsWith(".localhost")
+    || lower === "127.0.0.1" || lower.startsWith("127.")
+    || lower === "::1" || lower === "[::1]";
+}
+
+/**
+ * Normalize the sideband base to end in exactly `/v1`, with no query, fragment,
+ * or userinfo. Any failure closes to the canonical Realtime API root — never to
+ * the input — because this string decides where upstream bearer credentials and
+ * user audio are sent.
+ *
+ * Bounds, all fail-closed:
+ *   - scheme must be https/wss, or http/ws with a loopback host (the local
+ *     development case this knob exists for);
+ *   - URL userinfo is rejected (URL#toString would forward it verbatim);
+ *   - unparseable input is rejected.
+ *
+ * Endpoint-form overrides are recognized the way upstream recognizes them
+ * (codex-rs realtime_websocket/methods.rs:994): a terminal `/realtime`,
+ * `/realtime/calls/<id>`, or `/live/<id>` is stripped so the root can be
+ * re-derived. A path prefix survives (`https://host/api/v1` keeps `/api`).
+ */
+function normalizeSidebandRoot(baseUrl: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return LIVE_SIDEBAND_API_ROOT;
+  }
+  const secure = parsed.protocol === "https:" || parsed.protocol === "wss:";
+  const plaintext = parsed.protocol === "http:" || parsed.protocol === "ws:";
+  if ((!secure && !plaintext) || (plaintext && !isLoopbackHost(parsed.hostname)) || parsed.username || parsed.password) {
+    return LIVE_SIDEBAND_API_ROOT;
+  }
+  parsed.search = "";
+  parsed.hash = "";
+  const path = parsed.pathname
+    .replace(/\/+$/, "")
+    .replace(/\/realtime(?:\/calls\/[^/]+)?$/, "")
+    .replace(/\/live\/[^/]+$/, "")
+    .replace(/\/v1$/, "");
+  parsed.pathname = `${path}/v1`;
+  return parsed.toString().replace(/\/$/, "");
+}
+
+/**
+ * Resolve the sideband base. Upstream policy (codex-rs 438c9e98d): the sideband
+ * join is NOT derived from the selected model provider — precedence is exactly
+ * the explicit override when configured, otherwise the canonical Realtime API
+ * root. The provider base URL deliberately plays no part; a user who needs a
+ * non-canonical host sets the override, the same escape hatch upstream ships as
+ * `experimental_realtime_ws_base_url`.
+ */
+function sidebandBaseRoot(overrideBaseUrl?: string): string {
+  return normalizeSidebandRoot(overrideBaseUrl?.trim() || LIVE_SIDEBAND_API_ROOT);
+}
+
 /**
  * Build the upstream sideband WebSocket URL for a resolved OpenAI/ChatGPT provider.
  * Mirrors openai/codex `websocket_url_from_api_url_for_call` + `normalize_realtime_path`.
+ *
+ * Deliberate deviation: the realtime-query style keeps `intent=quicksilver`,
+ * which upstream does not send. That URL is live against real OpenAI
+ * infrastructure for every canonical voice user and this parameter is known to
+ * work; dropping it is future work gated on a live smoke test. Parity here is
+ * scoped to the host, override precedence, and provider-query exclusion.
  */
 export function buildLiveSidebandUpstreamWsUrl(
-  providerBaseUrl: string,
-  usesBackendShape: boolean,
   target: LiveSidebandTarget,
+  overrideBaseUrl?: string,
 ): string {
-  const root = providerBaseUrl.replace(/\/$/, "");
-  if (usesBackendShape) {
-    // ChatGPT backend-api call-create, but the sideband join lives on the public API host
-    // (matches openai/codex, which builds the sideband from the ApiKey provider default).
-    if (target.style === "frameless-path") {
-      return httpsToWss(`${LIVE_SIDEBAND_API_ROOT}/live/${target.callId}`);
-    }
-    if (target.style === "realtime-calls-path") {
-      return httpsToWss(`${LIVE_SIDEBAND_API_ROOT}/realtime/calls/${target.callId}`);
-    }
-    return httpsToWss(
-      `${LIVE_SIDEBAND_API_ROOT}/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
-    );
-  }
+  const sidebandRoot = sidebandBaseRoot(overrideBaseUrl);
   if (target.style === "frameless-path") {
-    // Frameless: normalize to .../live then append /{callId}.
-    const apiRoot = root.replace(/\/v1\/?$/, "");
-    return httpsToWss(`${apiRoot}/v1/live/${target.callId}`);
+    return httpsToWss(`${sidebandRoot}/live/${target.callId}`);
   }
   if (target.style === "realtime-calls-path") {
-    const apiRoot = root.replace(/\/v1\/?$/, "");
-    return httpsToWss(`${apiRoot}/v1/realtime/calls/${target.callId}`);
+    return httpsToWss(`${sidebandRoot}/realtime/calls/${target.callId}`);
   }
-  // Realtime v1/v2: /v1/realtime?intent=quicksilver&call_id=
-  const apiRoot = root.replace(/\/v1\/?$/, "");
   return httpsToWss(
-    `${apiRoot}/v1/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
+    `${sidebandRoot}/realtime?intent=quicksilver&call_id=${encodeURIComponent(target.callId)}`,
   );
 }
 
@@ -542,7 +592,7 @@ export async function resolveLiveSidebandUpgrade(
   if (relay instanceof Response) return relay;
   return {
     headers: relay.headers,
-    upstreamWsUrl: buildLiveSidebandUpstreamWsUrl(relay.providerBaseUrl, relay.usesBackendShape, target),
+    upstreamWsUrl: buildLiveSidebandUpstreamWsUrl(target, config.experimentalRealtimeWsBaseUrl),
     recordOutcome: relay.recordOutcome,
   };
 }

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

@@ -11,6 +11,7 @@ import {
   providerBaseUrlConfigError,
   providerHeadersConfigError,
   saveConfigPreservingClaudeCode,
+  subagentDefaultSyncEffective,
 } from "../../config";
 import {
   clearLoginState,
@@ -103,22 +104,43 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // 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 } = await import("../../codex/features");
+    const {
+      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads,
+      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
+    } = await import("../../codex/features");
     const enabled = isMultiAgentV2Enabled();
     return jsonResponse({
       enabled,
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      agentsEnabled: getAgentsEnabled(),
+      agentsMaxDepth: getAgentsMaxDepth(),
+      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      // 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.
+      agentsMaxDepthAppliesWhenV2Disabled: !enabled,
     });
   }
   if (url.pathname === "/api/v2" && req.method === "PUT") {
-    let body: { enabled?: unknown; maxConcurrentThreadsPerSession?: unknown; multiAgentMode?: unknown };
+    let body: {
+      enabled?: unknown;
+      maxConcurrentThreadsPerSession?: unknown;
+      multiAgentMode?: unknown;
+      agentsEnabled?: unknown;
+      agentsMaxDepth?: unknown;
+      subagentDeveloperInstructions?: unknown;
+    };
     try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
     const wantsFlag = body.enabled !== undefined;
     const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
     const wantsMode = body.multiAgentMode !== undefined;
-    if (!wantsFlag && !wantsThreads && !wantsMode) return jsonResponse({ error: "body must set enabled, multiAgentMode, and/or maxConcurrentThreadsPerSession" }, 400);
+    const wantsAgentsEnabled = body.agentsEnabled !== undefined;
+    const wantsMaxDepth = body.agentsMaxDepth !== undefined;
+    const wantsSubagentInstructions = body.subagentDeveloperInstructions !== undefined;
+    if (!wantsFlag && !wantsThreads && !wantsMode && !wantsAgentsEnabled && !wantsMaxDepth && !wantsSubagentInstructions) {
+      return jsonResponse({ error: "body must set enabled, multiAgentMode, maxConcurrentThreadsPerSession, agentsEnabled, agentsMaxDepth, and/or subagentDeveloperInstructions" }, 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") {
       return jsonResponse({ error: "body.multiAgentMode must be 'v1', 'default', or 'v2'" }, 400);
@@ -126,12 +148,31 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     if (wantsThreads && (typeof body.maxConcurrentThreadsPerSession !== "number" || !Number.isInteger(body.maxConcurrentThreadsPerSession) || body.maxConcurrentThreadsPerSession < 1)) {
       return jsonResponse({ error: "body.maxConcurrentThreadsPerSession must be an 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);
+    }
     const mode = wantsMode ? body.multiAgentMode as "v1" | "default" | "v2" : undefined;
     const modeFlag = mode === "v2" ? true : mode === "v1" ? false : undefined;
     if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
       return jsonResponse({ error: `body.enabled conflicts with multiAgentMode '${mode}'` }, 400);
     }
-    const { isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2 } = await import("../../codex/features");
+    const {
+      isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
+      getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
+      setAgentsEnabled, setAgentsMaxDepth, setSubagentDeveloperInstructions,
+    } = await import("../../codex/features");
     const warnings: string[] = [];
     const requestedFlag = wantsFlag ? body.enabled as boolean : modeFlag;
     if (requestedFlag !== undefined || wantsThreads) {
@@ -158,6 +199,36 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       saveConfigPreservingClaudeCode(config);
       warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
     }
+    // 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/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) });
+    if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => setAgentsMaxDepth(body.agentsMaxDepth as number | null) });
+    if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => setSubagentDeveloperInstructions(body.subagentDeveloperInstructions as string | null) });
+    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);
+      }
+    }
+    // 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.");
+    }
     await refreshCodexCatalogBestEffort();
     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();
@@ -167,6 +238,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxThreadsConflict: enabled && hasAgentsMaxThreads(),
       maxConcurrentThreadsPerSession: getLogicalMaxThreads(),
       multiAgentMode: config.multiAgentMode ?? "default",
+      agentsEnabled: getAgentsEnabled(),
+      agentsMaxDepth: getAgentsMaxDepth(),
+      subagentDeveloperInstructions: getSubagentDeveloperInstructions(),
+      agentsMaxDepthAppliesWhenV2Disabled: !enabled,
       warnings,
     });
   }
@@ -190,6 +265,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       )));
     return jsonResponse({
       multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
+      syncCodexSubagentDefaults: subagentDefaultSyncEffective(config),
       model: config.injectionModel ?? null,
       effort: config.injectionEffort ?? null,
       prompt: config.injectionPrompt ?? null,
@@ -207,6 +283,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     }
     const body = parsedBody as {
       multiAgentGuidanceEnabled?: unknown;
+      syncCodexSubagentDefaults?: unknown;
       model?: unknown;
       effort?: unknown;
       prompt?: unknown;
@@ -214,6 +291,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const { isCodexReasoningEffort } = await import("../../reasoning-effort");
 
     let nextEnabled = config.multiAgentGuidanceEnabled;
+    // Start from the effective state reported by GET. A stale hand-edited
+    // `true` without a model must not spring back on during a model-only PUT.
+    let nextSyncCodexSubagentDefaults = subagentDefaultSyncEffective(config);
     let nextModel = config.injectionModel;
     let nextEffort = config.injectionEffort;
     let nextPrompt = config.injectionPrompt;
@@ -224,10 +304,16 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       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.length > 0) nextModel = body.model;
-      else return jsonResponse({ error: "model must be a non-empty string or null" }, 400);
+      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;
@@ -242,10 +328,21 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       else if (body.prompt === null || body.prompt === "") nextPrompt = undefined;
       else return jsonResponse({ error: "prompt must be a string or null" }, 400);
     }
-    // Clearing the model always clears the effort (it is meaningless alone).
-    if (!nextModel) nextEffort = undefined;
+    // 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);
+    }
 
     config.multiAgentGuidanceEnabled = nextEnabled;
+    if (nextSyncCodexSubagentDefaults) config.syncCodexSubagentDefaults = true;
+    else delete config.syncCodexSubagentDefaults;
     if (nextModel) config.injectionModel = nextModel;
     else delete config.injectionModel;
     if (nextEffort) config.injectionEffort = nextEffort;
@@ -257,6 +354,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     return jsonResponse({
       ok: true,
       multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
+      syncCodexSubagentDefaults: subagentDefaultSyncEffective(config),
       model: config.injectionModel ?? null,
       effort: config.injectionEffort ?? null,
       prompt: config.injectionPrompt ?? null,

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

@@ -29,6 +29,10 @@ import { providerCodexAccountMode } from "../../providers/registry";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import {
+  CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR,
+  codexAccountNamespaceForModel,
+} from "../../codex/account-namespace-match";
 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";
@@ -123,6 +127,9 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
     const previous = config.combos?.[sourceId];
     const oldPublicModel = previous ? comboPublicModelId(sourceId, previous) : null;
     const newPublicModel = comboPublicModelId(id, normalized);
+    if (codexAccountNamespaceForModel(config.codexAccountNamespaces, newPublicModel)) {
+      return jsonResponse({ error: CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR }, 409);
+    }
     const nextCombos = { ...(config.combos ?? {}) };
     if (renameFrom) delete nextCombos[renameFrom];
     nextCombos[id] = stored;