@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/storage/restore-job.ts

@@ -0,0 +1,253 @@
+/**
+ * Single-flight controller for trash restore runs.
+ *
+ * Heavy work (file moves, SQLite reconcile) runs in a Bun Worker so the proxy
+ * event loop stays responsive while the management API awaits the outcome.
+ *
+ * Restore shares the CODEX_HOME storage-mutation coordinator with manual cleanup
+ * and (Phase 3) policy-driven cleanup. Concurrent callers receive
+ * `storage_mutation_busy` (409) instead of queueing.
+ */
+import { resolveCodexHomeDir } from "../codex/home";
+import { restoreTrashEntry, type RestoreResult, type RestoreTestHooks } from "./cleanup";
+import {
+  resetStorageMutationCoordinatorForTests,
+  setStorageMutationCoordinatorTestHooks,
+  withStorageMutationSlot,
+  type StorageMutationCoordinatorTestHooks,
+} from "./storage-mutation-coordinator";
+import {
+  drainStorageWorkers,
+  registerStorageWorker,
+  terminateStorageWorker,
+} from "./worker-lifecycle";
+
+export interface RestoreJobTestHooks extends StorageMutationCoordinatorTestHooks {
+  /**
+   * When true, run on the main thread via dynamic import + optional sleep.
+   * Responsiveness tests must leave this unset so work stays in a Worker.
+   */
+  runInProcess?: boolean;
+  /** Expose GET /api/storage/trash/restore/test-stream for responsiveness tests. */
+  enableTestStream?: boolean;
+  /** Forwarded to restoreTrashEntry _test hooks. */
+  restoreTest?: RestoreTestHooks;
+}
+
+const WORKER_TIMEOUT_MS = 10 * 60 * 1000;
+
+const WORKER_REJECTION_CODES: Record<string, RestoreResult["error"]> = {
+  restore_worker_timeout: "restore_worker_timeout",
+  aborted: "restore_worker_aborted",
+  worker_failed: "restore_worker_failed",
+};
+
+/** Map a rejected worker promise to a precise restore outcome (exported for tests). */
+export function restoreResultFromWorkerRejection(err: unknown, trashId: string): RestoreResult {
+  const raw = err instanceof Error ? err.message : String(err);
+  const error = WORKER_REJECTION_CODES[raw] ?? "restore_worker_failed";
+  const detail =
+    error === "restore_worker_failed" && raw !== "worker_failed" && raw.trim().length > 0
+      ? raw
+      : undefined;
+  console.error(
+    `[storage] trash restore worker failed (${error}) trashId=${trashId}${detail ? `: ${detail}` : ""}`,
+  );
+  return {
+    ok: false,
+    count: 0,
+    bytes: 0,
+    restoredPaths: [],
+    error,
+    ...(detail ? { message: detail } : {}),
+  };
+}
+
+let activeWorker: Worker | null = null;
+let testHooks: RestoreJobTestHooks | null = null;
+let cancelActiveRun: (() => void) | null = null;
+
+export function setRestoreTrashJobTestHooks(hooks: RestoreJobTestHooks | null): void {
+  testHooks = hooks;
+  setStorageMutationCoordinatorTestHooks(hooks);
+}
+
+export function resetRestoreTrashJobForTests(): void {
+  if (activeWorker) {
+    void terminateStorageWorker(activeWorker);
+    activeWorker = null;
+  }
+  cancelActiveRun?.();
+  cancelActiveRun = null;
+  testHooks = null;
+  resetStorageMutationCoordinatorForTests();
+}
+
+/** Await-able reset for test teardown; see policy-job's equivalent for why. */
+export async function resetRestoreTrashJobForTestsAsync(): Promise<void> {
+  resetRestoreTrashJobForTests();
+  await drainStorageWorkers();
+}
+
+/** Terminate an in-flight worker during process shutdown. */
+export function abortRestoreTrashJob(): void {
+  if (activeWorker) {
+    void terminateStorageWorker(activeWorker);
+    activeWorker = null;
+  }
+  cancelActiveRun?.();
+  cancelActiveRun = null;
+}
+
+/** Test-only SSE/text stream served from the proxy while a worker is blocked. */
+export function getRestoreTrashTestStreamResponse(): Response | null {
+  if (!testHooks?.enableTestStream) return null;
+  const encoder = new TextEncoder();
+  return new Response(
+    new ReadableStream({
+      async start(controller) {
+        for (let i = 0; i < 8; i++) {
+          controller.enqueue(encoder.encode(`chunk-${i}\n`));
+          await Bun.sleep(50);
+        }
+        controller.close();
+      },
+    }),
+    { headers: { "content-type": "text/plain; charset=utf-8" } },
+  );
+}
+
+function runInWorker(opts: {
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  blockMs?: number;
+  restoreTest?: RestoreTestHooks;
+}): Promise<RestoreResult> {
+  return new Promise((resolve, reject) => {
+    const requestId = crypto.randomUUID();
+    let settled = false;
+    const worker = new Worker(new URL("./restore-worker.ts", import.meta.url).href);
+    registerStorageWorker(worker);
+    activeWorker = worker;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cancelActiveRun = null;
+      void terminateStorageWorker(worker);
+      if (activeWorker === worker) activeWorker = null;
+      reject(new Error("restore_worker_timeout"));
+    }, WORKER_TIMEOUT_MS);
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      cancelActiveRun = null;
+      clearTimeout(timer);
+      if (activeWorker === worker) activeWorker = null;
+      void terminateStorageWorker(worker).then(fn, fn);
+    };
+
+    cancelActiveRun = () => {
+      finish(() => reject(new Error("aborted")));
+    };
+
+    worker.onmessage = (event: MessageEvent<unknown>) => {
+      const data = event.data;
+      if (!data || typeof data !== "object") return;
+      const msg = data as Record<string, unknown>;
+      if (msg.requestId !== requestId) return;
+      if (msg.type === "done" && msg.result && typeof msg.result === "object") {
+        finish(() => resolve(msg.result as RestoreResult));
+        return;
+      }
+      if (msg.type === "error") {
+        const message = typeof msg.message === "string" ? msg.message : "worker_failed";
+        finish(() => reject(new Error(message)));
+      }
+    };
+
+    worker.onerror = (err: ErrorEvent) => {
+      finish(() => reject(err.error instanceof Error ? err.error : new Error(err.message || "worker_failed")));
+    };
+
+    worker.postMessage({
+      type: "run",
+      requestId,
+      trashId: opts.trashId,
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(opts.blockMs !== undefined ? { blockMs: opts.blockMs } : {}),
+      ...(opts.restoreTest ? { restoreTest: opts.restoreTest } : {}),
+      env: {
+        ...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
+        ...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),
+      },
+    });
+  });
+}
+
+async function executeRestore(opts: {
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  _test?: RestoreTestHooks;
+}): Promise<RestoreResult> {
+  const blockMs = testHooks?.blockMs;
+  const restoreTest = opts._test ?? testHooks?.restoreTest;
+
+  if (testHooks?.runInProcess) {
+    if (typeof blockMs === "number" && blockMs > 0) await Bun.sleep(blockMs);
+    return restoreTrashEntry(opts.trashId, {
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(restoreTest ? { _test: restoreTest } : {}),
+    });
+  }
+
+  try {
+    return await runInWorker({
+      trashId: opts.trashId,
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(typeof blockMs === "number" && blockMs > 0 ? { blockMs } : {}),
+      ...(restoreTest ? { restoreTest } : {}),
+    });
+  } catch (err) {
+    return restoreResultFromWorkerRejection(err, opts.trashId);
+  }
+}
+
+function busyRestoreResult(): RestoreResult {
+  return {
+    ok: false,
+    count: 0,
+    bytes: 0,
+    restoredPaths: [],
+    error: "storage_mutation_busy",
+  };
+}
+
+/**
+ * Run trash restore off the event loop under the shared storage-mutation gate.
+ * Returns `storage_mutation_busy` when cleanup or another restore is in flight.
+ */
+export async function runRestoreTrashEntryJob(
+  trashId: string,
+  options?: {
+    codexHome?: string;
+    busyTimeoutMs?: number;
+    _test?: RestoreTestHooks;
+  },
+): Promise<RestoreResult> {
+  const codexHome = options?.codexHome ?? resolveCodexHomeDir();
+  const result = await withStorageMutationSlot("restore", codexHome, () =>
+    executeRestore({ trashId, ...options }),
+  );
+  if (result && typeof result === "object" && "ok" in result && result.ok === false
+    && "error" in result && result.error === "storage_mutation_busy") {
+    return busyRestoreResult();
+  }
+  return result as RestoreResult;
+}

