@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/desktop-compatibility/installed-build.ts

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { win32 } from "node:path";
+import { isTestHomeGuardArmed } from "../../lib/test-home-guard";
+import { resolveTrustedWindowsPowerShellExe } from "../../lib/windows-elevation";
+import { parseWindowsDesktopPackage, WINDOWS_PACKAGE_DISCOVERY_SCRIPT } from "../desktop-app/windows";
+import type { DesktopAppInstall } from "../desktop-app/types";
+
+export const DESKTOP_COMPATIBILITY_ASSESSED_VERSION = "26.924.2738.0";
+export const DESKTOP_COMPATIBILITY_ASSESSED_FAMILY = "OpenAI.Codex_2p2nqsd0c76g0";
+
+/** Last completed probe outcome. Only public package facts: never paths, keys or account data. */
+export interface DesktopBuildAssessment {
+  assessedVersion: string;
+  observedVersion: string | null;
+  verified: boolean;
+  completedAt: number;
+}
+
+function assessInstalledPackage(install: DesktopAppInstall): { observedVersion: string | null; verified: boolean } {
+  const name = win32.basename(install.root);
+  const parts = /^OpenAI\.Codex_(\d+\.\d+\.\d+\.\d+)_(x64|arm64|x86|neutral)_([A-Za-z0-9.-]*)_([A-Za-z0-9]+)$/.exec(name);
+  const identified = install.id === DESKTOP_COMPATIBILITY_ASSESSED_FAMILY && install.relaunch === `${install.id}!App`
+    && !!parts && `OpenAI.Codex_${parts[4]}` === install.id;
+  const observedVersion = identified ? parts![1] : null;
+  return { observedVersion, verified: identified && observedVersion === DESKTOP_COMPATIBILITY_ASSESSED_VERSION };
+}
+
+/** Resolve only after the exact asynchronous child has closed, including abort/timeout. */
+function queryInstalledPackage(signal: AbortSignal): Promise<DesktopAppInstall | null> {
+  if (process.platform !== "win32" || isTestHomeGuardArmed() || signal.aborted) return Promise.resolve(null);
+  return new Promise(resolve => {
+    let completed = false, closed = false, result: DesktopAppInstall | null = null;
+    const finish = () => { if (completed && closed) { signal.removeEventListener("abort", abort); resolve(result); } };
+    const child = execFile(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_PACKAGE_DISCOVERY_SCRIPT], {
+      timeout: 10000, maxBuffer: 65536, encoding: "utf8", windowsHide: true,
+    }, (error, stdout) => { result = error ? null : parseWindowsDesktopPackage(stdout); completed = true; finish(); });
+    const abort = () => { try { child.kill(); } catch { /* Keep ownership until execFile reports close. */ } };
+    child.once("close", () => { closed = true; finish(); });
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+}
+
+/** Coalesce concurrent fresh probes; never cache a positive verdict across requests. */
+export function createInstalledBuildProbe(query: (signal: AbortSignal) => Promise<DesktopAppInstall | null> = queryInstalledPackage) {
+  let pending: Promise<boolean> | null = null, controller: AbortController | null = null, closed = false;
+  let lastResult: DesktopBuildAssessment | null = null;
+  const record = (install: DesktopAppInstall | null) => {
+    const outcome = install ? assessInstalledPackage(install) : { observedVersion: null, verified: false };
+    lastResult = { assessedVersion: DESKTOP_COMPATIBILITY_ASSESSED_VERSION, ...outcome, completedAt: Date.now() };
+    return outcome.verified;
+  };
+  return {
+    check(): Promise<boolean> {
+      if (closed) return Promise.resolve(false);
+      if (pending) return pending;
+      const current = new AbortController(); controller = current;
+      pending = Promise.resolve().then(() => current.signal.aborted ? null : query(current.signal))
+        .then(install => closed || current.signal.aborted ? false : record(install))
+        .catch(() => closed || current.signal.aborted ? false : record(null))
+        .finally(() => { pending = null; controller = null; });
+      return pending;
+    },
+    /** Last completed check only: an aborted or in-flight query never rewrites it. */
+    lastResult(): DesktopBuildAssessment | null { return lastResult ? { ...lastResult } : null; },
+    async close(): Promise<void> { closed = true; controller?.abort(); await pending; },
+  };
+}
+
+export async function isAssessedDesktopInstalled(): Promise<boolean> {
+  const probe = createInstalledBuildProbe();
+  try { return await probe.check(); } finally { await probe.close(); }
+}

package/src/codex/desktop-compatibility/json-body.ts

@@ -0,0 +1,29 @@
+/** Buffer small JSON only; large bodies pass through without collecting the remainder. */
+export async function boundedJsonBody(body: ReadableStream<Uint8Array> | null, maxBytes = 262144): Promise<{ bytes: Buffer } | { stream: ReadableStream<Uint8Array> }> {
+  if (!body) return { bytes: Buffer.alloc(0) };
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let count = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) { reader.releaseLock(); return { bytes: Buffer.concat(chunks, count) }; }
+      chunks.push(next.value); count += next.value.byteLength;
+      if (count <= maxBytes && chunks.length < 1024) continue;
+      let index = 0;
+      return { stream: new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          if (index < chunks.length) {
+            const value = chunks[index]!; chunks[index++] = new Uint8Array(0); controller.enqueue(value); return;
+          }
+          try {
+            const part = await reader.read();
+            if (part.done) { reader.releaseLock(); controller.close(); }
+            else controller.enqueue(part.value);
+          } catch (error) { reader.releaseLock(); controller.error(error); }
+        },
+        async cancel(reason) { try { await reader.cancel(reason); } finally { reader.releaseLock(); } },
+      }) };
+    }
+  } catch (error) { reader.releaseLock(); throw error; }
+}

