@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/storage/storage-mutation-coordinator.ts

@@ -7,6 +7,7 @@
  */
 import { resolve } from "node:path";
 import { resolveCodexHomeDir } from "../codex/home";
+import { createAdmissionGate, type AdmissionLease, type AdmissionMetrics } from "../lib/admission";
 
 export type StorageMutationKind = "cleanup" | "restore" | "policy";
 
@@ -20,9 +21,13 @@ export interface StorageMutationCoordinatorTestHooks {
 interface ActiveSlot {
   kind: StorageMutationKind;
   startedAt: number;
+  lease: AdmissionLease;
 }
 
+export const MAX_ACTIVE_STORAGE_HOME_SLOTS = 32;
 const slots = new Map<string, ActiveSlot>();
+const slotGate = createAdmissionGate("storage_home_slots", MAX_ACTIVE_STORAGE_HOME_SLOTS);
+let releaseMisses = 0;
 let testHooks: StorageMutationCoordinatorTestHooks | null = null;
 
 function slotKey(codexHome?: string): string {
@@ -37,9 +42,15 @@ export function setStorageMutationCoordinatorTestHooks(
 
 export function resetStorageMutationCoordinatorForTests(): void {
   testHooks = null;
+  for (const slot of slots.values()) slot.lease.release();
   slots.clear();
 }
 
+export function storageMutationAdmissionMetrics(): AdmissionMetrics {
+  const metrics = slotGate.metrics();
+  return { ...metrics, releaseMisses: metrics.releaseMisses + releaseMisses };
+}
+
 export function getActiveStorageMutation(
   codexHome?: string,
 ): { kind: StorageMutationKind; startedAt: number } | null {
@@ -50,17 +61,36 @@ export function getActiveStorageMutation(
 export function tryBeginStorageMutation(
   kind: StorageMutationKind,
   codexHome?: string,
-): { acquired: true } | { acquired: false; error: StorageMutationBusyError } {
+): { acquired: true; lease: AdmissionLease } | { acquired: false; error: StorageMutationBusyError } {
   const key = slotKey(codexHome);
   if (slots.has(key)) {
     return { acquired: false, error: "storage_mutation_busy" };
   }
-  slots.set(key, { kind, startedAt: Date.now() });
-  return { acquired: true };
+  const lease = slotGate.tryAcquire();
+  if (!lease) return { acquired: false, error: "storage_mutation_busy" };
+  let active = true;
+  const ownerLease: AdmissionLease = {
+    release() {
+      if (!active) return;
+      active = false;
+      const owner = slots.get(key);
+      if (owner?.lease === ownerLease) slots.delete(key);
+      lease.release();
+    },
+  };
+  slots.set(key, { kind, startedAt: Date.now(), lease: ownerLease });
+  return { acquired: true, lease: ownerLease };
 }
 
 export function endStorageMutation(codexHome?: string): void {
-  slots.delete(slotKey(codexHome));
+  const key = slotKey(codexHome);
+  const slot = slots.get(key);
+  if (!slot) {
+    releaseMisses += 1;
+    return;
+  }
+  slots.delete(key);
+  slot.lease.release();
 }
 
 async function applyCoordinatorBlock(): Promise<void> {
@@ -87,7 +117,7 @@ export async function runPolicyStorageMutation<T>(
     await applyCoordinatorBlock();
     return await work();
   } finally {
-    endStorageMutation(codexHome);
+    gate.lease.release();
   }
 }
 
@@ -104,6 +134,6 @@ export async function withStorageMutationSlot<T>(
     await applyCoordinatorBlock();
     return await work();
   } finally {
-    endStorageMutation(codexHome);
+    gate.lease.release();
   }
 }

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";
@@ -150,8 +150,16 @@ function quoteRunValue(value: string): string {
   return `\"${value}\"`;
 }
 
-/** Command persisted under HKCU Run. Every value is an owned absolute package/home path. */
-export function buildWindowsTrayRunCommand(entry: WindowsTrayEntry, powershell = windowsPowerShellPath()): string {
+function installedTrayLauncherPath(): string {
+  return join(getConfigDir(), "opencodex-tray.vbs");
+}
+
+function quoteVbsPath(value: string): string {
+  return value.replace(/"/g, '""');
+}
+
+/** Full PowerShell invocation used by the owned VBS launcher (not written to HKCU Run). */
+export function buildWindowsTrayPowerShellCommand(entry: WindowsTrayEntry, powershell = windowsPowerShellPath()): string {
   return [
     quoteRunValue(powershell),
     "-NoLogo",
@@ -169,6 +177,27 @@ export function buildWindowsTrayRunCommand(entry: WindowsTrayEntry, powershell =
   ].join(" ");
 }
 
+/** Short HKCU Run command (must stay ≤260 chars under long Windows user/npm paths). */
+export function buildWindowsTrayRunCommand(entry: WindowsTrayEntry & { launcherPath: string }): string {
+  const wscript = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "wscript.exe");
+  return `${quoteRunValue(wscript)} //B //NoLogo ${quoteRunValue(entry.launcherPath)}`;
+}
+
+export function buildWindowsTrayLauncherScript(entry: WindowsTrayEntry, powershell = windowsPowerShellPath()): string {
+  const command = buildWindowsTrayPowerShellCommand(entry, powershell);
+  // VBS CreateObject("WScript.Shell").Run command, 0, False — hidden, non-blocking.
+  return [
+    "' OpenCodex owned tray launcher — do not edit by hand.",
+    `CreateObject("WScript.Shell").Run "${quoteVbsPath(command)}", 0, False`,
+    "",
+  ].join("\r\n");
+}
+
+/** @deprecated Prefer buildWindowsTrayPowerShellCommand; kept for callers that still expect the long form. */
+export function buildWindowsTrayLegacyRunCommand(entry: WindowsTrayEntry, powershell = windowsPowerShellPath()): string {
+  return buildWindowsTrayPowerShellCommand(entry, powershell);
+}
+
 function readState(): WindowsTrayState | null {
   try {
     const state = JSON.parse(readFileSync(trayStatePath(), "utf8")) as Partial<WindowsTrayState>;
@@ -189,24 +218,55 @@ 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);
+      }
+    }
   }
 }
 
-function writeState(entry: WindowsTrayEntry, runValue: string, runCommand: string): void {
+function writeState(
+  entry: WindowsTrayEntry & { launcherPath: string },
+  runValue: string,
+  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 {
@@ -376,7 +436,8 @@ function trayStatusFrom(registered: string | null): WindowsTrayStatus {
   const running = heartbeatProcessAlive(heartbeat);
   const registrationOwned = state !== null
     && registered === state.runCommand
-    && [state.bun, state.cli, state.script, ...installedTrayIconPaths()].every(path => existsSync(path));
+    && [state.bun, state.cli, state.script, ...(state.launcherPath ? [state.launcherPath] : []), ...installedTrayIconPaths()]
+      .every(path => existsSync(path));
   const stale = windowsTrayRegistrationIsStale({
     registered: registered !== null,
     registrationOwned,
@@ -507,7 +568,12 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   }
   recordOwnedConfigPath(getConfigDir(), trayStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
-  const runCommand = buildWindowsTrayRunCommand(entry);
+  const launcherPath = installedTrayLauncherPath();
+  const entryWithLauncher = { ...entry, launcherPath };
+  const runCommand = buildWindowsTrayRunCommand(entryWithLauncher);
+  if (runCommand.length > 260) {
+    throw new Error(`Tray Run command exceeds the Windows 260-character limit (${runCommand.length} chars).`);
+  }
   const runValue = windowsTrayRunValue(entry.opencodexHome);
   const existing = readOwnedRunValue(runValue);
   const state = readState();
@@ -517,6 +583,9 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   if (existsSync(entry.script) && (!state || resolve(state.script) !== resolve(entry.script))) {
     throw new Error(`Refusing to overwrite an unowned tray script at ${entry.script}.`);
   }
+  if (existsSync(launcherPath) && (!state?.launcherPath || resolve(state.launcherPath) !== resolve(launcherPath))) {
+    throw new Error(`Refusing to overwrite an unowned tray launcher at ${launcherPath}.`);
+  }
   if (!state && iconPairs.some(pair => existsSync(pair.installed))) {
     throw new Error("Refusing to overwrite unowned Windows tray icon assets.");
   }
@@ -531,23 +600,28 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
 
   const previousStateBytes = existsSync(trayStatePath()) ? readFileSync(trayStatePath()) : null;
   const previousScriptBytes = existsSync(entry.script) ? readFileSync(entry.script) : null;
+  const previousLauncherBytes = existsSync(launcherPath) ? readFileSync(launcherPath) : null;
   const previousIconBytes = new Map(iconPairs.map(pair => [
     pair.installed,
     existsSync(pair.installed) ? readFileSync(pair.installed) : null,
   ]));
   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) 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 {
@@ -565,10 +639,11 @@ 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));
+    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(entry, runValue, runCommand);
+    writeState(entryWithLauncher, runValue, runCommand);
   } catch (error) {
     restorePreviousInstall();
     throw error;
@@ -578,9 +653,6 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
     restorePreviousInstall();
     throw new Error("The tray startup registration was installed, but the tray process did not become healthy.");
   }
-  if (state?.launcherPath && existsSync(state.launcherPath)) {
-    try { unlinkSync(state.launcherPath); } catch { /* old owned VBS is inert after a committed Run replacement */ }
-  }
   return getWindowsTrayStatus();
 }
 

package/src/types.ts

@@ -455,6 +455,11 @@ export interface OcxClaudeCodeConfig {
   desktopProfile?: OcxClaudeDesktopProfile;
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
   desktopAutoApply?: boolean;
+  /**
+   * When false, omit `native/*` rows from Claude Desktop show/export/apply. Default: enabled.
+   * Routing-sidecar alias decoding is unchanged — only the Desktop model list writer.
+   */
+  desktopNativeModels?: boolean;
 }
 
 export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
@@ -511,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). */
@@ -574,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";
@@ -670,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. */
@@ -684,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. */
@@ -885,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
@@ -903,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.