@bitkyc08/opencodex 2.81.0 → 2.82.0

package/src/lib/bun-runtime-preflight.ts

@@ -0,0 +1,140 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, rmdirSync } from "node:fs";
+import { join } from "node:path";
+import type { DurableBunRuntime } from "./bun-runtime";
+
+export type RuntimePreflightReason = "spawn" | "timeout" | "create" | "remove" | "protocol";
+export const RUNTIME_PREFLIGHT_TIMEOUT_MS = 5_000;
+export const RUNTIME_PREFLIGHT_GUIDANCE = "The selected Bun runtime could not create and remove a directory in the OpenCodex config directory. "
+  + "Windows application policy may deny writes from this executable location. "
+  + "Set OPENCODEX_BUN_PATH to a trusted Bun executable allowed by your policy before launching ocx, "
+  + "or reinstall opencodex with npm install -g @bitkyc08/opencodex, then retry. No alternate runtime was selected.";
+
+export class RuntimePreflightError extends Error {
+  readonly code = "OCX_RUNTIME_PREFLIGHT_FAILED";
+  constructor(readonly reason: RuntimePreflightReason) {
+    super(`${RUNTIME_PREFLIGHT_GUIDANCE} (preflight: ${reason})`);
+    this.name = "RuntimePreflightError";
+  }
+}
+
+type DirectoryIdentity = { dev: number; ino: number; isDirectory(): boolean; isSymbolicLink(): boolean };
+export interface RuntimePreflightFs {
+  lstatSync: (path: string) => DirectoryIdentity;
+  mkdirSync: (path: string, mode: number) => unknown;
+  rmdirSync: (path: string) => void;
+  readdirSync: (path: string) => readonly string[];
+}
+export interface RuntimePreflightOptions {
+  platform?: NodeJS.Platform;
+  rootWasAbsent?: boolean;
+  spawnSync?: typeof spawnSync;
+  fs?: RuntimePreflightFs;
+  nonce?: () => string;
+}
+/** Caller seams keep one selection through admission, rendering and state publication. */
+export interface RuntimePreflightDeps {
+  selectRuntime?: () => DurableBunRuntime;
+  assertRuntimeWritable?: typeof assertSelectedRuntimeWritable;
+  configDir?: () => string;
+  platform?: NodeJS.Platform;
+}
+
+const probeFs: RuntimePreflightFs = { lstatSync, mkdirSync, rmdirSync, readdirSync };
+
+function sameDirectory(fs: RuntimePreflightFs, path: string, owned: DirectoryIdentity): boolean {
+  const current = fs.lstatSync(path);
+  return current.isDirectory() && !current.isSymbolicLink()
+    && current.dev === owned.dev && current.ino === owned.ino;
+}
+
+function removeOwnedEmptyDirectory(fs: RuntimePreflightFs, path: string, owned: DirectoryIdentity): void {
+  try {
+    if (sameDirectory(fs, path, owned) && fs.readdirSync(path).length === 0
+      && sameDirectory(fs, path, owned)) fs.rmdirSync(path);
+  } catch { /* Never delete contents or a replacement; cleanup does not mask refusal. */ }
+}
+
+function prepareRoot(fs: RuntimePreflightFs, root: string, rootWasAbsent?: boolean): void {
+  try {
+    if (rootWasAbsent === undefined) {
+      try { fs.lstatSync(root); rootWasAbsent = false; }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        rootWasAbsent = true;
+      }
+    }
+    if (rootWasAbsent) {
+      try {
+        fs.mkdirSync(root, 0o700); // Exclusive, non-recursive: a missing parent refuses.
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        // Use a concurrently created root, subject to the directory check below.
+      }
+    }
+    const current = fs.lstatSync(root);
+    if (!current.isDirectory() || current.isSymbolicLink()) throw new RuntimePreflightError("create");
+  } catch {
+    throw new RuntimePreflightError("create");
+  }
+}
+
+function probeInProcess(fs: RuntimePreflightFs, path: string): void {
+  let owned: DirectoryIdentity | undefined;
+  try {
+    try { fs.mkdirSync(path, 0o700); owned = fs.lstatSync(path); }
+    catch { throw new RuntimePreflightError("create"); }
+    try { fs.rmdirSync(path); }
+    catch { throw new RuntimePreflightError("remove"); }
+  } finally {
+    if (owned) removeOwnedEmptyDirectory(fs, path, owned);
+  }
+}
+
+function probeChild(runtime: DurableBunRuntime, path: string, nonce: string, spawn: typeof spawnSync): void {
+  // The child emits only this invocation's nonce and a fixed result, never paths/errors.
+  const script = `const fs = require("node:fs"); const path = ${JSON.stringify(path)};
+let result = "create", owned;
+try { fs.mkdirSync(path, 0o700); owned = fs.lstatSync(path); result = "remove";
+  fs.rmdirSync(path); result = "ok";
+} catch { /* result already names the failed step; details never leave the child */ } finally {
+  if (owned) { try { const now = fs.lstatSync(path);
+    if (now.isDirectory() && !now.isSymbolicLink() && now.dev === owned.dev && now.ino === owned.ino
+      && fs.readdirSync(path).length === 0) fs.rmdirSync(path);
+  } catch { /* leave any probe entry that cannot be proven ours */ } }
+}
+process.stdout.write(${JSON.stringify(nonce)} + ":" + result);
+process.exitCode = result === "ok" ? 0 : 1;`;
+  let child: ReturnType<typeof spawnSync>;
+  try {
+    child = spawn(runtime.path, ["-e", script], {
+      shell: false, windowsHide: true, timeout: RUNTIME_PREFLIGHT_TIMEOUT_MS,
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1024,
+    });
+  } catch { throw new RuntimePreflightError("spawn"); }
+  if (child.error) {
+    throw new RuntimePreflightError((child.error as NodeJS.ErrnoException).code === "ETIMEDOUT" ? "timeout" : "spawn");
+  }
+  const ack = String(child.stdout ?? "");
+  if (ack === `${nonce}:create` && child.status === 1) throw new RuntimePreflightError("create");
+  if (ack === `${nonce}:remove` && child.status === 1) throw new RuntimePreflightError("remove");
+  if (ack !== `${nonce}:ok` || child.status !== 0) throw new RuntimePreflightError("protocol");
+}
+
+/** Windows admission of ONLY the already selected runtime. No discovery or memoization. */
+export function assertSelectedRuntimeWritable(
+  runtime: DurableBunRuntime,
+  configDir: string,
+  deps: RuntimePreflightOptions = {},
+): void {
+  if ((deps.platform ?? process.platform) !== "win32") return;
+  if (runtime.source === "standalone" && runtime.path !== process.execPath) throw new RuntimePreflightError("protocol");
+  const fs = deps.fs ?? probeFs;
+  // The config root is durable: never delete it by pathname, even on refusal.
+  prepareRoot(fs, configDir, deps.rootWasAbsent);
+  const nonce = (deps.nonce ?? randomUUID)();
+  const path = join(configDir, `.ocx-runtime-probe-${nonce}`);
+  if (runtime.source === "standalone") probeInProcess(fs, path);
+  else probeChild(runtime, path, nonce, deps.spawnSync ?? spawnSync);
+}

