@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/codex/shim-overlay.ts

@@ -44,6 +44,10 @@ export function overlayActivationHint(configDir = getConfigDir()): string {
 function sameId(left: OverlayIdentity | null | undefined, right: OverlayIdentity | null | undefined): boolean {
   return !!left && !!right && left.dev === right.dev && left.ino === right.ino;
 }
+/** APFS device numbers can change after reboot; persisted ownership still requires the same inode. */
+function samePersistedInode(current: OverlayIdentity, recorded: OverlayIdentity | undefined): boolean {
+  return !!recorded && current.ino === recorded.ino;
+}
 function lexical(path: string): Stats | null {
   try { return lstatSync(path); }
   catch (error) { if (fileErrorCode(error) === "ENOENT") return null; throw error; }
@@ -128,7 +132,7 @@ function shellEnvironment(): string {
     'unset ocx_shim_dir ocx_shim_rest ocx_shim_path ocx_shim_more ocx_shim_part', ""].join("\n");
 }
 function ownedWrapper(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.wrapperIdentity)
+  return samePersistedInode(value.identity, state.wrapperIdentity)
     && value.content.includes(SHIM_MARKER) && value.content.includes(`exec ${shQuote(state.launcherPath)} "$@"`);
 }
 function requireOverlayIdentities(state: OverlayState): void {
@@ -137,7 +141,7 @@ function requireOverlayIdentities(state: OverlayState): void {
   }
 }
 function ownedEnvironment(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.envIdentity) && value.content === shellEnvironment();