package/src/codex/desktop-compatibility/native-identity.ts

@@ -0,0 +1,62 @@
+import { readFileSync, statSync, type BigIntStats } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import type { UsageIdentity } from './usage-controller';
+
+type Credential = { identity: UsageIdentity; accessToken: string };
+const equal = (a: UsageIdentity, b: UsageIdentity) => a.id === b.id && a.userId === b.userId && a.plan === b.plan
+  && a.credentialGeneration === b.credentialGeneration;
+
+/** Local native credentials remain in memory and are never returned by the public reader. */
+export function createNativeIdentityReader(authPath: string, upstreamFetch: typeof fetch = fetch) {
+  const readerId = randomUUID(); let generation = 0, previousSnapshot: string | undefined;
+  const stamp = (value: BigIntStats) =>
+    `${value.dev}:${value.ino}:${value.size}:${value.mtimeNs}:${value.ctimeNs}`;
+  const readCredential = (): Credential => {
+    const before = statSync(authPath, { bigint: true });
+    if (before.size > 1048576n) throw new Error('Unexpected native auth size');
+    const text = readFileSync(authPath, 'utf8'), after = statSync(authPath, { bigint: true });
+    if (stamp(before) !== stamp(after)) throw new Error('Native credentials changed during read');
+    const snapshot = `${stamp(after)}:${createHash('sha256').update(text).digest('hex')}`;
+    if (snapshot !== previousSnapshot) { previousSnapshot = snapshot; generation++; }
+    const auth = JSON.parse(text);
+    if (auth.auth_mode !== 'chatgpt' || typeof auth.tokens?.id_token !== 'string'
+      || typeof auth.tokens?.access_token !== 'string' || !auth.tokens.access_token
+      || typeof auth.tokens?.account_id !== 'string') throw new Error('Native login required');
+    // These local claims are only a binding hint. Activation additionally verifies upstream.
+    const claims = JSON.parse(Buffer.from(auth.tokens.id_token.split('.')[1], 'base64url').toString('utf8'))['https://api.openai.com/auth'];
+    if (!claims || claims.chatgpt_account_id !== auth.tokens.account_id
+      || typeof claims.chatgpt_user_id !== 'string' || !claims.chatgpt_user_id
+      || !['plus', 'pro'].includes(claims.chatgpt_plan_type)) throw new Error('Unsupported identity');
+    return { identity: { id: auth.tokens.account_id, userId: claims.chatgpt_user_id,
+      plan: claims.chatgpt_plan_type, structure: 'personal', credentialGeneration: `${readerId}:${generation}` }, accessToken: auth.tokens.access_token };
+  };
+  const readCurrentIdentity = async (): Promise<UsageIdentity | null> => {
+    try { return readCredential().identity; } catch { return null; }
+  };
+  const verifyFreshIdentity = async (): Promise<UsageIdentity | null> => {
+    try {
+      const before = readCredential();
+      const response = await upstreamFetch('https://chatgpt.com/backend-api/wham/usage', {
+        headers: { authorization: 'Bearer ' + before.accessToken, 'ChatGPT-Account-ID': before.identity.id },
+        redirect: 'manual', signal: AbortSignal.timeout(10000),
+      });
+      if (response.status !== 200 || !response.body) { await response.body?.cancel(); return null; }
+      const reader = response.body.getReader(); const chunks: Uint8Array[] = []; let size = 0;
+      try {
+        for (;;) {
+          const part = await reader.read(); if (part.done) break;
+          size += part.value.length;
+          if (size > 65536) { await reader.cancel(); return null; }
+          chunks.push(part.value);
+        }
+      } finally { reader.releaseLock(); }
+      const usage = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      const after = readCredential();
+      if (!equal(before.identity, after.identity) || before.accessToken !== after.accessToken
+        || usage.account_id !== before.identity.id || usage.user_id !== before.identity.userId
+        || usage.plan_type !== before.identity.plan) return null;
+      return before.identity;
+    } catch { return null; }
+  };
+  return { readCurrentIdentity, verifyFreshIdentity };
+}

package/src/codex/desktop-compatibility/relay-listener.ts

