@bitkyc08/opencodex 2.81.0 → 2.82.0

package/src/server/responses/sidecar-send-budget.ts

@@ -0,0 +1,58 @@
+import type { IncomingMeta, ProviderAdapter } from "../../adapters/base";
+import type { HandleResponsesOptions } from "./core-options";
+import type { ResponsesSendBudget } from "./request-send-budget";
+import type { ProviderFetchOptions } from "./fetch-helpers";
+import type { SingleUseDispatchPermit } from "../../lib/request-execution-budget";
+
+/** Hosted inference consumes the same child-owned booking as ordinary dispatch. */
+export function createSidecarSendBudget(
+  options: HandleResponsesOptions,
+  budget: Pick<ResponsesSendBudget, "adapterDispatchBudget" | "noteInitialDispatch" | "noteAdapterPhysicalSend" | "noteAdapterRecoveryWithheld" | "pendingHopPermit">,
+  inputTokens: () => number | undefined,
+) {
+  const initial = options.comboInitialSend;
+  let hopPermit: SingleUseDispatchPermit | undefined;
+  let producerActive = false;
+  /** Detach this owner’s hop before refunding its still-unused reservation. */
+  const releaseHop = (): void => {
+    const permit = hopPermit;
+    hopPermit = undefined;
+    if (budget.pendingHopPermit === permit) budget.pendingHopPermit = undefined;
+    permit?.release();
+  };
+  return {
+    /** Retain a Combo hop until dispatch; direct requests keep eager settlement. */
+    ownCredentialHop(permit?: SingleUseDispatchPermit): void {
+      if (!initial) { permit?.use(); return; } // Preserve direct callers' reporting contract.
+      releaseHop();
+      hopPermit = permit;
+      budget.pendingHopPermit = permit;
+    },
+    // Adapter-owned transports settle through the live dispatch view, not an HTTP receipt too.
+    incomingMeta: initial ? {
+      comboAttempt: options.comboAttempt === true,
+      sendBudget: budget.adapterDispatchBudget,
+      onPhysicalSend: send => budget.noteAdapterPhysicalSend(inputTokens(), send),
+      onRecoveryWithheld: budget.noteAdapterRecoveryWithheld,
+    } satisfies Partial<IncomingMeta> : {},
+    /** Attach HTTP receipts only when the adapter does not own physical dispatch. */
+    fetchOptions(adapter: ProviderAdapter): Pick<ProviderFetchOptions, "onPhysicalDispatch"> {
+      return initial && !adapter.fetchResponse && !adapter.runTurn
+        ? { onPhysicalDispatch: () => {
+          const prepaid = budget.pendingHopPermit;
+          budget.pendingHopPermit = undefined;
+          budget.noteInitialDispatch(prepaid);
+        } } : {};
+    },
+    /** Transfer cleanup to the asynchronous producer before it can outlive the response. */
+    takeProducerOwnership(): void {
+      if (initial) { initial.producerOwned = true; producerActive = true; }
+    },
+    /** Release unused bookings only after the owning producer has settled. */
+    release(): void {
+      initial?.permit.release(); producerActive = false; releaseHop();
+    },
+    /** An iteration may finish before runTurn; defer its refund while that producer is active. */
+    releaseUnsentHop(): void { if (!producerActive) releaseHop(); },
+  };
+}

package/src/server/responses/ws-upstream.ts

@@ -15,6 +15,7 @@ import type { NativeResponseControl } from "./native-response-control";
 // returned event frames as an SSE byte stream, so every downstream consumer
 // (passthrough relay, adapter parsers, usage sniffing) is unchanged.
 
+import { codexWsReuseAcrossTurnsEnabled } from "../../config/codex-ws-reuse-setting";
 import { compareBunVersions } from "../../lib/bun-stream-caps";
 import { resolveProxyRoute, socks5ProxyFromEnv } from "../../lib/proxy-env";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
@@ -26,7 +27,7 @@ import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
 import { isLoopbackUrl, rewriteWebSocketDial } from "../../plugins/upstream-hooks";
 export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
   MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
