@yansigit/opencodex 2.31.2 → 2.32.0

package/src/codex/history-worker.ts

@@ -4,8 +4,8 @@
  * Everything mutable about history happens here, behind H: the SQLite rows, the
  * backup manifest, and every rollout patch. Those three do not share a
  * transaction — sync writes the manifest before its database transaction, and
- * restore writes rollouts, then the database, then the manifest
- * (`src/codex/history-provider.ts:606-648,656-698`) — so a busy timeout only
+ * restore preflights every rollout, applies database CAS before rollout changes inside one
+ * SQLite transaction, then consumes the manifest after exact readback — so a busy timeout only
  * ever serialized a third of a state transition. Holding H across the whole unit
  * is what stops an opposite-direction process overtaking through the other two.
  *
@@ -74,7 +74,8 @@ export type HistoryWorkerResult =
   | { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
       readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly type: "error"; readonly requestId: string; readonly jobId: string;
-      readonly message: string; readonly reason?: CodexHistoryFailureReason };
+      readonly message: string; readonly reason?: CodexHistoryFailureReason;
+      readonly rows?: number; readonly files?: number };
 
 const OPERATIONS: ReadonlySet<string> = new Set<CodexHistoryWorkerOperation>([
   "skip",
@@ -142,8 +143,9 @@ export function runHistoryUnitUnderLock(
         const proof = snapshotCodexHistoryNoop(message.canonicalStateDbPath, message.canonicalBackupPath);
         if (proof.kind === "verified-noop") return { verifiedNoop: proof } as const;
       }
-      // apply-opencodex routes history to opencodex; migrate/restore return it to
-      // native. The provider is derived from the operation, never from a caller.
+      // apply-opencodex routes history to opencodex; migrate/restore recover only
+      // manifest-backed original metadata. The provider is derived from the operation,
+      // never from a caller; only recover-legacy-openai force-labels bare routed rows.
       const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
       return writeHistoryProviderTransition(permit, target, provider);
     },
@@ -179,6 +181,7 @@ export function runHistoryUnitUnderLock(
       jobId,
       message: "history_transition_failed",
       ...(result.failureReason ? { reason: result.failureReason } : {}),
+      ...(result.rows > 0 || result.files > 0 ? { rows: result.rows, files: result.files } : {}),
     };
   }
   return {

package/src/codex/inject.ts

@@ -1105,8 +1105,8 @@ export async function injectCodexConfig(
         : legacyMode
           ? `  Codex resume history: ${history.rows} thread(s) made visible for opencodex; originals backed up for restore.\n`
           : migratedRows > 0
-            ? `  Codex resume history: ${migratedRows} legacy opencodex-tagged thread(s) migrated back to openai (one-time).\n`
-            : `  Codex resume history: untouched (threads keep their native openai tag).\n`;
+            ? `  Codex resume history: restored original provider metadata for ${migratedRows} manifest-backed thread(s) (one-time).\n`
+            : `  Codex resume history: no backed-up metadata pending; untracked routed history left unchanged.\n`;
   // A user-owned root openai_base_url means we did NOT install routing — say so honestly
   // instead of claiming the proxy route is active (catalog/fast_mode were still written).
   if (keptUserBaseUrl) {
@@ -1345,18 +1345,33 @@ export interface CodexNativeRestoreResult {
   };
 }
 
-function failedHistoryRestore(reason?: CodexHistoryFailureReason, detail?: string): CodexRestoreHistoryResult {
+function failedHistoryRestore(
+  reason?: CodexHistoryFailureReason,
+  detail?: string,
+  progress: { rows?: number; files?: number } = {},
+): CodexRestoreHistoryResult {
+  const rows = progress.rows ?? 0;
+  const files = progress.files ?? 0;
+  const changed = rows > 0 || files > 0;
   return {
     state: "failed",
-    changed: false,
+    changed,
     ...(reason ? { reason } : {}),
-    rows: 0,
-    files: 0,
+    rows,
+    files,
     ejectedRows: 0,
     message: reason === "permission"
-      ? "Codex resume history could NOT be restored because permission was denied."
+      ? changed
+        ? "Codex resume history changed but did NOT converge because permission was denied while finalizing the backup manifest; the manifest was retained for review and safe retry."
+        : "Codex resume history could NOT be restored because permission was denied."
       : reason === "busy"
-        ? "Codex resume history could NOT be restored — the Codex app appears to be holding the history database."
+        ? changed
+          ? "Codex resume history changed but did NOT converge because backup-manifest finalization remained busy; the manifest was retained for review and safe retry."
+          : detail ?? "Codex resume history could NOT be restored — the Codex app appears to be holding the history database."
+        : reason === "integrity"
+          ? changed
+            ? "Codex resume history changed but did NOT converge because the backup or target changed; the manifest was retained for review and safe retry."
+            : "Codex resume history could NOT be restored because the backup or restore target failed integrity checks; unverified provider metadata was left unchanged."
         : detail
           ? `Codex resume history could NOT be restored: ${detail}`
           : "Codex resume history could NOT be restored; the reason was not recorded. Run 'ocx doctor'.",
@@ -1378,9 +1393,18 @@ export function failedHistoryRestoreFromOutcome(
   outcome: Extract<CodexHistoryJobOutcome, { kind: "blocked" | "failed" }>,
 ): CodexRestoreHistoryResult {
   if (outcome.kind === "blocked" && outcome.reason === "busy") return failedHistoryRestore("busy");
-  if (outcome.kind === "failed" && outcome.historyFailureReason === "busy") return failedHistoryRestore("busy");
+  if (outcome.kind === "failed" && outcome.historyFailureReason === "busy") {
+    return failedHistoryRestore(
+      "busy",
+      describeHistoryJobFailure(outcome, "restore"),
+      { rows: outcome.rows, files: outcome.files },
+    );
+  }
   if (outcome.kind === "failed" && outcome.historyFailureReason === "permission") {
-    return failedHistoryRestore("permission");
+    return failedHistoryRestore("permission", undefined, { rows: outcome.rows, files: outcome.files });
+  }
+  if (outcome.kind === "failed" && outcome.historyFailureReason === "integrity") {
+    return failedHistoryRestore("integrity", undefined, { rows: outcome.rows, files: outcome.files });
   }
   return failedHistoryRestore(undefined, describeHistoryJobFailure(outcome, "restore"));
 }
@@ -1620,10 +1644,10 @@ export async function restoreNativeCodexAsync(
   }
   const history: CodexRestoreHistoryResult = outcome.kind === "converged"
     ? {
-        state: "ok", changed: outcome.rows > 0, rows: outcome.rows, files: outcome.files, ejectedRows: 0,
+        state: "ok", changed: outcome.rows > 0 || outcome.files > 0, rows: outcome.rows, files: outcome.files, ejectedRows: 0,
         message: outcome.rows > 0
-          ? `Resume history restored from opencodex backup (${outcome.rows} thread(s)).`
-          : "Codex resume history was already native.",
+          ? `Resume history metadata restored from opencodex backup (${outcome.rows} thread(s)); original providers preserved.`
+          : "No backed-up resume-history metadata was pending; untracked routed history was left unchanged.",
       }
     : outcome.kind === "skipped"
       ? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "Codex resume history was skipped." }
@@ -1685,16 +1709,16 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   const history: CodexRestoreHistoryResult = options.skipHistory
     ? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "History restoration runs asynchronously." }
     : rawHistory.failed
-      ? failedHistoryRestore(rawHistory.failureReason)
+      ? failedHistoryRestore(rawHistory.failureReason, undefined, rawHistory)
       : {
           state: "ok",
-          changed: rawHistory.rows > 0 || (rawHistory.ejectedRows ?? 0) > 0,
+          changed: rawHistory.rows > 0 || rawHistory.files > 0 || (rawHistory.ejectedRows ?? 0) > 0,
           rows: rawHistory.rows,
           files: rawHistory.files,
           ejectedRows: rawHistory.ejectedRows ?? 0,
           message: rawHistory.rows > 0
-            ? `Resume history restored from opencodex backup (${rawHistory.rows} thread(s)).`
-            : "Codex resume history was already native.",
+            ? `Resume history metadata restored from opencodex backup (${rawHistory.rows} thread(s)); original providers preserved.`
+            : "No backed-up resume-history metadata was pending; untracked routed history was left unchanged.",
         };
   const message = catalog.removed > 0
     ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
@@ -1724,10 +1748,14 @@ export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legac
   const busy =
     (outcome.kind === "blocked" && outcome.reason === "busy") ||
     (outcome.kind === "failed" && outcome.historyFailureReason === "busy");
-  const headline = legacyMode
-    ? "Codex resume history sync SKIPPED"
-    : busy
-      ? "Codex resume history migration deferred"
+  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/injected-marker.ts

@@ -22,7 +22,7 @@ export function tomlStringPattern(key: string): RegExp {
   // A basic string escapes backslashes, so a Windows path is stored doubled; reading
   // the raw bytes back returned a path that matched nothing on disk and made the
   // journal's recorded catalog path un-restorable (#1798).
-  return new RegExp(`^\\s*${keyToken}\\s*=\\s*("(?:\\\\.|[^"])*"|'[^']*')\\s*(?:#.*)?$`);
+  return new RegExp(`^\\s*${keyToken}\\s*=\\s*("(?:\\\\.|[^"\\\\])*"|'[^']*')\\s*(?:#.*)?$`);
 }
 
 export function rootTomlString(content: string, key: string): string | null {

package/src/codex/internal/history-writer.ts

@@ -5,9 +5,10 @@
  * This module exists because the mutations are spread across three surfaces that
  * do not share a transaction: SQLite rows, the backup manifest, and the rollout
  * files. `syncCodexHistoryProvider` writes the manifest BEFORE its database
- * transaction and patches rollouts inside it; restore writes rollouts, then the
- * database, then the manifest, then ejects again
- * (`src/codex/history-provider.ts:606-648,656-698`). A SQLite busy timeout
+ * transaction and patches rollouts inside it; restore preflights every rollout,
+ * applies database CAS before file changes in one SQLite transaction, then consumes the
+ * manifest after exact readback (`src/codex/history-provider.ts`). A
+ * SQLite busy timeout
  * serializes exactly one of those three, which is why an opposite-direction
  * process could overtake through the other two.
  *

package/src/codex/native-profile-startup.ts

@@ -3,6 +3,7 @@ import { clearAccountNeedsReauth } from "./account-runtime-state";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import {
   probeNativeProfileRecoveryState,
+  resolveNativeProfileContext,
   type NativeProfileRecoveryState,
 } from "./native-profile-store";
 import {
@@ -43,6 +44,8 @@ export interface NativeMainStartupGateDeps {
   probeRecoveryState?: typeof probeNativeProfileRecoveryState;
   owner?: NativeMainOwnerOptions;
   stageSweepIntervalMs?: number;
+  /** Test seam / activation-time revalidation for the ambient physical auth home. */
+  currentHomeId?: () => string | null;
 }
 
 export interface NativeMainStartupLifecycle {
@@ -51,6 +54,11 @@ export interface NativeMainStartupLifecycle {
   release(): Promise<void>;
 }
 
+export interface PreparedNativeMainStartupLifecycle {
+  readonly homeId: string;
+  start(): NativeMainStartupLifecycle;
+}
+
 let epoch = 0;
 let snapshot: NativeMainStartupGateSnapshot = { status: "ready", homeId: null };
 let settled: Promise<NativeMainStartupGateSnapshot> = Promise.resolve(snapshot);
@@ -75,6 +83,7 @@ interface StartupEntry {
 }
 const startupEntries = new Map<string, StartupEntry>();
 const serverLifecycles = new WeakMap<object, NativeMainStartupLifecycle>();
+const serverLifecycleReleases = new WeakMap<object, Promise<void>>();
 
 function ready(homeId: string | null): NativeMainStartupGateSnapshot {
   return { status: "ready", homeId };
@@ -311,14 +320,48 @@ export function startNativeMainStartupLifecycle(
   };
 }
 
+/** Resolve and pin the owned lifecycle target without acquiring ownership or creating artifacts. */
+export function prepareNativeMainStartupLifecycle(
+  deps: NativeMainStartupGateDeps = {},
+  homes?: { codexHome: string; configDir: string },
+): PreparedNativeMainStartupLifecycle | null {
+  let manager: NativeProfileManager;
+  try {
+    manager = deps.manager ?? new NativeProfileManager(homes);
+    if (homes) {
+      const expected = resolveNativeProfileContext(homes);
+      if (
+        manager.context.homeId !== expected.homeId
+        || manager.context.instanceId !== expected.instanceId
+      ) return null;
+    }
+  } catch {
+    return null;
+  }
+  const currentHomeId = deps.currentHomeId ?? (() => {
+      try { return resolveNativeProfileContext().homeId; } catch { return null; }
+    });
+  const pinnedDeps = { ...deps, manager };
+  return {
+    homeId: manager.context.homeId,
+    start: () => {
+      if (currentHomeId() !== manager.context.homeId) {
+        throw new Error("The native-main startup home changed after ownership inspection.");
+      }
+      return startNativeMainStartupLifecycle(pinnedDeps);
+    },
+  };
+}
+
 /**
  * How many times a service-ownership fence will re-ask before it stops asking (#2108).
  *
  * A host that is permanently unaskable must not re-probe on every request forever, and a
  * host that recovers usually does so within the first few. The budget belongs to the
- * REASON, not to an individual fence: raising a second fence deliberately does not hand
- * out a fresh allowance, or a caller looping over fences could spin the probe forever.
- * It is dropped when the last fence for that reason releases.
+ * live hook owner, not to an individual fence: raising a second fence deliberately does
+ * not hand out a fresh allowance, or a caller looping over fences could spin the probe
+ * forever. Spending or releasing that hook owner ends its budget generation; a later
+ * fence can install a new owner even if an older hookless fence is still draining.
  */
 export const NATIVE_MAIN_OWNERSHIP_RETRY_LIMIT = 5;
 
@@ -327,6 +370,11 @@ const serviceOwnershipReprobes = new Map<NativeMainServiceOwnershipBlockReason,
 
 interface ServiceOwnershipReprobe {
   readonly probe: () => NativeCodexOwnership;
+  readonly expectedHomeId: () => string | null;
+  readonly activate: () => NativeMainStartupLifecycle;
+  readonly adopt: (lifecycle: NativeMainStartupLifecycle) => boolean;
+  readonly discard: (lifecycle: NativeMainStartupLifecycle) => void;
+  activating: boolean;
   attempts: number;
   /** The fence that installed this hook; only its own release may drop the entry. */
   readonly owner: NativeMainStartupLifecycle;
@@ -334,6 +382,10 @@ interface ServiceOwnershipReprobe {
   readonly spend: () => void;
 }
 
+function releaseUnadoptedLifecycle(lifecycle: NativeMainStartupLifecycle): Promise<void> {
+  try { return Promise.resolve(lifecycle.release()).catch(() => {}); } catch { return Promise.resolve(); }
+}
+
 /** Test-only: the retry budget is module state and would otherwise leak across tests. */
 export function __resetNativeMainOwnershipRetries(): void {
   for (const entry of serviceOwnershipReprobes.values()) entry.attempts = 0;
@@ -359,23 +411,53 @@ function reprobeServiceOwnership(reason: NativeMainServiceOwnershipBlockReason):
   if (reason !== "ownership-unknown") return false;
   const entry = serviceOwnershipReprobes.get(reason);
   if (!entry) return false;
+  if (entry.activating) return false;
   if (entry.attempts >= NATIVE_MAIN_OWNERSHIP_RETRY_LIMIT) return false;
   entry.attempts += 1;
-  let answer: NativeCodexOwnership;
+  let activated: NativeMainStartupLifecycle | undefined;
+  let expectedHomeId: string | null = null;
+  entry.activating = true;
   try {
-    answer = entry.probe();
+    const answer = entry.probe();
+    if (answer !== "owned") return false;
+    expectedHomeId = entry.expectedHomeId();
+    if (expectedHomeId === null) return false;
+    // Ownership becoming knowable is not itself startup completion. Install the
+    // normal owner/recovery lifecycle while this fence is still held, so native
+    // traffic cannot get ahead of owner registration, journal recovery, auth-temp
+    // scrubbing, or the initial stage sweep.
+    activated = entry.activate();
   } catch {
-    // An inspection that throws is not evidence the host became ownable.
+    // Neither a failed inspection nor a failed activation is evidence that
+    // native-main is safe to admit. Keep the fence and retry hook intact.
+    return false;
+  } finally {
+    entry.activating = false;
+  }
+  if (
+    !activated
+    || activated.homeId === null
+    || activated.homeId !== expectedHomeId
+    || typeof activated.release !== "function"
+  ) {
+    if (activated && typeof activated.release === "function") entry.discard(activated);
+    return false;
+  }
+  if (serviceOwnershipReprobes.get(reason) !== entry || !entry.adopt(activated)) {
+    // Shutdown or a re-entrant release can retire this fence while activation
+    // runs. A lifecycle that was never attached to the server must not retain
+    // another owner reference in the background.
+    entry.discard(activated);
     return false;
   }
-  if (answer !== "owned") return false;
   // Release through the fence that installed this hook, and only that one.
   //
   // Several servers can hold a fence for the same reason while only one carries a hook, so
   // clearing the shared refcount here would unblock fences this probe never spoke for.
   // Decrementing here directly is just as wrong the other way: that fence's own release()
-  // would then pay a second time for one fence, leaving the count short. Delegating to the
-  // fence's idempotent release keeps exactly one payment per fence.
+  // would then pay a second time for one fence, leaving the count short. The
+  // fence's idempotent spend hook keeps exactly one payment per fence while the
+  // transitioned owned lifecycle remains attached until server shutdown.
   entry.spend();
   return true;
 }
@@ -395,22 +477,44 @@ function serviceOwnershipSnapshot(
 /** Close native-main admission without resolving or creating any CODEX_HOME artifacts. */
 export function blockNativeMainStartupForUnownedServiceHome(
   reason: NativeMainServiceOwnershipBlockReason,
-  options?: { reprobe?: () => NativeCodexOwnership },
+  options?: {
+    reprobe: () => NativeCodexOwnership;
+    expectedHomeId: string | (() => string | null);
+    startOwnedLifecycle: () => NativeMainStartupLifecycle;
+  },
 ): NativeMainStartupLifecycle {
   serviceOwnershipRefs.set(reason, (serviceOwnershipRefs.get(reason) ?? 0) + 1);
-  let released = false;
-  const lifecycle: NativeMainStartupLifecycle = {
-    homeId: null,
-    settled: Promise.resolve(serviceOwnershipSnapshot(reason)),
-    async release() {
-      if (released) return;
-      released = true;
-      const remaining = Math.max(0, (serviceOwnershipRefs.get(reason) ?? 0) - 1);
-      if (remaining === 0) serviceOwnershipRefs.delete(reason);
-      else serviceOwnershipRefs.set(reason, remaining);
-      if (serviceOwnershipReprobes.get(reason)?.owner === lifecycle) {
-        serviceOwnershipReprobes.delete(reason);
-      }
+  let fenceSpent = false;
+  let ownedLifecycle: NativeMainStartupLifecycle | undefined;
+  let releaseFlight: Promise<void> | undefined;
+  const orphanReleaseFlights = new Set<Promise<void>>();
+  let lifecycle!: NativeMainStartupLifecycle;
+  const blockedSettled = Promise.resolve(serviceOwnershipSnapshot(reason));
+  const spendFence = () => {
+    if (fenceSpent) return;
+    fenceSpent = true;
+    const remaining = Math.max(0, (serviceOwnershipRefs.get(reason) ?? 0) - 1);
+    if (remaining === 0) serviceOwnershipRefs.delete(reason);
+    else serviceOwnershipRefs.set(reason, remaining);
+    if (serviceOwnershipReprobes.get(reason)?.owner === lifecycle) {
+      serviceOwnershipReprobes.delete(reason);
+    }
+  };
+  lifecycle = {
+    get homeId() { return ownedLifecycle?.homeId ?? null; },
+    get settled() { return ownedLifecycle?.settled ?? blockedSettled; },
+    release() {
+      return releaseFlight ??= (async () => {
+        spendFence();
+        // A synchronous activator can re-enter release before its returned
+        // lifecycle is adopted or discarded. Let that call stack finish so the
+        // cleanup set is complete before this shared release flight drains it.
+        await Promise.resolve();
+        await ownedLifecycle?.release();
+        if (orphanReleaseFlights.size > 0) {
+          await Promise.allSettled([...orphanReleaseFlights]);
+        }
+      })();
     },
   };
   // Do NOT reset an existing budget: keying the reprobe by reason means a caller raising
@@ -418,12 +522,28 @@ export function blockNativeMainStartupForUnownedServiceHome(
   // the probe forever. But once the holder is gone its entry is removed above, so a LATER
   // fence installs its own hook — a server started after an earlier probe must not be left
   // needing `ocx restart`, which is the very symptom this exists to remove.
-  if (options?.reprobe && reason === "ownership-unknown" && !serviceOwnershipReprobes.has(reason)) {
+  if (options && reason === "ownership-unknown" && !serviceOwnershipReprobes.has(reason)) {
+    const expectedHomeId = options.expectedHomeId;
     serviceOwnershipReprobes.set(reason, {
       probe: options.reprobe,
+      expectedHomeId: typeof expectedHomeId === "function"
+        ? expectedHomeId
+        : () => expectedHomeId,
+      activate: options.startOwnedLifecycle,
+      adopt: activated => {
+        if (releaseFlight !== undefined || fenceSpent || ownedLifecycle !== undefined) return false;
+        ownedLifecycle = activated;
+        return true;
+      },
+      discard: activated => {
+        const flight = releaseUnadoptedLifecycle(activated);
+        orphanReleaseFlights.add(flight);
+        void flight.finally(() => orphanReleaseFlights.delete(flight));
+      },
+      activating: false,
       attempts: 0,
       owner: lifecycle,
-      spend: () => { void lifecycle.release(); },
+      spend: spendFence,
     });
   }
   return lifecycle;
@@ -434,10 +554,20 @@ export function bindNativeMainStartupLifecycle(server: object, lifecycle: Native
 }
 
 export async function releaseNativeMainStartupLifecycle(server: object): Promise<void> {
+  const existing = serverLifecycleReleases.get(server);
+  if (existing) return existing;
   const lifecycle = serverLifecycles.get(server);
   if (!lifecycle) return;
-  serverLifecycles.delete(server);
-  await lifecycle.release();
+  const flight = Promise.resolve().then(() => lifecycle.release());
+  serverLifecycleReleases.set(server, flight);
+  try {
+    await flight;
+  } finally {
+    if (serverLifecycleReleases.get(server) === flight) {
+      serverLifecycleReleases.delete(server);
+      serverLifecycles.delete(server);
+    }
+  }
 }
 
 export function isNativeMainTrafficBlocked(): boolean {

package/src/codex/native-residue.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import {
   closeSync,
   fstatSync,
@@ -17,6 +16,7 @@ import { Database } from "bun:sqlite";
 
 import { getConfigDir } from "../config";
 import { catalogHasRoutedEntries, parseCatalogJson } from "./catalog/parsing";
+import { codexHistoryBackupId, validateCodexHistoryBackupManifest } from "./history-manifest";
 import {
   hasInjectedCodexRouting,
   OCX_SECTION_MARKER,
@@ -559,18 +559,22 @@ function classifyHistoryDatabase(path: string): NativeRoutedResidueResult {
         return indeterminate("history", resolved.path, "history row has no provider metadata");
       }
     }
+    // A bare opencodex row is not proof that OpenCodex owns a reversible transition: it may
+    // belong to any routed provider and has no native target without the backup manifest.
+    // Keep detecting interrupted metadata on native rows, but let the manifest classifier
+    // below be the authority for provenance-backed routed rows.
     const rollouts = classifyReferencedRollouts(
       "history",
-      rows.map(row => ({ id: row.id, path: row.rollout_path })),
+      rows
+        .filter(row => row.model_provider !== "opencodex")
+        .map(row => ({ id: row.id, path: row.rollout_path })),
     );
     if (rollouts.kind !== "clean") return rollouts;
     const after = statSync(resolved.path);
     if (!sameStat(resolved.stat, after)) {
       return indeterminate("history", resolved.path, "history database changed while it was being observed");
     }
-    return rows.some(row => row.model_provider === "opencodex")
-      ? { kind: "residue", surface: "history", path: resolved.path }
-      : { kind: "clean" };
+    return { kind: "clean" };
   } catch (error) {
     return indeterminate("history", resolved.path, `unreadable history database: ${errorReason(error)}`);
   } finally {
@@ -579,11 +583,7 @@ function classifyHistoryDatabase(path: string): NativeRoutedResidueResult {
 }
 
 function historyBackupPath(stateDatabasePath: string): string {
-  const normalized = process.platform === "win32"
-    ? resolve(stateDatabasePath).toLowerCase()
-    : resolve(stateDatabasePath);
-  const id = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join(getConfigDir(), `codex-history-backup-${id}.json`);
+  return join(getConfigDir(), `codex-history-backup-${codexHistoryBackupId(stateDatabasePath)}.json`);
 }
 
 function classifyHistoryBackup(path: string, stateDatabasePath: string): NativeRoutedResidueResult {
@@ -596,32 +596,25 @@ function classifyHistoryBackup(path: string, stateDatabasePath: string): NativeR
   } catch (error) {
     return indeterminate("history-backup", read.path, `malformed history backup JSON: ${errorReason(error)}`);
   }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return indeterminate("history-backup", read.path, "history backup has an unknown shape");
+  const validated = validateCodexHistoryBackupManifest(parsed, stateDatabasePath);
+  if (!validated.ok && validated.reason === "foreign-database") {
+    return indeterminate("history-backup", read.path, "history backup names a different state database");
   }
-  const manifest = parsed as Record<string, unknown>;
-  if (manifest.version !== 1 || !manifest.entries || typeof manifest.entries !== "object" || Array.isArray(manifest.entries)) {
-    return indeterminate("history-backup", read.path, "history backup has an unknown shape");
-  }
-  if (typeof manifest.stateDbPath === "string") {
-    const expected = process.platform === "win32" ? resolve(stateDatabasePath).toLowerCase() : resolve(stateDatabasePath);
-    const actual = process.platform === "win32" ? resolve(manifest.stateDbPath).toLowerCase() : resolve(manifest.stateDbPath);
-    if (actual !== expected) {
-      return indeterminate("history-backup", read.path, "history backup names a different state database");
-    }
+  if (!validated.ok) {
+    return indeterminate(
+      "history-backup",
+      read.path,
+      validated.scope === "entry-shape"
+        ? "history backup entry has an unknown shape"
+        : validated.scope === "entry-provenance"
+          ? "history backup entry has invalid provenance metadata"
+          : "history backup has an unknown shape",
+    );
   }
-  const entries = Object.values(manifest.entries as Record<string, unknown>);
+  const entries = Object.entries(validated.manifest.entries);
   const references: RolloutReference[] = [];
-  for (const entry of entries) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-      return indeterminate("history-backup", read.path, "history backup entry has an unknown shape");
-    }
-    const candidate = entry as Record<string, unknown>;
-    if (typeof candidate.id !== "string" || !candidate.id
-      || typeof candidate.rolloutPath !== "string" || !candidate.rolloutPath) {
-      return indeterminate("history-backup", read.path, "history backup entry has an unknown rollout reference");
-    }
-    references.push({ id: candidate.id, path: candidate.rolloutPath });
+  for (const entry of Object.values(validated.manifest.entries)) {
+    references.push({ id: entry.id, path: entry.rolloutPath });
   }
   const rollouts = classifyReferencedRollouts("history-backup", references);
   if (rollouts.kind !== "clean") return rollouts;

package/src/combos/failover.ts

@@ -109,6 +109,28 @@ export function clearComboTargetCooldowns(comboId?: string): void {
 
 export type ComboFailureDecision = "hop" | "stop";
 
+function isModelLifecycleGone(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 410) return false;
+  const normalizedCode = code?.trim().toLowerCase().replaceAll("-", "_");
+  if ([
+    "model_deprecated",
+    "model_end_of_life",
+    "model_eol",
+    "model_not_found",
+    "model_retired",
+  ].includes(normalizedCode ?? "")) return true;
+  const text = message.toLowerCase();
+  return /\bmodel\b/.test(text) && (
+    /\bend[ -]of[ -]life\b/.test(text)
+    || /\bno longer available\b/.test(text)
+    || /\b(?:deprecated|retired|retirement|sunset|decommissioned)\b/.test(text)
+  );
+}
+
 export function comboFailureDecision(
   status: number,
   message: string,
@@ -119,6 +141,11 @@ export function comboFailureDecision(
   // Cyber policy is a hard non-retryable refusal — honor structured code even when
   // classificationText was truncated before the JSON code field.
   if (isCyberPolicyCode(options?.code)) return "stop";
+  // HTTP 410 is normally terminal. A model-specific lifecycle verdict is target-local,
+  // however: another provider/model in the declared combo can still serve the request.
+  // Require structured lifecycle code or explicit model+lifecycle prose so unrelated
+  // application-level 410 responses remain fail-closed.
+  if (isModelLifecycleGone(status, message, options?.code)) return "hop";
   const error = classifyError(status, "upstream_error", message);
   if (isCyberPolicyCode(error.code)) return "stop";
   // A local input-admission refusal (#1524) says "this candidate cannot fit the request",

package/src/compatibility/index.ts

@@ -0,0 +1,26 @@
+import { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+import type { CompatibilityManifestV1 } from "./manifest";
+
+export {
+  COMPATIBILITY_DISPOSITIONS,
+  COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
+  compatibilityManifestIssues,
+  defineCompatibilityManifest,
+} from "./manifest";
+export type {
+  CompatibilityClaimV1,
+  CompatibilityDisposition,
+  CompatibilityEvidenceKind,
+  CompatibilityEvidenceRefV1,
+  CompatibilityManifestV1,
+  CompatibilitySubjectV1,
+} from "./manifest";
+export { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+
+export const COMPATIBILITY_MANIFESTS: readonly CompatibilityManifestV1[] = Object.freeze([
+  OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST,
+]);
+
+export function getCompatibilityManifest(id: string): CompatibilityManifestV1 | undefined {
+  return COMPATIBILITY_MANIFESTS.find(manifest => manifest.id === id);
+}