@@ -0,0 +1,93 @@
+import { createServer } from "node:https";
+import { Readable, type Duplex } from "node:stream";
+import type { PemKeyPair } from "../../claude/intercept/local-ca";
+import { forwardHeadersForUpstream } from "../../claude/intercept/listener";
+import { dialDesktopUpstream, type DesktopTunnelOptions } from "../../lib/desktop-upstream-tunnel";
+
+const ORIGIN = "https://chatgpt.com";
+const STRIP = new Set(["connection", "keep-alive", "transfer-encoding", "content-encoding", "content-length", "alt-svc", "proxy-authenticate"]);
+export interface DesktopRelayOptions {
+  leaf: PemKeyPair;
+  fetchImpl: typeof fetch;
+  /** Test-only TLS peer; the production destination is fixed, never taken from a request. */
+  websocketPeer?: { host: string; port: number; ca: string };
+  websocketTransport?: Pick<DesktopTunnelOptions, "proxy" | "proxyCa" | "timeoutMs">;
+}
+
+/** Transparent HTTP and raw upgraded-socket relay. Only fetchImpl owns usage policy. */
+export async function startDesktopRelay(options: DesktopRelayOptions) {
+  const sockets = new Set<Duplex>(), requests = new Set<AbortController>();
+  const server = createServer({ cert: options.leaf.certPem, key: options.leaf.keyPem, ALPNProtocols: ["http/1.1"] });
+  server.on("connection", socket => { sockets.add(socket); socket.once("close", () => sockets.delete(socket)); });
+  const valid = (host: string | undefined, path: string | undefined) =>
+    (host?.toLowerCase() === "chatgpt.com" || host?.toLowerCase() === "chatgpt.com:443") && !!path && path.startsWith("/") && !path.startsWith("//");
+  server.on("request", (req, res) => {
+    if (!valid(req.headers.host, req.url)) { res.writeHead(421); res.end(); return; }
+    const abort = new AbortController(); requests.add(abort);
+    const finish = () => { requests.delete(abort); abort.abort(); };
+    res.once("close", finish); req.once("error", finish);
+    void (async () => {
+      const headers = new Headers();
+      for (let i = 0; i < req.rawHeaders.length; i += 2) headers.append(req.rawHeaders[i]!, req.rawHeaders[i + 1]!);
+      const method = req.method ?? "GET";
+      const response = await options.fetchImpl(ORIGIN + req.url, {
+        method, headers: forwardHeadersForUpstream(headers), redirect: "manual", signal: abort.signal,
+        // Node's and Bun's declarations disagree on BYOB overloads; both implement Web streams.
+        body: method === "GET" || method === "HEAD" ? undefined : Readable.toWeb(req) as unknown as ReadableStream<Uint8Array>,
+        // @ts-expect-error Node-compatible streaming fetch requires half duplex.
+        duplex: "half",
+      });
+      if (res.destroyed) { await response.body?.cancel(); return; }
+      const output: Record<string, string | string[]> = {};
+      response.headers.forEach((value, key) => { if (!STRIP.has(key) && key !== "set-cookie") output[key] = value; });
+      const cookies = response.headers.getSetCookie(); if (cookies.length) output["set-cookie"] = cookies;
+      res.writeHead(response.status, output);
+      if (!response.body || method === "HEAD") { await response.body?.cancel(); res.end(); return; }
+      const body = Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream<Uint8Array>);
+      body.once("error", () => res.destroy()); res.once("close", () => body.destroy()); body.pipe(res);
+    })().catch(() => {
+      if (res.headersSent) res.destroy(); else { res.writeHead(502, { "Content-Length": "0" }); res.end(); }
+    });
+  });
+  server.on("upgrade", (req, client, head) => {
+    if (!valid(req.headers.host, req.url)) { client.end("HTTP/1.1 421 Misdirected Request\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"); return; }
+    const peer = options.websocketPeer;
+    const abort = new AbortController(); requests.add(abort);
+    client.once("close", () => { requests.delete(abort); abort.abort(); });
+    client.once("error", () => abort.abort());
+    void dialDesktopUpstream({ ...options.websocketTransport, ...(peer ? { target: { host: peer.host, port: peer.port }, ca: peer.ca } : {}), signal: abort.signal }).then(upstream => {
+      requests.delete(abort);
+      if (client.destroyed || abort.signal.aborted) { upstream.destroy(); return; }
+      sockets.add(upstream);
+      upstream.once("error", () => client.destroy());
+      upstream.once("close", () => { sockets.delete(upstream); client.destroy(); });
+      client.once("close", () => upstream.destroy());
+      const lines = [`${req.method ?? "GET"} ${req.url} HTTP/1.1`];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        if (!/^proxy-(?:authorization|connection)$/i.test(req.rawHeaders[i]!)) lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
+      }
+      upstream.write(lines.join("\r\n") + "\r\n\r\n");
+      if (head.length) upstream.write(head);
+      client.pipe(upstream).pipe(client);
+    }).catch(() => {
+      requests.delete(abort);
+      if (!client.destroyed) client.end("HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
+    });
+  });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+  } catch (error) { server.close(); throw error; }
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("desktop_compatibility_listener_unavailable");
+  let closing: Promise<void> | null = null;
+  return { port: address.port, close() {
+    if (closing) return closing;
+    for (const abort of requests) abort.abort();
+    for (const socket of sockets) socket.destroy();
+    closing = new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+    server.closeAllConnections(); return closing;
+  } };
+}

package/src/codex/desktop-compatibility/routing-binding.ts

