adversarial-review-gate 2.0.0

package/src/core/git.js

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+
+// Hard cap on accumulated stdout. A pathological git diff (e.g. a huge generated
+// file) could otherwise grow stdout without bound and OOM the process. When the
+// cap is exceeded we kill the child and resolve with what we have plus a
+// `truncated` flag so callers can flag a coverage limitation instead of silently
+// dropping output.
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+
+// Spawn a git subprocess and resolve with its exit code and captured output.
+// Never rejects; an exec error (e.g. git missing) resolves with code 127 so
+// callers can branch on `result.code` uniformly. The resolved object always
+// carries a `truncated` field (falsy for normal-size output).
+export async function git(args, cwd, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, shell: false, windowsHide: true });
+    const stdoutChunks = [];
+    let stdoutBytes = 0;
+    let stderr = "";
+    let truncated = false;
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    child.stdout.on("data", (chunk) => {
+      if (truncated) return;
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      if (stdoutBytes + buf.length > MAX_STDOUT_BYTES) {
+        // Keep only up to the cap, then stop the child to bound memory.
+        const remaining = MAX_STDOUT_BYTES - stdoutBytes;
+        if (remaining > 0) {
+          stdoutChunks.push(buf.subarray(0, remaining));
+          stdoutBytes += remaining;
+        }
+        truncated = true;
+        try { child.kill(); } catch { /* already gone */ }
+        finish({
+          code: null,
+          stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+          stderr,
+          truncated: true,
+        });
+        return;
+      }
+      stdoutChunks.push(buf);
+      stdoutBytes += buf.length;
+    });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) =>
+      finish({ code: 127, stdout: Buffer.concat(stdoutChunks).toString("utf8"), stderr: String(error), truncated })
+    );
+    child.on("close", (code) =>
+      finish({ code, stdout: Buffer.concat(stdoutChunks).toString("utf8"), stderr, truncated })
+    );
+  });
+}
+
+// Return true if `cwd` is inside a git working tree.
+export async function isGitRepo(cwd) {
+  const result = await git(["rev-parse", "--git-dir"], cwd);
+  return result.code === 0;
+}

