fix(settings): apply the Desktop switches and report effective state

scripts/test-layout/layout.json

@@ -1284,6 +1284,7 @@
     "service.test.ts": "service",
     "session-affinity.test.ts": "server",
     "session-lane-recall-harness.test.ts": "server",
+    "settings-desktop-switch-apply.test.ts": "config",
     "settings-main-account-hard-lock.test.ts": "config",
     "settings-oauth-open-browser.test.ts": "config",
     "settings-startup-health-seam.test.ts": "config",

src/cli/system-command.ts

@@ -42,6 +42,72 @@ async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined;
+}
+
+function desktopSwitchInertReason(reason: unknown): string {
+  if (reason === "client_role") return "this proxy is running in the client role";
+  if (reason === "non_loopback_bind_requires_admission_token") {
+    return "a non-loopback bind requires an admission token, so this flag is inert";
+  }
+  return "the stored setting is not effective in the current runtime configuration";
+}
+
+function desktopSwitchApplyReason(reason: unknown): string {
+  if (reason === "not_requested") return "no desktop switch rewrite was requested";
+  if (reason === "proxy_not_running") return "the proxy is not running";
+  if (reason === "integration_disabled") return "Codex integration is disabled";
+  if (reason === "write_lock_busy") return "the Codex config write lock is busy";
+  if (reason === "injection_refused") return "Codex config injection was refused";
+  return "the rewrite could not be completed";
+}
+
+function settingsUpdateLines(
+  result: unknown,
+  changed: { desktopAuthless: boolean; clientCompaction: boolean },
+): string[] {
+  if (!changed.desktopAuthless && !changed.clientCompaction) return ["System settings updated."];
+  const switches = recordValue(recordValue(result)?.codexDesktopSwitches);
+  if (!switches) return ["System settings updated."];
+
+  const lines: string[] = [];
+  const appendSwitch = (key: string, label: string): boolean => {
+    const state = recordValue(switches[key]);
+    if (!state || typeof state.stored !== "boolean" || typeof state.effective !== "boolean") return false;
+    lines.push(`${label}: stored ${state.stored ? "on" : "off"}.`);
+    // The effective value is always stated, even when it matches. Printing it only on a
+    // mismatch would make silence ambiguous — the reader could not tell "the stored value is
+    // in force" from "this build does not report effective state", and that ambiguity is a
+    // smaller version of the defect being fixed.
+    lines.push(state.effective === state.stored
+      ? `${label}: effective ${state.effective ? "on" : "off"}.`
+      : `${label}: effective ${state.effective ? "on" : "off"} because ${desktopSwitchInertReason(state.inertReason)}.`);
+    return true;
+  };
+
+  if (changed.desktopAuthless && !appendSwitch("codexDesktopAuthless", "Codex desktop authless")) {
+    return ["System settings updated."];
+  }
+  if (changed.clientCompaction && !appendSwitch("codexClientCompaction", "Codex client compaction")) {
+    return ["System settings updated."];
+  }
+
+  const apply = recordValue(switches.apply);
+  const authSource = recordValue(switches.authSource);
+  if (!apply || typeof apply.applied !== "boolean" || !authSource || typeof authSource.summary !== "string") {
+    return ["System settings updated."];
+  }
+  if (apply.applied) {
+    lines.push("Codex config: ~/.codex/config.toml was rewritten.");
+  } else {
+    const detail = typeof apply.detail === "string" && apply.detail.length > 0 ? ` Details: ${apply.detail}` : "";
+    lines.push(`Codex config: ~/.codex/config.toml was not rewritten because ${desktopSwitchApplyReason(apply.reason)}.${detail} Run 'ocx sync' to apply the stored settings.`);
+  }
+  lines.push(`Auth source: ${authSource.summary}`);
+  return lines;
+}
+
 async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
@@ -63,7 +129,10 @@ async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     ...(clientCompaction !== undefined ? { codexClientCompaction: clientCompaction } : {}),
   };
   const result = await runtimeRequest("/api/settings", { method: "PUT", body: JSON.stringify(body) }, deps);
