@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/cli/ready.ts

@@ -0,0 +1,301 @@
+/**
+ * `ocx ready` — pure parser + dependency-injected runner.
+ *
+ * Lives outside cli/index.ts (which dispatches argv at module top level) so the
+ * full behavior is unit-testable without spawning a subprocess, opening a
+ * loopback socket, or touching the real HOME/CODEX_HOME. The runner returns an
+ * exit code; cli/index.ts only calls it and exits with the returned code.
+ *
+ * Contract (per P1 review):
+ *  - Single wait loop. `--wait` waits for proxy discovery AND readiness within
+ *    one bounded deadline (default 45s, max 300s). Without `--wait` a single
+ *    identity-checked probe runs.
+ *  - Invalid arguments return exit code 64 BEFORE any discovery/network work.
+ *  - Output is sanitized: only the fixed `ready|pending|failed|unreachable`
+ *    vocabulary, plus pid/port; never carries sync message, warning, path,
+ *    provider, account, or error data.
+ */
+import { DEFAULT_PROBE_TIMEOUT_MS, findLiveProxy, probeReadiness } from "../server/proxy-liveness";
+
+/** Default --wait deadline (45s). */
+export const DEFAULT_READY_WAIT_TIMEOUT_SECONDS = 45;
+/** Maximum allowed --wait deadline (300s). */
+export const MAX_READY_WAIT_TIMEOUT_SECONDS = 300;
+const POLL_INTERVAL_MS = 500;
+/**
+ * Cap a remaining deadline budget to a positive per-call IO timeout. Stays
+ * positive (>= 1ms) and never exceeds the logical remaining time nor the
+ * shared per-call ceiling (DEFAULT_PROBE_TIMEOUT_MS). Passed by the production
+ * defaults to findLiveProxy's / probeReadiness's timeoutMs so their fetch waits
+ * are bounded by the deadline.
+ */
+function capIoTimeout(remainingMs: number): number {
+  return Math.max(1, Math.min(remainingMs, DEFAULT_PROBE_TIMEOUT_MS));
+}
+
+/** Fixed sanitized CLI status vocabulary. */
+export type CliReadinessStatus = "ready" | "pending" | "failed" | "unreachable";
+
+export interface ReadyArgs {
+  json: boolean;
+  wait: boolean;
+  timeoutSeconds: number;
+}
+
+export type ReadyParseResult =
+  | { ok: true; args: ReadyArgs }
+  | { ok: false; code: 64 };
+
+/**
+ * Pure argument parser. Accepts `--json`, `--wait`, and
+ * `--wait --timeout <seconds>` (positive integer 1..300). Any unknown flag,
+ * positional argument, missing/invalid --timeout value, or `--timeout` without
+ * `--wait` is a usage error that must surface exit code 64.
+ */
+export function parseReadyArgs(argv: string[]): ReadyParseResult {
+  let json = false;
+  let wait = false;
+  let timeoutSeconds: number | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
+    if (flag === "--wait") {
+      wait = true;
+      continue;
+    }
+    if (flag === "--timeout") {
+      const raw = argv[i + 1];
+      // Positive finite integer seconds only; /^[0-9]+$/ rejects negatives, decimals, hex, and "".
+      if (raw === undefined || !/^[0-9]+$/.test(raw)) return { ok: false, code: 64 };
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 1 || n > MAX_READY_WAIT_TIMEOUT_SECONDS) return { ok: false, code: 64 };
+      timeoutSeconds = n;
+      i++;
+      continue;
+    }
+    // Any unknown flag or positional argument is a usage error.
+    return { ok: false, code: 64 };
+  }
+  // --timeout only applies to --wait; pairing it with a single probe is a usage error.
+  if (timeoutSeconds !== undefined && !wait) return { ok: false, code: 64 };
+  return {
+    ok: true,
+    args: {
+      json,
+      wait,
+      timeoutSeconds: timeoutSeconds ?? DEFAULT_READY_WAIT_TIMEOUT_SECONDS,
+    },
+  };
+}
+
+export interface ReadyLive {
+  pid: number | null;
+  port: number;
+  hostname?: string;
+}
+
+export interface ReadyProbe {
+  ready: boolean;
+  status: "ready" | "pending" | "failed" | null;
+  pid: number | null;
+  port: number | null;
+}
+
+export interface ReadyIo {
+  /**
+   * Injected proxy discovery (defaults to the identity-checked findLiveProxy).
+   * Receives the positive remaining deadline budget (ms) in the --wait path so
+   * the production default can bound its fetch by the single deadline; receives
+   * `undefined` in the non-wait path so the default keeps its built-in timeout.
+   */
+  findLive?: (remainingMs: number | undefined) => Promise<ReadyLive | null>;
+  /**
+   * Injected readiness probe (defaults to the strict probeReadiness). The third
+   * argument is the positive remaining deadline budget (ms) in the --wait path,
+   * and `undefined` in the non-wait path (default probe timeout preserved).
+   */
+  probe?: (
+    port: number,
+    opts: { hostname?: string; expectedPid?: number },
+    remainingMs: number | undefined,
+  ) => Promise<ReadyProbe | null>;
+  /** Injected sleep so tests can poll without real timers. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injected clock so the deadline is deterministic without real time. */
+  now?: () => number;
+  /** Injected stdout (only `.log` is used). */
+  stdout?: { log: (s: string) => void };
+}
+
+function sanitizeProbeStatus(status: ReadyProbe["status"]): Exclude<CliReadinessStatus, "ready"> {
+  if (status === "failed") return "failed";
+  if (status === "pending") return "pending";
+  return "unreachable";
+}
+
+function report(
+  args: ReadyArgs,
+  ready: boolean,
+  status: CliReadinessStatus,
+  pid: number | null,
+  port: number | null,
+  stdout: { log: (s: string) => void },
+): void {
+  if (args.json) {
+    stdout.log(JSON.stringify({ ready, status, pid, port }));
+    return;
+  }
+  switch (status) {
+    case "ready":
+      stdout.log(`Proxy ready (PID ${pid ?? "?"}, port ${port ?? "?"})`);
+      return;
+    case "pending":
+      stdout.log("Proxy running but not ready yet (pending).");
+      return;
+    case "failed":
+      stdout.log("Proxy running but not ready (sync failed).");
+      return;
+    case "unreachable":
+      stdout.log("Proxy not reachable or readiness unavailable.");
+      return;
+  }
+}
+
+/**
+ * Run `ocx ready` over injected I/O. Returns the exit code (0 only when ready,
+ * 1 for not-ready/timeout, 64 for usage errors — though usage errors are
+ * normally caught by parseReadyArgs before this runs). The runner performs NO
+ * real subprocess/network work when the io injections are supplied.
+ */
+export async function runReady(args: ReadyArgs, io: ReadyIo = {}): Promise<number> {
+  const find = io.findLive ?? (async (remainingMs: number | undefined) => {
+    // In the --wait path, forward an ABSOLUTE deadline derived from the real
+    // wall clock (Date.now, NOT the injected logical now) plus the remaining
+    // budget: the per-probe AbortSignal timeout is real wall-clock time, so the
+    // injected test clock must not govern the network deadline. findLiveProxy's
+    // deadlineAt budget recomputes remaining before each candidate probe and
+    // bounds each fetch by it (plus the per-probe cap below). Non-wait path
+    // keeps the built-in default.
+    // verifyPidFn is disabled: readiness is non-destructive, so the killable-pid
+    // OS command-line verification (WMIC/PowerShell, seconds on Windows) would
+    // run OUTSIDE the deadline budget for no readiness value. The /healthz
+    // identity marker and the strict /readyz contract validation remain.
+    const live = await findLiveProxy(
+      remainingMs === undefined
+        ? { verifyPidFn: () => null }
+        : { deadlineAt: Date.now() + remainingMs, timeoutMs: DEFAULT_PROBE_TIMEOUT_MS, verifyPidFn: () => null },
+    );
+    return live ? { pid: live.pid, port: live.port, hostname: live.hostname } : null;
+  });
+  const probe = io.probe ?? (async (port, opts, remainingMs) =>
+    probeReadiness(port, opts, remainingMs === undefined ? {} : { timeoutMs: capIoTimeout(remainingMs) }));
+  const sleep = io.sleep ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const now = io.now ?? Date.now;
+  const stdout = io.stdout ?? console;
+
+  if (!args.wait) {
+    // Default: exactly one identity-checked readiness probe. No wait deadline —
+    // bounded only by the probe's own default timeout (remainingMs=undefined so
+    // the production defaults keep their built-in 750ms ceiling; no semantic
+    // regression vs. the single-probe behavior).
+    const live = await find(undefined);
+    if (!live) {
+      report(args, false, "unreachable", null, null, stdout);
+      return 1;
+    }
+    const p = await probe(live.port, { hostname: live.hostname, expectedPid: live.pid ?? undefined }, undefined);
+    if (p?.ready) {
+      report(args, true, "ready", p.pid, live.port, stdout);
+      return 0;
+    }
+    const status: CliReadinessStatus = sanitizeProbeStatus(p?.status ?? null);
+    report(args, false, status, p?.pid ?? live.pid ?? null, live.port, stdout);
+    return 1;
+  }
+
+  // --wait: ONE loop bounded by a single deadline (default 45s, max 300s). The
+  // deadline is the single source of truth:
+  //  - Before EVERY discovery and EVERY probe we compute remaining = deadline -
+  //    now(); if it is non-positive we return code 1 WITHOUT starting that I/O.
+  //  - After each awaited discovery/probe we re-read the clock; reached/exceeded
+  //    means timeout wins (code 1), so a ready probe resolving at/after the
+  //    deadline does NOT promote to ready.
+  //  - No second discovery/probe may start once the deadline is reached.
+  //  - Each sleep is capped to the positive remaining time. The remaining
+  //    budget is also forwarded to the production discovery/probe defaults so
+  //    their individual fetch waits are bounded by this same deadline.
+  const deadline = now() + args.timeoutSeconds * 1000;
+  let lastStatus: CliReadinessStatus = "unreachable";
+  let lastPid: number | null = null;
+  let lastPort: number | null = null;
+  for (;;) {
+    // Before discovery: refuse to start I/O when the deadline has elapsed.
+    const remainingBeforeFind = deadline - now();
+    if (remainingBeforeFind <= 0) {
+      report(args, false, lastStatus, lastPid, lastPort, stdout);
+      return 1;
+    }
+    const live = await find(remainingBeforeFind);
+    // After discovery: re-read the clock. Reached/exceeded → timeout wins and
+    // no probe is started (no second discovery/probe after the deadline).
+    let clock = now();
+    if (clock >= deadline) {
+      report(args, false, lastStatus, lastPid, lastPort, stdout);
+      return 1;
+    }
+    if (live) {
+      lastPort = live.port;
+      // Before probe: remaining derived from the post-discovery reading
+      // (guaranteed positive because clock < deadline above). This bounds the
+      // probe's fetch wait by the single deadline.
+      const remainingBeforeProbe = deadline - clock;
+      const p = await probe(
+        live.port,
+        { hostname: live.hostname, expectedPid: live.pid ?? undefined },
+        remainingBeforeProbe,
+      );
+      lastStatus = sanitizeProbeStatus(p?.status ?? null);
+      lastPid = p?.pid ?? live.pid ?? null;
+      // After every awaited probe: re-read the clock BEFORE terminal-failed or
+      // ready handling. Reached/exceeded → timeout wins (code 1) with the last
+      // sanitized status — a failed/ready probe resolving at/after the deadline
+      // must not take the terminal-failed shortcut or promote to ready.
+      clock = now();
+      if (clock >= deadline) {
+        report(args, false, lastStatus, lastPid, live.port, stdout);
+        return 1;
+      }
+      // `failed` is terminal only while still before the deadline: the startup
+      // sync has settled unsuccessfully, so waiting cannot change this gate.
+      // Report it immediately instead of consuming the rest of the timeout.
+      if (p?.status === "failed") {
+        report(args, false, "failed", lastPid, live.port, stdout);
+        return 1;
+      }
+      if (p?.ready) {
+        report(args, true, "ready", p.pid, live.port, stdout);
+        return 0;
+      }
+    } else {
+      // Discovery stopped finding the proxy: it may have exited since the last
+      // probe. Clear the cached status/identity so a stale `pending` (or its
+      // pid/port) cannot mislead a supervisor at timeout — the honest answer is
+      // `unreachable` with no identity.
+      lastStatus = "unreachable";
+      lastPid = null;
+      lastPort = null;
+    }
+    // Cap the sleep to the positive remaining time so we never sleep past the
+    // deadline. `clock` is the latest reading (post-discovery when no live
+    // proxy was found, post-probe otherwise) and is known to be < deadline.
+    const remainingForSleep = deadline - clock;
+    if (remainingForSleep <= 0) {
+      report(args, false, lastStatus, lastPid, lastPort, stdout);
+      return 1;
+    }
+    await sleep(Math.min(POLL_INTERVAL_MS, remainingForSleep));
+  }
+}

