@yansigit/opencodex 2.31.0

package/src/codex/history-lock.ts

@@ -0,0 +1,242 @@
+/**
+ * H — the cross-process history serialization primitive.
+ *
+ * Today a native apply or restore performs SQLite rows, the backup manifest and
+ * every rollout file on the caller thread, and the manifest and rollout writes
+ * sit OUTSIDE the provider's SQLite transaction
+ * (`src/codex/history-provider.ts:606-648,656-698`). A SQLite busy timeout
+ * therefore serializes one third of a state transition and explains one stall.
+ * H is held across the whole unit — DB, manifest and rollouts together — so an
+ * opposite-direction process cannot overtake through the unguarded files.
+ *
+ * Two ways H differs from K, both forced by review:
+ *
+ * `H -> N` is a real edge, not a violation. The Worker reads the coordinator row
+ * and writes its terminal state while holding H, and both take BEGIN IMMEDIATE
+ * on N. That is why H must be its own database: sharing N's would make the
+ * Worker contend with itself. `N -> H`, `K -> H` and `C -> H` are forbidden, and
+ * the resulting `H -> N -> K -> C` order was checked acyclic in review round 3.
+ *
+ * H is keyed by the canonical state database as well as the canonical home,
+ * because one CODEX_HOME can name a different `state_5.sqlite` and those are not
+ * the same exclusion (`src/codex/user-identity.ts`).
+ *
+ * The permit is a runtime registration, not a type. An opaque TypeScript brand
+ * proves a permit-bearing call path exists; it cannot prove the callback still
+ * holds the lock, and a permit leaked past its callback type-checks perfectly.
+ * So every history mutator asks this module at runtime whether the permit it was
+ * handed is still live for the state database it is about to write.
+ *
+ * Design record: devlog/_fin/260804_codex_write_substrate/005_contract.md §6.
+ */
+import { chmodSync, lstatSync, realpathSync } from "node:fs";
+
+import { Database } from "bun:sqlite";
+
+import {
+  CodexUserIdentityRefusal,
+  resolveCodexHistorySerializationDatabasePath,
+  resolveEffectiveUserIdentity,
+  samePathIdentity,
+} from "./user-identity";
+
+/**
+ * Authorization to perform history mutations inside ONE H acquisition.
+ *
+ * Deliberately carries no usable field. Holding this object is necessary and
+ * never sufficient: `assertHistoryWritePermit` decides, by looking the object up
+ * in a registry only this module can write. A forged cast, a prototype copy or a
+ * symbol clone produces a value of this type that every writer refuses.
+ */
+export interface HistoryWritePermit {
+  readonly [historyWritePermitBrand]: true;
+}
+
+declare const historyWritePermitBrand: unique symbol;
+
+export type HistorySerializationOutcome<T> =
+  | { kind: "completed"; value: T }
+  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" };
+
+export class HistoryWritePermitRefusal extends Error {
+  readonly code = "CODEX_HISTORY_WRITE_PERMIT_REFUSED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "HistoryWritePermitRefusal";
+  }
+}
+
+interface PermitRegistration {
+  readonly canonicalStateDbPath: string;
+  readonly transactionId: string;
+  live: boolean;
+}
+
+/**
+ * Registrations are marked dead, never deleted.
+ *
+ * Deleting would make a leaked permit indistinguishable from a forged one, and
+ * those are different bugs: "used after its acquisition released" points at a
+ * caller that kept a permit past its callback, while "never minted here" points
+ * at a cast or a clone. Both are refused; only the diagnosis differs. The map is
+ * weak, so a dead entry costs nothing once the permit is unreachable.
+ */
+const activePermits = new WeakMap<object, PermitRegistration>();
+let acquisitionCounter = 0;
+
+function isBusy(error: unknown): boolean {
+  const code = error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : "";
+  const message = error instanceof Error ? error.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+/**
+ * Refuse unless this exact permit is live for this exact state database.
+ *
+ * Every history mutator calls this BEFORE touching the database, the manifest or
+ * a rollout file. The state database is named by the caller rather than derived,
+ * because a rollout path can point anywhere the manifest recorded.
+ */
+export function assertHistoryWritePermit(
+  permit: HistoryWritePermit,
+  canonicalStateDbPath: string,
+): void {
+  const registration = activePermits.get(permit as unknown as object);
+  if (!registration) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit was not minted by the serialization owner.",
+    );
+  }
+  if (!registration.live) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit belongs to a released acquisition.",
+    );
+  }
+  if (registration.canonicalStateDbPath !== canonicalStateDbPath) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit authorizes a different Codex state database.",
+    );
+  }
+}
+
+/**
+ * Acquire H for one canonical state database and run `work` while it is held.
+ *
+ * The callback may enter N — that is the `H -> N` edge the Worker needs to read
+ * the coordinator row and publish its terminal state. It must never re-enter H.
+ *
+ * `busy_timeout = 0` with `BEGIN IMMEDIATE` makes contention fail fast and
+ * typed. Blocking here would hold the acquisition across an unbounded wait,
+ * which is the stall this phase exists to remove.
+ */
+export function withHistoryWriteSerialization<T>(
+  canonicalCodexHome: string,
+  canonicalStateDbPath: string,
+  work: (permit: HistoryWritePermit) => T,
+): HistorySerializationOutcome<T> {
+  let databasePath: string;
+  try {
+    databasePath = resolveCodexHistorySerializationDatabasePath(
+      resolveEffectiveUserIdentity(),
+      canonicalCodexHome,
+      canonicalStateDbPath,
+    );
+  } catch (error) {
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    return { kind: "unavailable", reason: "database" };
+  }
+
+  let database: Database | undefined;
+  let transactionOpen = false;
+  let registration: PermitRegistration | undefined;
+  let permit: HistoryWritePermit | undefined;
+
+  try {
+    let databaseWasAbsent = false;
+    try {
+      const before = lstatSync(databasePath);
+      if (before.isSymbolicLink() || !before.isFile()) {
+        return { kind: "unavailable", reason: "unsafe-path" };
+      }
+      if (process.platform !== "win32") {
+        const uid = process.getuid?.();
+        if (uid === undefined || before.uid !== uid || (before.mode & 0o777) !== 0o600) {
+          return { kind: "unavailable", reason: "unsafe-path" };
+        }
+      }
+    } catch (cause) {
+      const code = cause && typeof cause === "object" && "code" in cause
+        ? String((cause as { code?: unknown }).code)
+        : "";
+      if (code !== "ENOENT") throw cause;
+      databaseWasAbsent = true;
+    }
+
+    database = new Database(databasePath, { create: true });
+    if (databaseWasAbsent) {
+      try { chmodSync(databasePath, 0o600); } catch { /* Windows applies ACLs in WP11. */ }
+    }
+    const opened = lstatSync(databasePath);
+    if (opened.isSymbolicLink() || !opened.isFile()
+      || !samePathIdentity(realpathSync.native(databasePath), databasePath)) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+
+    acquisitionCounter += 1;
+    registration = {
+      canonicalStateDbPath,
+      transactionId: `${process.pid}:${acquisitionCounter}`,
+      live: true,
+    };
+    // A bare object: nothing about it is guessable or reconstructable, because
+    // the authority lives in the registry entry rather than in the value.
+    permit = {} as HistoryWritePermit;
+    activePermits.set(permit as unknown as object, registration);
+
+    let value: T;
+    try {
+      value = work(permit);
+    } finally {
+      // Revoke BEFORE releasing the transaction, so a mutator racing the release
+      // can never find a live permit without a live lock. This runs on the
+      // throwing path too, which is what a `finally`-less version gets wrong.
+      registration.live = false;
+    }
+
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return { kind: "completed", value };
+  } catch (error) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
+      transactionOpen = false;
+    }
+    if (registration?.live) {
+      registration.live = false;
+    }
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    if (isBusy(error)) return { kind: "unavailable", reason: "busy" };
+    // A callback failure is the caller's error, not a lock outcome: H acquired
+    // fine. Reporting it as `unavailable` would tell the caller to retry
+    // something that fails identically.
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* acquisition already finished */ }
+  }
+}
+
+/** Test-only: prove a leaked permit is dead without reaching into the registry. */
+export function isHistoryWritePermitLive(permit: HistoryWritePermit): boolean {
+  return activePermits.get(permit as unknown as object)?.live === true;
+}

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

