@iislee/opencodex 2.11.0 → 2.35.0

package/src/server/management/storage-log-guard-routes.ts

@@ -0,0 +1,186 @@
+import { resolveCodexHomeDir } from "../../codex/home";
+import {
+  compactCodexLogs,
+  type CodexLogGuardCompactionResult,
+} from "../../codex/log-guard/maintenance";
+import {
+  getCodexLogGuardProtectionStatus,
+  protectCodexLogs,
+  repairCodexLogGuardProtection,
+  unprotectCodexLogs,
+  type CodexLogGuardMutationResult,
+  type CodexLogGuardStatus,
+} from "../../codex/log-guard/protection";
+import { scanStorage } from "../../storage/scanner";
+import { jsonResponse } from "../auth-cors";
+import {
+  managementBodyTooLargeResponse,
+  readManagementJsonBody,
+} from "./body";
+import type { ManagementContext } from "./context";
+
+const INSPECTION_FAILED_MESSAGE = "Codex log inspection failed";
+
+function inspectionUnavailable(report: CodexLogGuardStatus): boolean {
+  return report.schema.state === "unavailable";
+}
+
+function mutationStatus(result: CodexLogGuardMutationResult): number {
+  if (result.ok) return 200;
+  switch (result.error) {
+    case "process_enumeration_failed":
+      return 503;
+    case "codex_running":
+    case "busy":
+    case "unsupported_schema":
+    case "trigger_collision":
+    case "unsafe_path":
+      return 409;
+    case "database_error":
+    case "config_write_failed":
+      return 500;
+  }
+}
+
+function compactStatus(result: CodexLogGuardCompactionResult): number {
+  if (result.ok) return 200;
+  switch (result.error) {
+    case "process_enumeration_failed":
+      return 503;
+    case "codex_running":
+    case "busy":
+    case "unsupported_schema":
+    case "auto_vacuum_not_incremental":
+    case "unsafe_path":
+    case "integrity_check_failed":
+      return 409;
+    case "database_error":
+      return 500;
+  }
+}
+
+function mutationResponse(
+  result: CodexLogGuardMutationResult,
+  ctx: ManagementContext,
+): Response {
+  return result.ok
+    ? jsonResponse(result.status, 200, ctx.req, ctx.config)
+    : jsonResponse({ error: result.error }, mutationStatus(result), ctx.req, ctx.config);
+}
+
+function compactResponse(
+  result: CodexLogGuardCompactionResult,
+  ctx: ManagementContext,
+): Response {
+  if (result.ok) {
+    return jsonResponse({ report: result.report }, 200, ctx.req, ctx.config);
+  }
+  return jsonResponse(
+    result.error === "integrity_check_failed"
+      ? { error: result.error, phase: result.phase }
+      : { error: result.error },
+    compactStatus(result),
+    ctx.req,
+    ctx.config,
+  );
+}
+
+async function readProtectMode(ctx: ManagementContext): Promise<"compat" | "quiet" | Response> {
+  let body: unknown;
+  try {
+    body = await readManagementJsonBody(ctx.req);
+  } catch (error) {
+    const tooLarge = managementBodyTooLargeResponse(error, ctx.req, ctx.config);
+    if (tooLarge) return tooLarge;
+    return jsonResponse({ error: "invalid_request" }, 400, ctx.req, ctx.config);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return jsonResponse({ error: "invalid_request" }, 400, ctx.req, ctx.config);
+  }
+  const mode = (body as Record<string, unknown>).mode;
+  if (mode !== "compat" && mode !== "quiet") {
+    return jsonResponse({ error: "invalid_mode" }, 400, ctx.req, ctx.config);
+  }
+  return mode;
+}
+
+/** Codex Log Guard diagnostics plus explicit protection and maintenance mutations. */
+export async function handleStorageLogGuardRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config, deps } = ctx;
+  const protectionDeps = deps.codexLogGuardProtectionDeps;
+
+  if (url.pathname === "/api/storage/codex-logs") {
+    if (req.method !== "GET") return null;
+    try {
+      const report = getCodexLogGuardProtectionStatus(protectionDeps);
+      if (inspectionUnavailable(report)) {
+        return jsonResponse({ error: "inspect_failed", message: INSPECTION_FAILED_MESSAGE }, 500, req, config);
+      }
+      return jsonResponse(report, 200, req, config);
+    } catch {
+      return jsonResponse({
+        error: "inspect_failed",
+        message: INSPECTION_FAILED_MESSAGE,
+      }, 500, req, config);
+    }
+  }
+
+  if (url.pathname === "/api/storage/codex-logs/protect") {
+    if (req.method !== "POST") return null;
+    const mode = await readProtectMode(ctx);
+    if (mode instanceof Response) return mode;
+    return mutationResponse(protectCodexLogs(mode, protectionDeps), ctx);
+  }
+
+  if (url.pathname === "/api/storage/codex-logs/unprotect") {
+    if (req.method !== "POST") return null;
+    return mutationResponse(unprotectCodexLogs(protectionDeps), ctx);
+  }
+
+  if (url.pathname === "/api/storage/codex-logs/repair") {
+    if (req.method !== "POST") return null;
+    return mutationResponse(repairCodexLogGuardProtection(protectionDeps), ctx);
+  }
+
+  if (url.pathname === "/api/storage/codex-logs/compact") {
+    if (req.method !== "POST") return null;
+    return compactResponse(compactCodexLogs(deps.codexLogGuardMaintenanceDeps), ctx);
+  }
+
+  if (url.pathname !== "/api/storage" || req.method !== "GET") return null;
+
+  // Keep the existing CODEX_HOME scan as the primary storage contract. The Log Guard
+  // report is attached separately so an external sqlite_home is visible without being
+  // silently folded into CODEX_HOME totals.
+  let storage;
+  try {
+    storage = scanStorage();
+  } catch {
+    const fallback = {
+      codexHome: resolveCodexHomeDir(),
+      generatedAt: Date.now(),
+      total: { bytes: 0, fileCount: 0 },
+      buckets: [],
+      error: "scan_failed",
+    };
+    try {
+      const report = getCodexLogGuardProtectionStatus(protectionDeps);
+      return inspectionUnavailable(report)
+        ? jsonResponse({ ...fallback, codexLogs: null, codexLogsError: "inspect_failed" }, 200, req, config)
+        : jsonResponse({ ...fallback, codexLogs: report }, 200, req, config);
+    } catch {
+      return jsonResponse({ ...fallback, codexLogs: null, codexLogsError: "inspect_failed" }, 200, req, config);
+    }
+  }
+
+  try {
+    const report = getCodexLogGuardProtectionStatus(protectionDeps);
+    return inspectionUnavailable(report)
+      ? jsonResponse({ ...storage, codexLogs: null, codexLogsError: "inspect_failed" }, 200, req, config)
+      : jsonResponse({ ...storage, codexLogs: report }, 200, req, config);
+  } catch {
+    // Log Guard inspection is auxiliary to the existing Storage page. A config/path
+    // resolution failure must not take the legacy read-only storage report down with it.
+    return jsonResponse({ ...storage, codexLogs: null, codexLogsError: "inspect_failed" }, 200, req, config);
+  }
+}

