@bitkyc08/opencodex 2.8.2-preview.20260731 → 2.9.0

package/src/storage/worker-lifecycle.ts

@@ -2,77 +2,211 @@
  * Deterministic teardown for the storage Bun Workers.
  *
  * `Worker.terminate()` returns void and does NOT wait for the thread to be
- * reclaimed. Every caller here used to fire it and move on, which is fine for
- * the proxy but not for `bun test --isolate`: the harness tears a test file's
- * realm down at the file boundary, and on Windows a worker that has not
- * finished exiting by then trips a Bun-internal assertion and kills the whole
- * run.
+ * reclaimed. Callers that fire-and-forget leave a window where
+ * `bun test --isolate` reclaims the file realm while a Windows worker thread
+ * is still exiting — Bun then panics with
+ * `workers_spawned(N) workers_terminated(N-1)` / Internal assertion failure.
  *
- * The crash header names the shape exactly — `workers_spawned(9)
- * workers_terminated(8)`, one worker still alive — and it lands right at the
- * `api-storage-policy` → `api-storage` file boundary, the only suite that
- * spawns policy workers. See `devlog/_plan/260730_remote_issue_merge_round/150`,
- * which reproduced the panic twice against an unchanged tree and left this
- * defence as the follow-up if it ever recurred. It recurred.
- *
- * So: keep a registry of live workers, and give shutdown/reset paths something
- * they can actually await. `close` is Bun's post-exit event for a worker
- * thread, so awaiting it is the real "the thread is gone" signal rather than a
- * timer we hope is long enough. The timeout only exists so a wedged worker
- * cannot hang a test teardown forever.
+ * Invariant: every registered worker has a `close` listener attached at spawn
+ * time (so we cannot miss `self.close()` / early exit), stays in `liveWorkers`
+ * until that close settles, and `drainStorageWorkers()` joins every in-flight
+ * terminate. Spawns are serialized through `withStorageWorkerSpawnGate` so the
+ * next Worker cannot be created until prior threads have exited. On Windows and
+ * macOS, a post-close settle covers the OS join gap Bun does not expose
+ * (Windows unbalanced join panic; macOS Silicon balanced-count segfault under
+ * `bun test --isolate`).
+ */
+
+import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
+
+type TrackedWorker = {
+  worker: Worker;
+  closed: Promise<void>;
+  resolveClosed: () => void;
+  terminatePromise?: Promise<void>;
+  reservation?: AdmissionReservation<Worker>;
+};
+
+export const MAX_RESERVED_STORAGE_WORKER_SPAWNS = 16;
+export class StorageWorkerAdmissionBusyError extends Error {
+  readonly code = "storage_mutation_busy";
+
+  constructor() {
+    super("storage worker spawn queue is busy");
+    this.name = "StorageWorkerAdmissionBusyError";
+  }
+}
+
+const liveWorkers = new Map<Worker, TrackedWorker>();
+const workerGate = createAdmissionGate("storage_worker_reservations", MAX_RESERVED_STORAGE_WORKER_SPAWNS);
+
+/** Serialize spawns so a new Worker never overlaps a still-exiting predecessor. */
+let spawnGate: Promise<void> = Promise.resolve();
+
+/**
+ * Bumped by teardown so a spawn still queued on `spawnGate` (not yet in
+ * `liveWorkers`) cannot create a Worker after reset/shutdown reported idle.
+ */
+let spawnCancelEpoch = 0;
+
+/**
+ * OS-join gap after the `close` event on platforms where Bun's Worker reclaim
+ * races the isolate/file boundary (not a CI job-timeout bump).
+ * Windows GHA at 250ms and 750ms still left `workers_spawned(N)
+ * workers_terminated(N-1)` panics under isolate (seen mid
+ * `storage-mutation-race` with 11/10). 1500ms covers deferred reclaim under
+ * stacked policy/restore workers. Darwin uses 250ms.
  */
+const WORKER_OS_JOIN_MS = process.platform === "win32" ? 1_500 : 250;
 