package/src/core/hash.js

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+
+export function sha256(text) {
+  return createHash("sha256").update(String(text), "utf8").digest("hex");
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function reviewCacheKey(parts) {
+  return sha256(stableJson({
+    diffHash: parts.diffHash,
+    configHash: parts.configHash,
+    promptHash: parts.promptHash,
+    reviewerId: parts.reviewerId,
+    reviewerVersion: parts.reviewerVersion,
+    model: parts.model || "",
+    level: parts.level,
+    toolVersion: parts.toolVersion,
+    privacyMode: parts.privacyMode,
+  }));
+}

package/src/core/load-config.js

@@ -0,0 +1,133 @@
+// Config + state-dir loading for the CLI entrypoints.
+//
+// This module centralizes how the `check`, `hook`, and `run` commands resolve
+// their effective config and where they keep per-session state.
+//
+// HARDENING #1 (Task 8 review): the gate's review-pass cache lives in session
+// state. A pre-seeded cache entry would yield an UNREVIEWED pass. Therefore the
+// state directory MUST live at a USER-LEVEL path (under the user's home dir),
+// never a repo-relative path that an untrusted project could pre-write. The
+// default is `~/.adversarial-review/state`. A test-only override is available
+// via the ADVERSARIAL_REVIEW_STATE_DIR env var, but the DEFAULT is always
+// user-level and never under `cwd`.
+
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_CONFIG, sanitizeProjectConfig, deepAssign, applyPolicyFloor } from "./config.js";
+
+const PROJECT_CONFIG_REL = path.join(".adversarial-review", "config.json");
+const USER_CONFIG_REL = path.join(".adversarial-review", "config.json");
+const USER_POLICY_REL = path.join(".adversarial-review", "policy.json");
+
+/**
+ * Tolerantly read+parse a JSON file. Missing file -> `{}` (no warning). Corrupt
+ * JSON -> `{}` plus a warning written to `stderr` (when provided). Never throws.
+ *
+ * @param {string} file
+ * @param {object} [io]  - { stderr }
+ * @param {string} [label]
+ * @returns {Promise<object>}
+ */
+async function readJsonTolerant(file, io, label) {
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return {}; // Missing/unreadable: treat as empty config.
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch (err) {
+    if (io?.stderr) {
+      io.stderr.write(
+        `adversarial-review: ignoring corrupt ${label || "config"} at ${file}: ${err.message}\n`
+      );
+    }
+    return {};
+  }
+}
+
+/**
+ * Load the effective config for a workspace.
+ *
+ * Merge precedence (lowest to highest):
+ *   DEFAULT_CONFIG < userConfig < projectConfig
+ * where:
+ *   - userConfig    comes from `<home>/.adversarial-review/config.json` and acts
+ *     as machine-wide host/reviewer DEFAULTS (e.g. so "claude-code+codex use
+ *     opencode" applies machine-wide without a per-project config);
+ *   - projectConfig comes from `<cwd>/.adversarial-review/config.json` and
+ *     overrides the user defaults for any key it sets.
+ * The user policy floor (`<home>/.adversarial-review/policy.json`) is then applied
+ * ON TOP via applyPolicyFloor, so it can only RATCHET STRICTER — neither the user
+ * config nor the project config can loosen it.
+ *
+ * All three files are tolerant (missing -> {}, corrupt -> {} + warning).
+ *
+ * @param {string} cwd
+ * @param {object} [io]  - { stderr, env }
+ * @returns {Promise<object>} resolved config
+ */
+export async function loadEffectiveConfig(cwd, io = {}) {
+  const home = homeDir(io.env);
+  const userConfig = await readJsonTolerant(
+    path.join(home, USER_CONFIG_REL),
+    io,
+    "user config"
+  );
+  const projectConfig = await readJsonTolerant(
+    path.join(cwd, PROJECT_CONFIG_REL),
+    io,
+    "project config"
+  );
+  const userPolicyFloor = await readJsonTolerant(
+    path.join(home, USER_POLICY_REL),
+    io,
+    "user policy"
+  );
+
+  // Layer lowest-to-highest: DEFAULT_CONFIG < userConfig < projectConfig.
+  // Both raw layers are sanitized (unknown top-level keys stripped) and merged
+  // via deepAssign, which also blocks prototype-pollution keys.
+  const merged = structuredClone(DEFAULT_CONFIG);
+  deepAssign(merged, sanitizeProjectConfig(userConfig));
+  deepAssign(merged, sanitizeProjectConfig(projectConfig));
+
+  // Apply the user policy floor LAST so it can only tighten, never loosen.
+  return applyPolicyFloor(merged, userPolicyFloor);
+}
+
+/**
+ * Resolve the user-level state directory.
+ *
+ * DEFAULT: `<home>/.adversarial-review/state` — always OUTSIDE any `cwd`, where
+ * `<home>` is the resolved user home (see homeDir, honoring ADVERSARIAL_REVIEW_HOME).
+ * Override: the ADVERSARIAL_REVIEW_STATE_DIR env var (tests only) takes priority
+ * over the home-based default. The default path is never repo-relative, so a
+ * project can never pre-seed the pass cache.
+ *
+ * @param {object} [env=process.env]
+ * @returns {string} absolute state dir path
+ */
+export function resolveStateDir(env = process.env) {
+  const override = env && env.ADVERSARIAL_REVIEW_STATE_DIR;
+  if (override) return path.resolve(override);
+  return path.join(homeDir(env), ".adversarial-review", "state");
+}
+
+// Resolve the user's home directory, honoring an injected env so tests can
+// redirect the user-level base (config.json, policy.json, state dir) without
+// touching the real home dir. Priority:
+//   1. ADVERSARIAL_REVIEW_HOME — dedicated override for the user-level base;
+//   2. HOME / USERPROFILE — standard OS home env vars;
+//   3. os.homedir() — the real home dir.
+function homeDir(env) {
+  if (env) {
+    const fromEnv = env.ADVERSARIAL_REVIEW_HOME || env.HOME || env.USERPROFILE;
+    if (fromEnv) return fromEnv;
+  }
+  return os.homedir();
+}