package/src/lib/desktop-cli-handoff.d.mts

@@ -0,0 +1,20 @@
+import type { spawn } from "node:child_process";
+import type { accessSync, lstatSync, statSync } from "node:fs";
+import type { DesktopCliRecordRead, DesktopCliRecordIssue } from "./desktop-cli-record.mjs";
+export type DesktopHandoffIssue = DesktopCliRecordIssue | "target-invalid" | "target-self" | "target-unusable" | "spawn-failed";
+export type DesktopCliHandoffPlan =
+  | { kind: "continue"; reason: "excluded" | "missing" | "disabled" | "target-missing" | "windows-path-only" }
+  | { kind: "error"; issue: DesktopHandoffIssue }
+  | { kind: "handoff"; target: string };
+export type DesktopCliHandoffExit =
+  | { kind: "continue" }
+  | { kind: "error"; issue: "spawn-failed" }
+  | { kind: "exit"; code: number; signal: NodeJS.Signals | null };
+export function desktopHandoffExcluded(argv: string[], env?: NodeJS.ProcessEnv): boolean;
+export function planDesktopCliHandoff(input?: {
+  argv?: string[]; env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform;
+  recordRead?: DesktopCliRecordRead; selfPaths?: (string | undefined)[];
+}, deps?: { stat?: typeof statSync; access?: typeof accessSync; realpath?: (path: string) => string }): DesktopCliHandoffPlan;
+export function runDesktopCliHandoff(plan: Extract<DesktopCliHandoffPlan, { kind: "handoff" }>, launch: {
+  argv: string[]; env: NodeJS.ProcessEnv; proof: string; context: string;
+}, deps?: { spawn?: typeof spawn; lstat?: typeof lstatSync; parent?: Pick<NodeJS.Process, "on" | "removeListener">; platform?: NodeJS.Platform }): Promise<DesktopCliHandoffExit>;

