@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/integrations/writer.ts

@@ -801,6 +801,11 @@ export interface CoordinatedIntegrationOptions {
    * non-null result refuses without writing anything.
    */
   revalidate?: (frozen: IntegrationWriteInput) => Promise<WriteOutcome | null>;
+  /**
+   * Synchronous last word, evaluated with no await between it and the transaction (after
+   * `revalidate` and any lock acquisition). A non-null result refuses without writing.
+   */
+  guard?: (frozen: IntegrationWriteInput) => WriteOutcome | null;
 }
 
 /** Freeze all mutable resolution seams before the first lock await. */
@@ -942,21 +947,22 @@ async function coordinatedWrite(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
+  const guarded = (bound: IntegrationWriteInput) => options?.guard?.(bound) ?? operation(bound);
   if (!spec.writerLock) {
     const refused = await options?.revalidate?.(frozen);
-    return refused ?? operation(frozen);
+    return refused ?? guarded(frozen);
   }
 
   // An absent client home is not created merely to acquire a sibling lock.
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
     const refused = await options?.revalidate?.(frozen);
     if (refused) return refused;
-    if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") return operation(frozen);
+    if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") return guarded(frozen);
   }
   return withClientLocks(
     frozen,
     spec.writerLock.suffix,
-    () => operation(frozen),
+    () => guarded(frozen),
     options,
   );
 }

package/src/lib/bun-path-runtime.d.mts

@@ -0,0 +1,32 @@
+export interface DesktopCliIo {
+  stat?: (path: string) => { isFile(): boolean };
+  access?: (path: string, mode: number) => void;
+}
+export interface PathBunIo extends DesktopCliIo {
+  now?: () => number;
+  realpath?: (path: string) => string;
+  stat?: (path: string) => { isFile(): boolean; mode: number };
+  isRealBunBinary?: (path: string) => boolean;
+  spawnSync?: (path: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    encoding: "utf8";
+    timeout: number;
+    maxBuffer: number;
+    killSignal: "SIGKILL";
+    shell: false;
+    windowsHide: true;
+    stdio: ["ignore", "pipe", "pipe"];
+  }) => { status: number | null; stdout?: string; signal?: string | null; error?: unknown };
+}
+export declare function findPathBun(options: {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  pinnedVersion: string;
+  deadlineMs?: number;
+  io?: PathBunIo;
+}): { path: string; version: string } | null;
+export declare function findDesktopCli(options?: {
+  platform?: NodeJS.Platform;
+  home?: string;
+  io?: DesktopCliIo;
+}): string | null;

package/src/lib/bun-path-runtime.mjs

