@iislee/opencodex 2.11.0 → 2.31.0

package/src/codex/log-guard/lock.ts

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+
+import { Database } from "bun:sqlite";
+
+import {
+  normalizeTrustedDarwinSystemAlias,
+  sameLogGuardPathIdentity,
+} from "./path-safety";
+import { isSqliteBusy } from "./sqlite-errors";
+
+import {
+  CodexUserIdentityRefusal,
+  resolveCodexCoordinatorDatabasePath,
+  resolveEffectiveUserIdentity,
+} from "../user-identity";
+
+export type CodexLogGuardLockOutcome<T> =
+  | { kind: "completed"; value: T }
+  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" };
+
+export interface CodexLogGuardLockDeps {
+  /** Test seam. Production resolves a dedicated DB in the trusted user runtime root. */
+  resolveDatabasePath?: (canonicalCodexHome: string, canonicalLogsDbPath: string) => string;
+}
+
+function lockFileIsSafe(path: string, requireRealpath: boolean): boolean {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) return false;
+  if (requireRealpath && !sameLogGuardPathIdentity(realpathSync.native(path), path)) return false;
+  if (process.platform === "win32") return true;
+  const uid = process.getuid?.();
+  return uid !== undefined && stat.uid === uid && (stat.mode & 0o777) === 0o600;
+}
+
+export function codexLogGuardLockDigest(
+  canonicalCodexHome: string,
+  canonicalLogsDbPath: string,
+): string {
+  const digestCodexHome = normalizeTrustedDarwinSystemAlias(canonicalCodexHome);
+  const digestLogsDbPath = normalizeTrustedDarwinSystemAlias(canonicalLogsDbPath);
+  return createHash("sha256")
+    .update(`${digestCodexHome.length}:${digestCodexHome}`)
+    .update(`${digestLogsDbPath.length}:${digestLogsDbPath}`)
+    .digest("hex");
+}
+
+function resolveLogGuardLockDatabase(
+  canonicalCodexHome: string,
+  canonicalLogsDbPath: string,
+): string {
+  if (!isAbsolute(canonicalCodexHome) || !isAbsolute(canonicalLogsDbPath)) {
+    throw new CodexUserIdentityRefusal("Codex Log Guard lock keys must be absolute paths.");
+  }
+
+  const identity = resolveEffectiveUserIdentity();
+  // Use the native-coordinator resolver only to enter the already-audited,
+  // environment-independent per-user runtime root. L itself is a different
+  // database in a sibling directory and never acquires N or H.
+  const coordinatorPath = resolveCodexCoordinatorDatabasePath(identity, canonicalCodexHome);
+  const runtimeRoot = dirname(dirname(coordinatorPath));
+  const locksDir = join(runtimeRoot, "log-guard-locks");
+  mkdirSync(locksDir, { recursive: true, mode: 0o700 });
+  const dirStat = lstatSync(locksDir);
+  if (!dirStat.isDirectory() || dirStat.isSymbolicLink()
+    || !sameLogGuardPathIdentity(realpathSync.native(locksDir), locksDir)) {
+    throw new CodexUserIdentityRefusal("Codex Log Guard lock directory is unsafe.");
+  }
+  if (process.platform !== "win32") {
+    const uid = process.getuid?.();
+    // `mkdirSync` applies `mode` only when it CREATES the directory, so a
+    // directory left by an earlier build (or a permissive umask on a older
+    // version) keeps its old permissions forever and every Log Guard mutation
+    // fails `unsafe_path` with no in-product way out. Tighten it ourselves when
+    // we own it, and only refuse if that cannot be achieved.
+    if (uid === undefined || dirStat.uid !== uid) {
+      throw new CodexUserIdentityRefusal("Codex Log Guard lock directory is not private to the effective user.");
+    }
+    if ((dirStat.mode & 0o777) !== 0o700) {
+      try {
+        chmodSync(locksDir, 0o700);
+      } catch {
+        throw new CodexUserIdentityRefusal("Codex Log Guard lock directory is not private to the effective user.");
+      }
+      // Re-read rather than trusting the chmod: a filesystem that ignores mode
+      // bits must still fail closed.
+      if ((lstatSync(locksDir).mode & 0o777) !== 0o700) {
+        throw new CodexUserIdentityRefusal("Codex Log Guard lock directory is not private to the effective user.");
+      }
+    }
+  }
+
+  return join(locksDir, `${codexLogGuardLockDigest(canonicalCodexHome, canonicalLogsDbPath)}.sqlite`);
+}
+
+export function withCodexLogGuardLock<T>(
+  canonicalCodexHome: string,
+  canonicalLogsDbPath: string,
+  work: () => T,
+  deps: CodexLogGuardLockDeps = {},
+): CodexLogGuardLockOutcome<T> {
+  let databasePath: string;
+  try {
+    databasePath = deps.resolveDatabasePath?.(canonicalCodexHome, canonicalLogsDbPath)
+      ?? resolveLogGuardLockDatabase(canonicalCodexHome, canonicalLogsDbPath);
+  } catch (error) {
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    return { kind: "unavailable", reason: "database" };
+  }
+
+  let database: Database | undefined;
+  let transactionOpen = false;
+  try {
+    let absent = false;
+    try {
+      if (!lockFileIsSafe(databasePath, false)) {
+        return { kind: "unavailable", reason: "unsafe-path" };
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException | undefined)?.code !== "ENOENT") throw error;
+      absent = true;
+    }
+
+    database = new Database(databasePath, { create: true });
+    if (absent) {
+      try { chmodSync(databasePath, 0o600); } catch { /* Windows permissions are enforced by the trusted runtime root. */ }
+    }
+    if (!lockFileIsSafe(databasePath, true)) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    const value = work();
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return { kind: "completed", value };
+  } catch (error) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close releases it */ }
+    }
+    if (isSqliteBusy(error)) return { kind: "unavailable", reason: "busy" };
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* acquisition already settled */ }
+  }
+}

