@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/server/restart-replacement.ts

@@ -0,0 +1,382 @@
+/**
+ * Spawning the detached `ocx start` that replaces this process: the parent side of a restart handoff.
+ *
+ * Shared by the dashboard drain-and-restart (`src/server/management/system-restart.ts`, which is also
+ * how a join into a Child restarts) and the client runtime's standalone recycle
+ * (`src/client/runtime.ts`). Deliberately lean: the client runtime loads it only at recycle time and
+ * must not pull the server lifecycle graph in with it.
+ *
+ * Every replacement carries `OCX_RESTART_PARENT_PID`, so a replacement that still finds this process
+ * answering on the port waits for it instead of refusing it (`src/cli/restart-handoff.ts`).
+ *
+ * A handoff that waits for health (the drain completed) retries a replacement that exits before it
+ * answers, at most {@link REPLACEMENT_EARLY_EXIT_RETRIES} more times inside the one readiness
+ * budget: the port a restart hands over can still be draining, and one refused start used to end the
+ * whole handoff. A parent-exit handoff resolves once the child spawned and is never retried; the
+ * replacement's own parent wait and port reclaim cover it. A spawn error is not retried; it does not
+ * change between attempts.
+ *
+ * The replacement's stdout and stderr go to `<configDir>/restart-handoff.log` instead of nowhere, so
+ * a switch that failed can be diagnosed. The file is private (0600, created in the private config
+ * directory, never opened through a symlink) and bounded at {@link RESTART_HANDOFF_LOG_MAX_BYTES} on
+ * both sides: a handoff empties it before it opens it, and the replacement, which keeps writing to
+ * it for its whole life, checks it once a minute ({@link RESTART_HANDOFF_LOG_ENV},
+ * {@link armRestartHandoffLogCap}). The parent writes only timestamps, pids, ports, attempt counts,
+ * exit codes and errno codes, never an environment value; the replacement writes what an `ocx start`
+ * prints to a terminal. A log that cannot be opened never blocks the handoff: the output is
+ * discarded as before.
+ */
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { closeSync, constants, fchmodSync, fstatSync, ftruncateSync, lstatSync, openSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { REPLACEMENT_READY_TIMEOUT_MS, withRestartParentMarker } from "../lib/system-restart-contract";
+import { findLiveProxy } from "./proxy-liveness";
+
+export const RESTART_HANDOFF_LOG_FILENAME = "restart-handoff.log";
+export const RESTART_HANDOFF_LOG_MAX_BYTES = 256 * 1024;
+/**
+ * Set to `1` on a replacement whose stdout and stderr are the handoff log. `handleStart` consumes it
+ * and arms {@link armRestartHandoffLogCap}, so the file stays bounded after the parent that opened it
+ * is gone. A hand-set value only makes that start cap the private handoff log.
+ */
+export const RESTART_HANDOFF_LOG_ENV = "OCX_RESTART_HANDOFF_LOG";
+/** How often a replacement writing into the handoff log checks its size: one lstat per tick. */
+export const RESTART_HANDOFF_LOG_CHECK_MS = 60_000;
+/** Respawns after an early exit, on top of the first attempt. */
+export const REPLACEMENT_EARLY_EXIT_RETRIES = 2;
+const REPLACEMENT_RETRY_DELAY_MS = 1_000;
+const REPLACEMENT_READY_POLL_MS = 150;
+
+export interface ReplacementReadinessIo {
+  findLive?: typeof findLiveProxy;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  /** One absolute deadline for every attempt of a handoff; defaults to now + the readiness budget. */
+  deadlineAt?: number;
+  /** Stops polling once the attempt it serves has already settled (the replacement exited). */
+  cancelled?: () => boolean;
+}
+
+export async function waitForReplacementReady(
+  expectedPid: number | undefined,
+  parentPid: number,
+  expectedPort: number | undefined,
+  io: ReplacementReadinessIo = {},
+): Promise<boolean> {
+  const findLive = io.findLive ?? findLiveProxy;
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const deadline = io.deadlineAt ?? now() + REPLACEMENT_READY_TIMEOUT_MS;
+  while (now() < deadline) {
+    if (io.cancelled?.()) return false;
+    try {
+      const live = await findLive({
+        deadlineAt: deadline,
+        nowFn: now,
+        sleepFn: sleep,
+      });
+      // A probe that began within budget can still return after it. Never accept
+      // delayed health as proof once the shared absolute handoff budget expired.
+      if (now() >= deadline) return false;
+      if (
+        live
+        && live.pid !== null
+        && live.pid !== parentPid
+        && (expectedPid === undefined || live.pid === expectedPid)
+        && (expectedPort === undefined || live.port === expectedPort)
+      ) {
+        return true;
+      }
+    } catch {
+      // A not-yet-bound replacement is indistinguishable from a transient
+      // liveness failure here; keep polling inside the one bounded window.
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) break;
+    await sleep(Math.min(REPLACEMENT_READY_POLL_MS, remainingMs));
+  }
+  return false;
+}
+
+export interface RestartHandoffLog {
+  readonly fd: number;
+  note(line: string): void;
+  close(): void;
+}
+
+export function restartHandoffLogPath(configDir: string = getConfigDir()): string {
+  return join(configDir, RESTART_HANDOFF_LOG_FILENAME);
+}
+
+/**
+ * Empty the handoff log once it has reached the cap; below the cap this is one lstat. The truncation
+ * goes through a fresh non-append descriptor, never through a symlink, so it also works where an
+ * append handle cannot truncate (Windows). Every writer's append descriptor carries on at the new end.
+ * Returns true when it emptied the file.
+ */
+export function emptyRestartHandoffLogIfFull(path: string, now: () => number = Date.now): boolean {
+  let fd: number | undefined;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size < RESTART_HANDOFF_LOG_MAX_BYTES) return false;
+    fd = openSync(path, constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0));
+    if (!fstatSync(fd).isFile()) return false;
+    ftruncateSync(fd, 0);
+    writeSync(fd, `[${new Date(now()).toISOString()}] log emptied at the ${RESTART_HANDOFF_LOG_MAX_BYTES / 1024} KiB cap\n`);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+  }
+}
+
+/**
+ * Open the handoff log for appending: private, never through a symlink, and emptied first when it
+ * has reached the cap. Returns null when it cannot be opened safely.
+ */
+export function openRestartHandoffLog(path: string, now: () => number = Date.now): RestartHandoffLog | null {
+  emptyRestartHandoffLogIfFull(path, now);
+  let fd: number | undefined;
+  try {
+    // O_NOFOLLOW turns a planted symlink into an open error instead of a write somewhere else.
+    const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0);
+    fd = openSync(path, flags, 0o600);
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) {
+      closeSync(fd);
+      return null;
+    }
+    if (process.platform !== "win32") fchmodSync(fd, 0o600);
+    const handle = fd;
+    return {
+      fd: handle,
+      note(line: string) {
+        try { writeSync(handle, `[${new Date(now()).toISOString()}] ${line}\n`); } catch { /* diagnostics only */ }
+      },
+      close() {
+        try { closeSync(handle); } catch { /* already closed */ }
+      },
+    };
+  } catch {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+    return null;
+  }
+}
+
+export interface RestartHandoffLogCapIo {
+  /** The log to bound; default: the config-dir handoff log. */
+  path?: string;
+  intervalMs?: number;
+}
+
+/**
+ * The replacement side of the log bound. A replacement whose parent sent its output to the handoff
+ * log keeps writing there for its whole life, long after that parent exited, so it checks the file
+ * itself from one low-frequency, unref'd timer and empties it at the cap. Consumes
+ * {@link RESTART_HANDOFF_LOG_ENV} so no later child inherits it; a start without the flag (every
+ * ordinary start) arms nothing. Returns a stop function, or null when nothing was armed.
+ */
+export function armRestartHandoffLogCap(
+  env: Record<string, string | undefined>,
+  io: RestartHandoffLogCapIo = {},
+): (() => void) | null {
+  const flagged = env[RESTART_HANDOFF_LOG_ENV] === "1";
+  delete env[RESTART_HANDOFF_LOG_ENV];
+  if (!flagged) return null;
+  const path = io.path ?? restartHandoffLogPath();
+  const timer = setInterval(() => { emptyRestartHandoffLogIfFull(path); }, io.intervalMs ?? RESTART_HANDOFF_LOG_CHECK_MS);
+  timer.unref?.();
+  return () => { clearInterval(timer); };
+}
+
+function openDefaultRestartHandoffLog(now: () => number): RestartHandoffLog | null {
+  const configDir = getConfigDir();
+  const path = restartHandoffLogPath(configDir);
+  // Owned like crash.log, so uninstall removes it with the rest of the config directory.
+  try { recordOwnedConfigPath(configDir, path); } catch { /* the log is optional */ }
+  return openRestartHandoffLog(path, now);
+}
+
+export type ReplacementSpawn = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+
+export interface ReplacementStartIo extends ReplacementReadinessIo {
+  spawnChild?: ReplacementSpawn;
+  /** The handoff log file; `null` discards the replacement's output. Default: the config-dir log. */
+  logPath?: string | null;
+  parentPid?: number;
+  retryDelayMs?: number;
+}
+
+export interface ReplacementStartRequest {
+  /** The port the replacement must bind; anything that is not a TCP port starts it unpinned. */
+  port?: number;
+  /**
+   * Wait until the replacement answers before resolving, retrying an early exit. Without it the
+   * promise resolves once the child spawned, so the parent can exit and release what the
+   * replacement is waiting for.
+   */
+  waitForHealth: boolean;
+  /** The replacement's environment, already prepared by the caller; the parent marker is added here. */
+  env: NodeJS.ProcessEnv;
+}
+
+type AttemptOutcome =
+  | { kind: "spawned" | "ready" | "not-ready"; pid: number | undefined }
+  | { kind: "early-exit"; pid: number | undefined; code: number | null; signal: NodeJS.Signals | null };
+
+function pinnedPort(port: number | undefined): number | undefined {
+  return typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535
+    ? Math.trunc(port)
+    : undefined;
+}
+
+function handoffError(code: string): NodeJS.ErrnoException {
+  const error = new Error(code) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+/** Stable, path-free label for a spawn failure (an errno message can carry the OS username). */
+function failureLabel(err: unknown): string {
+  if (err && typeof err === "object" && "code" in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (typeof code === "string" && /^[A-Za-z0-9_]{1,64}$/.test(code)) return code;
+  }
+  return "spawn_failed";
+}
+
+function runReplacementAttempt(
+  launchArgs: string[],
+  env: NodeJS.ProcessEnv,
+  logFd: number | undefined,
+  waitForHealth: boolean,
+  expectedPort: number | undefined,
+  parentPid: number,
+  io: ReplacementStartIo,
+): Promise<AttemptOutcome> {
+  return new Promise<AttemptOutcome>((resolve, reject) => {
+    let child: ChildProcess;
+    try {
+      const output = logFd ?? "ignore";
+      const options: SpawnOptions = {
+        detached: true,
+        stdio: ["ignore", output, output],
+        windowsHide: true,
+        env: withProcessRuntimeProvenance(env),
+      };
+      child = io.spawnChild
+        ? io.spawnChild(process.execPath, launchArgs, options)
+        : spawn(process.execPath, launchArgs, options);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let settled = false;
+    const cleanup = () => {
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.off("spawn", onSpawn);
+    };
+    const settle = (outcome: AttemptOutcome | { error: unknown }) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if ("error" in outcome) {
+        if (child.exitCode === null && child.signalCode === null) {
+          try { child.kill(); } catch { /* best-effort failed-start cleanup */ }
+        }
+        try { child.unref(); } catch { /* best-effort */ }
+        reject(outcome.error);
+        return;
+      }
+      try { child.unref(); } catch { /* best-effort */ }
+      resolve(outcome);
+    };
+    const onError = (err: Error) => { settle({ error: err }); };
+    const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      settle({ kind: "early-exit", pid: child.pid, code, signal });
+    };
+    const onSpawn = () => {
+      if (!waitForHealth) {
+        // The replacement may be waiting for resources only this parent's exit releases.
+        settle({ kind: "spawned", pid: child.pid });
+        return;
+      }
+      void waitForReplacementReady(child.pid, parentPid, expectedPort, { ...io, cancelled: () => settled }).then(
+        // Never kill a live ordinary start at its valid reclaim boundary. Parent exit is the
+        // final resource release the child may still be waiting for.
+        ready => { settle({ kind: ready ? "ready" : "not-ready", pid: child.pid }); },
+        err => { settle({ error: err }); },
+      );
+    };
+    child.once("error", onError);
+    child.once("exit", onExit);
+    child.once("spawn", onSpawn);
+  });
+}
+
+/**
+ * Spawn this process's replacement `ocx start` and, when asked, wait until it answers. Rejects with
+ * the spawn error, or with code `child_exit` once every attempt exited before it was ready.
+ */
+export async function spawnReplacementStart(
+  request: ReplacementStartRequest,
+  io: ReplacementStartIo = {},
+): Promise<void> {
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const parentPid = io.parentPid ?? process.pid;
+  const expectedPort = pinnedPort(request.port);
+  const launchArgs = selfLaunchArgv(expectedPort === undefined ? ["start"] : ["start", "--port", String(expectedPort)]);
+  const deadlineAt = io.deadlineAt ?? now() + REPLACEMENT_READY_TIMEOUT_MS;
+  const attempts = request.waitForHealth ? 1 + REPLACEMENT_EARLY_EXIT_RETRIES : 1;
+  const target = expectedPort === undefined ? "an unpinned port" : `port ${expectedPort}`;
+  const mode = request.waitForHealth ? "waiting for it to answer" : "exiting first";
+  const log = io.logPath === null
+    ? null
+    : io.logPath === undefined ? openDefaultRestartHandoffLog(now) : openRestartHandoffLog(io.logPath, now);
+  const env: NodeJS.ProcessEnv = withRestartParentMarker(request.env, parentPid);
+  // Only a replacement that really writes into the log keeps it bounded after this parent is gone.
+  if (log) env[RESTART_HANDOFF_LOG_ENV] = "1";
+  else delete env[RESTART_HANDOFF_LOG_ENV];
+  try {
+    for (let attempt = 1; ; attempt += 1) {
+      log?.note(`parent pid ${parentPid} starts a replacement on ${target} (attempt ${attempt}/${attempts}, ${mode})`);
+      let outcome: AttemptOutcome;
+      try {
+        outcome = await runReplacementAttempt(
+          launchArgs, env, log?.fd, request.waitForHealth, expectedPort, parentPid, { ...io, deadlineAt },
+        );
+      } catch (error) {
+        log?.note(`replacement spawn failed (${failureLabel(error)})`);
+        throw error;
+      }
+      const pid = outcome.pid ?? "unknown";
+      if (outcome.kind === "early-exit") {
+        log?.note(`replacement pid ${pid} exited before it answered (code ${outcome.code ?? "none"}, signal ${outcome.signal ?? "none"})`);
+        const retryDelayMs = io.retryDelayMs ?? REPLACEMENT_RETRY_DELAY_MS;
+        if (attempt >= attempts || now() + retryDelayMs >= deadlineAt) throw handoffError("child_exit");
+        await sleep(retryDelayMs);
+        continue;
+      }
+      if (outcome.kind === "not-ready") {
+        console.warn("Restart replacement is still starting after the readiness window; handing off to it anyway");
+        log?.note(`replacement pid ${pid} is still starting after the readiness window; handing off anyway`);
+      } else {
+        log?.note(outcome.kind === "ready" ? `replacement pid ${pid} is serving ${target}` : `replacement pid ${pid} started`);
+      }
+      return;
+    }
+  } finally {
+    log?.close();
+  }
+}