package/src/storage/restore-worker.ts

@@ -0,0 +1,52 @@
+/**
+ * Worker-thread entry for trash restore runs.
+ * Keeps file moves and SQLite reconcile off the proxy event loop.
+ */
+import { restoreTrashEntry, type RestoreResult, type RestoreTestHooks } from "./cleanup";
+
+interface RunMessage {
+  type: "run";
+  requestId: string;
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  /** Test-only: block before restore so responsiveness tests can probe /healthz. */
+  blockMs?: number;
+  restoreTest?: RestoreTestHooks;
+  /** Env snapshot — Workers may not see parent mutations on all platforms. */
+  env?: { CODEX_HOME?: string; OPENCODEX_HOME?: string };
+}
+
+function isRunMessage(data: unknown): data is RunMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const o = data as Record<string, unknown>;
+  return o.type === "run" && typeof o.requestId === "string" && typeof o.trashId === "string";
+}
+
+declare const self: Worker;
+
+self.onmessage = async (event: MessageEvent<unknown>) => {
+  if (!isRunMessage(event.data)) return;
+  const { requestId, trashId, codexHome, busyTimeoutMs, blockMs, restoreTest, env } = event.data;
+  try {
+    if (env?.CODEX_HOME) process.env.CODEX_HOME = env.CODEX_HOME;
+    if (env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = env.OPENCODEX_HOME;
+    if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
+      await Bun.sleep(Math.floor(blockMs));
+    }
+    const result = restoreTrashEntry(trashId, {
+      ...(codexHome ? { codexHome } : {}),
+      ...(busyTimeoutMs !== undefined ? { busyTimeoutMs } : {}),
+      ...(restoreTest ? { _test: restoreTest } : {}),
+    });
+    self.postMessage({ type: "done", requestId, result });
+  } catch (err) {
+    self.postMessage({
+      type: "error",
+      requestId,
+      message: err instanceof Error ? err.message : "worker_failed",
+    });
+  }
+};
+
+export type { RestoreResult };

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