package/src/codex/log-guard/maintenance.ts

@@ -0,0 +1,403 @@
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { Database, constants as sqliteConstants } from "bun:sqlite";
+
+import { getCodexHome, resolveCodexLogsDbPath } from "../paths";
+import { samePathIdentity } from "../user-identity";
+import { hasCurrentLogsSchema, inspectCodexLogs } from "./inspect";
+import { withCodexLogGuardLock, type CodexLogGuardLockOutcome } from "./lock";
+import { sameLogGuardPathIdentity } from "./path-safety";
+import { isSqliteBusy } from "./sqlite-errors";
+import { listRunningCodexProcesses, type CodexWriterProcessCheck } from "./processes";
+
+const CURRENT_LOG_COLUMNS = [
+  "id",
+  "ts",
+  "ts_nanos",
+  "level",
+  "target",
+  "feedback_log_body",
+  "module_path",
+  "file",
+  "line",
+  "thread_id",
+  "process_uuid",
+  "estimated_bytes",
+] as const;
+
+/**
+ * Budgets are expressed in BYTES and converted with the database's real page
+ * size, because that is what the guide promises: ~8 MiB per batch and ~256 MiB
+ * per run. Fixed page counts silently meant something different on every page
+ * size — at the 4 KiB pages the fixtures use, 512/8192 pages is 2 MiB/32 MiB,
+ * a quarter of the documented budget.
+ */
+const DEFAULT_BATCH_BYTES = 8 * 1024 * 1024;
+const DEFAULT_MAX_BYTES_PER_RUN = 256 * 1024 * 1024;
+const MAX_ITERATIONS = 64;
+
+/** Convert a byte budget to whole pages, never returning zero pages. */
+function pagesForBytes(bytes: number, pageSize: number): number {
+  if (!Number.isFinite(pageSize) || pageSize <= 0) return 1;
+  return Math.max(1, Math.floor(bytes / pageSize));
+}
+
+type CompactStopReason = "complete" | "page_budget" | "no_progress" | "busy";
+
+export interface CodexLogGuardCompactionMeasure {
+  databaseBytes: number;
+  /** On-disk WAL sidecar size at measurement time; FULL checkpoint does not imply shrinkage. */
+  walBytes: number;
+  pageCount: number;
+  freelistPages: number;
+  reclaimableBytes: number;
+}
+
+export interface CodexLogGuardCompactionReport {
+  pageSize: number;
+  before: CodexLogGuardCompactionMeasure;
+  after: CodexLogGuardCompactionMeasure;
+  pagesReclaimed: number;
+  /**
+   * Logical space returned to the free list, in bytes (`pagesReclaimed * pageSize`).
+   * Distinct from `physicalDatabaseBytesReclaimed`: an incremental vacuum can
+   * reclaim pages without the file shrinking, so a run that reports logical
+   * progress and zero physical shrinkage is normal rather than a failure. The
+   * guide documented this field before it existed.
+   */
+  logicalBytesReclaimed: number;
+  physicalDatabaseBytesReclaimed: number;
+  iterations: number;
+  complete: boolean;
+  stopReason: CompactStopReason;
+  integrity: { before: "ok"; after: "ok" };
+}
+
+export type CodexLogGuardCompactionError =
+  | "unsupported_schema"
+  | "codex_running"
+  | "process_enumeration_failed"
+  | "unsafe_path"
+  | "busy"
+  | "database_error"
+  | "auto_vacuum_not_incremental"
+  | "integrity_check_failed";
+
+export type CodexLogGuardCompactionResult =
+  | { ok: true; report: CodexLogGuardCompactionReport }
+  | {
+    ok: false;
+    error: Exclude<CodexLogGuardCompactionError, "integrity_check_failed">;
+  }
+  | { ok: false; error: "integrity_check_failed"; phase: "before" | "after" };
+
+export interface CodexLogGuardMaintenanceDeps {
+  codexHome?: string;
+  processCheck?: () => CodexWriterProcessCheck;
+  withLock?: <T>(
+    canonicalCodexHome: string,
+    canonicalLogsDbPath: string,
+    work: () => T,
+  ) => CodexLogGuardLockOutcome<T>;
+  quickCheck?: (db: Database) => string[];
+  openDatabase?: (databasePath: string, flags: number) => Database;
+  batchPages?: number;
+  maxPagesPerRun?: number;
+}
+
+interface ColumnRow { name: string }
+interface CheckpointRow {
+  busy?: number;
+  log?: number;
+  checkpointed?: number;
+}
+
+interface DatabaseFileIdentity {
+  dev: number;
+  ino: number;
+  realPath: string;
+}
+
+function databasePathIdentity(databasePath: string): DatabaseFileIdentity | null {
+  try {
+    const stat = lstatSync(databasePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return null;
+    const realPath = realpathSync.native(databasePath);
+    if (!sameLogGuardPathIdentity(realPath, databasePath)) return null;
+    return { dev: stat.dev, ino: stat.ino, realPath };
+  } catch {
+    return null;
+  }
+}
+
+function databasePathIsSafe(databasePath: string): boolean {
+  return databasePathIdentity(databasePath) !== null;
+}
+
+function databasePathStillMatches(
+  databasePath: string,
+  before: DatabaseFileIdentity,
+): boolean {
+  const after = databasePathIdentity(databasePath);
+  return after !== null
+    && after.dev === before.dev
+    && after.ino === before.ino
+    && samePathIdentity(after.realPath, before.realPath);
+}
+
+function exactCurrentSchema(db: Database): boolean {
+  // Same reasoning as protection.ts: the pre-mutation recheck must match the
+  // inspector's compatibility contract exactly, or Reclaim can vacuum a
+  // database the inspector classifies as monitor-only.
+  return hasCurrentLogsSchema(db);
+}
+
+function pragmaNumber(db: Database, sql: string): number {
+  const row = db.query<Record<string, unknown>, []>(sql).get();
+  if (!row) throw new Error(`missing pragma result for ${sql}`);
+  const value = Number(Object.values(row)[0]);
+  if (!Number.isFinite(value)) throw new Error(`invalid pragma result for ${sql}`);
+  return value;
+}
+
+function defaultQuickCheck(db: Database): string[] {
+  return db.query<Record<string, unknown>, []>("PRAGMA quick_check").all().map(row => {
+    const value = Object.values(row)[0];
+    return value === undefined ? "" : String(value);
+  });
+}
+
+function quickCheckIsOk(rows: string[]): boolean {
+  return rows.length === 1 && rows[0]?.trim().toLowerCase() === "ok";
+}
+
+function processRefusal(
+  check: CodexWriterProcessCheck,
+): "process_enumeration_failed" | "codex_running" | null {
+  if (check.state === "unknown") return "process_enumeration_failed";
+  if (check.processes.length > 0) return "codex_running";
+  return null;
+}
+
+function checkpointFull(db: Database): "ok" | "busy" {
+  const row = db.query<CheckpointRow, []>("PRAGMA wal_checkpoint(FULL)").get();
+  if (!row) throw new Error("missing wal_checkpoint result");
+  const values = Object.values(row).map(Number);
+  const busy = Number(row.busy ?? values[0] ?? 0);
+  const log = Number(row.log ?? values[1] ?? -1);
+  const checkpointed = Number(row.checkpointed ?? values[2] ?? -1);
+  if (busy !== 0) return "busy";
+  // SQLite returns -1/-1 when the database is not in WAL mode or there are no
+  // WAL frames to report. Otherwise FULL must have copied every frame.
+  if (log >= 0 && checkpointed >= 0 && checkpointed < log) return "busy";
+  return "ok";
+}
+
+function measure(databasePath: string, db: Database, pageSize: number): CodexLogGuardCompactionMeasure {
+  const databaseBytes = (() => {
+    try {
+      const stat = statSync(databasePath);
+      return stat.isFile() ? stat.size : 0;
+    } catch {
+      return 0;
+    }
+  })();
+  const walBytes = (() => {
+    try {
+      const stat = statSync(`${databasePath}-wal`);
+      return stat.isFile() ? stat.size : 0;
+    } catch {
+      return 0;
+    }
+  })();
+  const pageCount = pragmaNumber(db, "PRAGMA page_count");
+  const freelistPages = pragmaNumber(db, "PRAGMA freelist_count");
+  return {
+    databaseBytes,
+    walBytes,
+    pageCount,
+    freelistPages,
+    reclaimableBytes: pageSize * freelistPages,
+  };
+}
+
+function runCompaction(
+  databasePath: string,
+  deps: CodexLogGuardMaintenanceDeps,
+): CodexLogGuardCompactionResult {
+  let db: Database | undefined;
+  let probeOpen = false;
+  let reportBusyPartial: (() => CodexLogGuardCompactionResult) | undefined;
+  try {
+    const beforeOpenIdentity = databasePathIdentity(databasePath);
+    if (!beforeOpenIdentity) return { ok: false, error: "unsafe_path" };
+    const openDatabase = deps.openDatabase
+      ?? ((path: string, flags: number) => new Database(path, flags));
+    db = openDatabase(databasePath, sqliteConstants.SQLITE_OPEN_READWRITE);
+    // The path is user-writable foreign state. Re-check its regular-file,
+    // canonical-path and st_dev/st_ino identity immediately after SQLite opens
+    // it, before issuing any pragma or write-capable statement.
+    if (!databasePathStillMatches(databasePath, beforeOpenIdentity)) {
+      return { ok: false, error: "unsafe_path" };
+    }
+    db.exec("PRAGMA busy_timeout = 0");
+
+    if (!exactCurrentSchema(db)) return { ok: false, error: "unsupported_schema" };
+    if (pragmaNumber(db, "PRAGMA auto_vacuum") !== 2) {
+      return { ok: false, error: "auto_vacuum_not_incremental" };
+    }
+
+    const quickCheck = deps.quickCheck ?? defaultQuickCheck;
+    if (!quickCheckIsOk(quickCheck(db))) {
+      return { ok: false, error: "integrity_check_failed", phase: "before" };
+    }
+
+    // Confirm no SQLite writer can acquire the file before the first checkpoint.
+    // BEGIN IMMEDIATE is intentionally released before PRAGMA wal_checkpoint,
+    // which cannot run while this same connection holds a write transaction.
+    db.exec("BEGIN IMMEDIATE");
+    probeOpen = true;
+    db.exec("ROLLBACK");
+    probeOpen = false;
+
+    if (checkpointFull(db) === "busy") return { ok: false, error: "busy" };
+
+    const pageSize = pragmaNumber(db, "PRAGMA page_size");
+    const before = measure(databasePath, db, pageSize);
+    // Derived from the byte budgets AFTER reading the real page size, so the
+    // documented ~8 MiB batch / ~256 MiB run hold at any page size. Explicit
+    // page-count overrides still win, which is what the tests use.
+    const batchPages = Math.max(1, Math.floor(deps.batchPages ?? pagesForBytes(DEFAULT_BATCH_BYTES, pageSize)));
+    const maxPages = Math.max(batchPages, Math.floor(deps.maxPagesPerRun ?? pagesForBytes(DEFAULT_MAX_BYTES_PER_RUN, pageSize)));
+    let previousFreelist = before.freelistPages;
+    let pagesReclaimed = 0;
+    let iterations = 0;
+    let stopReason: CompactStopReason = previousFreelist === 0 ? "complete" : "page_budget";
+
+    const finish = (reason: CompactStopReason): CodexLogGuardCompactionResult => {
+      const after = measure(databasePath, db!, pageSize);
+      if (!quickCheckIsOk(quickCheck(db!))) {
+        return { ok: false, error: "integrity_check_failed", phase: "after" };
+      }
+      const complete = after.freelistPages === 0;
+      // If SQLITE_BUSY is thrown after an incremental_vacuum commit but before the
+      // loop can sample freelist_count, the before/after measurements still capture
+      // that committed logical reclamation. Never under-report already-landed work.
+      const observedPagesReclaimed = Math.max(
+        pagesReclaimed,
+        Math.max(0, before.freelistPages - after.freelistPages),
+      );
+      return {
+        ok: true,
+        report: {
+          pageSize,
+          before,
+          after,
+          pagesReclaimed: observedPagesReclaimed,
+          logicalBytesReclaimed: observedPagesReclaimed * pageSize,
+          physicalDatabaseBytesReclaimed: Math.max(0, before.databaseBytes - after.databaseBytes),
+          iterations,
+          complete,
+          stopReason: reason === "busy" ? "busy" : complete ? "complete" : reason,
+          integrity: { before: "ok", after: "ok" },
+        },
+      };
+    };
+    reportBusyPartial = () => iterations > 0 ? finish("busy") : { ok: false, error: "busy" };
+
+    while (previousFreelist > 0 && pagesReclaimed < maxPages && iterations < MAX_ITERATIONS) {
+      const pageBudget = Math.min(batchPages, maxPages - pagesReclaimed, previousFreelist);
+      if (pageBudget <= 0) {
+        stopReason = "page_budget";
+        break;
+      }
+      const priorFreelist = previousFreelist;
+      db.exec(`PRAGMA incremental_vacuum(${pageBudget})`);
+      iterations += 1;
+      const checkpoint = checkpointFull(db);
+      const currentFreelist = pragmaNumber(db, "PRAGMA freelist_count");
+      const reclaimed = Math.max(0, priorFreelist - currentFreelist);
+      pagesReclaimed += reclaimed;
+      previousFreelist = currentFreelist;
+
+      // incremental_vacuum has already committed by this point. A busy FULL
+      // checkpoint is therefore a partial-success stop, not an atomic refusal.
+      if (checkpoint === "busy") return finish("busy");
+      if (currentFreelist === 0) {
+        stopReason = "complete";
+        break;
+      }
+      if (currentFreelist >= priorFreelist) {
+        stopReason = "no_progress";
+        break;
+      }
+      stopReason = "page_budget";
+    }
+
+    if (previousFreelist > 0 && iterations >= MAX_ITERATIONS && stopReason !== "no_progress") {
+      // MAX_ITERATIONS is a bounded-work limit, not evidence that vacuum stalled.
+      stopReason = "page_budget";
+    }
+
+    // The preceding incremental-vacuum iterations checkpoint after every batch.
+    // One final FULL checkpoint backfills any remaining WAL frames before the
+    // final main-database measurement. FULL does not reset or shrink the WAL
+    // sidecar, so `after.walBytes` is an observational size, not reclaimed WAL.
+    if (checkpointFull(db) === "busy") {
+      return iterations > 0 ? finish("busy") : { ok: false, error: "busy" };
+    }
+    return finish(stopReason);
+  } catch (error) {
+    if (probeOpen) {
+      try { db?.exec("ROLLBACK"); } catch { /* close releases it */ }
+    }
+    if (isSqliteBusy(error)) {
+      // Mirror the explicit busy exits. Once at least one vacuum batch completed,
+      // a later thrown busy is a partial-success stop rather than a pure refusal.
+      if (reportBusyPartial) {
+        try { return reportBusyPartial(); } catch { /* fall through to refusal */ }
+      }
+      return { ok: false, error: "busy" };
+    }
+    return { ok: false, error: "database_error" };
+  } finally {
+    try { db?.close(); } catch { /* maintenance already settled */ }
+  }
+}
+
+export function compactCodexLogs(
+  deps: CodexLogGuardMaintenanceDeps = {},
+): CodexLogGuardCompactionResult {
+  const codexHome = deps.codexHome ?? getCodexHome();
+  const inspection = inspectCodexLogs({ codexHome });
+  const databasePath = resolveCodexLogsDbPath({ codexHome });
+  if (inspection.capabilities.reclaim.state !== "supported") {
+    return { ok: false, error: "unsupported_schema" };
+  }
+  if (!databasePathIsSafe(databasePath)) return { ok: false, error: "unsafe_path" };
+
+  const checkProcesses = deps.processCheck ?? listRunningCodexProcesses;
+  const firstRefusal = processRefusal(checkProcesses());
+  if (firstRefusal) return { ok: false, error: firstRefusal };
+
+  const withLock = deps.withLock ?? withCodexLogGuardLock;
+  let locked: CodexLogGuardLockOutcome<CodexLogGuardCompactionResult>;
+  try {
+    locked = withLock(codexHome, databasePath, () => {
+      const secondRefusal = processRefusal(checkProcesses());
+      if (secondRefusal) return { ok: false as const, error: secondRefusal };
+      return runCompaction(databasePath, deps);
+    });
+  } catch {
+    return { ok: false, error: "database_error" };
+  }
+
+  if (locked.kind === "unavailable") {
+    return {
+      ok: false,
+      error: locked.reason === "busy"
+        ? "busy"
+        : locked.reason === "unsafe-path" ? "unsafe_path" : "database_error",
+    };
+  }
+  return locked.value;
+}

package/src/codex/log-guard/path-safety.ts

@@ -0,0 +1,88 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+
+import { samePathIdentity } from "../user-identity";
+
+const TRUSTED_DARWIN_SYSTEM_ALIASES = [
+  { alias: "/var", canonical: "/private/var" },
+  { alias: "/tmp", canonical: "/private/tmp" },
+] as const;
+
+export function normalizeTrustedDarwinSystemAlias(path: string): string {
+  const requested = resolve(path);
+  if (process.platform !== "darwin") return requested;
+
+  for (const entry of TRUSTED_DARWIN_SYSTEM_ALIASES) {
+    if (requested !== entry.alias && !requested.startsWith(`${entry.alias}${sep}`)) continue;
+
+    let actualAliasTarget: string;
+    try {
+      actualAliasTarget = realpathSync.native(entry.alias);
+    } catch {
+      // If the platform alias is absent or unreadable, keep the strict spelling check.
+      return requested;
+    }
+    if (!samePathIdentity(actualAliasTarget, entry.canonical, "darwin")) return requested;
+    return `${entry.canonical}${requested.slice(entry.alias.length)}`;
+  }
+
+  return requested;
+}
+
+/**
+ * Compare a canonical realpath with a requested Log Guard path without treating
+ * macOS's OS-owned /var and /tmp aliases as user-controlled redirections.
+ * Arbitrary ancestor symlinks remain refused.
+ */
+export function sameLogGuardPathIdentity(realPath: string, requestedPath: string): boolean {
+  const requested = normalizeTrustedDarwinSystemAlias(requestedPath);
+  if (samePathIdentity(realPath, requested)) return true;
+  return sameWindowsCanonicalPath(realPath, requested);
+}
+
+/**
+ * On Windows, is the difference between these two spellings the OS canonicalizing the
+ * request rather than a redirection?
+ *
+ * `realpathSync.native` expands 8.3 short components — the `RUNNER~1` form that appears
+ * throughout `%TEMP%` — so the canonical path and the requested path can disagree as
+ * strings while naming the same file. Reading that as an ancestor-symlink redirection made
+ * every Log Guard mutation refuse with `unsafe_path` on Windows, which is what the CI shards
+ * were reporting.
+ *
+ * The first version of this re-canonicalized the requested path and compared the two
+ * canonical forms. That was wrong, and the Windows shard proved it: the caller already
+ * passes `realpathSync.native(requested)` as `realPath`, so re-resolving the request
+ * produced the same value on BOTH sides and a symlinked database compared equal. The
+ * widening let through exactly what the guard exists to refuse.
+ *
+ * The comparison is therefore link-aware. A short-name expansion rewrites the spelling of
+ * components that are all still directories on the same chain, so it is enough to require
+ * that no component of the request is a link: with none present, any remaining difference
+ * is the OS's own canonical spelling. A symlink or junction anywhere in the chain fails
+ * closed as before.
+ */
+function sameWindowsCanonicalPath(realPath: string, requestedPath: string): boolean {
+  if (process.platform !== "win32") return false;
+  try {
+    if (pathChainContainsLink(requestedPath)) return false;
+    return samePathIdentity(realPath, realpathSync.native(requestedPath));
+  } catch {
+    return false;
+  }
+}
+
+/** Is any component of this path a symlink or junction? Fails closed on an unreadable one. */
+function pathChainContainsLink(path: string): boolean {
+  let current = resolve(path);
+  for (;;) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) return true;
+    } catch {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}

