@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/codex/shim-state-file.ts

@@ -1,21 +1,31 @@
 import {
   closeSync,
+  constants,
   existsSync,
   fstatSync,
   lstatSync,
   mkdirSync,
   openSync,
   readSync,
+  renameSync,
+  unlinkSync,
   writeFileSync,
   type Stats,
 } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { getConfigDir } from "../config";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 export const CODEX_SHIM_STATE_MAX_BYTES = 1024 * 1024;
 
 interface ShimState {
+  schema?: 2;
+  mode?: "path-overlay";
+  launcherPath?: string;
+  wrapperIdentity?: OverlayIdentity;
+  envIdentity?: OverlayIdentity;
+  transactionId?: string;
   platform: NodeJS.Platform;
   wrapperPath: string;
   originalPath: string;
@@ -23,6 +33,51 @@ interface ShimState {
   wrappers?: ShimFileState[];
 }
 
+export interface OverlayIdentity { dev: number; ino: number }
+export interface OverlayState {
+  schema: 2;
+  mode: "path-overlay";
+  platform: NodeJS.Platform;
+  wrapperPath: string;
+  launcherPath: string;
+  // Older schema-2 records remain readable, but absent identities confer no mutation authority.
+  wrapperIdentity?: OverlayIdentity;
+  envIdentity?: OverlayIdentity;
+  transactionId?: string;
+}
+
+export function decodeOverlayState(value: unknown, configDir: string): OverlayState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const state = value as Record<string, unknown>;
+  const platforms = ["aix", "darwin", "freebsd", "linux", "openbsd", "sunos", "android", "netbsd", "haiku", "cygwin"];
+  const validPath = (path: unknown): path is string => typeof path === "string" && isAbsolute(path) && !/[\x00-\x1f\x7f]/.test(path);
+  if (state.schema !== 2 || state.mode !== "path-overlay" || !platforms.includes(String(state.platform))
+    || !validPath(configDir) || !validPath(state.wrapperPath) || !validPath(state.launcherPath)
+    || state.wrapperPath !== join(resolve(configDir), "bin", "codex")
+    || dirname(state.wrapperPath).includes(":") || resolve(state.launcherPath) === state.wrapperPath) return null;
+  for (const field of ["originalPath", "backupPath", "realPath"]) {
+    if (state[field] !== undefined && state[field] !== state.launcherPath) return null;
+  }
+  if (state.preserveOnly !== undefined && state.preserveOnly !== false) return null;
+  if (state.wrappers !== undefined) {
+    if (!Array.isArray(state.wrappers) || state.wrappers.length !== 1) return null;
+    const file = state.wrappers[0];
+    if (!file || typeof file !== "object" || file.wrapperPath !== state.wrapperPath
+      || file.originalPath !== state.launcherPath || file.backupPath !== state.launcherPath
+      || (file.realPath !== undefined && file.realPath !== state.launcherPath) || file.preserveOnly) return null;
+  }
+  for (const key of ["wrapperIdentity", "envIdentity"]) {
+    const id = state[key] as Partial<OverlayIdentity> | undefined;
+    if (id !== undefined && (!id || !Number.isSafeInteger(id.dev) || !Number.isSafeInteger(id.ino))) return null;
+  }
+  if (state.transactionId !== undefined && (typeof state.transactionId !== "string" || !/^[a-f0-9-]{36}$/.test(state.transactionId))) return null;
+  return state as unknown as OverlayState;
+}
+
+export function readOverlayState(configDir = getConfigDir()): OverlayState | null {
+  return decodeOverlayState(readStateResult(join(configDir, "codex-shim.json")).state, configDir);
+}
+
 interface ShimFileState {
   wrapperPath: string;
   originalPath: string;
@@ -43,7 +98,7 @@ function fileErrorCode(error: unknown): string | undefined {
     : undefined;
 }
 
-function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer; content: string } | { warning: string } | null {
+function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer; content: string; stat: Stats } | { warning: string } | null {
   let lexicalBefore: Stats;
   try {
     lexicalBefore = lstatSync(path);
@@ -56,7 +111,7 @@ function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer
   }
   let fd: number;
   try {
-    fd = openSync(path, "r");
+    fd = openSync(path, process.platform === "win32" ? "r" : constants.O_RDONLY | constants.O_NONBLOCK);
   } catch (error) {
     if (fileErrorCode(error) === "ENOENT") return null;
     return { warning: `Codex shim state could not be opened as a regular file at ${path}.` };
@@ -87,11 +142,16 @@ function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer
     }
     if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
       || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+      || before.mode !== after.mode || before.uid !== after.uid
       || lexicalBefore.dev !== before.dev || lexicalBefore.ino !== before.ino
-      || lexicalAfter.isSymbolicLink() || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino) {
+      || lexicalBefore.mode !== before.mode || lexicalBefore.uid !== before.uid
+      || lexicalBefore.size !== before.size || lexicalBefore.mtimeMs !== before.mtimeMs || lexicalBefore.ctimeMs !== before.ctimeMs
+      || !lexicalAfter.isFile() || lexicalAfter.isSymbolicLink() || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino
+      || lexicalAfter.mode !== after.mode || lexicalAfter.uid !== after.uid
+      || lexicalAfter.size !== after.size || lexicalAfter.mtimeMs !== after.mtimeMs || lexicalAfter.ctimeMs !== after.ctimeMs) {
       return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
     }
