@yansigit/opencodex 2.31.0

package/src/codex/history-transition.ts

@@ -0,0 +1,105 @@
+/**
+ * Resolve the transition a history job belongs to.
+ *
+ * `updateCodexHistoryTransition` had no production caller, so every completed or
+ * skipped job left the coordinator row permanently `pending` — a transition was
+ * published and never resolved. This is that caller.
+ *
+ * The classification is `020_history_isolation.md:564-572`, applied rather than
+ * reinvented. The two unions do not line up one-to-one, so each outcome is
+ * mapped by hand: a cast across them would compile on the words they share and
+ * lie about the rest.
+ */
+import type { CodexHistoryJobOutcome } from "./history-job";
+import type { CodexHistoryState, CodexTransitionVersion } from "./convergence-types";
+import { updateCodexHistoryTransition } from "./transition-state";
+
+/** The retry budget for a contended terminal CAS. Bounded; never unbounded. */
+const TERMINAL_RETRY_ATTEMPTS = 3;
+const TERMINAL_RETRY_DELAY_MS = 250;
+
+function sleep(ms: number): void {
+  // The caller path here is synchronous after the awaited job, so a spin is the
+  // honest tool — awaiting would be, and this is short.
+  const until = Date.now() + ms;
+  while (Date.now() < until) { /* bounded */ }
+}
+
+function classify(outcome: CodexHistoryJobOutcome, txId: string | null): CodexHistoryState {
+  switch (outcome.kind) {
+    case "converged":
+      return {
+        status: "converged",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        // A zero is durable only when the worker proved the exact DB/manifest
+        // state while H was held. Without proof, keep the counts unknown. Keep
+        // `??`: `||` would discard a verified zero.
+        pendingRows: outcome.proof?.pendingRows ?? null,
+        backupEntries: outcome.proof?.backupEntries ?? null,
+      };
+    case "skipped":
+      // The user opting out is a completed decision, not a failure — converged
+      // with no reason. Marking it blocked would retry what they asked not to do.
+      return { status: "converged", attempts: 0, nextRetryAt: null, txId, pendingRows: null, backupEntries: null };
+    case "blocked":
+      return {
+        status: outcome.reason === "busy" ? "pending" : "blocked",
+        reason: outcome.reason === "busy" ? "db-busy"
+          : outcome.reason === "database" ? "unreadable"
+          : "permission",
+        attempts: 1,
+        // A busy unit retries; the others do not reschedule themselves.
+        nextRetryAt: outcome.reason === "busy"
+          ? new Date(Date.now() + TERMINAL_RETRY_DELAY_MS * 10).toISOString()
+          : null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+    case "failed":
+      return {
+        status: "unknown",
+        reason: outcome.reason === "timeout" ? "timeout"
+          : outcome.reason === "worker-died" ? "worker-died"
+          : "record-write-failed",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+  }
+}
+
+/**
+ * Publish the terminal state of a history job against the transition it belongs
+ * to. A `conflict` means a newer transition won and is deliberately left alone.
+ * A `busy` terminal CAS retries a bounded number of times; when that exhausts,
+ * the previously persisted `pending` schedule is left intact — the same update
+ * needs the lock that was busy, so it cannot record its own failure
+ * (`005_contract.md:277`), and the retry being out of attempts is itself a
+ * terminal observation.
+ */
+export function resolveCodexHistoryTransition(
+  receipt: CodexTransitionVersion,
+  outcome: CodexHistoryJobOutcome,
+): void {
+  const state = classify(outcome, receipt.currentTxId);
+  for (let attempt = 0; attempt < TERMINAL_RETRY_ATTEMPTS; attempt += 1) {
+    const result = updateCodexHistoryTransition(receipt, state);
+    if (result.kind === "updated") return;
+    if (result.kind === "conflict") {
+      // A newer transition already owns the row. Overwriting it would be the
+      // overtaken job overwriting the winner.
+      return;
+    }
+    if (result.reason === "busy") {
+      if (attempt + 1 < TERMINAL_RETRY_ATTEMPTS) sleep(TERMINAL_RETRY_DELAY_MS * (attempt + 1));
+      continue;
+    }
+    // database / unsafe-path: retried CAS will not help.
+    return;
+  }
+}

package/src/codex/history-worker.ts

@@ -0,0 +1,220 @@
+/**
+ * Worker-thread entry for the Codex history unit.
+ *
+ * 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
+ * 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.
+ *
+ * The message is deliberately thin, and it does NOT carry a direction. A caller
+ * saying which way history should move is exactly what the durable operation
+ * exists to prevent: `syncResumeHistory: false` means leave history alone, apply
+ * targets opencodex only in legacy mode, and legacy recovery is a different
+ * operation from generic restore. So the Worker is told which JOB to run and
+ * reads the operation from the coordinator row itself.
+ *
+ * Homes are carried explicitly because a Worker is a separate process: it does
+ * not inherit the module-load `CODEX_HOME` that `history-provider.ts` resolves
+ * at import time, so a request that leaned on those constants would silently
+ * address the wrong home.
+ *
+ * Design record: devlog/_fin/260804_codex_write_substrate/020_history_isolation.md.
+ */
+import { withHistoryWriteSerialization } from "./history-lock";
+import { loadConfig } from "../config";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  writeHistoryProviderTransition,
+  writeLegacyOpenaiHistoryRecovery,
+  type HistoryWriteTarget,
+} from "./internal/history-writer";
+import {
+  snapshotCodexHistoryNoop,
+  type CodexHistoryFailureReason,
+  type CodexHistoryVerifiedNoopProof,
+} from "./history-provider";
+
+/**
+ * The durable operation, mirrored into the request for diagnostics only.
+ *
+ * The Worker validates this against what it reads and refuses a mismatch rather
+ * than trusting it — a tampered copy must not be able to turn a restore into an
+ * apply. Structured-clone safe by construction: a closed set of string literals.
+ */
+export type CodexHistoryWorkerOperation =
+  | "skip"
+  | "apply-opencodex"
+  | "migrate-openai"
+  | "restore-openai"
+  | "recover-legacy-openai";
+
+export interface HistoryWorkerRunMessage {
+  readonly type: "run";
+  readonly requestId: string;
+  /** Opaque durable job identity; the Worker refuses work that is not current. */
+  readonly jobId: string;
+  readonly operation: CodexHistoryWorkerOperation;
+  readonly canonicalCodexHome: string;
+  readonly canonicalStateDbPath: string;
+  readonly canonicalBackupPath: string;
+  /** When set, prove this transition's desired direction while H is held. */
+  readonly expectedDesiredEnabled?: boolean;
+  /** Env snapshot: a Worker may not observe parent mutations on every platform. */
+  readonly env?: { readonly CODEX_HOME?: string; readonly OPENCODEX_HOME?: string };
+}
+
+export type HistoryWorkerResult =
+  | { readonly type: "done"; readonly requestId: string; readonly jobId: string;
+      readonly outcome: "converged" | "skipped";
+      readonly rows: number; readonly files: number;
+      readonly proof?: CodexHistoryVerifiedNoopProof }
+  | { 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 };
+
+const OPERATIONS: ReadonlySet<string> = new Set<CodexHistoryWorkerOperation>([
+  "skip",
+  "apply-opencodex",
+  "migrate-openai",
+  "restore-openai",
+  "recover-legacy-openai",
+]);
+
+/**
+ * Validate the message before it can reach a writer.
+ *
+ * A malformed message is dropped rather than coerced. Every field is required
+ * and non-empty: an absent path would otherwise fall back to a module-load
+ * constant that points at the wrong home in this process.
+ */
+export function isHistoryWorkerRunMessage(data: unknown): data is HistoryWorkerRunMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const message = data as Record<string, unknown>;
+  const nonEmpty = (value: unknown): value is string =>
+    typeof value === "string" && value.trim().length > 0;
+  return message.type === "run"
+    && nonEmpty(message.requestId)
+    && nonEmpty(message.jobId)
+    && typeof message.operation === "string"
+    && OPERATIONS.has(message.operation)
+    && nonEmpty(message.canonicalCodexHome)
+    && nonEmpty(message.canonicalStateDbPath)
+    && nonEmpty(message.canonicalBackupPath)
+    && (message.expectedDesiredEnabled === undefined || typeof message.expectedDesiredEnabled === "boolean");
+}
+
+/**
+ * Run one history operation under H.
+ *
+ * Exported so the unit can be exercised in-process; the Worker entry below is a
+ * thin adapter over it. `skip` is a real outcome rather than an absence: opting
+ * out of history resume must be recorded, not inferred from nothing happening.
+ */
+export function runHistoryUnitUnderLock(
+  message: HistoryWorkerRunMessage,
+): HistoryWorkerResult {
+  const { requestId, jobId, operation } = message;
+  const target: HistoryWriteTarget = {
+    canonicalStateDbPath: message.canonicalStateDbPath,
+    canonicalBackupPath: message.canonicalBackupPath,
+  };
+
+  if (operation === "skip") {
+    return { type: "done", requestId, jobId, outcome: "skipped", rows: 0, files: 0 };
+  }
+
+  const acquired = withHistoryWriteSerialization(
+    message.canonicalCodexHome,
+    message.canonicalStateDbPath,
+    permit => {
+      if (message.expectedDesiredEnabled !== undefined
+        && shouldSyncCodexOnStart(loadConfig()) !== message.expectedDesiredEnabled) {
+        return { desiredStateChanged: true as const };
+      }
+      if (operation === "recover-legacy-openai") {
+        return writeLegacyOpenaiHistoryRecovery(permit, target);
+      }
+      if (operation === "migrate-openai") {
+        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.
+      const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
+      return writeHistoryProviderTransition(permit, target, provider);
+    },
+  );
+
+  if (acquired.kind !== "completed") {
+    return { type: "blocked", requestId, jobId, reason: acquired.reason };
+  }
+  const result = acquired.value;
+  if ("desiredStateChanged" in result) {
+    return {
+      type: "blocked",
+      requestId,
+      jobId,
+      reason: message.expectedDesiredEnabled ? "desired_disabled" : "desired_enabled",
+    };
+  }
+  if ("verifiedNoop" in result) {
+    return {
+      type: "done",
+      requestId,
+      jobId,
+      outcome: "converged",
+      rows: 0,
+      files: 0,
+      proof: result.verifiedNoop,
+    };
+  }
+  if (result.failed === true) {
+    return {
+      type: "error",
+      requestId,
+      jobId,
+      message: "history_transition_failed",
+      ...(result.failureReason ? { reason: result.failureReason } : {}),
+    };
+  }
+  return {
+    type: "done",
+    requestId,
+    jobId,
+    outcome: "converged",
+    rows: result.rows,
+    files: result.files,
+  };
+}
+
+declare const self: Worker;
+
+// Guarded so the module can be imported directly by tests without a Worker host.
+if (typeof self !== "undefined" && typeof (self as { onmessage?: unknown }) === "object") {
+  self.onmessage = (event: MessageEvent<unknown>) => {
+    if (!isHistoryWorkerRunMessage(event.data)) return;
+    const message = event.data;
+    try {
+      if (message.env?.CODEX_HOME) process.env.CODEX_HOME = message.env.CODEX_HOME;
+      if (message.env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = message.env.OPENCODEX_HOME;
+      self.postMessage(runHistoryUnitUnderLock(message));
+    } catch (error) {
+      self.postMessage({
+        type: "error",
+        requestId: message.requestId,
+        jobId: message.jobId,
+        message: error instanceof Error ? error.message : "history_worker_failed",
+      } satisfies HistoryWorkerResult);
+    } finally {
+      // Close from inside the Worker so the thread begins exiting before the
+      // parent's terminate() races isolate realm reclaim on Windows.
+      try {
+        (self as unknown as { close?: () => void }).close?.();
+      } catch { /* already closing */ }
+    }
+  };
+}

package/src/codex/home.ts

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, posix, resolve, win32 } from "node:path";
+import { expandUserPath } from "../config";
+import { redactUserPath } from "../lib/redact";
+
+export type CodexHomeDeps = {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform | string;
+  release?: string;
+  procVersion?: string | null;
+  homedir?: () => string;
+  usersRoot?: string;
+  /** Raw /etc/wsl.conf content override (tests); null means "no file". */
+  wslConf?: string | null;
+  existsSync?: (path: string) => boolean;
+  readdirSync?: (path: string) => string[];
+  statSync?: typeof statSync;
+  realpathSync?: (path: string) => string;
+};
+
+function windowsUserProfileToWslPath(value: string | undefined, automountRoot = DEFAULT_WSL_AUTOMOUNT_ROOT): string | null {
+  if (!value) return null;
+  const normalized = value.replaceAll("\\", "/");
+  const match = normalized.match(/^([A-Za-z]):\/Users\/([^/]+)$/);
+  if (!match) return null;
+  const root = normalizeAutomountRoot(automountRoot);
+  return `${root === "/" ? "" : root}/${match[1]!.toLowerCase()}/Users/${match[2]}`;
+}
+
+const DEFAULT_WSL_AUTOMOUNT_ROOT = "/mnt";
+
+function normalizeAutomountRoot(value: string): string {
+  const trimmed = value.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+
+function readWslConf(): string | null {
+  try {
+    return readFileSync("/etc/wsl.conf", "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Windows drive mount root inside WSL: `[automount] root` from /etc/wsl.conf,
+ * default `/mnt` (https://learn.microsoft.com/en-us/windows/wsl/wsl-config).
+ * Returns a path without a trailing slash (or `/` itself).
+ */
+export function wslAutomountRoot(deps: CodexHomeDeps = {}): string {
+  const content = deps.wslConf !== undefined ? deps.wslConf : readWslConf();
+  if (!content) return DEFAULT_WSL_AUTOMOUNT_ROOT;
+  let section = "";
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.replace(/[#;].*$/, "").trim();
+    if (!line) continue;
+    const sect = line.match(/^\[(.+)\]$/);
+    if (sect) {
+      section = sect[1]!.trim().toLowerCase();
+      continue;
+    }
+    if (section !== "automount") continue;
+    const kv = line.match(/^root\s*=\s*(.+)$/i);
+    if (kv) {
+      const value = kv[1]!.trim().replace(/^["']|["']$/g, "");
+      if (!value.startsWith("/")) return DEFAULT_WSL_AUTOMOUNT_ROOT;
+      return normalizeAutomountRoot(value);
+    }
+  }
+  return DEFAULT_WSL_AUTOMOUNT_ROOT;
+}
+
+function readProcVersion(): string | null {
+  try {
+    return readFileSync("/proc/version", "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function isWslRuntime(deps: CodexHomeDeps = {}): boolean {
+  if ((deps.platform ?? process.platform) !== "linux") return false;
+  const env = deps.env ?? process.env;
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+  const version = `${deps.release ?? ""}\n${deps.procVersion ?? readProcVersion() ?? ""}`;
+  return /microsoft|wsl/i.test(version);
+}
+
+/** All Windows-profile `.codex` homes (with config.toml) visible from WSL, resolved real paths. */
+export function listWslWindowsCodexHomes(deps: CodexHomeDeps = {}): string[] {
+  if (!isWslRuntime(deps)) return [];
+  const exists = deps.existsSync ?? existsSync;
+  const stat = deps.statSync ?? statSync;
+  const readdir = deps.readdirSync ?? readdirSync;
+  const realpath = deps.realpathSync ?? realpathSync.native;
+  const automountRoot = wslAutomountRoot(deps);
+  // WSL mount paths are POSIX by definition; keep separators stable on any host.
+  const usersRoot = deps.usersRoot ?? posix.join(automountRoot, "c", "Users");
+  if (!exists(usersRoot)) return [];
+
+  const candidates = [];
+  try {
+    for (const user of readdir(usersRoot)) {
+      if (user === "Default" || user === "Default User" || user === "Public" || user === "All Users") continue;
+      const home = posix.join(usersRoot, user, ".codex");
+      const config = posix.join(home, "config.toml");
+      if (!exists(config)) continue;
+      try {
+        if (stat(home).isDirectory()) candidates.push(realpath(home));
+      } catch {
+        // Ignore unreadable Windows profiles.
+      }
+    }
+  } catch {
+    return [];
+  }
+  return candidates;
+}
+
+export function findWslWindowsCodexHome(deps: CodexHomeDeps = {}): string | null {
+  const env = deps.env ?? process.env;
+  const candidates = listWslWindowsCodexHomes(deps);
+  if (candidates.length === 0) return null;
+
+  const explicitProfile = windowsUserProfileToWslPath(env.USERPROFILE, wslAutomountRoot(deps));
+  if (explicitProfile) {
+    const explicitHome = posix.join(explicitProfile, ".codex");
+    const match = candidates.find(candidate => candidate === explicitHome || candidate.endsWith(`/${explicitProfile.split("/").pop()}/.codex`));
+    if (match) return match;
+  }
+  return candidates.length === 1 ? candidates[0]! : null;
+}
+
+export function defaultCodexHome(deps: CodexHomeDeps = {}): string {
+  const home = (deps.homedir ?? homedir)();
+  const defaultHome = join(home, ".codex");
+  const exists = deps.existsSync ?? existsSync;
+  const detected = !exists(join(defaultHome, "config.toml")) ? findWslWindowsCodexHome(deps) : null;
+  return detected ?? defaultHome;
+}
+
+export function resolveCodexHomeDir(deps: CodexHomeDeps = {}): string {
+  const raw = (deps.env ?? process.env).CODEX_HOME?.trim();
+  if (raw) return resolve(expandUserPath(raw));
+  return defaultCodexHome(deps);
+}
+
+export type OrcaCodexHomeDiagnostic = {
+  applicable: boolean;
+  mismatch: boolean;
+  effectiveCodexHome: string;
+  appCodexHome: string;
+  orcaCodexHome: string | null;
+  warning: string | null;
+  action: string | null;
+};
+
+type OrcaCodexHomeDeps = CodexHomeDeps & {
+  effectiveCodexHome?: string;
+  appCodexHome?: string;
+};
+
+function normalizedWindowsPath(path: string): string {
+  return path.trim().replaceAll("/", "\\").replace(/\\+$/, "").toLowerCase();
+}
+
+/**
+ * High-confidence Orca/ChatGPT dual-home diagnosis. Explicit CODEX_HOME remains
+ * authoritative; this only explains when an Orca-owned shell targets a home the
+ * Windows ChatGPT/Codex app does not read.
+ */
+export function collectOrcaCodexHomeDiagnostic(deps: OrcaCodexHomeDeps = {}): OrcaCodexHomeDiagnostic {
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const effectiveCodexHome = deps.effectiveCodexHome ?? resolveCodexHomeDir(deps);
+  const appCodexHome = deps.appCodexHome
+    ?? (platform === "win32" ? win32.join((deps.homedir ?? homedir)(), ".codex") : join((deps.homedir ?? homedir)(), ".codex"));
+  const explicitHome = env.CODEX_HOME?.trim() ?? "";
+  const orcaCodexHome = env.ORCA_CODEX_HOME?.trim() || null;
+  const normalizedEffective = normalizedWindowsPath(effectiveCodexHome);
+  const normalizedOrca = orcaCodexHome ? normalizedWindowsPath(orcaCodexHome) : "";
+  const normalizedApp = normalizedWindowsPath(appCodexHome);
+  const applicable = platform === "win32"
+    && !!explicitHome
+    && !!orcaCodexHome
+    && normalizedEffective === normalizedOrca
+    && /(?:^|\\)orca\\codex-runtime-home\\home$/i.test(normalizedOrca);
+  const mismatch = applicable && normalizedEffective !== normalizedApp;
+  const displayEffective = redactUserPath(effectiveCodexHome);
+  const displayApp = redactUserPath(appCodexHome);
+  const displayOrca = orcaCodexHome ? redactUserPath(orcaCodexHome) : null;
+  return {
+    applicable,
+    mismatch,
+    effectiveCodexHome: displayEffective,
+    appCodexHome: displayApp,
+    orcaCodexHome: displayOrca,
+    warning: mismatch
+      ? `CODEX_HOME targets Orca's runtime home (${displayEffective}), while the Windows ChatGPT/Codex app uses ${displayApp}; OpenCodex injection will not reach that app.`
+      : null,
+    action: mismatch
+      ? "If a service was installed from Orca, run 'ocx service uninstall' in that original Orca shell first. Then in Command Prompt run set \"ORCA_CODEX_HOME=\" and set \"CODEX_HOME=%USERPROFILE%\\.codex\"; or in PowerShell run Remove-Item Env:ORCA_CODEX_HOME -ErrorAction SilentlyContinue; $env:CODEX_HOME = Join-Path $env:USERPROFILE '.codex'. Rerun the command, then reinstall with 'ocx service install'."
+      : null,
+  };
+}