package/src/core/paths.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+/**
+ * Canonicalize a candidate path relative to workspaceRoot and determine
+ * whether it escapes the workspace (path traversal / symlink escape guard).
+ *
+ * Algorithm:
+ *   1. Resolve the real path of workspaceRoot itself.
+ *   2. Build the absolute form of candidate.
+ *   3. Resolve the real path of its *parent* directory (catches symlinks that
+ *      would redirect the directory outside the workspace).  If the parent does
+ *      not exist yet, fall back to the un-resolved parent (creation paths).
+ *   4. Reconstruct the full path by joining real-parent + basename.
+ *   5. Compute path.relative(rootReal, resolved).  An empty relative means
+ *      the candidate IS the root; a relative that starts with ".." or is
+ *      absolute means it escaped.
+ *
+ * @param {string} workspaceRoot  - absolute path to the workspace root
+ * @param {string} candidate      - path to check (may be relative or absolute)
+ * @returns {Promise<{rootReal: string, absolute: string, relative: string, outside: boolean}>}
+ */
+export async function canonicalWorkspacePath(workspaceRoot, candidate) {
+  const rootReal = await realpath(workspaceRoot);
+  const absolute = path.resolve(workspaceRoot, candidate);
+  const parentReal = await realpath(path.dirname(absolute)).catch(
+    () => path.dirname(absolute)
+  );
+  const resolved = path.join(parentReal, path.basename(absolute));
+  const rel = path.relative(rootReal, resolved);
+  const outside = rel === "" ? false : rel.startsWith("..") || path.isAbsolute(rel);
+  return { rootReal, absolute: resolved, relative: rel, outside };
+}

package/src/core/policy.js