-const liveWorkers = new Set<Worker>();
+function needsWorkerOsJoinSettle(): boolean {
+  return process.platform === "win32" || process.platform === "darwin";
+}
+
+/** Invalidate spawn callbacks still waiting on the gate (reset / server drain). */
+export function cancelQueuedStorageWorkerSpawns(): void {
+  spawnCancelEpoch += 1;
+}
 
 /** Track a freshly spawned worker so teardown can wait for it later. */
 export function registerStorageWorker(worker: Worker): void {
-  liveWorkers.add(worker);
+  if (liveWorkers.has(worker)) return;
+
+  let resolveClosed!: () => void;
+  const closed = new Promise<void>(resolve => {
+    resolveClosed = resolve;
+  });
+
+  const tracked: TrackedWorker = { worker, closed, resolveClosed };
+  liveWorkers.set(worker, tracked);
+
+  try {
+    worker.addEventListener("close", () => {
+      resolveClosed();
+    }, { once: true });
+  } catch {
+    // No close event — terminate path will still resolve via timeout/settle.
+  }
+}
+
+export function tryReserveStorageWorker(): AdmissionReservation<Worker> | null {
+  const gateLease = workerGate.tryAcquire();
+  if (!gateLease) return null;
+  let active = true;
+  let bound: Worker | undefined;
+  const reservation: AdmissionReservation<Worker> = {
+    bind(worker) {
+      if (!active) return;
+      bound = worker;
+      registerStorageWorker(worker);
+      const tracked = liveWorkers.get(worker);
+      if (tracked) tracked.reservation = reservation;
+    },
+    release() {
+      if (!active) return;
+      active = false;
+      if (bound) {
+        const tracked = liveWorkers.get(bound);
+        if (tracked?.reservation === reservation) tracked.reservation = undefined;
+      }
+      bound = undefined;
+      gateLease.release();
+    },
+  };
+  return reservation;
+}
+
+export function storageWorkerAdmissionMetrics(): AdmissionMetrics {
+  return workerGate.metrics();
+}
+
+/**
+ * Run `fn` only after every previously gated spawn has finished tearing down.
+ * Used around `new Worker(...)` so tests cannot overlap Windows thread exit.
+ */
+export function withStorageWorkerSpawnGate<T>(fn: () => Promise<T>): Promise<T> {
+  const epochAtEnqueue = spawnCancelEpoch;
+  const run = spawnGate.then(async () => {
+    if (epochAtEnqueue !== spawnCancelEpoch) {
+      throw new Error("storage_worker_spawn_cancelled");
+    }
+    await drainStorageWorkers();
+    if (epochAtEnqueue !== spawnCancelEpoch) {
+      throw new Error("storage_worker_spawn_cancelled");
+    }
+    return fn();
+  });
+  spawnGate = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+export function queuedStorageWorkerSpawnCount(): number {
+  return Math.max(0, workerGate.metrics().active - liveWorkers.size);
 }
 
 /**
  * Terminate a worker and resolve once its thread has actually exited.
  *
- * Safe to call twice: the second call finds the worker already deregistered and
- * resolves immediately.
+ * Safe to call twice: the second call joins the in-flight terminate promise.
  */
 export function terminateStorageWorker(worker: Worker, timeoutMs = 5_000): Promise<void> {
-  if (!liveWorkers.has(worker)) {
+  const tracked = liveWorkers.get(worker);
+  if (!tracked) {
     try { worker.terminate(); } catch { /* already gone */ }
     return Promise.resolve();
   }
-  liveWorkers.delete(worker);
+  if (tracked.terminatePromise) return tracked.terminatePromise;
+
+  tracked.terminatePromise = (async () => {
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      tracked.resolveClosed();
+    }, timeoutMs);
 
-  return new Promise<void>(resolve => {
-    let done = false;
-    const settle = (): void => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      resolve();
-    };
-    // A worker that refuses to exit must not wedge teardown; the proxy path
-    // never awaits this, and a test teardown would rather continue than hang.
-    const timer = setTimeout(settle, timeoutMs);
-    try {
-      worker.addEventListener("close", settle, { once: true });
-    } catch {
-      // No close event available — fall back to the timeout above.
-    }
     try {
-      worker.terminate();
-    } catch {
-      settle();
+      try {
+        worker.terminate();
+      } catch {
+        tracked.resolveClosed();
+      }
+      await tracked.closed;
+      // Disarm before the OS-join settle: a late timer firing during the sleep
+      // would set timedOut after close already won and throw a false timeout.
+      clearTimeout(timer);
+      // Always run the OS-join settle before throwing on timeout: the timer
+      // only forces `closed`, it does not prove the OS thread has exited.
+      // Callers that catch and continue (e.g. drainAndShutdown) still need
+      // that gap before the next isolate reclaim or server.stop.
+      if (needsWorkerOsJoinSettle()) {
+        await Bun.sleep(0);
+        await Bun.sleep(WORKER_OS_JOIN_MS);
+      }
+      if (timedOut) {
+        throw new Error(`storage worker did not exit within ${timeoutMs}ms`);
+      }
+    } finally {
+      clearTimeout(timer);
+      liveWorkers.delete(worker);
+      tracked.reservation?.release();
+      tracked.reservation = undefined;
     }
-  });
+  })();
+
+  return tracked.terminatePromise;
 }
 
 /**
- * Await every worker this module still tracks. Used by test resets so no
- * storage worker outlives the file that spawned it.
+ * Await every worker this module still tracks (including terminations already
+ * in flight). Used by test resets so no storage worker outlives the file that
+ * spawned it.
  */
 export async function drainStorageWorkers(timeoutMs = 5_000): Promise<void> {
-  const pending = [...liveWorkers];
-  await Promise.all(pending.map(worker => terminateStorageWorker(worker, timeoutMs)));
+  const pending = [...liveWorkers.keys()].map(worker => terminateStorageWorker(worker, timeoutMs));
+  await Promise.all(pending);
 }
 
 /** Live worker count — exported so a regression test can assert the invariant. */