@@ -0,0 +1,10 @@
+import type { OcxConfig } from "../../types";
+
+export interface NativeCompatibilityOwner { hostname: string; port: number; loopbackPort?: number; config: OcxConfig }
+let owner: NativeCompatibilityOwner | null = null;
+/** Bound sockets, not persisted desired ports, identify this process's native routing target. */
+export function bindNativeCompatibilityOwner(value: NativeCompatibilityOwner): () => void {
+  owner = value;
+  return () => { if (owner === value) owner = null; };
+}
+export function nativeCompatibilityOwner(): NativeCompatibilityOwner | null { return owner; }

package/src/codex/desktop-compatibility/routing-preflight.ts

@@ -0,0 +1,69 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { OcxConfig } from "../../types";
+import { nativeCompatibilityOwner, type NativeCompatibilityOwner } from "./routing-binding";
+
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+// These are routing inputs, not proof of a conversation's final provider. Their
+// changes revoke the observed context even if the loopback URL stays the same.
+const ROUTING_KEYS = ["providers", "defaultProvider", "defaultModelAliases", "customModels", "combos", "routingProfiles",
+  "subagentModelFallback", "subagentModelFallbackByModel", "injectionModel", "compactionRouting", "compactionRecovery",
+  "blockedModelRedirects", "shadowCallIntercept", "protocols", "memoryModels", "codexMainAccountHardLockFallback"] as const satisfies readonly (keyof OcxConfig)[];
+function routingDigest(text: string, owner: NativeCompatibilityOwner): string {
+  const native = Bun.TOML.parse(text) as Record<string, unknown>;
+  // Desktop refreshes MCP endpoints after launch. Tool transport metadata and TOML
+  // formatting do not select the model transport. Keep all other (including unknown)
+  // native fields bound, rather than an allowlist that could miss a new routing key.
+  const { mcp_servers: _mcpServers, ...nativeContext } = native;
+  const projection = Object.fromEntries(ROUTING_KEYS.map(key => [key, owner.config[key]]));
+  const serialized = JSON.stringify([nativeContext, owner.hostname, owner.port, owner.loopbackPort, projection], (_key, value) =>
+    record(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, value[key]])) : value);
+  if (Buffer.byteLength(serialized) > 1048576) throw new Error("Routing snapshot too large");
+  return createHash("sha256").update(serialized).digest("hex");
+}
+/** Validates the effective root/profile routing only; it does not prove a thread's selected provider. */
+export function matchesNativeCompatibilityRouting(text: string, owner: NativeCompatibilityOwner | null): boolean {
+  if (!owner || owner.config.codexDesktopAuthless === true || owner.config.runtimeRole === "client") return false;
+  try {
+    const root: unknown = Bun.TOML.parse(text);
+    if (!record(root)) return false;
+    let effective = root;
+    if (root.profile !== undefined) {
+      if (typeof root.profile !== "string" || !record(root.profiles)) return false;
+      const profile = root.profiles[root.profile];
+      if (!record(profile)) return false;
+      effective = { ...root, ...profile };
+    }
+    if ((effective.model_provider ?? "openai") !== "openai" || effective.forced_login_method === "api") return false;
+    if (typeof effective.openai_base_url !== "string") return false;
+    const url = new URL(effective.openai_base_url);
+    if (url.protocol !== "http:" || !["127.0.0.1", "[::1]"].includes(url.hostname) || url.username || url.password
+      || url.search || url.hash || !["/v1", "/v1/"].includes(url.pathname) || !url.port) return false;
+    const port = Number(url.port), matchesPort = (value: number | undefined) => Number.isInteger(value) && Number(value) > 0 && value === port;
+    // The companion always binds IPv4. localhost can resolve to another address family.
+    if (matchesPort(owner.loopbackPort) && url.hostname === "127.0.0.1") return true;
+    if (!matchesPort(owner.port)) return false;
+    return url.hostname === "127.0.0.1" ? ["127.0.0.1", "0.0.0.0"].includes(owner.hostname)
+      : ["::1", "[::1]", "::", "[::]"].includes(owner.hostname);
+  } catch { return false; }
+}
+export function createNativeRoutingVerifier(codexHome: string, readOwner = nativeCompatibilityOwner) {
+  const path = join(codexHome, "config.toml");
+  let baseline: string | undefined, invalidated = false;
+  return () => {
+    if (invalidated) return false;
+    try {
+      // Process-level overrides could put the app on another transport despite its TOML.
+      if (["CODEX_API_BASE_URL", "CODEX_APP_SERVER_WS_URL", "CODEX_ELECTRON_USER_DATA_PATH", "ELECTRON_RUN_AS_NODE"].some(key => process.env[key]?.trim())) { invalidated = true; return false; }
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1048576) { invalidated = true; return false; }
+      const text = readFileSync(path, "utf8"), owner = readOwner();
+      if (!owner || !matchesNativeCompatibilityRouting(text, owner)) { invalidated = true; return false; }
+      const current = routingDigest(text, owner);
+      if (baseline !== undefined && current !== baseline) { invalidated = true; return false; }
+      baseline ??= current;
+      return true;
+    } catch { invalidated = true; return false; }
+  };
+}

package/src/codex/desktop-compatibility/runtime-ownership.ts