package/src/lib/desktop-cli-handoff.mjs

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, lstatSync, realpathSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { readDesktopCliRecord } from "./desktop-cli-record.mjs";
+import { isCodexCliUpdateInspectionArgv } from "../update/codex-cli-update-launch-policy.mjs";
+
+const PROOF_PREFIX = "--ocx-internal-launch-proof=";
+
+export function desktopHandoffExcluded(argv, env = process.env) {
+  const args = argv.filter(arg => !arg.startsWith(PROOF_PREFIX));
+  return env.OCX_NO_DESKTOP_HANDOFF === "1"
+    || ["update", "uninstall", "remove"].includes(args[0])
+    || (args[0] ?? "").startsWith("__")
+    || isCodexCliUpdateInspectionArgv(["node", "ocx.mjs", ...args]);
+}
+
+export function planDesktopCliHandoff(input = {}, deps = {}) {
+  const platform = input.platform ?? process.platform;
+  if (platform === "win32") return { kind: "continue", reason: "windows-path-only" };
+  const argv = input.argv ?? process.argv.slice(2);
+  const env = input.env ?? process.env;
+  if (desktopHandoffExcluded(argv, env)) return { kind: "continue", reason: "excluded" };
+  const read = input.recordRead ?? readDesktopCliRecord({ env, platform: input.platform });
+  if (read.state === "missing" || read.state === "disabled") {
+    return { kind: "continue", reason: read.state };
+  }
+  if (read.state !== "ready") return { kind: "error", issue: read.issue };
+  const api = platform === "win32" ? win32 : posix;
+  const target = read.record.cliExecutable;
+  if (!api.isAbsolute(target)) return { kind: "error", issue: "target-invalid" };
+  const stat = deps.stat ?? statSync;
+  const access = deps.access ?? accessSync;
+  const realpath = deps.realpath ?? realpathSync;
+  try {
+    if (!stat(target).isFile()) return { kind: "error", issue: "target-invalid" };
+    access(target, platform === "win32" ? constants.F_OK : constants.X_OK);
+    const physical = realpath(target);
+    const key = path => platform === "win32" ? path.toLowerCase() : path;
+    for (const self of input.selfPaths ?? [process.argv[1], process.execPath]) {
+      if (!self) continue;
+      let own;
+      try { own = realpath(self); }
+      catch (error) { if (error?.code === "ENOENT") continue; throw error; }
+      if (key(own) === key(physical)) return { kind: "error", issue: "target-self" };
+    }
+    return { kind: "handoff", target: physical };
+  } catch (error) {
+    return error?.code === "ENOENT"
+      ? { kind: "continue", reason: "target-missing" }
+      : { kind: "error", issue: "target-unusable" };
+  }
+}
+
+export function runDesktopCliHandoff(plan, launch, deps = {}) {
+  const spawnChild = deps.spawn ?? spawn;
+  const parent = deps.parent ?? process;
+  const platform = deps.platform ?? process.platform;
+  const lstat = deps.lstat ?? lstatSync;
+  const spawnFailure = error => {
+    if (error?.code === "ENOENT") {
+      try { lstat(plan.target); }
+      catch (checkError) { if (checkError?.code === "ENOENT") return { kind: "continue" }; }
+    }
+    return { kind: "error", issue: "spawn-failed" };
+  };
+  const argv = launch.argv.filter(arg => !arg.startsWith(PROOF_PREFIX));
+  const env = { ...launch.env, OCX_NO_DESKTOP_HANDOFF: "1", OCX_NODE_LAUNCH_CONTEXT: launch.context };
+  delete env.OCX_BUN_RUNTIME_SOURCE;
+  delete env.OCX_BUN_RUNTIME_PATH;
+  return new Promise(resolveExit => {
+    let child;
+    try {
+      child = spawnChild(plan.target, [`${PROOF_PREFIX}${launch.proof}`, ...argv], {
+        stdio: "inherit", shell: false, windowsHide: true, env,
+      });
+    } catch (error) {
+      resolveExit(spawnFailure(error));
+      return;
+    }
+    const forwarded = platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handlers = forwarded.map(signal => {
+      const handler = () => { try { child.kill(signal); } catch { /* child already exited */ } };
+      parent.on(signal, handler);
+      return [signal, handler];
+    });
+    const clear = () => { for (const [signal, handler] of handlers) parent.removeListener(signal, handler); };
+    let done = false;
+    const finish = result => { if (done) return; done = true; clear(); resolveExit(result); };
+    child.once("error", error => finish(spawnFailure(error)));
+    child.once("exit", (code, signal) => finish({ kind: "exit", code: code ?? 1, signal }));
+  });
+}

