@bitkyc08/opencodex 2.83.0 → 2.86.0

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"] 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,173 @@
+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 } 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>;
+  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;
+  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,
+    ...(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 (isTestHomeGuardArmed() && !(io.testOnly && io.identity && io.loadAuthority && io.trust && io.buildSupported && 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";
+    if (!io.buildSupported) buildProbe = createInstalledBuildProbe();
+    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.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>;

package/src/codex/desktop-compatibility/usage-activation.ts

@@ -0,0 +1,86 @@
+/** Account-bound, time-limited compatibility activation; no persistent settings or timers. */
+export type Observation = 'exhausted' | 'available' | 'protected';
+export type ApplyScope = 'selected-external-model' | 'account-ui-compatibility';
+type RefreshResult = {requested:number;closed:number;failed:number};
+export class UsageActivation {
+  private mode: 'observe' | 'apply' = 'observe';
+  private phase = 'observing';
+  private generation = 0;
+  private latest: { kind:Observation; at:number } | null = null;
+  private startedAt: number | null = null;
+  private outputs = 0;
+  constructor(private binding:string, private refresh:(binding:string)=>Promise<RefreshResult>,
+    private verifyIdentity:()=>Promise<string|null>,
+    private clock:()=>number=Date.now, private timeoutMs=180000) {
+    if(!binding || !Number.isSafeInteger(timeoutMs) || timeoutMs<1 || timeoutMs>180000) throw new Error('Invalid activation limits');
+  }
+  snapshot() { return {mode:this.mode,phase:this.phase,generation:this.generation,outputs:this.outputs,
+    appCacheConfirmed:false,requestedUiScope:'account-wide',providerIsolationAvailable:false}; }
+  invalidateIdentity() {
+    this.mode='observe';this.phase='identity-invalidated';this.startedAt=null;this.latest=null;this.outputs=0;++this.generation;
+  }
+  observe(binding:string,kind:Observation) {
+    if(binding!==this.binding)return false;
+    this.latest={kind,at:this.clock()};
+    // A recovered or protected account must not silently re-enter a previous trial
+    // if a later snapshot becomes exhausted again. A new trial requires consent.
+    if(this.mode==='apply'&&kind!=='exhausted'){
+      this.mode='observe';this.phase=kind==='available'?'usage-recovered':'protected-observation';
+      this.startedAt=null;this.outputs=0;++this.generation;
+    }
+    return true;
+  }
+  private async reset(phase:string) {
+    this.mode='observe';this.phase=phase;this.startedAt=null;this.latest=null;this.outputs=0;++this.generation;
+    return this.refresh(this.binding);
+  }
+  async activate(options:{scope:ApplyScope;accountWideConsent:boolean}) {
+    if(options.scope!=='account-ui-compatibility')return{accepted:false,reason:'selected-model-scope-unavailable',...this.snapshot()};
+    if(!options.accountWideConsent)return{accepted:false,reason:'account-wide-scope-not-accepted',...this.snapshot()};
+    const beforeVerification=this.generation,binding=this.binding;
+    let verified:string|null;
+    try{verified=await this.verifyIdentity();}catch{verified=null;}
+    if(verified!==binding||this.binding!==binding||this.generation!==beforeVerification)return{accepted:false,reason:'identity-not-verified',...this.snapshot()};
+    if(this.mode==='apply')return{accepted:false,reason:'activation-already-pending',...this.snapshot()};
+    const age=this.latest?this.clock()-this.latest.at:Infinity;
+    if(!this.latest||this.latest.kind!=='exhausted'||age<0||age>300000)return{accepted:false,reason:'no-fresh-eligible-exhaustion',...this.snapshot()};
+    // An exhausted observation authorizes one trial, not every retry within its TTL.
+    this.latest=null;
+    this.mode='apply';this.phase='awaiting-fresh-usage';this.startedAt=this.clock();this.outputs=0;
+    const generation=++this.generation;
+    let refreshed:RefreshResult;
+    try { refreshed=await this.refresh(this.binding); }
+    catch {
+      if(this.generation===generation){this.mode='observe';this.phase='refresh-failed';this.startedAt=null;this.latest=null;this.outputs=0;++this.generation;}
+      return{accepted:false,reason:'refresh-failed',...this.snapshot()};
+    }
+    // Account/mode changes while a close callback awaited invalidate this activation.
+    if(this.generation!==generation)return{accepted:false,reason:'superseded',...this.snapshot()};
+    // The registry settles every close and reports failures; it does not reject the batch.
+    // Partial closure cannot leave rewriting enabled while an old app cache may survive.
+    if(!Number.isSafeInteger(refreshed.requested)||!Number.isSafeInteger(refreshed.closed)
+      ||!Number.isSafeInteger(refreshed.failed)||refreshed.requested<0||refreshed.closed<0
+      ||refreshed.failed!==0||refreshed.closed!==refreshed.requested){
+      this.mode='observe';this.phase='refresh-failed';this.startedAt=null;this.latest=null;this.outputs=0;++this.generation;
+      return{accepted:false,reason:'refresh-failed',refresh:refreshed,...this.snapshot()};
+    }
+    return{accepted:true,reason:'awaiting-new-response',refresh:refreshed,...this.snapshot()};
+  }
+  recordOutput(binding:string,generation:number) {
+    if(binding!==this.binding||generation!==this.generation||this.mode!=='apply')return false;
+    if(this.startedAt===null||this.clock()-this.startedAt<0||this.clock()-this.startedAt>=this.timeoutMs)return false;
+    ++this.outputs;this.phase='response-produced-app-confirmation-needed';return true;
+  }
+  async expireIfNeeded() {
+    if(this.startedAt===null||this.clock()-this.startedAt<this.timeoutMs&&this.clock()-this.startedAt>=0)return false;
+    await this.reset('expired-awaiting-original-response');return true;
+  }
+  async observeOnly() { return this.reset('observing-awaiting-original-response'); }
+  async changeBinding(binding:string) {
+    if(!binding)throw new Error('Verified account binding is required');
+    const previous=this.binding;
+    this.mode='observe';this.phase='account-changed';this.startedAt=null;this.latest=null;this.outputs=0;++this.generation;
+    this.binding=binding;
+    return this.refresh(previous);
+  }
+}