@yansigit/opencodex 2.31.3 → 2.32.0

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 };
+}

package/src/codex/history-migration-guardian.ts

@@ -2,11 +2,11 @@ import { migrateHistoryToOpenai } from "./history-provider";
 import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "./history-job";
 
 /**
- * Daemon-side retry for the one-time Design-B history migration.
+ * Daemon-side retry for the one-time Design-B history metadata restoration.
  *
  * Most upgrades run `ocx start` while the Codex app still holds `state_5.sqlite`,
- * so the inject-time migration often fails on the FIRST start — exactly the moment
- * every legacy thread is still tagged `opencodex` and invisible to the app. Instead
+ * so the inject-time restore can fail on the FIRST start while manifest-backed original
+ * metadata is still pending. Instead
  * of asking the user to close the app and rerun start, this guardian keeps retrying
  * in the background until the migration lands.
  *
@@ -77,7 +77,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
       if (!result.failed) {
         const moved = result.rows + ((result as { ejectedRows?: number }).ejectedRows ?? 0);
         if (moved > 0) {
-          log.log(`🩹 history-migration: ${moved} legacy opencodex thread(s) migrated back to openai.`);
+          log.log(`🩹 history-migration: restored original provider metadata for ${moved} manifest-backed thread(s).`);
         }
         // Zero mutations are authoritative only when the worker verified the
         // exact DB/manifest state while H was held.
@@ -92,7 +92,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
     }
     if (ticks >= maxTicks) {
       stopped = true;
-      log.log("⚠️ history-migration: Could not verify that legacy threads were migrated; the history database may be busy, unavailable, or not yet ready. Run 'ocx sync' (or check 'ocx doctor').");
+      log.log("⚠️ history-migration: Could not verify that backed-up provider metadata was restored; the history database may be busy, unavailable, or not yet ready. Run 'ocx sync' (or check 'ocx doctor').");
       return;
     }
     schedule();