package/src/server/management/sync-response.ts

@@ -0,0 +1,69 @@
+/**
+ * The single HTTP projection of ConvergeOutcome.
+ *
+ * Three phase documents once mapped /api/sync independently and one silently
+ * dropped Retry-After. Keeping the exhaustive switch here makes a new domain
+ * outcome a compile error until its management contract is chosen explicitly.
+ */
+import type { ConvergeOutcome } from "../../codex/convergence-types";
+import { jsonResponse } from "../auth-cors";
+
+export function toSyncResponse(outcome: ConvergeOutcome): Response {
+  switch (outcome.kind) {
+    case "catalog-only":
+      return jsonResponse({
+        ok: true,
+        changed: outcome.changed,
+        observed: outcome.observed,
+        catalogRefresh: outcome.catalogRefresh,
+        history: outcome.history,
+      });
+    case "converged":
+      return jsonResponse({
+        ok: true,
+        changed: outcome.changed,
+        observed: outcome.observed,
+        catalogRefresh: outcome.catalogRefresh,
+        history: outcome.history,
+      });
+    case "skipped":
+      return jsonResponse({
+        ok: true,
+        changed: false,
+        observed: outcome.observed,
+        catalogRefresh: outcome.catalogRefresh,
+        history: outcome.history,
+      });
+    case "refused":
+      return jsonResponse({
+        ok: false,
+        authority: outcome.authority,
+        message: outcome.message,
+        observed: outcome.observed,
+      }, 409);
+    case "busy": {
+      const response = jsonResponse({
+        ok: false,
+        surface: outcome.surface,
+        retryAfterMs: outcome.retryAfterMs,
+      }, 503);
+      response.headers.set("Retry-After", String(Math.ceil(outcome.retryAfterMs / 1_000)));
+      return response;
+    }
+    case "deferred":
+      return jsonResponse({
+        ok: true,
+        changed: outcome.changed,
+        unresolved: outcome.unresolved,
+        observed: outcome.observed,
+        catalogRefresh: outcome.catalogRefresh,
+        history: outcome.history,
+      });
+    case "failed":
+      return jsonResponse({ error: outcome.message, surface: outcome.surface }, 500);
+    default: {
+      const exhaustive: never = outcome;
+      return exhaustive;
+    }
+  }
+}