package/src/server/startup-health-cache.ts

@@ -38,6 +38,14 @@ export function startupHealthProbeTimeoutMs(): number {
   return PROBE_TIMEOUT_MS;
 }
 let cached: { timestamp: number; value: StartupHealth } | null = null;
+/**
+ * Last completed reading, kept across invalidation. Invalidation only means "no longer
+ * fresh": a settings write clears `cached` so the next fresh read re-probes, but answering
+ * the snapshot with the synthetic not-installed fallback meanwhile turned a healthy service
+ * into `at-risk` on the dashboard until the probe finished (up to 15s on Windows). The
+ * fallback is kept for a process that has never completed a reading.
+ */
+let lastReading: StartupHealth | null = null;
 let inflight: Promise<StartupHealth> | null = null;
 let generation = 0;
 
@@ -64,7 +72,11 @@ export function getStartupHealthSnapshot(
   const now = deps.now ?? Date.now;
   if (cached && now() - cached.timestamp < CACHE_TTL_MS) return cached.value;
   refreshInBackground(config, deps);
-  return cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config);
+  return staleOrFallback(config);
+}
+
+function staleOrFallback(config: Pick<OcxConfig, "codexAutoStart">): StartupHealth {
+  return lastReading ? markStartupHealthDiagnosticStale(lastReading) : conservativeFallback(config);
 }
 
 export function markStartupHealthDiagnosticStale(value: StartupHealth): StartupHealth {
@@ -140,7 +152,7 @@ function runProbe(config: Pick<OcxConfig, "codexAutoStart">): Promise<StartupHea
           } catch { /* scan earlier output; config repair messages may precede JSON */ }
         }
       }