@@ -0,0 +1,108 @@
+import { migrateHistoryToOpenai } from "./history-provider";
+import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "./history-job";
+
+/**
+ * Daemon-side retry for the one-time Design-B history migration.
+ *
+ * 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
+ * of asking the user to close the app and rerun start, this guardian keeps retrying
+ * in the background until the migration lands.
+ *
+ * Design constraints (audit-driven):
+ * - Ticks use `{ attempts: 1 }`: no sleepSync inside the daemon event loop; the tick
+ *   cadence IS the retry. Worst case per tick is one sqlite busy wait.
+ * - Timers are unref'd so the guardian never keeps the process alive.
+ * - Started ONLY from `ocx start` (cli handleStart), never from injectCodexConfig —
+ *   `/api/sync` re-runs inject and must not double-start loops.
+ */
+
+export interface HistoryMigrationGuardianHandle {
+  stop(): void;
+}
+
+export interface HistoryMigrationGuardianDeps {
+  migrateFn?: () => ReturnType<typeof migrateHistoryToOpenai>
+    | Promise<ReturnType<typeof migrateHistoryToOpenai>>;
+  log?: Pick<Console, "log">;
+  tickMs?: number;
+  maxTicks?: number;
+  /** Test hook: schedule fn after ms; return a cancel handle. Defaults to setTimeout. */
+  scheduleFn?: (fn: () => void, ms: number) => { cancel(): void };
+}
+
+const DEFAULT_TICK_MS = 60_000;
+const DEFAULT_MAX_TICKS = 60; // give up after ~an hour; doctor still surfaces the pending state
+
+function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
+  const timer = setTimeout(fn, ms);
+  if (typeof timer.unref === "function") timer.unref();
+  return { cancel: () => clearTimeout(timer) };
+}
+
+export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps = {}): HistoryMigrationGuardianHandle {
+  // The default migration goes through the history job, so the guardian's timer
+  // thread never performs the transition itself. A background repair that races
+  // an apply or a restore is exactly what H exists to order.
+  const migrateFn = deps.migrateFn ?? (async () => {
+    const outcome = await runCodexHistoryJob({
+      ...resolveCodexHistoryJobTarget(),
+      operation: "migrate-openai",
+    });
+    return outcome.kind === "converged"
+      ? { rows: outcome.rows, files: outcome.files, verifiedNoop: outcome.proof?.kind === "verified-noop" }
+      : { rows: 0, files: 0, failed: true as const };
+  });
+  const log = deps.log ?? console;
+  const tickMs = deps.tickMs ?? DEFAULT_TICK_MS;
+  const maxTicks = deps.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  let stopped = false;
+  let pending: { cancel(): void } | undefined;
+  let ticks = 0;
+
+  const schedule = () => {
+    if (stopped) return;
+    pending = (deps.scheduleFn ?? defaultSchedule)(tick, tickMs);
+  };
+
+  const tick = async () => {
+    if (stopped) return;
+    ticks++;
+    try {
+      // The worker re-derives state under H on every pass; no pre-lock probe is
+      // allowed to stop or suppress this attempt.
+      const result = await migrateFn();
+      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.`);
+        }
+        // Zero mutations are authoritative only when the worker verified the
+        // exact DB/manifest state while H was held.
+        const verifiedNoop = (result as { verifiedNoop?: boolean }).verifiedNoop === true;
+        if (moved > 0 || verifiedNoop) {
+          stopped = true;
+          return;
+        }
+      }
+    } catch {
+      /* hard errors are not retryable state — fall through to the tick budget */
+    }
+    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').");
+      return;
+    }
+    schedule();
+  };
+
+  schedule();
+  return {
+    stop() {
+      stopped = true;
+      pending?.cancel();
+    },
+  };
+}