+  return samePersistedInode(value.identity, state.envIdentity) && value.content === shellEnvironment();
 }
 function revalidateOverlay(state: OverlayState, saved: Snapshot | null, wrapper: Snapshot | null, env: Snapshot | null): void {
   if (!unchanged(statePath(), saved) || !unchanged(state.wrapperPath, wrapper) || !unchanged(overlayPaths().env, env)) {
@@ -201,6 +205,7 @@ export function overlayDiagnostic(state: ShimState): CodexShimDiagnostic {
     inspection?.revalidate();
   } catch (error) { active = null; runnable = false; integrityMessage = failure(error).message; }
   return { installed: true, healthy: complete && runnable && active === true, runnable, active,
+    activationPending: complete && runnable && active !== true,
     summary: `Codex PATH shim: ${complete && runnable ? "ready" : "unhealthy"} at ${state.wrapperPath}; launcher ${state.launcherPath}; PATH ${active === null ? "unverified" : active ? "active" : "inactive"}. ${complete && runnable ? overlayActivationHint() : integrityMessage || "Run ocx codex-shim install to repair the shim."}` };
 }
 
@@ -404,7 +409,9 @@ function failure(error: unknown): InstallResult {
   const message = error instanceof Error ? error.message : "Codex overlay operation failed";
   return { installed: false, refused: true, message: truncateRetainedUtf8(message.replace(/[\r\n]/g, " "), MAX_DIAGNOSTIC_VALUE_BYTES) };
 }
-function installLocked(discover: () => string | null, automatic: boolean, check: () => void): InstallResult {
+function installLocked(
+  discover: () => string | null, automatic: boolean, check: () => void, describeMiss?: () => string | null,
+): InstallResult {
   recoverJournal(check);
   const pinnedState = snapshot(statePath());
   const result = readStateResult();
@@ -428,18 +435,20 @@ function installLocked(discover: () => string | null, automatic: boolean, check:
     const discovered = automatic ? null : discover();
     launcher = discovered ? resolve(discovered) : null;
   }
-  if (!launcher) throw new Error("Native Codex launcher not found; install or repair Codex with its package manager");
+  // A discovery that refused a candidate (fnm's temporary multishell path) says why; reporting it
+  // as plain absence sent users to reinstall a Codex that was already there (#6963).
+  if (!launcher) throw new Error(describeMiss?.() || "Native Codex launcher not found; install or repair Codex with its package manager");
   check();
   return publishOverlay(launcher, overlay, check, pinnedState);
 }
-export function installUnixOverlay(discover: () => string | null): InstallResult {
+export function installUnixOverlay(discover: () => string | null, describeMiss?: () => string | null): InstallResult {
   let lock: ReturnType<typeof tryAcquireShimRestoreLock> = null;
   try {
     const check = namespace(true);
     lock = tryAcquireShimRestoreLock();
     if (!lock) throw new Error("Codex shim operation is already in progress; retry later");
     check();
-    return installLocked(discover, false, check);
+    return installLocked(discover, false, check, describeMiss);
   } catch (error) { return failure(error); }
   finally { lock?.release(); }
 }

package/src/codex/shim.ts

@@ -1079,7 +1079,7 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
 }
 
 export function installCodexShim(deps: RuntimePreflightDeps = {}): { installed: boolean; message: string; refused?: boolean; runnable?: boolean } {
-  if (process.platform !== "win32") return installUnixOverlay(findCodexOnPath);
+  if (process.platform !== "win32") return installUnixOverlay(findCodexOnPath, lastCodexDiscoveryError);
   return installCodexShimInternal({ ...deps, allowFreshInstall: true });
 }
 

package/src/combos/failover.ts

@@ -1,6 +1,7 @@
 import { parseResetCooldownMs } from "../codex/routing";
 import { classifyError, isCyberPolicyCode } from "../lib/errors";
 import { isNonReplayableUpstreamCode } from "../lib/upstream-retry";
+import { isAnthropicBillingFailure } from "../providers/anthropic-billing-refusal";
 import type { OcxComboTarget } from "../types";
 import { targetKey } from "./types";
 import {
@@ -563,6 +564,7 @@ export function comboFailureCooldownScope(
   options?: { code?: string | null },
 ): ComboFailureCooldownScope {
   const code = normalizedFailureCode(options?.code);
+  if (isAnthropicBillingFailure(status, message, options?.code)) return "provider";
   // Request-shape refusals first: an oversized request must not cool a healthy target.
   // A native transport can surface a zero-output model overflow as a generic
   // upstream_server_error carrying precise context-window prose, so consult the bounded
@@ -847,6 +849,7 @@ export function comboFailureDecision(
   // reaches that list and returns terminal before anything can ask whether the next target
   // could have served the request (#4903).
   if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop";
+  if (isAnthropicBillingFailure(status, message, options?.code)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/config/api-key-reconcile.ts

@@ -0,0 +1,34 @@
+type KeyRecord = Record<string, unknown> & { id: string };
+
+function index(value: unknown): Map<string, KeyRecord> | null {
+  if (value === undefined) return new Map();
+  if (!Array.isArray(value)) return null;
+  const rows = new Map<string, KeyRecord>();
+  for (const row of value) {
+    if (!row || typeof row !== "object" || Array.isArray(row) || typeof row.id !== "string" || !row.id || rows.has(row.id)) return null;
+    rows.set(row.id, row);
+  }
+  return rows;
+}
+
+/** Stable-ID three-way merge: either side's revocation defeats stale edits to that ID. */
+export function reconcileApiKeys(
+  baseline: unknown, live: unknown, persisted: unknown,
+  mergeRecord: (live: Record<string, unknown>, baseline: Record<string, unknown>, persisted: Record<string, unknown>) => void,
+): unknown[] | null {
+  if (baseline === undefined && live === undefined && persisted === undefined) return null;
+  const before = index(baseline), pending = index(live), disk = index(persisted);
+  if (!before || !pending || !disk) return null;
+  const merged: KeyRecord[] = [];
+  const liveOrder = [...pending.keys()], diskOrder = [...disk.keys()];
+  const order = JSON.stringify(liveOrder) === JSON.stringify([...before.keys()])
+    ? [...diskOrder, ...liveOrder] : [...liveOrder, ...diskOrder];
+  for (const id of new Set(order)) {
+    const local = pending.get(id), saved = disk.get(id);
+    if (before.has(id) && (!local || !saved)) continue;
+    const row = structuredClone(local ?? saved!);
+    if (local && saved) mergeRecord(row, before.get(id) ?? {}, saved);
+    merged.push(row);
+  }
+  return merged;
+}

package/src/config/diagnostics.ts

@@ -6,6 +6,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import * as z from "zod/v4";
 import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
+import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import type { OcxConfig } from "../types";
 import { anthropicAccountPoolConfigError, anthropicOAuthInstanceConfigError, anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
@@ -648,6 +649,21 @@ export function metricsExportConfigError(value: unknown): string | null {
   return null;
 }
 
+/** Load degrades a malformed service health recovery section to off; live writes reject it. */
+export function serviceHealthRecoveryConfigError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "serviceHealthRecovery") || raw.serviceHealthRecovery === undefined) return null;
+  const section = rawConfigRecord(raw.serviceHealthRecovery);
+  if (!section) return "schema_invalid: serviceHealthRecovery: must be an object or omitted";
+  if (Object.keys(section).some(key => key !== "enabled")) {
+    return "schema_invalid: serviceHealthRecovery: contains an unsupported field";
+  }
+  if (section.enabled !== undefined && typeof section.enabled !== "boolean") {
+    return "schema_invalid: serviceHealthRecovery.enabled: must be a boolean";
+  }
+  return null;
+}
+
 
 function skillsConfigError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
@@ -679,7 +695,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
   const anthropicError = anthropicOAuthInstanceConfigError(value) ?? anthropicAccountPoolConfigError(value) ?? anthropicSidecarConfigError(value);
   if (anthropicError) return { ok: false, error: anthropicError };
   const boundaryError = blockedModelRedirectsError(value)
-    ?? compactionRecoveryConfigError(value) ?? configReasoningPinsConfigError(value)
+    ?? compactionRecoveryConfigError(value) ?? desktopCompatibilityConfigError(value) ?? configReasoningPinsConfigError(value)
     ?? blankHostnameError(value)
     ?? (rawSubagentModelForce(value) !== undefined && !isSubagentModelEntry(rawSubagentModelForce(value)) ? "schema_invalid: claudeCode.subagentModelForce: expected a safe roster-style model id" : null)
     ?? claudeSubagentEffortError(value)
@@ -710,6 +726,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? loopbackListenerPortError(value)
     ?? managementIngressConfigError(value)
     ?? metricsExportConfigError(value)
+    ?? serviceHealthRecoveryConfigError(value)
     ?? skillsConfigError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);

package/src/config/feature-flags.ts

@@ -17,6 +17,11 @@ export function metricsExportEnabled(config: Pick<OcxConfig, "metricsExport">):
   return config.metricsExport?.enabled === true;
 }
 
+/** Default-off service health recovery (#6671); read once when the proxy starts. */
+export function serviceHealthRecoveryEnabled(config: Pick<OcxConfig, "serviceHealthRecovery">): boolean {
+  return config.serviceHealthRecovery?.enabled === true;
+}
+
 /**
  * Default cadence for catalog auto-refresh (issue #3630): one converge pass
  * per hour. Each pass spends a live /models call against every enabled provider, and

package/src/config/live-reconcile.ts

@@ -18,6 +18,8 @@ import { withConfigMutationLockSync, bumpGenerationForCooperatingConfigWrite } f
 import { ConfigWritePublishedError, persistConfigUnlocked, readRawConfigJson } from "./persist-unlocked";
 import { configDiagnosticsFromRaw, readConfigDiagnostics } from "./diagnostics";
 import { normalizePersistedClaudeCode } from "./load-degrade";
+import { reconcileApiKeys } from "./api-key-reconcile";
+import { captureLiveTopologyBaseline, LIVE_TOPOLOGY_KEYS, projectLiveTopology } from "./live-topology";
 
 // ---------------------------------------------------------------------------
 // Hand-edit protection for the `claudeCode` subtree (devlog 260726_claude_auth_auto/040 H1).
@@ -104,6 +106,7 @@ const detachedConfigSnapshots = new WeakSet<OcxConfig>();
 export function armClaudeCodeBaseline(config: OcxConfig): void {
   liveConfigBaseline.set(config, structuredClone(config));
   claudeCodeBaseline.set(config, structuredClone(config.claudeCode));
+  captureLiveTopologyBaseline(config);
 }
 
 /**
@@ -135,6 +138,19 @@ export function adoptPersistedProviderIntoLiveConfig(
   if (persistedConfig) refreshPreservedProviderOwner(config, persistedConfig);
 }
 
+/** Adopt only the committed next-start preference; preserve unrelated pending live edits. */
+export function adoptPersistedDesktopCompatibility(config: OcxConfig, persisted: OcxConfig["desktopCompatibility"]): void {
+  const baseline = liveConfigBaseline.get(config);
+  const merged = reconcileConfigValue(baseline?.desktopCompatibility ?? MISSING_CONFIG_VALUE,
+    config.desktopCompatibility ?? MISSING_CONFIG_VALUE, persisted ?? MISSING_CONFIG_VALUE);
+  if (merged === MISSING_CONFIG_VALUE) delete config.desktopCompatibility;
+  else config.desktopCompatibility = merged as OcxConfig["desktopCompatibility"];
+  if (baseline) {
+    if (persisted === undefined) delete baseline.desktopCompatibility;
+    else baseline.desktopCompatibility = structuredClone(persisted);
+  }
+}
+
 /** Test seam only: is this instance armed? */
 export function claudeCodeBaselineArmed(config: OcxConfig): boolean {
   return claudeCodeBaseline.has(config);
@@ -321,7 +337,12 @@ function reconcileConfigRecord(
         && baselineValue !== MISSING_CONFIG_VALUE
         && persistedValue === MISSING_CONFIG_VALUE
       ? MISSING_CONFIG_VALUE
-      : key === "customModels"
+      : key === "apiKeys"
+        ? reconcileApiKeys(baselineValue === MISSING_CONFIG_VALUE ? undefined : baselineValue,
+            liveValue === MISSING_CONFIG_VALUE ? undefined : liveValue,
+            persistedValue === MISSING_CONFIG_VALUE ? undefined : persistedValue, reconcileConfigRecord)
+          ?? reconcileConfigValue(baselineValue, liveValue, persistedValue)
+        : key === "customModels"
         ? reconcileCustomModels(baselineValue, liveValue, persistedValue)
           ?? reconcileConfigValue(baselineValue, liveValue, persistedValue)
         : key === "disabledModels"
@@ -401,7 +422,7 @@ export function reconcileLiveConfigFromDisk(config: OcxConfig, persistedBaseline
     config as unknown as Record<string, unknown>,
     persistedBaseline as unknown as Record<string, unknown>,
     persisted as unknown as Record<string, unknown>,
-    new Set(["hostname", "port", ...(claudeGuardArmed ? ["claudeCode"] : [])]),
+    new Set([...LIVE_TOPOLOGY_KEYS, ...(claudeGuardArmed ? ["claudeCode"] : [])]),
   );
   applyConfigObjectChildDeletions(config, childDeletions);
 
@@ -473,36 +494,32 @@ export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
     // custom-model deletion migration. A second read could observe different bytes.
     const onDisk = readRawConfigJson();
     const baseline = liveConfigBaseline.get(config);
+    let diskDeletedKeys = new Set<string>();
+    let persistedSnapshot: OcxConfig | undefined;
     if (baseline && onDisk !== undefined) {
       const persistedDiagnostics = configDiagnosticsFromRaw(JSON.stringify(onDisk));
       if (persistedDiagnostics.source === "file") {
-        // A detached snapshot diverged only where this pipeline mutated it (model
-        // discovery fields for the auto-refresh tick): it cannot express a
-        // deliberate deletion, so the disk-only-key and listener-binding skips
-        // below would only discard concurrent hand edits. It merges every top-level
-        // key — including configRebaseProvenance, so a cooperating writer's
-        // deletion marker adopted from disk is honored instead of silently dropped —
-        // and captures deletion intent from the current disk snapshot before the
-        // merge can temporarily restore a key and invalidate its deletion marker.
+        persistedSnapshot = persistedDiagnostics.config;
+        // Capture authoritative disk deletions before reconciliation can restore a key.
+        // Live instances retain actual socket identity; detached discovery snapshots
+        // own no socket and also merge listener fields and disk-only sections.
         const detached = detachedConfigSnapshots.has(config);
-        const deletedKeys = detached
-          ? configRebaseDeletionKeys(persistedDiagnostics.config)
-          : configRebaseDeletionKeys(config);
+        diskDeletedKeys = configRebaseDeletionKeys(persistedDiagnostics.config);
+        // Preserve explicit pending live edits; stale retention is not an edit.
+        if (!detached) for (const key of diskDeletedKeys) {
+          if (!LIVE_TOPOLOGY_KEYS.has(key) && !deepEqual(
+            ownConfigValue(config as unknown as Record<string, unknown>, key),
+            ownConfigValue(baseline as unknown as Record<string, unknown>, key))) diskDeletedKeys.delete(key);
+        }
+        const deletedKeys = new Set([...diskDeletedKeys, ...configRebaseDeletionKeys(config)]);
         const skipped = detached
           ? new Set(["claudeCode"])
-          : new Set(["hostname", "port", "claudeCode", CONFIG_REBASE_PROVENANCE_KEY]);
+          : new Set([...LIVE_TOPOLOGY_KEYS, "claudeCode", CONFIG_REBASE_PROVENANCE_KEY]);
         if (!detached) {
-          const provenanceExists = configHasRebaseProvenance(config);
-          // Only keys this live config is actually known to have diverged on may be
-          // rebased. The baseline is captured once when the server arms it, so any key
-          // that appeared on disk afterwards — through saveConfig(), a hand edit, or
-          // another process — is absent from the baseline as well as from the live
-          // config. Reconciling those keys reads "live never changed this" and adopts
-          // the disk value, which resurrects a field the live writer had deliberately
-          // deleted (#1462 regression: PUT /api/grok/selection with an empty list).
-          // Restrict the merge to keys the baseline knew about, plus keys the live
-          // config still carries; a key that exists only on disk is left to the
-          // ordinary whole-config write below.
+          const provenanceExists = configHasRebaseProvenance(config) || configHasRebaseProvenance(persistedDiagnostics.config);
+          // Without provenance, disk-only keys remain subject to the legacy whole-
+          // config write: adopting them could resurrect a deliberate live deletion
+          // absent from its baseline (#1462). Provenance makes that intent explicit.
           const rebaseableKeys = new Set([
             ...Object.keys(baseline as unknown as Record<string, unknown>),
             ...Object.keys(config as unknown as Record<string, unknown>),
@@ -521,6 +538,7 @@ export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
           skipped,
         );
         for (const key of deletedKeys) {
+          if (!detached && LIVE_TOPOLOGY_KEYS.has(key)) continue;
           delete (config as unknown as Record<string, unknown>)[key];
         }
       }
@@ -537,15 +555,23 @@ export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
         }
       }
     }
-    const provenanceProjection = projectConfigRebaseProvenance(config);
+    const desired = persistedSnapshot && !detachedConfigSnapshots.has(config)
+      ? projectLiveTopology(config, persistedSnapshot, reconcileConfigRecord) : config;
+    const durableProjection = { ...desired, configRebaseProvenance: projectConfigRebaseProvenance(config).configRebaseProvenance };
+    for (const key of diskDeletedKeys) {
+      delete (durableProjection as unknown as Record<string, unknown>)[key];
+    }
+    if (diskDeletedKeys.size) durableProjection.configRebaseProvenance = { version: 1,
+      deletedTopLevelKeys: [...new Set([...configRebaseDeletionKeys(durableProjection), ...diskDeletedKeys])].sort() };
+    const provenanceProjection = projectConfigRebaseProvenance(durableProjection);
     const projectedConfig = projectCustomModelCatalogMigration(
       onDisk,
-      config,
+      durableProjection,
     );
     if (provenanceProjection.configRebaseProvenance === undefined) delete projectedConfig.configRebaseProvenance;
     else projectedConfig.configRebaseProvenance = provenanceProjection.configRebaseProvenance;
-    const persistedBinding = bindingBaseline && onDisk
-      ? readPersistedServerBinding(onDisk, bindingBaseline)
+    const persistedBinding = (bindingBaseline || diskDeletedKeys.has("hostname")) && onDisk
+      ? readPersistedServerBinding(onDisk, bindingBaseline ?? { port: config.port, hostname: config.hostname })
       : bindingBaseline;
     if (persistedBinding) {
       const persistedConfig: OcxConfig = { ...projectedConfig, port: persistedBinding.port };
@@ -557,6 +583,7 @@ export function saveConfigPreservingClaudeCode(config: OcxConfig): void {
       persist(projectedConfig);
     }
     adoptCustomModelCatalogMigration(config, projectedConfig);
+    captureLiveTopologyBaseline(config);
     if (claudeCodeBaseline.has(config)) {
       claudeCodeBaseline.set(config, structuredClone(config.claudeCode));
     }

package/src/config/live-topology.ts

@@ -0,0 +1,29 @@
+import type { OcxConfig } from "../types";
+
+export const LIVE_TOPOLOGY_KEYS = new Set(["hostname", "port", "runtimeRole", "hub", "client", "unauthenticatedLoopbackListener"]);
+const baselines = new WeakMap<OcxConfig, Record<string, unknown>>();
+
+function snapshot(config: OcxConfig): Record<string, unknown> {
+  const record = config as unknown as Record<string, unknown>;
+  return Object.fromEntries([...LIVE_TOPOLOGY_KEYS].filter(key => Object.hasOwn(record, key))
+    .map(key => [key, structuredClone(record[key])]));
+}
+
+/** Track actual active values independently of the desired config last persisted. */
+export function captureLiveTopologyBaseline(config: OcxConfig): void {
+  baselines.set(config, snapshot(config));
+}
+
+/** Merge desired next-start topology without mutating the active listener/role objects. */
+export function projectLiveTopology(
+  config: OcxConfig, persisted: OcxConfig,
+  mergeRecord: (live: Record<string, unknown>, baseline: Record<string, unknown>, disk: Record<string, unknown>, skipped: ReadonlySet<string>) => void,
+): OcxConfig {
+  const projected = { ...config, ...snapshot(config) } as unknown as Record<string, unknown>;
+  const baseline = baselines.get(config) ?? snapshot(config);
+  const disk = persisted as unknown as Record<string, unknown>;
+  const skipped = new Set([...Object.keys(projected), ...Object.keys(baseline), ...Object.keys(disk)]
+    .filter(key => !LIVE_TOPOLOGY_KEYS.has(key)));
+  mergeRecord(projected, baseline, disk, skipped);
+  return projected as unknown as OcxConfig;
+}

package/src/config/load-degrade.ts

@@ -3,6 +3,7 @@ import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { compactionRecoveryConfigError } from "./schema/compaction-recovery";
+import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import {
@@ -16,6 +17,7 @@ import {
 } from "./provider-validation";
 import { UPSTREAM_HOST_CIRCUIT_MAX_THRESHOLD } from "../codex/upstream-host-health";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
+import { isPassiveRead } from "../lib/passive-read";
 import { redactSecretString } from "../lib/redact";
 import { isValidProviderName } from "./provider-name";
 import { MODEL_ALIAS_PATTERN } from "../providers/default-aliases";
@@ -49,10 +51,13 @@ import {
 import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict } from "./warn-memo";
 
 export function hardenExistingSecret(path: string): void {
-  if (existsSync(path)) {
-    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  if (existsSync(path) && !isPassiveRead()) {
     if (process.platform === "win32") {
+      // Preserve the ACL helper's metadata observation across reads. Windows chmod does
+      // not establish a private DACL and can invalidate that observation before every load.
       hardenSecretPath(path, { required: false });
+    } else {
+      try { chmodSync(path, 0o600); } catch { /* best-effort */ }
     }
   }
 }
@@ -128,6 +133,7 @@ export function warnDegradedCompactionRouting(rawParsed: unknown, validated: Ocx
 export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
   setCodexWsReuseAcrossTurns(validated.codexWsReuseAcrossTurns === true);
   if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️  invalid compactionRecovery disabled; the original compaction failure is preserved");
+  if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
   if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️  invalid blockedModelRedirects ignored; provider routing remains available");
   const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
   if (chatgptDesktop) console.warn(`⚠️  config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);

package/src/config/paths.ts

@@ -3,6 +3,8 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { flushWindowsSecretAclReapsBeforeRemoval, hardenSecretDirAsync, windowsSecretAclApplies } from "../lib/windows-secret-acl";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { isPassiveRead } from "../lib/passive-read";
+import { trackBackgroundWork } from "../lib/background-work";
 
 /**
  * Expand a leading `~` in user-supplied paths without interpreting shell
@@ -29,22 +31,30 @@ export function getConfigPath(): string {
 }
 
 export function hardenConfigDir(): void {
+  // A passive read (a Remote Link Child's, #6959) repairs nothing on this machine.
+  if (isPassiveRead()) return;
   const dir = getConfigDir();
   // The guard runs before any mutation: refusing after chmod/ACL would already
   // have changed the protected directory used by the test-home boundary.
   assertNotRealHomeUnderTest(dir);
   if (!existsSync(dir)) return;
-  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  // Windows privacy is enforced by NTFS ACLs. chmod only changes DOS attributes there;
+  // doing it before the ACL lookup can invalidate its ctime-based successful observation.
+  if (!windowsSecretAclApplies()) {
+    try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  }
   if (windowsSecretAclApplies() && !configDirHardeningFlights.has(dir)) {
     // This is an optional read-path harden. Waiting synchronously here used to stop the Bun
     // event loop (including /healthz) for the full icacls timeout. Required mutation paths keep
     // their own awaited/fail-closed hardening; ordinary config reads only start one soft flight.
-    const flight = hardenSecretDirAsync(dir, { required: false })
+    // Tracked: icacls holds the directory open, and a config write or removal that lands on
+    // it before the child exits fails with a sharing violation on Windows.
+    const flight = trackBackgroundWork("config-dir-acl-harden", hardenSecretDirAsync(dir, { required: false })
       .then(() => undefined)
       .catch(() => undefined)
       .finally(() => {
         if (configDirHardeningFlights.get(dir) === flight) configDirHardeningFlights.delete(dir);
-      });
+      }));
     configDirHardeningFlights.set(dir, flight);
   }
 }

package/src/config/salvage.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import * as z from "zod/v4";
 import { CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR } from "../codex/account-namespace-match";
 import { redactSecretString } from "../lib/redact";
+import { isPassiveRead } from "../lib/passive-read";
 import { hasWarnedConfigFallback, markWarnedConfigFallback } from "./warn-memo";
 import { configSchema } from "./schema/config-schema";
 import type { OcxConfig } from "../types";
@@ -232,7 +233,8 @@ export function warnAndBackupInvalidConfig(configPath: string, error: unknown):
 }
 
 export function backupInvalidConfig(configPath: string): string | null {
-  if (!existsSync(configPath)) return null;
+  // A passive read leaves a malformed file for the Home's own load to back up (#6959).
+  if (!existsSync(configPath) || isPassiveRead()) return null;
   const backupPath = `${configPath}.invalid-${new Date().toISOString().replace(/[:.]/g, "-")}`;
   try {
     copyFileSync(configPath, backupPath);

package/src/config/schema/config-schema.ts

@@ -2,6 +2,7 @@ import { MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT } from "../../codex/quota-types";
 import * as z from "zod/v4";
 import { anthropicAccountPoolSchema } from "./anthropic-account-pool";
 import { compactionRecoverySchema } from "./compaction-recovery";
+import { desktopCompatibilitySchema } from "./desktop-compatibility";
 import { blockedModelRedirectsSchema } from "./blocked-model-redirects";
 import {
   agentTaskRecoverySchema,
@@ -83,6 +84,7 @@ export const protocolConfigSchema = z.object({
     managedMessagesNative: z.boolean().optional(),
     managedMessagesNativeOAuth: z.boolean().optional(),
     directEncoders: z.boolean().optional(),
+    antigravityDirect: z.boolean().optional(),
     shadowPlan: z.boolean().optional(),
   }).strict().optional(),
 }).strict();
@@ -105,6 +107,8 @@ export const configSchema = z.object({
   skills: skillsConfigSchema.optional().catch(undefined),
   // Malformed hand edits disable this opt-in exporter. Live writes reject them in diagnostics.ts.
   metricsExport: z.object({ enabled: z.boolean().optional() }).strict().optional().catch(undefined),
+  // Same contract as metricsExport: a malformed hand edit leaves recovery off; live writes reject it.
+  serviceHealthRecovery: z.object({ enabled: z.boolean().optional() }).strict().optional().catch(undefined),
   // Kept raw on purpose: `.catch(undefined)` would turn a mistyped `enabled` into "inherit",
   // which can reopen a surface the operator meant to close. src/protocols/settings.ts parses it
   // and fails closed instead.
@@ -122,6 +126,7 @@ export const configSchema = z.object({
         managedMessagesNative: false,
         managedMessagesNativeOAuth: false,
         directEncoders: fields.directEncoders === true,
+        antigravityDirect: fields.antigravityDirect === true,
         shadowPlan: fields.shadowPlan === true,
       },
     };
@@ -188,6 +193,7 @@ export const configSchema = z.object({
   modelPinnedEfforts: modelPinnedEffortsSchema.optional(),
   compactionRouting: compactionRoutingSchema.optional().catch(undefined),
   compactionRecovery: compactionRecoverySchema.optional().catch(undefined),
+  desktopCompatibility: desktopCompatibilitySchema.optional().catch(undefined),
   // A hand-edited malformed phase disables only that phase instead of rejecting
   // providers/apiKeys, matching the load-time degradation notice; the management write
   // boundary (validateConfigCandidate) still refuses the bad value through the shared,
@@ -215,6 +221,8 @@ export const configSchema = z.object({
     short: z.number().int().min(MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT).max(100).optional().catch(undefined),
     long: z.number().int().min(MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT).max(100).optional().catch(undefined),
   }).optional().catch(undefined),
+  // #2999: a malformed hand edit falls back to auto detection rather than rejecting the config.
+  nativeMainRefresh: z.enum(["codex", "opencodex"]).optional().catch(undefined),
   // Future versions remain opaque through passthrough-compatible whole-config saves.
   // Only version 1 grants deletion authority in the rebase path.
   configRebaseProvenance: z.unknown().optional(),
@@ -676,6 +684,17 @@ export const configSchema = z.object({
         message: reasoningSummaryDeliveryError,
       });
     }
+    const minMaxOutputError = positiveIntegerConfigError(
+      (provider as { minMaxOutputTokens?: unknown }).minMaxOutputTokens,
+      "minMaxOutputTokens",
+    );
+    if (minMaxOutputError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", redactSecretString(name), "minMaxOutputTokens"],
+        message: minMaxOutputError,
+      });
+    }
     const defaultMaxOutputError = positiveIntegerConfigError(
       (provider as { defaultMaxOutputTokens?: unknown }).defaultMaxOutputTokens,
       "defaultMaxOutputTokens",

package/src/config/schema/desktop-compatibility.ts

@@ -0,0 +1,9 @@
+import * as z from "zod/v4";
+/** Startup resumes observation only. Certificate trust, app launch and Apply are never saved here. */
+export const desktopCompatibilitySchema = z.object({ startOnProxyStart: z.boolean() }).strict();
+export function desktopCompatibilityConfigError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const setting = (value as Record<string, unknown>).desktopCompatibility;
+  return setting === undefined || desktopCompatibilitySchema.safeParse(setting).success
+    ? null : "schema_invalid: desktopCompatibility: requires only boolean startOnProxyStart";
+}

package/src/config/schema/leaf-validators.ts

@@ -331,6 +331,7 @@ export const providerConfigSchema = z.object({
   responseTierAuthoritative: z.boolean().optional(),
   fastEnabled: z.boolean().optional(),
   supportsServiceTier: z.boolean().optional(),
+  inferContextWindow: z.boolean().optional(),
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
   modelSuppressSyntheticMax: z.record(z.string().min(1), z.boolean()).optional(),
   preserveResponsesReasoningContent: z.boolean().optional(),