package/src/lib/desktop-cli-record.d.mts

@@ -0,0 +1,29 @@
+import type { Stats } from "node:fs";
+
+export const DESKTOP_CLI_RECORD_MAX_BYTES: number;
+export type DesktopCliRecord = Readonly<{
+  platform: "darwin" | "win32" | "linux";
+  kind: "macos-app" | "windows-install" | "linux-deb";
+  cliExecutable: string;
+}>;
+export type DesktopCliRecordIssue = "record-invalid" | "record-too-large" | "record-pending" | "record-unreadable" | "record-unsafe";
+export type DesktopCliRecordRead =
+  | { state: "missing"; path: string }
+  | { state: "disabled"; path: string; cleanupPending: boolean }
+  | { state: "ready"; path: string; record: DesktopCliRecord }
+  | { state: "invalid" | "unreadable"; path: string; issue: DesktopCliRecordIssue };
+export type DesktopCliRecordOptions = {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  recordPath?: string;
+};
+export function desktopCliRecordPath(options?: DesktopCliRecordOptions): string;
+export type DesktopCliRecordDeps = {
+  lstat?: (path: string) => Stats;
+  fstat?: (fd: number) => Stats;
+  open?: (path: string, flags: number) => number;
+  euid?: number;
+  checkAcl?: (directory: string, path: string) => boolean;
+};
+export function readDesktopCliRecord(options?: DesktopCliRecordOptions, deps?: DesktopCliRecordDeps): DesktopCliRecordRead;