package/src/cli/system-restart-client.ts

@@ -0,0 +1,146 @@
+import { readRuntimePort } from "../config";
+import {
+  LOCAL_ATTESTATION_CHALLENGE_HEADER,
+  LOCAL_ATTESTATION_PROOF_HEADER,
+  createLocalAttestationChallenge,
+  verifyLocalAttestationProof,
+} from "../lib/local-management-attestation";
+import {
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_CAPABILITY_VERSION,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_METHOD,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  createSystemRestartCapability,
+} from "../lib/system-restart-contract";
+import {
+  findLiveProxy,
+  isOpencodexHealthz,
+  probeHostname,
+  type HealthzIdentity,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+import type { ProxyRestartRequestOutcome } from "./tray-proxy";
+
+export const SYSTEM_RESTART_REQUEST_TIMEOUT_MS = 5_000;
+export const SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS = 4_000;
+
+export interface BoundSystemRestartDeps {
+  fetchImpl?: typeof fetch;
+  readRuntime?: typeof readRuntimePort;
+  findLive?: typeof findLiveProxy;
+  createChallenge?: () => string;
+  now?: () => number;
+}
+
+function rejected(code: string): ProxyRestartRequestOutcome {
+  return { accepted: false, uncertain: false, error: new Error(code) };
+}
+
+function uncertain(code: string): ProxyRestartRequestOutcome {
+  return { accepted: false, uncertain: true, error: new Error(code) };
+}
+
+function remaining(deadlineAt: number, now: () => number, cap: number): number {
+  return Math.max(0, Math.min(cap, deadlineAt - now()));
+}
+
+function sameRestartTarget(expected: LiveProxy, observed: LiveProxy | null): boolean {
+  return expected.pid !== null
+    && observed?.source === "runtime"
+    && observed.pid === expected.pid
+    && observed.port === expected.port;
+}
+
+/**
+ * Send one restart request to the exact runtime proxy observed by the caller.
+ *
+ * No reusable admin credential is sent. After the listener proves possession of
+ * its per-process runtime secret, the client derives a capability bound to this
+ * method, path, PID, and port. The expected PID is repeated so a replacement that
+ * wins the port between proof and POST rejects the request.
+ */
+export async function requestBoundSystemRestart(
+  target: LiveProxy,
+  deadlineAt: number,
+  deps: BoundSystemRestartDeps = {},
+): Promise<ProxyRestartRequestOutcome> {
+  if (target.source !== "runtime" || target.pid === null) return rejected("restart_target_unattested");
+
+  const now = deps.now ?? Date.now;
+  const readRuntime = deps.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(target.pid);
+  if (!runtime?.attestationSecret || runtime.pid !== target.pid || runtime.port !== target.port) {
+    return rejected("restart_target_runtime_mismatch");
+  }
+
+  const attestationBudget = remaining(deadlineAt, now, SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS);
+  if (attestationBudget <= 0) return rejected("restart_deadline_expired");
+
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const challenge = (deps.createChallenge ?? createLocalAttestationChallenge)();
+  const baseUrl = `http://${probeHostname(target.hostname)}:${target.port}`;
+  let proofResponse: Response;
+  try {
+    proofResponse = await fetchImpl(`${baseUrl}/healthz`, {
+      headers: { [LOCAL_ATTESTATION_CHALLENGE_HEADER]: challenge },
+      signal: AbortSignal.timeout(attestationBudget),
+    });
+  } catch {
+    return rejected("restart_attestation_unreachable");
+  }
+  const body = await proofResponse.json().catch(() => null) as HealthzIdentity | null;
+  const proof = proofResponse.headers.get(LOCAL_ATTESTATION_PROOF_HEADER);
+  if (
+    !proofResponse.ok
+    || !isOpencodexHealthz(body)
+    || body?.pid !== target.pid
+    || !verifyLocalAttestationProof(runtime.attestationSecret, challenge, target.pid, target.port, proof)
+  ) {
+    return rejected("restart_attestation_failed");
+  }
+  if (body.restartCapability !== SYSTEM_RESTART_CAPABILITY_VERSION) {
+    // A pre-update proxy accepts only the reusable management credential and cannot
+    // bind the operation to the attested PID. Refuse before POST rather than weakening
+    // the exact-process contract or replaying a stop/start transaction.
+    return rejected("restart_capability_unsupported");
+  }
+
+  let observed: LiveProxy | null;
+  try {
+    observed = await (deps.findLive ?? findLiveProxy)({ deadlineAt, nowFn: now });
+  } catch {
+    return rejected("restart_target_recheck_failed");
+  }
+  if (!sameRestartTarget(target, observed)) return rejected("restart_target_changed");
+
+  const capability = createSystemRestartCapability(
+    runtime.attestationSecret,
+    challenge,
+    SYSTEM_RESTART_METHOD,
+    SYSTEM_RESTART_PATH,
+    target.pid,
+    target.port,
+  );
+  if (!capability) return rejected("restart_capability_unavailable");
+
+  const requestBudget = remaining(deadlineAt, now, SYSTEM_RESTART_REQUEST_TIMEOUT_MS);
+  if (requestBudget <= 0) return rejected("restart_deadline_expired");
+  try {
+    const response = await fetchImpl(`${baseUrl}${SYSTEM_RESTART_PATH}`, {
+      method: SYSTEM_RESTART_METHOD,
+      headers: {
+        [SYSTEM_RESTART_EXPECTED_PID_HEADER]: String(target.pid),
+        [SYSTEM_RESTART_NONCE_HEADER]: challenge,
+        [SYSTEM_RESTART_CAPABILITY_HEADER]: capability,
+      },
+      signal: AbortSignal.timeout(requestBudget),
+    });
+    return response.ok ? { accepted: true } : rejected(`restart_request_http_${response.status}`);
+  } catch {
+    // The server may have accepted the restart before the response connection failed.
+    // The coordinator observes the original PID for replacement instead of replaying.
+    return uncertain("restart_request_outcome_unknown");
+  }
+}

package/src/cli/tray-proxy.ts

@@ -8,6 +8,8 @@ export interface TrayProxyServiceState {
 
 export interface TrayProxyStartIo {
   findLive: () => Promise<TrayProxyLive | null>;
+  /** Normal Start is idempotent; restart fallback refuses a target that reappeared. */
+  existingIsSuccess?: boolean;
   diagnoseService: () => TrayProxyServiceState;
   startService: () => void | Promise<void>;
   startDirect: () => void | Promise<void>;
@@ -16,10 +18,101 @@ export interface TrayProxyStartIo {
   error: (message: string) => void;
 }
 
+export interface ProxyRestartLive {
+  pid: number | null;
+  port: number;
+  hostname?: string;
+  source: "runtime" | "config";
+}
+
+export type ProxyRestartRequestOutcome =
+  | { accepted: true }
+  | { accepted: false; uncertain: boolean; error?: unknown };
+
+export type ProxyRestartResult =
+  | { ok: true; mode: "started" }
+  | { ok: true; mode: "skipped" }
+  | { ok: true; mode: "restarted"; live: ProxyRestartLive }
+  | { ok: false; phase: "start" | "identity" | "request" | "replacement"; error?: unknown };
+
+export type ProxyRestartDiscovery =
+  | { status: "live"; live: ProxyRestartLive }
+  | { status: "absent" }
+  | { status: "uncertain"; error?: unknown };
+
+export interface ProxyRestartDiscoveryIo {
+  findLive: () => Promise<ProxyRestartLive | null>;
+  waitBetweenChecks?: () => Promise<void>;
+  expired?: () => boolean;
+}
+
+export interface ProxyRestartIo {
+  findLive: () => Promise<ProxyRestartDiscovery>;
+  startWhenStopped: () => boolean | "skipped" | Promise<boolean | "skipped">;
+  requestInPlaceRestart: (
+    previous: ProxyRestartLive,
+  ) => ProxyRestartRequestOutcome | Promise<ProxyRestartRequestOutcome>;
+  waitForReplacement: (previous: ProxyRestartLive) => Promise<ProxyRestartLive | null>;
+}
+
+/**
+ * Confirm absence twice before restart is allowed to select a start-only path.
+ * A live target appearing during confirmation is uncertainty, not success: the
+ * caller must not claim it restarted a process it never asked to restart.
+ */
+export async function discoverStableProxyForRestart(
+  io: ProxyRestartDiscoveryIo,
+): Promise<ProxyRestartDiscovery> {
+  let first: ProxyRestartLive | null;
+  try {
+    first = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (first) return { status: "live", live: first };
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+
+  await (io.waitBetweenChecks ?? (() => Bun.sleep(100)))();
+  let second: ProxyRestartLive | null;
+  try {
+    second = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (second) {
+    return {
+      status: "uncertain",
+      error: new Error("restart_target_appeared_during_absence_confirmation"),
+    };
+  }
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+  return { status: "absent" };
+}
+
+export function isProxyReplacement(
+  previous: ProxyRestartLive,
+  candidate: ProxyRestartLive | null,
+): candidate is ProxyRestartLive & { pid: number } {
+  return previous.pid !== null
+    && candidate?.pid !== null
+    && candidate?.pid !== undefined
+    && candidate.source === "runtime"
+    && candidate.port === previous.port
+    && candidate.pid !== previous.pid;
+}
+
 /** Side-effect coordinator for the tray's fixed proxy-start action. */
 export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean> {
   const live = await io.findLive();
   if (live) {
+    if (io.existingIsSuccess === false) {
+      io.error("Proxy appeared while restart was confirming absence; no start was attempted.");
+      return false;
+    }
     io.info(`Proxy already running on port ${live.port}.`);
     return true;
   }
@@ -43,10 +136,64 @@ export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean>
   return true;
 }
 
-export async function runTrayProxyRestart(io: {
-  stop: () => boolean | Promise<boolean>;
-  start: () => boolean | Promise<boolean>;
-}): Promise<boolean> {
-  if (!await io.stop()) return false;
-  return io.start();
+/**
+ * Shared restart transaction for both `ocx restart` and the Windows tray.
+ *
+ * A live proxy restarts itself through POST /api/system/restart. That lifecycle owns
+ * drain, supervisor handoff, exact replacement identity, and managed-routing
+ * preservation. Re-implementing restart as `stop` + `start` here races a late service
+ * child and lets ordinary /api/stop restore native routing between the two halves.
+ * When no proxy is live there is nothing to recycle, so restart degrades to the
+ * caller's normal start path.
+ */
+export async function runProxyRestart(io: ProxyRestartIo): Promise<ProxyRestartResult> {
+  let discovery: ProxyRestartDiscovery;
+  try {
+    discovery = await io.findLive();
+  } catch (error) {
+    return { ok: false, phase: "request", error };
+  }
+
+  if (discovery.status === "uncertain") {
+    return { ok: false, phase: "request", error: discovery.error };
+  }
+
+  if (discovery.status === "absent") {
+    try {
+      const started = await io.startWhenStopped();
+      if (started === "skipped") return { ok: true, mode: "skipped" };
+      return started ? { ok: true, mode: "started" } : { ok: false, phase: "start" };
+    } catch (error) {
+      return { ok: false, phase: "start", error };
+    }
+  }
+
+  const previous = discovery.live;
+
+  if (previous.pid === null || previous.source !== "runtime") {
+    return { ok: false, phase: "identity" };
+  }
+
+  let request: ProxyRestartRequestOutcome;
+  try {
+    request = await io.requestInPlaceRestart(previous);
+  } catch (error) {
+    // The request may have reached the proxy before the response connection failed.
+    // Keep observing the original identity; never replay or fall back to stop/start.
+    request = { accepted: false, uncertain: true, error };
+  }
+
+  if (!request.accepted && !request.uncertain) {
+    return { ok: false, phase: "request", error: request.error };
+  }
+
+  try {
+    const replacement = await io.waitForReplacement(previous);
+    if (replacement) return { ok: true, mode: "restarted", live: replacement };
+    return request.accepted
+      ? { ok: false, phase: "replacement" }
+      : { ok: false, phase: "request", error: request.error };
+  } catch (error) {
+    return { ok: false, phase: "replacement", error };
+  }
 }