@bitkyc08/opencodex 2.84.0 → 2.86.0

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

package/src/codex/desktop-compatibility/usage-controlled-fetch.ts

@@ -0,0 +1,59 @@
+import { UsageRelayController } from './usage-controller';
+import { controlledUsageSse } from './usage-sse-controller';
+import { boundedJsonBody } from './json-body';
+
+/** Inject as the listener's fetchImpl. Existing auth forwarding/TLS/WS code stays unchanged. */
+export function createUsageControlledFetch(controller: UsageRelayController, upstreamFetch: typeof fetch = fetch): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const upstream = await upstreamFetch(input, init);
+    const pathname = new URL(input instanceof Request ? input.url : String(input)).pathname;
+    const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+    const exchange = { pathname, method, status: upstream.status };
+    if (method !== 'GET' || upstream.status !== 200 || !upstream.body
+      || !['/backend-api/wham/usage', '/backend-api/wham/usage/stream'].includes(pathname)) return upstream;
+    const contentType = upstream.headers.get('content-type') ?? '';
+    const headers = new Headers(upstream.headers);
+    const output = (body: BodyInit, transformed = false) => {
+      headers.delete('content-length'); headers.delete('content-encoding');
+      if (transformed) {
+        for (const name of ['etag', 'last-modified', 'digest', 'content-md5']) headers.delete(name);
+        headers.set('cache-control', 'no-store');
+      }
+      return new Response(body, { status: upstream.status, statusText: upstream.statusText, headers });
+    };
+    if (contentType.includes('application/json') || contentType.endsWith('+json')) {
+      const body = await boundedJsonBody(upstream.body);
+      if ('stream' in body) return output(body.stream);
+      let text: string;
+      try { text = new TextDecoder('utf-8', { fatal: true }).decode(body.bytes); }
+      catch { return output(new Uint8Array(body.bytes)); }
+      const changed = await controller.rewriteJson(text, exchange);
+      return output(changed ?? new Uint8Array(body.bytes), changed !== null);
+    }
+    if (!contentType.includes('text/event-stream') || pathname !== '/backend-api/wham/usage/stream') return upstream;
+    let registration: ReturnType<UsageRelayController['registerStream']> = null;
+    const reader = upstream.body.pipeThrough(controlledUsageSse(text => controller.rewriteJson(text, exchange, registration))).getReader();
+    let ended = false, sink: ReadableStreamDefaultController<Uint8Array>;
+    const close = async () => {
+      if (ended) return;
+      ended = true; registration?.release();
+      const cancelled = reader.cancel();
+      try { sink.close(); } catch { /* caller already cancelled */ }
+      await cancelled;
+    };
+    const body = new ReadableStream<Uint8Array>({
+      start(value) { sink = value; },
+      async pull(value) {
+        try {
+          const next = await reader.read();
+          if (ended) return;
+          if (next.done) { ended = true; registration?.release(); value.close(); }
+          else value.enqueue(next.value);
+        } catch (error) { if (!ended) { ended = true; registration?.release(); value.error(error); } }
+      },
+      cancel: close,
+    });
+    registration = controller.registerStream(exchange, close);
+    return output(body, true);
+  }) as typeof fetch;
+}

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

