@bitkyc08/opencodex 2.20.0 → 2.22.0

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,39 @@
+import { realpathSync } from "node:fs";
+import { 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 {
+  return samePathIdentity(realPath, normalizeTrustedDarwinSystemAlias(requestedPath));
+}

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);
+}

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),
+  };
+}