@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/service/health-sentinel-main.ts

@@ -12,11 +12,10 @@
  * - Windows reuses ids quickly, so the sentinel opens a handle on its parent at startup, accepts it
  *   only if that process was created before the sentinel, and terminates through the handle
  *   (health-sentinel-windows.ts). While the handle is open the id cannot be reused.
- * - POSIX allocates ids sequentially, and the sentinel's live `process.ppid` changes the moment
- *   its parent exits, before the exited parent can be reaped and its id freed. It is the last check
- *   before `kill`. Reuse inside that window needs the parent to exit, be reaped, and the id space to
- *   wrap completely (99,999 ids on macOS, `pid_max` on Linux) between two adjacent syscalls; that
- *   residual is accepted and documented in structure/ops/service-health-recovery.md.
+ * - Linux holds a pidfd after rechecking the live parent relationship, and signals that fd.
+ *   Only unsupported kernels/architectures retain the live-ppid fallback used by macOS.
+ * - macOS checks the live parent id immediately before SIGKILL; PID reuse between those two
+ *   syscalls remains a documented residual (structure/ops/service-health-recovery.md).
  *
  * SIGKILL rather than SIGTERM: a proxy whose event loop is stuck cannot run its own SIGTERM
  * handler, and systemd counts a SIGTERM death as a clean exit that `Restart=on-failure` does not