@@ -0,0 +1,107 @@
+import { UsageActivation, type ApplyScope } from './usage-activation';
+import { UsageRefreshRegistry } from './usage-refresh';
+import { evaluateUsageRewrite, type UsageRewriteContext } from './usage-policy';
+
+export type UsageIdentity = NonNullable<UsageRewriteContext['account']> & { credentialGeneration?: string };
+type Registration = NonNullable<ReturnType<UsageRefreshRegistry['register']>>;
+type Exchange = { method: string; pathname: string; status: number };
+const same = (a: UsageIdentity | null, b: UsageIdentity) => a !== null
+  && a.id === b.id && a.userId === b.userId && a.plan === b.plan && a.structure === b.structure
+  && a.credentialGeneration === b.credentialGeneration;
+const object = (value: unknown): value is Record<string, unknown> => value !== null
+  && typeof value === 'object' && !Array.isArray(value);
+
+/** Response-level controller. Construction never starts a listener, timer or trust operation. */
+export class UsageRelayController {
+  private readonly account: UsageIdentity;
+  private readonly key: string;
+  private readonly refresh = new UsageRefreshRegistry();
+  private readonly activation: UsageActivation;
+  private jsonSnapshots = 0;
+  private streamSnapshots = 0;
+  private lastSnapshotAt: number | null = null;
+  constructor(account: UsageIdentity, private readonly readCurrentIdentity: () => Promise<UsageIdentity | null>,
+    verifyFreshIdentity: () => Promise<UsageIdentity | null>, private readonly clock: () => number,
+    private readonly expiresAt: number, timeoutMs = 180000, private readonly contextValid: () => boolean | Promise<boolean> = () => true) {
+    if (!account.id || !account.userId || !['plus', 'pro'].includes(account.plan)
+      || account.structure !== 'personal' || !Number.isFinite(expiresAt) || expiresAt <= clock()) {
+      throw new Error('A verified supported identity and finite safety deadline are required');
+    }
+    this.account = { ...account };
+    this.key = JSON.stringify([account.id, account.userId, account.plan, account.credentialGeneration ?? null]);
+    this.activation = new UsageActivation(this.key, key => this.refresh.refresh(key), async () => {
+      return same(await verifyFreshIdentity(), this.account) ? this.key : null;
+    }, clock, timeoutMs);
+  }
+  snapshot() { return { ...this.activation.snapshot(), trackedStreams: this.refresh.size, expired: this.clock() >= this.expiresAt,
+    observation: { jsonSnapshots: this.jsonSnapshots, streamSnapshots: this.streamSnapshots,
+      validatedActiveStreams: this.refresh.boundSize, lastSnapshotAt: this.lastSnapshotAt,
+      sourceProcessVerified: false as const, composerRecoveryVerified: false as const } }; }
+  private async checkContext() { try { return await this.contextValid(); } catch { return false; } }
+  async activate(options: { scope: ApplyScope; accountWideConsent: boolean }) {
+    const generation = this.activation.snapshot().generation, valid = await this.checkContext();
+    if (generation !== this.activation.snapshot().generation) return { accepted: false, reason: 'superseded', ...this.snapshot() };
+    if (!valid) { this.activation.invalidateIdentity(); return { accepted: false, reason: 'native-context-changed', ...this.snapshot() }; }
+    if (this.clock() >= this.expiresAt) { this.activation.invalidateIdentity(); return { accepted: false, reason: 'safety-deadline', ...this.snapshot() }; }
+    return this.activation.activate(options);
+  }
+  observeOnly() { return this.activation.observeOnly(); }
+  expireIfNeeded() { return this.activation.expireIfNeeded(); }
+  registerStream(exchange: Exchange, close: () => Promise<void>): Registration | null {
+    if (exchange.status !== 200) return null;
+    return this.refresh.register(exchange.method, exchange.pathname, close);
+  }
+  /** Only a complete original usage record may establish the stream's account binding. */
+  async rewriteJson(text: string, exchange: Exchange, stream?: Registration | null): Promise<string | null> {
+    if (exchange.method !== 'GET' || exchange.status !== 200
+      || !['/backend-api/wham/usage', '/backend-api/wham/usage/stream'].includes(exchange.pathname)) return null;
+    if (this.clock() >= this.expiresAt) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    const observedGeneration = this.activation.snapshot().generation;
+    let current: UsageIdentity | null;
+    try { current = await this.readCurrentIdentity(); } catch { current = null; }
+    if (!same(current, this.account)) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    // Do not apply an activation that raced this response's identity read.
+    if (observedGeneration !== this.activation.snapshot().generation) return null;
+    if (this.clock() >= this.expiresAt) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    if (Buffer.byteLength(text, 'utf8') > 262144) { stream?.exclude(); return null; }
+    let parsed: unknown;
+    try { parsed = JSON.parse(text); } catch { stream?.exclude(); return null; }
+    const envelope = object(parsed) && 'usage' in parsed ? parsed : null;
+    if ((exchange.pathname.endsWith('/stream') && !envelope)
+      || (envelope && (envelope.version !== 1 || typeof envelope.stream_id !== 'string' || !envelope.stream_id
+        || !Number.isSafeInteger(envelope.sequence) || Number(envelope.sequence) <= 0))) { stream?.exclude(); return null; }
+    const original = envelope ? envelope.usage : parsed;
+    if (!object(original) || original.account_id !== this.account.id || original.user_id !== this.account.userId
+      || original.plan_type !== this.account.plan) { stream?.exclude(); return null; }
+    const rate = original.rate_limit;
+    if (!object(rate) || typeof rate.allowed !== 'boolean' || typeof rate.limit_reached !== 'boolean') {
+      stream?.exclude(); return null;
+    }
+    if (stream && !stream.bind(this.key)) return null;
+    // Identity-checked responses received by this relay do not establish the
+    // sending process or prove that an authoritative UI cache consumed them.
+    if (exchange.pathname.endsWith('/stream')) this.streamSnapshots = Math.min(Number.MAX_SAFE_INTEGER, this.streamSnapshots + 1);
+    else this.jsonSnapshots = Math.min(Number.MAX_SAFE_INTEGER, this.jsonSnapshots + 1);
+    this.lastSnapshotAt = this.clock();
+    const context: UsageRewriteContext = { enabled: true, mode: 'observe', status: exchange.status,
+      pathname: exchange.pathname, account: this.account };
+    const observed = evaluateUsageRewrite(original, context);
+    this.activation.observe(this.key, observed.eligible ? 'exhausted'
+      : rate.allowed === true && rate.limit_reached === false ? 'available' : 'protected');
+    const state = this.activation.snapshot();
+    if (state.mode !== 'apply') return null;
+    const result = evaluateUsageRewrite(original, { ...context, mode: 'apply' });
+    if (!result.changed) return null;
+    // Observe and unchanged responses never spawn an installed-package probe.
+    const valid = await this.checkContext();
+    if (state.generation !== this.activation.snapshot().generation) return null;
+    if (!valid) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    // A native account or trial can change while the asynchronous build check runs.
+    try { current = await this.readCurrentIdentity(); } catch { current = null; }
+    if (state.generation !== this.activation.snapshot().generation) return null;
+    if (!same(current, this.account)) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    if (this.clock() >= this.expiresAt) { this.activation.invalidateIdentity(); stream?.exclude(); return null; }
+    if (!this.activation.recordOutput(this.key, state.generation)) return null;
+    return JSON.stringify(envelope ? { ...envelope, usage: result.value } : result.value);
+  }
+}

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