-    return { bytes: buffer, content: buffer.toString("utf8") };
+    return { bytes: buffer, content: buffer.toString("utf8"), stat: after };
   } finally {
     closeSync(fd);
   }
@@ -105,6 +165,15 @@ function readStateResult(path = statePath()): ShimStateReadResult {
     const value = JSON.parse(bounded.content) as unknown;
     if (!value || typeof value !== "object") return { state: null, present: true };
     const state = value as Record<string, unknown>;
+    if (state.mode !== undefined || state.schema !== undefined) {
+      // Legacy records stay readable; private overlay authority requires safe ownership.
+      // Non-writable mode drift is readable for opt-in repair, never a healthy installation.
+      if (process.platform !== "win32" && (bounded.stat.uid !== process.getuid?.() || (bounded.stat.mode & 0o022))) {
+        return { state: null, present: true, warning: "Private Codex shim state is not owned by the current user or is group/world writable; preserving artifacts. Remove the private files manually before reinstalling." };
+      }
+      const overlay = decodeOverlayState(value, dirname(path));
+      return { state: overlay ? { ...overlay, originalPath: overlay.launcherPath, backupPath: overlay.launcherPath } : null, present: true };
+    }
     if (typeof state.platform !== "string") return { state: null, present: true };
     const validFile = (item: unknown): item is ShimFileState => {
       if (!item || typeof item !== "object") return false;
@@ -134,18 +203,35 @@ function statePath(): string {
   return join(getConfigDir(), "codex-shim.json");
 }
 
-function writeState(state: ShimState): void {
+function writeState(state: ShimState | OverlayState): void {
   const path = statePath();
   recordOwnedConfigPath(getConfigDir(), path);
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  if (state.mode === "path-overlay") {
+    if (!decodeOverlayState(state, getConfigDir()) || !state.wrapperIdentity || !state.envIdentity) {
+      throw new Error("Invalid Codex overlay state: recorded ownership identities are required");
+    }
+    const staged = `${path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(staged, JSON.stringify(state, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+      renameSync(staged, path);
+    } finally {
+      try { unlinkSync(staged); } catch { /* committed or absent */ }
+    }
+    return;
+  }
   writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
 }
 
 function stateFiles(state: ShimState): ShimFileState[] {
+  if (state.mode === "path-overlay" && state.launcherPath) return [{
+    wrapperPath: state.wrapperPath, originalPath: state.launcherPath,
+    backupPath: state.launcherPath, realPath: state.launcherPath,
+  }];
   return state.wrappers?.length
     ? state.wrappers
     : [{ wrapperPath: state.wrapperPath, originalPath: state.originalPath, backupPath: state.backupPath }];
 }
 
 export type { ShimState, ShimFileState };
-export { fileErrorCode, readStateResult, readState, statePath, writeState, stateFiles };
+export { readBoundedRegularFile, fileErrorCode, readStateResult, readState, statePath, writeState, stateFiles };

package/src/codex/shim.ts

@@ -55,6 +55,8 @@ import {
 import { tryAcquireShimRestoreLock } from "./shim-restore-lock";
 import {
   isWindowsInteropDir,
+  isExecutableCodexCandidate,
+  inspectShimFile,
   realIsDirectory,
   resolveStableFnmCodexPath,
   type CodexPathScanDeps,
@@ -69,6 +71,10 @@ export type { CodexPathScanDeps } from "./shim-path-resolution";
 export { isWindowsInteropDir } from "./shim-path-resolution";
 export { isLocalAbsoluteInspectionPath, inspectCodexShimBackingForCommand } from "./shim-inspect";
 
+import { isShim, diagnoseCodexShim } from "./shim-diagnostics";
+import { installUnixOverlay, autoRestoreUnixOverlay, uninstallUnixCodexShim, overlayPaths } from "./shim-overlay";
+export { diagnoseCodexShim, codexShimStatus, type CodexShimDiagnostic } from "./shim-diagnostics";
+
 export const CODEX_SHIM_REPLACEMENT_STABLE_MS = 100;
 
 let lastShimDiscoveryError: string | null = null;
@@ -114,31 +120,12 @@ function commandNames(name: string): string[] {
   return [name, ...exts.flatMap(ext => [`${name}${ext.toLowerCase()}`, `${name}${ext.toUpperCase()}`])];
 }
 
-function isShim(path: string): boolean {
-  try {
-    return readFileSync(path, "utf8").includes(SHIM_MARKER);
-  } catch {
-    return false;
-  }
-}
-
-function isHealthyShim(path: string, platform: NodeJS.Platform): boolean {
-  try {
-    const content = readFileSync(path, "utf8");
-    if (content.length < 180 || !content.includes(SHIM_MARKER) || !content.includes("ensure")) return false;
-    if (platform !== "win32" && !content.includes(UNIX_SHIM_REVISION_MARKER)) return false;
-    if (platform !== "win32" && (lstatSync(path).mode & 0o111) === 0) return false;
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export function findCodexOnPath(deps: CodexPathScanDeps = {}): string | null {
   lastShimDiscoveryError = null;
   const exists = deps.exists ?? existsSync;
-  const shimFile = deps.isShimFile ?? isShim;
+  const shimFile = deps.isShimFile ?? (process.platform === "win32" ? isShim : (path: string) => inspectShimFile(path) !== false);
   const isDir = deps.isDirectory ?? realIsDirectory;
+  const eligible = deps.executableEligible ?? (deps.exists ? () => true : isExecutableCodexCandidate);
   const wsl = deps.wsl ?? (process.platform === "linux" && isWslRuntime());
   const usePosix = deps.posixPaths ?? (wsl || process.platform !== "win32");
   // The injected path flavour governs join and separator alike; host-native `join` and
@@ -166,7 +153,9 @@ export function findCodexOnPath(deps: CodexPathScanDeps = {}): string | null {
     const names = isWindowsInteropDir(dir, automountRoot) ? interopNames : commandNames("codex");
     for (const name of names) {
       const path = joinPath(dir, name);
-      if (!exists(path) || shimFile(path)) continue;
+      if (!exists(path)) continue;
+      if (usePosix && (path === overlayPaths().wrapper || !eligible(path))) continue;
+      if (shimFile(path)) continue;
       if (!isDir(path)) {
         const resolved = discoveredCodexPath(path, usePosix, deps.realpath);
         if (resolved !== null) return resolved;
@@ -1072,7 +1061,8 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
   };
 }
 
-export function installCodexShim(): { installed: boolean; message: string } {
+export function installCodexShim(): { installed: boolean; message: string; refused?: boolean; runnable?: boolean } {
+  if (process.platform !== "win32") return installUnixOverlay(findCodexOnPath);
   return installCodexShimInternal({ allowFreshInstall: true });
 }
 
@@ -1086,6 +1076,7 @@ export function autoRestoreCodexShim(options: {
   /** Narrow deterministic race seam for the guarded transaction tests. */
   beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
 }): CodexShimAutoRestoreResult {
+  if (process.platform !== "win32") return autoRestoreUnixOverlay(options);
   const stateRead = readStateResult();
   const state = stateRead.state;
   if (!state) {
@@ -1181,6 +1172,7 @@ export function autoRestoreCodexShim(options: {
 }
 
 export function uninstallCodexShim(): { removed: boolean; message: string } {
+  if (process.platform !== "win32") return uninstallUnixCodexShim();
   const state = readState();
   if (!state) return { removed: false, message: "Codex autostart shim is not installed." };
   const files = stateFiles(state);
@@ -1199,48 +1191,3 @@ export function uninstallCodexShim(): { removed: boolean; message: string } {
 export function isCodexShimInstalled(): boolean {
   return diagnoseCodexShim().installed;
 }
-
-export interface CodexShimDiagnostic {
-  installed: boolean;
-  healthy: boolean;
-  summary: string;
-}
-
-/** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */
-export function diagnoseCodexShim(): CodexShimDiagnostic {
-  const state = readState();
-  if (!state) {
-    if (existsSync(statePath())) {
-      return {
-        installed: true,
-        healthy: false,
-        summary: `Codex autostart shim state is invalid or corrupt at ${statePath()}. Reinstall or remove the shim.`,
-      };
-    }
-    return {
-      installed: false,
-      healthy: false,
-      summary: "Codex autostart shim is not installed.",
-    };
-  }
-  const files = stateFiles(state);
-  const healthy = files.length > 0 && files.every(file => file.preserveOnly
-    ? existsSync(file.backupPath) && !existsSync(file.originalPath)
-    : existsSync(file.wrapperPath)
-      && (existsSync(file.backupPath) || (file.realPath ? existsSync(file.realPath) : false))
-      && isHealthyShim(file.wrapperPath, state.platform));
-  const summary = files.map(file => {
-    const wrapper = existsSync(file.wrapperPath)
-      ? isShim(file.wrapperPath)
-        ? "shim present"
-        : "present but not an opencodex shim"
-      : "missing";
-    const backup = existsSync(file.backupPath) ? "present" : "missing";
-    return `Codex autostart shim: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
-  }).join("\n");
-  return { installed: true, healthy, summary };
-}
-
-export function codexShimStatus(): string {
-  return diagnoseCodexShim().summary;
-}

package/src/codex/sync.ts

@@ -1,4 +1,5 @@
 import { currentExternalCodexModelProvider, injectCodexConfig } from "./inject";
+import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE, unbackedRoutedRemovalMessage } from "./catalog/routed-removal";
 import { printProjectCodexConfigWarnings, groupProjectCodexConfigWarningsByPath, type ProjectCodexConfigWarning } from "./project-config-warnings";
 import { refreshCodexModelCatalog } from "./refresh";
 import { applyProxyEnv, loadConfig } from "../config";
@@ -35,8 +36,8 @@ export interface CodexSyncResult {
   cacheSynced: boolean;
   /**
    * Whether the catalog owner committed a validated catalog or refused the
-   * refresh. Only a `catalog-only` result carries it; `ok` already answers the
-   * question for callers that do not care which half refused.
+   * refresh. Available on applied and catalog-only results; `ok` on applied
+   * describes config injection, so callers must also inspect catalog evidence.
    */
   refreshOutcome?: "committed" | "refused";
   message: string;
@@ -262,17 +263,27 @@ export async function syncModelsToCodex(
   let cacheSynced = false;
   let warning: string | undefined;
   let comboOmissions: ComboCatalogOmission[] = [];
+  let refreshOutcome: "committed" | "refused" | undefined;
 
   try {
     const cat = await deps.refreshCodexModelCatalog(config);
     added = cat.added;
+    refreshOutcome = cat.refreshOutcome;
     catalogExists = cat.catalogExists;
     catalogWritten = cat.catalogWritten;
     cacheSynced = cat.cacheSynced;
     catalogPathForInjection = cat.catalogExists ? cat.path : null;
     catalogPath = catalogPathForInjection;
     comboOmissions = cat.comboOmissions ?? [];
-    if (cat.added > 0) {
+    if (cat.skippedReason === "unbacked_routed_removal" || cat.skippedReason === "foreign_owner" || cat.skippedReason === "owner_unknown") {
+      // The catalog on disk is kept as it was; say so, or a native-only refresh refused for safety
+      // reads exactly like a successful sync (#6529).
+      warning = cat.skippedReason === "foreign_owner"
+        ? FOREIGN_CODEX_HOME_OWNER_MESSAGE
+        : cat.skippedReason === "owner_unknown" ? UNKNOWN_CODEX_HOME_OWNER_MESSAGE
+        : unbackedRoutedRemovalMessage(cat.protectedRoutedNamespaces ?? 1);
+      log?.error(`[opencodex] ${warning}`);
+    } else if (cat.added > 0) {
       log?.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
     } else if (!cat.catalogExists) {
       warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";
@@ -322,6 +333,7 @@ export async function syncModelsToCodex(
     status: "applied",
     ok: result.success,
     added,
+    ...(refreshOutcome ? { refreshOutcome } : {}),
     catalogPath,
     catalogExists,
     catalogWritten,
@@ -370,7 +382,15 @@ async function refreshCatalogForSync(
     cacheSynced = cat.cacheSynced;
     catalogPath = cat.catalogExists ? cat.path : null;
     comboOmissions = cat.comboOmissions ?? [];
-    if (cat.added > 0) {
+    if (cat.skippedReason === "unbacked_routed_removal" || cat.skippedReason === "foreign_owner" || cat.skippedReason === "owner_unknown") {
+      // The catalog on disk is kept as it was; say so, or a native-only refresh refused for safety
+      // reads exactly like a successful sync (#6529).
+      warning = cat.skippedReason === "foreign_owner"
+        ? FOREIGN_CODEX_HOME_OWNER_MESSAGE
+        : cat.skippedReason === "owner_unknown" ? UNKNOWN_CODEX_HOME_OWNER_MESSAGE
+        : unbackedRoutedRemovalMessage(cat.protectedRoutedNamespaces ?? 1);
+      log?.error(`[opencodex] ${warning}`);
+    } else if (cat.added > 0) {
       log?.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
     } else if (!cat.catalogExists) {
       warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";

package/src/combos/failover.ts

@@ -11,6 +11,7 @@ import {
 
 interface TargetCooldown {
   cooldownUntil: number;
+  status?: number;
 }
 
 const DEFAULT_COOLDOWN_MS = 60_000;
@@ -195,6 +196,23 @@ export function remainingComboCooldownMs(comboId: string, now = Date.now()): num
   return soonest;
 }
 
+/** Snapshot active quota cooldowns without inspecting request eligibility or changing state. */
+export function snapshotComboQuotaCooldowns<T extends Pick<OcxComboTarget, "provider" | "model">>(
+  comboId: string,
+  targets: Iterable<T>,
+  now = Date.now(),
+): Array<{ target: T; cooldownUntil: number }> {
+  const snapshot: Array<{ target: T; cooldownUntil: number }> = [];
+  for (const target of targets) {
+    const key = cooldownMapKey(comboId, target);
+    const cooldown = targetCooldowns.get(key);
+    if (!cooldown || cooldown.cooldownUntil <= now) continue;
+    if (cooldown.status !== 429 && cooldown.status !== 402) continue;
+    snapshot.push({ target, cooldownUntil: cooldown.cooldownUntil });
+  }
+  return snapshot;
+}
+
 export function comboCooldownRetryAfterSeconds(comboId: string, now = Date.now()): string | undefined {
   const remainingMs = remainingComboCooldownMs(comboId, now);
   if (remainingMs === undefined) return undefined;
@@ -244,6 +262,7 @@ export function coolComboTarget(
   targetCooldowns.set(cooldownMapKey(comboId, target), {
     // Local fallbacks are capped at ten minutes; explicit server delays at one day.
     cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
+    status: options?.status,
   });
   sweepExpiredOnWrite(now);
   return true;

package/src/combos/index.ts

@@ -28,6 +28,7 @@ export {
   pickComboTarget,
   pickComboTargetWithWait,
   quotaInactiveReason,
+  snapshotComboQuotaCooldowns,
   tryPickComboModel,
   UnknownComboError,
   type ComboPick,

package/src/combos/resolve.ts

@@ -6,6 +6,7 @@ import {
   coolComboTarget,
   earliestComboCooldown,
   isComboTargetInCooldown,
+  snapshotComboQuotaCooldowns as snapshotTargetQuotaCooldowns,
   type ComboFailureCooldownScope,
 } from "./failover";
 import { quotaResetRemainingMs } from "./reset-window";
@@ -67,6 +68,17 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now:
   return !cachedProviderQuotaIsExhausted(getCachedProviderRoutingQuota(target.provider, provider, now), now, target.model);
 }
 
+/** Capture usable providers' quota cooldowns; request eligibility is deferred to exhaustion. */
+export function snapshotComboQuotaCooldowns(
+  config: OcxConfig,
+  comboId: string,
+  now = Date.now(),
+): Array<{ target: NormalizedComboTarget; cooldownUntil: number }> {
+  const targets = getCombo(config, comboId)?.targets.filter(target =>
+    targetProviderIsUsable(config, target, now)) ?? [];
+  return snapshotTargetQuotaCooldowns(comboId, targets, now);
+}
+
 function quotaWindowExhausted(percent: number | undefined, resetAt: number | undefined, now: number): boolean {
   if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 100) return false;
   return typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt > now;

package/src/config/atomic-write.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
-import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { assertNotRealCodexHomeUnderTest, assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import {
   forgetEphemeralSecretPath,
   hardenSecretPath,
@@ -114,14 +114,19 @@ export function resolveWriteTarget(path: string): string {
 }
 
 function assertResolvedTargetAllowed(path: string, target: string): void {
+  // Codex-home files (catalog, models cache, journal, config.toml, profile) are addressed through
+  // CODEX_HOME, which falls back to os.homedir() when a test's teardown deletes it, and os.homedir()
+  // ignores HOME. That is how test runs rewrote the real catalog (#6529), so every atomic write
+  // whose directory is the real Codex home is refused under an armed test process.
+  let realParent: string | null = null;
+  try {
+    realParent = realpathSync(dirname(target));
+  } catch {
+    realParent = null;
+  }
+  assertNotRealCodexHomeUnderTest(realParent ?? dirname(target));
   if (target === path) {
-    let realParent: string;
-    try {
-      realParent = realpathSync(dirname(target));
-    } catch {
-      return;
-    }
-    if (realParent !== dirname(target)) assertNotRealHomeUnderTest(realParent);
+    if (realParent !== null && realParent !== dirname(target)) assertNotRealHomeUnderTest(realParent);
     return;
   }
   assertNotRealHomeUnderTest(dirname(target));

package/src/config/diagnostics.ts

@@ -1,4 +1,5 @@
 import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
+import { protocolConfigSchema } from "./schema/config-schema";
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -66,6 +67,7 @@ import {
   runtimeRoleSchema,
   spendSchema,
   chatgptDesktopSchema,
+  chatgptDesktopConfigIssue,
   compactionRoutingSchema,
   skillsConfigSchema,
   memoryModelsSchema,
@@ -109,6 +111,8 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (normalized.chatgptDesktop?.appServerShim === true && process.platform !== "darwin") {
     warnings.push("chatgptDesktop.appServerShim is experimental and macOS only; ignored on this platform");
   }
+  const chatgptDesktopIssue = chatgptDesktopConfigIssue(rawParsed);
+  if (chatgptDesktopIssue) warnings.push(`${chatgptDesktopIssue}; the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
   warnings.push(...inheritedFastWireConflictProviderNames(normalized).map(inheritedFastWireConflictWarning));
   warnings.push(...degradedCodexAccountPriorityWarnings(rawParsed, normalized));
   warnings.push(...degradedListenerWarnings(rawParsed, normalized));
@@ -647,7 +651,19 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
   if (memoryModels !== undefined && !memoryModelsSchema.safeParse(memoryModels).success) {
     return { ok: false, error: "schema_invalid: memoryModels: requires a nonblank model and an optional declared reasoningEffort per configured phase, and no other fields" };
   }
-  const routeValue = (rawConfigRecord(value)?.anthropicAccountPool as Record<string, unknown> | undefined)?.routes;
+  const protocols = rawConfigRecord(value)?.protocols;
+  if (protocols !== undefined && !protocolConfigSchema.safeParse(protocols).success) {
+    return { ok: false, error: "schema_invalid: protocols: expected valid protocol policy and boolean rollout flags" };
+  }
+  const rawAnthropicPool = rawConfigRecord(value)?.anthropicAccountPool;
+  const anthropicPool = rawConfigRecord(rawAnthropicPool);
+  if (rawAnthropicPool !== undefined && !anthropicPool) {
+    return { ok: false, error: "schema_invalid: anthropicAccountPool: must be an object" };
+  }
+  if (anthropicPool && Object.hasOwn(anthropicPool, "nativeMessages") && typeof anthropicPool.nativeMessages !== "boolean") {
+    return { ok: false, error: "schema_invalid: anthropicAccountPool.nativeMessages: must be a boolean" };
+  }
+  const routeValue = anthropicPool?.routes;
   if (routeValue !== undefined) {
     const parsed = parseAnthropicModelRoutes(routeValue);
     if (!parsed.ok) return { ok: false, error: `schema_invalid: anthropicAccountPool.routes: ${parsed.error}` };
@@ -730,6 +746,8 @@ export function configDiagnosticsFromRaw(raw: string): ConfigDiagnostics {
     if (salvaged) {
       const config = normalizeApiKeyIds(salvaged.parsed);
       const warnings = degradedListenerWarnings(parsed, config);
+      const chatgptDesktopIssue = chatgptDesktopConfigIssue(parsed);
+      if (chatgptDesktopIssue) warnings.push(`${chatgptDesktopIssue}; the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
       return {
         config,
         source: "fallback",

package/src/config/load-degrade.ts

@@ -41,6 +41,7 @@ import {
   transientRetryOn5xxPolicySchema,
   runtimeRoleSchema,
   spendSchema,
+  chatgptDesktopConfigIssue,
 } from "./schema/leaf-validators";
 import { hasWarnedInheritedFastWireConflict, markWarnedInheritedFastWireConflict } from "./warn-memo";
 
@@ -124,6 +125,8 @@ export function warnDegradedCompactionRouting(rawParsed: unknown, validated: Ocx
 export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxConfig): void {
   if (compactionRecoveryConfigError(rawParsed)) console.warn("⚠️  invalid compactionRecovery disabled; the original compaction failure is preserved");
   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`);
   warnDegradedStreamMode(rawParsed, validated);
   warnDegradedCompactionRouting(rawParsed, validated);
   warnDegradedMemoryModels(rawParsed, validated);

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

@@ -0,0 +1,22 @@
+import * as z from "zod/v4";
+import { redactSecretString } from "../../lib/redact";
+
+/** Experimental macOS ChatGPT app-server shim; only a strict optional boolean is accepted. */
+export const chatgptDesktopSchema = z.object({ appServerShim: z.boolean().optional() }).strict();
+
+/**
+ * Why a present `chatgptDesktop` block fails the schema, or null when it is valid or absent. The
+ * read path degrades a failing block to absent, so the integration reads as off while the file
+ * still says `appServerShim: true`; this names the field so that is never silent. A leftover key
+ * from an older or ported config (for example `unblockSend`) is the usual cause.
+ */
+export function chatgptDesktopConfigIssue(rawParsed: unknown): string | null {
+  if (!rawParsed || typeof rawParsed !== "object" || Array.isArray(rawParsed)) return null;
+  const block = (rawParsed as Record<string, unknown>).chatgptDesktop;
+  if (block === undefined) return null;
+  const result = chatgptDesktopSchema.safeParse(block);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return redactSecretString(`chatgptDesktop${field ? `.${field}` : ""}: ${issue?.message ?? "invalid configuration"}`);
+}

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

@@ -74,6 +74,18 @@ import { parseDesktopProfile } from "../../claude/desktop-profile";
 import { isInterceptBindingId, isInterceptBindingRoute } from "../../claude/intercept/model-bindings";
 import { DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES, MAX_APP_OWNED_MEMORY_BUDGET_MB, MIN_APP_OWNED_MEMORY_BUDGET_MB } from "../../lib/app-owned-memory";
 
+/** Strict write contract; file-load recovery is applied only by the enclosing schema. */
+export const protocolConfigSchema = z.object({
+  unrepresentable: z.enum(["legacy", "reject"]).optional(),
+  rollout: z.object({
+    nativeChatCombos: z.boolean().optional(),
+    managedMessagesNative: z.boolean().optional(),
+    managedMessagesNativeOAuth: z.boolean().optional(),
+    directEncoders: z.boolean().optional(),
+    shadowPlan: z.boolean().optional(),
+  }).strict().optional(),
+}).strict();
+
 export const configSchema = z.object({
   chatgptDesktop: chatgptDesktopSchema.optional().catch(undefined),
   codexNativeSteering: z.boolean().optional().catch(false),
@@ -96,18 +108,23 @@ export const configSchema = z.object({
   // which can reopen a surface the operator meant to close. src/protocols/settings.ts parses it
   // and fails closed instead.
   apiSurfaces: z.unknown().optional(),
-  // Every protocol default is the conservative one (legacy policy, rollout off), so a malformed
-  // block dropping to undefined cannot widen behavior.
-  protocols: z.object({
-    unrepresentable: z.enum(["legacy", "reject"]).optional(),
-    rollout: z.object({
-      nativeChatCombos: z.boolean().optional(),
-      managedMessagesNative: z.boolean().optional(),
-      managedMessagesNativeOAuth: z.boolean().optional(),
-      directEncoders: z.boolean().optional(),
-      shadowPlan: z.boolean().optional(),
-    }).strict().optional(),
-  }).strict().optional().catch(undefined),
+  // Keep malformed native policy disabled even when an enabled pool supplies defaults.
+  protocols: protocolConfigSchema.optional().catch(ctx => {
+    const raw = ctx.input;
+    const protocols = raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+    const rollout = protocols.rollout;
+    const fields = rollout && typeof rollout === "object" && !Array.isArray(rollout) ? rollout as Record<string, unknown> : {};
+    return {
+      unrepresentable: protocols.unrepresentable === "reject" ? "reject" as const : "legacy" as const,
+      rollout: {
+        nativeChatCombos: fields.nativeChatCombos === true,
+        managedMessagesNative: false,
+        managedMessagesNativeOAuth: false,
+        directEncoders: fields.directEncoders === true,
+        shadowPlan: fields.shadowPlan === true,
+      },
+    };
+  }),
   // A malformed present client block must remain diagnosable from raw config and
   // fail closed through src/client/state.ts; unrelated provider state still loads.
   client: clientConnectionSchema.optional().catch(undefined),
@@ -308,8 +325,9 @@ export const configSchema = z.object({
   // path below and wipe providers/pool accounts. Warning emitted in loadConfig.
   streamMode: z.enum(["auto", "legacy-tee", "eager-relay"]).optional().catch(undefined),
   blockedModelRedirects: blockedModelRedirectsSchema.optional().catch(undefined),
-  // Preserve malformed hand edits for a local routing error; candidate writes use the shared parser.
-  anthropicAccountPool: z.unknown().optional(),
+  // Degrade malformed hand edits locally; candidate writes reject them before parsing.
+  // An invalid native preference retains the legacy route instead of enabling native by default.
+  anthropicAccountPool: z.object({ nativeMessages: z.boolean().optional().catch(false) }).passthrough().optional().catch(undefined),
   // Same degrade-don't-reject rationale as the fields above: a hand-edited
   // non-string must not trip the backup-and-defaults repair path. Unset then
   // takes the canonical sideband path (src/server/live.ts normalizeSidebandRoot).