@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+
+interface LaunchContext { pacUrl: string; generation: string; current(): boolean }
+/** Process-local ownership; the management sibling guard owns the cross-instance boundary. */
+let owner: { token: symbol; kind: "runtime" | "certificate"; launch?: LaunchContext } | null = null;
+export function desktopCompatibilityRuntimeActive(): boolean { return owner?.kind === "runtime"; }
+function acquire(kind: "runtime" | "certificate"): () => void {
+  if (owner !== null) throw new Error("desktop_compatibility_busy");
+  const token = Symbol(); owner = { token, kind };
+  return () => { if (owner?.token === token) owner = null; };
+}
+export const acquireDesktopCompatibilityRuntime = () => acquire("runtime");
+export const acquireDesktopCertificateMutation = () => acquire("certificate");
+
+/** Published only by a successfully started runtime, never reconstructed from disk or app arguments. */
+export function bindDesktopCompatibilityLaunch(pacUrl: string, current: () => boolean): () => void {
+  if (owner?.kind !== "runtime" || owner.launch) throw new Error("desktop_compatibility_launch_owner_unverified");
+  const lease = owner, launch = { pacUrl, generation: randomUUID(), current };
+  lease.launch = launch;
+  return () => { if (lease.launch === launch) delete lease.launch; };
+}
+
+/** No key loading, socket discovery, or optional-runtime construction on the ordinary restart path. */
+export function readDesktopCompatibilityLaunch(): { pacUrl: string; generation: string } | null {
+  const launch = owner?.kind === "runtime" ? owner.launch : undefined;
+  try { return launch?.current() ? { pacUrl: launch.pacUrl, generation: launch.generation } : null; }
+  catch { return null; }
+}