package/src/server/management/system-restart.ts

@@ -17,45 +17,123 @@
  * - If detached spawn fails (sync throw or pre-start `error`): exit(1) without
  *   markRecycling — after drain the listen socket is already closed, so a latch
  *   reset cannot recover serving. Clear inherited `OCX_SERVICE` so exit cleanup
- *   can restore Codex/Grok fences (ensure/tray daemons set the marker without a
- *   real supervisor). Log only a stable errno code — never the raw message
+ *   can restore Codex/Grok fences when a stale service marker has no viable
+ *   supervisor. Log only a stable errno code — never the raw message
  *   (paths in ENOENT often include the OS username).
  */
 import { spawn } from "node:child_process";
 import {
+  beginShutdownDrain,
   drainAndShutdown,
   getActiveTurnCount,
   getServerListenPort,
   isDraining,
+  isShutdownDraining,
   markRecyclingForExit,
-  setDraining,
+  stopServerListener,
 } from "../lifecycle";
 import { isServiceViable } from "../../service";
-import { readRuntimePort } from "../../config";
+import { readRuntimePort } from "../../config/process-state";
+import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
+import { selfLaunchArgv } from "../../lib/self-launch-argv";
+import {
+  MEMORY_DRAIN_RESTART_MS,
+  REPLACEMENT_READY_TIMEOUT_MS,
+} from "../../lib/system-restart-contract";
+import { findLiveProxy } from "../proxy-liveness";
+
+export { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../../lib/system-restart-contract";
+export const DEADLINE_LISTENER_STOP_TIMEOUT_MS = 5_000;
+const REPLACEMENT_READY_POLL_MS = 150;
 
-/** Fixed v1 drain window for the memory-card action (not config-driven). */
-export const MEMORY_DRAIN_RESTART_MS = 60_000;
+export interface ReplacementReadinessIo {
+  findLive?: typeof findLiveProxy;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
 
 export interface SystemRestartIo {
   drainAndShutdown?: typeof drainAndShutdown;
   /** True when a background service can actually respawn this process after exit(1). */
   isServiceViable?: () => boolean;
   isSupervisedServiceChild?: () => boolean;
-  /** Must resolve only after the replacement process has actually started. */
-  spawnStart?: (port?: number) => void | Promise<void>;
+  /** Ordinary start; deadline handoff may defer health until parent exit releases OS locks. */
+  spawnStart?: (port?: number, waitForHealthBeforeParentExit?: boolean) => void | Promise<void>;
+  /** Idempotent listener close; must settle before an ordinary start is spawned. */
+  stopListener?: () => void | Promise<void>;
   markRecycling?: () => void;
   exitProcess?: (code: number) => void;
   schedule?: (fn: () => void | Promise<void>, ms: number) => void;
+  scheduleDeadline?: (fn: () => void, ms: number) => () => void;
   isDraining?: () => boolean;
+  isShutdownDraining?: () => boolean;
+  beginShutdownDrain?: () => boolean;
   setDraining?: (value: boolean) => void;
   getActiveTurnCount?: () => number;
   listenPort?: () => number | undefined;
+  now?: () => number;
 }
 
 let restartIo: SystemRestartIo = {};
 /** Prevents double-scheduling in the 200ms window before drainAndShutdown sets draining. */
 let restartAccepted = false;
 
+type RestartDrainOutcome = "completed" | "rejected" | "deadline";
+type BoundedSettlementOutcome = "completed" | "rejected" | "deadline";
+
+function waitForRestartDrain(
+  drainPromise: Promise<void>,
+  deadlineMs: number,
+  now: () => number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<RestartDrainOutcome> {
+  const remainingMs = Math.max(0, deadlineMs - now());
+  if (remainingMs === 0) {
+    // Observe any late rejection even though orchestration is already terminal.
+    void drainPromise.catch(() => {});
+    return Promise.resolve("deadline");
+  }
+  return new Promise<RestartDrainOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: RestartDrainOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), remainingMs);
+    if (settled) cancelDeadline();
+    void drainPromise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
+function waitForBoundedSettlement(
+  promise: Promise<void>,
+  timeoutMs: number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<BoundedSettlementOutcome> {
+  return new Promise<BoundedSettlementOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: BoundedSettlementOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), timeoutMs);
+    if (settled) cancelDeadline();
+    void promise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
 /** Test seam — reset between tests. */
 export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
   restartIo = io;
@@ -86,42 +164,180 @@ function spawnFailureCode(err: unknown): string {
   return "spawn_failed";
 }
 
-function spawnDetachedStart(port?: number): Promise<void> {
-  const args = [process.argv[1], "start"];
-  if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) {
-    args.push("--port", String(Math.trunc(port)));
+function handoffError(code: string): NodeJS.ErrnoException {
+  const error = new Error(code) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+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 = now() + REPLACEMENT_READY_TIMEOUT_MS;
+  while (now() < deadline) {
+    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;
+}
+
+function spawnDetachedStart(
+  port?: number,
+  waitForHealthBeforeParentExit = true,
+): Promise<void> {
+  const args = ["start"];
+  const expectedPort = typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535
+    ? Math.trunc(port)
+    : undefined;
+  if (expectedPort !== undefined) {
+    args.push("--port", String(expectedPort));
+  }
+  const launchArgs = selfLaunchArgv(args);
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
     try {
-      child = spawn(process.execPath, args, {
+      const env: NodeJS.ProcessEnv = { ...process.env };
+      delete env.OCX_SERVICE;
+      child = spawn(process.execPath, launchArgs, {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env, OCX_SERVICE: "1" },
+        env: withProcessRuntimeProvenance(env),
       });
     } catch (err) {
       reject(err);
       return;
     }
     let settled = false;
-    const finish = (fn: () => void) => {
+    const cleanup = () => {
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.off("spawn", onSpawn);
+    };
+    const finish = (error?: unknown) => {
       if (settled) return;
       settled = true;
-      fn();
+      cleanup();
+      if (error !== undefined) {
+        if (child.exitCode === null && child.signalCode === null) {
+          try { child.kill(); } catch { /* best-effort failed-start cleanup */ }
+        }
+        try { child.unref(); } catch { /* best-effort */ }
+        reject(error);
+        return;
+      }
+      child.unref();
+      resolve();
     };
-    child.once("error", (err) => {
-      finish(() => reject(err));
-    });
-    child.once("spawn", () => {
-      finish(() => {
-        child.unref();
-        resolve();
-      });
-    });
+    const onError = (err: Error) => { finish(err); };
+    const onExit = () => { finish(handoffError("child_exit")); };
+    const onSpawn = () => {
+      if (!waitForHealthBeforeParentExit) {
+        // A deadline may have been caused by native-main ownership cleanup.
+        // Let the ordinary child survive parent exit, which releases those OS locks.
+        finish();
+        return;
+      }
+      void waitForReplacementReady(child.pid, process.pid, expectedPort).then(
+        ready => {
+          if (!ready) {
+            console.warn(
+              "Drain-and-restart replacement is still alive after the readiness window; allowing it to continue after parent exit",
+            );
+          }
+          // 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.
+          finish();
+        },
+        err => finish(err),
+      );
+    };
+    child.once("error", onError);
+    child.once("exit", onExit);
+    child.once("spawn", onSpawn);
   });
 }
 
+async function completeDeferredParentExitHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  phase: "deadline" | "listener-stop fallback",
+): Promise<void> {
+  try {
+    await (io.spawnStart ?? spawnDetachedStart)(port, false);
+  } catch (err) {
+    console.warn(
+      `Drain-and-restart ${phase} spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
+    );
+    delete process.env.OCX_SERVICE;
+    exitProcess(1);
+    return;
+  }
+  (io.markRecycling ?? markRecyclingForExit)();
+  exitProcess(0);
+}
+
+async function completeDeadlineRestartHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<void> {
+  const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
+  if (supervised) {
+    // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+    exitProcess(1);
+    return;
+  }
+
+  const stopPromise = Promise.resolve().then(
+    () => (io.stopListener ?? (() => stopServerListener()))(),
+  );
+  const stopOutcome = await waitForBoundedSettlement(
+    stopPromise,
+    DEADLINE_LISTENER_STOP_TIMEOUT_MS,
+    scheduleDeadline,
+  );
+  if (stopOutcome === "rejected") {
+    console.warn("Drain-and-restart deadline listener stop failed; continuing parent-exit handoff");
+  } else if (stopOutcome === "deadline") {
+    console.warn("Drain-and-restart deadline listener stop timed out; continuing parent-exit handoff");
+  }
+  // The ordinary child must survive parent exit: a failed/pending socket close
+  // or overdue cleanup is completed by process teardown, without a hidden mode.
+  await completeDeferredParentExitHandoff(io, exitProcess, port, "deadline");
+}
+
 /**
  * Accept a drain-and-restart request. Returns immediately; the drain +
  * respawn runs on a short timer so the HTTP response can flush first.
@@ -133,34 +349,74 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
   activeTurnCount: number;
   drainTimeoutMs: number;
 } {
-  const alreadyDraining = restartAccepted || (io.isDraining ?? isDraining)();
+  const shutdownActive = io.isShutdownDraining
+    ?? io.isDraining
+    ?? isShutdownDraining;
+  const alreadyDraining = restartAccepted || shutdownActive();
   const activeTurnCount = (io.getActiveTurnCount ?? getActiveTurnCount)();
   const schedule = io.schedule ?? ((fn, ms) => { setTimeout(() => { void fn(); }, ms); });
 
   if (!alreadyDraining) {
     restartAccepted = true;
+    const now = io.now ?? Date.now;
+    const restartDeadlineMs = now() + MEMORY_DRAIN_RESTART_MS;
     // Reject new data-plane traffic immediately (503), before the 200ms response-flush delay.
-    (io.setDraining ?? setDraining)(true);
+    if (io.beginShutdownDrain) io.beginShutdownDrain();
+    else if (io.setDraining) io.setDraining(true);
+    else beginShutdownDrain();
     schedule(async () => {
+      // Preserve the live binding before drainAndShutdown (or its deadline race)
+      // closes the listener and makes both the server ref and runtime metadata stale.
+      const restartPort = (io.listenPort ?? resolveListenPort)();
       const drain = io.drainAndShutdown ?? drainAndShutdown;
-      await drain(undefined, MEMORY_DRAIN_RESTART_MS);
+      const remainingMs = Math.max(0, restartDeadlineMs - now());
+      const drainPromise = Promise.resolve().then(() => drain(undefined, remainingMs));
+      const scheduleDeadline = io.scheduleDeadline ?? ((fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        return () => clearTimeout(timer);
+      });
+      const drainOutcome = await waitForRestartDrain(drainPromise, restartDeadlineMs, now, scheduleDeadline);
+      const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
+      if (drainOutcome === "deadline") {
+        console.warn("Drain-and-restart deadline expired; forcing terminal restart handoff");
+        await completeDeadlineRestartHandoff(io, exitProcess, restartPort, scheduleDeadline);
+        return;
+      }
+      if (drainOutcome === "rejected") {
+        // drainAndShutdown stops the listener in finally. Even if ancillary cleanup
+        // rejects, an accepted restart must still reach replacement or terminal exit.
+        console.warn("Drain-and-restart cleanup failed; continuing terminal restart handoff");
+      }
       const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
       if (supervised) {
         // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
         (io.exitProcess ?? ((code: number) => { process.exit(code); }))(1);
         return;
       }
-      const port = (io.listenPort ?? resolveListenPort)();
-      const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
       try {
-        await (io.spawnStart ?? spawnDetachedStart)(port);
+        await (io.stopListener ?? (() => stopServerListener()))();
+      } catch {
+        console.warn("Drain-and-restart listener stop failed; continuing parent-exit handoff");
+        await completeDeferredParentExitHandoff(
+          io,
+          exitProcess,
+          restartPort,
+          "listener-stop fallback",
+        );
+        return;
+      }
+      try {
+        // A rejected drain has uncertain cleanup ownership, so it uses the same
+        // parent-exit handoff as a deadline. Only a fully completed drain waits
+        // for replacement health in the old process.
+        await (io.spawnStart ?? spawnDetachedStart)(restartPort, drainOutcome === "completed");
       } catch (err) {
         console.warn(
           `⚠️  Drain-and-restart spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
         );
         // Listen socket is already stopped; do not markRecycling — no child to inherit fences.
-        // ensure/tray children inherit OCX_SERVICE=1 without an installed service; clear it so
-        // syncCleanup can restore Codex/Grok fences instead of leaving clients pointed at a dead port.
+        // No replacement inherited the routing. Clear a stale service marker so
+        // this unsupervised parent restores clients after the failed handoff.
         delete process.env.OCX_SERVICE;
         exitProcess(1);
         return;