@@ -0,0 +1,95 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { performance } from "node:perf_hooks";
+import { isRealBunBinary } from "./bun-binary-validator.mjs";
+
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const MAX_VERSION_BYTES = 4096;
+const IDENTITY_PROBE = "process.stdout.write(String(typeof Bun==='object'&&Bun.version))";
+
+function stableVersion(value) {
+  if (typeof value !== "string" || value.length > 64) return null;
+  const match = STABLE.exec(value);
+  if (!match) return null;
+  const numbers = match.slice(1, 4).map(Number);
+  return numbers.every(Number.isSafeInteger) ? numbers : null;
+}
+
+/** Discover the first absolute PATH Bun passing version-policy and identity checks. */
+export function findPathBun({
+  env = process.env, platform = process.platform, pinnedVersion,
+  deadlineMs = 750, io = {},
+}) {
+  const pin = stableVersion(pinnedVersion);
+  if (!pin || !Number.isFinite(deadlineMs) || deadlineMs <= 0) return null;
+  const paths = platform === "win32" ? win32 : posix;
+  const absolute = value => paths.isAbsolute(value)
+    && (platform !== "win32" || /^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+)/.test(value));
+  const now = io.now ?? (() => performance.now());
+  const end = now() + deadlineMs;
+  const realpath = io.realpath ?? realpathSync.native;
+  const stat = io.stat ?? statSync;
+  const access = io.access ?? accessSync;
+  const validate = io.isRealBunBinary ?? isRealBunBinary;
+  const spawn = io.spawnSync ?? spawnSync;
+  const key = platform === "win32"
+    ? Object.keys(env).find(name => name.toLowerCase() === "path") : "PATH";
+  const directories = (env[key ?? "PATH"] ?? "").split(platform === "win32" ? ";" : ":");
+  const seen = new Set();
+  const probe = (path, args) => {
+    const remaining = Math.floor(end - now());
+    if (remaining <= 0) return null;
+    const result = spawn(path, args, {
+      env, encoding: "utf8", timeout: remaining, maxBuffer: MAX_VERSION_BYTES,
+      killSignal: "SIGKILL", shell: false, windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (now() >= end || result.error || result.signal || result.status !== 0
+      || typeof result.stdout !== "string" || result.stdout.length > MAX_VERSION_BYTES) return null;
+    return result.stdout.trim();
+  };
+  for (const directory of directories) {
+    if (now() >= end) break;
+    if (!directory || !absolute(directory)) continue;
+    try {
+      const path = realpath(paths.join(directory, platform === "win32" ? "bun.exe" : "bun"));
+      if (!absolute(path)) continue;
+      const identity = platform === "win32" ? path.toLowerCase() : path;
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      const file = stat(path);
+      if (!file.isFile()) continue;
+      if (platform !== "win32" && ((file.mode & 0o022) || (stat(paths.dirname(path)).mode & 0o022))) continue;
+      access(path, constants.X_OK);
+      if (!validate(path)) continue;
+      const version = probe(path, ["--version"]);
+      const candidate = stableVersion(version);
+      if (!candidate || candidate[0] !== pin[0] || candidate[1] < pin[1]) continue;
+      if (probe(path, ["-e", IDENTITY_PROBE]) !== version) continue;
+      return { path, version };
+    } catch {
+      // Unreadable, unexecutable, vanished or invalid: try the next absolute candidate.
+    }
+  }
+  return null;
+}
+
+/** Failure-text pointer only. Never execute or delegate to this binary. */
+export function findDesktopCli({ platform = process.platform, home = homedir(), io = {} } = {}) {
+  if (platform !== "darwin") return null;
+  const stat = io.stat ?? statSync;
+  const access = io.access ?? accessSync;
+  for (const path of [
+    "/Applications/OpenCodex.app/Contents/MacOS/ocx",
+    posix.join(home, "Applications/OpenCodex.app/Contents/MacOS/ocx"),
+  ]) {
+    try {
+      if (!stat(path).isFile()) continue;
+      access(path, constants.X_OK);
+      return path;
+    } catch { /* Missing or not executable: no pointer for this candidate. */ }
+  }
+  return null;
+}

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/errors.ts

@@ -17,6 +17,7 @@ export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
  * string for a client to be able to tell this apart from a provider rate limit.
  */
 export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
+export const SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE = "spend_ledger_storage_unavailable";
 
 /** First nonblank string across the canonical upstream error paths, in priority order. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {
@@ -357,6 +358,9 @@ export function isUpstreamResetReplayRefusedMessage(text: string): boolean {
 
 export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
   const text = message.toLowerCase();
+  if (type === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE) {
+    return { message, type: "server_error", code: SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE };
+  }
   if (type === "previous_response_not_found") {
     return { message, type: "invalid_request_error", code: "previous_response_not_found" };
   }
@@ -639,6 +643,24 @@ export function adapterFailureFromMessage(message: string): { httpStatus: number
   return { httpStatus, error };
 }
 
+/** Narrow structured classes carried through a synthesized bare-error terminal. */
+export function recognizedUpstreamError(error: { type?: unknown; code?: unknown }):
+  { type: string; code: string; httpStatus: 429 | 503 } | undefined {
+  const code = typeof error.code === "string" ? error.code : undefined;
+  // An explicit unknown code must not gain a recognized class from its type or copy.
+  if (code !== undefined && !["rate_limit_exceeded", "rate_limit_error", "server_is_overloaded", "overloaded_error"].includes(code)) return undefined;
+  if (code === "rate_limit_exceeded" || code === "rate_limit_error"
+    || (code === undefined && error.type === "rate_limit_error")) {
+    return { type: "rate_limit_error", code: code ?? "rate_limit_exceeded", httpStatus: 429 };
+  }
+  if (code === "server_is_overloaded" || code === "overloaded_error"
+    || (code === undefined && error.type === "overloaded_error")) {
+    return { type: error.type === "overloaded_error" ? "overloaded_error" : "server_error",
+      code: code ?? "server_is_overloaded", httpStatus: 503 };
+  }
+  return undefined;
+}
+
 /** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
 export function httpStatusFromTerminalError(error: {
   type?: string;
@@ -646,10 +668,13 @@ export function httpStatusFromTerminalError(error: {
   message?: string;
 } | undefined): number {
   if (!error) return 502;
+  if (error.code === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE) return 503;
   if (error.code === "client_closed_request" || error.code === "client_cancelled") return 499;
   if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
     return 400;
   }
+  const recognized = recognizedUpstreamError(error);
+  if (recognized) return recognized.httpStatus;
   if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
   if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
   if (

package/src/lib/redact.ts

@@ -7,7 +7,7 @@ export const REDACTED_SECRET = "[REDACTED]";
  * credentials over an unsafe channel (e.g. plaintext non-loopback HTTP) rather than
  * re-deriving a narrower local list.
  */
-export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
+export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|copilot[-_]?session[-_]?token|session[-_]?token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
 
 /**
  * Colon-labelled credential headers echoed back inside an error body
@@ -40,7 +40,7 @@ export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cook
 // Every letter position also accepts \u0001, the placeholder the fold emits for
 // an unresolved HTML named reference: `authorⅈzation` is the label with one
 // character we cannot name, and that is still the label.
-const CREDENTIAL_HEADER_LABEL_RAW = "x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
+const CREDENTIAL_HEADER_LABEL_RAW = "copilot[_-]?session[_-]?token|session[_-]?token|sessionToken|x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
 
 const CREDENTIAL_HEADER_LABEL = CREDENTIAL_HEADER_LABEL_RAW
   .replace(/(?<![\[\\])([A-Za-z])(?![\]\-])/g, "[$1\u0001]");

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