-  printData(result, wantsJson, ["System settings updated."]);
+  printData(result, wantsJson, settingsUpdateLines(result, {
+    desktopAuthless: desktopAuthless !== undefined,
+    clientCompaction: clientCompaction !== undefined,
+  }));
 }
 
 async function startup(argv: string[], deps: RuntimeApiDeps): Promise<void> {

src/codex/desktop-switches.ts

@@ -0,0 +1,145 @@
+import type { OcxConfig } from "../types";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  isEffectiveCodexClientCompaction,
+  isEffectiveCodexDesktopAuthless,
+} from "./loopback-target";
+
+export type CodexDesktopSwitchInertReason =
+  | "client_role"
+  | "non_loopback_bind_requires_admission_token";
+
+export interface CodexDesktopSwitchState {
+  stored: boolean;
+  effective: boolean;
+  inertReason?: CodexDesktopSwitchInertReason;
+}
+
+export type CodexDesktopSwitchApplyReason =
+  | "not_requested"
+  | "proxy_not_running"
+  | "integration_disabled"
+  | "write_lock_busy"
+  | "injection_refused";
+
+export type CodexDesktopSwitchApply =
+  | { applied: true }
+  | {
+      applied: false;
+      reason: CodexDesktopSwitchApplyReason;
+      retryable: boolean;
+      detail?: string;
+    };
+
+export interface CodexDesktopSwitchReport {
+  codexDesktopAuthless: CodexDesktopSwitchState;
+  codexClientCompaction: CodexDesktopSwitchState;
+  apply: CodexDesktopSwitchApply;
+  authSource: { presentsCodexAccount: boolean; summary: string };
+}
+
+type DesktopSwitchConfig = Pick<
+  OcxConfig,
+  | "clientIntegrations"
+  | "runtimeRole"
+  | "hostname"
+  | "unauthenticatedLoopbackListener"
+  | "codexDesktopAuthless"
+  | "codexClientCompaction"
+>;
+
+function describeSwitch(
+  stored: boolean,
+  effective: boolean,
+  config: Pick<OcxConfig, "runtimeRole">,
+): CodexDesktopSwitchState {
+  if (!stored || effective) return { stored, effective };
+  return {
+    stored,
+    effective,
+    inertReason: config.runtimeRole === "client"
+      ? "client_role"
+      : "non_loopback_bind_requires_admission_token",
+  };
+}
+
+export function describeCodexDesktopSwitches(
+  config: DesktopSwitchConfig,
+  apply: CodexDesktopSwitchApply,
+): CodexDesktopSwitchReport {
+  const authlessStored = config.codexDesktopAuthless === true;
+  const authlessEffective = isEffectiveCodexDesktopAuthless(config);
+  const compactionStored = config.codexClientCompaction === true;
+  const compactionEffective = isEffectiveCodexClientCompaction(config);
+
+  return {
+    codexDesktopAuthless: describeSwitch(authlessStored, authlessEffective, config),
+    codexClientCompaction: describeSwitch(compactionStored, compactionEffective, config),
+    apply,
+    authSource: authlessEffective
+      ? {
+          presentsCodexAccount: false,
+          summary: "The Codex app will not require its own account sign-in.",
+        }
+      : {
+          presentsCodexAccount: true,
+          summary: "The Codex app will require its own account sign-in.",
+        },
+  };
+}
+
+export async function applyCodexDesktopSwitches(
+  config: OcxConfig,
+): Promise<CodexDesktopSwitchApply> {
+  if (!shouldSyncCodexOnStart(config)) {
+    return { applied: false, reason: "integration_disabled", retryable: false };
+  }
+
+  const { readRuntimePort } = await import("../config/process-state");
+  const runtime = readRuntimePort(process.pid);
+  if (!runtime) {
+    return { applied: false, reason: "proxy_not_running", retryable: true };
+  }
+
+  try {
+    // Imported at call time, not module load. The settings route reaches this module on
+    // every GET, and pulling the whole injection graph in just to report stored-versus-
+    // effective state would put it on a read path that never writes anything.
+    const { injectCodexConfig } = await import("./inject");
+    const result = await injectCodexConfig(runtime.port, config);
+    if (result.status === "skipped") {
+      return {
+        applied: false,
+        reason: "integration_disabled",
+        retryable: false,
+        detail: result.message,
+      };
+    }
+    if (result.success) {
+      // history_paginated_requires_native_writer stands down only the legacy relabel;
+      // apply still writes the routing and catalog half for paginated Codex homes.
+      return { applied: true };
+    }
+    if (result.retryable === true) {
+      return {
+        applied: false,
+        reason: "write_lock_busy",
+        retryable: true,
+        detail: result.message,
+      };
+    }
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: result.message,
+    };
+  } catch (error) {
+    return {
+      applied: false,
+      reason: "injection_refused",
+      retryable: false,
+      detail: error instanceof Error ? error.message : "Codex config injection failed.",
+    };
+  }
+}

src/codex/inject.ts

@@ -158,6 +158,8 @@ export interface CodexInjectResult {
    */
   historyPreflightFailureReason?: string;
   status?: "skipped";
+  /** Busy write lock, emitted by `codexInjectLockOutcome` and undeclared here until #4809. */
+  retryable?: boolean;
   /** `hub-gated` is the hub-role gate (#4236), distinct from the user's own OFF switch. */
   skippedReason?: "desired_disabled" | "desired_enabled" | "hub-gated";
   nativeSubagentDefaultsWarning?: string;

src/codex/loopback-target.ts

@@ -97,3 +97,12 @@ export function isEffectiveCodexDesktopAuthless(
     && config.runtimeRole !== "client"
     && !shouldInjectApiAuthHeader(config);
 }
+
+/** Keep reporting aligned with the admission-token gate used by standalone injection. */
+export function isEffectiveCodexClientCompaction(
+  config: Pick<OcxConfig, "runtimeRole" | "hostname" | "unauthenticatedLoopbackListener" | "codexClientCompaction"> | undefined,
+): boolean {
+  return config?.codexClientCompaction === true
+    && config.runtimeRole !== "client"
+    && !shouldInjectApiAuthHeader(config);
+}

src/server/management/config-routes.ts

@@ -3,6 +3,11 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  applyCodexDesktopSwitches,
+  describeCodexDesktopSwitches,
+  type CodexDesktopSwitchApply,
+} from "../../codex/desktop-switches";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
@@ -328,6 +333,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopAuthless: config.codexDesktopAuthless === true,
       // Absent keeps Design B remote compaction; true selects the dedicated provider identity.
       codexClientCompaction: config.codexClientCompaction === true,
