@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/integrations/aside-profiles.ts

@@ -8,7 +8,7 @@ import { readIntegrationState, type IntegrationState, type IntegrationStatus } f
 import {
   applyIntegrationCoordinated, disableIntegrationCoordinated,
   overwriteIntegrationCoordinated, refreshIntegrationCoordinated,
-  type IntegrationWriteInput,
+  type CoordinatedIntegrationOptions, type IntegrationWriteInput,
 } from "./writer";
 import {
   asideProfileEnabled, asideProfileFailure, asideProfileScope, asideWriteInput,
@@ -260,7 +260,10 @@ export function mutateAsideProfiles(
   });
 }
 
-export function refreshAsideProfiles(input: AsideProfilesInput): Promise<Array<OwnedIntegrationRefreshOutcome & { profileId: number }>> {
+export function refreshAsideProfiles(
+  input: AsideProfilesInput,
+  options?: { refreshOnly?: boolean; guard?: CoordinatedIntegrationOptions["guard"] },
+): Promise<Array<OwnedIntegrationRefreshOutcome & { profileId: number }>> {
   const policy = input.config.asideProfileSync;
   const selected = Object.values(policy?.profiles ?? {}).some(enabled => enabled === true);
   if (!selected && (policy?.allProfiles === false
@@ -272,11 +275,15 @@ export function refreshAsideProfiles(input: AsideProfilesInput): Promise<Array<O
       try {
         const scope = asideProfileScope(ctx, profile);
         const owned = scope.store.readRecords().aside !== undefined;
+        if (options?.refreshOnly && !owned) continue;
         const bound = await asideWriteInput(ctx, scope);
         // A surviving ownership record means a removed block stays removed.
         // A newly discovered, enabled profile may receive its first safe apply.
         const operation = owned ? refreshIntegrationCoordinated : applyIntegrationCoordinated;
-        const result = await operation(bound, { lockSeams: input.lockSeams });
+        const result = await operation(bound, {
+          lockSeams: input.lockSeams,
+          ...(options?.guard ? { guard: options.guard } : {}),
+        });
         outcomes.push({
           client: "aside", profileId: profile.id, ok: result.ok,
           ...(result.ok ? { changed: result.changed } : {}),

package/src/integrations/catalog-refresh.ts

@@ -2,6 +2,7 @@ import { siblingOfLivePort } from "../codex/sibling-start";
 import { redactSecretString } from "../lib/redact";
 import type { ExportModel } from "../clients/config-export";
 import type { IntegrationClientId } from "./registry";
+import type { CoordinatedIntegrationOptions, WriteOutcome } from "./writer";
 import {
   refreshOwnedIntegration,
   type OwnedIntegrationRefreshInput,
@@ -11,7 +12,8 @@ import {
 /** Refresh only previously connected clients; a refused file never blocks its peers. */
 export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
-  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "droid", "opencode", "kilo"],
+  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo"],
+  options: { refreshOnly?: boolean; admit?: () => boolean } = {},
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
   // Client files are shared with the live proxy a sibling instance runs beside; their entries
   // point at the owner's port, and refreshing them here would re-point them at this one.
@@ -20,14 +22,28 @@ export async function refreshOwnedCatalogIntegrations(
   const loadModels = () => models ??= Promise.resolve().then(() =>
     typeof input.models === "function" ? input.models() : input.models);
   const outcomes: OwnedIntegrationRefreshOutcome[] = [];
+  const admit = options.admit;
+  const writeOptions: CoordinatedIntegrationOptions | undefined = admit ? {
+    guard: (frozen): WriteOutcome | null => admit() ? null : {
+      ok: false, reason: "superseded_store", state: "current", clientId: frozen.clientId,
+      message: "Background refresh superseded",
+    },
+  } : undefined;
   for (const clientId of clientIds) {
+    if (admit?.() === false) break;
     try {
       if (clientId === "aside") {
         const { refreshAsideProfiles } = await import("./aside-profiles");
-        outcomes.push(...await refreshAsideProfiles({ ...input, models: loadModels }));
+        const asideOptions = options.refreshOnly === undefined ? writeOptions
+          : { ...writeOptions, refreshOnly: options.refreshOnly };
+        const bound = { ...input, models: loadModels };
+        outcomes.push(...await (asideOptions === undefined
+          ? refreshAsideProfiles(bound) : refreshAsideProfiles(bound, asideOptions)));
         continue;
       }
-      const result = await refreshOwnedIntegration({ ...input, clientId, models: loadModels });
+      const bound = { ...input, clientId, models: loadModels };
+      const result = await (writeOptions === undefined
+        ? refreshOwnedIntegration(bound) : refreshOwnedIntegration(bound, writeOptions));
       if (result) outcomes.push(result);
     } catch (error) {
       const busy = error !== null && typeof error === "object"

package/src/integrations/mutation-plan.ts

@@ -149,6 +149,13 @@ const CLIENT_MANAGED_PATHS = {
     [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
     [...ZCODE_STORE_MODEL_RULES_PATH, DYNAMIC_SEGMENT],
   ],
+  /*
+   * Both roots, because the client picks between them rather than reading both:
+   * `document.provider ?? document.providers` in `command-code@1.66.0`. The
+   * builder chooses the one the target already uses, and a block we wrote under
+   * either root has to be removable from either root afterwards.
+   */
+  commandcode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]],
   prime: [["providers", OPENCODE_PROVIDER_ID]],
   aside: [["providers", OPENCODE_PROVIDER_ID]],
   raycast: [["providers", `[id=${OPENCODE_PROVIDER_ID}]`]],

package/src/integrations/registry.ts

@@ -58,6 +58,8 @@ import {
   DSH_PROFILE_PROVIDER_PATH,
   type BuildContribution,
   type ConfigFormat,
+  commandCodeConfigPath,
+  commandCodeHomeDir,
   kiloConfigPath,
   kiloHomeDir,
   kiloCandidatePath,
@@ -369,6 +371,12 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
       buildContribution: buildZcodeStoreContribution,
     },
   },
+  commandcode: {
+    id: "commandcode",
+    configPath: (env = process.env, home = homedir()) => commandCodeConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => commandCodeHomeDir(env, home),
+    writerLock: { suffix: ".lock" },
+  },
   prime: {
     id: "prime",
     configPath: (env = process.env, home = homedir()) => primeConfigPath(env, home),

package/src/integrations/state.ts

@@ -490,7 +490,8 @@ export function exportContextOf(input: {
   config: OcxConfig;
   port: number;
   droidReasoningDefaults?: Record<string, string>;
-}): { baseUrl: string; models: readonly ExportModel[]; config: OcxConfig; droidReasoningDefaults?: Record<string, string> } {
+  document?: unknown;
+}): { baseUrl: string; models: readonly ExportModel[]; config: OcxConfig; droidReasoningDefaults?: Record<string, string>; document?: unknown } {
   return {
     /*
      * Composed through the SAME helper `ocx export` uses. Interpolating the
@@ -505,6 +506,9 @@ export function exportContextOf(input: {
     models: input.models,
     config: input.config,
     ...(input.droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: input.droidReasoningDefaults }),
+    // Forwarded only when the caller parsed a target: a client that resolves
+    // between two document roots (Command Code) needs the bytes on disk.
+    ...(input.document === undefined ? {} : { document: input.document }),
   };
 }
 
@@ -514,7 +518,10 @@ export function buildIntegrationContribution(
   parsed: unknown,
   record: OwnershipRecord | null,
 ): ManagedContribution {
-  const context = exportContextOf(input);
+  // The parsed target travels with the context: a client whose reader picks
+  // between two document roots (Command Code) must see the bytes on disk, and
+  // routing it through this one builder keeps classify, plan and write agreeing.
+  const context = exportContextOf({ ...input, document: parsed });
   if (input.clientId === "droid" && input.droidReasoningDefaults === undefined && record?.configPath === effective.configPath) {
     const inherited = recordedDroidContributionMatches(parsed, record)
       ? droidDefaultsFromOwnedRows(context, parsed, record.fragmentPaths)

package/src/integrations/writer.ts

@@ -18,7 +18,7 @@ import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { detachedConfigSnapshot } from "../config/admitted-identity";
 import { copyPlainData } from "../lib/plain-data";
 import type { OcxConfig } from "../types";
-import { defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { inspectKiloCandidates } from "./kilo-candidates";
 import {
   fingerprint,
@@ -727,9 +727,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   // exact bytes when the snapshot was taken. Re-deriving it from the file would
   // mean guessing which entries are ours, and a wrong guess deletes a user's.
   const restoredRecord = entry.priorRecord;
+  let restoredDocument = clientId === "droid" && restoredText !== null ? parseConfig(restoredText, "json") : undefined;
+  if (clientId === "commandcode" && restoredText !== null) {
+    const parsed = parseConfig(restoredText, "json");
+    // Restoring raw snapshot bytes must remain possible even when they are not parseable.
+    restoredDocument = parsed === PARSE_FAILED ? undefined : parsed;
+  }
   const fresh = buildIntegrationContribution(
     { ...input, droidReasoningDefaults: undefined }, rowTarget,
-    clientId === "droid" && restoredText !== null ? parseConfig(restoredText, "json") : undefined,
+    restoredDocument,
     restoredRecord,
   );
   /*
@@ -795,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. */
@@ -936,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;