package/src/tray/windows.ts

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
 import { durableBunPath } from "../lib/bun-runtime";
-import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
@@ -218,18 +218,45 @@ function readState(): WindowsTrayState | null {
   }
 }
 
-function replaceOwnedFile(path: string, contents: string | Buffer): void {
+export interface WindowsTrayOwnedFileIO {
+  write(path: string, contents: string | Buffer): void;
+  harden(path: string): void;
+  rename(source: string, destination: string): void;
+  unlink(path: string): void;
+}
+
+export function replaceWindowsTrayOwnedFile(
+  path: string,
+  contents: string | Buffer,
+  io: WindowsTrayOwnedFileIO = {
+    write: (target, value) => writeFileSync(target, value, { mode: 0o600 }),
+    harden: target => {
+      try { chmodSync(target, 0o600); } catch { /* best-effort */ }
+      if (process.platform !== "win32") return;
+      const hardened = hardenSecretPath(target, { required: true });
+      if (!hardened.ok) throw new Error("Windows tray ACL hardening did not complete; refusing to persist executable state.");
+    },
+    rename: renameSync,
+    unlink: unlinkSync,
+  },
+): void {
   const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(temporary, contents, { mode: 0o600 });
+  io.write(temporary, contents);
+  let renamed = false;
   try {
-    try { chmodSync(temporary, 0o600); } catch { /* best-effort */ }
-    if (process.platform === "win32") {
-      const hardened = hardenSecretPath(temporary, { required: true });
-      if (!hardened.ok) throw new Error("Windows tray ACL hardening did not complete; refusing to persist executable state.");
-    }
-    renameSync(temporary, path);
+    io.harden(temporary);
+    io.rename(temporary, path);
+    renamed = true;
+    forgetHardenedSecretPath(temporary);
   } finally {
-    try { if (existsSync(temporary)) unlinkSync(temporary); } catch { /* best-effort */ }
+    if (!renamed) {
+      try {
+        io.unlink(temporary);
+        forgetHardenedSecretPath(temporary);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") forgetHardenedSecretPath(temporary);
+      }
+    }
   }
 }
 
@@ -239,7 +266,7 @@ function writeState(
   runCommand: string,
 ): void {
   const path = trayStatePath();
-  replaceOwnedFile(path, JSON.stringify({ version: TRAY_STATE_VERSION, ...entry, runValue, runCommand }, null, 2) + "\n");
+  replaceWindowsTrayOwnedFile(path, JSON.stringify({ version: TRAY_STATE_VERSION, ...entry, runValue, runCommand }, null, 2) + "\n");
 }
 
 export function parseWindowsTrayRunValue(output: string, runValue: string): string | null {
@@ -580,21 +607,21 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   ]));
   const restorePreviousInstall = () => {
     try {
-      if (previousScriptBytes) replaceOwnedFile(entry.script, previousScriptBytes);
+      if (previousScriptBytes) replaceWindowsTrayOwnedFile(entry.script, previousScriptBytes);
       else if (existsSync(entry.script)) unlinkSync(entry.script);
     } catch { /* rollback best-effort */ }
     try {
-      if (previousLauncherBytes) replaceOwnedFile(launcherPath, previousLauncherBytes);
+      if (previousLauncherBytes) replaceWindowsTrayOwnedFile(launcherPath, previousLauncherBytes);
       else if (existsSync(launcherPath)) unlinkSync(launcherPath);
     } catch { /* rollback best-effort */ }
     for (const [path, contents] of previousIconBytes) {
       try {
-        if (contents) replaceOwnedFile(path, contents);
+        if (contents) replaceWindowsTrayOwnedFile(path, contents);
         else if (existsSync(path)) unlinkSync(path);
       } catch { /* rollback best-effort */ }
     }
     try {
-      if (previousStateBytes) replaceOwnedFile(trayStatePath(), previousStateBytes);
+      if (previousStateBytes) replaceWindowsTrayOwnedFile(trayStatePath(), previousStateBytes);
       else if (existsSync(trayStatePath())) unlinkSync(trayStatePath());
     } catch { /* rollback best-effort */ }
     try {
@@ -612,9 +639,9 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   try {
     const hardenedDir = hardenSecretDir(getConfigDir(), { required: true });
     if (!hardenedDir.ok) throw new Error("Windows tray directory ACL hardening did not complete; refusing to install persistence.");
-    replaceOwnedFile(entry.script, readFileSync(sourceScript));
-    for (const pair of iconPairs) replaceOwnedFile(pair.installed, readFileSync(pair.source));
-    replaceOwnedFile(launcherPath, Buffer.from("\uFEFF" + buildWindowsTrayLauncherScript(entry), "utf16le"));
+    replaceWindowsTrayOwnedFile(entry.script, readFileSync(sourceScript));
+    for (const pair of iconPairs) replaceWindowsTrayOwnedFile(pair.installed, readFileSync(pair.source));
+    replaceWindowsTrayOwnedFile(launcherPath, Buffer.from("\uFEFF" + buildWindowsTrayLauncherScript(entry), "utf16le"));
     runRegistry(["add", RUN_KEY, "/v", runValue, "/t", "REG_SZ", "/d", runCommand, "/f", "/reg:64"]);
     writeState(entryWithLauncher, runValue, runCommand);
   } catch (error) {

package/src/types.ts

@@ -516,8 +516,22 @@ export interface OcxCustomModel {
   addedAt?: string;
 }
 
+/**
+ * A generated `ocx_` data-plane key. `key` is the secret itself and never leaves
+ * the server except in the one-time POST /api/keys response; every other surface
+ * sees only the masked prefix.
+ */
+export interface OcxApiKeyEntry {
+  id: string;
+  name: string;
+  key: string;
+  createdAt: string;
+}
+
 export interface OcxConfig {
   port: number;
+  /** Maximum usage-log bytes read for one management snapshot. */
+  managementUsageMaxReadBytes?: number;
   providers: Record<string, OcxProviderConfig>;
   defaultProvider: string;
   /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
@@ -579,11 +593,12 @@ export interface OcxConfig {
    */
   fastMode?: boolean;
   /**
-   * Windows SSE passthrough stream shape (#314 mitigation).
-   * "auto" (default): eager bounded relay only on runtimes proven to carry the
-   * Bun#32111 fix (none today → legacy tee). "eager-relay": force the new relay
-   * (accepts #32111 crash risk on Bun 1.3.14). "legacy-tee": pin the tee path.
-   * Persisted in config.json because Windows services do not inherit shell env.
+   * Windows/macOS SSE passthrough stream shape (#314 mitigation).
+   * On Windows, "auto" (default) selects eager relay only on a runtime proven
+   * to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
+   * eager relay is explicit-only. "eager-relay" opts into the new relay (and
+   * accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
+   * Persisted in config.json so service users can select the stream shape.
    * See src/lib/bun-stream-caps.ts.
    */
   streamMode?: "auto" | "legacy-tee" | "eager-relay";
@@ -675,7 +690,7 @@ export interface OcxConfig {
    */
   storageCleanupPolicy?: StorageCleanupPolicy;
   /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
-  apiKeys?: Array<{ id: string; name: string; key: string; createdAt: string }>;
+  apiKeys?: OcxApiKeyEntry[];
   /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
   codexAutoStart?: boolean;
   /** Restore an installed shim after a stable external Codex update replaces it. Default true. */
@@ -689,6 +704,8 @@ export interface OcxConfig {
   syncResumeHistory?: boolean;
   /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
   modelCacheTtlMs?: number;
+  /** Evictable retained app-state budget in MiB. Default 256; valid 64..4096. */
+  appOwnedMemoryBudgetMb?: number;
   /** Anthropic prompt-cache retention: "short" = 5-min ephemeral (default), "long" = 1-hour extended, "none" = disabled. */
   cacheRetention?: "none" | "short" | "long";
   /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
@@ -890,6 +907,10 @@ export interface ResponsesItemIdRepairConfig {
 
 export interface OcxProviderConfig {
   adapter: string;
+  /** Cursor MCP compatibility bounds; positive integers when configured. */
+  mcpMaxTools?: number;
+  mcpMaxSchemaBytes?: number;
+  mcpMaxResultBytes?: number;
   /**
    * Per-model wire override, keyed by the upstream native model id (after namespace
    * and combo resolution). A single gateway can front models that speak different
@@ -908,6 +929,13 @@ export interface OcxProviderConfig {
    * the legacy `/v1/responses` construction.
    */
   responsesPath?: string;
+  /**
+   * Responses upstream that stores nothing server-side (DeepSeek documents "the API
+   * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
+   * and orphaned tool results left by a replay miss are repaired rather than
+   * forwarded to an upstream that cannot resolve their pair.
+   */
+  statelessResponses?: boolean;
   /**
    * Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
    * link-local, or unique-local upstreams. Metadata endpoints remain blocked.

package/src/update/index.ts

@@ -321,16 +321,35 @@ export async function runUpdate(): Promise<void> {
           windowsHide: true,
         });
         if (svcStdio === "pipe") logSpawnOutput("", svc);
-        if (svc.status !== 0) {
+        const serviceRefreshed = svc.status === 0;
+        let serviceViable = serviceRefreshed;
+        if (serviceRefreshed) {
+          try {
+            const { isServiceViable } = await import("../service");
+            serviceViable = isServiceViable();
+          } catch {
+            serviceViable = false;
+          }
+        }
+        if (!serviceRefreshed || !serviceViable) {
           // On Windows, schtasks /create requires elevation. The CLI inherits the
           // user's (non-admin) token, so the service reinstall can fail with access
-          // denied. Fall back to a direct detached proxy start so the update never
-          // leaves the user without a running proxy — but only when the port is free.
+          // denied — or exit 0 while leaving stale/missing assets that never start
+          // the proxy. Fall back to a direct detached proxy start so the update
+          // never leaves the user without a running proxy — but only when the port is free.
           if (!freed) {
-            console.warn("⚠️  Service refresh failed and the captured port is still busy; not starting on another port.");
+            console.warn(
+              serviceRefreshed
+                ? "⚠️  Service refresh left a non-viable manager and the captured port is still busy; not starting on another port."
+                : "⚠️  Service refresh failed and the captured port is still busy; not starting on another port.",
+            );
             console.warn(`   Run 'ocx service install' as administrator, then 'ocx start --port ${capturedListen.port}'.`);
           } else {
-            console.warn("⚠️  Service refresh failed — starting the proxy directly instead.");
+            console.warn(
+              serviceRefreshed
+                ? "⚠️  Service refresh left a non-viable manager (stale or missing assets) — starting the proxy directly instead."
+                : "⚠️  Service refresh failed — starting the proxy directly instead.",
+            );
             console.warn("   Run 'ocx service install' as administrator to refresh the background service.");
             const env = { ...process.env };
             delete env.OCX_SERVICE;