@iislee/opencodex 2.31.0 → 2.35.0

package/src/codex/convergence.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 
-import { getConfigDir, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
+import { getConfigDir, saveConfigPreservingClaudeCode, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
+import { reconcileSuccessfulModelDiscoveries } from "../providers/new-model-policy";
 import { COMBO_NAMESPACE } from "../combos";
 import { getAuthStorePath } from "../oauth/store";
 import type { OcxConfig } from "../types";
@@ -41,6 +42,7 @@ import {
   import {
   buildCatalogEntriesFromObservedState,
   CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
+  finalizeAutoReviewModelOverride,
   mergeCatalogEntriesFromObservedState,
   mergeCatalogModelsWithNativeRecovery,
   orderForSubagents,
@@ -54,6 +56,7 @@ import {
   disabledNativeSlugs,
   desktopAllowlistSuppressedNativeSlugs,
   NATIVE_OPENAI_MODELS,
+  nativeContextLimits,
   shouldIncludeAccountBoundNativeOpenAi,
   shouldIncludeNativeOpenAi,
 } from "./catalog/metadata";
@@ -134,6 +137,7 @@ interface CandidateState {
   readonly changed: boolean;
   readonly notices: readonly CatalogNotice[];
   readonly modelEntitlements: CodexModelEntitlementSnapshot;
+  readonly discoveryConfig?: OcxConfig;
 }
 
 const candidateStates = new WeakMap<object, CandidateState>();
@@ -286,6 +290,7 @@ function prepareCatalog(
   // selector-qualified rows when a live selector is configured.
   const observedNativeSlugs: string[] = [];
   const disabledNative = disabledNativeSlugs(config);
+  const openaiContextCap = nativeContextLimits(config);
   const nativeCatalogModels = mergeCatalogModelsWithNativeRecovery(
     active?.models ?? catalog.models ?? [],
     [catalog.models ?? [], ...nativeRecoverySources],
@@ -304,6 +309,7 @@ function prepareCatalog(
     suppressedBareNativeSlugs,
     disabledNativeAccountSlugs: new Set(),
     multiAgentV2Enabled,
+    openaiContextCap,
   });
   const accountBoundEntries = accountSelectors.length === 0
     ? []
@@ -320,6 +326,7 @@ function prepareCatalog(
       disabledNativeAccountSlugs: new Set([...disabledNative].filter(slug => suppressedBareNativeSlugs.has(slug))),
       multiAgentV2Enabled,
       keepNativeChatGptOnV1: config.keepNativeChatGptOnV1 === true,
+      openaiContextCap,
       accountNativeSlugs,
       accountNativeSlugsBySelector,
     }).filter(entry => trustedAccountBoundNativeCatalogSlug(entry) !== undefined);
@@ -352,6 +359,7 @@ function prepareCatalog(
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    openaiContextCap,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],
@@ -364,6 +372,7 @@ function prepareCatalog(
       ? supportedCodexReasoningEffortsFromObservedCatalog(source.runtimeSupport.catalog)
       : null,
   );
+  finalizeAutoReviewModelOverride(mergedModels, catalogModels);
   catalog.models = mergedModels;
   return catalog;
 }
@@ -431,8 +440,17 @@ export async function gatherCodexCatalogCandidate(
           ? active
           : !hasRoutedEntries(source.catalog) ? source.catalog : null)
         : null);
+    const discoveryConfig = structuredClone(snapshot.config) as OcxConfig;
+    const discoveryChanged = reconcileSuccessfulModelDiscoveries({
+      config: discoveryConfig,
+      models: routedModels,
+      authoritativeProviders: providerModelOutcomes
+        .filter(outcome => outcome.state === "authoritative")
+        .map(outcome => outcome.provider),
+      now: new Date().toISOString(),
+    });
     const preparedCatalog = prepareCatalog(
-      snapshot.config,
+      discoveryConfig,
       source,
       active,
       routedModels,
@@ -497,6 +515,7 @@ export async function gatherCodexCatalogCandidate(
         || Buffer.from(cacheBytes ?? []).toString("utf8") !== preparedCacheBytes,
       notices: Object.freeze([...notices]),
       modelEntitlements,
+      ...(discoveryChanged ? { discoveryConfig } : {}),
     });
     return { kind: "candidate", candidate };
   } catch (error) {
@@ -644,6 +663,12 @@ export async function convergeCodexCatalog(
   const state = candidateStates.get(gathered.candidate as object)!;
   lifecycle.onCommitBegin?.();
   const committed = await commitCodexCatalogCandidate(gathered.candidate, request.deadlineMs);
+  if (committed.kind === "committed" && state.discoveryConfig) {
+    const mutable = snapshot.config as OcxConfig;
+    mutable.modelDiscovery = state.discoveryConfig.modelDiscovery;
+    mutable.disabledModels = state.discoveryConfig.disabledModels;
+    saveConfigPreservingClaudeCode(mutable);
+  }
   return {
     changed: committed.kind === "committed" ? committed.changed : false,
     catalogRefresh: projectCommit(committed, state.notices),

package/src/codex/desired-state.ts

@@ -20,7 +20,7 @@
  *
  * Design record: devlog/_fin/260803_codex_desktop_toggle/030_desired_state.md.
  */
-import { loadConfig, mutatePersistedConfig } from "../config";
+import { deleteConfigTopLevelKey, loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxClientIntegrationsConfig, OcxConfig } from "../types";
 import { runStartupReadinessSync, type ReadinessGate, type SyncOutcomeLike } from "../server/readiness";
 
@@ -114,7 +114,7 @@ export function setIntegrationEnabled(
     }
     // Drop the key entirely once nothing is left in it, so enabling twice does
     // not leave `"clientIntegrations": {}` behind in the user's file.
-    if (Object.keys(integrations).length === 0) delete config.clientIntegrations;
+    if (Object.keys(integrations).length === 0) deleteConfigTopLevelKey(config, "clientIntegrations");
     else config.clientIntegrations = integrations;
     return { changed: true, value: enabled };
   });

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

@@ -0,0 +1,355 @@
+/**
+ * Full restart of the Codex desktop app (the Electron shell), Windows only.
+ *
+ * `--restart-codex` deliberately signals only `codex app-server` /
+ * `codex-code-mode-host` processes: `isCodexAppServerCommandLine` requires a
+ * `codex` executable token, so the shell that owns the model picker is never a
+ * match. On macOS that is enough, because the respawned app-server re-emits
+ * `codex-app-server-initialized` and the renderer drops its cached
+ * `model/list`. On Windows MSIX it is not: externally terminating the child
+ * does not reliably re-emit that event in the surviving shell, so the picker
+ * keeps showing the old catalog until the app itself is restarted (#2292).
+ *
+ * This is therefore a SEPARATE opt-in flag rather than a widening of
+ * `--restart-codex`. Quitting the desktop app ends live conversations, which is
+ * a different consent from restarting a background helper, and the CLI contract
+ * for `--restart-codex` promises the narrow behavior.
+ *
+ * Everything here fails CLOSED: if the package cannot be identified, if a
+ * target is part of our own ancestry, or if any target survives termination,
+ * nothing is relaunched and the caller is told to restart manually. A stale
+ * picker is a much smaller problem than a wrongly killed process.
+ */
+import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsTaskkillExe } from "../lib/windows-elevation";
+import { execFileSync } from "node:child_process";
+
+/** Bounded subprocess options. A hung Appx/CIM probe must never wedge `ocx sync`. */
+export interface DesktopAppExecOptions {
+  timeout?: number;
+  windowsHide?: boolean;
+}
+
+export interface DesktopAppRestartIo {
+  platform?: NodeJS.Platform;
+  /** Returns stdout. Options are part of the seam so the timeout is testable. */
+  execFile?: (file: string, args: readonly string[], options?: DesktopAppExecOptions) => string;
+  /** Process ancestry of the current process, innermost first. Used for the self-kill guard. */
+  ancestryPids?: () => number[];
+  isAlive?: (pid: number) => boolean;
+  sleep?: (ms: number) => void;
+  now?: () => number;
+}
+
+export type DesktopAppRestartReason =
+  | "windows_only"
+  | "package_discovery_failed"
+  | "process_probe_failed"
+  | "no_targets"
+  | "self_ancestry"
+  | "targets_survived";
+
+export interface DesktopAppRestartResult {
+  attempted: boolean;
+  stopped: number[];
+  surviving: number[];
+  relaunch: "started" | "skipped";
+  reason?: DesktopAppRestartReason;
+}
+
+/** How long a graceful close is given before the forced pass. */
+const GRACEFUL_EXIT_TIMEOUT_MS = 15_000;
+/** How long a forced kill is given before the target counts as surviving. */
+const FORCED_EXIT_TIMEOUT_MS = 5_000;
+/** Every probe is bounded; PowerShell module loading is the slow part. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+interface DesktopPackage {
+  family: string;
+  installLocation: string;
+  aumid: string;
+}
+
+/**
+ * Runtime discovery, never a hardcoded identifier. The beta MSIX package family
+ * changes between builds, so a literal AUMID would silently stop matching and
+ * then either do nothing or — worse — match a package we did not mean.
+ */
+function discoverPackage(exec: NonNullable<DesktopAppRestartIo["execFile"]>): DesktopPackage | null {
+  const script = [
+    "$ErrorActionPreference='SilentlyContinue'",
+    "Import-Module Appx -ErrorAction SilentlyContinue",
+    "$p = Get-AppxPackage -Name OpenAI.Codex",
+    "if (-not $p) { $p = Get-AppxPackage -Name OpenAI.CodexBeta }",
+    "if (-not $p -or -not $p.InstallLocation) { 'MISS' } else {",
+    "  $p.PackageFamilyName; $p.InstallLocation; \"$($p.PackageFamilyName)!App\"",
+    "}",
+  ].join("; ");
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], {
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+  } catch {
+    return null;
+  }
+  const lines = stdout.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+  if (lines.length < 3 || lines[0] === "MISS") return null;
+  const [family, installLocation, aumid] = lines;
+  if (!family || !installLocation || !aumid) return null;
+  return { family, installLocation, aumid };
+}
+
+interface DesktopProcess {
+  pid: number;
+  parentPid: number;
+  /** Win32_Process CreationDate. Guards against PID reuse across the wait window. */
+  createdAt: string;
+}
+
+/**
+ * Only `ChatGPT.exe` processes whose image lives under the discovered install
+ * location AND owned by the current user. The install location alone is not
+ * enough: an MSIX package under `WindowsApps` is shared, so on a multi-user
+ * machine another account's Codex desktop matches the same path. The app-server
+ * collector already pays for `GetOwner` for exactly this reason.
+ *
+ * `CreationDate` is captured so a PID can be re-verified before it is signalled;
+ * a graceful-close window is long enough for Windows to recycle a PID.
+ */
+function listPackageProcesses(
+  exec: NonNullable<DesktopAppRestartIo["execFile"]>,
+  installLocation: string,
+): DesktopProcess[] | null {
+  const literal = installLocation.replace(/'/g, "''");
+  const script = [
+    "$ErrorActionPreference='SilentlyContinue'",
+    `$root = '${literal}'`,
+    "$me = ([Security.Principal.WindowsIdentity]::GetCurrent()).Name",
+    "Get-CimInstance Win32_Process -Filter \"Name='ChatGPT.exe'\" |",
+    "  Where-Object { $_.ExecutablePath -and $_.ExecutablePath.StartsWith($root, 'OrdinalIgnoreCase') } |",
+    "  ForEach-Object {",
+    "    $o = Invoke-CimMethod -InputObject $_ -MethodName GetOwner",
+    "    if ($o -and $o.ReturnValue -eq 0 -and $o.User) {",
+    "      $owner = if ($o.Domain) { \"$($o.Domain)\\$($o.User)\" } else { $o.User }",
+    "      if ($owner -ieq $me) {",
+    "        \"$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToString('o'))\"",
+    "      }",
+    "    }",
+    "  }",
+  // Statements must be newline-separated. Joining with a space concatenates
+  // `$ErrorActionPreference='SilentlyContinue' $root = '...'` into one malformed statement,
+  // which PowerShell rejects — so the probe threw and every caller read "not running" (#2557).
+  ].join("\n");
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], {
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+  } catch {
+    // A probe that could not run is NOT proof the app is absent. Returning [] here made a
+    // failed enumeration indistinguishable from "no targets", so the CLI reported the app as
+    // not running and skipped a restart the user had explicitly asked for.
+    return null;
+  }
+  const processes: DesktopProcess[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const createdAt = match[3]!;
+    if (Number.isSafeInteger(pid) && Number.isSafeInteger(parentPid)) {
+      processes.push({ pid, parentPid, createdAt });
+    }
+  }
+  return processes;
+}
+
+/**
+ * True when the PID still names the same process we verified. Between listing
+ * and signalling there is a graceful-close window, and a `taskkill /T /F` on a
+ * recycled PID would tear down an unrelated process tree.
+ */
+function stillSameProcess(
+  exec: NonNullable<DesktopAppRestartIo["execFile"]>,
+  installLocation: string,
+  target: DesktopProcess,
+): boolean {
+  const processes = listPackageProcesses(exec, installLocation);
+  // Fail CLOSED on a failed re-probe: this guards a kill, and "we could not look" must not be
+  // read as "the pid was recycled and is now someone else's process".
+  if (processes === null) return false;
+  const current = processes.find(p => p.pid === target.pid);
+  return current !== undefined && current.createdAt === target.createdAt;
+}
+
+/** Roots are the package processes whose parent is not itself in the package tree. */
+function rootProcesses(processes: readonly DesktopProcess[]): DesktopProcess[] {
+  const inTree = new Set(processes.map(p => p.pid));
+  return processes.filter(p => !inTree.has(p.parentPid));
+}
+
+/**
+ * Full Windows parent chain for this process, innermost first.
+ *
+ * `process.ppid` is one level, which is not enough: a terminal hosted inside the
+ * desktop app sits several hops below `ChatGPT.exe`, so a one-level check would
+ * miss the exact case the guard exists for and we would terminate our own host.
+ * The chain therefore comes from CIM, with a bound so a corrupted parent cycle
+ * cannot spin.
+ */
+function windowsAncestryPids(exec: NonNullable<DesktopAppRestartIo["execFile"]>): number[] {
+  const chain: number[] = [process.pid];
+  let current = process.pid;
+  for (let hop = 0; hop < 16; hop++) {
+    let stdout: string;
+    try {
+      stdout = exec(resolveTrustedWindowsPowerShellExe(), [
+        "-NoProfile", "-NonInteractive", "-Command",
+        `$ErrorActionPreference='SilentlyContinue'; (Get-CimInstance Win32_Process -Filter "ProcessId=${current}").ParentProcessId`,
+      ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    } catch {
+      // An unreadable chain must not be read as "not our ancestor".
+      return [];
+    }
+    const parent = Number(stdout.trim());
+    if (!Number.isSafeInteger(parent) || parent <= 0 || chain.includes(parent)) break;
+    chain.push(parent);
+    current = parent;
+  }
+  return chain;
+}
+
+function defaultExecFile(file: string, args: readonly string[], options?: DesktopAppExecOptions): string {
+  return execFileSync(file, [...args], {
+    encoding: "utf-8",
+    timeout: options?.timeout ?? PROBE_TIMEOUT_MS,
+    windowsHide: options?.windowsHide ?? true,
+  });
+}
+
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultSleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function waitForExit(
+  pid: number,
+  timeoutMs: number,
+  isAlive: (pid: number) => boolean,
+  sleep: (ms: number) => void,
+  now: () => number,
+): boolean {
+  const deadline = now() + timeoutMs;
+  while (now() < deadline) {
+    if (!isAlive(pid)) return true;
+    sleep(250);
+  }
+  return !isAlive(pid);
+}
+
+/**
+ * Stop every package-tree root gracefully, force the stragglers, then relaunch
+ * through the discovered AUMID. Returns without relaunching if anything
+ * survived, because launching a second shell beside a stuck one is worse than
+ * leaving the user to restart it.
+ */
+export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult {
+  const platform = io.platform ?? process.platform;
+  const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({
+    attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason,
+  });
+  if (platform !== "win32") return skipped("windows_only");
+
+  const exec = io.execFile ?? defaultExecFile;
+  const pkg = discoverPackage(exec);
+  if (!pkg) return skipped("package_discovery_failed");
+
+  const processes = listPackageProcesses(exec, pkg.installLocation);
+  // A probe that could not run is not evidence of absence. Reporting it as `no_targets` told
+  // the user the app was not running and silently skipped the restart they asked for (#2557).
+  if (processes === null) return skipped("process_probe_failed");
+  const roots = rootProcesses(processes);
+  if (roots.length === 0) return skipped("no_targets");
+
+  const ancestryPids = io.ancestryPids ? io.ancestryPids() : windowsAncestryPids(exec);
+  if (ancestryPids.length === 0) {
+    // Fail closed: an unreadable ancestry chain cannot prove we are outside the
+    // tree we are about to terminate.
+    return skipped("self_ancestry");
+  }
+  const ancestry = new Set(ancestryPids);
+  if (processes.some(p => ancestry.has(p.pid))) {
+    // Terminating our own tree would kill this command mid-flight and leave the
+    // user with neither a restarted app nor an explanation.
+    return skipped("self_ancestry");
+  }
+
+  const isAlive = io.isAlive ?? defaultIsAlive;
+  const sleep = io.sleep ?? defaultSleep;
+  const now = io.now ?? (() => Date.now());
+  const stopped: number[] = [];
+  const surviving: number[] = [];
+
+  for (const root of roots) {
+    const pid = root.pid;
+    // Re-verify immediately before the graceful close: the listing is already
+    // one probe old.
+    if (!stillSameProcess(exec, pkg.installLocation, root)) {
+      stopped.push(pid);
+      continue;
+    }
+    try {
+      exec(resolveTrustedWindowsPowerShellExe(), [
+        "-NoProfile", "-NonInteractive", "-Command",
+        `$p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue; if ($p) { [void]$p.CloseMainWindow() }`,
+      ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    } catch {
+      /* a refused graceful close still gets the forced pass below */
+    }
+    if (waitForExit(pid, GRACEFUL_EXIT_TIMEOUT_MS, isAlive, sleep, now)) {
+      stopped.push(pid);
+      continue;
+    }
+    // The wait window is long enough for Windows to recycle a PID, and the next
+    // step is `/T /F` against a whole tree. Confirm the PID is still the process
+    // we verified, or leave it alone.
+    if (!stillSameProcess(exec, pkg.installLocation, root)) {
+      stopped.push(pid);
+      continue;
+    }
+    try {
+      exec(resolveTrustedWindowsTaskkillExe(), ["/PID", String(pid), "/T", "/F"], {
+        timeout: PROBE_TIMEOUT_MS, windowsHide: true,
+      });
+    } catch {
+      /* fall through to the liveness check: the process state decides, not the exit code */
+    }
+    if (waitForExit(pid, FORCED_EXIT_TIMEOUT_MS, isAlive, sleep, now)) stopped.push(pid);
+    else surviving.push(pid);
+  }
+
+  if (surviving.length > 0) {
+    return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" };
+  }
+
+  try {
+    exec(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Start-Process 'shell:AppsFolder\\${pkg.aumid}'`,
+    ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+  } catch {
+    return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" };
+  }
+  return { attempted: true, stopped, surviving, relaunch: "started" };
+}

package/src/codex/history-job.ts

@@ -109,7 +109,8 @@ export type CodexHistoryJobOutcome =
   | { readonly kind: "skipped" }
   | { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
-      readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason };
+      readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason;
+      readonly rows?: number; readonly files?: number };
 
 /**
  * Derive the durable history operation from admitted intent.
@@ -174,7 +175,14 @@ function isPlausibleWorkerResult(
         || message.reason === "desired_disabled" || message.reason === "desired_enabled";
     case "error":
       return typeof message.message === "string"
-        && (message.reason === undefined || message.reason === "busy" || message.reason === "permission");
+        && (message.rows === undefined || (Number.isSafeInteger(message.rows) && Number(message.rows) >= 0))
+        && (message.files === undefined || (Number.isSafeInteger(message.files) && Number(message.files) >= 0))
+        && ((message.rows === undefined && message.files === undefined)
+          || (message.rows !== undefined && message.files !== undefined))
+        && (message.reason === undefined
+          || message.reason === "busy"
+          || message.reason === "permission"
+          || message.reason === "integrity");
     default:
       return false;
   }
@@ -224,6 +232,7 @@ export function describeHistoryJobFailure(
     : surface === "recover-legacy"
       ? "the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command."
       : "the Codex app appears to be holding the history database. Close Codex and run `ocx restore` again.";
+  const busyStateText = "Codex history state is busy (database, backup manifest, or rollout file); this is not enough evidence to blame the Codex app. It is retried automatically while the proxy runs; run 'ocx doctor' before forcing another attempt.";
   if (outcome.kind === "blocked") {
     if (outcome.reason === "busy") return busyText;
     switch (outcome.reason) {
@@ -237,10 +246,22 @@ export function describeHistoryJobFailure(
         return "Codex integration is enabled, so the history operation was skipped.";
     }
   }
-  if (outcome.historyFailureReason === "busy") return busyText;
+  const partiallyChanged = (outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0;
+  if (partiallyChanged && outcome.historyFailureReason === "busy") {
+    return "Codex history metadata changed but did not converge because manifest finalization remained busy; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
+  }
+  if (partiallyChanged && outcome.historyFailureReason === "permission") {
+    return "Codex history metadata changed but did not converge because permission was denied while finalizing the manifest; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
+  }
+  if (outcome.historyFailureReason === "busy") return busyStateText;
   if (outcome.historyFailureReason === "permission") {
     return "permission was denied while writing Codex history; this is not a Codex app lock. Run 'ocx doctor'.";
   }
+  if (outcome.historyFailureReason === "integrity") {
+    return partiallyChanged
+      ? "the history backup or its restore target changed after a partial restore; the manifest was retained for review and safe retry. Run 'ocx doctor'."
+      : "the history backup or its restore target failed integrity checks; no unverified provider metadata was applied. Run 'ocx doctor'.";
+  }
   switch (outcome.reason) {
     case "worker-error":
       return `the history worker failed (${outcome.message}). Run 'ocx doctor'.`;
@@ -277,6 +298,9 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
       reason: "worker-error",
       message: redactWorkerMessage(result.message),
       ...(result.reason ? { historyFailureReason: result.reason } : {}),
+      ...(result.rows !== undefined && result.files !== undefined
+        ? { rows: result.rows, files: result.files }
+        : {}),
     };
   }
   return result.outcome === "skipped"
@@ -284,6 +308,11 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
     : { kind: "converged", rows: result.rows, files: result.files, ...(result.proof ? { proof: result.proof } : {}) };
 }
 
+/** Test seam for the parent-side Worker result classification contract. */
+export function classifyWorkerResultForTests(result: HistoryWorkerResult): CodexHistoryJobOutcome {
+  return classifyWorkerResult(result);
+}
+
 /**
  * Run one history unit in a Worker and join it before returning.
  *

package/src/codex/history-manifest.ts

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+
+/** Sources whose native OpenAI provenance can be restored exactly. */
+export const CODEX_HISTORY_RESUMABLE_SOURCES = ["cli", "vscode"] as const;
+
+export interface CodexHistoryBackupEntry {
+  id: string;
+  rolloutPath: string;
+  modelProvider: string;
+  source: string;
+  hasUserEvent: 0 | 1;
+}
+
+export interface CodexHistoryBackupManifest {
+  version: 1;
+  stateDbPath: string;
+  entries: Record<string, CodexHistoryBackupEntry>;
+}
+
+export type CodexHistoryManifestValidation =
+  | { readonly ok: true; readonly manifest: CodexHistoryBackupManifest }
+  | { readonly ok: false; readonly reason: "foreign-database" }
+  | {
+      readonly ok: false;
+      readonly reason: "schema";
+      readonly scope: "manifest" | "entry-shape" | "entry-provenance";
+    };
+
+function codexHistoryPathIdentity(path: string): string {
+  const canonical = resolve(path);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+/**
+ * Canonical identity used by both backup naming and manifest ownership checks.
+ * Windows paths are case-insensitive for this contract; other platforms keep
+ * the resolved path's case.
+ */
+export function codexHistoryStateDbIdentity(path: string): string {
+  return codexHistoryPathIdentity(path);
+}
+
+/** Stable, non-secret file-name component for one state database. */
+export function codexHistoryBackupId(stateDbPath: string): string {
+  return createHash("sha256")
+    .update(codexHistoryStateDbIdentity(stateDbPath))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/** Platform-aware identity comparison shared by database and rollout checks. */
+export function sameCodexHistoryPath(left: string, right: string): boolean {
+  return codexHistoryPathIdentity(left) === codexHistoryPathIdentity(right);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasAllowedProvenance(entry: Record<string, unknown>): boolean {
+  return (entry.modelProvider === "openai"
+      && CODEX_HISTORY_RESUMABLE_SOURCES.includes(
+        entry.source as (typeof CODEX_HISTORY_RESUMABLE_SOURCES)[number],
+      ))
+    || (entry.modelProvider === "opencodex" && entry.source === "exec");
+}
+
+/**
+ * Validate only the versioned data contract and database ownership identity.
+ * Filesystem type checks, reads, fingerprints, rollout inspection, SQLite, and
+ * mutation deliberately remain with the callers.
+ */
+export function validateCodexHistoryBackupManifest(
+  raw: unknown,
+  expectedStateDbPath: string,
+): CodexHistoryManifestValidation {
+  if (!isRecord(raw)
+    || raw.version !== 1
+    || typeof raw.stateDbPath !== "string"
+    || !raw.stateDbPath.trim()
+    || !isAbsolute(raw.stateDbPath)
+    || !isRecord(raw.entries)) {
+    return { ok: false, reason: "schema", scope: "manifest" };
+  }
+  if (!sameCodexHistoryPath(raw.stateDbPath, expectedStateDbPath)) {
+    return { ok: false, reason: "foreign-database" };
+  }
+
+  for (const [id, value] of Object.entries(raw.entries)) {
+    if (!isRecord(value)) {
+      return { ok: false, reason: "schema", scope: "entry-shape" };
+    }
+    if (!id
+      || value.id !== id
+      || typeof value.rolloutPath !== "string"
+      || !value.rolloutPath.trim()
+      || !isAbsolute(value.rolloutPath)
+      || typeof value.modelProvider !== "string"
+      || !value.modelProvider.trim()
+      || typeof value.source !== "string"
+      || !value.source.trim()
+      || typeof value.hasUserEvent !== "number"
+      || !Number.isSafeInteger(value.hasUserEvent)
+      || (value.hasUserEvent !== 0 && value.hasUserEvent !== 1)
+      || !hasAllowedProvenance(value)) {
+      return { ok: false, reason: "schema", scope: "entry-provenance" };
+    }
+  }
+
+  return { ok: true, manifest: raw as unknown as CodexHistoryBackupManifest };
+}