@yansigit/opencodex 2.31.0

package/src/cli/status-oauth.ts

@@ -0,0 +1,78 @@
+import { maskAccountId } from "../lib/privacy";
+import {
+  CODEX_HEALTH_AUTH_FAILED_NOTE,
+  CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE,
+  CODEX_HEALTH_UNAVAILABLE_NOTE,
+  MASKED_ACCOUNT_FALLBACK,
+  type OAuthAccountHealth,
+  type OAuthCliHealthReport,
+  type OAuthHealthEntry,
+} from "../oauth/health";
+
+function describeHealth(health: OAuthAccountHealth): string {
+  switch (health.status) {
+    case "healthy":
+      return "healthy";
+    case "reauth_required":
+      return "reauthentication required";
+    case "cooldown":
+      return health.reason === "rate_limit"
+        ? `rate limited until ${health.until}`
+        : `quota limited until ${health.until}`;
+    case "warning":
+      switch (health.reason) {
+        case "refresh_conflict":
+          return "refresh conflict";
+        case "metadata_mismatch":
+          return "metadata mismatch";
+        case "stale_credentials":
+          return "stale credentials";
+        default:
+          return "warning";
+      }
+    default:
+      return "unknown";
+  }
+}
+
+function formatEntryBlock(entries: OAuthHealthEntry[]): string {
+  if (entries.length === 0) return "";
+
+  const notable = entries.filter((entry) => entry.health.status !== "healthy");
+  if (notable.length === 0) return "OAuth health: ok";
+
+  const lines = ["OAuth health: warning"];
+  for (const entry of notable) {
+    const masked = maskAccountId(entry.accountId) ?? MASKED_ACCOUNT_FALLBACK;
+    lines.push(`  ${entry.provider}  ${masked}  ${describeHealth(entry.health)}`);
+    if (entry.action) {
+      lines.push(`    Action: ${entry.action}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Human-readable OAuth health block for `ocx status` (redacted account ids, no tokens). */
+export function formatOAuthHealthForStatus(
+  input: OAuthHealthEntry[] | OAuthCliHealthReport,
+): string {
+  const report: OAuthCliHealthReport = Array.isArray(input)
+    ? { entries: input, codexHealthSource: "management-api" }
+    : input;
+
+  const parts: string[] = [];
+  switch (report.codexHealthSource) {
+    case "unavailable":
+      parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+      break;
+    case "management-auth-failed":
+      parts.push(CODEX_HEALTH_AUTH_FAILED_NOTE);
+      break;
+    case "management-api-unavailable":
+      parts.push(CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE);
+      break;
+  }
+  const oauthBlock = formatEntryBlock(report.entries);
+  if (oauthBlock) parts.push(oauthBlock);
+  return parts.join("\n");
+}

package/src/cli/status.ts

@@ -0,0 +1,328 @@
+import { durableBunRuntime } from "../lib/bun-runtime";
+import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
+import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
+import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { directLocalHttpFetch } from "../server/direct-local-http";
+import type { OcxConfig } from "../types";
+import { diagnoseService, serviceLogPath } from "../service";
+import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
+import { getCodexRoutingKind } from "../codex/inject";
+import { diagnoseCodexShim } from "../codex/shim";
+import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
+import { redactSecretString, redactUserPath } from "../lib/redact";
+import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
+import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
+
+type HealthCheck = {
+  ok: boolean;
+  url: string;
+  message: string;
+  label: string;
+};
+
+export type CliStatusJson = {
+  schemaVersion: 1;
+  proxy: {
+    running: boolean;
+    pid: number | null;
+    health: {
+      ok: boolean;
+      url: string;
+      message: string;
+    };
+  };
+  dashboard: { url: string };
+  listen: {
+    port: number;
+    hostname: string | null;
+    source: "runtime" | "config";
+  };
+  paths: {
+    config: string;
+    pid: string;
+    runtime: string;
+  };
+  runtime: {
+    source: string;
+    overrideEnv?: string;
+  };
+  codexAutostart: boolean;
+  startup: StartupHealth;
+  defaultProvider: string | null;
+  config: {
+    source: "default" | "file" | "fallback";
+    error: string | null;
+  };
+  service: { summary: string };
+  codexShim: { summary: string };
+  codexPlugins: CodexPluginsDiagnostic;
+  codexRuntime: {
+    path: string;
+    version: string | null;
+    source: string;
+    newerAvailable: { path: string; version: string | null } | null;
+    warning: string | null;
+    catalogClamp: {
+      active: boolean;
+      removedEfforts: string[];
+      runtimeVersion: string | null;
+    };
+  };
+  codexHome: OrcaCodexHomeDiagnostic;
+};
+
+export type CliStatusView = {
+  json: CliStatusJson;
+  proxyLabel: string;
+  healthLabel: string;
+};
+
+
+export type ListenTarget = {
+  port: number;
+  hostname?: string;
+  source: "runtime" | "config";
+  healthUrl: string;
+  dashboardUrl: string;
+};
+
+export function selectListenTarget(
+  config: Pick<OcxConfig, "port" | "hostname">,
+  pid: number | null,
+  runtimePort: RuntimePortState | null,
+): ListenTarget {
+  const currentRuntimePort = pid && runtimePort?.pid === pid ? runtimePort : null;
+  const port = currentRuntimePort ? currentRuntimePort.port : config.port ?? 10100;
+  const hostname = currentRuntimePort ? currentRuntimePort.hostname : config.hostname;
+  return {
+    port,
+    hostname,
+    source: currentRuntimePort ? "runtime" : "config",
+    healthUrl: `http://${probeHostname(hostname)}:${port}/healthz`,
+    dashboardUrl: `http://localhost:${port}/`,
+  };
+}
+
+/** Prefer live result (including authoritative null pid) over the on-disk pid file. */
+export function resolveStatusPid(
+  live: { pid: number | null } | null,
+  pidFile: number | null,
+): number | null {
+  return live ? live.pid : pidFile;
+}
+
+export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "timed out" | "unreachable" {
+  return signal.aborted || (error instanceof Error && error.name === "AbortError")
+    ? "timed out"
+    : "unreachable";
+}
+
+async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
+  const url = target.healthUrl;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 800);
+  try {
+    const response = await directLocalHttpFetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      const message = `returned HTTP ${response.status}`;
+      return { ok: false, url, message, label: `${url} ${message}` };
+    }
+    const body = await response.json().catch(() => null) as { service?: unknown; status?: unknown; version?: unknown; uptime?: unknown } | null;
+    if (!isOpencodexHealthz(body)) {
+      const message = "responded, but not an opencodex proxy";
+      return { ok: false, url, message, label: `${url} ${message}` };
+    }
+    const version = typeof body?.version === "string" ? ` v${body.version}` : "";
+    const uptime = typeof body?.uptime === "number" ? `, uptime ${Math.round(body.uptime)}s` : "";
+    const message = `ok${version}${uptime}`;
+    return { ok: true, url, message, label: `${url} ${message}` };
+  } catch (error) {
+    const reason = proxyHealthFailureReason(error, controller.signal);
+    return { ok: false, url, message: reason, label: `${url} ${reason}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function collectStatus(): Promise<CliStatusView> {
+  const configDiagnostics = readConfigDiagnostics();
+  const config = configDiagnostics.config;
+  // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618).
+  // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and
+  // warn on malformed config.json (status --json must stay stderr-clean).
+  const live = await findLiveProxy({
+    configFn: () => ({ port: config.port, hostname: config.hostname }),
+  });
+  const pidFile = readPid();
+  // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
+  const pid = resolveStatusPid(live, pidFile);
+  const listen = live
+    ? {
+      port: live.port,
+      hostname: live.hostname,
+      source: live.source,
+      healthUrl: `http://${probeHostname(live.hostname)}:${live.port}/healthz`,
+      dashboardUrl: `http://localhost:${live.port}/`,
+    }
+    : selectListenTarget(config, pidFile, pidFile ? readRuntimePort(pidFile) : null);
+  // findLiveProxy already identity-probed /healthz; avoid a second fetch that can race.
+  const health = live
+    ? {
+      ok: true,
+      url: listen.healthUrl,
+      message: `ok (pid ${live.pid ?? "unknown"})`,
+      label: `${listen.healthUrl} ok (live)`,
+    }
+    : await checkProxyHealth(listen);
+  const bunRuntime = durableBunRuntime();
+  const service = diagnoseService();
+  // A service can be registered and still not serve: the manager reports the job
+  // either way. `live` was already identity-probed a few lines above, so cross-check
+  // rather than print registration as if it were service.
+  const serviceSummary = service.installed && !live
+    ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
+    : service.summary;
+  const codexShim = diagnoseCodexShim();
+  const codexShimSummary = codexShim.summary;
+  const startup = collectStartupHealth(config, {
+    service,
+    shim: codexShim,
+    routingKind: getCodexRoutingKind(),
+  });
+  const codexPlugins = diagnoseCodexBundledPlugins();
+  const resolvedRuntime = (() => {
+    try {
+      return resolveCodexRuntime();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
+      return {
+        runtime: { command: "codex", version: null, source: "fallback" as const },
+        failures: [{
+          command: "codex",
+          source: "fallback" as const,
+          reason: `resolve threw: ${redacted}`,
+        }],
+        replacedConfigured: undefined,
+        newerAvailable: undefined,
+      };
+    }
+  })();
+  const lastClamp = loadLastEffortClamp();
+  const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);
+  const codexHome = collectOrcaCodexHomeDiagnostic();
+  const warningParts: string[] = [];
+  if (
+    resolvedRuntime.replacedConfigured
+    && resolvedRuntime.replacedConfigured.from.command !== resolvedRuntime.runtime.command
+  ) {
+    warningParts.push(
+      `Preferred Codex runtime is unavailable; using ${displayCodexRuntimePath(resolvedRuntime.runtime.command)} instead. Run ocx doctor for diagnosis and recovery.`,
+    );
+  } else if (
+    resolvedRuntime.runtime.source === "fallback"
+    && resolvedRuntime.failures.length > 0
+    && !resolvedRuntime.runtime.version
+  ) {
+    const detail = resolvedRuntime.failures[0]?.reason;
+    warningParts.push(
+      detail
+        ? `No validated Codex runtime found (${detail}); falling back to \`codex\`. Run ocx doctor for diagnosis and recovery.`
+        : "No validated Codex runtime found; falling back to `codex`. Run ocx doctor for diagnosis and recovery.",
+    );
+  }
+  if (resolvedRuntime.newerAvailable) {
+    warningParts.push("OpenCodex is using an older Codex binary. Run ocx doctor for diagnosis and recovery.");
+  }
+  if (clampActive) {
+    warningParts.push(
+      `Catalog clamp removed: ${lastClamp!.removedEfforts.join(", ")}. Run ocx doctor for diagnosis and recovery.`,
+    );
+  }
+  // A Grok fence naming a port we are not listening on is invisible everywhere else:
+  // grok retries the refused connection on its own side, so no request — and therefore
+  // no log line — ever reaches us. Surface it here, where the live port is already known.
+  const grokDrift = (() => {
+    try {
+      return grokFenceEndpointDrift(readGrokStatus(), health.ok ? listen.port : undefined);
+    } catch {
+      return null; // reading grok's config must never break `ocx status`
+    }
+  })();
+  if (grokDrift) {
+    warningParts.push(
+      `Grok Build config points at port ${grokDrift.fencePort}, but the proxy is on `
+      + `${grokDrift.livePort}; grok turns will retry against a closed port. Run 'ocx ensure' to repoint it.`,
+    );
+  }
+  const codexRuntime = {
+    path: displayCodexRuntimePath(resolvedRuntime.runtime.command),
+    version: resolvedRuntime.runtime.version,
+    source: resolvedRuntime.runtime.source,
+    newerAvailable: resolvedRuntime.newerAvailable
+      ? {
+        path: displayCodexRuntimePath(resolvedRuntime.newerAvailable.command),
+        version: resolvedRuntime.newerAvailable.version,
+      }
+      : null,
+    warning: warningParts.length > 0 ? warningParts.join(" ") : null,
+    catalogClamp: {
+      active: clampActive,
+      removedEfforts: clampActive ? (lastClamp?.removedEfforts ?? []) : [],
+      runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
+    },
+  };
+  const proxyLabel = live
+    ? `running (PID ${live.pid ?? pid ?? "unknown"})`
+    : pid && health.ok
+      ? `running (PID ${pid})`
+      : pid
+        ? `PID file points to PID ${pid}, but health check failed`
+        : health.ok
+          ? "reachable, but PID file is missing or stale"
+          : "not running";
+
+  return {
+    proxyLabel,
+    healthLabel: health.label,
+    json: {
+      schemaVersion: 1,
+      proxy: {
+        running: Boolean(live) || Boolean(pid && health.ok),
+        pid: live?.pid ?? pid,
+        health: {
+          ok: health.ok,
+          url: health.url,
+          message: health.message,
+        },
+      },
+      dashboard: { url: listen.dashboardUrl },
+      listen: {
+        port: listen.port,
+        hostname: listen.hostname ?? null,
+        source: listen.source,
+      },
+      paths: {
+        config: getConfigPath(),
+        pid: getPidPath(),
+        runtime: bunRuntime.path,
+      },
+      runtime: {
+        source: bunRuntime.source,
+        ...(bunRuntime.source === "override" ? { overrideEnv: bunRuntime.overrideEnv } : {}),
+      },
+      codexAutostart: codexAutoStartEnabled(config),
+      startup,
+      defaultProvider: typeof config.defaultProvider === "string" ? config.defaultProvider : null,
+      config: {
+        source: configDiagnostics.source,
+        error: configDiagnostics.error,
+      },
+      service: { summary: serviceSummary },
+      codexShim: { summary: codexShimSummary },
+      codexPlugins,
+      codexRuntime,
+      codexHome,
+    },
+  };
+}