package/src/lib/desktop-cli-record.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, posix, resolve, win32 } from "node:path";
+
+export const DESKTOP_CLI_RECORD_MAX_BYTES = 64 * 1024;
+
+export function desktopCliRecordPath(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const home = options.home ?? (platform === "win32" ? env.USERPROFILE || homedir() : homedir());
+  return (platform === "win32" ? win32 : posix).join(home, ".opencodex-desktop", "cli.json");
+}
+
+// Keep these lexical rules aligned with Rust's absolute_for in cli_command_record.rs.
+function validTargetPath(path, platform) {
+  if ([...path].length > 4096 || /[\x00\r\n]/.test(path)) return false;
+  const absolute = platform === "win32"
+    ? /^[A-Za-z]:[/\\]/.test(path) || path.startsWith("\\\\") || path.startsWith("//")
+    : path.startsWith("/");
+  return absolute && !path.split(platform === "win32" ? /[/\\]/ : /\//)
+    .some(part => part === "." || part === "..");
+}
+
+function noMacAcl(directory, path) {
+  const result = spawnSync("/bin/ls", ["-lde", directory, path], {
+    encoding: "utf8", timeout: 1000, shell: false, windowsHide: true,
+    env: { ...process.env, LC_ALL: "C" },
+  });
+  if (result.error || result.status !== 0 || result.stderr) return false;
+  // Each path has one metadata line; ACL entries add numbered lines and a "+" marker.
+  const lines = result.stdout.trimEnd().split("\n");
+  return lines.length === 2 && lines.every(line => /^[d-][rwxStTs-]{9}[.@]?\s/.test(line));
+}
+
+export function readDesktopCliRecord(options = {}, deps = {}) {
+  const platform = options.platform ?? process.platform;
+  const path = options.recordPath ?? desktopCliRecordPath(options);
+  const directory = dirname(resolve(path));
+  const lstat = deps.lstat ?? lstatSync;
+  const fstat = deps.fstat ?? fstatSync;
+  const open = deps.open ?? openSync;
+  const unsafe = () => ({ state: "invalid", path, issue: "record-unsafe" });
+  const posixHost = platform !== "win32";
+  let fd;
+  let checkingSafety = true;
+  let absenceAllowed = true;
+  try {
+    const dirInfo = lstat(directory);
+    if (dirInfo.isSymbolicLink() || !dirInfo.isDirectory()) return unsafe();
+    const uid = posixHost ? deps.euid ?? process.geteuid?.() : undefined;
+    if (posixHost && (uid === undefined || dirInfo.uid !== uid || (dirInfo.mode & 0o077) !== 0)) return unsafe();
+    const fileInfo = lstat(path);
+    absenceAllowed = false;
+    if (fileInfo.isSymbolicLink() || !fileInfo.isFile()
+      || (posixHost && (fileInfo.uid !== uid || (fileInfo.mode & 0o077) !== 0))) return unsafe();
+    const flags = constants.O_RDONLY | (posixHost ? constants.O_NOFOLLOW | constants.O_NONBLOCK : 0);
+    fd = open(path, flags);
+    const info = fstat(fd);
+    if (!info.isFile() || ["dev", "ino", "uid", "mode"].some(key => info[key] !== fileInfo[key])) return unsafe();
+    if (platform === "darwin" && !(deps.checkAcl ?? noMacAcl)(directory, resolve(path))) return unsafe();
+    checkingSafety = false;
+    if (info.size > DESKTOP_CLI_RECORD_MAX_BYTES) {
+      return { state: "invalid", path, issue: "record-too-large" };
+    }
+    const bytes = Buffer.alloc(DESKTOP_CLI_RECORD_MAX_BYTES + 1);
+    let used = 0;
+    while (used < bytes.length) {
+      const n = readSync(fd, bytes, used, bytes.length - used, null);
+      if (n === 0) break;
+      used += n;
+    }
+    if (used > DESKTOP_CLI_RECORD_MAX_BYTES) {
+      return { state: "invalid", path, issue: "record-too-large" };
+    }
+    let value;
+    try { value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, used))); }
+    catch { return { state: "invalid", path, issue: "record-invalid" }; }
+    if (!value || typeof value !== "object" || Array.isArray(value)
+      || value.version !== 1 || typeof value.enabled !== "boolean") {
+      return { state: "invalid", path, issue: "record-invalid" };
+    }
+    if (!value.enabled) return { state: "disabled", path, cleanupPending: value.pending != null };
+    if (value.pending != null) return { state: "invalid", path, issue: "record-pending" };
+    const bundle = value.bundle;
+    const kind = { darwin: "macos-app", win32: "windows-install", linux: "linux-deb" }[platform];
+    if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)
+      || !kind || bundle.platform !== platform || bundle.kind !== kind
+      || typeof bundle.cliExecutable !== "string" || !validTargetPath(bundle.cliExecutable, platform)) {
+      return { state: "invalid", path, issue: "record-invalid" };
+    }
+    return { state: "ready", path, record: {
+      platform, kind, cliExecutable: bundle.cliExecutable,
+    } };
+  } catch (error) {
+    return error?.code === "ENOENT" && absenceAllowed
+      ? { state: "missing", path }
+      : checkingSafety ? unsafe() : { state: "unreadable", path, issue: "record-unreadable" };
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}

package/src/lib/request-execution-budget.ts