@@ -0,0 +1,77 @@
+// Policy helper functions — derive boolean/string decisions from a resolved config.
+// All functions are pure (no side effects, no state).
+
+/**
+ * Returns true when the effective policy mode is "strict-ci".
+ *
+ * @param {object} config - resolved config (from mergeConfig)
+ * @returns {boolean}
+ */
+export function isStrict(config) {
+  return config.policy.mode === "strict-ci";
+}
+
+/**
+ * Returns true when every code change must be reviewed regardless of size.
+ * True for "all-code" reviewScope or when mode is "strict-ci".
+ *
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function requiresReviewForCode(config) {
+  return config.policy.reviewScope === "all-code" || isStrict(config);
+}
+
+/**
+ * Returns the action to take when a reviewer call fails.
+ * In "soft" mode the configured value (or "self-review") is returned.
+ * In all other modes the configured value (or "block") is returned.
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+export function reviewerErrorAction(config) {
+  if (config.policy.mode === "soft") return config.policy.onReviewerError || "self-review";
+  return config.policy.onReviewerError || "block";
+}
+
+/**
+ * Returns the action to take when an internal (tool-level) error occurs.
+ * When there is no evidence of a significant change the gate should never
+ * block — the change either hasn't happened or is trivial.
+ * In "soft" mode the configured value (or "allow") is returned.
+ * In all other modes the configured value (or "block") is returned.
+ *
+ * @param {object} config
+ * @param {boolean} evidenceOfSignificantChange
+ * @returns {string}
+ */
+export function internalErrorAction(config, evidenceOfSignificantChange) {
+  if (!evidenceOfSignificantChange) return "allow";
+  if (config.policy.mode === "soft") return config.policy.onInternalError || "allow";
+  return config.policy.onInternalError || "block";
+}
+
+/**
+ * Returns the action to take when consecutive block count reaches the cap.
+ * In "soft" mode the configured value (or "allow") is returned.
+ * In all other modes the configured value (or "block") is returned.
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+export function blockCapAction(config) {
+  if (config.policy.mode === "soft") return config.policy.onBlockCap || "allow";
+  return config.policy.onBlockCap || "block";
+}
+
+/**
+ * Returns true when the current config permits a review to be skipped.
+ * Skip is never allowed in "strict-ci" mode, regardless of allowSkip setting.
+ *
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function skipAllowed(config) {
+  return config.policy.mode !== "strict-ci" && config.policy.allowSkip === true;
+}

package/src/core/process.js

@@ -0,0 +1,158 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { constants } from "node:fs";
+import { spawn } from "node:child_process";
+
+/**
+ * Resolve a command name or path to an absolute executable path.
+ * On Windows, walks PATHEXT extensions (e.g. .COM .EXE .BAT .CMD).
+ * Returns null if nothing is found.
+ *
+ * @param {string} command  - bare name ("claude") or explicit path
+ * @param {object} env      - environment variables (defaults to process.env)
+ * @returns {Promise<string|null>}
+ */
+export async function resolveExecutable(command, env = process.env) {
+  // Explicit path: check existence and return resolved form, or null if missing.
+  if (command.includes("/") || command.includes("\\")) {
+    try {
+      await access(command, constants.X_OK);
+    } catch {
+      try {
+        await access(command, constants.F_OK);
+      } catch {
+        // File does not exist or is inaccessible — return null instead of throwing.
+        return null;
+      }
+    }
+    return path.resolve(command);
+  }
+
+  const pathEntries = String(env.PATH || "").split(path.delimiter).filter(Boolean);
+  const extensions =
+    process.platform === "win32"
+      ? String(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";")
+      : [""];
+
+  for (const dir of pathEntries) {
+    for (const ext of extensions) {
+      const candidate = path.join(
+        dir,
+        process.platform === "win32" ? `${command}${ext}` : command
+      );
+      try {
+        await access(candidate, constants.F_OK);
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Spawn a child process with shell:false to prevent shell-injection.
+ * stdio defaults to ["ignore", "pipe", "pipe"].
+ *
+ * @param {string}   command
+ * @param {string[]} args
+ * @param {object}   options  - { cwd, env, stdio }
+ * @returns {import("node:child_process").ChildProcess}
+ */
+export function spawnSafe(command, args, options = {}) {
+  return spawn(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    shell: false,
+    stdio: options.stdio || ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+}
+
+// Characters that cmd.exe treats as metacharacters when it re-parses the
+// trailing arguments of `cmd.exe /c <batch> <args...>`. An argument containing
+// any of these can break out of the intended command and execute attacker code,
+// so batch-wrapped invocations MUST reject args matching this pattern.
+const CMD_METACHAR_RE = /[&|<>^"%()\r\n]/;
+
+/**
+ * Spawn a RESOLVED executable path with shell:false.
+ *
+ * On Windows, `.cmd` and `.bat` files cannot be spawned directly with
+ * shell:false — they must be invoked via `cmd.exe /c <path> [args...]`.
+ * This function handles that transparently so callers never need to
+ * special-case Windows batch wrappers.
+ *
+ * SECURITY: when wrapping a `.cmd`/`.bat` target, cmd.exe re-parses the trailing
+ * arguments, so an argument containing cmd metacharacters
+ * (`& | < > ^ " % ( )`, CR/LF) would execute attacker-controlled commands. This
+ * function FAILS CLOSED: if any arg passed to a batch wrapper matches a cmd
+ * metacharacter it THROWS `unsafe_batch_argument` BEFORE spawning. Callers must
+ * therefore never hand free-text (prompts, briefs, repo content) directly as a
+ * batch argument — pass such data via a temp file path or the child's stdin.
+ * Non-batch (`.exe`/direct) targets are spawned via CreateProcess with no shell
+ * and are unaffected by this check.
+ *
+ * @param {string}   resolvedPath  - absolute path returned by resolveExecutable
+ * @param {string[]} args
+ * @param {object}   options       - { cwd, env, stdio }
+ * @returns {import("node:child_process").ChildProcess}
+ * @throws {Error} "unsafe_batch_argument" when a batch wrapper would receive a
+ *                 cmd-metacharacter argument.
+ */
+export function spawnResolved(resolvedPath, args, options = {}) {
+  let command = resolvedPath;
+  let finalArgs = args;
+
+  if (process.platform === "win32") {
+    const lower = resolvedPath.toLowerCase();
+    if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+      // Defense-in-depth (Layer B): reject any cmd-metacharacter argument BEFORE
+      // spawning. cmd.exe /c re-parses these args, so this prevents the trailing
+      // arguments from breaking out into attacker-controlled commands.
+      for (const arg of args) {
+        if (CMD_METACHAR_RE.test(String(arg))) {
+          throw new Error("unsafe_batch_argument");
+        }
+      }
+      // Wrap batch files with cmd.exe /c to avoid EINVAL with shell:false.
+      command = "cmd.exe";
+      finalArgs = ["/c", resolvedPath, ...args];
+    }
+  }
+
+  return spawn(command, finalArgs, {
+    cwd: options.cwd,
+    env: options.env,
+    shell: false,
+    stdio: options.stdio || ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Custom-reviewer argument template validation
+// ---------------------------------------------------------------------------
+
+/** Placeholders that a custom reviewer's args array may use. */
+export const ALLOWED_PLACEHOLDERS = new Set(["cwd", "diffPath", "briefPath", "jobPath"]);
+
+/**
+ * Expand `{placeholder}` tokens in a reviewer args array.
+ * Throws if an unknown placeholder is encountered (injection guard).
+ *
+ * @param {string[]} args   - template args from reviewer config
+ * @param {object}   values - map of placeholder → value
+ * @returns {string[]}
+ */
+export function expandArgs(args, values) {
+  return args.map((arg) =>
+    String(arg).replace(/\{([^}]+)\}/g, (_m, name) => {
+      if (!ALLOWED_PLACEHOLDERS.has(name)) {
+        throw new Error(`Unknown custom reviewer placeholder: ${name}`);
+      }
+      return values[name] || "";
+    })
+  );
+}

package/src/core/secrets.js

@@ -0,0 +1,46 @@
+// Secret scanner: detects likely credentials in diff text and flags sensitive
+// file paths. Used by the gate to block sending secrets to external reviewers.
+
+const SECRET_PATTERNS = [
+  // Matches PEM-format private key headers, including ECDSA and DSA variants.
+  /-----BEGIN (?:RSA |EC |ECDSA |DSA |OPENSSH |PGP )?PRIVATE KEY-----/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bghp_[A-Za-z0-9_]{30,}\b/,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/,
+  /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{12,}/i,
+];
+
+// Matches file paths that are inherently sensitive: .env files, credential/
+// secret/private-key names, SSH key file names, and common key/cert extensions.
+const SENSITIVE_PATH_RE =
+  /(^|[\\/])\.env(\.|$)|credential|secret|private[-_]?key|id_rsa|id_dsa|id_ecdsa|id_ed25519|\.pem|\.pfx|\.p12|\.key|\.keystore|\.jks/i;
+
+/**
+ * Scan diff text and file paths for potential secrets or sensitive material.
+ *
+ * @param {string|*} text - Raw diff or file content to scan. Non-string values
+ *   are coerced to string; null/undefined become an empty string.
+ * @param {string[]|null|undefined} [paths=[]] - File paths included in the
+ *   change set. null or undefined are treated as an empty array.
+ * @returns {Array<{ type: "sensitive_path", path: string } | { type: "secret_pattern", sample: string }>}
+ */
+export function scanSecrets(text, paths = []) {
+  // Guard against non-string text (null, undefined, numbers, etc.).
+  const body = typeof text === "string" ? text : String(text ?? "");
+  // Guard against null/undefined paths — only iterate an actual array.
+  const list = Array.isArray(paths) ? paths : [];
+
+  const findings = [];
+  // Flag paths that are inherently sensitive regardless of content.
+  for (const filePath of list) {
+    if (SENSITIVE_PATH_RE.test(filePath)) {
+      findings.push({ type: "sensitive_path", path: filePath });
+    }
+  }
+  // Scan text for known secret shapes.
+  for (const pattern of SECRET_PATTERNS) {
+    const match = pattern.exec(body);
+    if (match) findings.push({ type: "secret_pattern", sample: match[0].slice(0, 12) });
+  }
+  return findings;
+}

package/src/core/state.js

@@ -0,0 +1,107 @@
+// Per-session gate state persistence.
+//
+// State is a small JSON file per session under `stateDir`. It holds the
+// session baseline (recorded by the SessionStart hook in a later task), a
+// consecutive-block counter, and a review-pass cache keyed by reviewCacheKey.
+//
+// All reads are tolerant: a missing or corrupt file yields a default `{}` so
+// the gate never crashes on a fresh or damaged state directory. Writes are
+// atomic (temp file + rename) and use owner-only permissions where supported.
+
+import { readFile, writeFile, rename, mkdir, readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256 } from "./hash.js";
+
+// Owner read/write only. Honored on POSIX; a no-op effect on Windows but safe.
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+/**
+ * Derive a safe on-disk file name for a session id. The id is hashed so that
+ * arbitrary characters (path separators, etc.) in a host-provided session id
+ * cannot escape the state directory.
+ *
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function sessionFileName(sessionId) {
+  return `session-${sha256(String(sessionId || "default"))}.json`;
+}
+
+/**
+ * Read the persisted state for a session.
+ *
+ * @param {string} stateDir
+ * @param {string} sessionId
+ * @returns {Promise<object>} the stored state, or `{}` if missing/corrupt.
+ */
+export async function readSessionState(stateDir, sessionId) {
+  const file = join(stateDir, sessionFileName(sessionId));
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch {
+    // Corrupt JSON: treat as empty rather than crashing the gate.
+    return {};
+  }
+}
+
+/**
+ * Atomically persist a session's state. Writes a temp file then renames it into
+ * place so a concurrent reader never observes a half-written file.
+ *
+ * @param {string} stateDir
+ * @param {string} sessionId
+ * @param {object} state
+ * @returns {Promise<void>}
+ */
+export async function writeSessionState(stateDir, sessionId, state) {
+  await mkdir(stateDir, { recursive: true, mode: DIR_MODE });
+  const file = join(stateDir, sessionFileName(sessionId));
+  // Unique temp name so concurrent writers do not clobber each other's temp.
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const payload = { ...state, updatedAt: Date.now() };
+  await writeFile(tmp, JSON.stringify(payload), { mode: FILE_MODE });
+  await rename(tmp, file);
+}
+
+/**
+ * Delete session state files whose last update is older than `ttlDays`.
+ * Tolerant of unreadable entries and a missing state directory.
+ *
+ * @param {string} stateDir
+ * @param {number} ttlDays
+ * @param {number} [now=Date.now()]
+ * @returns {Promise<number>} count of files removed.
+ */
+export async function pruneState(stateDir, ttlDays, now = Date.now()) {
+  let entries;
+  try {
+    entries = await readdir(stateDir);
+  } catch {
+    return 0;
+  }
+  const ttlMs = Math.max(0, Number(ttlDays) || 0) * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  for (const name of entries) {
+    if (!name.startsWith("session-") || !name.endsWith(".json")) continue;
+    const file = join(stateDir, name);
+    try {
+      const info = await stat(file);
+      if (now - info.mtimeMs > ttlMs) {
+        await unlink(file);
+        removed += 1;
+      }
+    } catch {
+      // Ignore races / unreadable entries.
+    }
+  }
+  return removed;
+}