package/src/codex/desktop-compatibility/runtime.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { getConfigDir } from "../../config/paths";
+import { issueServerLeaf } from "../../claude/intercept/local-ca";
+import { startConnectProxy, type ConnectProxyHandle } from "../../claude/intercept/connect-proxy";
+import { didRunOptionalShutdownHooks, registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
+import { isTestHomeGuardArmed } from "../../lib/test-home-guard";
+import { desktopOutboundFetch, desktopProxyFor } from "../../lib/desktop-proxy-route";
+import { inspectDesktopCompatibilityAuthority, loadDesktopCompatibilityAuthority, type StoredDesktopAuthority } from "./certificate-store";
+import { inspectWindowsCertificateTrust } from "./windows-certificate-trust";
+import { createNativeIdentityReader } from "./native-identity";
+import { UsageRelayController, type UsageIdentity } from "./usage-controller";
+import { createUsageControlledFetch } from "./usage-controlled-fetch";
+import { startDesktopRelay } from "./relay-listener";
+import { launchWindowsCodexCompatibility } from "./windows-package-launch";
+import { acquireDesktopCompatibilityRuntime, bindDesktopCompatibilityLaunch } from "./runtime-ownership";
+import { createDesktopConnectionStore, type DesktopConnectionStore } from "./connection-store";
+import { createNativeRoutingVerifier } from "./routing-preflight";
+import { createInstalledBuildProbe, type DesktopBuildAssessment } from "./installed-build";
+
+export { DESKTOP_COMPATIBILITY_ASSESSED_VERSION, isAssessedDesktopInstalled } from "./installed-build";
+export interface DesktopRuntimeIo {
+  platform?: string;
+  loadAuthority?: () => Promise<StoredDesktopAuthority>;
+  trust?: (authority: StoredDesktopAuthority) => Promise<"trusted" | "not-trusted" | "unknown">;
+  identity?: ReturnType<typeof createNativeIdentityReader>;
+  buildSupported?: () => boolean | Promise<boolean>;
+  /** Internal fixture probe factory; requires testOnly and all sandbox identity/CA seams. */
+  testOnlyBuildProbe?: () => ReturnType<typeof createInstalledBuildProbe>;
+  upstreamFetch?: typeof fetch;
+  connectionStore?: DesktopConnectionStore;
+  routingSupported?: () => boolean;
+  /** Synthetic-test execution is admitted only with explicit fixture identity and CA seams. */
+  testOnly?: boolean;
+}
+
+/** Optional runtime. Import/construction/status do not start listeners or touch credentials. */
+export function createDesktopCompatibilityRuntime(io: DesktopRuntimeIo = {}) {
+  const platform = io.platform ?? process.platform;
+  let buildProbe: ReturnType<typeof createInstalledBuildProbe> | undefined;
+  let previousBuildAssessment: DesktopBuildAssessment | null = null;
+  const buildSupported = io.buildSupported ?? (() => buildProbe?.check() ?? Promise.resolve(false));
+  let routingSupported = io.routingSupported ?? (() => false);
+  let contextFailure: "build_unverified" | "native_routing_unverified" | null = null;
+  const contextValid = async () => {
+    try {
+      if (!routingSupported()) { contextFailure = "native_routing_unverified"; return false; }
+      const supported = await buildSupported();
+      contextFailure = !routingSupported() ? "native_routing_unverified" : !supported ? "build_unverified" : null;
+    }
+    catch { contextFailure = "build_unverified"; }
+    return contextFailure === null;
+  };
+  let phase: "off" | "starting" | "running" | "stopping" | "cleanup-required" = "off";
+  let owned: { controller: UsageRelayController; close(): Promise<void>; pacUrl: string; fingerprint: string; deadline: number } | null = null;
+  let closing: Promise<void> | null = null;
+  let pendingCleanup: (() => Promise<void>) | null = null;
+  let releaseOwner: (() => void) | null = null;
+  const status = () => ({ phase, supported: platform === "win32", running: owned !== null, contextFailure,
+    ...(buildProbe ? { buildAssessment: buildProbe.lastResult() ?? (previousBuildAssessment ? { ...previousBuildAssessment } : null) } : {}),
+    ...(owned ? { fingerprint: owned.fingerprint, safetyDeadline: owned.deadline, usage: owned.controller.snapshot() } : {}) });
+  async function stop(): Promise<ReturnType<typeof status>> {
+    if (phase === "starting") throw new Error("desktop_compatibility_busy");
+    if (closing) { await closing; return status(); }
+    if (!pendingCleanup) return status();
+    phase = "stopping";
+    closing = pendingCleanup().then(() => { owned = null; pendingCleanup = null; phase = "off"; releaseOwner?.(); releaseOwner = null; })
+      .catch(error => { phase = "cleanup-required"; throw error; }).finally(() => { closing = null; });
+    await closing; return status();
+  }
+  async function start() {
+    if (phase !== "off") throw new Error("desktop_compatibility_busy");
+    if (platform !== "win32") throw new Error("desktop_compatibility_unsupported");
+    if (io.testOnlyBuildProbe && (!io.testOnly || io.buildSupported)) throw new Error("desktop_compatibility_test_environment");
+    if ((isTestHomeGuardArmed() || io.testOnlyBuildProbe) && !(io.testOnly && io.identity && io.loadAuthority && io.trust && (io.buildSupported || io.testOnlyBuildProbe) && io.connectionStore && io.routingSupported)) throw new Error("desktop_compatibility_test_environment");
+    if (didRunOptionalShutdownHooks()) throw new Error("desktop_compatibility_stopping");
+    try { desktopProxyFor(new URL("https://chatgpt.com")); } catch { throw new Error("desktop_compatibility_egress_proxy_invalid"); }
+    releaseOwner = acquireDesktopCompatibilityRuntime(); phase = "starting";
+    let relay: Awaited<ReturnType<typeof startDesktopRelay>> | undefined, proxy: ConnectProxyHandle | undefined;
+    let pac: ReturnType<typeof Bun.serve> | undefined, timer: ReturnType<typeof setInterval> | undefined;
+    let detach: (() => void) | undefined, unbindLaunch: (() => void) | undefined, controller: UsageRelayController | undefined;
+    const cleanup = async () => {
+      unbindLaunch?.();
+      if (timer) clearInterval(timer); detach?.();
+      // Abort transport before awaiting stream refresh so a stuck reader cannot retain sockets.
+      const results = await Promise.allSettled([pac?.stop(true), proxy?.close(), relay?.close(), controller?.observeOnly(), buildProbe?.close()]);
+      if (results.some(result => result.status === "rejected")) throw new Error("desktop_compatibility_cleanup_incomplete");
+    };
+    pendingCleanup = cleanup;
+    try {
+      if (!io.buildSupported) {
+        // A fresh probe owns this start; diagnostics retain the last completed observation.
+        previousBuildAssessment = buildProbe?.lastResult() ?? previousBuildAssessment;
+        buildProbe = io.testOnlyBuildProbe ? io.testOnlyBuildProbe() : createInstalledBuildProbe();
+      }
+      if (!io.routingSupported) routingSupported = createNativeRoutingVerifier((await import("../paths")).getCodexHome());
+      if (!await contextValid()) throw new Error(`desktop_compatibility_${contextFailure}`);
+      const directory = join(getConfigDir(), "codex-desktop-compatibility");
+      if (!io.loadAuthority) {
+        const saved = inspectDesktopCompatibilityAuthority(directory);
+        if (saved.status === "missing") throw new Error("desktop_compatibility_certificate_not_prepared");
+        if (saved.status === "invalid") throw new Error("desktop_compatibility_certificate_invalid");
+        if (saved.status === "expired") throw new Error("desktop_compatibility_certificate_expired");
+      }
+      const authority = await (io.loadAuthority?.() ?? loadDesktopCompatibilityAuthority({ directory }));
+      const trust = await (io.trust?.(authority) ?? inspectWindowsCertificateTrust(authority.authority.certPem, authority.fingerprint));
+      if (trust !== "trusted") throw new Error("desktop_compatibility_trust_required");
+      const connections = io.connectionStore ?? createDesktopConnectionStore(directory);
+      const previousConnection = connections.read();
+      const deadline = authority.expiresAt - 300_000;
+      if (deadline <= Date.now()) throw new Error("desktop_compatibility_certificate_expiring");
+      const identity = io.identity ?? createNativeIdentityReader(join((await import("../paths")).getCodexHome(), "auth.json"), desktopOutboundFetch as typeof fetch);
+      const account: UsageIdentity | null = await identity.verifyFreshIdentity();
+      if (!account) throw new Error("desktop_compatibility_native_identity_unverified");
+      if (didRunOptionalShutdownHooks()) throw new Error("desktop_compatibility_stopping");
+      controller = new UsageRelayController(account, identity.readCurrentIdentity, identity.verifyFreshIdentity, Date.now, deadline, 180000, contextValid);
+      relay = await startDesktopRelay({ leaf: issueServerLeaf(authority.authority, authority.commonName, ["chatgpt.com"]),
+        fetchImpl: createUsageControlledFetch(controller, io.upstreamFetch ?? desktopOutboundFetch as typeof fetch) });
+      try { proxy = await startConnectProxy(previousConnection?.connectPort ?? 0, { interceptPort: relay.port, interceptHosts: ["chatgpt.com"], allowedTargets: ["chatgpt.com:443"] }); }
+      catch { throw new Error("desktop_compatibility_connection_unavailable"); }
+      const runId = previousConnection?.id ?? randomUUID(), proxyPort = proxy.port;
+      try { pac = Bun.serve({ hostname: "127.0.0.1", port: previousConnection?.pacPort ?? 0, fetch(req) {
+        const url = new URL(req.url);
+        if (req.method !== "GET" || req.headers.has("origin") || url.origin !== `http://127.0.0.1:${pac!.port}` || url.pathname !== `/${runId}/proxy.pac`) return new Response(null, { status: 404 });
+        return new Response(`function FindProxyForURL(url, host) { return Date.now() < ${deadline} && host.toLowerCase() === "chatgpt.com" && url.indexOf("https:") === 0 ? "PROXY 127.0.0.1:${proxyPort}; DIRECT" : "DIRECT"; }`,
+          { headers: { "content-type": "application/x-ns-proxy-autoconfig", "cache-control": "no-store" } });
+      } }); } catch { throw new Error("desktop_compatibility_connection_unavailable"); }
+      const connection = await connections.publish({ version: 1, id: runId, connectPort: proxyPort, pacPort: pac.port! });
+      if (connection.id !== runId || connection.connectPort !== proxyPort || connection.pacPort !== pac.port) throw new Error("desktop_compatibility_connection_changed");
+      if (didRunOptionalShutdownHooks()) throw new Error("desktop_compatibility_stopping");
+      const active = controller; let ticking = false, deadlineHandled = false, lastContextCheck = Date.now();
+      timer = setInterval(() => {
+        if (ticking) return; ticking = true;
+        const expired = Date.now() >= deadline;
+        const work = (async () => {
+          const contextCadence = active.snapshot().mode === "apply" ? 10000 : 60000;
+          if (!expired && Date.now() - lastContextCheck >= contextCadence) {
+            lastContextCheck = Date.now();
+            if (!await contextValid() && active.snapshot().mode === "apply") { await active.observeOnly(); return; }
+          }
+          await (expired && !deadlineHandled ? (deadlineHandled = true, active.observeOnly()) : active.expireIfNeeded());
+        })();
+        void work.catch(() => {}).finally(() => { ticking = false; });
+      }, 1000); timer.unref();
+      owned = { controller, close: cleanup, fingerprint: authority.fingerprint, deadline, pacUrl: `http://127.0.0.1:${pac.port}/${runId}/proxy.pac` };
+      phase = "running";
+      const launchedBy = owned;
+      unbindLaunch = bindDesktopCompatibilityLaunch(owned.pacUrl,
+        () => owned === launchedBy && phase === "running" && Date.now() < deadline);
+      detach = registerOptionalShutdownHook("codex-desktop-compatibility", () => { void stop().catch(() => {}); });
+      return status();
+    } catch (error) {
+      try { await cleanup(); pendingCleanup = null; phase = "off"; releaseOwner?.(); releaseOwner = null; }
+      catch { phase = "cleanup-required"; throw new Error("desktop_compatibility_cleanup_incomplete"); }
+      throw error;
+    }
+  }
+  async function apply(accountWideConsent: boolean) {
+    const current = owned;
+    if (!current || phase !== "running") throw new Error("desktop_compatibility_not_running");
+    const generation = current.controller.snapshot().generation, valid = await contextValid();
+    if (owned !== current || phase !== "running") throw new Error("desktop_compatibility_not_running");
+    if (generation !== current.controller.snapshot().generation) return { accepted: false, reason: "superseded", ...current.controller.snapshot() };
+    if (!valid) { await current.controller.observeOnly(); throw new Error(`desktop_compatibility_${contextFailure}`); }
+    const result = await current.controller.activate({ scope: "account-ui-compatibility", accountWideConsent });
+    if (owned !== current || phase !== "running") { await current.controller.observeOnly(); return { ...result, accepted: false, reason: "runtime-stopped" }; }
+    return result;
+  }
+  return { status, start, stop, apply,
+    async observe() { if (owned) await owned.controller.observeOnly(); return status(); },
+    async launch() {
+      if (!owned || phase !== "running") throw new Error("desktop_compatibility_not_running");
+      const current = owned;
+      if (!await contextValid()) throw new Error(`desktop_compatibility_${contextFailure}`);
+      if (owned !== current || phase !== "running") throw new Error("desktop_compatibility_not_running");
+      return launchWindowsCodexCompatibility(current.pacUrl);
+    },
+    /** Internal native launch context; management status never returns the control endpoint. */
+    getPacUrl: () => owned?.pacUrl ?? null,
+  };
+}
+export type DesktopCompatibilityRuntime = ReturnType<typeof createDesktopCompatibilityRuntime>;

package/src/codex/desktop-compatibility/service.ts

@@ -0,0 +1,30 @@
+import { createDesktopCompatibilityRuntime, type DesktopCompatibilityRuntime } from "./runtime";
+
+/** One runtime for management and automatic startup; shutdown never constructs a new instance. */
+export function createDesktopCompatibilityService(factory: () => DesktopCompatibilityRuntime = createDesktopCompatibilityRuntime) {
+  let runtime: DesktopCompatibilityRuntime | undefined;
+  let starting: Promise<ReturnType<DesktopCompatibilityRuntime["status"]>> | null = null;
+  let shuttingDown = false;
+  return {
+    get(): DesktopCompatibilityRuntime {
+      if (!runtime) {
+        const raw = factory();
+        runtime = { ...raw, start() {
+          if (shuttingDown) return Promise.reject(new Error("desktop_compatibility_stopping"));
+          if (starting) return Promise.reject(new Error("desktop_compatibility_busy"));
+          starting = raw.start().finally(() => { starting = null; });
+          return starting;
+        } };
+      }
+      return runtime;
+    },
+    async shutdown(): Promise<void> {
+      shuttingDown = true;
+      try { await starting; } catch { /* failed start owns its cleanup */ }
+      if (runtime) await runtime.stop();
+    },
+  };
+}
+const service = createDesktopCompatibilityService();
+export const getDesktopCompatibilityRuntime = () => service.get();
+export const shutdownDesktopCompatibility = () => service.shutdown();

package/src/codex/desktop-compatibility/startup-settings.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { readConfigFileSnapshot } from "../../config/diagnostics";
+import { mutatePersistedConfig } from "../../config/persisted-mutation";
+import { desktopCompatibilityConfigError } from "../../config/schema/desktop-compatibility";
+import { adoptPersistedDesktopCompatibility } from "../../config/live-reconcile";
+import type { OcxConfig } from "../../types";
+
+export interface DesktopStartupSettings { startOnProxyStart: boolean; revision: string }
+interface SettingsIo { read?: typeof readConfigFileSnapshot; mutate?: typeof mutatePersistedConfig; liveConfig?: OcxConfig }
+const failure = (code: string) => new Error(`desktop_compatibility_settings_${code}`);
+/** A next-process preference: never changes live runtime, trust, app or login state. */
+export function createDesktopStartupSettings(io: SettingsIo = {}) {
+  const read = io.read ?? readConfigFileSnapshot, mutate = io.mutate ?? mutatePersistedConfig;
+  function inspect() {
+    const snapshot = read();
+    if (snapshot.diagnostics.source !== "file" || snapshot.raw === undefined) throw failure("unavailable");
+    let raw: Record<string, unknown>;
+    try { raw = JSON.parse(snapshot.raw.replace(/^\uFEFF/, "")); } catch { throw failure("unavailable"); }
+    if (desktopCompatibilityConfigError(raw)) throw failure("invalid");
+    const setting = raw.desktopCompatibility as { startOnProxyStart: boolean } | undefined;
+    return { setting, status: { startOnProxyStart: setting?.startOnProxyStart === true,
+      revision: createHash("sha256").update(JSON.stringify(setting ?? null)).digest("hex") } };
+  }
+  const status = (): DesktopStartupSettings => inspect().status;
+  function set(startOnProxyStart: boolean, expectedRevision: string): DesktopStartupSettings {
+    if (typeof startOnProxyStart !== "boolean" || !/^[a-f0-9]{64}$/.test(expectedRevision)) throw failure("invalid_request");
+    let outcome;
+    try { outcome = mutate(config => {
+      // Runs under the existing config lock, including each rebase retry. Unrelated fields
+      // may change, but a changed preference must be shown again before this write.
+      const current = status();
+      if (current.revision !== expectedRevision) throw failure("changed");
+      if (current.startOnProxyStart === startOnProxyStart) return { changed: false, value: startOnProxyStart };
+      config.desktopCompatibility = { startOnProxyStart };
+      return { changed: true, value: startOnProxyStart };
+    }); } catch (error) {
+      // Publication can succeed before bookkeeping fails. Reconcile a verified disk
+      // field without claiming success or replaying the uncertain write.
+      if (io.liveConfig) { try { adoptPersistedDesktopCompatibility(io.liveConfig, inspect().setting); } catch { /* unresolved state remains an error */ } }
+      throw error;
+    }
+    if (outcome.status === "unavailable") throw failure("unavailable");
+    const actual = inspect();
+    if (io.liveConfig) adoptPersistedDesktopCompatibility(io.liveConfig, actual.setting);
+    if (actual.status.startOnProxyStart !== startOnProxyStart) throw failure("changed");
+    return actual.status;
+  }
+  return { status, set };
+}
+export type DesktopStartupSettingsService = ReturnType<typeof createDesktopStartupSettings>;