@@ -0,0 +1,59 @@
+/** Pure response policy. Real quota windows, credits and spending restrictions stay unchanged. */
+export interface UsageRewriteContext {
+  enabled: boolean;
+  mode: 'observe' | 'apply';
+  status: number;
+  pathname: string;
+  account: {
+    id: string;
+    userId: string;
+    plan: 'plus' | 'pro';
+    structure: 'personal';
+  } | null;
+}
+
+type RecordValue = Record<string, unknown>;
+function record(value: unknown): value is RecordValue {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Transform only a complete, matched personal-account usage snapshot.
+ * Account context must come from a trusted live integration; this module does not
+ * discover it or prove provider isolation. Never persist the adjusted snapshot as
+ * actual provider/account capacity. Unknown or protected states pass unchanged.
+ */
+export function evaluateUsageRewrite(value: unknown, context: UsageRewriteContext) {
+  const unchanged = (reason: string) => ({ value, changed: false, eligible: false, reason });
+  if (!context.enabled) return unchanged('off');
+  if (context.status !== 200) return unchanged('non-success-response');
+  if (!['/backend-api/wham/usage', '/backend-api/wham/usage/stream'].includes(context.pathname)) return unchanged('unowned-path');
+  const account = context.account;
+  if (!account || !account.id || !account.userId || account.structure !== 'personal' || !['plus', 'pro'].includes(account.plan)) return unchanged('unsupported-account');
+  if (!record(value) || value.account_id !== account.id || value.user_id !== account.userId || value.plan_type !== account.plan) return unchanged('identity-mismatch');
+  const rate = value.rate_limit;
+  if (!record(rate) || rate.allowed !== false || rate.limit_reached !== true) return unchanged('not-explicitly-exhausted');
+  const spend = value.spend_control;
+  // Absence is unknown, not evidence that no protected spending restriction exists.
+  if (!record(spend) || spend.reached !== false) return unchanged('protected-or-unknown-spend');
+  const reason = value.rate_limit_reached_type;
+  if (reason != null && (!record(reason) || reason.type !== 'rate_limit_reached')) return unchanged('protected-or-unknown-reason');
+  const credits = value.credits;
+  if (!record(credits) || typeof credits.has_credits !== 'boolean' || typeof credits.unlimited !== 'boolean') return unchanged('unknown-credit-schema');
+  if (credits.overage_limit_reached != null && credits.overage_limit_reached !== false) return unchanged('overage-restriction');
+  // These entitlements already keep the native gate open. Rewriting the ordinary
+  // rate limit would unnecessarily change the app's Reserve activation predicate.
+  if (credits.has_credits || credits.unlimited) return unchanged('credits-available');
+  const upsell = value.rate_limit_upsell, additional = value.additional_rate_limits;
+  if (upsell != null && !record(upsell)) return unchanged('unknown-reserve-schema');
+  if (additional != null && (!Array.isArray(additional) || additional.some(limit => !record(limit)
+    || limit.limit_name === 'gpt-reserve' && (!record(limit.rate_limit) || typeof limit.rate_limit.allowed !== 'boolean')))) return unchanged('unknown-reserve-schema');
+  if (record(upsell) && upsell.banner_type === 'luna_reserve' && Array.isArray(additional)
+    && additional.some(limit => record(limit) && limit.limit_name === 'gpt-reserve'
+      && record(limit.rate_limit) && limit.rate_limit.allowed === true)) return unchanged('reserve-active');
+  if (context.mode !== 'apply') return { value, changed: false, eligible: true, reason: 'observe-only' };
+  return {
+    value: { ...value, rate_limit: { ...rate, allowed: true, limit_reached: false } },
+    changed: true, eligible: true, reason: 'personal-usage-only',
+  };
+}

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

@@ -0,0 +1,33 @@
+/** Exact usage-stream refresh registry. No timers, sockets or core-path imports. */
+export class UsageRefreshRegistry {
+  private entries = new Set<{ binding: string | null; tainted: boolean; close: () => Promise<void> }>();
+  register(method: string, pathname: string, close: () => Promise<void>) {
+    if (method !== 'GET' || pathname !== '/backend-api/wham/usage/stream') return null;
+    const entry = { binding: null as string | null, tainted: false, close };
+    this.entries.add(entry);
+    return {
+      // Caller must invoke only after validating a complete upstream snapshot's identity.
+      // A connection that changes account identity never becomes a refresh target again.
+      bind: (verifiedBinding: string) => {
+        if (!verifiedBinding || entry.tainted || !this.entries.has(entry)) return false;
+        if (entry.binding !== null && entry.binding !== verifiedBinding) {
+          entry.tainted = true; entry.binding = null; return false;
+        }
+        entry.binding = verifiedBinding; return true;
+      },
+      exclude: () => { entry.tainted = true; entry.binding = null; },
+      release: () => { this.entries.delete(entry); },
+    };
+  }
+  async refresh(binding: string) {
+    if (!binding) throw new Error('Verified account binding is required');
+    const selected = [...this.entries].filter(e => !e.tainted && e.binding === binding);
+    // Detach before awaiting; concurrent refreshes cannot close the same stream twice.
+    for (const entry of selected) this.entries.delete(entry);
+    const results = await Promise.allSettled(selected.map(entry => Promise.resolve().then(entry.close)));
+    return { requested: selected.length, closed: results.filter(r => r.status === 'fulfilled').length,
+      failed: results.filter(r => r.status === 'rejected').length };
+  }
+  get size() { return this.entries.size; }
+  get boundSize() { return [...this.entries].filter(entry => !entry.tainted && entry.binding !== null).length; }
+}