@@ -0,0 +1,109 @@
+/**
+ * Single-flight gate for CODEX_HOME storage mutations (cleanup, restore, policy).
+ *
+ * Manual cleanup, trash restore, and (Phase 3) policy-driven cleanup share one
+ * in-flight slot per resolved CODEX_HOME. A second caller receives
+ * `storage_mutation_busy` immediately — no per-operation queues.
+ */
+import { resolve } from "node:path";
+import { resolveCodexHomeDir } from "../codex/home";
+
+export type StorageMutationKind = "cleanup" | "restore" | "policy";
+
+export type StorageMutationBusyError = "storage_mutation_busy";
+
+export interface StorageMutationCoordinatorTestHooks {
+  /** Block after acquiring the slot, before mutation work (race tests). */
+  blockMs?: number;
+}
+
+interface ActiveSlot {
+  kind: StorageMutationKind;
+  startedAt: number;
+}
+
+const slots = new Map<string, ActiveSlot>();
+let testHooks: StorageMutationCoordinatorTestHooks | null = null;
+
+function slotKey(codexHome?: string): string {
+  return resolve(codexHome ?? resolveCodexHomeDir());
+}
+
+export function setStorageMutationCoordinatorTestHooks(
+  hooks: StorageMutationCoordinatorTestHooks | null,
+): void {
+  testHooks = hooks;
+}
+
+export function resetStorageMutationCoordinatorForTests(): void {
+  testHooks = null;
+  slots.clear();
+}
+
+export function getActiveStorageMutation(
+  codexHome?: string,
+): { kind: StorageMutationKind; startedAt: number } | null {
+  const active = slots.get(slotKey(codexHome));
+  return active ? { kind: active.kind, startedAt: active.startedAt } : null;
+}
+
+export function tryBeginStorageMutation(
+  kind: StorageMutationKind,
+  codexHome?: string,
+): { acquired: true } | { 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 };
+}
+
+export function endStorageMutation(codexHome?: string): void {
+  slots.delete(slotKey(codexHome));
+}
+
+async function applyCoordinatorBlock(): Promise<void> {
+  const blockMs = testHooks?.blockMs;
+  if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
+    await Bun.sleep(Math.floor(blockMs));
+  }
+}
+
+/**
+ * Phase 3 policy worker integration — wrap policy-driven cleanup FS/DB work.
+ * Returns `{ ok: false, error: 'storage_mutation_busy' }` when another mutation
+ * holds the CODEX_HOME slot.
+ */
+export async function runPolicyStorageMutation<T>(
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation("policy", codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    endStorageMutation(codexHome);
+  }
+}
+
+export async function withStorageMutationSlot<T>(
+  kind: StorageMutationKind,
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation(kind, codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    endStorageMutation(codexHome);
+  }
+}