@@ -80,6 +79,8 @@ export type HealthSentinelDeps = {
   isTargetGone(): boolean;
   /** Bind to the target once at startup; a failure stands the sentinel down. */
   bindTarget(): { ok: true } | { ok: false; reason: string };
+  /** Release the process owner on every exit, refusal, cancellation or exception. */
+  closeTarget(): void;
   /** Terminate the bound target, re-proving it is still the target at the last moment. */
   terminateTarget(): TerminateResult;
   /** Run under the ownership mutation lease, released on return; "busy" when it could not be taken promptly. */
@@ -149,6 +150,11 @@ function matchesProbeTarget(runtime: SentinelRuntimeRecord | null, pid: number,
 }
 
 export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<HealthSentinelResult> {
+  try { return await observeHealthSentinel(deps); }
+  finally { deps.closeTarget(); }
+}
+
+async function observeHealthSentinel(deps: HealthSentinelDeps): Promise<HealthSentinelResult> {
   const timing: HealthSentinelTiming = { ...DEFAULT_HEALTH_SENTINEL_TIMING, ...deps.timing };
   const standDown = (reason: string): HealthSentinelResult => {
     deps.log(`standing down: ${reason} (pid ${deps.targetPid})`);
@@ -407,59 +413,72 @@ export async function runHealthSentinelProcess(env: NodeJS.ProcessEnv = process.
     if (opened.ok) windowsHandle = opened.handle;
     else windowsBindFailure = opened.reason;
   }
+  let linuxHandle: import("./health-sentinel-linux").ParentPidfd | null = null;
+  let linuxBindFailure: string | null = null;
+  if (process.platform === "linux") {
+    const { openParentPidfd } = await import("./health-sentinel-linux");
+    const opened = openParentPidfd(targetPid, () => !gone && process.ppid === targetPid);
+    if (opened.kind === "bound") linuxHandle = opened.handle;
+    else if (opened.kind === "refused") linuxBindFailure = opened.reason;
+    else appendBoundedLog(logPath, `pidfd unavailable: ${opened.reason}; using live parent PID check`);
+  }
   const lag = startLagMonitor();
-  const result = await runHealthSentinel({
-    targetPid,
-    now: Date.now,
-    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
-    probe: async (target, timeoutMs) => {
-      lag.reset();
-      const outcome = await probeHealth(target, timeoutMs);
-      return outcome.kind === "timeout" ? { ...outcome, sentinelLagMs: lag.read() } : outcome;
-    },
-    readRuntime: () => readSentinelRuntime(runtimePath),
-    targetExited,
-    isTargetGone: () => gone || (windowsHandle?.exited() ?? false),
-    bindTarget: () => {
-      // POSIX: Bun reads the parent id live, and it stops naming the proxy once the proxy exits.
-      // Windows: it is the creating parent's id, so the handle below carries the identity.
-      if (process.ppid !== targetPid) return { ok: false, reason: "the sentinel is not the watched process's child" };
-      if (process.platform !== "win32") return { ok: true };
-      return windowsHandle ? { ok: true } : { ok: false, reason: windowsBindFailure ?? "the parent process cannot be opened" };
-    },
-    terminateTarget: () => {
-      if (process.platform === "win32") {
-        if (!windowsHandle) return "failed";
-        return windowsHandle.terminate(1) ? "terminated" : "failed";
-      }
-      if (gone || process.ppid !== targetPid) return "not_target";
-      try {
-        process.kill(targetPid, "SIGKILL");
-        return "terminated";
-      } catch {
-        return "failed";
-      }
-    },
-    withOwnershipLease: run => {
-      let lease: { release(): void };
-      try {
-        lease = acquireOwnershipMutationLease(statePaths, { waitMs: LEASE_WAIT_MS, processImage: () => null });
-      } catch {
-        return "busy";
-      }
-      try { return run(); } finally { lease.release(); }
-    },
-    readHistory: () => {
-      const entries = readRecoveryEntries(historyPath);
-      return entries === null ? null : countedRecoveryTimes(entries);
-    },
-    writeHistory: entry => writeRecoveryEntry(historyPath, entry),
-    log: line => appendBoundedLog(logPath, line),
-    timing: parseTimingOverride(env[HEALTH_SENTINEL_ENV.timing]),
-  });
-  lag.stop();
-  windowsHandle?.close();
-  void result;
+  try {
+    await runHealthSentinel({
+      targetPid,
+      now: Date.now,
+      sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+      probe: async (target, timeoutMs) => {
+        lag.reset();
+        const outcome = await probeHealth(target, timeoutMs);
+        return outcome.kind === "timeout" ? { ...outcome, sentinelLagMs: lag.read() } : outcome;
+      },
+      readRuntime: () => readSentinelRuntime(runtimePath),
+      targetExited,
+      closeTarget: () => { linuxHandle?.close(); windowsHandle?.close(); },
+      isTargetGone: () => gone || (windowsHandle?.exited() ?? false),
+      bindTarget: () => {
+        // POSIX: Bun reads the parent id live, and it stops naming the proxy once the proxy exits.
+        // Windows: it is the creating parent's id, so the handle below carries the identity.
+        if (process.ppid !== targetPid) return { ok: false, reason: "the sentinel is not the watched process's child" };
+        if (linuxBindFailure) return { ok: false, reason: linuxBindFailure };
+        if (process.platform !== "win32") return { ok: true };
+        return windowsHandle ? { ok: true } : { ok: false, reason: windowsBindFailure ?? "the parent process cannot be opened" };
+      },
+      terminateTarget: () => {
+        if (process.platform === "win32") {
+          if (!windowsHandle) return "failed";
+          return windowsHandle.terminate(1) ? "terminated" : "failed";
+        }
+        if (gone || process.ppid !== targetPid) return "not_target";
+        if (linuxHandle) return linuxHandle.terminate();
+        try {
+          process.kill(targetPid, "SIGKILL");
+          return "terminated";
+        } catch {
+          return "failed";
+        }
+      },
+      withOwnershipLease: run => {
+        let lease: { release(): void };
+        try {
+          lease = acquireOwnershipMutationLease(statePaths, { waitMs: LEASE_WAIT_MS, processImage: () => null });
+        } catch {
+          return "busy";
+        }
+        try { return run(); } finally { lease.release(); }
+      },
+      readHistory: () => {
+        const entries = readRecoveryEntries(historyPath);
+        return entries === null ? null : countedRecoveryTimes(entries);
+      },
+      writeHistory: entry => writeRecoveryEntry(historyPath, entry),
+      log: line => appendBoundedLog(logPath, linuxHandle && line.startsWith("watching pid ") ? `${line} (pidfd)` : line),
+      timing: parseTimingOverride(env[HEALTH_SENTINEL_ENV.timing]),
+    });
+  } finally {
+    lag.stop();
+  }
   return 0;
 }
 

package/src/service/health.ts

@@ -1,77 +1,18 @@
-import { win32 } from "node:path";
 import { loadConfig } from "../config";
-import { serviceApiTokenFilePath } from "../lib/service-secrets";
-import { PROXY_ENV_KEYS } from "../lib/proxy-env";
+import { resolveServiceListenPort } from "./definition";
 import { proxyIdentityAt } from "../server/proxy-liveness";
 import { launchdListenPort } from "./launchd";
 import { serviceLogPath } from "./state";
 import { systemdListenPort } from "./systemd";
 import { windowsListenPort, winswListenPort } from "./windows-ops";
 
-export function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
-/**
- * Listen port baked into service wrappers / WinSW XML.
- * Priority: explicit override → OCX_BAKE_PORT (update restart) → config.port → 10100.
- * `config.port === 0` means ephemeral for interactive start; services need a stable pin,
- * so treat 0 / invalid like unset (default 10100) instead of baking `--port 0`.
- */
-export function resolveServiceListenPort(override?: number): number {
-  if (typeof override === "number" && Number.isFinite(override) && override > 0 && override <= 65535) {
-    return Math.trunc(override);
-  }
-  const baked = process.env.OCX_BAKE_PORT?.trim();
-  if (baked && /^\d+$/.test(baked)) {
-    const n = Number(baked);
-    if (n > 0 && n <= 65535) return n;
-  }
-  const configured = loadConfig().port;
-  if (typeof configured === "number" && configured > 0 && configured <= 65535) return configured;
-  return 10100;
-}
-
-export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
-  const tokenFile = serviceApiTokenFilePath();
-  const args = cli ? `${shellQuote(cli)} start` : "start";
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
-}
-
-/**
- * The same command shape, launched through a stable `ocx` executable instead of an
- * explicit Bun + CLI pair. The token-file preamble is identical and deliberately shared
- * in form: the service still reads the token from disk at start and never carries it in
- * the unit.
- */
-export function buildServiceLauncherShellCommand(launcher: string, port = resolveServiceListenPort()): string {
-  const tokenFile = serviceApiTokenFilePath();
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
-}
-
-/**
- * Shared tail parser for the baked `--port <n>`.
- *
- * Terminators cover all three artifact shapes: whitespace (batch wrapper, systemd
- * unit), `"` (systemd's quoted ExecStart), `<` (WinSW's `</arguments>`), and `&` (an
- * XML-escaped quote). Matched LAST because every artifact carries the Bun and CLI
- * paths ahead of the argument, and a path containing the literal must not shadow it.
- */
-export function parseBakedListenPort(read: () => string): number | null {
-  try {
-    const last = [...read().matchAll(/start --port (\d{1,5})(?:\s|"|&|<|$)/gm)].at(-1);
-    if (!last) return null;
-    const n = Number(last[1]);
-    return n > 0 && n <= 65535 ? n : null;
-  } catch {
-    return null;
-  }
-}
+export { resolveServiceListenPort };
+export { shellQuote, buildServiceShellCommand, buildServiceLauncherShellCommand, parseBakedListenPort, resolvedProxyEnv } from "./definition";
 
 /**
  * The listen port of the INSTALLED service artifact, falling back to the configured
- * one. Each reader returns null off its own platform, so the chain needs no platform
- * branch — and on Windows both return null, preserving today's behavior.
+ * one. This historical artifact chain can read retained files from another platform;
+ * platform-specific launchd command checks instead use only the plist and configured port.
  */
 export function installedServiceListenPort(): number {
   return launchdListenPort()
@@ -239,28 +180,3 @@ export async function reportServiceServing(
 export function serviceRepairCommand(): string {
   return "ocx service repair";
 }
-
-/**
- * Outbound proxy settings the installing shell had, resolved for baking into a service
- * definition.
- *
- * A service manager does not inherit the environment of the shell that installed it, and
- * `ExecStart=/bin/sh -lc` is dash on Ubuntu/WSL — login dash reads `.profile`, not
- * `.bashrc`, which is where proxy exports usually live. So a user who needs a proxy to
- * reach the upstream got a service that dialed direct: the socket was reset, the retry
- * budget drained, and the request surfaced as `502 Provider unreachable` (#2107). The
- * same install driven through `ocx codex-shim` worked, because that path spawns with
- * `{ ...process.env }`.
- *
- * Lower-case variants are honored because curl-style tooling sets them and the runtime's
- * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
- * upper-case name is baked, so a definition never carries two spellings of one setting.
- */
-export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
-  const resolved: { name: string; value: string }[] = [];
-  for (const key of PROXY_ENV_KEYS) {
-    const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
-    if (value) resolved.push({ name: key, value });
-  }
-  return resolved;
-}

package/src/service/launchd.ts

@@ -11,7 +11,7 @@ import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime, type D
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./guards";
-import { resolveServiceListenPort, buildServiceShellCommand, buildServiceLauncherShellCommand, installedServiceListenPort, resolvedProxyEnv } from "./health";
+import { resolveServiceListenPort, buildServiceShellCommand, buildServiceLauncherShellCommand, resolvedProxyEnv } from "./definition";
 import { SERVICE_MANAGED_ENV, LABEL, cliEntry, filterTransientServicePath, logPath, serviceStatePath, currentCodexSqliteHomeAbsolute, type ServiceInstallState, writeServiceInstallState, readServiceInstallState } from "./state";
 import { writeServiceDefinitionFile } from "./windows-ops";
 import { readTextOrNull } from "./windows-taskxml";
@@ -359,8 +359,11 @@ export function probeLaunchdLoadState(deps: {
   for (const domain of [`gui/${uid}`, `user/${uid}`]) {
     const printed = run(["print", `${domain}/${LABEL}`]);
     if (printed.status === 0) {
+      // Use this backend's plist, then the configured service port. Foreign artifacts
+      // can exist on macOS: systemdListenPort has no platform gate, so the general
+      // installed-artifact chain could incorrectly select a copied Linux unit's port.
       const expected = (deps.expectedCommand
-        ?? (() => expectedLaunchdCommand(installedServiceListenPort())))();
+        ?? (() => expectedLaunchdCommand(launchdListenPort() ?? resolveServiceListenPort())))();
       const printedText = `${printed.stdout}\n${printed.stderr}`;
       return {
         state: printedText.includes(expected) ? "loaded-current" : "loaded-stale",
@@ -382,8 +385,16 @@ export function probeLaunchdLoadState(deps: {
   return { state: "not-loaded" };
 }
 
-/** Up to ~5 × 200 ms, the launchd twin of the Windows scheduler settle delays. */
-const LAUNCHD_SETTLE_ATTEMPTS = 5;
+/**
+ * Up to 125 × 200 ms = 25 s: long enough for an evicted job to finish EXITING. Measured on
+ * macOS 26: `bootout` returns at once, the label stays registered (`state = SIGTERMed`) until
+ * the process exits, and `bootstrap` fails with 5 for that whole window. The proxy drains on
+ * SIGTERM (`shutdownTimeoutMs`, 5 s default) behind a launcher that waits for it, so a 1 s
+ * settle bootstrapped into that window, the retry and the rollback raced it too, and the old
+ * job then exited leaving nothing loaded. launchd SIGKILLs at its default `ExitTimeOut` of
+ * 20 s, which bounds this wait.
+ */
+const LAUNCHD_SETTLE_ATTEMPTS = 125;
 
 const LAUNCHD_SETTLE_DELAY_MS = 200;
 
@@ -769,6 +780,7 @@ export function restartLaunchdJob(deps: {
 export function startLaunchd(deps: {
   launchctl?: typeof runLaunchctl;
   matches?: typeof launchdJobMatchesPlist;
+  readPlist?: () => string;
 } = {}): void {
   const run = deps.launchctl ?? runLaunchctl;
   const p = plistPath();
@@ -778,16 +790,24 @@ export function startLaunchd(deps: {
   // already be bootstrapped from THIS plist, which is a no-op rather than an error.
   // `install` can assume a stale job (it just rewrote the plist); `start` cannot, and
   // throwing here would break `ocx service start` on every healthy service.
+  // A live job can outlast its deleted or unreadable plist. Only a readable
+  // definition can justify the no-op; use the same snapshot for port parsing.
+  let plist: string | null;
+  try { plist = (deps.readPlist ?? (() => readFileSync(p, "utf8")))(); }
+  catch { plist = null; }
+  // Match the same launchd-only port choice as probeLaunchdLoadState above.
   const live = (deps.matches ?? launchdJobMatchesPlist)(
-    expectedLaunchdCommand(installedServiceListenPort()),
+    expectedLaunchdCommand(launchdListenPort({ readPlist: () => plist ?? "" }) ?? resolveServiceListenPort()),
   );
-  if (live.loaded && live.matchesPlist) {
+  if (plist !== null && live.loaded && live.matchesPlist) {
     console.log("ℹ️  service was already loaded from the current plist; nothing to do.");
     return;
   }
   throw new Error(
     `launchctl could not load ${p}: ${loaded.stderr || "load reported failure"}\n`
-    + (live.loaded
+    + (plist === null
+      ? "The service plist is missing or unreadable. Run 'ocx service repair' to restore it."
+      : live.loaded
       ? `launchd is running an OLDER plist. Fix:\n  launchctl bootout ${launchdGuiDomain()}/${LABEL}\n  ocx service repair`
       : "The job is not loaded. Run 'ocx service repair' to reload it."),
   );

package/src/service/logging.ts

@@ -1,24 +1,81 @@
-import { closeSync, fstatSync, ftruncateSync, openSync, readSync, renameSync, writeSync } from "node:fs";
+import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, openSync, readSync, realpathSync, renameSync, statSync, writeSync, type BigIntStats } from "node:fs";
 import { formatWithOptions } from "node:util";
-import { dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 export const SERVICE_LOG_MAX_BYTES = 20 * 1024 * 1024;
 export const SERVICE_LOG_CHECK_INTERVAL_MS = 60_000;
 
+function regularLeaf(path: string): BigIntStats | undefined {
+  try {
+    const info = lstatSync(path, { bigint: true });
+    if (!info.isFile() || info.nlink !== 1n || info.ino === 0n) throw new Error("Unsafe service log leaf");
+    return info;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function sameFile(left: BigIntStats | undefined, right: BigIntStats | undefined): boolean {
+  return left !== undefined && right !== undefined && left.dev === right.dev && left.ino === right.ino;
+}
+
+function matchesDescriptor(path: string, fd: number, expected: BigIntStats): boolean {
+  const info = fstatSync(fd, { bigint: true });
+  return info.isFile() && info.nlink === 1n && sameFile(expected, info)
+    && sameFile(info, regularLeaf(path));
+}
+
 /** Preserve the manager's open append descriptor; retain at most two bounded archives. */
-export function rotateServiceLog(path: string, maxBytes = SERVICE_LOG_MAX_BYTES): boolean {
+export function rotateServiceLog(requestedPath: string, maxBytes = SERVICE_LOG_MAX_BYTES): boolean {
   let source: number | undefined;
   let archive: number | undefined;
   try {
     if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) return false;
-    source = openSync(path, "r+");
-    const size = fstatSync(source).size;
-    if (size <= maxBytes) return false;
-    try { renameSync(`${path}.1`, `${path}.2`); } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") return false;
+    // Resolve only the parent: exclusive creation through a Windows junction
+    // can report EEXIST for a missing leaf. Never resolve away a leaf symlink.
+    const parent = dirname(requestedPath);
+    const directory = statSync(parent, { bigint: true });
+    if (!directory.isDirectory() || directory.ino === 0n) return false;
+    const canonicalParent = realpathSync(parent);
+    const path = join(canonicalParent, basename(requestedPath));
+    const sameDirectory = () => {
+      const alias = statSync(parent, { bigint: true });
+      const canonical = statSync(canonicalParent, { bigint: true });
+      return alias.isDirectory() && canonical.isDirectory()
+        && sameFile(directory, alias) && sameFile(directory, canonical);
+    };
+    const matches = (suffix: string, fd: number, expected: BigIntStats) => sameDirectory()
+      && matchesDescriptor(`${path}${suffix}`, fd, expected)
+      && matchesDescriptor(`${requestedPath}${suffix}`, fd, expected);
+    if (!sameDirectory()) return false;
+    const original = regularLeaf(requestedPath);
+    if (!original) return false;
+    // Windows does not expose O_NOFOLLOW: descriptor/leaf identity checks still
+    // apply there. Do not reject legitimate junctions in the home path.
+    const guardedFlags = process.platform === "win32" ? 0 : constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    source = openSync(path, constants.O_RDWR | guardedFlags);
+    if (!matches("", source, original)) return false;
+    const size = Number(fstatSync(source, { bigint: true }).size);
+    if (!Number.isSafeInteger(size) || size <= maxBytes) return false;
+    const previous = regularLeaf(`${path}.1`);
+    const oldest = regularLeaf(`${path}.2`);
+    if (!matches("", source, original)) return false;
+    if (previous) {
+      if (!sameFile(previous, regularLeaf(`${path}.1`))) return false;
+      const currentOldest = regularLeaf(`${path}.2`);
+      if (oldest ? !sameFile(oldest, currentOldest) : currentOldest !== undefined) return false;
+      if (!sameDirectory()) return false;
+      renameSync(`${path}.1`, `${path}.2`);
+      if (!sameFile(previous, regularLeaf(`${path}.2`))) return false;
     }
-    archive = openSync(`${path}.1`, "w", 0o600);
+    // Never truncate an existing archive, even if another rotation or a path
+    // replacement wins the gap after rename. Failure leaves the source intact.
+    if (!sameDirectory()) return false;
+    archive = openSync(`${path}.1`, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | guardedFlags, 0o600);
+    const created = fstatSync(archive, { bigint: true });
+    if (!matches(".1", archive, created)) return false;
     // A legacy unbounded file may be huge. Copy only its newest cap-sized tail,
     // using fixed memory, before truncating the original inode.
     const buffer = Buffer.alloc(Math.min(64 * 1024, maxBytes));
@@ -28,12 +85,18 @@ export function rotateServiceLog(path: string, maxBytes = SERVICE_LOG_MAX_BYTES)
       if (read === 0) return false;
       let written = 0;
       while (written < read) {
+        if (!matches(".1", archive, created)) return false;
         const count = writeSync(archive, buffer, written, read - written);
         if (count === 0) return false;
         written += count;
       }
       position += read;
     }
+    fsyncSync(archive);
+    // Revalidate both names and open objects at the destructive boundary. These
+    // checks detect observed replacement; they are not an atomic namespace lock.
+    if (!matches(".1", archive, created)
+      || !matches("", source, original)) return false;
     ftruncateSync(source, 0);
     return true;
   } catch {

package/src/service/repair.ts

@@ -6,7 +6,8 @@ import { randomUUID } from "node:crypto";
 import { defaultWinswEntry, installWinswService } from "../lib/winsw";
 import { resolveWindowsTaskDiagnosticUserId, diagnoseService } from "./diagnostics";
 import type { ServiceDiagnostic } from "./diagnostics";
-import { assertServiceEnvironmentMatchesInstall, assertServiceAuthEnvironment } from "./guards";
+import { assertServiceAuthEnvironment } from "./auth-preflight";
+import { assertServiceEnvironmentMatchesInstall } from "./guards";
 import { installLaunchd, restartLaunchdJob } from "./launchd";
 import type { LaunchdInstallOutcome } from "./launchd";
 import { TASK, writeServiceInstallState, serviceSourceDir, resolveServiceOwnership, serviceLauncherPathDiagnostic } from "./state";

package/src/service/state.ts

@@ -172,20 +172,19 @@ function defaultOpenCodexHome(): string {
 }
 
 export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string[] {
-  return serviceStateFilesFor(opencodexHome, defaultOpenCodexHome());
+  // Bun caches the startup home: parallel workers inherit the wrapper's HOME even
+  // after the preload gives each one a sandbox. Tests must not share that mirror,
+  // including serial cases that select different OPENCODEX_HOME fixtures.
+  return serviceStateFilesFor(opencodexHome, isTestHomeGuardArmed() ? opencodexHome : defaultOpenCodexHome());
 }
 
 export function serviceStatePaths(): string[] {
   const paths = serviceStatePathsForOpenCodexHome(currentOpenCodexHome());
   if (!isTestHomeGuardArmed()) return paths;
   /*
-   * Under an armed test process the legacy default-home entry IS the developer's real
-   * `~/.opencodex/service-state.json`. It is there so an install made before
-   * OPENCODEX_HOME was set can still be found, but it means a test whose OPENCODEX_HOME
-   * points at a sandbox still writes their live install state — observed while building
-   * the launchd repair coverage: one case replaced the real record's codexHome and
-   * opencodexHome with temp-directory paths. Drop it rather than deny the write, so the
-   * sandbox path keeps working and the real one is simply not in the list.
+   * The test resolver omits the legacy mirror; still reject an explicit or fallback
+   * OPENCODEX_HOME that names the developer's real home. A missing fixture pin must
+   * never allow a test to read or replace their live service installation.
    *
    * The predicate is the guard's own, not a local `resolve()` compare: the guard
    * canonicalizes through `realpath`, and on macOS a sandbox under `/var/folders/...`

package/src/service/systemd.ts

@@ -8,7 +8,7 @@ import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime, type D
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { systemdProperty } from "../service-manager-probe";
 import { writeServiceApiTokenFile, sh } from "./guards";
-import { shellQuote, buildServiceShellCommand, buildServiceLauncherShellCommand, resolvedProxyEnv } from "./health";
+import { shellQuote, buildServiceShellCommand, buildServiceLauncherShellCommand, resolvedProxyEnv } from "./definition";
 import type { ServiceInstallCleanupOps } from "./orchestration";
 import { SERVICE_MANAGED_ENV, TASK, cliEntry, filterTransientServicePath, stableLauncherEntry, logPath, serviceStatePath, currentCodexSqliteHomeAbsolute, writeServiceInstallState } from "./state";
 import { writeServiceDefinitionFile } from "./windows-ops";

package/src/service/windows-guarded-manager.ts

@@ -29,7 +29,8 @@ import { cachedCurrentWindowsIdentity, resolveCurrentWindowsPrincipal, WINDOWS_P
 import { statusWinswRaw, winswExePath, WINSW_SERVICE_ID, type WinswStatus } from "../lib/winsw";
 import type { GuardedManagerStopped, GuardedManagerTarget } from "./guarded-manager-target";
 import { TASK, windowsLauncherVbsPath, windowsServiceScriptPath } from "./state";
-import { probeWindowsSchedulerTask, querySchtasks, windowsWscript, type WindowsSchedulerTaskProbe } from "./windows-scheduler";
+import { probeWindowsSchedulerTask, querySchtasks, type WindowsSchedulerTaskProbe } from "./windows-scheduler";
+import { windowsWscript } from "./windows-wscript";
 import { windowsTaskRegistrationHealthy, windowsTaskRegistrationRefreshableLegacy } from "./windows-taskxml";
 
 /** Runtime table of one Win32 process; a null parent means the chain is unreadable. */

package/src/service/windows-ops.ts

@@ -5,7 +5,7 @@ import { winswXmlPath } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
 import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
 import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
-import { parseBakedListenPort } from "./health";
+import { parseBakedListenPort } from "./definition";
 import { windowsServiceScriptPath } from "./state";
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, rmdirSync, unlinkSync } from "node:fs";

package/src/service/windows-scheduler.ts

@@ -1,7 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { ELEVATION_REQUEST_TIMEOUT_MS, OCX_ELEVATED_PROTOCOL_FAILED, raceWithTimeout, resolveTrustedWindowsSchtasksExe, startElevatedSchtasksCreateAndRun, runWindowsElevated, toWindowsSchtasksError, WindowsElevationError, type ElevatedSchedulerOutcome, type ElevatedSchtasksCreateAndRunExecution, type ElevatedSchtasksCreateAndRunResult } from "../lib/windows-elevation";
 import { statusWinswRaw } from "../lib/winsw";
@@ -10,9 +9,10 @@ import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { TASK, windowsServiceScriptPath, windowsLauncherVbsPath, windowsTaskXmlPath, writeServiceInstallState } from "./state";
 import { buildWindowsSchtasksCreateArgs, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
 import type { ExpectedWindowsTaskUserId } from "./windows-taskxml";
-import { win32 } from "node:path";
 import { WINSW_SERVICE_ID } from "../lib/winsw";
 
+export { windowsWscript } from "./windows-wscript";
+
 /**
  * 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
@@ -69,11 +69,6 @@ function windowsSchtasks(): string {
   return resolveTrustedWindowsSchtasksExe();
 }
 
-export function windowsWscript(): string {
-  const candidate = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "wscript.exe");
-  return existsSync(candidate) ? candidate : "wscript.exe";
-}
-
 let querySchtasksForTests: ((args: string[]) => string) | null = null;
 
 export function querySchtasks(args: string[]): string {

package/src/service/windows-taskxml.ts

@@ -1,14 +1,14 @@
 import { WINDOWS_WRAPPER_PROTOCOL_ENV, WINDOWS_WRAPPER_STAY_OUT_EXIT_CODE } from "./windows-wrapper-exit";
 import { readFileSync } from "node:fs";
 import { TASK, windowsServiceScriptPath, windowsLauncherVbsPath, windowsTaskXmlPath } from "./state";
-import { windowsWscript } from "./windows-scheduler";
+import { windowsWscript } from "./windows-wscript";
 import { join } from "node:path";
 import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV } from "../lib/bun-runtime";
 import { REAL_BUN_MIN_BYTES } from "../lib/bun-binary-validator.mjs";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from "../lib/win-paths";
 import { cachedCurrentWindowsIdentity, resolveCurrentWindowsPrincipal, WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS } from "../lib/windows-user-principal";
-import { resolveServiceListenPort, resolvedProxyEnv } from "./health";
+import { resolveServiceListenPort, resolvedProxyEnv } from "./definition";
 import { cliEntry, filterTransientServicePath, serviceLogPath, currentCodexSqliteHomeAbsolute } from "./state";
 
 function windowsBatchValue(value: string): string {

package/src/service/windows-wscript.ts

@@ -0,0 +1,14 @@
+/**
+ * The `wscript.exe` the Task Scheduler XML must name.
+ *
+ * Leaf module on purpose: `windows-taskxml.ts` needs it to render the task document,
+ * and taking it from `windows-scheduler.ts` made the two one cyclic component.
+ * `windows-scheduler` owns the schtasks process surface, not this one path lookup.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function windowsWscript(): string {
+  const candidate = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "wscript.exe");
+  return existsSync(candidate) ? candidate : "wscript.exe";
+}

package/src/service.ts

@@ -13,8 +13,10 @@ export { acquireOwnershipMutationLease, withOwnershipMutationLease } from "./ser
 export type { ManagingCliRole, ManagingCliObservation, RegisteredManagingCliInvocation, ServiceTakeoverCompatibilityInput, ServiceTakeoverCompatibility } from "./service/ownership-compatibility";
 export { registeredManagingCliInvocation, assessServiceTakeoverCompatibility, sameServiceTakeoverCompatibility } from "./service/ownership-compatibility";
 export type { ServiceApiTokenOrigin, ProvisionedServiceApiToken } from "./service/guards";
-export { ServiceOwnershipError, isServiceOwnershipError, serviceEnvironmentOwnedHere, assertServiceEnvironmentMatchesInstall, serviceRetryCommand, assertNotAdminToken, assertServiceAuthEnvironment, writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./service/guards";
-export { resolveServiceListenPort, installedServiceListenPort, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, confirmServiceServing, reportServiceServing, resolvedProxyEnv } from "./service/health";
+export { ServiceOwnershipError, isServiceOwnershipError, serviceEnvironmentOwnedHere, assertServiceEnvironmentMatchesInstall, assertNotAdminToken, writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./service/guards";
+export { serviceRetryCommand, assertServiceAuthEnvironment } from "./service/auth-preflight";
+export { resolveServiceListenPort, resolvedProxyEnv } from "./service/definition";
+export { installedServiceListenPort, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, confirmServiceServing, reportServiceServing } from "./service/health";
 export type { LaunchdLoadState, LaunchdLoadProbe, LaunchdInstallOutcome } from "./service/launchd";
 export { buildPlist, reusePreviousPlistPathVariable, expectedLaunchdCommand, launchdListenPort, runLaunchctl, launchctlLoadFailed, launchdJobMatchesPlist, launchdEvictionTargets, probeLaunchdLoadState, installLaunchd, restartLaunchdJob, startLaunchd } from "./service/launchd";
 export { systemdListenPort, buildUnit, systemdNeedsDaemonReload, uninstallSystemd, systemdServiceInstallCleanupOps } from "./service/systemd";

package/src/sidecar/auth.ts

@@ -134,6 +134,8 @@ function findAnthropicAuthProvider(
     // its token path and the token guardian refuse an unmarked row of that name, so offering such a
     // custom row here would advertise credentials no helper executor will spend.
     if (providerName === "anthropic2") continue;
+    // The DSH account token is pinned to its own adapter and DeepSeek host; no helper may spend it.
+    if (providerName === "dsh-account") continue;
     if (provider.disabled === true) continue;
     if (provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
     const set = getAccountSet(providerName);