-  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./codex-ws-wire";
+  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse, isCodexWsPreludeProjection } from "./codex-ws-wire";
 export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
 
 /**
@@ -99,8 +100,10 @@ export function planCodexWsDial(
   // and is authoritative; a pooled socket's upgrade copy is intentionally ignored. A rewriter
   // therefore cannot change them here, and the upgrade keeps the values the frame carries.
   const dialHeaders = { ...rewritten.headers };
+  const reuseAcrossTurns = codexWsReuseAcrossTurnsEnabled();
   for (const name of CODEX_WS_FRAME_HEADERS) {
-    if (Object.hasOwn(headers, name)) dialHeaders[name] = headers[name]!;
+    if (reuseAcrossTurns) delete dialHeaders[name];
+    else if (Object.hasOwn(headers, name)) dialHeaders[name] = headers[name]!;
     else delete dialHeaders[name];
   }
   const dial = { ...rewritten, headers: dialHeaders };
@@ -148,7 +151,8 @@ export function shouldUseCodexWsUpstream(
   }
 }
 
-export function codexWsUpstreamFetch(
+/** Select the bounded WS lane or HTTP fallback, forwarding receipts at physical dispatch. */
+export async function codexWsUpstreamFetch(
   url: string,
   init: RequestInit,
   sseFallback: typeof globalThis.fetch,
@@ -157,6 +161,7 @@ export function codexWsUpstreamFetch(
   beforeDispatch?: (headers: Headers) => void,
   nativeControl?: NativeResponseControl,
   beforeContinuation?: () => Promise<void>,
+  onPhysicalDispatch?: () => void,
 ): Promise<Response> {
   const prepared = prepareCodexWsRequest(url, init);
   if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
@@ -217,8 +222,16 @@ export function codexWsUpstreamFetch(
     const dial = planCodexWsDial(wsUrl, headers, proxy);
     if (!dial) return sseFallback(url, init);
     const identity = control ? null : codexWsReuseIdentity(url, dial.headers, frameText, dial.proxy, dial.url);
-    session = (identity ? codexWsPool.acquire(identity, dial.url, dial.headers, dial.proxy) : null)
-      ?? new CodexWsSession(dial.url, dial.headers, false, undefined, dial.proxy);
+    const reuseAcrossTurns = identity !== null && codexWsReuseAcrossTurnsEnabled();
+    const pooled = identity
+      ? reuseAcrossTurns
+        ? await codexWsPool.acquireWaiting(identity, dial.url, dial.headers, dial.proxy, signal)
+        : codexWsPool.acquire(identity, dial.url, dial.headers, dial.proxy)
+      : null;
+    if (reuseAcrossTurns && signal?.aborted) {
+      return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    session = pooled ?? new CodexWsSession(dial.url, dial.headers, false, undefined, dial.proxy);
     if (!session.busy && !session.reserve()) {
       session.dispose();
       return sseFallback(url, init);
@@ -229,7 +242,7 @@ export function codexWsUpstreamFetch(
   return codexWsExchange({
     session, url, init, prepared, sseFallback, onQuota, beforeDispatch,
     nativeControl: control,
-    beforeContinuation,
+    beforeContinuation, onPhysicalDispatch,
     bunVersion: typeof runtime === "string" ? runtime : runtime.version,
   });
 }

package/src/server/startup-health-cache.ts

@@ -88,7 +88,8 @@ export function markStartupHealthDiagnosticStale(value: StartupHealth): StartupH
     // Mirror deriveStartupHealth's choice: an already-registered service is refreshed in
     // place. Hardcoding installService here silently undid that for every stale-cache
     // read, which is the path the dashboard hits while a probe is revalidating.
-    recommendedCommand: value.routingKind === "opencodex-local" && value.desktop?.owned
+    recommendedAction: value.desktop ? "Reopen OpenCodex and check Start at Login." : value.recommendedAction,
+    recommendedCommand: value.routingKind === "opencodex-local" && value.desktop !== undefined
       ? null
       : value.routingKind === "custom-local" || value.routingKind === "unknown"
       ? value.commands.restoreNative

package/src/server/workflow-refusal.ts

@@ -41,6 +41,8 @@ export interface WorkflowRefusalLog {
   readonly requestId: string;
   readonly start: number;
   readonly logCtx: RequestLogContext;
+  /** Receiving HTTP route's notification after this refusal's final-log call. */
+  readonly onLogged?: () => void;
 }
 
 /**
@@ -84,6 +86,7 @@ export function workflowRefusalResponse(
     addFinalRequestLog(refusalLog.requestId, refusalLog.start, refusalLog.logCtx, 429, {
       closeReason: "terminal",
     });
+    refusalLog.onLogged?.();
   }
   const refusal = formatErrorResponse(
     429,

package/src/service/cli.ts

@@ -26,6 +26,7 @@ import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { win32 } from "node:path";
 import { serviceDiagnosticsSummary } from "./diagnostics";
 import { runServiceClaim } from "./claim";
+import { createSupervisionLatch, desktopServiceCommandRefusal } from "./desktop-command-guard";
 
 /**
  * `restart` is NO LONGER folded into `repair`.
@@ -214,6 +215,7 @@ export function removeServiceTokenAfterUninstall(
 /** Execute a service verb while preserving client-owned credentials during uninstall. */
 export async function serviceCommand(...args: (string | undefined)[]): Promise<void> {
   const filteredArgs = args.filter((a): a is string => Boolean(a));
+  const supervisionLatch = createSupervisionLatch();
   const execute = async (): Promise<void> => {
     // `claim` is not an install verb: it is deliberately outside planServiceCommand (whose
     // backend/installation checks do not apply to an ownership write) and outside
@@ -231,6 +233,12 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       process.exit(1);
     }
     const { parsed, command } = plan;
+    const refusal = desktopServiceCommandRefusal(command, undefined, supervisionLatch);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
   if (command === "repair" || command === "restart") {
     const verb: ServiceRepairVerb = command === "restart" ? "restart" : "repair";
     assertServiceEnvironmentMatchesInstall();
@@ -249,7 +257,7 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     // existing registration had been restarted, not repaired (#4914).
     let repairError: unknown;
     try {
-      await repairService({ verb });
+      await repairService({ verb, supervisionLatch });
     } catch (error) {
       repairError = error;
       process.exitCode = 1;
@@ -295,12 +303,12 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
             throw new Error(`Task Scheduler state could not be verified before install: ${scheduler.detail}`);
           }
           if (scheduler.status === "absent") {
-            await installFreshWindowsSchedulerSafely();
+            await installFreshWindowsSchedulerSafely({ supervisionLatch });
           } else {
-            await installServiceSafely(backend, ops.install);
+            await installServiceSafely(backend, ops.install, { supervisionLatch });
           }
         } else {
-          await installServiceSafely(backend, ops.install);
+          await installServiceSafely(backend, ops.install, { supervisionLatch });
         }
       } catch (error) {
         console.error(`❌ Service install cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -474,6 +482,14 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
   };
 
   const preliminary = parseServiceArgs(filteredArgs);
+  if (preliminary.invalid.length === 0) {
+    const refusal = desktopServiceCommandRefusal(preliminary.sub, undefined, supervisionLatch);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const windowsMutation = process.platform === "win32"
     && preliminary.invalid.length === 0
     && preliminary.sub !== "status";

package/src/service/desktop-command-guard.ts

@@ -0,0 +1,32 @@
+import { createSupervisionLatch, inspectDesktopSupervision } from "./desktop-supervision.mjs";
+
+export { createSupervisionLatch };
+export type DesktopSupervision = ReturnType<typeof inspectDesktopSupervision>;
+export type SupervisionInspector = (deps?: Parameters<typeof inspectDesktopSupervision>[0]) => DesktopSupervision;
+export type SupervisionLatch = ReturnType<typeof createSupervisionLatch>;
+
+export function desktopServiceRefusal(evidence: DesktopSupervision, blocked: boolean): string | null {
+  if (!blocked) return null;
+  const runtime = evidence.kind === "desktop" ? ` (pid ${evidence.runtimePid}, ${evidence.app})` : "";
+  return `OpenCodex Desktop supervises the running proxy${runtime}. `
+    + "Quit OpenCodex, then rerun 'ocx service install' to move startup management to this CLI.";
+}
+
+export function assertNoDesktopSupervision(
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  latch: SupervisionLatch = createSupervisionLatch(),
+): void {
+  const evidence = inspect();
+  const refusal = desktopServiceRefusal(evidence, latch.observe(evidence));
+  if (refusal) throw new Error(refusal);
+}
+
+export function desktopServiceCommandRefusal(
+  command: string,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  latch: SupervisionLatch = createSupervisionLatch(),
+): string | null {
+  if (!["install", "repair", "start", "restart"].includes(command)) return null;
+  const evidence = inspect();
+  return desktopServiceRefusal(evidence, latch.observe(evidence));
+}

package/src/service/desktop-startup.ts

@@ -1,9 +1,10 @@
 import { execFileSync } from "node:child_process";
-import { accessSync, constants, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { readPid } from "../config/process-state";
 import { resolveServiceOwnership, sameServiceOwnershipSubject, type ServiceOwnershipResolution } from "./state";
+import { inspectDesktopSupervision, processIdentity, procfs, type ProcReader } from "./desktop-supervision.mjs";
 
 export interface DesktopStartupDiagnostic {
   /** Durable desktop claim; failed supervision does not release ownership. */
@@ -11,11 +12,13 @@ export interface DesktopStartupDiagnostic {
   loginEnabled: boolean;
   running: boolean;
   viable: boolean;
+  /** Live parentage when no durable claim exists; never converts supervision into ownership. */
+  supervisor?: { supervisorPid: number; runtimePid: number; app: string };
 }
 
-/** A login item alone is insufficient: the same app must own and supervise this proxy. */
+/** A login item alone is insufficient: the same app must supervise this proxy. */
 export function deriveDesktopStartup(facts: Omit<DesktopStartupDiagnostic, "viable">): DesktopStartupDiagnostic {
-  return { ...facts, viable: facts.owned && facts.loginEnabled && facts.running };
+  return { ...facts, viable: (facts.owned || facts.supervisor !== undefined) && facts.loginEnabled && facts.running };
 }
 
 function run(command: string, args: string[]): string {
@@ -28,25 +31,12 @@ interface DesktopStartupDeps {
   uid?: number;
   ownership?: () => ServiceOwnershipResolution;
   readPid?: () => number | null;
+  readRuntimePortPid?: () => number | null;
   run?: typeof run;
   env?: NodeJS.ProcessEnv;
   proc?: ProcReader;
 }
 
-/** Linux process identity from procfs: executable target and parent pid. */
-interface ProcReader {
-  exe(pid: number): string;
-  parent(pid: number): number;
-}
-const procfs: ProcReader = {
-  exe: pid => readlinkSync(`/proc/${pid}/exe`),
-  // comm may contain spaces or parentheses, so fields are counted after the last ')'.
-  parent: pid => {
-    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
-  },
-};
-
 /** Cheap ownership-only snapshot: no launchd/process probes on the server request path. */
 export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopStartupDiagnostic | undefined {
   const platform = deps.platform ?? process.platform;
@@ -56,9 +46,47 @@ export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopS
     ? deriveDesktopStartup({ owned: true, loginEnabled: false, running: false }) : undefined;
 }
 
-function processIdentity(pid: number, execute: typeof run): { parent: number; executable: string } | null {
-  const row = /^(\d+)\s+(.+)$/.exec(execute("/bin/ps", ["-p", String(pid), "-o", "ppid=,comm="]));
-  return row ? { parent: Number(row[1]), executable: realpathSync(row[2]!) } : null;
+function macLoginRegistration(deps: DesktopStartupDeps) {
+  const execute = deps.run ?? run;
+  const path = join(deps.home ?? homedir(), "Library", "LaunchAgents", "OpenCodex.plist");
+  const plist = JSON.parse(execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]));
+  const args = plist.ProgramArguments;
+  if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
+    || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
+    || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
+    || (plist.Program !== undefined && plist.Program !== args[0])) return null;
+  const app = realpathSync(args[0]);
+  const proxy = realpathSync(join(dirname(app), "ocx"));
+  accessSync(app, constants.X_OK);
+  accessSync(proxy, constants.X_OK);
+  const domain = `gui/${deps.uid ?? process.getuid!()}`;
+  const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
+  const loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]);
+  const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
+  const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
+  const loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
+    && !/"OpenCodex"\s*=>\s*(?:disabled|true)/.test(disabled)
+    && program !== undefined && realpathSync(program) === app
+    && loadedPath !== undefined && realpathSync(loadedPath) === realpathSync(path);
+  return { app, proxy, loginEnabled };
+}
+
+function diagnoseSupervisedStartup(deps: DesktopStartupDeps, ownerRevision: number, loginFor: (app: string) => boolean): DesktopStartupDiagnostic | undefined {
+  const evidence = inspectDesktopSupervision(deps);
+  if (evidence.kind !== "desktop") return undefined;
+  let loginEnabled = false;
+  try { loginEnabled = loginFor(evidence.app); }
+  catch { /* Login failure revokes restart viability, not the observed live supervisor. */ }
+  if ((deps.ownership ?? resolveServiceOwnership)().kind !== "none") return undefined;
+  // Login probes can outlive the runtime or its parent; only the same live chain gets credit.
+  const final = inspectDesktopSupervision({ ...deps, targetPid: evidence.runtimePid });
+  if (final.kind !== "desktop" || final.runtimePid !== evidence.runtimePid
+    || final.supervisorPid !== evidence.supervisorPid || final.app !== evidence.app) return undefined;
+  // A new claim or revision during the last process probe invalidates the unowned projection.
+  const finalOwner = (deps.ownership ?? resolveServiceOwnership)();
+  if (finalOwner.kind !== "none" || finalOwner.revision !== ownerRevision) return undefined;
+  const { supervisorPid, runtimePid, app } = evidence;
+  return deriveDesktopStartup({ owned: false, loginEnabled, running: true, supervisor: { supervisorPid, runtimePid, app } });
 }
 
 /** Read-only macOS desktop ownership, login registration and live parent/child checks. */
@@ -66,6 +94,10 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
   if ((deps.platform ?? process.platform) !== "darwin") return undefined;
   const ownership = deps.ownership ?? resolveServiceOwnership;
   const owner = ownership();
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => {
+    const login = macLoginRegistration(deps);
+    return login !== null && login.app === app && login.loginEnabled;
+  });
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
   const facts = { owned: true, loginEnabled: false, running: false };
   const execute = deps.run ?? run;
@@ -74,26 +106,10 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
     const home = deps.home ?? homedir();
     const id = readFileSync(join(home, "Library", "Application Support", "com.opencodex.desktop", "install-id"), "utf8").trim();
     if (id !== owner.ownership.installId) return deriveDesktopStartup(facts);
-    const path = join(home, "Library", "LaunchAgents", "OpenCodex.plist");
-    const plist = JSON.parse(execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]));
-    const args = plist.ProgramArguments;
-    if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
-      || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
-      || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
-      || (plist.Program !== undefined && plist.Program !== args[0])) return deriveDesktopStartup(facts);
-    const app = realpathSync(args[0]);
-    const proxy = realpathSync(join(dirname(app), "ocx"));
-    accessSync(app, constants.X_OK);
-    accessSync(proxy, constants.X_OK);
-    const domain = `gui/${deps.uid ?? process.getuid!()}`;
-    const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
-    const loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]);
-    const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
-    const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
-    facts.loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
-      && !/"OpenCodex"\s*=>\s*(?:disabled|true)/.test(disabled)
-      && program !== undefined && realpathSync(program) === app
-      && loadedPath !== undefined && realpathSync(loadedPath) === realpathSync(path);
+    const login = macLoginRegistration(deps);
+    if (!login) return deriveDesktopStartup(facts);
+    const { app, proxy } = login;
+    facts.loginEnabled = login.loginEnabled;
     const pid = pidReader();
     if (pid !== null) {
       const child = processIdentity(pid, execute);
@@ -135,6 +151,16 @@ export function diagnoseLinuxDesktopStartup(deps: DesktopStartupDeps = {}): Desk
   if ((deps.platform ?? process.platform) !== "linux") return undefined;
   const ownership = deps.ownership ?? resolveServiceOwnership;
   const owner = ownership();
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => {
+    const home = deps.home ?? homedir();
+    const configured = (deps.env ?? process.env).XDG_CONFIG_HOME;
+    const config = configured && isAbsolute(configured) ? configured : join(home, ".config");
+    // auto-launch's HOME entry must remain inside the session's XDG autostart search path.
+    if (resolve(config) !== resolve(home, ".config")) return false;
+    const entry = readFileSync(join(home, ".config", "autostart", "OpenCodex.desktop"), "utf8");
+    const login = linuxLoginApp(entry);
+    return login !== null && realpathSync(login) === app;
+  });
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
   const facts = { owned: true, loginEnabled: false, running: false };
   const proc = deps.proc ?? procfs;

package/src/service/desktop-supervision.d.mts

@@ -0,0 +1,26 @@
+export type SupervisionEvidence =
+  | { kind: "desktop"; runtimePid: number; supervisorPid: number; app: string; proxy: string }
+  | { kind: "none" }
+  | { kind: "unknown"; reason: string; desktopSeen: boolean }
+  | { kind: "unsupported" };
+
+export interface ProcReader {
+  exe(pid: number): string;
+  parent(pid: number): number;
+}
+
+export interface DesktopSupervisionDeps {
+  targetPid?: number;
+  platform?: NodeJS.Platform;
+  run?: (command: string, args: string[]) => string;
+  proc?: ProcReader;
+  readPid?: () => number | null;
+  readRuntimePortPid?: () => number | null;
+}
+
+export function desktopSupervisionPaths(): { pid: string; runtimePort: string };
+export const procfs: ProcReader;
+export function processIdentity(pid: number, execute?: DesktopSupervisionDeps["run"], onExecutable?: (path: string) => void):
+  { parent: number; executable: string } | null;
+export function inspectDesktopSupervision(deps?: DesktopSupervisionDeps): SupervisionEvidence;
+export function createSupervisionLatch(): { observe(evidence: SupervisionEvidence): boolean };

package/src/service/desktop-supervision.mjs

@@ -0,0 +1,140 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+// Node >=18 also imports this module from bin/ocx.mjs; do not import TS or Bun APIs.
+function run(command, args) {
+  return execFileSync(command, args, {
+    encoding: "utf8", timeout: 750, maxBuffer: 128 * 1024, stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+// Mirror src/config/paths.ts getConfigDir/expandUserPath and process-state.ts paths.
+// Keep this Node-safe copy in sync; the focused startup test pins both implementations.
+export function desktopSupervisionPaths() {
+  const raw = process.env.OPENCODEX_HOME?.trim();
+  const expanded = raw === "~" ? homedir()
+    : raw?.startsWith("~/") || raw?.startsWith("~\\") ? join(homedir(), raw.slice(2)) : raw;
+  const home = expanded ? resolve(expanded) : join(homedir(), ".opencodex");
+  return { pid: join(home, "ocx.pid"), runtimePort: join(home, "runtime-port.json") };
+}
+
+function validPid(pid) {
+  return Number.isSafeInteger(pid) && pid > 0;
+}
+
+function readState(path, parse) {
+  try { return parse(readFileSync(path, "utf8")); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function readPidFile() {
+  return readState(desktopSupervisionPaths().pid, raw => {
+    const text = raw.trim();
+    if (!/^\d+$/.test(text) || !validPid(Number(text))) throw new Error("invalid pid");
+    return Number(text);
+  });
+}
+
+function readRuntimePortPid() {
+  return readState(desktopSupervisionPaths().runtimePort, raw => {
+    // Only project pid: no credential validation, serialization or returned port state.
+    const pid = JSON.parse(raw)?.pid;
+    if (!validPid(pid)) throw new Error("invalid runtime pid");
+    return pid;
+  });
+}
+
+/** Linux identity fields count from the end of comm, which may contain spaces or ')'. */
+export const procfs = {
+  exe: pid => readlinkSync(`/proc/${pid}/exe`),
+  parent: pid => {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+  },
+};
+
+export function processIdentity(pid, execute = run, onExecutable) {
+  const text = execute("/bin/ps", ["-p", String(pid), "-o", "ppid=,comm="]).trim();
+  const row = /^(\d+)\s+(.+)$/.exec(text);
+  if (!row) {
+    if (text) throw new Error("invalid process identity");
+    return null;
+  }
+  onExecutable?.(row[2]);
+  return { parent: Number(row[1]), executable: realpathSync(row[2]) };
+}
+
+/** Live supervision is evidence, never a durable ownership claim. */
+export function inspectDesktopSupervision(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux") return { kind: "unsupported" };
+  let desktopSeen = false;
+  const unknown = reason => ({ kind: "unknown", reason, desktopSeen });
+  const seen = executable => { if (basename(executable) === "opencodex-desktop") desktopSeen = true; };
+  const readPid = deps.readPid ?? readPidFile;
+  const readPortPid = deps.readRuntimePortPid ?? readRuntimePortPid;
+  const proc = deps.proc ?? procfs;
+  const execute = deps.run ?? run;
+  function identity(pid, parent = false) {
+    if (platform === "darwin") return processIdentity(pid, execute, parent ? seen : undefined);
+    const executable = proc.exe(pid);
+    if (parent) seen(executable);
+    const parentPid = proc.parent(pid);
+    if (!Number.isSafeInteger(parentPid) || parentPid < 0) throw new Error("invalid parent pid");
+    return { parent: parentPid, executable: realpathSync(executable) };
+  }
+  function capture() {
+    const pidFile = readPid();
+    const portPid = readPortPid();
+    const pids = [deps.targetPid, pidFile, portPid].filter(pid => pid !== undefined && pid !== null);
+    if (pids.some(pid => !validPid(pid))) return { error: "invalid-pid" };
+    if (pids.some(pid => pid !== pids[0])) return { error: "pid-mismatch" };
+    const runtimePid = pids[0] ?? null;
+    const child = runtimePid !== null ? identity(runtimePid) : null;
+    const parent = child && child.parent > 1 ? identity(child.parent, true) : null;
+    const snapshot = { pidFile, portPid, runtimePid, child, parent };
+    if (!runtimePid || !child || !parent || basename(parent.executable) !== "opencodex-desktop") {
+      return { ...snapshot, kind: "none" };
+    }
+    seen(parent.executable);
+    const app = parent.executable;
+    if (platform === "darwin" && (basename(dirname(app)) !== "MacOS"
+      || basename(dirname(dirname(app))) !== "Contents")) return { error: "app-mismatch" };
+    const proxy = realpathSync(join(dirname(app), "ocx"));
+    if (child.executable !== proxy || (platform === "linux"
+      && (dirname(proxy) !== dirname(app) || basename(proxy) !== "ocx"))) return { error: "proxy-mismatch" };
+    accessSync(app, constants.X_OK);
+    accessSync(proxy, constants.X_OK);
+    return { ...snapshot, kind: "desktop", app, proxy };
+  }
+  try {
+    const first = capture();
+    if (first.error) return unknown(first.error);
+    const final = capture();
+    if (final.error) return unknown(final.error);
+    if (JSON.stringify(first) !== JSON.stringify(final)) return unknown("snapshot-changed");
+    return final.kind === "desktop"
+      ? { kind: "desktop", runtimePid: final.runtimePid, supervisorPid: final.child.parent, app: final.app, proxy: final.proxy }
+      : { kind: "none" };
+  } catch {
+    // Error messages can contain paths or file contents; expose only the bounded reason.
+    return unknown("probe-failed");
+  }
+}
+
+/** One operation retains its Desktop veto through inconclusive later probes. */
+export function createSupervisionLatch() {
+  let blocked = false;
+  return {
+    observe(evidence) {
+      if (evidence.kind === "none") blocked = false;
+      else if (evidence.kind === "desktop" || (evidence.kind === "unknown" && evidence.desktopSeen)) blocked = true;
+      return blocked;
+    },
+  };
+}

package/src/service/managing-cli.ts

@@ -81,6 +81,7 @@ function probeVersionOnce(
       windowsShim ? ["/c", shimCommand] : [...args, "--version"],
       {
         timeout: VERSION_PROBE_TIMEOUT_MS, encoding: "utf8", stdio: "pipe",
+        env: { ...deps.env, OCX_NO_DESKTOP_HANDOFF: "1" },
         windowsHide: true, ...(windowsShim ? { windowsVerbatimArguments: true } : {}),
       },
     ) as SpawnSyncReturns<string>;