package/src/storage/worker-lifecycle.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+const liveWorkers = new Set<Worker>();
+
+/** Track a freshly spawned worker so teardown can wait for it later. */
+export function registerStorageWorker(worker: Worker): void {
+  liveWorkers.add(worker);
+}
+
+/**
+ * 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.
+ */
+export function terminateStorageWorker(worker: Worker, timeoutMs = 5_000): Promise<void> {
+  if (!liveWorkers.has(worker)) {
+    try { worker.terminate(); } catch { /* already gone */ }
+    return Promise.resolve();
+  }
+  liveWorkers.delete(worker);
+
+  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();
+    }
+  });
+}
+
+/**
+ * Await every worker this module still tracks. 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)));
+}
+
+/** Live worker count — exported so a regression test can assert the invariant. */
+export function liveStorageWorkerCount(): number {
+  return liveWorkers.size;
+}

package/src/tray/windows.ts

@@ -6,6 +6,7 @@ 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 { recordOwnedConfigPath } from "../lib/config-ownership";
 
 const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
 const RUN_PARENT_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion";
@@ -413,17 +414,43 @@ function assertWindows(): void {
   if (process.platform !== "win32") throw new Error(`The opencodex tray is Windows-only (current platform: ${process.platform}).`);
 }
 
-function spawnTray(state: WindowsTrayEntry): void {
-  const child = spawn(state.bun, [state.cli, "__tray-host"], {
-    detached: true,
+const DETACHED_TRAY_HOST_LAUNCHER = [
+  "$startInfo = New-Object System.Diagnostics.ProcessStartInfo",
+  "$startInfo.FileName = $env:OCX_TRAY_HOST_BUN",
+  "$startInfo.Arguments = $env:OCX_TRAY_HOST_ARGS",
+  "$startInfo.UseShellExecute = $true",
+  "$startInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden",
+  "$child = [System.Diagnostics.Process]::Start($startInfo)",
+  "if ($null -eq $child) { throw 'Windows tray host did not start.' }",
+  "$child.Dispose()",
+].join("; ");
+
+const DETACHED_TRAY_HOST_LAUNCHER_B64 = Buffer.from(DETACHED_TRAY_HOST_LAUNCHER, "utf16le").toString("base64");
+
+export function launchWindowsTrayHost(state: WindowsTrayEntry): void {
+  const bun = safePath(state.bun);
+  const cli = safePath(state.cli);
+  execFileSync(windowsPowerShellPath(), [
+    "-NoLogo",
+    "-NoProfile",
+    "-NonInteractive",
+    "-EncodedCommand",
+    DETACHED_TRAY_HOST_LAUNCHER_B64,
+  ], {
     stdio: "ignore",
     windowsHide: true,
+    timeout: 15_000,
     env: {
       ...process.env,
+      OCX_TRAY_HOST_BUN: bun,
+      OCX_TRAY_HOST_ARGS: `${quoteRunValue(cli)} __tray-host`,
       OCX_TRAY_ENTRY_B64: Buffer.from(JSON.stringify(state), "utf8").toString("base64"),
     },
   });
-  child.unref();
+}
+
+function spawnTray(state: WindowsTrayEntry): void {
+  launchWindowsTrayHost(state);
 }
 
 function parseTrayHostEntry(): WindowsTrayEntry {
@@ -442,6 +469,8 @@ export async function runWindowsTrayHost(): Promise<void> {
   assertWindows();
   const entry = parseTrayHostEntry();
   delete process.env.OCX_TRAY_ENTRY_B64;
+  delete process.env.OCX_TRAY_HOST_BUN;
+  delete process.env.OCX_TRAY_HOST_ARGS;
   const child = spawn(windowsPowerShellPath(), windowsTrayProcessArgs(entry, "Run", process.pid), {
     stdio: "ignore",
     windowsHide: true,
@@ -476,6 +505,7 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   for (const path of [entry.bun, entry.cli, sourceScript, ...iconPairs.map(pair => pair.source)]) {
     if (!existsSync(path)) throw new Error(`Cannot install the tray because a required file is missing: ${path}`);
   }
+  recordOwnedConfigPath(getConfigDir(), trayStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
   const runCommand = buildWindowsTrayRunCommand(entry);
   const runValue = windowsTrayRunValue(entry.opencodexHome);