-      resolve(cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config));
+      resolve(staleOrFallback(config));
     });
   });
 }
@@ -156,10 +168,11 @@ function refreshInBackground(
     .then(value => {
       if (startedGeneration === generation) {
         cached = { timestamp: (deps.now ?? Date.now)(), value };
+        if (!value.diagnosticStale) lastReading = value;
       }
       return value;
     })
-    .catch(() => cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config))
+    .catch(() => staleOrFallback(config))
     .finally(() => {
       // An invalidated probe must never clear the newer generation's flight.
       if (inflight === probe) inflight = null;
@@ -189,7 +202,7 @@ export async function getCachedStartupHealth(
         ]));
     if (settled) return settled;
   }
-  return cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config);
+  return staleOrFallback(config);
 }
 
 export function invalidateStartupHealthCache(): void {
@@ -197,3 +210,9 @@ export function invalidateStartupHealthCache(): void {
   cached = null;
   inflight = null;
 }
+
+/** Test-only: also forget the last reading, returning to the never-probed state. */
+export function resetStartupHealthCacheForTests(): void {
+  invalidateStartupHealthCache();
+  lastReading = null;
+}

package/src/server/stop-teardown.ts

@@ -1,5 +1,8 @@
 import type { CodexNativeRestoreResult } from "../codex/inject";
+import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
 import { deferralMatchesReceipt } from "../config/pending-teardown";
+import { isDesktopSupervised } from "../lib/system-restart-contract";
+import type { ManagementPrincipal } from "./management-auth";
 
 /**
  * Shared-teardown decision and execution for `POST /api/stop` (#3008).
@@ -22,7 +25,8 @@ export type StopTeardownIo = {
 export type StopTeardownBody = {
   success: boolean;
   message: string;
-  sharedTeardown: "deferred" | "performed";
+  /** `not-owned`: a sibling instance, whose shared client routing belongs to the live owner. */
+  sharedTeardown: "deferred" | "performed" | "not-owned";
 };
 
 /**
@@ -43,8 +47,38 @@ export function deferralHonored(url: URL, ownsReceipt: (nonce: string | null) =>
   return ownsReceipt(url.searchParams.get("teardownNonce"));
 }
 
+export type StopRefusalBody = { success: false; code: string; message: string };
+
+/**
+ * The dashboard's Stop, refused while the desktop app supervises this process.
+ *
+ * The app starts its runtime again after any exit it did not ask for
+ * (`desktop/src-tauri/src/supervisor.rs`), and a dashboard Stop is not the app asking: the proxy
+ * would restore native Codex and exit, and the app would start it again seconds later and reload
+ * the dashboard. Like the service-manager refusals it is refused before anything changes, and it
+ * names what does stop the proxy: the app's tray Stop proxy, or Quit. Only a dashboard session is
+ * refused. `ocx stop`, which the tray's Stop, Quit and an update's drain all run, authenticates
+ * with the admin token and is unaffected. Read only on this route, never on the request path.
+ */
+export function desktopSupervisedStopRefusal(
+  principal: ManagementPrincipal | null | undefined,
+  supervised: () => boolean = isDesktopSupervised,
+): StopRefusalBody | null {
+  if (principal !== "gui-session" || !supervised()) return null;
+  return {
+    success: false,
+    code: "desktop_supervised",
+    message: "The OpenCodex desktop app runs this proxy and starts it again after it exits, so the dashboard does not stop it. Use Stop proxy in the app's tray menu, or quit the app. Nothing was changed.",
+  };
+}
+
 /** Run (or skip) the shared teardown and describe the outcome truthfully. */
 export async function performStopTeardown(url: URL, io: StopTeardownIo = {}): Promise<StopTeardownBody> {
+  // Before the deferral check: a sibling owns no shared teardown to perform OR to hand over.
+  // Restoring here would replay the live owner's journal and strip its Grok fence.
+  if (siblingOfLivePort() !== null) {
+    return { success: true, message: `Proxy stopping. ${siblingSkipMessage()}`, sharedTeardown: "not-owned" };
+  }
   const ownsReceipt = io.ownsReceipt ?? deferralMatchesReceipt;
   if (deferralHonored(url, ownsReceipt)) {
     // Not "native Codex restored": nothing was restored here, and claiming otherwise

package/src/server/system-env.ts

@@ -11,6 +11,7 @@ import { localAdmissionToken, localInferenceDestination } from "../lib/local-des
 import { probeHostname } from "./proxy-liveness";
 import { providerContextCap } from "../providers/context-cap";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import { siblingOfLivePort } from "../codex/sibling-start";
 export { getShellEnvFilePath, installShellHook, uninstallShellHook, claudeCodeCliInstalled, reconcileShellHook } from "./system-env-shell";
 export type { SystemEnvDeps } from "./system-env-shell";
 import { systemEnvMarkerMode, writeShellEnvFile, removeShellEnvFile } from "./system-env-shell";
@@ -196,6 +197,8 @@ export async function injectSystemEnv(
   config: OcxConfig,
   deps: SystemEnvDeps = {},
 ): Promise<SystemEnvResult> {
+  // The launchd domain is machine-wide; a sibling instance leaves it to the live owner.
+  if (siblingOfLivePort() !== null) return { injected: false, reason: "sibling instance" };
   if (process.platform !== "darwin") return { injected: false, reason: "not macOS" };
   if (config.claudeCode?.enabled === false) return { injected: false, reason: "claude disabled" };
 

package/src/service/windows-taskxml.ts

@@ -1,3 +1,4 @@
+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";
@@ -64,11 +65,13 @@ export function buildWindowsServiceScript(
   const path = process.env.PATH ?? "";
   const lines = [
     "@echo off",
-    "setlocal",
+    "setlocal EnableExtensions DisableDelayedExpansion",
+    'set "ERRORLEVEL="',
     // The wrapper console is hidden by the wscript launcher (window style 0), so switching
     // it to UTF-8 is safe (no leak into user shells) and lets cmd parse UTF-8 remnants.
     "chcp 65001 >nul",
     windowsBatchSet("OCX_SERVICE", "1"),
+    windowsBatchSet(WINDOWS_WRAPPER_PROTOCOL_ENV, "1"),
     windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource),
     windowsBatchSet(BUN_RUNTIME_PATH_ENV, bun, "path"),
     windowsBatchSet("PATH", path, "pathList"),
@@ -110,15 +113,16 @@ export function buildWindowsServiceScript(
     cli ? "  exit /b 3" : null,
     cli ? ")" : null,
     cli ? `"%OCX_BUN%" "%OCX_CLI%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1` : `"%OCX_BUN%" start --port ${port} >>"%OCX_SERVICE_LOG%" 2>&1`,
-    "if %ERRORLEVEL% NEQ 0 (",
-    '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] child exited with code %ERRORLEVEL%; restarting in 5s',
+    // Stop commands kill the wrapper; a zero child exit alone is not a stop request.
+    `if "%ERRORLEVEL%"=="${WINDOWS_WRAPPER_STAY_OUT_EXIT_CODE}" goto stopped`,
+    '>>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] child exited with code %ERRORLEVEL%; restarting in 5s',
     // `timeout` needs console stdin and dies with "Input redirection is not supported"
     // under Task Scheduler, turning the 5s cooldown into a hot restart loop; ping doesn't.
-    "  ping -n 6 127.0.0.1 >nul",
-    "  goto loop",
-    ")",
+    "ping -n 6 127.0.0.1 >nul",
+    "goto loop",
+    ":stopped",
     "endlocal",
-    "goto :eof",
+    "exit /b 0",
     "",
     // #1942/#1849: a power loss mid-swap leaves the live package dir missing/broken and
     // a sibling .ocx-backup-* holding the previous version. This wrapper lives OUTSIDE

package/src/service/windows-wrapper-exit.ts

@@ -0,0 +1,8 @@
+// Only wrappers advertising this protocol understand a nonzero intentional exit.
+export const WINDOWS_WRAPPER_PROTOCOL_ENV = "OCX_WINDOWS_WRAPPER_PROTOCOL";
+export const WINDOWS_WRAPPER_STAY_OUT_EXIT_CODE = 42;
+
+export function serviceStayOutExitCode(env: NodeJS.ProcessEnv = process.env): number {
+  return env.OCX_SERVICE === "1" && env[WINDOWS_WRAPPER_PROTOCOL_ENV] === "1"
+    ? WINDOWS_WRAPPER_STAY_OUT_EXIT_CODE : 0;
+}

package/src/stall-timeout.ts

@@ -1,20 +1,45 @@
+export const DEFAULT_STALL_TIMEOUT_SEC = 300;
+
 /**
- * Bridge upstream stall budget: seconds of silence (no adapter events) before the
- * Responses bridge emits `response.incomplete` / `upstream_stall_timeout`.
+ * How the configured stall budget should be resolved for a request.
  *
- * Raised from 90s so long reasoning + large tool writes are not cut mid-turn.
- * Hung streams still die; they just get a more realistic window.
+ * `localUpstream` marks a request whose upstream is operator-trusted local infrastructure
+ * (loopback / private / `.local` / `.lan` — see src/lib/local-upstream.ts). Such models are often
+ * CPU-bound, and their time-to-first-token or "thinking" phases can go silent for many minutes;
+ * a stall budget there would cut a healthy turn mid-thought. Callers compute the flag with
+ * `isLocalUpstream(destination)` and pass it in.
  */
-export const DEFAULT_STALL_TIMEOUT_SEC = 300;
+export interface StallTimeoutOptions {
+  localUpstream?: boolean;
+}
 
 /**
- * Resolve the effective bridge stall deadline for a turn.
- * - unset / non-finite config → {@link DEFAULT_STALL_TIMEOUT_SEC}
- * - finite config → ceil, minimum 1
+ * Resolve the per-request stall budget in seconds.
+ *
+ * An explicit value always wins: `0` (or any non-positive) disables the budget everywhere, and a
+ * positive value applies verbatim to local and public upstreams alike. Only when the operator
+ * left the budget unset does the destination matter: a local upstream resolves to disabled
+ * (`0`) while a public upstream keeps the {@link DEFAULT_STALL_TIMEOUT_SEC} safety clock.
+ *
+ * Disabling is expressed as `0`, never as a tiny budget: several consumers translate the
+ * seconds into a tick count or a pull deadline, where `0` would otherwise expire on the first
+ * beat and kill a healthy stream in ~2s. Consumers that kill on the budget must therefore gate
+ * on `resolveStallTimeoutSec(...) > 0` (see src/bridge/sse.ts, src/server/chat-native-sse.ts).
  */
-export function resolveStallTimeoutSec(configuredSec: number | undefined): number {
+export function resolveStallTimeoutSec(configuredSec: number | undefined, options: StallTimeoutOptions = {}): number {
+  const { localUpstream = false } = options;
   if (typeof configuredSec === "number" && Number.isFinite(configuredSec)) {
+    if (configuredSec <= 0) return 0;
     return Math.max(1, Math.ceil(configuredSec));
   }
-  return DEFAULT_STALL_TIMEOUT_SEC;
+  return localUpstream ? 0 : DEFAULT_STALL_TIMEOUT_SEC;
+}
+
+/**
+ * The same resolution as {@link resolveStallTimeoutSec}, in milliseconds, for consumers that
+ * deadline against `performance.now()`. `0` is a stable "disabled" sentinel the inactivity
+ * guards honor (they arm no clock for a non-positive budget).
+ */
+export function resolveStallTimeoutMs(configuredSec: number | undefined, options: StallTimeoutOptions = {}): number {
+  return resolveStallTimeoutSec(configuredSec, options) * 1_000;
 }

package/src/storage/policy-job.ts

@@ -8,6 +8,7 @@
 import type { CleanupMode, CleanupResult } from "./cleanup";
 import { spawnWorker } from "../lib/worker-embed";
 import { resolveCodexHomeDir } from "../codex/home";
+import { siblingOfLivePort } from "../codex/sibling-start";
 import {
   tryBeginStorageMutation,
 } from "./storage-mutation-coordinator";
@@ -452,11 +453,14 @@ export function requestStorageCleanupPolicyRun(
 /**
  * Fire-and-forget entry for startup / schedule ticks.
  * Skips the single-flight slot when disabled or not due so manual runs stay free.
+ * A sibling instance never runs one: the archived sessions belong to the shared CODEX_HOME the
+ * live owner serves (`src/codex/sibling-start.ts`), and the manual run route is refused there too.
  */
 export function maybeRequestStorageCleanupPolicyRun(
   reason: PolicyRunReason,
   opts?: Omit<RequestPolicyRunOptions, "reason">,
 ): void {
+  if (siblingOfLivePort() !== null) return;
   try {
     const policy = readStorageCleanupPolicyFromConfig();
     if (!policy.enabled) return;