package/src/cli/system-command.ts

@@ -0,0 +1,112 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx system [status] [--json]
+  ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>] [--json]
+  ocx system startup <health|install-service|install-shim> [--json]
+  ocx system diagnostics [--json]
+  ocx system sync [--json]
+  ocx system update check [--channel <latest|preview>] [--json]
+  ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]
+  ocx system update status <job-id> [--json]`;
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const [settings, startup, memory] = await Promise.all([
+    runtimeRequest("/api/settings", {}, deps),
+    runtimeRequest("/api/startup-health", {}, deps),
+    runtimeRequest("/api/system/memory", {}, deps),
+  ]);
+  const result = { settings, startup, memory };
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const autoStart = takeBooleanOption(args, "--auto-start");
+  const streamMode = takeOption(args, "--stream-mode");
+  rejectArgs(args, USAGE);
+  if (autoStart === undefined && streamMode === undefined) {
+    const result = await runtimeRequest("/api/settings", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  const body = { ...(autoStart !== undefined ? { codexAutoStart: autoStart } : {}), ...(streamMode !== undefined ? { streamMode } : {}) };
+  const result = await runtimeRequest("/api/settings", { method: "PUT", body: JSON.stringify(body) }, deps);
+  printData(result, wantsJson, ["System settings updated."]);
+}
+
+async function startup(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "health").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  if (action === "health" || action === "status") {
+    const result = await runtimeRequest("/api/startup-health", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (action !== "install-service" && action !== "install-shim") throw new CliUsageError("startup action must be health, install-service, or install-shim", USAGE);
+  const result = await runtimeRequest("/api/startup-action", { method: "POST", body: JSON.stringify({ action }) }, deps);
+  printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? `${action} complete.`)]);
+}
+
+async function update(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "check").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    const jobId = args.shift();
+    if (!jobId) throw new CliUsageError("update job id is required", USAGE);
+    rejectArgs(args, USAGE);
+    printData(await runtimeRequest(`/api/update/status?jobId=${encodeURIComponent(jobId)}`, {}, deps), wantsJson);
+    return;
+  }
+  const channel = takeOption(args, "--channel") ?? "latest";
+  if (channel !== "latest" && channel !== "preview") throw new CliUsageError("--channel must be latest or preview", USAGE);
+  if (action === "check") {
+    rejectArgs(args, USAGE);
+    printData(await runtimeRequest(`/api/update/check?tag=${channel}`, {}, deps), wantsJson);
+    return;
+  }
+  if (action !== "run") throw new CliUsageError(`unknown update action ${action}`, USAGE);
+  const restart = takeBooleanOption(args, "--restart") ?? true;
+  const yes = takeFlag(args, "--yes");
+  if (!yes) throw new CliUsageError("update run requires --yes", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest("/api/update/run", { method: "POST", body: JSON.stringify({ tag: channel, restart }) }, deps);
+  printData(result, wantsJson, [`Update started (${channel}).`]);
+}
+
+export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "settings") await settings(rest, deps);
+    else if (sub === "startup") await startup(rest, deps);
+    else if (sub === "diagnostics") {
+      const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/diagnostics/project-config", {}, deps), wantsJson);
+    } else if (sub === "sync") {
+      const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/sync", { method: "POST" }, deps), wantsJson);
+    } else if (sub === "update") await update(rest, deps);
+    else throw new CliUsageError(`unknown system command ${sub}`, USAGE);
+  });
+}
+
+export const SYSTEM_USAGE = USAGE;

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");
+  }
+}