@iislee/opencodex 2.11.0 → 2.31.0

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

@@ -0,0 +1,205 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+
+import {
+  listWindowsSnapshots,
+  tokenizeCommandLine,
+  type ProcessSnapshot,
+} from "../app-server-processes";
+
+export interface CodexWriterProcess {
+  pid: number;
+  commandLine: string;
+}
+
+export type CodexWriterProcessCheck =
+  | { state: "ok"; processes: CodexWriterProcess[] }
+  | { state: "unknown"; reason: "enumeration_failed" };
+
+export interface CodexWriterProcessIo {
+  platform?: NodeJS.Platform;
+  getuid?: () => number | undefined;
+  listSnapshots?: () => ProcessSnapshot[];
+}
+
+const TARGET_TRIPLE = /^[a-z0-9_]+-[a-z0-9_]+-[a-z0-9_]+(?:-[a-z0-9_]+)?$/i;
+
+function basename(token: string): string {
+  return token.replace(/\\/g, "/").split("/").pop()?.toLowerCase() ?? "";
+}
+
+function isOfficialCodexExecutable(token: string): boolean {
+  const base = basename(token);
+  if (base === "codex" || base === "codex.exe" || base === "codex.cmd") return true;
+  const withoutSuffix = base.replace(/\.(?:exe|cmd)$/i, "");
+  if (!withoutSuffix.startsWith("codex-")) return false;
+  return TARGET_TRIPLE.test(withoutSuffix.slice("codex-".length));
+}
+
+function isCodeModeHostExecutable(token: string): boolean {
+  const base = basename(token);
+  return base === "codex-code-mode-host" || base === "codex-code-mode-host.exe";
+}
+
+function isInterpreterExecutable(token: string): boolean {
+  const base = basename(token);
+  return base === "node" || base === "node.exe"
+    || base === "bun" || base === "bun.exe"
+    || base === "deno" || base === "deno.exe";
+}
+
+function looksLikePathPrefix(token: string): boolean {
+  return token.startsWith("/") || token.startsWith("./") || token.startsWith("../")
+    || token.startsWith("~") || /^[a-z]:[\\/]/i.test(token);
+}
+
+function flattenedPathPrefix(
+  commandLine: string,
+  predicate: (candidate: string) => boolean,
+): { executable: string; remainder: string } | null {
+  const parts = commandLine.trim().split(/\s+/).filter(Boolean);
+  for (let end = parts.length; end >= 1; end -= 1) {
+    const executable = parts.slice(0, end).join(" ");
+    if (!predicate(executable)) continue;
+    return { executable, remainder: parts.slice(end).join(" ") };
+  }
+  return null;
+}
+
+function interpreterHostWithFlattenedPath(commandLine: string, tokens: readonly string[]): boolean {
+  if (tokens.length < 2 || !isInterpreterExecutable(tokens[0]!)) return false;
+  const trimmed = commandLine.trim();
+  const firstWhitespace = trimmed.search(/\s/);
+  if (firstWhitespace < 0) return false;
+  const remainder = trimmed.slice(firstWhitespace).trim();
+  return flattenedPathPrefix(remainder, isCodeModeHostExecutable) !== null;
+}
+
+/**
+ * Match official Codex writer executables at argv0 plus the repository's
+ * established interpreter-entrypoint form for code-mode-host.
+ *
+ * OS process listings can flatten argv into a display string. When an unquoted
+ * executable path contains spaces, recover only a leading path-shaped executable
+ * prefix; arbitrary later argv tokens still never turn a process into Codex.
+ */
+export function isCodexWriterCommandLine(commandLine: string, executable?: string): boolean {
+  if (executable && (isOfficialCodexExecutable(executable) || isCodeModeHostExecutable(executable))) return true;
+  const tokens = tokenizeCommandLine(commandLine.trim());
+  if (tokens.length === 0) return false;
+  if (isOfficialCodexExecutable(tokens[0]!) || isCodeModeHostExecutable(tokens[0]!)) return true;
+  return tokens.length > 1
+    && isInterpreterExecutable(tokens[0]!)
+    && isCodeModeHostExecutable(tokens[1]!);
+}
+
+function statusUid(status: string): number | undefined {
+  const match = /^Uid:\s+(\d+)/m.exec(status);
+  if (!match) return undefined;
+  const value = Number(match[1]);
+  return Number.isSafeInteger(value) ? value : undefined;
+}
+
+function listLinuxSnapshots(uid: number | undefined): ProcessSnapshot[] {
+  if (!existsSync("/proc")) throw new Error("procfs_unavailable");
+  const rows: ProcessSnapshot[] = [];
+  for (const entry of readdirSync("/proc")) {
+    if (!/^\d+$/.test(entry)) continue;
+    const pid = Number(entry);
+    if (!Number.isSafeInteger(pid) || pid <= 0) continue;
+    try {
+      const procUid = statusUid(readFileSync(`/proc/${pid}/status`, "utf8"));
+      if (uid !== undefined && procUid !== undefined && procUid !== uid) continue;
+      const argv = readFileSync(`/proc/${pid}/cmdline`)
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean);
+      const commandLine = argv.join(" ").trim();
+      if (commandLine) rows.push({ pid, commandLine, executable: argv[0], uid: procUid });
+    } catch {
+      // A process disappearing mid-enumeration is normal. A top-level procfs
+      // failure is handled before the loop and fails closed.
+    }
+  }
+  return rows;
+}
+
+function listDarwinSnapshots(uid: number | undefined): ProcessSnapshot[] {
+  const commandOutput = uid !== undefined
+    ? execFileSync("/bin/ps", ["-u", String(uid), "-o", "pid=,command="], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    })
+    : execFileSync("/bin/ps", ["-axo", "pid=,uid=,command="], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    });
+  const executableOutput = uid !== undefined
+    ? execFileSync("/bin/ps", ["-u", String(uid), "-o", "pid=,comm="], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    })
+    : execFileSync("/bin/ps", ["-axo", "pid=,comm="], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    });
+  const executableByPid = new Map<number, string>();
+  for (const raw of executableOutput.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(raw);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const executable = match[2]?.trim() ?? "";
+    if (Number.isSafeInteger(pid) && pid > 0 && executable) executableByPid.set(pid, executable);
+  }
+  const rows: ProcessSnapshot[] = [];
+  for (const raw of commandOutput.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    const match = uid !== undefined
+      ? /^(\d+)\s+(.*)$/.exec(line)
+      : /^(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const commandLine = (uid !== undefined ? match[2] : match[3])?.trim() ?? "";
+    if (!Number.isSafeInteger(pid) || pid <= 0 || !commandLine) continue;
+    rows.push({
+      pid, commandLine, executable: executableByPid.get(pid),
+      uid: uid ?? (Number.isSafeInteger(Number(match[2])) ? Number(match[2]) : undefined),
+    });
+  }
+  return rows;
+}
+
+function effectiveUid(getuid?: () => number | undefined): number | undefined {
+  try {
+    return getuid ? getuid() : process.getuid?.();
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultSnapshots(platform: NodeJS.Platform, uid: number | undefined): ProcessSnapshot[] {
+  if (platform === "win32") return listWindowsSnapshots();
+  if (platform === "darwin") return listDarwinSnapshots(uid);
+  if (platform === "linux") return listLinuxSnapshots(uid);
+  throw new Error("unsupported_process_enumeration_platform");
+}
+
+export function listRunningCodexProcesses(io: CodexWriterProcessIo = {}): CodexWriterProcessCheck {
+  const platform = io.platform ?? process.platform;
+  let snapshots: ProcessSnapshot[];
+  try {
+    snapshots = io.listSnapshots?.() ?? defaultSnapshots(platform, effectiveUid(io.getuid));
+  } catch {
+    return { state: "unknown", reason: "enumeration_failed" };
+  }
+
+  const byPid = new Map<number, CodexWriterProcess>();
+  for (const snapshot of snapshots) {
+    if (!Number.isSafeInteger(snapshot.pid) || snapshot.pid <= 0) continue;
+    if (!isCodexWriterCommandLine(snapshot.commandLine, snapshot.executable)) continue;
+    if (!byPid.has(snapshot.pid)) {
+      byPid.set(snapshot.pid, { pid: snapshot.pid, commandLine: snapshot.commandLine });
+    }
+  }
+  return {
+    state: "ok",
+    processes: [...byPid.values()].sort((a, b) => a.pid - b.pid),
+  };
+}

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

@@ -0,0 +1,489 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { Database, constants as sqliteConstants } from "bun:sqlite";
+
+import { getCodexHome, resolveCodexLogsDbPath } from "../paths";
+import { hasCurrentLogsSchema, inspectCodexLogs, type CodexLogGuardInspection } from "./inspect";
+import { withCodexLogGuardLock, type CodexLogGuardLockOutcome } from "./lock";
+import { sameLogGuardPathIdentity } from "./path-safety";
+import { isSqliteBusy } from "./sqlite-errors";
+import {
+  readCodexLogGuardMode,
+  writeCodexLogGuardMode,
+  type CodexLogGuardMode,
+} from "./policy";
+import {
+  listRunningCodexProcesses,
+  type CodexWriterProcessCheck,
+} from "./processes";
+
+export { type CodexLogGuardMode } from "./policy";
+
+const IMMUTABLE_READONLY_FLAGS = sqliteConstants.SQLITE_OPEN_READONLY | sqliteConstants.SQLITE_OPEN_URI;
+const COMPAT_TRIGGER = "opencodex_log_guard_compat_v1";
+const QUIET_TRIGGER = "opencodex_log_guard_quiet_v1";
+const OWNED_TRIGGER_NAMES = [COMPAT_TRIGGER, QUIET_TRIGGER] as const;
+
+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;
+
+/**
+ * Versioned compatibility policy pinned to the current upstream Codex persistent
+ * log filters researched for Log Guard v1. It intentionally preserves unrelated
+ * TRACE rows rather than assuming all TRACE diagnostics are disposable.
+ */
+/**
+ * Upstream configures these filters with `Targets::with_target`, which matches a
+ * target and every module path BENEATH it: `hyper_util` also covers
+ * `hyper_util::client::legacy::pool`, and `codex_api::sse` also covers
+ * `codex_api::sse::responses`. Exact equality reproduced only the parent, so the
+ * high-volume child targets — the ones that actually fill the database — kept
+ * writing while compat mode reported itself active.
+ *
+ * The comparison uses `substr`, not `LIKE`. SQLite's `LIKE` is ASCII
+ * case-insensitive by default, so a `LIKE` form would also suppress
+ * `HYPER_UTIL::child` — Rust target paths are case-sensitive, and silently
+ * dropping a differently-cased target is a wrong answer, not a safe default.
+ * `substr(NEW.target, 1, N) = 'X::'` is a plain case-sensitive comparison with
+ * no wildcard metacharacters to escape, which also removes the `_`/`%` hazard
+ * that `LIKE` would have required an ESCAPE clause to contain.
+ *
+ * The `'::'` boundary is deliberate and NARROWER than upstream's raw prefix
+ * rule: `Targets::with_target("hyper_util")` would also match a sibling crate
+ * named `hyper_utilities`. Suppressing an unrelated crate's logs is worse for
+ * a guard that silently discards rows, so this matches the module-descendant
+ * relation instead. The existing regression pins `hyper_utilities` as
+ * preserved.
+ *
+ * `opentelemetry_sdk` stays exact because upstream registers it with exact
+ * equality rather than a prefix filter.
+ */
+function targetOrDescendant(target: string): string {
+  const prefix = `${target}::`;
+  return `(NEW.target = '${target}' OR substr(NEW.target, 1, ${prefix.length}) = '${prefix}')`;
+}
+
+function anyTargetOrDescendant(targets: readonly string[]): string {
+  return `(${targets.map(targetOrDescendant).join(" OR ")})`;
+}
+
+const COMPAT_TRIGGER_SQL = `CREATE TRIGGER ${COMPAT_TRIGGER}
+BEFORE INSERT ON logs
+WHEN
+  NEW.target = 'log'
+  OR NEW.target = 'codex_otel.log_only'
+  OR NEW.target = 'codex_otel.trace_safe'
+  OR NEW.target = 'codex_api::responses_websocket_timing'
+  OR NEW.target = 'codex_core::post_sampling_token_estimate'
+  OR (${targetOrDescendant("hyper_util")} AND upper(NEW.level) IN ('TRACE', 'DEBUG', 'INFO'))
+  OR (${anyTargetOrDescendant(["codex_rmcp_client", "rmcp"])} AND upper(NEW.level) IN ('TRACE', 'DEBUG'))
+  OR (${anyTargetOrDescendant([
+    "codex_http_client::transport",
+    "codex_api::sse",
+    "codex_tui::streaming::controller",
+    "codex_tui::streaming::table_holdback",
+  ])} AND upper(NEW.level) = 'TRACE')
+  OR (NEW.target = 'opentelemetry_sdk' AND upper(NEW.level) IN ('TRACE', 'DEBUG'))
+BEGIN
+  SELECT RAISE(IGNORE);
+END`;
+
+const QUIET_TRIGGER_SQL = `CREATE TRIGGER ${QUIET_TRIGGER}
+BEFORE INSERT ON logs
+WHEN upper(NEW.level) = 'TRACE'
+BEGIN
+  SELECT RAISE(IGNORE);
+END`;
+
+const SQL_BY_MODE: Record<Exclude<CodexLogGuardMode, "off">, string> = {
+  compat: COMPAT_TRIGGER_SQL,
+  quiet: QUIET_TRIGGER_SQL,
+};
+
+export type CodexLogGuardObservedMode = CodexLogGuardMode | "collision";
+export type CodexLogGuardProtectionState = "off" | "active" | "drifted" | "unsupported" | "unknown";
+
+export interface CodexLogGuardProtectionSummary {
+  desiredMode: CodexLogGuardMode;
+  observedMode: CodexLogGuardObservedMode;
+  state: CodexLogGuardProtectionState;
+}
+
+export type CodexLogGuardStatus = CodexLogGuardInspection & {
+  protection: CodexLogGuardProtectionSummary;
+};
+
+export type CodexLogGuardMutationError =
+  | "unsupported_schema"
+  | "codex_running"
+  | "process_enumeration_failed"
+  | "trigger_collision"
+  | "unsafe_path"
+  | "busy"
+  | "database_error"
+  | "config_write_failed";
+
+export type CodexLogGuardMutationResult =
+  | { ok: true; status: CodexLogGuardStatus }
+  | { ok: false; error: CodexLogGuardMutationError };
+
+export interface CodexLogGuardProtectionDeps {
+  codexHome?: string;
+  processCheck?: () => CodexWriterProcessCheck;
+  readDesiredMode?: () => CodexLogGuardMode;
+  writeDesiredMode?: (mode: CodexLogGuardMode) => void;
+  withLock?: <T>(
+    canonicalCodexHome: string,
+    canonicalLogsDbPath: string,
+    work: () => T,
+  ) => CodexLogGuardLockOutcome<T>;
+}
+
+interface TriggerRow {
+  name: string;
+  sql: string | null;
+}
+interface ColumnRow { name: string }
+interface OwnedTriggerSnapshot { name: string; sql: string }
+
+type LockedMutationResult =
+  | { ok: true }
+  | { ok: false; error: CodexLogGuardMutationError };
+
+function normalizeSql(sql: string | null | undefined): string {
+  return (sql ?? "").trim().replace(/;\s*$/, "").replace(/\s+/g, " ");
+}
+
+function expectedSql(mode: Exclude<CodexLogGuardMode, "off">): string {
+  return normalizeSql(SQL_BY_MODE[mode]);
+}
+
+function ownedModeForRow(row: TriggerRow): Exclude<CodexLogGuardMode, "off"> | null {
+  if (row.name === COMPAT_TRIGGER && normalizeSql(row.sql) === expectedSql("compat")) return "compat";
+  if (row.name === QUIET_TRIGGER && normalizeSql(row.sql) === expectedSql("quiet")) return "quiet";
+  return null;
+}
+
+function queryReservedTriggers(db: Database): TriggerRow[] {
+  const placeholders = OWNED_TRIGGER_NAMES.map(() => "?").join(", ");
+  return db.query<TriggerRow, string[]>(
+    `SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND name IN (${placeholders}) ORDER BY name`,
+  ).all(...OWNED_TRIGGER_NAMES);
+}
+
+function observeTriggers(db: Database): CodexLogGuardObservedMode {
+  const rows = queryReservedTriggers(db);
+  if (rows.length === 0) return "off";
+  const modes = rows.map(ownedModeForRow);
+  if (modes.some(mode => mode === null)) return "collision";
+  const unique = new Set(modes);
+  return unique.size === 1 && rows.length === 1 ? modes[0]! : "collision";
+}
+
+function exactCurrentSchema(db: Database): boolean {
+  // Delegates to the inspector's predicate so the locked recheck is exactly as
+  // strict as the compatibility report. Column names alone let a schema change
+  // between inspection and the locked write slip a mutation onto a database the
+  // inspector calls monitor-only.
+  return hasCurrentLogsSchema(db);
+}
+
+/**
+ * Read trigger metadata with the same immutable/checkpointed semantics as PR 1
+ * diagnostics. A status GET must never participate in Codex's SQLite WAL/SHM
+ * protocol or materialise sidecars merely to report protection state.
+ */
+function openReadOnly(databasePath: string): Database {
+  const uri = `${pathToFileURL(databasePath).href}?immutable=1`;
+  return new Database(uri, IMMUTABLE_READONLY_FLAGS);
+}
+
+function openReadWrite(databasePath: string): Database {
+  // READWRITE without CREATE: a missing/moved canonical DB is a refusal, not a
+  // reason for OpenCodex to materialise a new foreign database.
+  return new Database(databasePath, sqliteConstants.SQLITE_OPEN_READWRITE);
+}
+
+function databasePathIsSafe(databasePath: string): boolean {
+  try {
+    const stat = lstatSync(databasePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) return false;
+    return sameLogGuardPathIdentity(realpathSync.native(databasePath), databasePath);
+  } catch {
+    return false;
+  }
+}
+
+function protectionSummary(
+  inspection: CodexLogGuardInspection,
+  desiredMode: CodexLogGuardMode,
+  observedMode: CodexLogGuardObservedMode,
+): CodexLogGuardProtectionSummary {
+  if (inspection.capabilities.protection.state !== "supported") {
+    return { desiredMode, observedMode, state: "unsupported" };
+  }
+  if (observedMode === "collision") return { desiredMode, observedMode, state: "unknown" };
+  if (desiredMode === "off" && observedMode === "off") {
+    return { desiredMode, observedMode, state: "off" };
+  }
+  if (desiredMode !== "off" && desiredMode === observedMode) {
+    return { desiredMode, observedMode, state: "active" };
+  }
+  return { desiredMode, observedMode, state: "drifted" };
+}
+
+function inspectionDeps(deps: CodexLogGuardProtectionDeps): { codexHome?: string } {
+  return deps.codexHome ? { codexHome: deps.codexHome } : {};
+}
+
+export function getCodexLogGuardProtectionStatus(
+  deps: CodexLogGuardProtectionDeps = {},
+): CodexLogGuardStatus {
+  const codexHome = deps.codexHome ?? getCodexHome();
+  const inspection = inspectCodexLogs({ codexHome });
+  const databasePath = resolveCodexLogsDbPath({ codexHome });
+  const desiredMode = (deps.readDesiredMode ?? readCodexLogGuardMode)();
+  let observedMode: CodexLogGuardObservedMode = inspection.schema.state === "compatible" ? "collision" : "off";
+
+  if (inspection.schema.state === "compatible" && databasePathIsSafe(databasePath)) {
+    try {
+      const db = openReadOnly(databasePath);
+      try { observedMode = observeTriggers(db); }
+      finally { db.close(); }
+    } catch {
+      observedMode = "collision";
+    }
+  }
+
+  return {
+    ...inspection,
+    protection: protectionSummary(inspection, desiredMode, observedMode),
+  };
+}
+
+function successfulMutationStatus(
+  codexHome: string,
+  mode: CodexLogGuardMode,
+): CodexLogGuardStatus {
+  const inspection = inspectCodexLogs({ codexHome });
+  const state: CodexLogGuardProtectionState = inspection.capabilities.protection.state === "supported"
+    ? (mode === "off" ? "off" : "active")
+    : "unsupported";
+  return {
+    ...inspection,
+    protection: { desiredMode: mode, observedMode: mode, state },
+  };
+}
+
+function processRefusal(check: CodexWriterProcessCheck): CodexLogGuardMutationError | null {
+  if (check.state === "unknown") return "process_enumeration_failed";
+  if (check.processes.length > 0) return "codex_running";
+  return null;
+}
+
+function mutateOwnedTrigger(
+  databasePath: string,
+  mode: CodexLogGuardMode,
+): { ok: true; previousTriggers: readonly OwnedTriggerSnapshot[] } | { ok: false; error: CodexLogGuardMutationError } {
+  let db: Database | undefined;
+  let transactionOpen = false;
+  try {
+    if (!databasePathIsSafe(databasePath)) return { ok: false, error: "unsafe_path" };
+    db = openReadWrite(databasePath);
+    db.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    if (!exactCurrentSchema(db)) {
+      // Same reasoning as the caller's gate: installing into an unrecognized
+      // schema is refused, but removing a trigger we installed ourselves stays
+      // available so a schema upgrade cannot strand it.
+      if (mode !== "off") {
+        db.exec("ROLLBACK");
+        transactionOpen = false;
+        return { ok: false, error: "unsupported_schema" };
+      }
+    }
+
+    const rows = queryReservedTriggers(db);
+    const modes = rows.map(ownedModeForRow);
+    if (modes.some(item => item === null)) {
+      db.exec("ROLLBACK");
+      transactionOpen = false;
+      return { ok: false, error: "trigger_collision" };
+    }
+    const previousTriggers: OwnedTriggerSnapshot[] = rows.map(row => ({
+      name: row.name,
+      sql: row.sql!,
+    }));
+
+    for (const row of rows) {
+      // Name is from our fixed allow-list; never interpolate arbitrary sqlite_master data.
+      db.exec(`DROP TRIGGER ${row.name}`);
+    }
+    if (mode !== "off") db.exec(SQL_BY_MODE[mode]);
+
+    const observed = observeTriggers(db);
+    if (observed !== mode) throw new Error("log_guard_trigger_verification_failed");
+    db.exec("COMMIT");
+    transactionOpen = false;
+    return { ok: true, previousTriggers };
+  } catch (error) {
+    if (transactionOpen) {
+      try { db?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
+    }
+    if (isSqliteBusy(error)) return { ok: false, error: "busy" };
+    return { ok: false, error: "database_error" };
+  } finally {
+    try { db?.close(); } catch { /* mutation already settled */ }
+  }
+}
+
+function restoreOwnedTriggers(databasePath: string, previousTriggers: readonly OwnedTriggerSnapshot[]): void {
+  // Best-effort compensation only. Failure is deliberately not hidden by
+  // claiming success; the caller returns config_write_failed and status will
+  // expose any remaining drift on the next read.
+  let db: Database | undefined;
+  let transactionOpen = false;
+  try {
+    if (!databasePathIsSafe(databasePath)) return;
+    db = openReadWrite(databasePath);
+    db.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    if (!exactCurrentSchema(db)) {
+      db.exec("ROLLBACK");
+      transactionOpen = false;
+      return;
+    }
+
+    const current = queryReservedTriggers(db);
+    if (current.some(row => ownedModeForRow(row) === null)) {
+      db.exec("ROLLBACK");
+      transactionOpen = false;
+      return;
+    }
+    for (const row of current) db.exec(`DROP TRIGGER ${row.name}`);
+
+    for (const trigger of previousTriggers) {
+      if (ownedModeForRow(trigger) === null) throw new Error("invalid_owned_trigger_snapshot");
+      db.exec(trigger.sql);
+    }
+
+    const restored = queryReservedTriggers(db);
+    const expected = new Map(previousTriggers.map(row => [row.name, normalizeSql(row.sql)]));
+    if (restored.length !== previousTriggers.length
+      || restored.some(row => expected.get(row.name) !== normalizeSql(row.sql))) {
+      throw new Error("log_guard_trigger_restore_verification_failed");
+    }
+    db.exec("COMMIT");
+    transactionOpen = false;
+  } catch {
+    if (transactionOpen) {
+      try { db?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
+    }
+  } finally {
+    try { db?.close(); } catch { /* compensation already settled */ }
+  }
+}
+
+function performMutation(
+  requestedMode: CodexLogGuardMode | (() => CodexLogGuardMode),
+  deps: CodexLogGuardProtectionDeps,
+): CodexLogGuardMutationResult {
+  const codexHome = deps.codexHome ?? getCodexHome();
+  const inspection = inspectCodexLogs({ codexHome });
+  const databasePath = resolveCodexLogsDbPath({ codexHome });
+  // Removal must not be gated on the schema still being recognized. A Codex
+  // upgrade that changes the logs schema would otherwise strand an installed
+  // trigger: Protect is refused (correctly), but so is Disable, leaving the
+  // user with an active OpenCodex trigger and no in-product way to remove it.
+  // Installing into an unknown schema stays refused; taking our own trigger
+  // back out is always allowed.
+  const removingProtection = typeof requestedMode !== "function" && requestedMode === "off";
+  if (!removingProtection && inspection.capabilities.protection.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;
+  const writeDesired = deps.writeDesiredMode ?? writeCodexLogGuardMode;
+  let locked: CodexLogGuardLockOutcome<LockedMutationResult>;
+  // Repair passes a resolver instead of a value: its target mode must be read
+  // INSIDE L. Reading it before acquiring the lock let a Disable complete in
+  // the gap, after which the stale Repair reinstalled protection and reported
+  // success — the caller saw an honest "off" and got "compat".
+  let effectiveMode: CodexLogGuardMode = typeof requestedMode === "function" ? "off" : requestedMode;
+  try {
+    locked = withLock(codexHome, databasePath, () => {
+      // Recheck after acquiring L so a Codex process that starts during lock
+      // acquisition cannot race the foreign-schema mutation.
+      const secondRefusal = processRefusal(checkProcesses());
+      if (secondRefusal) return { ok: false, error: secondRefusal };
+
+      effectiveMode = typeof requestedMode === "function" ? requestedMode() : requestedMode;
+      const mutation = mutateOwnedTrigger(databasePath, effectiveMode);
+      if (!mutation.ok) return mutation;
+
+      // Desired state belongs to the same logical transition as the trigger.
+      // Keep L held through this write so another OpenCodex process cannot
+      // interleave a different mode between the DB commit and config commit.
+      try {
+        writeDesired(effectiveMode);
+      } catch {
+        restoreOwnedTriggers(databasePath, mutation.previousTriggers);
+        return { ok: false, error: "config_write_failed" as const };
+      }
+      return { ok: true };
+    });
+  } 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",
+    };
+  }
+  if (!locked.value.ok) return locked.value;
+
+  // Report the mode that was actually applied under the lock, not the one the
+  // caller guessed before acquiring it.
+  return { ok: true, status: successfulMutationStatus(codexHome, effectiveMode) };
+}
+
+export function protectCodexLogs(
+  mode: Exclude<CodexLogGuardMode, "off">,
+  deps: CodexLogGuardProtectionDeps = {},
+): CodexLogGuardMutationResult {
+  return performMutation(mode, deps);
+}
+
+export function unprotectCodexLogs(
+  deps: CodexLogGuardProtectionDeps = {},
+): CodexLogGuardMutationResult {
+  return performMutation("off", deps);
+}
+
+export function repairCodexLogGuardProtection(
+  deps: CodexLogGuardProtectionDeps = {},
+): CodexLogGuardMutationResult {
+  // Resolve the desired mode under the lock (see performMutation): a Disable
+  // that lands between the read and the lock must win, not be silently undone.
+  return performMutation(() => (deps.readDesiredMode ?? readCodexLogGuardMode)(), deps);
+}