@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/codex/desktop-app-restart.ts

@@ -206,6 +206,27 @@ export function listCodexDesktopAppPids(io: DesktopAppRestartIo = {}): number[]
   return processes === null ? null : processes.map(entry => entry.pid);
 }
 
+/**
+ * Pids of the running desktop-app ROOT shells, or null when discovery or the probe failed.
+ *
+ * Read-only. The shell is the process whose renderer built the model picker, so its start
+ * time is what tells `performCodexRestart` whether the picker predates the catalog (#4761).
+ * `[]` means the probe ran and the app is not running.
+ */
+export function listCodexDesktopShellPids(io: DesktopAppRestartIo = {}): number[] | null {
+  const platform = io.platform ?? process.platform;
+  const selected = ADAPTERS[platform];
+  const adapter = io.adapter ?? selected?.adapter;
+  if (!adapter) return null;
+  const exec = io.execFile ?? selected?.exec;
+  if (!exec) return null;
+  const install = adapter.discover(exec);
+  if (!install) return null;
+  const processes = adapter.listProcesses(exec, install);
+  if (processes === null) return null;
+  return rootShells(processes, install, adapter).map(entry => entry.pid);
+}
+
 export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult {
   const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({
     attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason,

package/src/codex/desktop-compatibility/installed-build.ts

@@ -8,11 +8,21 @@ import type { DesktopAppInstall } from "../desktop-app/types";
 export const DESKTOP_COMPATIBILITY_ASSESSED_VERSION = "26.924.2738.0";
 export const DESKTOP_COMPATIBILITY_ASSESSED_FAMILY = "OpenAI.Codex_2p2nqsd0c76g0";
 
-function matchesAssessedPackage(install: DesktopAppInstall): boolean {
+/** Last completed probe outcome. Only public package facts: never paths, keys or account data. */
+export interface DesktopBuildAssessment {
+  assessedVersion: string;
+  observedVersion: string | null;
+  verified: boolean;
+  completedAt: number;
+}
+
+function assessInstalledPackage(install: DesktopAppInstall): { observedVersion: string | null; verified: boolean } {
   const name = win32.basename(install.root);
   const parts = /^OpenAI\.Codex_(\d+\.\d+\.\d+\.\d+)_(x64|arm64|x86|neutral)_([A-Za-z0-9.-]*)_([A-Za-z0-9]+)$/.exec(name);
-  return install.id === DESKTOP_COMPATIBILITY_ASSESSED_FAMILY && install.relaunch === `${install.id}!App`
-    && !!parts && parts[1] === DESKTOP_COMPATIBILITY_ASSESSED_VERSION && `OpenAI.Codex_${parts[4]}` === install.id;
+  const identified = install.id === DESKTOP_COMPATIBILITY_ASSESSED_FAMILY && install.relaunch === `${install.id}!App`
+    && !!parts && `OpenAI.Codex_${parts[4]}` === install.id;
+  const observedVersion = identified ? parts![1] : null;
+  return { observedVersion, verified: identified && observedVersion === DESKTOP_COMPATIBILITY_ASSESSED_VERSION };
 }
 
 /** Resolve only after the exact asynchronous child has closed, including abort/timeout. */
@@ -34,17 +44,25 @@ function queryInstalledPackage(signal: AbortSignal): Promise<DesktopAppInstall |
 /** Coalesce concurrent fresh probes; never cache a positive verdict across requests. */
 export function createInstalledBuildProbe(query: (signal: AbortSignal) => Promise<DesktopAppInstall | null> = queryInstalledPackage) {
   let pending: Promise<boolean> | null = null, controller: AbortController | null = null, closed = false;
+  let lastResult: DesktopBuildAssessment | null = null;
+  const record = (install: DesktopAppInstall | null) => {
+    const outcome = install ? assessInstalledPackage(install) : { observedVersion: null, verified: false };
+    lastResult = { assessedVersion: DESKTOP_COMPATIBILITY_ASSESSED_VERSION, ...outcome, completedAt: Date.now() };
+    return outcome.verified;
+  };
   return {
     check(): Promise<boolean> {
       if (closed) return Promise.resolve(false);
       if (pending) return pending;
       const current = new AbortController(); controller = current;
       pending = Promise.resolve().then(() => current.signal.aborted ? null : query(current.signal))
-        .then(install => !closed && !current.signal.aborted && !!install
-          && matchesAssessedPackage(install))
-        .catch(() => false).finally(() => { pending = null; controller = null; });
+        .then(install => closed || current.signal.aborted ? false : record(install))
+        .catch(() => closed || current.signal.aborted ? false : record(null))
+        .finally(() => { pending = null; controller = null; });
       return pending;
     },
+    /** Last completed check only: an aborted or in-flight query never rewrites it. */
+    lastResult(): DesktopBuildAssessment | null { return lastResult ? { ...lastResult } : null; },
     async close(): Promise<void> { closed = true; controller?.abort(); await pending; },
   };
 }

package/src/codex/desktop-compatibility/routing-preflight.ts

@@ -9,7 +9,7 @@ const record = (value: unknown): value is Record<string, unknown> => !!value &&
 // changes revoke the observed context even if the loopback URL stays the same.
 const ROUTING_KEYS = ["providers", "defaultProvider", "defaultModelAliases", "customModels", "combos", "routingProfiles",
   "subagentModelFallback", "subagentModelFallbackByModel", "injectionModel", "compactionRouting", "compactionRecovery",
-  "blockedModelRedirects", "shadowCallIntercept", "protocols", "memoryModels"] as const satisfies readonly (keyof OcxConfig)[];
+  "blockedModelRedirects", "shadowCallIntercept", "protocols", "memoryModels", "codexMainAccountHardLockFallback"] as const satisfies readonly (keyof OcxConfig)[];
 function routingDigest(text: string, owner: NativeCompatibilityOwner): string {
   const native = Bun.TOML.parse(text) as Record<string, unknown>;
   // Desktop refreshes MCP endpoints after launch. Tool transport metadata and TOML

package/src/codex/desktop-compatibility/runtime.ts

@@ -16,7 +16,7 @@ import { launchWindowsCodexCompatibility } from "./windows-package-launch";
 import { acquireDesktopCompatibilityRuntime, bindDesktopCompatibilityLaunch } from "./runtime-ownership";
 import { createDesktopConnectionStore, type DesktopConnectionStore } from "./connection-store";
 import { createNativeRoutingVerifier } from "./routing-preflight";
-import { createInstalledBuildProbe } from "./installed-build";
+import { createInstalledBuildProbe, type DesktopBuildAssessment } from "./installed-build";
 
 export { DESKTOP_COMPATIBILITY_ASSESSED_VERSION, isAssessedDesktopInstalled } from "./installed-build";
 export interface DesktopRuntimeIo {
@@ -25,6 +25,8 @@ export interface DesktopRuntimeIo {
   trust?: (authority: StoredDesktopAuthority) => Promise<"trusted" | "not-trusted" | "unknown">;
   identity?: ReturnType<typeof createNativeIdentityReader>;
   buildSupported?: () => boolean | Promise<boolean>;
+  /** Internal fixture probe factory; requires testOnly and all sandbox identity/CA seams. */
+  testOnlyBuildProbe?: () => ReturnType<typeof createInstalledBuildProbe>;
   upstreamFetch?: typeof fetch;
   connectionStore?: DesktopConnectionStore;
   routingSupported?: () => boolean;
@@ -36,6 +38,7 @@ export interface DesktopRuntimeIo {
 export function createDesktopCompatibilityRuntime(io: DesktopRuntimeIo = {}) {
   const platform = io.platform ?? process.platform;
   let buildProbe: ReturnType<typeof createInstalledBuildProbe> | undefined;
+  let previousBuildAssessment: DesktopBuildAssessment | null = null;
   const buildSupported = io.buildSupported ?? (() => buildProbe?.check() ?? Promise.resolve(false));
   let routingSupported = io.routingSupported ?? (() => false);
   let contextFailure: "build_unverified" | "native_routing_unverified" | null = null;
@@ -54,6 +57,7 @@ export function createDesktopCompatibilityRuntime(io: DesktopRuntimeIo = {}) {
   let pendingCleanup: (() => Promise<void>) | null = null;
   let releaseOwner: (() => void) | null = null;
   const status = () => ({ phase, supported: platform === "win32", running: owned !== null, contextFailure,
+    ...(buildProbe ? { buildAssessment: buildProbe.lastResult() ?? (previousBuildAssessment ? { ...previousBuildAssessment } : null) } : {}),
     ...(owned ? { fingerprint: owned.fingerprint, safetyDeadline: owned.deadline, usage: owned.controller.snapshot() } : {}) });
   async function stop(): Promise<ReturnType<typeof status>> {
     if (phase === "starting") throw new Error("desktop_compatibility_busy");
@@ -67,11 +71,11 @@ export function createDesktopCompatibilityRuntime(io: DesktopRuntimeIo = {}) {
   async function start() {
     if (phase !== "off") throw new Error("desktop_compatibility_busy");
     if (platform !== "win32") throw new Error("desktop_compatibility_unsupported");
-    if (isTestHomeGuardArmed() && !(io.testOnly && io.identity && io.loadAuthority && io.trust && io.buildSupported && io.connectionStore && io.routingSupported)) throw new Error("desktop_compatibility_test_environment");
+    if (io.testOnlyBuildProbe && (!io.testOnly || io.buildSupported)) throw new Error("desktop_compatibility_test_environment");
+    if ((isTestHomeGuardArmed() || io.testOnlyBuildProbe) && !(io.testOnly && io.identity && io.loadAuthority && io.trust && (io.buildSupported || io.testOnlyBuildProbe) && io.connectionStore && io.routingSupported)) throw new Error("desktop_compatibility_test_environment");
     if (didRunOptionalShutdownHooks()) throw new Error("desktop_compatibility_stopping");
     try { desktopProxyFor(new URL("https://chatgpt.com")); } catch { throw new Error("desktop_compatibility_egress_proxy_invalid"); }
     releaseOwner = acquireDesktopCompatibilityRuntime(); phase = "starting";
-    if (!io.buildSupported) buildProbe = createInstalledBuildProbe();
     let relay: Awaited<ReturnType<typeof startDesktopRelay>> | undefined, proxy: ConnectProxyHandle | undefined;
     let pac: ReturnType<typeof Bun.serve> | undefined, timer: ReturnType<typeof setInterval> | undefined;
     let detach: (() => void) | undefined, unbindLaunch: (() => void) | undefined, controller: UsageRelayController | undefined;
@@ -84,6 +88,11 @@ export function createDesktopCompatibilityRuntime(io: DesktopRuntimeIo = {}) {
     };
     pendingCleanup = cleanup;
     try {
+      if (!io.buildSupported) {
+        // A fresh probe owns this start; diagnostics retain the last completed observation.
+        previousBuildAssessment = buildProbe?.lastResult() ?? previousBuildAssessment;
+        buildProbe = io.testOnlyBuildProbe ? io.testOnlyBuildProbe() : createInstalledBuildProbe();
+      }
       if (!io.routingSupported) routingSupported = createNativeRoutingVerifier((await import("../paths")).getCodexHome());
       if (!await contextValid()) throw new Error(`desktop_compatibility_${contextFailure}`);
       const directory = join(getConfigDir(), "codex-desktop-compatibility");

package/src/codex/desktop-compatibility/windows-key-protection.ts

@@ -1,12 +1,14 @@
 import { execFile } from "node:child_process";
-import { resolveTrustedWindowsPowerShellExe } from "../../lib/windows-elevation";
+import { join } from "node:path";
+import { dlopen, ptr, toArrayBuffer, type Pointer } from "bun:ffi";
+import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsSystemDirectory } from "../../lib/windows-elevation";
 
 const MAX_INPUT = 65_536;
 const MAX_OUTPUT = 131_072;
 const PURPOSE = "opencodex/codex-desktop-compatibility/authority/v1";
-// A cold Windows PowerShell that must also load System.Security has been measured past 10s on a
-// loaded machine (Windows CI run 38591626343). The call is async and off the request path, so a
-// wider bound costs nothing while healthy and turns a slow start into success instead of a refusal.
+const ENTROPY = new TextEncoder().encode(PURPOSE);
+// Only the PowerShell fallback is bounded by a clock. A cold Windows PowerShell that must also load
+// System.Security has been measured past 10s on a loaded machine (Windows CI run 38591626343).
 const DPAPI_TIMEOUT_MS = 20_000;
 const SCRIPT = [
   "$ErrorActionPreference='Stop'",
@@ -24,18 +26,94 @@ const SCRIPT = [
   "[Console]::Out.Write([Convert]::ToBase64String($out))",
 ].join("\n");
 
+type Operation = "protect" | "unprotect";
+
 export interface AuthorityKeyProtection {
   protect(cleartext: Uint8Array): Promise<Uint8Array>;
   unprotect(ciphertext: Uint8Array): Promise<Uint8Array>;
 }
 
+// CRYPTPROTECT_UI_FORBIDDEN and no CRYPTPROTECT_LOCAL_MACHINE: the CurrentUser scope that
+// ProtectedData.Protect(..., CurrentUser) requests, so blobs written by either path read in the other.
+const CRYPTPROTECT_UI_FORBIDDEN = 0x1;
+// DATA_BLOB on x64: DWORD cbData, four bytes of padding, BYTE* pbData.
+const DATA_BLOB_BYTES = 16;
+const DPAPI_SIGNATURE = { args: ["ptr", "ptr", "ptr", "ptr", "ptr", "u32", "ptr"], returns: "i32" } as const;
+
+type NativeDpapi = (operation: Operation, data: Uint8Array) => Uint8Array;
+let nativeDpapi: NativeDpapi | undefined;
+
+function dataBlob(bytes: Uint8Array): Buffer {
+  const blob = Buffer.alloc(DATA_BLOB_BYTES);
+  blob.writeUInt32LE(bytes.byteLength, 0);
+  blob.writeBigUInt64LE(BigInt(ptr(bytes)), 8);
+  return blob;
+}
+
+/**
+ * In-process CryptProtectData/CryptUnprotectData. Spawning Windows PowerShell for every call cost
+ * seconds of cold start (past 20s on a loaded CI runner) for a call that takes milliseconds.
+ * crypt32 is loaded from the GetSystemDirectoryW path so the DLL search order cannot substitute it.
+ * Returns null where Bun's FFI is unavailable (Windows ARM64), leaving the PowerShell helper.
+ */
+function loadNativeDpapi(): NativeDpapi | null {
+  if (nativeDpapi) return nativeDpapi;
+  if (process.platform !== "win32" || process.arch !== "x64") return null;
+  let crypt32;
+  let kernel32;
+  try {
+    const systemDirectory = resolveTrustedWindowsSystemDirectory();
+    crypt32 = dlopen(join(systemDirectory, "crypt32.dll"), {
+      CryptProtectData: DPAPI_SIGNATURE,
+      CryptUnprotectData: DPAPI_SIGNATURE,
+    }).symbols;
+    kernel32 = dlopen(join(systemDirectory, "kernel32.dll"), {
+      LocalFree: { args: ["ptr"], returns: "ptr" },
+      // Wipes by address, so clearing never depends on a JS view having been created.
+      RtlZeroMemory: { args: ["ptr", "u64"], returns: "void" },
+    }).symbols;
+  } catch {
+    return null;
+  }
+  const { CryptProtectData, CryptUnprotectData } = crypt32;
+  const { LocalFree, RtlZeroMemory } = kernel32;
+  nativeDpapi = (operation, data) => {
+    const input = dataBlob(data);
+    const entropy = dataBlob(ENTROPY);
+    const output = Buffer.alloc(DATA_BLOB_BYTES);
+    const call = operation === "protect" ? CryptProtectData : CryptUnprotectData;
+    // Description, reserved and prompt are null; Windows reports no detail worth propagating.
+    if (!call(ptr(input), null, ptr(entropy), null, null, CRYPTPROTECT_UI_FORBIDDEN, ptr(output))) {
+      throw new Error("desktop_compatibility_key_protection_failed");
+    }
+    const length = output.readUInt32LE(0);
+    const address = Number(output.readBigUInt64LE(8)) as Pointer;
+    // Every step after a successful call sits inside try so the native buffer is always
+    // released, even if creating the view over it throws.
+    let view: Uint8Array | null = null;
+    try {
+      view = length > 0 ? new Uint8Array(toArrayBuffer(address, 0, length)) : null;
+      if (length === 0 || length > MAX_INPUT) throw new Error("desktop_compatibility_key_size");
+      return Uint8Array.from(view!);
+    } finally {
+      // The unprotected buffer is cleartext key material; wipe it natively before LocalFree
+      // releases it, including when the size check or view creation fails. LocalFree still
+      // runs if wiping throws.
+      try {
+        if (operation === "unprotect" && length > 0) RtlZeroMemory(address, length);
+      } finally {
+        LocalFree(address);
+      }
+    }
+  };
+  return nativeDpapi;
+}
+
 /** The payload travels on stdin, never in process arguments, environment or logs. */
-function runDpapi(operation: "protect" | "unprotect", data: Uint8Array): Promise<Uint8Array> {
-  if (process.platform !== "win32") return Promise.reject(new Error("desktop_compatibility_windows_required"));
-  if (data.byteLength === 0 || data.byteLength > MAX_INPUT) return Promise.reject(new Error("desktop_compatibility_key_size"));
+function runPowerShellDpapi(operation: Operation, data: Uint8Array, timeoutMs = DPAPI_TIMEOUT_MS): Promise<Uint8Array> {
   return new Promise((resolve, reject) => {
-    const child = execFile(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", SCRIPT], {
-      timeout: DPAPI_TIMEOUT_MS, maxBuffer: MAX_OUTPUT, windowsHide: true, encoding: "utf8",
+    const child = execFile(resolveTrustedWindowsPowerShellExe(), ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", SCRIPT], {
+      timeout: timeoutMs, maxBuffer: MAX_OUTPUT, windowsHide: true, encoding: "utf8",
     }, (error, stdout) => {
       // Do not include PowerShell stderr, command output or the input in a propagated error.
       if (error || !/^[A-Za-z0-9+/]+={0,2}$/.test(stdout.trim())) {
@@ -52,8 +130,36 @@ function runDpapi(operation: "protect" | "unprotect", data: Uint8Array): Promise
   });
 }
 
+function validated(data: Uint8Array): Uint8Array {
+  if (process.platform !== "win32") throw new Error("desktop_compatibility_windows_required");
+  if (data.byteLength === 0 || data.byteLength > MAX_INPUT) throw new Error("desktop_compatibility_key_size");
+  return data;
+}
+
+async function runDpapi(operation: Operation, data: Uint8Array): Promise<Uint8Array> {
+  validated(data);
+  const native = loadNativeDpapi();
+  return native ? native(operation, data) : runPowerShellDpapi(operation, data);
+}
+
 /** CurrentUser protects against other OS identities, not other processes of the same user. */
 export const windowsAuthorityKeyProtection: AuthorityKeyProtection = {
   protect: bytes => runDpapi("protect", bytes),
   unprotect: bytes => runDpapi("unprotect", bytes),
 };
+
+/**
+ * Test-only: the PowerShell helper (Windows ARM64, and every key stored before the native path).
+ * The caller owns the bound because a compatibility check must not depend on cold-start latency.
+ */
+export function powerShellAuthorityKeyProtectionForTests(timeoutMs: number): AuthorityKeyProtection {
+  return {
+    protect: async bytes => runPowerShellDpapi("protect", validated(bytes), timeoutMs),
+    unprotect: async bytes => runPowerShellDpapi("unprotect", validated(bytes), timeoutMs),
+  };
+}
+
+/** Test-only: whether this process protects keys in-process rather than through PowerShell. */
+export function usesNativeDpapiForTests(): boolean {
+  return process.platform === "win32" && loadNativeDpapi() !== null;
+}

package/src/codex/features.ts

@@ -44,6 +44,10 @@ import { resolveCodexHomeDir } from "./home";
 import { resolveAndPersistCodexRuntime } from "./runtime";
 import { decodeOverlayState } from "./shim-state-file";
 import { canonicalizeOpenCodexModeHint } from "./multi-agent-mode-policy";
+import { rootAssignmentKey, sourceText, splitSourceLines } from "./toml-source-lines";
+
+const AGENTS_THREAD_LIMIT_KEY = "max_concurrent_threads_per_session";
+const LEGACY_AGENTS_THREAD_LIMIT_KEY = "max_threads";
 
 /** Upstream codex-rs feature key: allow `request_user_input` in Default mode. */
 export const DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY = "default_mode_request_user_input";
@@ -328,36 +332,31 @@ export function isDefaultModeRequestUserInputEnabled(configPath?: string): boole
 }
 
 /**
- * TRUE when config.toml still carries `[agents] max_threads` — codex-rs REFUSES to
- * boot with that key while multi_agent_v2 is enabled ("agents.max_threads cannot be
- * set when features.multi_agent_v2 is enabled", core/src/config/mod.rs:1421). The
- * `ocx v2 on` flow warns about it instead of editing config itself.
+ * Whether either spelling of the [agents] limit is present, including invalid
+ * values. Keep the exported compatibility name; migrations must remove both.
  */
 export function hasAgentsMaxThreads(configPath?: string): boolean {
   const content = readConfigText(configPath);
   if (content === null) return false;
   const parsed = parsedTomlTable(content, "agents");
-  if (parsed !== null) return Object.hasOwn(parsed, "max_threads");
-  const agents = tomlTableBody(content, "agents");
-  if (agents === null) return false;
-  return /^\s*max_threads\s*=/m.test(agents);
+  if (parsed !== null) return Object.hasOwn(parsed, AGENTS_THREAD_LIMIT_KEY) || Object.hasOwn(parsed, LEGACY_AGENTS_THREAD_LIMIT_KEY);
+  return agentsThreadLimitEntries(content).entries.length > 0;
 }
 
-/** Current legacy v1 `[agents] max_threads`, or null when absent/invalid. */
+/** Canonical [agents] limit, falling back to max_threads only when absent. */
 export function getAgentsMaxThreads(configPath?: string): number | null {
   const content = readConfigText(configPath);
   if (content === null) return null;
   const parsed = parsedTomlTable(content, "agents");
   if (parsed !== null) {
-    const value = parsed.max_threads;
+    const value = Object.hasOwn(parsed, AGENTS_THREAD_LIMIT_KEY) ? parsed[AGENTS_THREAD_LIMIT_KEY] : parsed[LEGACY_AGENTS_THREAD_LIMIT_KEY];
     return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null;
   }
-  const agents = tomlTableBody(content, "agents");
-  if (agents === null) return null;
-  const m = agents.match(/^\s*max_threads\s*=\s*(\d+)\s*(?:#.*)?$/m);
-  if (!m) return null;
-  const value = Number(m[1]);
-  return Number.isInteger(value) && value >= 1 ? value : null;
+  // Unrelated valid 64-bit integers can make Bun reject the whole document.
+  // Decode the same isolated structural assignment the editor uses, including
+  // quoted keys and non-decimal integers, rather than treating unreadable as unset.
+  const entries = agentsThreadLimitEntries(content).entries;
+  return (entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0])?.value ?? null;
 }
 
 /**
@@ -1310,33 +1309,59 @@ function editAgentsMaxThreads(value: number | null, configPath?: string, migrate
   const path = configPath ?? activeCodexConfigPath();
   return editCodexConfigToml(path, (content): TomlEditOutcome => {
     const eol = dominantEol(content);
-    const lines = content.split(/\r?\n/);
-    const headerIdx = lines.findIndex(l => /^\s*\[agents\]\s*(?:#.*)?$/.test(l));
+    const { lines, headerIdx, entries } = agentsThreadLimitEntries(content);
     if (headerIdx === -1) {
       if (value === null) return { next: content };
-      const separator = lines.length > 0 && lines[lines.length - 1] !== "" ? [""] : [];
-      lines.push(...separator, "[agents]", `max_threads = ${value}${migratedComment ?? ""}`);
-      return { next: applyEol(lines.join("\n"), eol) };
+      const separator = content.length > 0 && !content.endsWith("\n") ? eol : "";
+      return { next: `${content}${separator}${eol}[agents]${eol}${AGENTS_THREAD_LIMIT_KEY} = ${value}${migratedComment ?? ""}${eol}` };
     }
-    let end = lines.length;
-    for (let i = headerIdx + 1; i < lines.length; i++) {
-      if (/^\s*\[/.test(lines[i])) { end = i; break; }
+    const selected = entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0];
+    if (entries.length === 1 && selected?.key === AGENTS_THREAD_LIMIT_KEY && selected.value === value
+      && value !== null && mergeTrailingComments(selected.comment, migratedComment) === (selected.comment ?? "")) return { next: content };
+    let comment = selected?.comment;
+    for (const entry of entries) comment = mergeTrailingComments(comment, entry.comment);
+    comment = mergeTrailingComments(comment, migratedComment);
+    for (const entry of [...entries].reverse()) {
+      if (value !== null && entry === selected) {
+        const line = lines[entry.index]!;
+        line.text = `${line.text.match(/^\s*/)?.[0] ?? ""}${AGENTS_THREAD_LIMIT_KEY} = ${value}${comment}`;
+      } else lines.splice(entry.index, 1);
     }
-    const keyRe = /^(\s*)max_threads\s*=\s*(\d+)(\s*#.*)?$/;
-    for (let i = headerIdx + 1; i < end; i++) {
-      const m = lines[i].match(keyRe);
-      if (!m) continue;
-      if (value === null) lines.splice(i, 1);
-      else if (Number(m[2]) === value && (!migratedComment || migratedComment === m[3])) return { next: content };
-      else lines[i] = `${m[1]}max_threads = ${value}${mergeTrailingComments(m[3], migratedComment)}`;
-      return { next: applyEol(lines.join("\n"), eol) };
+    if (value !== null && !selected) {
+      if (!lines[headerIdx]!.eol) lines[headerIdx]!.eol = eol;
+      lines.splice(headerIdx + 1, 0, { text: `${AGENTS_THREAD_LIMIT_KEY} = ${value}${comment}`, eol, structural: true });
     }
-    if (value === null) return { next: content };
-    lines.splice(headerIdx + 1, 0, `max_threads = ${value}${migratedComment ?? ""}`);
-    return { next: applyEol(lines.join("\n"), eol) };
+    return { next: sourceText(lines) };
   });
 }
 
+/** Only structural assignments in the supported agents table are editable. */
+function agentsThreadLimitEntries(content: string) {
+  const lines = splitSourceLines(content);
+  const headerIdx = lines.findIndex(line => line.structural && /^\s*\[agents\]\s*(?:#.*)?$/.test(line.text));
+  const entries: Array<{ index: number; key: string; value: number | null; comment?: string; editable: boolean }> = [];
+  if (headerIdx !== -1) {
+    for (let index = headerIdx + 1; index < lines.length; index++) {
+      const line = lines[index]!;
+      if (!line.structural) continue;
+      if (/^\s*\[/.test(line.text)) break;
+      const key = rootAssignmentKey(line.text);
+      if (key !== AGENTS_THREAD_LIMIT_KEY && key !== LEGACY_AGENTS_THREAD_LIMIT_KEY) continue;
+      const assignment = findTomlAssignment(line.text, key);
+      const editable = assignment !== null && (index + 1 === lines.length || lines[index + 1]!.structural);
+      let value: unknown;
+      try { value = (Bun.TOML.parse(line.text) as Record<string, unknown>)[key]; } catch {
+        // Match the reader's large-integer fallback without widening edit syntax.
+        const integer = assignment && /^\d+$/.exec(line.text.slice(assignment.valueStart, assignment.valueEnd).trim());
+        if (integer) value = Number(integer[0]);
+      }
+      entries.push({ index, key, editable, value: typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null,
+        comment: assignment ? line.text.slice(assignment.valueEnd).match(/\s*#.*$/)?.[0] : undefined });
+    }
+  }
+  return { lines, headerIdx, entries };
+}
+
 function removeMaxConcurrentThreads(configPath?: string): ConfigEditResult {
   const path = configPath ?? activeCodexConfigPath();
   return editCodexConfigToml(path, (content): TomlEditOutcome => {
@@ -1439,7 +1464,9 @@ function discoverStoredThreadLimit(configPath?: string): { value: number; units:
 }
 
 function activeThreadComment(content: string, v2Enabled: boolean): string | undefined {
-  const legacy = tomlTableBody(content, "agents")?.match(/^\s*max_threads\s*=\s*\d+(\s*#.*)$/m)?.[1];
+  const entries = agentsThreadLimitEntries(content).entries;
+  let legacy = (entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0])?.comment;
+  for (const entry of entries) legacy = mergeTrailingComments(legacy, entry.comment) || undefined;
   const dedicated = tomlTableBody(content, "features.multi_agent_v2")
     ?.match(/^\s*max_concurrent_threads_per_session\s*=\s*\d+(\s*#.*)$/m)?.[1];
   const features = tomlTableBody(content, "features");
@@ -1503,8 +1530,8 @@ export type MultiAgentV2TransitionResult =
   | { ok: true; changed: boolean; threadLimit: number | null }
   | { ok: false; error: string; retryable?: boolean };
 
-function transitionConfigError(content: string): string | null {
-  if (/^\s*(?:features\.multi_agent_v2(?:\.[A-Za-z0-9_]+)?|agents\.max_threads)\s*=/m.test(content)) {
+function transitionConfigError(content: string, explicitThreadLimit: boolean): string | null {
+  if (/^\s*(?:features\.multi_agent_v2(?:\.[A-Za-z0-9_]+)?|agents\.(?:max_threads|max_concurrent_threads_per_session))\s*=/m.test(content)) {
     return "dotted multi-agent config keys are not supported for automatic migration";
   }
   const dedicatedTables = content.match(/^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/gm) ?? [];
@@ -1521,9 +1548,18 @@ function transitionConfigError(content: string): string | null {
   if (features && /^\s*multi_agent_v2\.(?:enabled|max_concurrent_threads_per_session)\s*=/m.test(features)) {
     return "dotted multi_agent_v2 fields are not supported for automatic migration";
   }
-  const agents = tomlTableBody(content, "agents");
-  if ((agents?.match(/^\s*max_threads\s*=/gm) ?? []).length > 1) {
-    return "duplicate agents.max_threads definitions cannot be migrated safely";
+  const entries = agentsThreadLimitEntries(content).entries;
+  const parsedAgents = parsedTomlTable(content, "agents");
+  for (const key of [AGENTS_THREAD_LIMIT_KEY, LEGACY_AGENTS_THREAD_LIMIT_KEY]) {
+    const matches = entries.filter(entry => entry.key === key);
+    if (matches.length > 1) return `duplicate agents.${key} definitions cannot be migrated safely`;
+    if (parsedAgents && Object.hasOwn(parsedAgents, key) && matches.length === 0) {
+      return "unsupported agents thread-limit storage cannot be migrated safely";
+    }
+  }
+  if (entries.some(entry => !entry.editable)) return "unsupported agents thread-limit value cannot be migrated safely";
+  if (!explicitThreadLimit && (entries.some(entry => entry.value === null) || (entries.length === 2 && entries[0]!.value !== entries[1]!.value))) {
+    return "conflicting or invalid agents thread-limit aliases require an explicit thread limit";
   }
   const dedicated = tomlTableBody(content, "features.multi_agent_v2");
   if ((dedicated?.match(/^\s*max_concurrent_threads_per_session\s*=/gm) ?? []).length > 1) {
@@ -1542,15 +1578,15 @@ export function transitionMultiAgentV2(
   toggleFeature: (enabled: boolean, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void,
   options: { configPath?: string; threadLimit?: number; heldConfigWriteLock?: LockHandle } = {},
 ): MultiAgentV2TransitionResult {
-  if (options.threadLimit !== undefined && (!Number.isInteger(options.threadLimit) || options.threadLimit < 1)) {
-    return { ok: false, error: "thread limit must be an integer >= 1" };
+  if (options.threadLimit !== undefined && (!Number.isSafeInteger(options.threadLimit) || options.threadLimit < 1)) {
+    return { ok: false, error: "thread limit must be a safe integer >= 1" };
   }
   const path = options.configPath ?? activeCodexConfigPath();
   if (codexHomeIsAbsent(dirname(path))) return { ok: false, error: `config.toml not readable at ${path}` };
   const runTransition = (held: LockHandle): MultiAgentV2TransitionResult => {
   const original = readConfigText(path);
   if (original === null) return { ok: false, error: `config.toml not readable at ${path}` };
-  const preflightError = transitionConfigError(original);
+  const preflightError = transitionConfigError(original, options.threadLimit !== undefined);
   if (preflightError) return { ok: false, error: preflightError };
   const beforeEnabled = isMultiAgentV2Enabled(path);
   // A caller-supplied limit is already in the DESTINATION backend's units and is
@@ -1573,6 +1609,9 @@ export function transitionMultiAgentV2(
       ? v1ChildLimitToV2TotalLimit(discovered.value)
       : v2TotalLimitToV1ChildLimit(discovered.value);
   }
+  if (threadLimit !== null && !Number.isSafeInteger(threadLimit)) {
+    return { ok: false, error: "stored thread limit cannot be written safely; supply an explicit safe integer limit" };
+  }
   const migratedComment = activeThreadComment(original, beforeEnabled);
   try {
     return withConfigWriteRecovery(path, held, () => {
@@ -1606,7 +1645,8 @@ export function transitionMultiAgentV2(
           return editAgentsMaxThreads(threadLimit, tempPath, migratedComment);
         });
         if (!target.ok) throw new Error(target.error);
-        if (getMaxConcurrentThreads(path) !== null || getAgentsMaxThreads(path) !== threadLimit) throw new Error("v1 thread-limit migration postcondition failed");
+        const agents = parsedTomlTable(readConfigText(path) ?? "", "agents");
+        if (getMaxConcurrentThreads(path) !== null || getAgentsMaxThreads(path) !== threadLimit || (agents && Object.hasOwn(agents, LEGACY_AGENTS_THREAD_LIMIT_KEY))) throw new Error("v1 thread-limit migration postcondition failed");
       }
       return { ok: true, changed: readConfigText(path) !== original, threadLimit };
     });

package/src/codex/inject/history-failure.ts

@@ -0,0 +1,27 @@
+import { describeHistoryJobFailure, type CodexHistoryJobOutcome } from "../history-job";
+
+/**
+ * Frame one failed apply history job honestly.
+ *
+ * A genuine lock keeps the established deferred/SKIPPED wording; any other
+ * reason names itself instead of blaming the Codex app/IDE.
+ */
+export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legacyMode: boolean): string {
+  // A busy database is a deferral no matter which half observed it: the lock
+  // contended (blocked/busy), or the worker acquired the lock and then found
+  // SQLite busy (failed with a busy history reason). Only those keep the
+  // deferred headline; every other failure is a real "NOT changed".
+  const busy =
+    (outcome.kind === "blocked" && outcome.reason === "busy") ||
+    (outcome.kind === "failed" && outcome.historyFailureReason === "busy");
+  const partiallyChanged = outcome.kind === "failed"
+    && ((outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0);
+  const headline = partiallyChanged
+    ? "Codex resume history changed but did not converge"
+    : legacyMode
+      ? "Codex resume history sync SKIPPED"
+      : busy
+      ? "Codex resume history metadata restore deferred"
+      : "Codex resume history NOT changed";
+  return `  ⚠️ ${headline}: ${describeHistoryJobFailure(outcome, "apply", legacyMode)}\n`;
+}

package/src/codex/inject/restore.ts

@@ -1,3 +1,4 @@
+import { restoreApprovedCodexProviders } from "../provider-routing";
 import { beginCodexWriteSection, cleanExternalProviderJournal, publishCodexArtifact } from "./config-write-section";
 import { assertCodexHomeOwner, codexHomeIsAbsent, codexHomeOwnerBlocksCompensation, CodexHomeOwnerRefusal, type CodexHomeOwnerRefusalReason } from "../codex-home-owner";
 import { loadConfig } from "../../config";
@@ -115,6 +116,7 @@ export interface CodexRestoreConfigResult {
     | "owned-fields-stripped"
     | "routing-restored-provider-retained"
     | "external-provider-preserved"
+    | "approved-provider-restored"
     | "failed";
   message: string;
   retained?: RetainedCodexProviderTable;
@@ -236,6 +238,26 @@ export function failedHistoryRestoreFromOutcome(
   return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
 }
 
+export function finishApprovedProviderRestore(result: CodexNativeRestoreResult, revalidateDesiredState = false): CodexNativeRestoreResult {
+  if (!result.success || revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) return result;
+  try {
+    if (!restoreApprovedCodexProviders()) return result;
+  } catch (error) {
+    if (error instanceof CodexHomeOwnerRefusal) throw error;
+    const message = `Approved Codex provider URL restoration failed: ${error instanceof Error ? error.message : String(error)}`;
+    return { ...result, success: false, message: `${result.message} ${message}`, artifacts: {
+      ...result.artifacts, config: { ...result.artifacts.config, state: "failed", action: "failed", message },
+    } };
+  }
+  const message = "Approved Codex provider URLs restored; identity, other settings and history preserved.";
+  return { ...result, message: result.externalProvider ? message : `${result.message} ${message}`, artifacts: {
+    ...result.artifacts,
+    config: { ...result.artifacts.config, state: result.artifacts.config.state === "partial" ? "partial" : "ok", changed: true,
+      action: result.artifacts.config.changed ? result.artifacts.config.action : "approved-provider-restored",
+      message: result.artifacts.config.state === "partial" ? `${result.artifacts.config.message} ${message}` : message },
+  } };
+}
+
 function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
   const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
   return {
@@ -553,7 +575,7 @@ export async function restoreNativeCodexAsync(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return await restoreNativeCodexAsyncImpl(options);
+    return finishApprovedProviderRestore(await restoreNativeCodexAsyncImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     if (!(error instanceof CodexRestoreRefusal)) throw error;
@@ -782,7 +804,7 @@ export function restoreNativeCodex(
   if (sibling) return sibling;
   try {
     assertCodexHomeOwner(getCodexHome());
-    return restoreNativeCodexImpl(options);
+    return finishApprovedProviderRestore(restoreNativeCodexImpl(options), options.revalidateDesiredState);
   } catch (error) {
     if (error instanceof CodexHomeOwnerRefusal) return homeOwnerRestoreRefusal(error);
     throw error;