package/src/codex/log-guard/policy.ts

@@ -0,0 +1,44 @@
+import { loadConfig, saveConfigPreservingClaudeCode } from "../../config";
+import type { OcxConfig } from "../../types";
+
+export type CodexLogGuardMode = "off" | "compat" | "quiet";
+
+type ConfigWithLogGuard = OcxConfig & {
+  codexLogGuard?: {
+    mode?: unknown;
+    [key: string]: unknown;
+  };
+};
+
+export interface CodexLogGuardPolicyDeps {
+  load?: () => OcxConfig;
+  save?: (config: OcxConfig) => void;
+}
+
+export function readCodexLogGuardMode(deps: CodexLogGuardPolicyDeps = {}): CodexLogGuardMode {
+  const config = (deps.load ?? loadConfig)() as ConfigWithLogGuard;
+  const mode = config.codexLogGuard?.mode;
+  return mode === "compat" || mode === "quiet" ? mode : "off";
+}
+
+/**
+ * Persist user intent separately from Codex's logs database.
+ *
+ * A Codex migration may rebuild the `logs` table and thereby remove our
+ * trigger. Keeping intent in OpenCodex config makes that observable as drift
+ * rather than silently treating protection as disabled. `off` is explicit so
+ * a stale unknown value cannot reactivate protection later.
+ */
+export function writeCodexLogGuardMode(
+  mode: CodexLogGuardMode,
+  deps: CodexLogGuardPolicyDeps = {},
+): void {
+  const load = deps.load ?? loadConfig;
+  const save = deps.save ?? saveConfigPreservingClaudeCode;
+  const config = load() as ConfigWithLogGuard;
+  const current = config.codexLogGuard && typeof config.codexLogGuard === "object"
+    ? config.codexLogGuard
+    : {};
+  config.codexLogGuard = { ...current, mode };
+  save(config);
+}