+      codexDesktopSwitches: describeCodexDesktopSwitches(config, {
+        applied: false,
+        reason: "not_requested",
+        retryable: false,
+      }),
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -597,15 +607,26 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       configureAppOwnedMemoryBudget(resolveAppOwnedMemoryBudgetBytes(body.appOwnedMemoryBudgetMb));
       enforceAppOwnedMemoryBudget();
     }
-    // Both Desktop compatibility switches change the injected config.toml shape, so converge now
-    // rather than waiting for the next start; the injector re-reads config and rewrites the form.
     const authlessIsEnabled = config.codexDesktopAuthless === true;
     const clientCompactionIsEnabled = config.codexClientCompaction === true;
-    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled
-      || authlessWasEnabled !== authlessIsEnabled
-      || clientCompactionWasEnabled !== clientCompactionIsEnabled
+    const desktopSwitchesChanged = authlessWasEnabled !== authlessIsEnabled
+      || clientCompactionWasEnabled !== clientCompactionIsEnabled;
+    // Catalog convergence is not config injection, and the comment that used to sit here said
+    // it was. `convergeCodexCatalog` rejects any scope but `catalog` and never reaches the
+    // injector, which is why flipping either switch left `config.toml` in its old shape until
+    // a separate `ocx sync` (#4809). Both halves are needed when a Desktop switch changes; a
+    // picker-only update still refreshes just the catalog.
+    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled || desktopSwitchesChanged
       ? await convergeCodexCatalog()
       : undefined;
+    // Injection second, matching `syncModelsToCodex`: the injected `model_catalog_json` should
+    // point at a catalog that has already settled. And it runs here rather than inside the save
+    // because coordinated Codex writes acquire the Codex write lock N before the config mutation
+    // lock C — awaiting N while still holding C would invert that order.
+    const desktopSwitchApply: CodexDesktopSwitchApply = desktopSwitchesChanged
+      ? await applyCodexDesktopSwitches(config)
+      : { applied: false, reason: "not_requested", retryable: false };
+    const codexDesktopSwitches = describeCodexDesktopSwitches(config, desktopSwitchApply);
     const catalogRefreshPending = catalogRefresh
       ? catalogRefreshIsPending(catalogRefresh)
       : false;
@@ -622,6 +643,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       catalogRefreshPending,
       codexDesktopAuthless: authlessIsEnabled,
       codexClientCompaction: clientCompactionIsEnabled,
+      codexDesktopSwitches,
       codexMainAccountHardLock: config.codexMainAccountHardLock === true,
       mainAccountHardLock: getMainAccountHardLockStatus(config),
       startupHealth: await readStartupHealth(config),

structure/config.md

@@ -240,6 +240,34 @@ the preflight is an early no-write guard, not an authorization token for a later
 `supports_websockets = true` is appended to the provider table only when `websocketsEnabled(config)`
 returns true.
 
+## Desktop compatibility switches report three things, not one
+
+`codexDesktopAuthless` and `codexClientCompaction` only mean anything through the injected
+`config.toml`, so persisting them is not applying them. `PUT /api/settings` used to persist
+and then converge the catalog, and a comment there claimed the injector rewrote the form;
+`convergeCodexCatalog` rejects any scope but `catalog` and never reaches `injectCodexConfig`,
+so the injected shape stayed as it was until a separate `ocx sync`.
+
+The route now runs the real injection after catalog convergence and after the config mutation
+lock has closed — coordinated Codex writes take the Codex write lock before the config mutation
+lock, so awaiting the injector inside that transaction would invert the order — and reports
+three separate facts per switch: the **stored** value in `config.json`, the **effective** value
+this bind and role will actually produce, and whether `config.toml` was **applied**, with the
+reason and retryability when it was not. `src/codex/desktop-switches.ts` owns that projection.
+
+Effective values come from `isEffectiveCodexDesktopAuthless` and
+`isEffectiveCodexClientCompaction` in `src/codex/loopback-target.ts` rather than a second copy
+of the predicate, because the reporting answer and the injection answer diverging is the defect
+being fixed: a non-loopback bind without the unauthenticated loopback listener drops the
+authless flag while the API read back the configured `true`.
+
+The report also states the auth-source consequence. The flag decides `requires_openai_auth` in
+the injected provider table, which is what Codex reads to decide whether to ask the user to
+sign in at all, so flipping it changes whose identity is in use and the user is told at the
+moment they change it. The pre-existing top-level `codexDesktopAuthless` and
+`codexClientCompaction` booleans keep reporting the configured value for compatibility; the
+report is additive.
+
 ## Profile and fast tier
 
 When opencodex owns routing, it also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile