@remodex/rmx 1.0.2

package/src/codex/history-provider.ts

@@ -0,0 +1,1075 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { zstdDecompressSync } from "node:zlib";
+import { Database } from "bun:sqlite";
+import { CODEX_HOME } from "./paths";
+import { atomicWriteFile, getConfigDir } from "../config";
+
+/**
+ * Cap for decompressing a lone `.jsonl.zst` rollout during quarantine restore.
+ * Bounds peak memory while reconstructing thread rows; never write the decoded
+ * JSONL to disk.
+ */
+export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+
+const STATE_DB_PATH = join(CODEX_HOME, "state_5.sqlite");
+/**
+ * The manifest that shadows one state database.
+ *
+ * Exported because the history job must resolve it at CALL time for a Worker
+ * that does not inherit this module's load-time constants — and must resolve it
+ * the same way, since a manifest addressed differently is a different manifest.
+ */
+export function historyBackupPathFor(stateDbPath: string): string {
+  const normalized = process.platform === "win32" ? resolve(stateDbPath).toLowerCase() : resolve(stateDbPath);
+  const id = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join(getConfigDir(), `codex-history-backup-${id}.json`);
+}
+const HISTORY_BACKUP_PATH = historyBackupPathFor(STATE_DB_PATH);
+const RESUMABLE_SOURCES = ["cli", "vscode"] as const;
+
+/**
+ * Open the live `state_5.sqlite` the way the Codex app expects a *secondary* writer to behave:
+ * wait on the WAL/file lock instead of failing instantly, so we never race the app's own
+ * connection pool into a half-applied checkpoint. The app opens this DB with `busy_timeout=5s`
+ * (see codex-rs `state::runtime::base_sqlite_options`); we mirror that here.
+ */
+let historyDbBusyTimeoutMs = 5000;
+
+/**
+ * Test-only knob: Windows CI can spend the FULL busy timeout on a transient file lock, which
+ * alone exceeds bun's 5s default per-test timeout. Tests shrink this so a busy DB fails fast
+ * into withHistoryRetry instead of stalling; production keeps the codex-rs-matching 5s.
+ */
+export function setHistoryDbBusyTimeoutForTests(ms: number): void {
+  historyDbBusyTimeoutMs = ms;
+}
+
+function openStateDb(stateDbPath: string): Database {
+  const db = new Database(stateDbPath);
+  try {
+    db.exec(`PRAGMA busy_timeout = ${historyDbBusyTimeoutMs}`);
+  } catch {
+    /* best-effort: an older sqlite without busy_timeout still works, just less politely */
+  }
+  return db;
+}
+
+/**
+ * Append one JSONL line to a rollout using an O_APPEND handle, exactly like the Codex app's own
+ * metadata writer (`append_rollout_item_to_path` in codex-rs `rollout/src/recorder.rs`).
+ *
+ * Why append instead of rewriting line 1:
+ * - The app caches the live session's append handle and only reopens it when the handle is gone
+ *   (codex-rs `RolloutWriterState::ensure_writer_open`). A temp+rename swap would orphan that
+ *   handle; an in-place truncate would race the app's concurrent appends and clip new turns.
+ * - The app folds metadata by replaying every `session_meta` line in file order, last-writer-wins
+ *   (codex-rs `apply_session_meta_from_item`), so a trailing `session_meta` overrides earlier ones.
+ *   Real rollouts already contain multiple `session_meta` lines for this reason.
+ * For legacy unnumbered rollouts, O_APPEND makes each write land at EOF atomically, so it composes
+ * with the app appending concurrently. Ordered/paginated rollouts remain writer-owned: a second
+ * writer cannot safely allocate their next ordinal. We do not touch mtime: a fresh mtime is correct
+ * here (the app uses mtime as the rollout's updated_at), and forcing it backwards could hide a real
+ * edit from list ordering.
+ */
+function appendRolloutLine(path: string, line: string): void {
+  const fd = openSync(path, "a");
+  try {
+    const buf = Buffer.from(line.endsWith("\n") ? line : `${line}\n`, "utf8");
+    let offset = 0;
+    while (offset < buf.length) {
+      offset += writeSync(fd, buf, offset, buf.length - offset, null);
+    }
+    try { fsyncSync(fd); } catch { /* best-effort durability */ }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Patch the `model_provider` value inside the FIRST line of a rollout *in place, length-preserving*.
+ *
+ * Why this exists in addition to {@link appendRolloutLine}: Codex resolves a thread's provider via
+ * two different readers. The SQLite replay path folds every `session_meta` line last-writer-wins
+ * (covered by appending a trailing meta), but `read_session_meta_line` reads only the FIRST line
+ * and `update_thread_metadata` clones it when the app later writes git/memory-mode metadata
+ * (codex-rs `thread-store/src/local/update_thread_metadata.rs`). If the first line still says
+ * `opencodex` after a native restore, that clone re-appends `opencodex` and last-writer-wins
+ * resurrects the routed provider. So a durable restore must also fix line 1.
+ *
+ * Safety: Codex parses each rollout line as `serde_json::from_str(line.trim())`, which tolerates
+ * insignificant JSON whitespace. We therefore replace the provider value and pad the removed bytes
+ * with spaces so the line's byte length is unchanged. Equal length means we can write at offset 0
+ * with no truncate and no inode swap, so this composes safely with the app's cached append handle.
+ * Only length-preserving shrinks are handled (e.g. "opencodex" -> "openai"); callers that would
+ * grow the value fall back to append-only, which is correct for the opencodex direction.
+ *
+ * Returns true when line 1 was patched, false when it could not be done safely (missing file,
+ * non-`session_meta` first line, id mismatch, value already correct, or a length-growing change).
+ */
+function patchFirstLineProviderInPlace(path: string, expectedId: string, provider: string): boolean {
+  if (!existsSync(path)) return false;
+  const fd = openSync(path, "r+");
+  try {
+    // Read the first line by growing the probe until we hit a newline. session_meta lines embed
+    // base_instructions and can be tens of KB; a fixed cap would silently skip the in-place patch
+    // (and fall back to append-only, re-opening the first-line-clone resurrection gap), so we read
+    // until the line actually ends rather than guessing a ceiling.
+    const CHUNK = 1 << 16;
+    const MAX_FIRST_LINE = 1 << 24; // 16 MiB hard stop so a newline-less/corrupt file can't OOM us.
+    let collected = Buffer.alloc(0);
+    let nlIndex = -1;
+    let pos = 0;
+    while (nlIndex === -1) {
+      const chunk = Buffer.alloc(CHUNK);
+      const read = readSync(fd, chunk, 0, CHUNK, pos);
+      if (read === 0) break; // EOF with no newline: single-line file, skip
+      collected = Buffer.concat([collected, chunk.subarray(0, read)]);
+      nlIndex = collected.indexOf(0x0a);
+      pos += read;
+      if (collected.length > MAX_FIRST_LINE) return false;
+    }
+    if (nlIndex === -1) return false; // no newline anywhere: skip
+    const firstLine = collected.subarray(0, nlIndex).toString("utf8");
+
+    const meta = parseSessionMetaLine(firstLine);
+    if (!meta) return false;
+    if (meta.record.payload.id !== expectedId) return false;
+    if (meta.record.payload.model_provider === provider) return false;
+
+    // Locate the exact `"model_provider":"<value>"` token (allowing whitespace after the colon).
+    const match = firstLine.match(/"model_provider"\s*:\s*"([^"\\]*)"/);
+    if (!match || match.index === undefined) return false;
+    const oldToken = match[0];
+    const newCore = `"model_provider":"${provider}"`;
+    if (Buffer.byteLength(newCore, "utf8") > Buffer.byteLength(oldToken, "utf8")) return false; // grow: not length-preserving
+    const pad = " ".repeat(Buffer.byteLength(oldToken, "utf8") - Buffer.byteLength(newCore, "utf8"));
+    const newToken = `${newCore}${pad}`;
+
+    const patchedLine = firstLine.slice(0, match.index) + newToken + firstLine.slice(match.index + oldToken.length);
+    // Length must be identical so the trailing bytes (newline + rest of file) are untouched.
+    if (Buffer.byteLength(patchedLine, "utf8") !== Buffer.byteLength(firstLine, "utf8")) return false;
+    // Sanity: the patched line must still parse and carry the new provider.
+    const reparsed = parseSessionMetaLine(patchedLine);
+    if (!reparsed || reparsed.record.payload.model_provider !== provider) return false;
+
+    const out = Buffer.from(patchedLine, "utf8");
+    let offset = 0;
+    while (offset < out.length) {
+      offset += writeSync(fd, out, offset, out.length - offset, offset);
+    }
+    try { fsyncSync(fd); } catch { /* best-effort durability */ }
+    return true;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export type CodexHistoryProvider = "openai" | "opencodex";
+
+export type CodexHistoryFailureReason = "busy" | "permission";
+
+export interface CodexHistorySyncResult {
+  rows: number;
+  files: number;
+  ejectedRows?: number;
+  /** Set when a lock/busy error survived retries and the sync was SKIPPED, not empty. */
+  failed?: true;
+  /** Why the retry budget was exhausted when `failed` is set. */
+  failureReason?: CodexHistoryFailureReason;
+}
+
+interface ThreadRow {
+  id: string;
+  rollout_path: string;
+  model_provider: string;
+  source: string;
+  has_user_event: number;
+}
+
+interface BackupEntry {
+  id: string;
+  rolloutPath: string;
+  modelProvider: string;
+  source: string;
+  hasUserEvent: number;
+  /** Model observed while the original codex-lb row was captured; used for compare-and-swap. */
+  codexLbOriginalModel?: string | null;
+  /** One-time marker: the adopted provider identity is now encoded in the task model slug. */
+  codexLbModelQualified?: boolean;
+}
+
+interface BackupManifest {
+  version: 1;
+  stateDbPath?: string;
+  entries: Record<string, BackupEntry>;
+}
+
+interface NativeRestoreTarget {
+  modelProvider: string;
+  source: string;
+  hasUserEvent: number;
+}
+
+interface ThreadRowWithModel extends ThreadRow {
+  model: string | null;
+}
+
+function threadsHaveModelColumn(db: Database): boolean {
+  const row = db.query<{ n: number }, []>(`
+    SELECT count(*) AS n
+    FROM pragma_table_info('threads')
+    WHERE name = 'model'
+  `).get();
+  return (row?.n ?? 0) > 0;
+}
+
+function qualifyCodexLbModel(model: string | null): string | null {
+  if (!model || model.includes("/")) return model;
+  return `codex-lb/${model}`;
+}
+
+function samePath(a: string, b: string): boolean {
+  const left = resolve(a);
+  const right = resolve(b);
+  return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+function readBackup(path: string, stateDbPath?: string): BackupManifest {
+  if (!existsSync(path)) return { version: 1, stateDbPath, entries: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<BackupManifest>;
+    if (parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== "object") {
+      return { version: 1, stateDbPath, entries: {} };
+    }
+    if (stateDbPath && typeof parsed.stateDbPath === "string" && !samePath(parsed.stateDbPath, stateDbPath)) {
+      return { version: 1, stateDbPath, entries: {} };
+    }
+    return { version: 1, stateDbPath: parsed.stateDbPath ?? stateDbPath, entries: parsed.entries };
+  } catch {
+    return { version: 1, stateDbPath, entries: {} };
+  }
+}
+
+function writeBackup(path: string, manifest: BackupManifest, stateDbPath?: string): void {
+  if (Object.keys(manifest.entries).length === 0) {
+    if (existsSync(path)) unlinkSync(path);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  atomicWriteFile(path, JSON.stringify({ ...manifest, stateDbPath: manifest.stateDbPath ?? stateDbPath }, null, 2) + "\n");
+}
+
+function rememberOriginal(manifest: BackupManifest, row: ThreadRow): void {
+  if (manifest.entries[row.id]) return;
+  const model = "model" in row
+    ? (typeof (row as ThreadRowWithModel).model === "string" ? (row as ThreadRowWithModel).model : null)
+    : undefined;
+  manifest.entries[row.id] = {
+    id: row.id,
+    rolloutPath: row.rollout_path,
+    modelProvider: row.model_provider,
+    source: row.source,
+    hasUserEvent: Number(row.has_user_event) || 0,
+    ...(model !== undefined ? { codexLbOriginalModel: model } : {}),
+  };
+}
+
+interface ParsedSessionMeta {
+  record: {
+    type?: unknown;
+    timestamp?: unknown;
+    ordinal?: unknown;
+    payload: { model_provider?: unknown; source?: unknown } & Record<string, unknown>;
+  };
+}
+
+/** Parse one JSONL line into a `session_meta` record, or null if it isn't one. */
+function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as ParsedSessionMeta["record"];
+  if (record.type !== "session_meta" || !record.payload || typeof record.payload !== "object") return null;
+  return { record };
+}
+
+/**
+ * Find the LAST `session_meta` line in a rollout, mirroring the app's last-writer-wins fold
+ * (codex-rs `apply_session_meta_from_item`). We base our patch on the most recent metadata so we
+ * never resurrect a stale provider that a later app-written `session_meta` already changed.
+ */
+export function readLatestSessionMeta(path: string): ParsedSessionMeta | null {
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line) continue;
+    if (!line.includes("\"session_meta\"")) continue;
+    const meta = parseSessionMetaLine(line);
+    if (meta) return meta;
+  }
+  return null;
+}
+
+/** Find the newest session metadata that belongs to one canonical task id. */
+function readLatestSessionMetaForId(path: string, expectedId: string): ParsedSessionMeta | null {
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || !line.includes("\"session_meta\"")) continue;
+    const meta = parseSessionMetaLine(line);
+    if (meta?.record.payload.id === expectedId) return meta;
+  }
+  return null;
+}
+
+/** Ordered rollouts must only be changed by Codex, which owns their ordinal allocation. */
+function isWriterOwnedRollout(record: ParsedSessionMeta["record"]): boolean {
+  return record.payload.history_mode === "paginated" || Object.hasOwn(record, "ordinal");
+}
+
+/**
+ * Fields needed to re-insert a production-shaped `threads` row from a rollout JSONL when a
+ * Phase-2 quarantine predates full `satellite-backup.json` thread snapshots.
+ *
+ * Uses the same last-writer-wins `session_meta` fold as {@link readLatestSessionMeta}, plus the
+ * first user-message preview (codex-rs `list.rs` / `EventMsg::UserMessage` path).
+ */
+export interface RolloutThreadFields {
+  id: string;
+  modelProvider: string;
+  source: string;
+  firstUserMessage: string;
+  hasUserEvent: number;
+  cwd?: string;
+  historyMode?: string;
+  cliVersion?: string;
+}
+
+function textFromContentParts(content: unknown): string | null {
+  if (typeof content === "string" && content.trim()) return content.trim();
+  if (!Array.isArray(content)) return null;
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as Record<string, unknown>;
+    if (typeof p.text === "string" && p.text.trim()) parts.push(p.text.trim());
+    else if (typeof p.input_text === "string" && p.input_text.trim()) parts.push(p.input_text.trim());
+  }
+  const joined = parts.join("\n").trim();
+  return joined || null;
+}
+
+/** Extract the first user-message preview from a rollout line, or null. */
+function extractUserMessagePreview(line: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as { type?: unknown; payload?: unknown };
+  const payload = record.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as Record<string, unknown>;
+
+  if (record.type === "event_msg") {
+    // codex-rs EventMsg::UserMessage — payload.type is "user_message" (or omitted in fixtures).
+    if (p.type === "user_message" || typeof p.message === "string") {
+      if (typeof p.message === "string" && p.message.trim()) return p.message.trim();
+      const fromContent = textFromContentParts(p.content);
+      if (fromContent) return fromContent;
+    }
+    return null;
+  }
+
+  if (record.type === "response_item") {
+    if (p.type === "message" && p.role === "user") {
+      return textFromContentParts(p.content);
+    }
+  }
+  return null;
+}
+
+/**
+ * Reconstruct thread identity + listing fields from a staged/restored rollout JSONL.
+ * Returns null when the file is missing or has no parseable `session_meta`.
+ *
+ * Accepts plain `.jsonl` or a lone `.jsonl.zst` (legacy Phase-2 quarantine). Compressed
+ * rollouts are decompressed in memory with {@link MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES};
+ * no decompressed copy is written to disk.
+ */
+export function readThreadFieldsFromRollout(path: string): RolloutThreadFields | null {
+  if (!path || !existsSync(path)) return null;
+  let raw: string;
+  try {
+    raw = path.endsWith(".zst")
+      ? decompressRolloutZstUtf8(path)
+      : readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  return parseThreadFieldsFromRolloutText(raw);
+}
+
+function decompressRolloutZstUtf8(
+  path: string,
+  maxBytes: number = MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES,
+): string {
+  const compressed = readFileSync(path);
+  const decoded = zstdDecompressSync(compressed as Uint8Array<ArrayBuffer>, {
+    maxOutputLength: maxBytes,
+  });
+  if (decoded.byteLength > maxBytes) {
+    throw new Error("rollout_zst_too_large");
+  }
+  return new TextDecoder().decode(decoded);
+}
+
+function parseThreadFieldsFromRolloutText(raw: string): RolloutThreadFields | null {
+  const lines = raw.split("\n");
+  let latest: ParsedSessionMeta | null = null;
+  let firstUserMessage = "";
+  for (const line of lines) {
+    if (!line) continue;
+    if (line.includes("\"session_meta\"")) {
+      const meta = parseSessionMetaLine(line);
+      if (meta) latest = meta;
+    }
+    if (!firstUserMessage) {
+      const preview = extractUserMessagePreview(line);
+      if (preview) firstUserMessage = preview;
+    }
+  }
+  if (!latest) return null;
+  const payload = latest.record.payload;
+  const id = typeof payload.id === "string" ? payload.id : "";
+  if (!id) return null;
+  const modelProvider = typeof payload.model_provider === "string" && payload.model_provider
+    ? payload.model_provider
+    : "openai";
+  const source = typeof payload.source === "string" && payload.source
+    ? payload.source
+    : "cli";
+  return {
+    id,
+    modelProvider,
+    source,
+    firstUserMessage,
+    hasUserEvent: firstUserMessage.trim() ? 1 : 0,
+    ...(typeof payload.cwd === "string" ? { cwd: payload.cwd } : {}),
+    ...(typeof payload.history_mode === "string" ? { historyMode: payload.history_mode } : {}),
+    ...(typeof payload.cli_version === "string" ? { cliVersion: payload.cli_version } : {}),
+  };
+}
+
+/**
+ * Make a thread's rollout reflect a provider/source change by APPENDING a new `session_meta` line,
+ * rather than rewriting line 1. The appended line clones the latest metadata payload (so no field
+ * is accidentally reset to empty) and applies only the requested changes. Returns false when the
+ * rollout is missing, has no parseable `session_meta`, its latest `session_meta` belongs to a
+ * different thread id, it uses Codex-owned ordinal ordering, or it already matches the desired
+ * values.
+ */
+function updateSessionMeta(
+  path: string,
+  expectedId: string,
+  patch: { provider?: string; source?: string },
+  options: { patchFirstLine?: boolean; findLatestMatchingId?: boolean } = {},
+): boolean {
+  if (!path || !existsSync(path)) return false;
+
+  const latest = options.findLatestMatchingId
+    ? readLatestSessionMetaForId(path, expectedId)
+    : readLatestSessionMeta(path);
+  if (!latest) return false;
+  const record = latest.record;
+
+  // The app ignores `session_meta` lines whose payload id != the canonical thread id
+  // (codex-rs `apply_session_meta_from_item`). Forked rollouts can embed a source session's
+  // metadata, so an id-mismatched latest line means we'd be cloning the wrong thread's meta and
+  // appending a line the app would discard. Skip rather than write a no-op/misleading line.
+  const payloadId = record.payload.id;
+  if (typeof payloadId !== "string" || payloadId !== expectedId) return false;
+
+  // Paginated rollouts require one globally increasing ordinal per record. Cloning this metadata
+  // would clone its old ordinal, while computing max + 1 would race Codex's live writer. Leave the
+  // rollout byte-identical and let the SQLite/provider migration proceed independently.
+  if (isWriterOwnedRollout(record)) return false;
+
+  let changed = false;
+  if (patch.provider !== undefined && record.payload.model_provider !== patch.provider) {
+    record.payload.model_provider = patch.provider;
+    changed = true;
+  }
+  if (patch.source !== undefined && record.payload.source !== patch.source) {
+    record.payload.source = patch.source;
+    changed = true;
+  }
+  if (!changed) return false;
+
+  // Cover Codex's *other* provider reader: `read_session_meta_line` reads only line 1, and the
+  // app clones it when writing later git/memory-mode metadata. Appending alone leaves a stale
+  // line-1 provider that the clone would re-append, so for a length-preserving provider change we
+  // also patch line 1 in place (no inode swap, no truncate). Best-effort: when it can't be done
+  // safely (e.g. a length-growing change), the trailing append below is still correct for the
+  // SQLite replay path.
+  if (patch.provider !== undefined && options.patchFirstLine !== false) {
+    try { patchFirstLineProviderInPlace(path, expectedId, patch.provider); } catch { /* best-effort line-1 patch */ }
+  }
+
+  // Refresh the line timestamp so the appended record reads as the newest metadata.
+  record.timestamp = new Date().toISOString();
+  appendRolloutLine(path, JSON.stringify(record));
+  return true;
+}
+
+function toNativeRestoreTarget(entry: BackupEntry): NativeRestoreTarget {
+  if (entry.modelProvider !== "opencodex") {
+    return {
+      modelProvider: entry.modelProvider,
+      source: entry.source,
+      hasUserEvent: entry.hasUserEvent,
+    };
+  }
+  return {
+    modelProvider: "openai",
+    source: entry.source === "exec" ? "cli" : entry.source,
+    hasUserEvent: 1,
+  };
+}
+
+function ejectRemainingOpencodexHistory(db: Database): { rows: number; files: number } {
+  const rows = db
+    .query<ThreadRow, []>(`
+      SELECT id, rollout_path, model_provider, source, has_user_event
+      FROM threads
+      WHERE model_provider = 'opencodex'
+        AND trim(coalesce(first_user_message, '')) != ''
+    `)
+    .all();
+
+  let files = 0;
+  for (const row of rows) {
+    try {
+      if (updateSessionMeta(row.rollout_path, row.id, {
+        provider: "openai",
+        source: row.source === "exec" ? "cli" : undefined,
+      })) files++;
+    } catch {
+      /* native restore should continue even if an old rollout is missing */
+    }
+  }
+
+  const restore = db.transaction(() => {
+    const update = db.query(`
+      UPDATE threads
+      SET model_provider = 'openai',
+          source = CASE WHEN source = 'exec' THEN 'cli' ELSE source END,
+          has_user_event = 1
+      WHERE id = ?
+    `);
+    for (const row of rows) update.run(row.id);
+  });
+  restore();
+  return { rows: rows.length, files };
+}
+
+/**
+ * Move Desktop tasks that still carry the adopted codex-lb provider identity onto the built-in
+ * openai identity used by loopback injection. The original rows are retained in the ordinary
+ * history manifest so restore can put codex-lb back exactly. Unlike the legacy opencodex eject,
+ * keep line 1 unchanged: it already contains the native codex-lb identity that restore needs,
+ * while the appended openai metadata is the active last-writer-wins value during mediation.
+ */
+export function migrateCodexLbHistoryToOpenai(
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  const retried = withHistoryRetryResult(() => {
+    const db = openStateDb(stateDbPath);
+    try {
+      const manifest = readBackup(backupPath, stateDbPath);
+      const hasModelColumn = threadsHaveModelColumn(db);
+      const backedTaskIds = new Set(Object.values(manifest.entries)
+        .filter(entry => entry.modelProvider === "codex-lb")
+        .map(entry => entry.id));
+      const rows = db
+        .query<ThreadRowWithModel, []>(`
+          SELECT id, rollout_path, model_provider, source, has_user_event,
+                 ${hasModelColumn ? "model" : "NULL"} AS model
+          FROM threads
+          WHERE model_provider IN ('codex-lb', 'openai')
+        `)
+        .all()
+        .filter(row => row.model_provider === "codex-lb" || backedTaskIds.has(row.id));
+      if (rows.length === 0) return { rows: 0, files: 0 };
+
+      const pendingRows = rows.filter(row => row.model_provider === "codex-lb");
+      if (pendingRows.length > 0) {
+        for (const row of pendingRows) rememberOriginal(manifest, row);
+        writeBackup(backupPath, manifest, stateDbPath);
+      }
+      // Backfill manifests written by versions that did not retain the selected model. Once this
+      // observation is persisted, every retry uses a compare-and-swap and cannot overwrite a newer
+      // Desktop/Android selection made between the database read and migration write.
+      let backfilledOriginalModel = false;
+      for (const row of rows) {
+        const entry = manifest.entries[row.id];
+        if (entry?.modelProvider !== "codex-lb"
+          || entry.codexLbModelQualified === true
+          || Object.hasOwn(entry, "codexLbOriginalModel")) continue;
+        entry.codexLbOriginalModel = row.model;
+        backfilledOriginalModel = true;
+      }
+      if (backfilledOriginalModel) writeBackup(backupPath, manifest, stateDbPath);
+      const modelNormalizationRows = rows.filter(row => {
+        const entry = manifest.entries[row.id];
+        return entry?.modelProvider === "codex-lb" && entry.codexLbModelQualified !== true;
+      });
+
+      let files = 0;
+      for (const row of rows) {
+        try {
+          if (updateSessionMeta(
+            row.rollout_path,
+            row.id,
+            { provider: "openai" },
+            { patchFirstLine: false, findLatestMatchingId: true },
+          )) files++;
+        } catch {
+          /* keep the database migration moving if an old rollout is missing or malformed */
+        }
+      }
+
+      if (pendingRows.length > 0 || modelNormalizationRows.length > 0) {
+        const update = db.transaction(() => {
+          const providerStatement = db.query(`
+            UPDATE threads
+            SET model_provider = 'openai'
+            WHERE id = ?
+              AND model_provider = 'codex-lb'
+          `);
+          for (const row of pendingRows) providerStatement.run(row.id);
+          if (hasModelColumn) {
+            const modelStatement = db.query(`
+              UPDATE threads
+              SET model = ?
+              WHERE id = ?
+                AND model IS ?
+            `);
+            for (const row of modelNormalizationRows) {
+              const entry = manifest.entries[row.id];
+              const original = entry?.codexLbOriginalModel ?? row.model;
+              const qualified = qualifyCodexLbModel(original);
+              if (row.model === original) modelStatement.run(qualified, row.id, original);
+            }
+          }
+        });
+        update();
+      }
+      if (modelNormalizationRows.length > 0) {
+        for (const row of modelNormalizationRows) {
+          const entry = manifest.entries[row.id];
+          if (entry) entry.codexLbModelQualified = true;
+        }
+        // Persist the idempotency marker only after the database transaction. If the process
+        // exits between them, the next pass safely observes an already-qualified model slug.
+        writeBackup(backupPath, manifest, stateDbPath);
+      }
+      const changedIds = new Set([
+        ...pendingRows.map(row => row.id),
+        ...modelNormalizationRows.map(row => row.id),
+      ]);
+      return { rows: changedIds.size, files };
+    } finally {
+      db.close();
+    }
+  });
+  return retried.ok
+    ? retried.value
+    : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+}
+
+export function classifyRecoverableHistoryError(error: unknown): CodexHistoryFailureReason | null {
+  const code = typeof error === "object" && error && "code" in error ? String((error as { code?: unknown }).code) : "";
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  if (code === "SQLITE_BUSY"
+    || code === "SQLITE_LOCKED"
+    || code === "EBUSY"
+    || message.includes("database is locked")
+    || message.includes("database is busy")
+    || message.includes("resource busy")) return "busy";
+  if (code === "EPERM"
+    || code === "EACCES"
+    || message.includes("operation not permitted")
+    || message.includes("permission denied")) return "permission";
+  return null;
+}
+
+export function isRecoverableHistoryError(error: unknown): boolean {
+  return classifyRecoverableHistoryError(error) !== null;
+}
+
+const HISTORY_RETRY_DELAY_MS = 500;
+const HISTORY_RETRY_ATTEMPTS = 2;
+
+/**
+ * Run a history mutation with one retry across recoverable lock/busy errors (the app's own
+ * connection holds `state_5.sqlite` in WAL with a 5 s busy_timeout; a transient writer
+ * usually clears within that window). Returns null when both attempts hit a recoverable
+ * error — callers surface that as `failed: true` instead of a silent no-op. Hard errors
+ * (corruption, programming bugs) still throw.
+ */
+function withHistoryRetryResult<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}):
+  | { ok: true; value: T }
+  | { ok: false; reason: CodexHistoryFailureReason } {
+  const sleepFn = io.sleepFn ?? Bun.sleepSync;
+  const attempts = Math.max(1, io.attempts ?? HISTORY_RETRY_ATTEMPTS);
+  const delayMs = io.delayMs ?? HISTORY_RETRY_DELAY_MS;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return { ok: true, value: fn() };
+    } catch (error) {
+      const reason = classifyRecoverableHistoryError(error);
+      if (!reason) throw error;
+      if (attempt >= attempts - 1) return { ok: false, reason };
+      try { sleepFn(delayMs); } catch { /* sleep is best-effort */ }
+    }
+  }
+}
+
+export function withHistoryRetry<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}): T | null {
+  const result = withHistoryRetryResult(fn, io);
+  return result.ok ? result.value : null;
+}
+
+/**
+ * True when a READONLY probe proves the openai-direction restore would be a no-op:
+ * zero threads still tagged opencodex AND an empty backup manifest. Used to skip the
+ * write-open entirely in the Design B steady state — on Windows the Codex app holds
+ * `state_5.sqlite` (WAL, busy_timeout 5s), so an unnecessary write open can stall for
+ * seconds and surface a false lock warning, while WAL always admits readers. A failed
+ * probe (locked even for readers / schema drift) returns false so callers fall through
+ * to the write attempt and keep today's behavior for genuinely unknown state.
+ */
+function openaiRestoreIsNoop(stateDbPath: string, backupPath: string): boolean {
+  const pending = countPendingOpencodexHistory(stateDbPath, backupPath);
+  return !pending.failed && pending.pendingRows === 0 && pending.backupEntries === 0;
+}
+
+export function syncCodexHistoryProvider(
+  provider: CodexHistoryProvider,
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+  opts: { skipWhenProvablyNoop?: boolean } = {},
+): CodexHistorySyncResult {
+  // Opt-in steady-state gate (Design B loopback callers only): default semantics of
+  // this exported API are unchanged — legacy stop/restore paths never pass the flag.
+  if (opts.skipWhenProvablyNoop && provider === "openai" && existsSync(stateDbPath)
+    && openaiRestoreIsNoop(stateDbPath, backupPath)) {
+    return { rows: 0, files: 0 };
+  }
+  const retried = withHistoryRetryResult(() => syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath));
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+}
+
+function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbPath: string, backupPath: string): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  if (provider === "openai") return restoreCodexHistoryProvider(stateDbPath, backupPath);
+
+  const db = openStateDb(stateDbPath);
+  try {
+    const placeholders = RESUMABLE_SOURCES.map(() => "?").join(",");
+    const openaiRows = db
+      .query<ThreadRow, string[]>(`
+        SELECT id, rollout_path, model_provider, source, has_user_event
+        FROM threads
+        WHERE model_provider = 'openai'
+          AND source IN (${placeholders})
+      `)
+      .all(...RESUMABLE_SOURCES);
+    const execRows = db
+      .query<ThreadRow, []>(`
+        SELECT id, rollout_path, model_provider, source, has_user_event
+        FROM threads
+        WHERE model_provider = 'opencodex'
+          AND source = 'exec'
+          AND trim(coalesce(first_user_message, '')) != ''
+      `)
+      .all();
+
+    const manifest = readBackup(backupPath, stateDbPath);
+    for (const row of [...openaiRows, ...execRows]) rememberOriginal(manifest, row);
+    writeBackup(backupPath, manifest, stateDbPath);
+
+    let files = 0;
+    for (const row of openaiRows) {
+      try {
+        if (updateSessionMeta(row.rollout_path, row.id, { provider: "opencodex" })) files++;
+      } catch {
+        /* best-effort; keep DB migration moving even if one old rollout is malformed */
+      }
+    }
+    for (const row of execRows) {
+      try {
+        if (updateSessionMeta(row.rollout_path, row.id, { source: "cli" })) files++;
+      } catch {
+        /* best-effort; keep DB migration moving even if one old rollout is malformed */
+      }
+    }
+
+    const update = db.transaction(() => {
+      const markUserEvent = db.query(`
+        UPDATE threads
+        SET has_user_event = 1
+        WHERE id = ?
+          AND trim(coalesce(first_user_message, '')) != ''
+      `);
+      for (const row of [...openaiRows, ...execRows]) markUserEvent.run(row.id);
+      db.query(`
+        UPDATE threads
+        SET model_provider = 'opencodex'
+        WHERE model_provider = 'openai'
+          AND source IN (${placeholders})
+      `).run(...RESUMABLE_SOURCES);
+      db.query(`
+        UPDATE threads
+        SET source = 'cli'
+        WHERE model_provider = 'opencodex'
+          AND source = 'exec'
+          AND trim(coalesce(first_user_message, '')) != ''
+      `).run();
+    });
+    update();
+
+    return { rows: openaiRows.length + execRows.length, files };
+  } finally {
+    db.close();
+  }
+}
+
+function restoreCodexHistoryProvider(
+  stateDbPath: string,
+  backupPath: string,
+  options: { preserveOriginalProviders?: ReadonlySet<string> } = {},
+): CodexHistorySyncResult {
+  const manifest = readBackup(backupPath, stateDbPath);
+  const preservedEntries: Record<string, BackupEntry> = {};
+  const entries: BackupEntry[] = [];
+  for (const entry of Object.values(manifest.entries)) {
+    if (options.preserveOriginalProviders?.has(entry.modelProvider)) {
+      preservedEntries[entry.id] = entry;
+    } else {
+      entries.push(entry);
+    }
+  }
+
+  const db = openStateDb(stateDbPath);
+  try {
+    if (entries.length === 0) {
+      const ejected = ejectRemainingOpencodexHistory(db);
+      return ejected.rows > 0 ? { rows: 0, files: ejected.files, ejectedRows: ejected.rows } : { rows: 0, files: 0 };
+    }
+
+    let files = 0;
+    for (const entry of entries) {
+      const target = toNativeRestoreTarget(entry);
+      try {
+        if (updateSessionMeta(entry.rolloutPath, entry.id, { provider: target.modelProvider, source: target.source })) files++;
+      } catch {
+        /* best-effort; keep DB restore moving even if one rollout disappeared */
+      }
+    }
+
+    const restore = db.transaction(() => {
+      if (threadsHaveModelColumn(db)) {
+        const update = db.query(`
+          UPDATE threads
+          SET model_provider = ?,
+              source = ?,
+              has_user_event = ?,
+              model = CASE
+                WHEN ? = 1 AND model LIKE 'codex-lb/%' THEN substr(model, length('codex-lb/') + 1)
+                ELSE model
+              END
+          WHERE id = ?
+        `);
+        for (const entry of entries) {
+          const target = toNativeRestoreTarget(entry);
+          update.run(
+            target.modelProvider,
+            target.source,
+            target.hasUserEvent,
+            entry.codexLbModelQualified === true ? 1 : 0,
+            entry.id,
+          );
+        }
+      } else {
+        const update = db.query(`
+          UPDATE threads
+          SET model_provider = ?,
+              source = ?,
+              has_user_event = ?
+          WHERE id = ?
+        `);
+        for (const entry of entries) {
+          const target = toNativeRestoreTarget(entry);
+          update.run(target.modelProvider, target.source, target.hasUserEvent, entry.id);
+        }
+      }
+    });
+    restore();
+    writeBackup(backupPath, { version: 1, stateDbPath, entries: preservedEntries }, stateDbPath);
+    const ejected = ejectRemainingOpencodexHistory(db);
+    return ejected.rows > 0
+      ? { rows: entries.length, files: files + ejected.files, ejectedRows: ejected.rows }
+      : { rows: entries.length, files };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Restore legacy Remodex history while mediation stays active, without consuming the native
+ * codex-lb identities retained for a later full restore. This is deliberately separate from the
+ * public native restore: stop/eject must still restore every provider exactly.
+ */
+export function restoreManagedOpenaiHistory(
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  const retried = withHistoryRetryResult(() => restoreCodexHistoryProvider(
+    stateDbPath,
+    backupPath,
+    { preserveOriginalProviders: new Set(["codex-lb"]) },
+  ));
+  return retried.ok
+    ? retried.value
+    : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+}
+
+export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  const retried = withHistoryRetryResult(() => {
+    const db = openStateDb(stateDbPath);
+    try {
+      return ejectRemainingOpencodexHistory(db);
+    } finally {
+      db.close();
+    }
+  });
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+}
+
+/**
+ * One-time Design-B migration: restore backed-up originals, then eject any remaining
+ * opencodex-tagged threads to openai. Thin wrapper over the restore path with a
+ * configurable retry budget — the daemon migration guardian uses `{ attempts: 1 }`
+ * per tick so a locked DB never stalls the event loop beyond one sqlite busy wait.
+ */
+export function migrateHistoryToOpenai(
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+  opts: { attempts?: number; delayMs?: number; sleepFn?: (ms: number) => void } = {},
+): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  // Steady-state gate: this migration is Design-B-specific (inject + guardian callers),
+  // and after the one-time migration every start would otherwise write-open the DB for
+  // nothing. A missing DB with a leftover backup manifest does NOT satisfy the gate
+  // (backupEntries > 0), so the guardian's fresh-reinstall re-count protection holds.
+  if (openaiRestoreIsNoop(stateDbPath, backupPath)) return { rows: 0, files: 0 };
+  const retried = withHistoryRetryResult(() => syncCodexHistoryProviderUnsafe("openai", stateDbPath, backupPath), opts);
+  return retried.ok ? retried.value : { rows: 0, files: 0, failed: true, failureReason: retried.reason };
+}
+
+export interface PendingHistoryCount {
+  /** Threads still tagged opencodex that the eject path WOULD move (mirrors its WHERE). */
+  pendingRows: number;
+  /** Entries still recorded in the backup manifest (restore targets). */
+  backupEntries: number;
+  /** Set when the DB could not be opened/read (locked); counts are then unknown, not zero. */
+  failed?: true;
+}
+
+/**
+ * Read-only migration progress probe for the guardian and `rmx doctor`. Opens sqlite
+ * readonly with a SHORT busy timeout so a locked DB cannot stall a daemon tick. The
+ * pending predicate mirrors ejectRemainingOpencodexHistory exactly — rows eject ignores
+ * (empty first_user_message) are not counted, so 0 really means "migration done".
+ */
+export function countPendingOpencodexHistory(stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): PendingHistoryCount {
+  let backupEntries = 0;
+  try {
+    const manifest = readBackup(backupPath, stateDbPath);
+    backupEntries = Object.keys(manifest.entries).length;
+  } catch { /* unreadable manifest counts as 0 — restore treats it the same way */ }
+
+  if (!existsSync(stateDbPath)) return { pendingRows: 0, backupEntries };
+  try {
+    const db = new Database(stateDbPath, { readonly: true });
+    try {
+      db.exec("PRAGMA busy_timeout = 100");
+      const row = db.query<{ n: number }, []>(`
+        SELECT count(*) AS n
+        FROM threads
+        WHERE model_provider = 'opencodex'
+          AND trim(coalesce(first_user_message, '')) != ''
+      `).get();
+      return { pendingRows: row?.n ?? 0, backupEntries };
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    if (isRecoverableHistoryError(error)) return { pendingRows: 0, backupEntries, failed: true };
+    // Schema drift (e.g. a future codex renames the table) is a "cannot know" too, not a crash.
+    return { pendingRows: 0, backupEntries, failed: true };
+  }
+}
+
+/**
+ * Read-only progress for the managed OpenAI migration. Preserved codex-lb manifest entries are
+ * restore state, not pending migration work; newly discovered codex-lb database rows are work.
+ */
+export function countPendingManagedOpenaiHistory(
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+): PendingHistoryCount {
+  let backupEntries = 0;
+  try {
+    const manifest = readBackup(backupPath, stateDbPath);
+    backupEntries = Object.values(manifest.entries)
+      .filter(entry => entry.modelProvider !== "codex-lb" || entry.codexLbModelQualified !== true)
+      .length;
+  } catch { /* unreadable manifest counts as 0 — migration treats it the same way */ }
+
+  if (!existsSync(stateDbPath)) return { pendingRows: 0, backupEntries };
+  try {
+    const db = new Database(stateDbPath, { readonly: true });
+    try {
+      db.exec("PRAGMA busy_timeout = 100");
+      const row = db.query<{ n: number }, []>(`
+        SELECT count(*) AS n
+        FROM threads
+        WHERE model_provider = 'codex-lb'
+           OR (model_provider = 'opencodex'
+               AND trim(coalesce(first_user_message, '')) != '')
+      `).get();
+      return { pendingRows: row?.n ?? 0, backupEntries };
+    } finally {
+      db.close();
+    }
+  } catch {
+    return { pendingRows: 0, backupEntries, failed: true };
+  }
+}