@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/client/link-relay.ts

@@ -1,4 +1,5 @@
 import { fetchBoundLinkRelay, LinkRelayAuthenticationError } from "./link-relay-transport";
+import { homeUnreachableBody } from "./home-unreachable";
 import {
   boundedRelayResponseStream,
   filterRelayHeaders,
@@ -112,6 +113,29 @@ function jsonError(status: number, error: string, retry = false): Response {
   return Response.json({ error }, { status, headers });
 }
 
+/** A retryable 503 for a Home this Child cannot reach (OCX-11 `home_unreachable`). */
+function homeUnreachable(error: string): Response {
+  return Response.json(homeUnreachableBody(error), {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
+/**
+ * The peer answered but the connection-bound relay authentication failed. That is not a Home
+ * outage (an unrecognized protocol needs an upgrade or a re-link), so it must never read as
+ * `home_unreachable`, which GOAT's device-local fallback keys on. The status and Retry-After it
+ * carried before OCX-11 are kept: a lost bound socket can succeed on a fresh connection.
+ */
+export const LINK_RELAY_AUTH_FAILED_CODE = "link_relay_auth_failed";
+
+function relayAuthenticationFailed(error: string): Response {
+  return Response.json({ error, code: LINK_RELAY_AUTH_FAILED_CODE }, {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
 export function linkRelayDestination(url: URL, target: Pick<LinkRelayTarget, "tunnelPort">): string {
   if (!isLinkPort(target.tunnelPort)) {
     throw new RangeError("invalid link tunnel port");
@@ -369,7 +393,7 @@ export async function relayLinkDataRequest(
   const tunnelUnavailable = async (): Promise<Response> => {
     cleanup();
     try { await body?.cancel(); } catch { /* best effort */ }
-    return jsonError(503, "link tunnel unavailable", true);
+    return homeUnreachable("link tunnel unavailable");
   };
   const readyForFetch = async (): Promise<boolean> => {
     if (!tunnel) return false;
@@ -393,7 +417,7 @@ export async function relayLinkDataRequest(
       if (error instanceof LinkRelayAuthenticationError) {
         cleanup();
         try { await body?.cancel(); } catch { /* an upload might already be drained */ }
-        return jsonError(503, error.message, true);
+        return relayAuthenticationFailed(error.message);
       }
       if (bodyOverflow) {
         cleanup();
@@ -408,7 +432,7 @@ export async function relayLinkDataRequest(
   if (relayAbort.signal.aborted) {
     cleanup();
     try { await upstream.body?.cancel(); } catch { /* best effort */ }
-    return jsonError(503, "link tunnel unavailable", true);
+    return homeUnreachable("link tunnel unavailable");
   }
 
   const sse = isSse(upstream.headers);

package/src/client/machine-listener.ts

@@ -22,9 +22,23 @@ import { readClientLinkState, type ClientLinkState } from "./link-state";
 import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-status";
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
 import { packageVersion } from "../lib/package-version";
+import { createLocalAttestationProof, LOCAL_ATTESTATION_CHALLENGE_HEADER, LOCAL_ATTESTATION_PROOF_HEADER } from "../lib/local-management-attestation";
+import {
+  CLIENT_RESTART_BUDGET_MS,
+  parseExpectedSystemRestartPid,
+  RESTART_SUPERVISED_ERROR,
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_CAPABILITY_VERSION,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_METHOD,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  verifySystemRestartCapability,
+} from "../lib/system-restart-contract";
 import { linkRouteAllowed } from "../link/routes";
 import { linkHomeName, linkHomePhrase } from "./link-home";
 import { relayLinkManagementRead } from "./link-management-relay";
+import type { ClientRestartAdmission } from "./runtime-restart";
 
 const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
@@ -51,6 +65,17 @@ export interface MachineListenerDeps {
   linkTunnel?: LinkTunnelGate;
   /** Link mode: relay seams (deadline clock and byte cap). */
   linkRelay?: LinkIngress["relay"];
+  /**
+   * The bound restart (OCX-6). With it, `/healthz` proves this process's identity to a challenge,
+   * advertises `restartCapability` and `startedAt`, and `POST /api/system/restart` accepts a
+   * capability signed with `attestationSecret` for this pid and port, and nothing else.
+   */
+  restart?: {
+    attestationSecret: string;
+    /** ISO start time of this runtime's process. */
+    startedAt: string;
+    request: () => Promise<ClientRestartAdmission>;
+  };
   serve?: (options: Parameters<typeof Bun.serve>[0]) => Server<unknown>;
 }
 
@@ -68,6 +93,8 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
   if (linkMode && linkRouteAllowed(url, req)) return true;
   const path = url.pathname;
   if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
+  // The bound restart. Only a capability signed for this exact process admits it (see the handler).
+  if (req.method === SYSTEM_RESTART_METHOD && path === SYSTEM_RESTART_PATH) return true;
   if ((req.method === "GET" || req.method === "HEAD") && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
   // The one link route a connected Child serves: its own read-only link status.
   if (linkMode && (req.method === "GET" || req.method === "HEAD") && path === "/api/link/status") return true;
@@ -143,7 +170,20 @@ export function startMachineListener(
       }
       if (!machineRouteAllowed(url, req, relayEnabled, linkMode)) return json404(req);
       if (url.pathname === "/healthz" && req.method === "GET") {
-        return Response.json({ service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port });
+        const restart = deps.restart;
+        const response = Response.json({
+          service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port,
+          ...(restart ? { startedAt: restart.startedAt, restartCapability: SYSTEM_RESTART_CAPABILITY_VERSION, restartBudgetMs: CLIENT_RESTART_BUDGET_MS } : {}),
+        });
+        const challenge = restart ? req.headers.get(LOCAL_ATTESTATION_CHALLENGE_HEADER) : null;
+        const proof = challenge && server.port
+          ? createLocalAttestationProof(restart!.attestationSecret, challenge, process.pid, server.port)
+          : null;
+        if (proof) response.headers.set(LOCAL_ATTESTATION_PROOF_HEADER, proof);
+        return response;
+      }
+      if (url.pathname === SYSTEM_RESTART_PATH && req.method === SYSTEM_RESTART_METHOD) {
+        return await handleBoundRestart(req, server, deps.restart);
       }
       if (url.pathname === "/readyz" && req.method === "GET") {
         return Response.json({ service: "opencodex", version: VERSION, role: "client", status: "ready", uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 });
@@ -232,3 +272,45 @@ export function startMachineListener(
     },
   } as Parameters<typeof Bun.serve>[0]);
 }
+
+/**
+ * `POST /api/system/restart` on the client listener (OCX-6). The only accepted principal is the
+ * process-bound restart capability `ocx restart` derives from this runtime's attestation secret:
+ * no dashboard session, admin token or link key reaches it, and a browser cannot mint it.
+ */
+async function handleBoundRestart(
+  req: Request,
+  server: Server<unknown>,
+  restart: MachineListenerDeps["restart"],
+): Promise<Response> {
+  const noStore = { "cache-control": "no-store" };
+  if (!restart || !server.port) return json404(req);
+  const expected = parseExpectedSystemRestartPid(req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER));
+  if (expected.kind !== "present" || expected.pid !== process.pid) {
+    return Response.json({ success: false, error: "Restart target identity changed." }, { status: 409, headers: noStore });
+  }
+  const authorized = verifySystemRestartCapability(
+    restart.attestationSecret,
+    req.headers.get(SYSTEM_RESTART_NONCE_HEADER),
+    SYSTEM_RESTART_METHOD,
+    SYSTEM_RESTART_PATH,
+    process.pid,
+    server.port,
+    req.headers.get(SYSTEM_RESTART_CAPABILITY_HEADER),
+  );
+  if (!authorized) return Response.json({ success: false, error: "restart capability required" }, { status: 401, headers: noStore });
+  const admission = await restart.request();
+  if (admission.kind === "supervised") {
+    return Response.json({
+      success: false,
+      error: { code: RESTART_SUPERVISED_ERROR, supervisor: admission.supervisor },
+    }, { status: 409, headers: noStore });
+  }
+  return Response.json({
+    success: true,
+    message: admission.alreadyRestarting ? "Restart already in progress." : "Restarting the client runtime.",
+    activeTurnCount: 0,
+    drainTimeoutMs: CLIENT_RESTART_BUDGET_MS,
+    alreadyDraining: admission.alreadyRestarting,
+  }, { status: 202, headers: noStore });
+}

package/src/client/runtime-restart.ts

@@ -0,0 +1,127 @@
+/**
+ * The connected client runtime's answer to the bound `POST /api/system/restart` (OCX-6).
+ *
+ * It is the same restart `ocx restart` drives on a standalone proxy, with one difference the
+ * Remote Link parity work requires: a failed restart keeps the old runtime. That is only possible
+ * when this process starts its own replacement, so:
+ *
+ * - Under the desktop app or a viable service supervisor the restart is refused (409
+ *   `restart_supervised`) and the runtime keeps serving. The supervisor owns this process and its
+ *   port; handing off to it means exiting before anything proves the replacement can start.
+ * - Otherwise the listener drains, a replacement `ocx start` is spawned and must answer within the
+ *   budget. Success exits this process. A replacement that exited, or never answered and was then
+ *   stopped, leaves this process to bind the port again, start a fresh tunnel supervisor and
+ *   republish its records: the old runtime keeps serving and the CLI, still seeing its pid,
+ *   reports the restart as failed.
+ *
+ * Everything runs inside {@link CLIENT_RESTART_BUDGET_MS} from acceptance.
+ */
+import {
+  CLIENT_RESTART_DRAIN_MS,
+  CLIENT_RESTART_READY_BY_MS,
+  isDesktopSupervised,
+} from "../lib/system-restart-contract";
+import type { OcxClientConnectionConfig } from "../types";
+import { sameClientConnectionOwner, type readClientConnectionState } from "./state";
+
+type ClientConnectionState = ReturnType<typeof readClientConnectionState>;
+
+export type ClientRestartSupervisor = "service" | "desktop";
+
+export type ClientRestartAdmission =
+  | { kind: "accepted"; alreadyRestarting: boolean }
+  | { kind: "supervised"; supervisor: ClientRestartSupervisor };
+
+export interface ClientRestartIo {
+  /** Which supervisor owns this process, or null when it starts its own replacement. */
+  supervisor(): Promise<ClientRestartSupervisor | null>;
+  /** Stop the tunnel supervisor and the listener, giving in-flight requests up to `drainMs`. */
+  stop(drainMs: number): Promise<void>;
+  /** Start the replacement; resolves once it answers, rejects when none survives. */
+  spawnReplacement(deadlineAt: number): Promise<void>;
+  /** Serve again on this process: listener, fresh tunnel supervisor, records. */
+  resume(): Promise<void>;
+  exitProcess(code: number): void;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  warn?: (message: string) => void;
+}
+
+export interface ClientRestartController {
+  request(): Promise<ClientRestartAdmission>;
+  /** Settles when the restart in flight (if any) has finished or rolled back. Tests only. */
+  settled(): Promise<void>;
+}
+
+/** Stable, path-free label for a failure (an error message can carry a path). */
+function failureCode(error: unknown): string {
+  const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+  return typeof code === "string" && /^[A-Za-z0-9_]{1,64}$/.test(code) ? code : "failed";
+}
+
+export function createClientRestartController(io: ClientRestartIo): ClientRestartController {
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const warn = io.warn ?? ((message: string) => console.warn(message));
+  let flight: Promise<void> | null = null;
+
+  const run = async (acceptedAt: number): Promise<void> => {
+    // Let the 202 reach the CLI before the listener starts closing.
+    await sleep(200);
+    try {
+      await io.stop(CLIENT_RESTART_DRAIN_MS);
+    } catch (error) {
+      warn(`[client] restart: stopping the runtime failed (${failureCode(error)}); continuing`);
+    }
+    try {
+      await io.spawnReplacement(acceptedAt + CLIENT_RESTART_READY_BY_MS);
+    } catch (error) {
+      warn(`[client] restart: the replacement did not start (${failureCode(error)}); this runtime keeps serving`);
+      try {
+        await io.resume();
+      } catch (resumeError) {
+        warn(`[client] restart: this runtime could not serve again (${failureCode(resumeError)}); run 'ocx start'`);
+        io.exitProcess(1);
+      }
+      return;
+    }
+    io.exitProcess(0);
+  };
+
+  return {
+    async request() {
+      const supervisor = await io.supervisor();
+      if (supervisor) return { kind: "supervised", supervisor };
+      if (flight) return { kind: "accepted", alreadyRestarting: true };
+      flight = run(now()).finally(() => { flight = null; });
+      return { kind: "accepted", alreadyRestarting: false };
+    },
+    async settled() {
+      await flight;
+    },
+  };
+}
+
+/** Production supervision check: the desktop app, then a service that will really relaunch us. */
+export async function clientRestartSupervisor(): Promise<ClientRestartSupervisor | null> {
+  if (isDesktopSupervised()) return "desktop";
+  if (process.env.OCX_SERVICE !== "1") return null;
+  // Same viability test as the standalone restart: stale service assets would not relaunch.
+  const { isServiceViable } = await import("../service/orchestration");
+  return isServiceViable() ? "service" : null;
+}
+
+/**
+ * After a failed replacement: serve the same connection again only while it is still the durable
+ * one (same owner and link). Anything else, a disconnect or a different connection, goes to the
+ * recycle, which starts what the current state calls for instead of a stale client runtime.
+ */
+export function clientRestartRollbackAction(
+  served: OcxClientConnectionConfig,
+  current: ClientConnectionState,
+): "resume" | "recycle" {
+  return current.kind === "connected" && sameClientConnectionOwner(current.value, served)
+    && current.value.link?.linkId === served.link?.linkId
+    ? "resume"
+    : "recycle";
+}

package/src/client/runtime.ts

@@ -9,6 +9,7 @@ import { createLocalAttestationSecret } from "../lib/local-management-attestatio
 import { loadServiceTokenFromFile, serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { handledSignalExitCode } from "../lib/handled-signal-exit";
 import {
+  CLIENT_RESTART_REBIND_WAIT_MS,
   DESKTOP_RESTART_EXIT_CODE,
   DESKTOP_SUPERVISED_ENV,
   DESKTOP_SUPERVISED_PORT_WAIT_MS,
@@ -23,12 +24,22 @@ import { createClientLinkSupervisor, type ClientLinkSupervisor } from "./link-tu
 import { clientLinkStatePath, isChildInitiatedLink, recordChildInitiatedLink } from "./link-state";
 import { startMachineListener, type MachineListenerDeps } from "./machine-listener";
 import { isLinkConnection, readClientConnectionState } from "./state";
+import { withClientLifecycleSync } from "./lifecycle-lock";
+import { clientRestartRollbackAction, clientRestartSupervisor, createClientRestartController, type ClientRestartController } from "./runtime-restart";
+import { createLinkParityReporter, type LinkParityReporter } from "./link-parity-reporter";
 
 let activeServer: Server<unknown> | null = null;
 let activePort: number | null = null;
 let activeSupervisor: ClientLinkSupervisor | null = null;
+let activeReporter: LinkParityReporter | null = null;
 let recycleScheduled = false;
 
+/**
+ * When this runtime's process started (OCX-6, P5): what `/healthz` reports as `startedAt` and the
+ * Child reports to its Home. A Home settings apply recorded after it means this runtime predates it.
+ */
+export const CLIENT_RUNTIME_STARTED_AT = new Date(Date.now() - process.uptime() * 1000).toISOString();
+
 /**
  * How long link mode waits for its configured port: the budget a hard-pinned `ocx start --port`
  * gives `reclaimListenPort` (`src/cli/index.ts`).
@@ -53,6 +64,8 @@ export interface ClientRuntimeIo {
   /** Link-mode port budget; defaults to {@link LINK_PORT_WAIT_MS}. */
   portWaitMs?: number;
   startListener?: typeof startMachineListener;
+  /** Which supervisor owns this process for a bound restart; tests replace the production check. */
+  restartSupervisor?: () => Promise<"service" | "desktop" | null>;
 }
 
 export interface StandaloneRecycleIo {
@@ -214,7 +227,7 @@ export async function bindClientListener(
     preferred: number;
     explicitPort: boolean;
     configuredPort: number;
-  } & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel">,
+  } & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel" | "restart">,
   io: ClientRuntimeIo = {},
 ): Promise<{ server: Server<unknown>; port: number }> {
   const { linkMode } = request;
@@ -254,6 +267,7 @@ export async function bindClientListener(
         ...(request.linkStatus ? { linkStatus: request.linkStatus } : {}),
         ...(request.linkKeySource ? { linkKeySource: request.linkKeySource } : {}),
         ...(request.linkTunnel ? { linkTunnel: request.linkTunnel } : {}),
+        ...(request.restart ? { restart: request.restart } : {}),
       });
       return { server, port: server.port ?? port };
     } catch (error) {
@@ -286,33 +300,129 @@ export async function startClientRuntime(
   if (linkMode && state.value.link) {
     try { recordChildInitiatedLink(state.value.link.linkId); } catch { /* the sidecar check below still applies */ }
   }
-  const supervisor = linkMode && existsSync(clientLinkStatePath())
-    ? createClientLinkSupervisor({
-      onLinkEnded: () => scheduleStandaloneRecycle(state.value.tokenFingerprint),
-      linkKey,
-    })
-    : null;
+  const supervised = linkMode && existsSync(clientLinkStatePath());
   // A Child with no sidecar and no record of joining itself was connected by its Home over
   // `ssh -R`; that link keeps 2.67.0's unproven forward. A Child-initiated link that lost its
   // sidecar gets no gate at all, so the relay refuses it.
-  const homeInitiated = linkMode && !supervisor && !!state.value.link
+  const homeInitiated = linkMode && !supervised && !!state.value.link
     && !isChildInitiatedLink(state.value.link.linkId);
-  const { server, port: boundPort } = await bindClientListener({
-    state: state.value,
-    linkMode,
-    preferred,
-    explicitPort: options.port !== undefined,
-    configuredPort: config.port,
-    ...(linkMode ? { linkStatus: () => supervisor?.status() ?? { kind: "stopped" as const }, linkKeySource: linkKey } : {}),
-    ...(supervisor ? { linkTunnel: supervisor } : homeInitiated ? { linkTunnel: HOME_INITIATED_LINK_TUNNEL } : {}),
-  }, io);
-  activeServer = server;
-  activePort = boundPort;
-  activeSupervisor = supervisor;
-  supervisor?.start();
+  // One secret for the life of this process: a rollback republishes the same identity.
+  const attestationSecret = createLocalAttestationSecret();
+
+  // Bind, start a fresh tunnel supervisor and publish. Runs once at start and again when a failed
+  // restart rolls back (OCX-6); the stopped supervisor cannot be started twice, so each call builds one.
+  // The port this process actually serves on; a rollback binds exactly this one again.
+  let servedPort = preferred;
+  // Returns false only for a rollback whose connection changed while it was binding: the new
+  // listener is then closed unpublished and the caller recycles.
+  const serve = async (rollback?: { port: number; portWaitMs: number }): Promise<boolean> => {
+    const supervisor = supervised
+      ? createClientLinkSupervisor({
+        onLinkEnded: () => scheduleStandaloneRecycle(state.value.tokenFingerprint),
+        linkKey,
+      })
+      : null;
+    const { server, port: boundPort } = await bindClientListener({
+      state: state.value,
+      linkMode,
+      // A rollback takes back exactly the port it gave up: never the preferred one, never another.
+      preferred: rollback?.port ?? preferred,
+      explicitPort: rollback !== undefined || options.port !== undefined,
+      configuredPort: config.port,
+      restart: { attestationSecret, startedAt: CLIENT_RUNTIME_STARTED_AT, request: () => restartController.request() },
+      ...(linkMode ? { linkStatus: () => activeSupervisor?.status() ?? { kind: "stopped" as const }, linkKeySource: linkKey } : {}),
+      ...(supervisor ? { linkTunnel: supervisor } : homeInitiated ? { linkTunnel: HOME_INITIATED_LINK_TUNNEL } : {}),
+    }, rollback === undefined ? io : { ...io, portWaitMs: rollback.portWaitMs });
+    const publish = (): void => {
+      activeServer = server;
+      activePort = boundPort;
+      servedPort = boundPort;
+      activeSupervisor = supervisor;
+      supervisor?.start();
+      writePid(process.pid);
+      writeRuntimePort(clientRuntimeRecord(process.pid, boundPort, attestationSecret));
+      if (linkMode && state.value.link && linkKey) {
+        activeReporter = createLinkParityReporter({ connection: state.value, linkKey, runtimeStartedAt: CLIENT_RUNTIME_STARTED_AT });
+        activeReporter.start();
+      }
+    };
+    if (!rollback) {
+      publish();
+      return true;
+    }
+    // A rollback publishes under the client lifecycle lock, after rechecking the connection there,
+    // so a disconnect or connect that committed during the bind can never be served over. A lock
+    // held by such an operation counts as a change.
+    let published = false;
+    try {
+      published = withClientLifecycleSync(() => {
+        if (clientRestartRollbackAction(state.value, readClientConnectionState()) === "recycle") return false;
+        publish();
+        return true;
+      });
+    } catch {
+      published = false;
+    }
+    if (!published) {
+      try { await server.stop(true); } catch { /* never published */ }
+    }
+    return published;
+  };
+
+  // Stop everything this process serves, giving in-flight requests up to `drainMs`.
+  const stopServing = async (drainMs: number): Promise<void> => {
+    activeReporter?.stop();
+    activeReporter = null;
+    try {
+      await activeSupervisor?.stop();
+    } catch (error) {
+      console.warn(`[client] link supervisor stop failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    activeSupervisor = null;
+    const server = activeServer;
+    activeServer = null;
+    if (!server) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        Promise.resolve(server.stop(false)),
+        new Promise<void>(resolve => { timer = setTimeout(resolve, drainMs); }),
+      ]);
+    } catch { /* closed below */ } finally {
+      if (timer) clearTimeout(timer);
+    }
+    try { await server.stop(true); } catch { /* already closed */ }
+  };
+
+  const restartController: ClientRestartController = createClientRestartController({
+    supervisor: io.restartSupervisor ?? clientRestartSupervisor,
+    stop: stopServing,
+    spawnReplacement: async deadlineAt => {
+      const { replacementStartEnvironment } = await import("../server/management/system-restart");
+      const { spawnReplacementStart } = await import("../server/restart-replacement");
+      await spawnReplacementStart(
+        { port: activePort ?? config.port, waitForHealth: true, env: replacementStartEnvironment(true), notReady: "terminate" },
+        { deadlineAt },
+      );
+    },
+    resume: async () => {
+      // The connection may have changed while the replacement was starting (`ocx disconnect`, a
+      // new connect). Serving the old one again would be a stale runtime nothing recycles; hand
+      // off to the recycle, which starts whatever the durable state now calls for.
+      if (clientRestartRollbackAction(state.value, readClientConnectionState()) === "recycle") {
+        await recycleStandalone(state.value.tokenFingerprint);
+        return;
+      }
+      if (!(await serve({ port: servedPort, portWaitMs: CLIENT_RESTART_REBIND_WAIT_MS }))) {
+        await recycleStandalone(state.value.tokenFingerprint);
+      }
+    },
+    exitProcess: code => { process.exit(code); },
+  });
+
   installCrashGuards();
-  writePid(process.pid);
-  writeRuntimePort(clientRuntimeRecord(process.pid, boundPort));
+  // serve() publishes the pid and runtime record; the ownership lease is released only after it.
+  await serve();
   options.afterPublish?.();
 
   let shuttingDown = false;
@@ -320,14 +430,16 @@ export async function startClientRuntime(
     if (shuttingDown) return;
     shuttingDown = true;
     void (async () => {
+      activeReporter?.stop();
+      activeReporter = null;
       try {
-        await supervisor?.stop();
+        await activeSupervisor?.stop();
       } catch (error) {
         console.warn(`[client] link supervisor stop failed: ${error instanceof Error ? error.message : String(error)}`);
       }
       activeSupervisor = null;
       try {
-        server.stop(true);
+        activeServer?.stop(true);
       } catch (error) {
         console.warn(`[client] listener stop failed: ${error instanceof Error ? error.message : String(error)}`);
       } finally {

package/src/codex/account-lifecycle.ts

@@ -1,4 +1,5 @@
 import { observeSignedInCodexIdentity } from "./signed-in-identity";
+import { observeMainCodexCollisionIdentity } from "./collision-identity";
 import { existsSync, readFileSync } from "node:fs";
 import {
   deleteConfigTopLevelKey,
@@ -9,11 +10,12 @@ import {
 import { captureConfigTopLevelRollback } from "../config/rebase-provenance";
 import { removeCodexAccountCredential } from "./account-store";
 import { clearAccountNeedsReauth } from "./account-runtime-state";
-import { readCodexTokensResult } from "./auth-collision";
+import { readMainAuth } from "./auth-collision";
 import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { clearAccountQuota } from "./quota";
 import { forgetManualPreference } from "./routing/active-account";
 import { deleteAllHealthForAccount } from "./routing/health-store";
+import { forgetCodexFailureWindow } from "./routing/failure-window";
 import { clearThreadAccountMapForAccount } from "./routing/thread-affinity";
 
 import { clearCodexPoolRefreshFailure } from "./pool-refresh-backoff";
@@ -49,11 +51,15 @@ export function purgeCodexAccountRuntimeState(accountId: string): void {
   clearAccountNeedsReauth(accountId);
   clearAccountQuota(accountId);
   clearThreadAccountMapForAccount(accountId);
-  // Deliberately not via `./routing`: the account-delete path only needs the health rows and
-  // the manual preference gone, and importing the router here closed a cycle through
-  // routing/health-store and routing/active-account.
+  // Deliberately not via `./routing`: the account-delete path only needs the health rows
+  // and their sibling routing state gone, and importing the router barrel here closed a
+  // cycle through routing/health-store and routing/active-account. The leaf imports below
+  // carry every per-account forget that barrel helper used to perform — including the
+  // failure window, whose degrade and pin-warning state must not leak into a replacement
+  // account or a new physical login behind __main__.
   deleteAllHealthForAccount(accountId);
   forgetManualPreference(accountId);
+  forgetCodexFailureWindow(accountId);
   clearCodexPoolRefreshFailure(accountId);
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
     clearMainAccountInfoCache();
@@ -74,7 +80,8 @@ function purgeMainCodexAccountRuntimeState(): void {
  * cooldown, quota, reauth, and thread affinity do not leak across accounts.
  */
 export function reconcileMainCodexAccountRuntimeState(): boolean {
-  const read = readCodexTokensResult();
+  const read = readMainAuth();
+  if (read.status === "missing" || read.status === "api-key-only") observeMainCodexCollisionIdentity();
   const currentAccountId = read.status === "ok"
     ? extractAccountId(read.tokens.id_token, read.tokens.access_token) ?? (read.tokens.account_id || null)
     : null;
@@ -86,11 +93,13 @@ export function reconcileMainCodexAccountRuntimeState(): boolean {
   observedMainChatgptAccountId = currentAccountId;
   if (previousAccountId === undefined || previousAccountId === currentAccountId) {
     observeMainQuotaIdentity(currentAccountId);
+    if (read.status === "ok") observeMainCodexCollisionIdentity(read.tokens);
     return false;
   }
 
   purgeMainCodexAccountRuntimeState();
   observeMainQuotaIdentity(currentAccountId);
+  if (read.status === "ok") observeMainCodexCollisionIdentity(read.tokens);
   return true;
 }
 
@@ -103,7 +112,8 @@ export function reconcileMainCodexAccountRuntimeState(): boolean {
 export function initializeMainAccountPolicyBinding(authPath: string): boolean {
   // Startup observes the pinned owned path inside the exclusive claim: bound the read so a
   // replaced non-regular or oversized file cannot stall startup inside that claim.
-  const result = readCodexTokensResult(authPath, { bounded: true });
+  const result = readMainAuth(authPath);
+  if (result.status === "missing" || result.status === "api-key-only") observeMainCodexCollisionIdentity();
   if (result.status !== "ok") return false;
   const { tokens } = result;
   if (typeof tokens.access_token !== "string" || !tokens.access_token
@@ -124,6 +134,7 @@ export function initializeMainAccountPolicyBinding(authPath: string): boolean {
   if (previousAccountId !== undefined && previousAccountId !== accountId) purgeMainCodexAccountRuntimeState();
   observeSignedInCodexIdentity(tokens);
   observeMainQuotaIdentity(accountId);
+  observeMainCodexCollisionIdentity(tokens);
   return observeMainQuotaCredential(tokens.access_token, accountId) !== undefined;
 }
 
@@ -136,6 +147,7 @@ export function applyConfirmedMainCodexAccountTransition(
   toAccountId: string,
 ): boolean {
   observeSignedInCodexIdentity();
+  observeMainCodexCollisionIdentity();
   if (!fromAccountId || !toAccountId || fromAccountId === toAccountId) {
     if (toAccountId) {
       observedMainChatgptAccountId = toAccountId;
@@ -150,6 +162,7 @@ export function applyConfirmedMainCodexAccountTransition(
 }
 
 export function resetMainCodexAccountIdentityTrackingForTests(): void {
+  observeMainCodexCollisionIdentity();
   observedMainChatgptAccountId = undefined;
   observeSignedInCodexIdentity();
   clearMainAccountCredentialPresence();