@@ -194,6 +194,8 @@ export interface RequestExecutionBudget extends TransientSendBudget {
   readonly alternateTargetSends: number;
   readonly targetTransitions: number;
   readonly lastTargetKey: string | undefined;
+  /** Seed a fresh derived scope with the actual endpoint of its already-paid initial send. */
+  bindPrepaidTarget?(targetKey: string): void;
   /**
    * Spend one operator-granted replacement for an AMBIGUOUS failure of this logical request,
    * up to `limit`. False once the request has none left.
@@ -390,6 +392,7 @@ function createAmbiguousResendGrant(): Pick<SharedSendLedger, "claimAmbiguousRes
   };
 }
 
+/** Keep target-local transition state over the shared ledger and its single-use bookings. */
 function createRequestExecutionBudgetWithLedger(
   policy: RequestExecutionBudgetPolicy,
   logicalRequestId: string | undefined,
@@ -441,6 +444,11 @@ function createRequestExecutionBudgetWithLedger(
     get alternateTargetSends() { return alternateTargetSends; },
     get targetTransitions() { return targetTransitions; },
     get lastTargetKey() { return lastTargetKey; },
+    /** Seed only a fresh scope; never reset recovery history on an existing target. */
+    bindPrepaidTarget(targetKey: string): void {
+      // Only a fresh scope may bind: this is initial identity, never a recovery rebase.
+      if (lastTargetKey === undefined) lastTargetKey = targetKey;
+    },
     remainingBaseSends(cap: number): number {
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
       return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));

package/src/lib/synced-state-location.ts

@@ -1,4 +1,4 @@
-import { lstatSync, realpathSync } from "node:fs";
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 // POSIX path operations on purpose: every path this module classifies is a macOS path. The
 // host's own path module would build backslash or drive-letter paths on Windows and make the
@@ -15,7 +15,11 @@ const { join, resolve } = posix;
  * synced folder turns ordinary requests into intermittent 502s (#6314). This only answers
  * "is it likely synced"; the guard itself stays strict.
  */
-export type SyncedStateLocation = "icloud-drive" | "file-provider" | "icloud-desktop-documents";
+export type SyncedStateLocation =
+  | "icloud-drive"
+  | "file-provider"
+  | "icloud-desktop-documents"
+  | "google-drive-desktop-documents";
 
 export interface SyncedStateLocationProbe {
   readonly platform?: NodeJS.Platform;
@@ -24,23 +28,34 @@ export interface SyncedStateLocationProbe {
   readonly realpath?: (path: string) => string;
   /** Whether a directory entry exists at the path, without following it. */
   readonly entryExists?: (path: string) => boolean;
+  /** Entry names in a directory. An unreadable directory is empty, not an error. */
+  readonly listEntries?: (dir: string) => readonly string[];
 }
 
 const defaultEntryExists = (path: string): boolean => {
   try { lstatSync(path); return true; } catch { return false; }
 };
 
+const defaultListEntries = (dir: string): readonly string[] => {
+  try { return readdirSync(dir); } catch { return []; }
+};
+
 /**
  * Advisory only. Apple publishes no API a CLI can ask, so this reads the observed layout:
  * iCloud Drive lives under ~/Library/Mobile Documents, File Provider clients (OneDrive, Dropbox,
  * Google Drive) under ~/Library/CloudStorage, and with "Desktop & Documents Folders" turned on
- * iCloud Drive holds a Desktop/Documents entry of its own. A false positive costs one warning
- * line; nothing is refused on the strength of it.
+ * iCloud Drive holds a Desktop/Documents entry of its own. Google Drive for desktop can also
+ * sync the native Desktop and Documents folders without moving them under CloudStorage (#6314).
+ * The cheap signals for that are a DriveFS directory or a `GoogleDrive-*` CloudStorage folder.
+ * They do not read which folders the app was told to sync, so Drive being installed can warn
+ * even when Documents is not selected. A false positive costs one warning line; nothing is
+ * refused on the strength of it.
  */
 export function syncedStateLocation(dir: string, probe: SyncedStateLocationProbe = {}): SyncedStateLocation | undefined {
   if ((probe.platform ?? process.platform) !== "darwin") return undefined;
   const realpath = probe.realpath ?? ((path: string) => realpathSync.native(path));
   const entryExists = probe.entryExists ?? defaultEntryExists;
+  const listEntries = probe.listEntries ?? defaultListEntries;
   const canonical = (path: string): string => {
     try { return realpath(path); } catch { return resolve(path); }
   };
@@ -56,17 +71,42 @@ export function syncedStateLocation(dir: string, probe: SyncedStateLocationProbe
   if (within(mobileDocuments)) return "icloud-drive";
   if (within(join(home, "Library", "CloudStorage"))) return "file-provider";
   for (const folder of ["Desktop", "Documents"]) {
-    if (within(join(home, folder)) && entryExists(join(mobileDocuments, "com~apple~CloudDocs", folder))) {
-      return "icloud-desktop-documents";
+    if (!within(join(home, folder))) continue;
+    if (entryExists(join(mobileDocuments, "com~apple~CloudDocs", folder))) return "icloud-desktop-documents";
+    if (googleDriveAppearsToSyncDesktopDocuments(home, entryExists, listEntries)) {
+      return "google-drive-desktop-documents";
     }
   }
   return undefined;
 }
 
+/**
+ * Presence only. Drive for desktop keeps its config under DriveFS and, on current macOS,
+ * a `GoogleDrive-*` directory in CloudStorage. Either one means the app is in use. Missing
+ * or unreadable markers are "not detected", never a startup failure.
+ */
+function googleDriveAppearsToSyncDesktopDocuments(
+  home: string,
+  entryExists: (path: string) => boolean,
+  listEntries: (dir: string) => readonly string[],
+): boolean {
+  const driveFs = join(home, "Library", "Application Support", "Google", "DriveFS");
+  try {
+    if (entryExists(driveFs)) return true;
+  } catch { /* unreadable marker */ }
+  try {
+    return listEntries(join(home, "Library", "CloudStorage"))
+      .some((name) => name.toLowerCase().startsWith("googledrive-"));
+  } catch {
+    return false;
+  }
+}
+
 const LOCATION_LABEL: Record<SyncedStateLocation, string> = {
   "icloud-drive": "inside iCloud Drive",
   "file-provider": "inside a cloud-storage (File Provider) folder",
   "icloud-desktop-documents": "in Desktop or Documents, which iCloud Drive appears to sync",
+  "google-drive-desktop-documents": "in Desktop or Documents, which Google Drive appears to sync",
 };
 
 /** The startup warning. Names the location kind, never the path. */

package/src/lib/test-home-guard.ts

@@ -20,7 +20,7 @@
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
@@ -31,6 +31,8 @@ const GUARD_ENV = "OCX_TEST_HOME_GUARD";
  * loads, so the true home is only knowable from this hand-off.
  */
 const REAL_HOME_ENV = "OCX_REAL_HOME";
+/** Set by `scripts/test.ts` to the developer's own Claude config directory before it sandboxes one. */
+const REAL_CLAUDE_CONFIG_DIR_ENV = "OCX_REAL_CLAUDE_CONFIG_DIR";
 
 /**
  * Resolve symlinks so two spellings of one location compare equal — macOS hands out
@@ -62,6 +64,25 @@ function canonicalize(path: string): string {
 const REAL_HOME = process.env[REAL_HOME_ENV]?.trim() || homedir();
 const PROTECTED_HOME = canonicalize(join(REAL_HOME, ".opencodex"));
 const PROTECTED_CODEX_HOME = canonicalize(join(REAL_HOME, ".codex"));
+/**
+ * The developer's Claude config directory: the default `<real home>/.claude`, plus their own
+ * `CLAUDE_CONFIG_DIR` when they set one. `scripts/test.ts` hands the original over as
+ * `OCX_REAL_CLAUDE_CONFIG_DIR` because its child already starts with a sandboxed
+ * `CLAUDE_CONFIG_DIR`; a bare run imports this module before the preload rewrites the
+ * environment, so `CLAUDE_CONFIG_DIR` still holds the developer's value here.
+ *
+ * Claude agent sync prunes generated `agents/ocx-*.md`, and a bare `bun test` once did that
+ * to a live directory: Bun's `os.homedir()` ignores a HOME rewritten after startup (#6775).
+ */
+const REAL_CLAUDE_CONFIG_DIRS = [...new Set([
+  join(REAL_HOME, ".claude"),
+  process.env[REAL_CLAUDE_CONFIG_DIR_ENV]?.trim() || process.env.CLAUDE_CONFIG_DIR?.trim() || join(REAL_HOME, ".claude"),
+])];
+const PROTECTED_CLAUDE_TREES = REAL_CLAUDE_CONFIG_DIRS.map(path => ({
+  path: canonicalize(path),
+  lexical: resolve(path),
+  label: "the real Claude config directory",
+}));
 /**
  * `~/Library/LaunchAgents` needs its own entry because HOME isolation does not reach it:
  * `os.homedir()` reads the password database, not `$HOME`, so a macOS test that rewrites
@@ -83,6 +104,11 @@ export function protectedCodexHomeForTests(): string {
   return PROTECTED_CODEX_HOME;
 }
 
+/** The Claude config directories this process protects. Exported for the guard's own tests. */
+export function protectedClaudeConfigDirsForTests(): readonly string[] {
+  return PROTECTED_CLAUDE_TREES.map(tree => tree.path);
+}
+
 export function isTestHomeGuardArmed(): boolean {
   return process.env[GUARD_ENV] === "1";
 }
@@ -155,6 +181,54 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
   );
 }
 
+/**
+ * Throw when an armed test process is about to write or prune inside the real Claude config
+ * directory. Unlike the OpenCodex and Codex homes this refuses descendants too, and callers pass
+ * every directory they are about to touch (the config root AND its `agents`/`cache` child), so a
+ * sandbox child that is a link into the real directory is judged by where it resolves.
+ *
+ * The protected roots are resolved at check time rather than at import, so a custom directory
+ * created after this module loaded still compares by its current identity. On macOS and Windows,
+ * whose default filesystems ignore case, paths compare case-insensitively: `.CLAUDE` is the same
+ * directory there. Comparing too broadly only refuses more, which is the safe direction here.
+ *
+ * Call FIRST, outside any best-effort catch, so a refusal is visible and nothing is touched.
+ */
+export function assertNotRealClaudeConfigUnderTest(...paths: string[]): void {
+  if (!isTestHomeGuardArmed()) return;
+  const roots = currentClaudeConfigRoots();
+  for (const path of paths) {
+    for (const candidate of [canonicalize(path), resolve(path)]) {
+      for (const root of roots) {
+        if (!isSameOrInsideIgnoringPlatformCase(root, candidate)) continue;
+        throw new Error(
+          `refusing to write the real Claude config directory (${root}) from a test process. `
+          + "Set CLAUDE_CONFIG_DIR to a temp directory, or pass an explicit config directory "
+          + "(for a server, startServer's managementApi.claudeAgentConfigDir).",
+        );
+      }
+    }
+  }
+}
+
+function currentClaudeConfigRoots(): string[] {
+  return REAL_CLAUDE_CONFIG_DIRS.flatMap(path => [canonicalize(path), resolve(path)]);
+}
+
+function foldPlatformCase(path: string): string {
+  return process.platform === "darwin" || process.platform === "win32" ? path.toLowerCase() : path;
+}
+
+function isSameOrInsideIgnoringPlatformCase(root: string, candidate: string): boolean {
+  const parent = foldPlatformCase(root);
+  const child = foldPlatformCase(candidate);
+  if (parent === child) return true;
+  const rel = relative(parent, child);
+  // Only a leading ".." COMPONENT leaves the root, split on this platform's separator: a child
+  // named "..fixture", or "..\\fixture" on POSIX where a backslash is a filename character, is inside.
+  return rel !== "" && !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+
 /**
  * The trees a removal must never reach, and the reason each one is named.
  *
@@ -172,6 +246,7 @@ const PROTECTED_TREES: ReadonlyArray<{ path: string; lexical: string; label: str
     lexical: resolve(join(REAL_HOME, "Library", "LaunchAgents")),
     label: "the real LaunchAgents directory",
   },
+  ...PROTECTED_CLAUDE_TREES,
 ];
 const PROTECTED_REAL_HOME = canonicalize(REAL_HOME);
 const LEXICAL_REAL_HOME = resolve(REAL_HOME);
@@ -258,6 +333,17 @@ export function protectedRemovalReason(target: string): string | null {
         if (isInside(candidate, protectedPath)) return `an ancestor of ${tree.label} (${protectedPath})`;
       }
     }
+    // The Claude directory is judged like its writer guard: roots resolved now, case folded
+    // where the filesystem folds it, so an alias created after import is still refused.
+    for (const root of currentClaudeConfigRoots()) {
+      if (isSameOrInsideIgnoringPlatformCase(root, candidate)) {
+        // Same narrow lift as the trees above: content of the running checkout when that
+        // checkout itself lives inside the directory. Never the root itself.
+        if (foldPlatformCase(root) !== foldPlatformCase(candidate) && isOwnCheckoutContent(root, candidate)) continue;
+        return `the real Claude config directory or a path inside it (${root})`;
+      }
+      if (isSameOrInsideIgnoringPlatformCase(candidate, root)) return `an ancestor of the real Claude config directory (${root})`;
+    }
   }
   return null;
 }