@bitkyc08/opencodex 2.7.43 → 2.8.0

package/src/server/responses/upstream-error.ts

@@ -0,0 +1,48 @@
+/**
+ * Upstream connection failures share one message shape across the three catch sites in
+ * core.ts. A TLS certificate/hostname mismatch deserves its own wording: the generic
+ * "Provider unreachable" reads as if opencodex built a wrong endpoint, which sent issue
+ * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
+ * command that settles it.
+ */
+export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  if (err instanceof Error && err.name === "TimeoutError") {
+    return `Provider connect timeout after ${connectMs}ms`;
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? (err as { code?: unknown }).code : undefined;
+  // `code` is the reliable signal. The message fallback is anchored to the head because Bun
+  // renders this rejection as `ERR_TLS_CERT_ALTNAME_INVALID fetching "<url>"`; matching the
+  // bare substring anywhere would also fire on text that merely quotes the code back at us.
+  // Only transport failures reach these call sites, so that is defensive rather than load-bearing.
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || detail.startsWith("ERR_TLS_CERT_ALTNAME_INVALID")) {
+    const host = extractHostname(detail);
+    const target = host ?? "the provider host";
+    const probe = host ?? "<host>";
+    return `Provider TLS certificate does not match ${target}: ${redactUrlUserinfo(detail)}. `
+      + "opencodex did not rewrite this hostname — a certificate that does not cover it normally "
+      + "means TLS interception (corporate proxy, VPN, or local MITM tooling) or a poisoned DNS "
+      + `answer. Check with: openssl s_client -connect ${probe}:443 -servername ${probe} `
+      + "</dev/null | openssl x509 -noout -subject -ext subjectAltName";
+  }
+  return `Provider unreachable: ${redactUrlUserinfo(detail)}`;
+}
+
+/**
+ * A provider base URL may carry credentials as userinfo (`https://user:token@host/`), and the
+ * runtime error echoes the URL it was fetching. Strip it before the message reaches a client
+ * or a log line.
+ */
+function redactUrlUserinfo(detail: string): string {
+  return detail.replace(/(https?:\/\/)[^/\s"'@]*@/g, "$1<redacted>@");
+}
+
+function extractHostname(detail: string): string | null {
+  const match = detail.match(/https?:\/\/([^/\s"']+)/);
+  if (!match?.[1]) return null;
+  try {
+    return new URL(`https://${match[1]}`).hostname || null;
+  } catch {
+    return null;
+  }
+}

package/src/server/startup-action-control.ts

@@ -106,10 +106,14 @@ export function resetStartupInstallStateForTests(): void {
   installState = { status: "idle" };
 }
 
-export function startupInstallArgv(action: StartupInstallAction): string[] {
-  return action === "install-service"
-    ? ["service", "install"]
-    : ["codex-shim", "install"];
+export function startupInstallArgv(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): string[] {
+  if (action === "install-service") {
+    return options?.repair ? ["service", "repair"] : ["service", "install"];
+  }
+  return ["codex-shim", "install"];
 }
 
 export interface CliInstallFailure {
@@ -152,10 +156,13 @@ export function installFailureDetail(stdout: string, stderr: string, error: Erro
   return classifyCliInstallFailure(stdout, stderr, error).detail;
 }
 
-function runCliInstall(action: StartupInstallAction): Promise<{ stdout: string; stderr: string }> {
+function runCliInstall(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): Promise<{ stdout: string; stderr: string }> {
   const bun = durableBunPath();
   const cli = join(import.meta.dir, "..", "cli", "index.ts");
-  const argv = [cli, ...startupInstallArgv(action)];
+  const argv = [cli, ...startupInstallArgv(action, options)];
   return new Promise((resolve, reject) => {
     execFile(bun, argv, {
       encoding: "utf8",
@@ -219,29 +226,37 @@ function applyReconciliationOutcome(
 /**
  * Execute the existing fixed CLI installer outside the proxy event loop.
  *
+ * Repair mode (`options.repair`) runs `ocx service repair` — asset rewrite + restart
+ * without Task Scheduler re-registration, so it must not enter the UAC elevation path.
+ *
  * After an elevation request timeout the lock becomes `indeterminate` until the
  * original elevated transaction completes and is reconciled. A process restart
  * clears this in-memory lock — callers must then inspect Task Scheduler reality
  * (see evaluateSchedulerInstallRestartReconciliation) before installing again.
  */
-export function runStartupInstallAction(action: StartupInstallAction): Promise<{ message: string }> {
+export function runStartupInstallAction(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): Promise<{ message: string }> {
   const busy = rejectIfBusy(action);
   if (busy) return Promise.reject(busy);
 
+  const repair = options?.repair === true;
   const attemptId = randomUUID();
   const startedAt = Date.now();
   installState = { status: "running", action, attemptId, startedAt };
 
   const operation = (async () => {
     try {
-      await runCliInstall(action);
+      await runCliInstall(action, { repair });
     } catch (error) {
       const code = installFailureCode(error);
       const detail = error instanceof Error ? error.message : String(error);
-      // Elevate only for a structured Task Scheduler /create access denial — never for
-      // WinSW removal, asset writes, or generic permission errors.
+      // Elevate only for fresh install + structured Task Scheduler /create access denial —
+      // never for repair, WinSW removal, asset writes, or generic permission errors.
       if (
-        action === "install-service"
+        !repair
+        && action === "install-service"
         && process.platform === "win32"
         && (code === WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER
           || isWindowsSchtasksCreateAccessDenied(detail))
@@ -276,10 +291,11 @@ export function runStartupInstallAction(action: StartupInstallAction): Promise<{
         throw error;
       }
     }
+    if (action === "install-service") {
+      return { message: repair ? "Background service repaired." : "Background service installed." };
+    }
     return {
-      message: action === "install-service"
-        ? "Background service installed."
-        : "Codex launcher shim installed.",
+      message: repair ? "Codex launcher shim repaired." : "Codex launcher shim installed.",
     };
   })();
 

package/src/service.ts

@@ -17,6 +17,7 @@ import { isWslRuntime } from "./codex/home";
 import { durableBunPath, durableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
 import { serviceApiTokenFilePath } from "./lib/service-secrets";
+import { findLiveProxy } from "./server/proxy-liveness";
 import { randomUUID } from "node:crypto";
 import {
   ELEVATION_REQUEST_TIMEOUT_MS,
@@ -35,6 +36,7 @@ import { defaultWinswEntry, installWinswService, startWinswService, stopWinswSer
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from "./lib/win-paths";
 import { recordOwnedConfigPath } from "./lib/config-ownership";
+import { maybeShowStarPrompt } from "./cli/star-prompt";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -354,8 +356,41 @@ function sh(cmd: string): string {
   return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
 }
 
+/**
+ * Decode schtasks stdout. `/query /xml` emits UTF-16LE (often with BOM) because the
+ * registered task document is UTF-16; reading that as UTF-8 makes every health check
+ * fail ("registration present but unhealthy") and rolls back a successful elevated create.
+ */
+export function decodeSchtasksOutput(buffer: Buffer): string {
+  if (buffer.length === 0) return "";
+  const bomUtf16Le = buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe;
+  const bomUtf16Be = buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff;
+  const looksUtf16Le = buffer.length >= 4
+    && buffer[1] === 0x00
+    && buffer[3] === 0x00
+    && buffer[0] !== 0x00;
+  if (bomUtf16Le || looksUtf16Le) {
+    return buffer.toString("utf16le").replace(/^\uFEFF/, "").trim();
+  }
+  if (bomUtf16Be) {
+    // Swap pairs then decode as utf16le.
+    const swapped = Buffer.alloc(buffer.length - 2);
+    for (let i = 2; i + 1 < buffer.length; i += 2) {
+      swapped[i - 2] = buffer[i + 1]!;
+      swapped[i - 1] = buffer[i]!;
+    }
+    return swapped.toString("utf16le").trim();
+  }
+  return buffer.toString("utf8").replace(/^\uFEFF/, "").trim();
+}
+
 function runFile(file: string, args: string[]): string {
-  return execFileSync(file, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }).trim();
+  const buffer = execFileSync(file, args, {
+    encoding: "buffer",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  }) as Buffer;
+  return decodeSchtasksOutput(buffer);
 }
 
 function windowsSchtasks(): string {
@@ -393,6 +428,70 @@ export type WindowsSchedulerTaskProbe =
   | { status: "absent" }
   | { status: "unknown"; detail: string };
 
+export type WindowsSchedulerProxyProbe =
+  | { status: "running"; port: number }
+  | { status: "not-running" }
+  | { status: "unknown" };
+
+/**
+ * Render Task Scheduler status without exposing localized `schtasks` table output.
+ * The task probe answers installation state; the identity-checked health probe answers
+ * runtime state. Keep probe details out of this user-facing line because they can contain
+ * incorrectly decoded, locale-specific command output.
+ */
+export function formatWindowsSchedulerServiceStatus(
+  task: WindowsSchedulerTaskProbe,
+  proxy: WindowsSchedulerProxyProbe,
+): string {
+  if (task.status === "present") {
+    if (proxy.status === "running") {
+      return `✅ service installed (Task Scheduler); OpenCodex proxy running on port ${proxy.port}.`;
+    }
+    if (proxy.status === "not-running") {
+      return "⚠️  service installed (Task Scheduler); OpenCodex proxy not running.";
+    }
+    return "⚠️  service installed (Task Scheduler); OpenCodex proxy status unknown.";
+  }
+  if (task.status === "absent") {
+    if (proxy.status === "running") {
+      return `❌ service not installed (Task Scheduler); OpenCodex proxy is running independently on port ${proxy.port}.`;
+    }
+    if (proxy.status === "unknown") {
+      return "❌ service not installed (Task Scheduler); OpenCodex proxy status unknown.";
+    }
+    return "❌ service not installed (Task Scheduler).";
+  }
+  if (proxy.status === "running") {
+    return `⚠️  Task Scheduler registration unknown; OpenCodex proxy running on port ${proxy.port}.`;
+  }
+  if (proxy.status === "not-running") {
+    return "⚠️  service status unknown (Task Scheduler query failed); OpenCodex proxy not running.";
+  }
+  return "⚠️  service status unknown (Task Scheduler and proxy checks failed).";
+}
+
+export async function inspectWindowsSchedulerServiceStatus(io: {
+  probeTask?: () => WindowsSchedulerTaskProbe;
+  findProxy?: () => Promise<{ port: number } | null>;
+} = {}): Promise<string> {
+  let task: WindowsSchedulerTaskProbe;
+  try {
+    task = (io.probeTask ?? probeWindowsSchedulerTask)();
+  } catch (error) {
+    task = { status: "unknown", detail: schtasksErrorDetail(error) };
+  }
+
+  let proxy: WindowsSchedulerProxyProbe;
+  try {
+    const live = await (io.findProxy ?? findLiveProxy)();
+    proxy = live ? { status: "running", port: live.port } : { status: "not-running" };
+  } catch {
+    proxy = { status: "unknown" };
+  }
+
+  return formatWindowsSchedulerServiceStatus(task, proxy);
+}
+
 function schtasksErrorDetail(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -486,7 +585,9 @@ export function evaluateWindowsSchedulerInstallVerification(inputs: {
       : !assetsHealthy
         ? "Required scheduler service assets are missing."
         : !registrationHealthy
-          ? "Task Scheduler registration is present but unhealthy."
+          ? (inputs.xml.trim()
+            ? "Task Scheduler registration is present but unhealthy."
+            : "Task Scheduler task is present but its XML could not be read.")
           : nativeStatusUnknown
             ? "The Task Scheduler task was created, but OpenCodex could not verify that the native WinSW service is absent."
             : "ok";
@@ -505,9 +606,18 @@ export function evaluateWindowsSchedulerInstallVerification(inputs: {
 /** Conflict-free postcondition check for an elevated scheduler install. */
 export function verifyWindowsSchedulerInstall(taskName = TASK): WindowsSchedulerInstallVerification {
   const taskInstalled = windowsSchedulerTaskInstalled(taskName);
-  const xml = taskInstalled ? (() => {
-    try { return querySchtasks(["/query", "/tn", taskName, "/xml"]); } catch { return ""; }
-  })() : "";
+  let xml = "";
+  if (taskInstalled) {
+    try { xml = querySchtasks(["/query", "/tn", taskName, "/xml"]); } catch { xml = ""; }
+  }
+  // After elevated create, non-elevated `/query /xml` can fail or return empty while the
+  // task is still listed. Fall back to the on-disk document we registered.
+  if (taskInstalled && !xml.trim()) {
+    const diskPath = windowsTaskXmlPath();
+    if (existsSync(diskPath)) {
+      try { xml = decodeSchtasksOutput(readFileSync(diskPath)); } catch { /* keep empty */ }
+    }
+  }
   return evaluateWindowsSchedulerInstallVerification({
     taskInstalled,
     xml,
@@ -895,6 +1005,22 @@ function taskXmlString(value: string): string {
     .replace(/'/g, "&apos;");
 }
 
+/**
+ * RunLevel check. Schema default is LeastPrivilege (omitted on export). Elevated
+ * `schtasks /create` often rewrites the registered task to HighestAvailable even when
+ * the source XML asked for LeastPrivilege — still InteractiveToken / same user.
+ * Keep accepting HighestAvailable here: rejecting it would false-fail healthy elevated
+ * installs, and windowsTaskRegistrationHealthy tests encode that contract.
+ */
+function taskXmlRunLevelAcceptable(principal: string): boolean {
+  if (taskXmlHasPrefixedTag(principal, "RunLevel")) return false;
+  const count = taskXmlElementCount(principal, "RunLevel");
+  if (count === 0) return true;
+  if (count > 1) return false;
+  const value = new RegExp(`<RunLevel(?:\\s[^>]*?)?>\\s*([^<]*?)\\s*<\\/RunLevel>`, "i").exec(principal)?.[1]?.trim().toLowerCase();
+  return value === "leastprivilege" || value === "highestavailable";
+}
+
 export function buildWindowsServiceScript(entry = cliEntry(), port = resolveServiceListenPort()): string {
   const { bun, cli } = entry;
   const bunRuntime = durableBunRuntime();
@@ -1076,7 +1202,7 @@ function taskXmlDecodedValueEquals(xml: string, tag: string, expected: string):
   // `[^<]*` refuses nested markup, so a decoy inside a child element cannot match.
   const value = new RegExp(`<${tag}(?:\\s[^>]*?)?>([^<]*)<\\/${tag}>`, "i").exec(xml)?.[1];
   if (value === undefined) return false;
-  return taskXmlDecodeEntities(value).trim() === expected.trim();
+  return taskXmlDecodeEntities(value).trim().toLowerCase() === expected.trim().toLowerCase();
 }
 
 function taskXmlOptionalValueEquals(xml: string, tag: string, expected: string): boolean {
@@ -1112,13 +1238,14 @@ export function windowsTaskRegistrationHealthy(
   return taskXmlElementCount(triggers, "LogonTrigger") > 0
     && taskXmlOptionalValueEquals(trigger, "Enabled", "true")
     && /<LogonType>\s*InteractiveToken\s*<\/LogonType>/i.test(principal)
-    && taskXmlOptionalValueEquals(principal, "RunLevel", "LeastPrivilege")
+    && taskXmlRunLevelAcceptable(principal)
     && taskXmlOptionalValueEquals(settings, "Enabled", "true")
     && /<MultipleInstancesPolicy>\s*IgnoreNew\s*<\/MultipleInstancesPolicy>/i.test(settings)
     && /<ExecutionTimeLimit>\s*PT0S\s*<\/ExecutionTimeLimit>/i.test(settings)
     // Compare decoded VALUES, not encodings: Task Scheduler canonicalizes the
     // quotes we wrote as `&quot;` back to literal `"` on export, so an escaped
     // needle never matched and a healthy task read as permanently stale (#608).
+    // Case-insensitive: elevated `schtasks /create` may rewrite System32 casing.
     && taskXmlDecodedValueEquals(action, "Command", wscript)
     && taskXmlDecodedValueEquals(action, "Arguments", `/b /nologo "${launcher}"`);
 }
@@ -1191,10 +1318,23 @@ function writeServiceAssetWithRetry(path: string, content: string, encoding: "ut
   }
 }
 
-function installWindows(): void {
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+/**
+ * Rewrite on-disk scheduler assets (script/VBS/XML) without re-registering the task.
+ * Used by fresh install (before schtasks /create) and by repair (no elevation).
+ */
+function writeWindowsSchedulerAssets(): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
+  const script = windowsServiceScriptPath();
+  writeServiceAssetWithRetry(script, buildWindowsServiceScript(), "utf8");
+  // UTF-16LE + BOM: a BOM-less UTF-8 VBS mis-decodes non-ASCII (e.g. Korean) profile
+  // paths on some WSH/codepage combinations — same contract as the task XML below.
+  writeServiceAssetWithRetry(windowsLauncherVbsPath(), `\uFEFF${buildWindowsLauncherVbs(script)}`, "utf16le");
+  writeServiceAssetWithRetry(windowsTaskXmlPath(), `\uFEFF${buildWindowsTaskXml(script)}`, "utf16le");
+}
+
+function installWindows(): void {
+  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   // Transactional backend switch: installing the scheduler backend removes a native
   // service first — two live managers would both respawn the proxy (conflict).
   if (statusWinswRaw() !== "nonexistent") {
@@ -1211,17 +1351,78 @@ function installWindows(): void {
   // End a running task BEFORE rewriting the assets it is executing — cmd.exe reading the
   // script mid-rewrite runs a torn batch file, and its open handle can fail the write.
   try { stopWindows(); } catch { /* not running */ }
-  const script = windowsServiceScriptPath();
-  writeServiceAssetWithRetry(script, buildWindowsServiceScript(), "utf8");
-  // UTF-16LE + BOM: a BOM-less UTF-8 VBS mis-decodes non-ASCII (e.g. Korean) profile
-  // paths on some WSH/codepage combinations — same contract as the task XML below.
-  writeServiceAssetWithRetry(windowsLauncherVbsPath(), `\uFEFF${buildWindowsLauncherVbs(script)}`, "utf16le");
-  writeServiceAssetWithRetry(windowsTaskXmlPath(), `\uFEFF${buildWindowsTaskXml(script)}`, "utf16le");
-  schtasks(buildWindowsSchtasksCreateArgs(script));
+  writeWindowsSchedulerAssets();
+  schtasks(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
   schtasks(["/run", "/tn", TASK]);
   writeServiceInstallState("scheduler");
 }
 
+export interface RepairServiceDeps {
+  diagnose?: () => ServiceDiagnostic;
+  assertEnv?: () => void;
+  assertAuth?: () => void;
+  writeSchedulerAssets?: () => void;
+  stopScheduler?: () => void;
+  startScheduler?: () => void;
+  writeSchedulerState?: () => void;
+  writeNativeState?: () => void;
+  repairNative?: () => void | Promise<void>;
+  repairLaunchd?: () => void;
+  repairSystemd?: () => void;
+  /** Test seam — defaults to process.platform so Linux CI cannot hit real installSystemd. */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Repair an already-installed background service without Task Scheduler re-registration.
+ *
+ * Windows scheduler: rewrite assets + stop/start — no `schtasks /create`, no UAC.
+ * Windows native: WinSW asset rewrite + restart (skips `install /p` when present).
+ * macOS/Linux: re-run the user-level install/reload path.
+ */
+export async function repairService(deps: RepairServiceDeps = {}): Promise<void> {
+  const diagnose = deps.diagnose ?? diagnoseService;
+  const platform = deps.platform ?? process.platform;
+  const diag = diagnose();
+  if (!diag.supported) {
+    throw new Error(`Background service is unsupported (${diag.summary}).`);
+  }
+  if (diag.conflict) {
+    throw new Error(
+      "Cannot repair while Task Scheduler and native WinSW are both present. "
+        + "Run 'ocx service uninstall' then reinstall one backend with 'ocx service install'.",
+    );
+  }
+  if (!diag.installed) {
+    throw new Error("Background service is not installed. Run 'ocx service install' first.");
+  }
+
+  (deps.assertEnv ?? assertServiceEnvironmentMatchesInstall)();
+  (deps.assertAuth ?? assertServiceAuthEnvironment)();
+
+  if (platform === "win32") {
+    if (diag.backend === "native") {
+      await (deps.repairNative ?? (() => installWinswService(defaultWinswEntry(import.meta.dir))))();
+      (deps.writeNativeState ?? (() => writeServiceInstallState("native")))();
+      return;
+    }
+    try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
+    (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)();
+    (deps.startScheduler ?? startWindows)();
+    (deps.writeSchedulerState ?? (() => writeServiceInstallState("scheduler")))();
+    return;
+  }
+  if (platform === "darwin") {
+    (deps.repairLaunchd ?? installLaunchd)();
+    return;
+  }
+  if (platform === "linux") {
+    (deps.repairSystemd ?? installSystemd)();
+    return;
+  }
+  throw new Error(`Background service repair is unsupported on ${platform}.`);
+}
+
 /**
  * Opt-in native backend (`ocx service install --native`). Transactional: removes the
  * scheduler backend first; on failure the machine is left with NO service (explicitly
@@ -1711,6 +1912,13 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     console.error("--native (WinSW) is Windows-only.");
     process.exit(1);
   }
+  if (command === "repair") {
+    assertServiceEnvironmentMatchesInstall();
+    assertServiceAuthEnvironment();
+    await repairService();
+    console.log("✅ opencodex background service repaired (assets refreshed, no Task Scheduler re-registration).");
+    return;
+  }
   // Non-install subcommands follow the backend recorded at install time (state v2).
   const backend: ServiceBackend = parsed.backend ?? (process.platform === "win32" ? readServiceBackend() : "scheduler");
   const ops = platformOps(backend);
@@ -1727,6 +1935,11 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         ? "✅ opencodex native service installed + started (windowless, starts at boot, auto-restarts on crash)."
         : "✅ opencodex service installed + started (auto-starts on login, auto-restarts on crash).");
       if (process.platform === "linux") console.log("   For auto-start on boot: loginctl enable-linger $USER");
+      // Service users never reach the `ocx start` prompt: the proxy they run is the
+      // supervised child, which always carries OCX_SERVICE=1. This command, though, is
+      // hand-typed in a real terminal, so it is the one interactive moment they get.
+      // Same one-time marker and same guards (TTY, gh auth, agent deferral) apply.
+      await maybeShowStarPrompt();
       break;
     case "start":
       ops.start();
@@ -1750,8 +1963,12 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       }
       break;
     case "status": {
-      const s = ops.status();
-      console.log(s ? `✅ running:\n${s}` : "❌ service not installed/running.");
+      if (process.platform === "win32" && backend === "scheduler") {
+        console.log(await inspectWindowsSchedulerServiceStatus());
+      } else {
+        const s = ops.status();
+        console.log(s ? `✅ running:\n${s}` : "❌ service not installed/running.");
+      }
       console.log(`Diagnostics: ${serviceDiagnosticsSummary()}`);
       break;
     }
@@ -1783,8 +2000,9 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       console.log("✅ service uninstalled.");
       break;
     default:
-      console.error("Usage: ocx service [install|start|stop|status|uninstall|remove] [--native|--scheduler]");
+      console.error("Usage: ocx service [install|repair|start|stop|status|uninstall|remove] [--native|--scheduler]");
       console.error("       With no subcommand, installs/updates and starts the background service.");
+      console.error("       repair: refresh assets and restart an already-installed service (no admin re-prompt).");
       console.error("       --native (Windows only): register a real SCM service via WinSW instead of Task Scheduler.");
       process.exit(1);
   }

package/src/storage/policy-job.ts

@@ -18,6 +18,11 @@ import {
   type PolicyRunResult,
   type PolicySkipReason,
 } from "./policy";
+import {
+  drainStorageWorkers,
+  registerStorageWorker,
+  terminateStorageWorker,
+} from "./worker-lifecycle";
 
 export type PolicyJobStatus = "idle" | "running";
 
@@ -127,7 +132,7 @@ function disownActiveRun(): void {
 export function resetStorageCleanupPolicyJobForTests(): void {
   disownActiveRun();
   if (activeWorker) {
-    try { activeWorker.terminate(); } catch { /* */ }
+    void terminateStorageWorker(activeWorker);
     activeWorker = null;
   }
   inflight = null;
@@ -136,11 +141,24 @@ export function resetStorageCleanupPolicyJobForTests(): void {
   state = { status: "idle" };
 }
 
+/**
+ * Await-able sibling of the reset above, for test teardown.
+ *
+ * `bun test --isolate` reclaims a file's realm at the file boundary. A storage
+ * worker still exiting at that moment trips a Bun-internal assertion on Windows
+ * and takes the whole run down, so a suite that spawns workers must be able to
+ * wait for them rather than fire-and-forget.
+ */
+export async function resetStorageCleanupPolicyJobForTestsAsync(): Promise<void> {
+  resetStorageCleanupPolicyJobForTests();
+  await drainStorageWorkers();
+}
+
 /** Terminate an in-flight worker during process shutdown. */
 export function abortStorageCleanupPolicyJob(): void {
   disownActiveRun();
   if (activeWorker) {
-    try { activeWorker.terminate(); } catch { /* */ }
+    void terminateStorageWorker(activeWorker);
     activeWorker = null;
   }
   releaseHeldMutationSlot();
@@ -218,13 +236,14 @@ function runInWorker(opts: RequestPolicyRunOptions & { blockMs?: number }): Prom
     const requestId = crypto.randomUUID();
     let settled = false;
     const worker = new Worker(new URL("./policy-worker.ts", import.meta.url).href);
+    registerStorageWorker(worker);
     activeWorker = worker;
 
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
       cancelActiveRun = null;
-      try { worker.terminate(); } catch { /* */ }
+      void terminateStorageWorker(worker);
       if (activeWorker === worker) activeWorker = null;
       reject(new Error("storage_cleanup_worker_timeout"));
     }, WORKER_TIMEOUT_MS);
@@ -235,8 +254,10 @@ function runInWorker(opts: RequestPolicyRunOptions & { blockMs?: number }): Prom
       cancelActiveRun = null;
       clearTimeout(timer);
       if (activeWorker === worker) activeWorker = null;
-      try { worker.terminate(); } catch { /* */ }
-      fn();
+      // Settle the caller only after the thread is actually gone, so a suite
+      // that awaits its request cannot reach the next test file with a worker
+      // still exiting behind it.
+      void terminateStorageWorker(worker).then(fn, fn);
     };
 
     cancelActiveRun = () => {

package/src/storage/restore-job.ts

@@ -16,6 +16,11 @@ import {
   withStorageMutationSlot,
   type StorageMutationCoordinatorTestHooks,
 } from "./storage-mutation-coordinator";
+import {
+  drainStorageWorkers,
+  registerStorageWorker,
+  terminateStorageWorker,
+} from "./worker-lifecycle";
 
 export interface RestoreJobTestHooks extends StorageMutationCoordinatorTestHooks {
   /**
@@ -69,7 +74,7 @@ export function setRestoreTrashJobTestHooks(hooks: RestoreJobTestHooks | null):
 
 export function resetRestoreTrashJobForTests(): void {
   if (activeWorker) {
-    try { activeWorker.terminate(); } catch { /* */ }
+    void terminateStorageWorker(activeWorker);
     activeWorker = null;
   }
   cancelActiveRun?.();
@@ -78,10 +83,16 @@ export function resetRestoreTrashJobForTests(): void {
   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) {
-    try { activeWorker.terminate(); } catch { /* */ }
+    void terminateStorageWorker(activeWorker);
     activeWorker = null;
   }
   cancelActiveRun?.();
@@ -117,13 +128,14 @@ function runInWorker(opts: {
     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;
-      try { worker.terminate(); } catch { /* */ }
+      void terminateStorageWorker(worker);
       if (activeWorker === worker) activeWorker = null;
       reject(new Error("restore_worker_timeout"));
     }, WORKER_TIMEOUT_MS);
@@ -134,8 +146,7 @@ function runInWorker(opts: {
       cancelActiveRun = null;
       clearTimeout(timer);
       if (activeWorker === worker) activeWorker = null;
-      try { worker.terminate(); } catch { /* */ }
-      fn();
+      void terminateStorageWorker(worker).then(fn, fn);
     };
 
     cancelActiveRun = () => {