@iislee/opencodex 2.11.0

package/src/update/job.ts

@@ -0,0 +1,1520 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  atomicWriteFile,
+  getConfigDir,
+  loadConfig,
+  readPid,
+  readRuntimePort,
+  removePid,
+  removeRuntimePort,
+  verifyPidIdentity,
+} from "../config";
+import { isProcessAlive, killProxy } from "../lib/process-control";
+import {
+  buildWindowsElevatedArgumentList,
+  resolveTrustedWindowsPowerShellExe,
+} from "../lib/windows-elevation";
+import { stopWinswService } from "../lib/winsw";
+import { listListenPids, reclaimListenPort, scanListenPids, type ListenPidScan } from "../server/port-reclaim";
+import { dropWindowsTcpRowsForLocalPort } from "../server/windows-tcp-drop";
+import { isOpencodexHealthz, probeHostname, proxyIdentityAt, type HealthzIdentity } from "../server/proxy-liveness";
+import { isServiceInstalled, isServiceViable, readServiceBackend, stopWindows } from "../service";
+import {
+  type Channel,
+  type Installer,
+  PKG,
+  checkUpdatePackageIntegrity,
+  currentVersion,
+  defaultUpdateTag,
+  detectInstall,
+  latestVersion,
+  updateCommand,
+  updateCommandStr,
+} from "./index";
+import { isNewer } from "./notify";
+import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
+import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
+
+const RELEASE_NOTES_URL = "https://github.com/lidge-jun/opencodex/releases/latest";
+const UPDATE_JOB_FILENAME = "update-job.json";
+const UPDATE_TIMEOUT_MS = 180_000;
+const RESTART_TIMEOUT_MS = 60_000;
+const RESTART_HEALTH_TIMEOUT_MS = 30_000;
+const RESTART_STABILITY_WINDOW_MS = 15_000;
+/** Legacy active records did not persist a worker PID, so age is their only safe recovery signal. */
+export const UPDATE_JOB_LEGACY_STALE_MS = 10 * 60_000;
+/** How long update restart waits for the captured port to become bindable after stop. */
+export const RESTART_PORT_RECLAIM_MS = 30_000;
+
+export type UpdateJobStatus = "running" | "restarting" | "succeeded" | "failed";
+
+export interface UpdateCheckResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  channel: Channel;
+  installer: Installer;
+  updateAvailable: boolean;
+  canUpdate: boolean;
+  command: string;
+  releaseNotesUrl: string;
+  reason?: string;
+}
+
+export interface UpdateJobState {
+  id: string;
+  status: UpdateJobStatus;
+  startedAt: string;
+  updatedAt: string;
+  currentVersion: string;
+  latestVersion: string | null;
+  channel: Channel;
+  installer: Installer;
+  restart: boolean;
+  command: string;
+  releaseNotesUrl: string;
+  log: string[];
+  pid?: number;
+  error?: string;
+  exitCode?: number | null;
+  signal?: string | null;
+  restarted?: boolean;
+}
+
+export class UpdateJobError extends Error {
+  constructor(message: string, readonly status = 400, readonly code = "update_error") {
+    super(message);
+  }
+}
+
+export interface UpdateCheckDeps {
+  currentVersion: () => string;
+  detectInstall: () => Installer;
+  latestVersion: (tag: Channel) => string | null;
+}
+
+interface UpdateWorkerProcess {
+  pid?: number;
+  unref(): void;
+  once(event: "error", listener: (error: Error) => void): unknown;
+}
+
+export interface StartUpdateJobDeps {
+  checkForUpdateFn: (channel: Channel) => UpdateCheckResult;
+  spawnWorkerFn: (jobId: string, channel: Channel, restart: boolean) => UpdateWorkerProcess;
+  isProcessAliveFn: (pid: number) => boolean;
+  nowMs: () => number;
+}
+
+const defaultCheckDeps: UpdateCheckDeps = {
+  currentVersion,
+  detectInstall,
+  latestVersion,
+};
+
+function nodeBin(): string {
+  return process.platform === "win32" ? "node.exe" : "node";
+}
+
+/**
+ * Strict bind script: exit 0 only after listen+close. Any listen error (including
+ * Windows ghost-TCB failures under Bun) is busy — matches published `ocx start`
+ * probes that treat every listen error as unavailable.
+ */
+function strictBindProbeScript(port: number, hostname: string): string {
+  return [
+    "const net=require('net');",
+    "const s=net.createServer();",
+    "s.once('error',()=>process.exit(2));",
+    `s.listen(${Math.trunc(port)},${JSON.stringify(hostname)},()=>s.close(()=>process.exit(0)));`,
+    "setTimeout(()=>process.exit(3),2500);",
+  ].join("");
+}
+
+function spawnBindProbe(bin: string, script: string): boolean {
+  try {
+    const r = spawnSync(bin, ["-e", script], {
+      windowsHide: true,
+      timeout: 4000,
+      stdio: "ignore",
+    });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Live global package Bun — not the npm rename tree the update worker may still
+ * be executing from (`@scope/.opencodex-*`). Reject the tiny postinstall
+ * stub so probes fall back to the worker runtime instead of failing forever.
+ */
+function livePackageBunPath(): string | null {
+  const launcher = packageLauncherPath();
+  const root = join(dirname(launcher), "..");
+  for (const name of ["bun.exe", "bun"]) {
+    const candidate = join(root, "node_modules", "bun", "bin", name);
+    if (isRealBunBinary(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Port is free for post-update `ocx start` only when the runtime that will
+ * actually execute the start can bind. Prefer live package Bun; fall back to the
+ * worker runtime. Do not require a separate `node` binary (Bun-only installs).
+ */
+async function strictRuntimePortAvailable(port: number, hostname = "127.0.0.1"): Promise<boolean> {
+  const script = strictBindProbeScript(port, hostname);
+  const bun = livePackageBunPath();
+  if (bun) return spawnBindProbe(bun, script);
+  return spawnBindProbe(process.execPath, script);
+}
+
+/**
+ * Wait until netstat reports no LISTEN owners on `port` AND the start runtime
+ * can bind. Dead PIDs still appear as holders while the ghost TCB lives;
+ * SetTcpEntry is a no-op without elevation (rc 317), so wait them out.
+ */
+async function waitForGhostListenClear(
+  port: number,
+  hostname: string,
+  listPids: (port: number) => number[],
+  timeoutMs: number,
+  sleep: (ms: number) => Promise<void>,
+  aliveFn: (pid: number) => boolean = isProcessAlive,
+): Promise<{ ok: boolean; accessDenied: boolean }> {
+  const deadline = Date.now() + timeoutMs;
+  let accessDenied = false;
+  while (Date.now() < deadline) {
+    const holders = listPids(port).filter(pid => pid !== process.pid);
+    const liveHolders = holders.filter(pid => aliveFn(pid));
+    // Never SetTcpEntry while a live process still owns the port (foreign or ocx).
+    if (process.platform === "win32" && liveHolders.length === 0) {
+      try {
+        const drop = dropWindowsTcpRowsForLocalPort(port);
+        if (drop.accessDenied > 0) accessDenied = true;
+      } catch { /* best-effort */ }
+    }
+    if (holders.length === 0 && await strictRuntimePortAvailable(port, hostname)) {
+      return { ok: true, accessDenied };
+    }
+    await sleep(500);
+  }
+  return { ok: false, accessDenied };
+}
+
+function packageLauncherPath(): string {
+  // This module lives at src/update/job.ts — the launcher is <pkg-root>/bin/ocx.mjs.
+  // After `npm install -g`, import.meta.url can still point at npm's renamed temp
+  // tree (`@scope/.opencodex-*`). Prefer the live package path when that happens.
+  const fromMeta = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "bin", "ocx.mjs");
+  if (!/[\\/]\.opencodex-/i.test(fromMeta) && existsSync(fromMeta)) return fromMeta;
+  // Support both the upstream scope and this fork's publish scope.
+  for (const scope of ["iislee", "bitkyc08"]) {
+    const live = fromMeta.replace(
+      new RegExp(`[\\\\/]@${scope}[\\\\/]\\.opencodex-[^\\\\/]+`, "i"),
+      `${sep}@${scope}${sep}opencodex`,
+    );
+    if (live !== fromMeta && existsSync(live)) return live;
+  }
+  return fromMeta;
+}
+
+function formatCommand(bin: string, args: string[]): string {
+  return `${bin} ${args.join(" ")}`;
+}
+
+function manualSourceCommand(): string {
+  return "git pull && bun install && bun run build:gui";
+}
+
+export function normalizeUpdateChannel(raw: string | null | undefined, current = currentVersion()): Channel {
+  return raw === "latest" || raw === "preview" ? raw : defaultUpdateTag(current);
+}
+
+export function updateJobPath(): string {
+  return join(getConfigDir(), UPDATE_JOB_FILENAME);
+}
+
+function ensureJobDir(): void {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function writeJob(job: UpdateJobState): void {
+  ensureJobDir();
+  atomicWriteFile(updateJobPath(), `${JSON.stringify(job, null, 2)}\n`);
+}
+
+export function readUpdateJob(jobId?: string | null): UpdateJobState | null {
+  try {
+    const parsed = JSON.parse(readFileSync(updateJobPath(), "utf8")) as UpdateJobState;
+    if (jobId && parsed.id !== jobId) return null;
+    if (!parsed || typeof parsed.id !== "string" || typeof parsed.status !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function updateJob(job: UpdateJobState, patch: Partial<UpdateJobState>, logLine?: string): UpdateJobState {
+  const current = readUpdateJob(job.id) ?? job;
+  const next = {
+    ...current,
+    ...patch,
+    updatedAt: new Date().toISOString(),
+    log: logLine ? [...current.log, logLine] : current.log,
+  };
+  writeJob(next);
+  return next;
+}
+
+export function updateExecutionCommand(
+  installer: Installer,
+  channel: Channel,
+  launcher = packageLauncherPath(),
+  resolvedVersion?: string | null,
+): { bin: string; args: string[]; display: string } {
+  if (installer === "npm") {
+    const bin = nodeBin();
+    const args = [launcher, "update", "--tag", channel];
+    // The Node launcher self-update re-resolves the tag at its own time — a residual
+    // divergence window this path cannot close (documented, not claimed immutable).
+    return { bin, args, display: formatCommand(bin, args) };
+  }
+  if (installer === "bun") {
+    const command = updateCommand(installer, channel, resolvedVersion);
+    const bin = process.platform === "win32" ? process.execPath : command.bin;
+    const { args } = command;
+    return { bin, args, display: updateCommandStr(installer, channel, resolvedVersion) };
+  }
+  return { bin: "sh", args: ["-lc", manualSourceCommand()], display: manualSourceCommand() };
+}
+
+export function restartCommand(
+  serviceInstalled: boolean,
+  installer: Installer,
+  launcher = packageLauncherPath(),
+  port?: number,
+  serviceArgs?: string[],
+): { mode: "service" | "proxy"; bin: string; args: string[]; display: string } {
+  const mode = serviceInstalled ? "service" : "proxy";
+  const pinPort = !serviceInstalled && typeof port === "number" && Number.isFinite(port) && port > 0;
+  const startArgs = pinPort
+    ? [launcher, "start", "--port", String(Math.trunc(port))]
+    : [launcher, "start"];
+  const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "install"])] : startArgs;
+  if (installer === "npm") {
+    const bin = nodeBin();
+    const args = svcArgs;
+    return { mode, bin, args, display: formatCommand(bin, args) };
+  }
+  // bun/source installs: restart via the current runtime executable + package launcher (both real
+  // .exe files), NOT the `ocx.cmd` shim. Spawning a `.cmd` shell-less throws EINVAL on Windows
+  // Node/Bun ≥18.20/20.12 (CVE-2024-27980 hardening) — the same class the npm path (nodeBin) avoids.
+  const bin = process.execPath;
+  const args = svcArgs;
+  return { mode, bin, args, display: formatCommand(bin, args) };
+}
+
+export function checkForUpdate(
+  requestedChannel?: Channel,
+  deps: UpdateCheckDeps = defaultCheckDeps,
+): UpdateCheckResult {
+  const current = deps.currentVersion();
+  const installer = deps.detectInstall();
+  const channel = requestedChannel ?? normalizeUpdateChannel(null, current);
+  // Always resolve the registry version so the dashboard can show local vs remote,
+  // even for source checkouts (which stay manual-only for installation).
+  const latest = deps.latestVersion(channel);
+  const updateAvailable = !!latest && isNewer(latest, current, channel);
+  let reason: string | undefined;
+  let command = installer === "source" ? manualSourceCommand() : updateExecutionCommand(installer, channel).display;
+
+  if (installer === "source") {
+    reason = "source_checkout";
+    command = manualSourceCommand();
+  } else if (!latest) {
+    reason = "latest_unavailable";
+  } else if (!updateAvailable) {
+    reason = "already_latest";
+  }
+
+  return {
+    currentVersion: current,
+    latestVersion: latest,
+    channel,
+    installer,
+    updateAvailable,
+    canUpdate: installer !== "source" && updateAvailable,
+    command,
+    releaseNotesUrl: RELEASE_NOTES_URL,
+    ...(reason ? { reason } : {}),
+  };
+}
+
+function newJobId(): string {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * [Decision Log]
+ * - Purpose: recover dashboard updates after a detached worker dies without unlocking concurrent live updates.
+ * - Existing constraints: legacy records have no PID, while a healthy update may legitimately run for minutes.
+ * - Alternatives considered: clear every active record by age, or require operators to delete the file manually.
+ * - Chosen approach: trust PID liveness first and use a conservative age limit only for legacy no-PID records.
+ * - Why: age-only recovery can start two installers, while never recovering leaves the dashboard permanently blocked.
+ * - Impact: live PID records remain locked regardless of age; dead PIDs recover immediately; legacy records recover after ten minutes.
+ */
+export function staleActiveUpdateJobReason(
+  job: Pick<UpdateJobState, "status" | "pid" | "updatedAt">,
+  now = Date.now(),
+  isAlive: (pid: number) => boolean = isProcessAlive,
+): string | null {
+  if (job.status !== "running" && job.status !== "restarting") return null;
+  if (typeof job.pid === "number" && Number.isSafeInteger(job.pid) && job.pid > 0) {
+    return isAlive(job.pid) ? null : `update worker PID ${job.pid} is no longer running`;
+  }
+  const updatedAt = Date.parse(job.updatedAt);
+  if (Number.isFinite(updatedAt) && now - updatedAt >= UPDATE_JOB_LEGACY_STALE_MS) {
+    return "legacy active update record has no worker PID and exceeded the stale window";
+  }
+  return null;
+}
+
+/**
+ * Spawn the GUI update worker without inheriting the proxy's LISTEN socket.
+ *
+ * On Windows, `spawn(..., { detached: true, stdio: "ignore" })` still inherits
+ * inheritable handles — including Bun.serve's LISTEN socket. After stop-first
+ * update kills the proxy PID, netstat keeps showing that dead PID as LISTENING
+ * until every inheriting child exits. The update worker was that child, so the
+ * port stayed busy for the whole job. Launch via PowerShell Start-Process so
+ * the worker is a fresh process tree with no inherited LISTEN handle.
+ */
+export function spawnGuiUpdateWorker(
+  jobId: string,
+  channel: Channel,
+  restart: boolean,
+): UpdateWorkerProcess {
+  const script = process.argv[1];
+  const args = [
+    script,
+    "__gui-update-worker",
+    jobId,
+    channel,
+    restart ? "restart" : "no-restart",
+  ];
+  if (process.platform !== "win32") {
+    return spawn(process.execPath, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: { ...process.env, OCX_SERVICE: "1" },
+    });
+  }
+
+  // Single -ArgumentList string with CommandLineToArgvW quoting so paths with
+  // spaces survive Start-Process's space-join (array elements lose outer quotes).
+  const psQuote = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+  const argumentList = buildWindowsElevatedArgumentList(args);
+  const ps = [
+    `$env:OCX_SERVICE = '1'`,
+    `$p = Start-Process -FilePath ${psQuote(process.execPath)} -ArgumentList ${psQuote(argumentList)} -WindowStyle Hidden -PassThru`,
+    `if (-not $p) { exit 1 }`,
+    `Write-Output $p.Id`,
+  ].join("; ");
+  const launched = spawnSync(
+    resolveTrustedWindowsPowerShellExe(),
+    ["-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps],
+    { encoding: "utf8", windowsHide: true, timeout: 15_000 },
+  );
+  const pid = Number(String(launched.stdout ?? "").trim().split(/\r?\n/).pop());
+  if (launched.status !== 0 || !Number.isSafeInteger(pid) || pid <= 0) {
+    const detail = String(launched.stderr ?? launched.stdout ?? "").trim() || `status ${launched.status}`;
+    throw new Error(`Windows update worker Start-Process failed: ${detail}`);
+  }
+  return {
+    pid,
+    unref() { /* Start-Process already detached */ },
+    once() { /* startup errors are not wired across Start-Process */ },
+  };
+}
+
+const defaultStartUpdateJobDeps: StartUpdateJobDeps = {
+  checkForUpdateFn: channel => checkForUpdate(channel),
+  spawnWorkerFn: spawnGuiUpdateWorker,
+  isProcessAliveFn: isProcessAlive,
+  nowMs: Date.now,
+};
+
+export function startUpdateJob(
+  channel: Channel,
+  restart: boolean,
+  deps: Partial<StartUpdateJobDeps> = {},
+): UpdateJobState {
+  const resolvedDeps = { ...defaultStartUpdateJobDeps, ...deps };
+  const running = readUpdateJob();
+  if (running?.status === "running" || running?.status === "restarting") {
+    const staleReason = staleActiveUpdateJobReason(
+      running,
+      resolvedDeps.nowMs(),
+      resolvedDeps.isProcessAliveFn,
+    );
+    if (!staleReason) {
+      throw new UpdateJobError("An update job is already running", 409, "update_already_running");
+    }
+    updateJob(
+      running,
+      { status: "failed", error: `Recovered stale update job: ${staleReason}.`, exitCode: null },
+      `Recovered stale update job: ${staleReason}.`,
+    );
+  }
+
+  const check = resolvedDeps.checkForUpdateFn(channel);
+  if (!check.canUpdate) {
+    throw new UpdateJobError(check.reason ?? "No update is available", 409, check.reason ?? "update_unavailable");
+  }
+
+  const id = newJobId();
+  const now = new Date(resolvedDeps.nowMs()).toISOString();
+  const job: UpdateJobState = {
+    id,
+    status: "running",
+    startedAt: now,
+    updatedAt: now,
+    currentVersion: check.currentVersion,
+    latestVersion: check.latestVersion,
+    channel: check.channel,
+    installer: check.installer,
+    restart,
+    command: check.command,
+    releaseNotesUrl: check.releaseNotesUrl,
+    log: [`Update job queued for ${check.currentVersion} -> ${check.latestVersion}.`],
+  };
+  writeJob(job);
+
+  let child: UpdateWorkerProcess;
+  try {
+    child = resolvedDeps.spawnWorkerFn(id, channel, restart);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    updateJob(job, { status: "failed", error: `Could not start update worker: ${message}` }, "Update worker failed to start.");
+    throw new UpdateJobError("Could not start update worker", 500, "update_worker_start_failed");
+  }
+  if (typeof child.pid !== "number" || !Number.isSafeInteger(child.pid) || child.pid <= 0) {
+    updateJob(job, { status: "failed", error: "Could not start update worker: no worker PID was returned." }, "Update worker failed to start.");
+    throw new UpdateJobError("Could not start update worker", 500, "update_worker_start_failed");
+  }
+  const startedJob = updateJob(job, { pid: child.pid }, `Update worker started as PID ${child.pid}.`);
+  child.once("error", error => {
+    const current = readUpdateJob(id);
+    if (!current || current.pid !== child.pid || (current.status !== "running" && current.status !== "restarting")) return;
+    updateJob(
+      current,
+      { status: "failed", error: `Update worker failed to start: ${error.message}` },
+      "Update worker emitted a startup error.",
+    );
+  });
+  child.unref();
+  return startedJob;
+}
+
+function runLoggedCommand(job: UpdateJobState, bin: string, args: string[], timeout: number): { status: number | null; signal: NodeJS.Signals | null } {
+  job = updateJob(job, {}, `$ ${formatCommand(bin, args)}`);
+  const result = spawnSync(bin, args, {
+    encoding: "utf8",
+    timeout,
+    windowsHide: true,
+  });
+  const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
+  const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+  if (stdout) job = updateJob(job, {}, stdout.slice(-4000));
+  if (stderr) updateJob(job, {}, stderr.slice(-4000));
+  return { status: result.status, signal: result.signal };
+}
+
+/**
+ * Tear down anything that would make `ocx start` exit 1 with "already running"
+ * (service wrapper respawn, stale pidfile + live /healthz) before a pinned spawn.
+ */
+function preparePortForPinnedStart(
+  job: UpdateJobState,
+  port: number,
+  listPids: (port: number) => number[],
+  aliveFn: (pid: number) => boolean,
+  verifyOcx: (pid: number) => number | null = verifyPidIdentity,
+): void {
+  stopWindowsServiceWrappersBestEffort();
+  const pid = readPid();
+  if (pid) {
+    updateJob(job, {}, `Clearing pre-start proxy PID ${pid} before pinned start.`);
+    try { killProxy(pid); } catch { /* best-effort */ }
+    removePid(pid);
+  } else {
+    removePid();
+  }
+  removeRuntimePort();
+  for (const holder of listPids(port)) {
+    if (holder === process.pid || !aliveFn(holder)) continue;
+    if (verifyOcx(holder) !== holder) {
+      updateJob(
+        job,
+        {},
+        `Leaving foreign listen holder PID ${holder} on port ${port}; refusing collateral kill.`,
+      );
+      continue;
+    }
+    updateJob(job, {}, `Stopping live ocx listen holder PID ${holder} on port ${port} before pinned start.`);
+    try { killProxy(holder); } catch { /* best-effort */ }
+  }
+  // Match reclaimListenPort: never SetTcpEntry while a live holder remains.
+  const liveRemain = listPids(port).filter(pid => pid !== process.pid && aliveFn(pid));
+  if (process.platform === "win32" && liveRemain.length === 0) {
+    try { dropWindowsTcpRowsForLocalPort(port); } catch { /* best-effort */ }
+  }
+}
+
+function spawnDetachedStart(
+  job: UpdateJobState,
+  installer: Installer,
+  port?: number,
+): ChildProcess {
+  const cmd = restartCommand(false, installer, packageLauncherPath(), port);
+  const env = { ...process.env };
+  delete env.OCX_SERVICE;
+  updateJob(job, {}, `$ ${cmd.display}`);
+  let stdio: "ignore" | [ "ignore", number, number ] = "ignore";
+  let logFd: number | undefined;
+  try {
+    const logPath = join(getConfigDir(), "update-pinned-start.log");
+    mkdirSync(getConfigDir(), { recursive: true });
+    logFd = openSync(logPath, "a");
+    writeSync(logFd, `\n--- ${new Date().toISOString()} ---\n$ ${cmd.display}\n`);
+    stdio = ["ignore", logFd, logFd];
+  } catch { /* fall back to ignored stdio */ }
+  const child = spawn(cmd.bin, cmd.args, {
+    detached: true,
+    stdio,
+    windowsHide: true,
+    env,
+  });
+  child.once("error", err => {
+    try {
+      updateJob(job, {}, `Pinned start spawn error: ${err instanceof Error ? err.message : String(err)}`);
+    } catch { /* best-effort */ }
+  });
+  // Foreground `ocx start` keeps the listen process; EADDRINUSE/ghost races exit quickly
+  // with stdio ignored — surface that so the job log explains a silent miss.
+  child.once("exit", (code, signal) => {
+    if (code === 0 && !signal) return;
+    try {
+      updateJob(
+        job,
+        {},
+        `Pinned start exited early (code=${code ?? "null"} signal=${signal ?? "null"}).`,
+      );
+    } catch { /* best-effort */ }
+  });
+  child.unref();
+  return child;
+}
+
+/** Identity snapshot used to prove an npm self-update actually replaced the pre-update process. */
+export interface RestartProxyIdentity {
+  pid: number | null;
+  version?: string;
+}
+
+/** Test seam: the wait/spawn pair is injectable so the restart path is verifiable. */
+export interface RestartIo {
+  waitForPort?: typeof reclaimListenPort;
+  spawnStart?: (job: UpdateJobState, installer: Installer, port?: number) => void;
+  serviceInstalledFn?: () => boolean;
+  /**
+   * After a service reinstall exits 0, only trust the service path when this is true.
+   * Defaults to {@link isServiceViable} — installed-but-stale assets must fall through
+   * to a direct proxy start so dashboard updates never leave /healthz dead.
+   */
+  serviceViableFn?: () => boolean;
+  probeProxy?: (port: number, hostname?: string) => Promise<boolean>;
+  /** Richer /healthz read for update-correlated restart evidence (pid + version). */
+  probeProxyIdentity?: (port: number, hostname?: string) => Promise<RestartProxyIdentity | null>;
+  /** Override the /healthz appearance window (default {@link RESTART_HEALTH_TIMEOUT_MS}). */
+  healthTimeoutMs?: number;
+  /**
+   * Override the window for deciding whether a service-managed restart actually
+   * served (default {@link SERVICE_RECOVERY_HEALTH_MS}). Distinct from
+   * {@link healthTimeoutMs}, which is the FINAL /healthz appearance window consumed
+   * by awaitRestartedProxyHealthy: this one only chooses whether to ALSO attempt a
+   * direct start, so coupling them would let a test tightening one silently retune
+   * the other.
+   */
+  serviceHealthTimeoutMs?: number;
+  sleepMs?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** Service-mode install/reinstall command (defaults to spawnSync via runLoggedCommand). */
+  runService?: (
+    job: UpdateJobState,
+    bin: string,
+    args: string[],
+  ) => { status: number | null; signal?: NodeJS.Signals | null };
+  /** Override the explicit restart path (used by finishGuiUpdateRestart tests). */
+  restartAfterUpdateFn?: (
+    job: UpdateJobState,
+    captured?: { port: number; hostname: string; oldPid?: number },
+    io?: RestartIo,
+  ) => Promise<void>;
+  /**
+   * PIDs currently LISTENing on the captured port. Used to widen the post-update
+   * kill allowlist beyond the pre-update PID (Windows often leaves a respawned
+   * ocx child that would otherwise be treated as a protected listener).
+   */
+  listListenPidsFn?: (port: number) => number[];
+  /**
+   * Full listen-PID scan (ok/fail). When omitted, {@link scanListenPids} is used
+   * so a probe failure is not mistaken for "no listeners".
+   */
+  scanListenPidsFn?: (port: number) => ListenPidScan;
+  /** Identity check for listeners discovered via {@link listListenPidsFn}. */
+  verifyOcxFn?: (pid: number) => number | null;
+  /** Liveness check when deciding whether a reclaim timeout still has live holders. */
+  isAliveFn?: (pid: number) => boolean;
+}
+
+/**
+ * Health window for deciding whether a service-managed restart served, before
+ * falling back to a direct start. Deliberately shorter than the final verdict
+ * window: being wrong here costs one extra start attempt; being wrong the other way
+ * leaves the user with no proxy at all.
+ *
+ * It runs AFTER the child's own 20s install probe (SERVICE_INSTALL_HEALTH_MS on
+ * macOS/Linux), so a reinstall that exits 0 but never serves spends up to 45s before
+ * the fallback — inside RESTART_TIMEOUT_MS of 60s. That is why this is 25s, not more.
+ */
+export const SERVICE_RECOVERY_HEALTH_MS = 25_000;
+
+/**
+ * Whether the reinstalled service actually produced a listener on the captured target.
+ *
+ * Not a duplicate of the child's own check: since WP2 the child asserts the port on
+ * macOS/Linux, but Windows still reports success from registration alone, a flapping
+ * supervisor can satisfy a single probe, and the child may be a CLI older than that
+ * change. `isServiceViable()` cannot see any of those — it reads registration state.
+ */
+async function serviceRestartServed(
+  job: UpdateJobState,
+  port: number,
+  hostname: string,
+  io: RestartIo = {},
+): Promise<boolean> {
+  const probe = io.probeProxy ?? (async (p: number, h?: string) => (
+    !!(await proxyIdentityAt(p, { hostname: h }))
+  ));
+  const sleep = io.sleepMs ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
+  const now = io.now ?? (() => Date.now());
+  const deadline = now() + (io.serviceHealthTimeoutMs ?? SERVICE_RECOVERY_HEALTH_MS);
+  for (;;) {
+    if (await probe(port, hostname)) {
+      updateJob(job, {}, `Service-managed proxy answered on ${hostname}:${port}.`);
+      return true;
+    }
+    if (now() >= deadline) return false;
+    await sleep(500);
+  }
+}
+
+async function restartAfterUpdate(
+  job: UpdateJobState,
+  captured?: { port: number; hostname: string; oldPid?: number },
+  io: RestartIo = {},
+): Promise<void> {
+  const serviceInstalled = (io.serviceInstalledFn ?? isServiceInstalled)();
+  const config = loadConfig();
+  // The stop-first update flow has already cleared pid/runtime state by the time we run,
+  // so the pre-update capture (taken before the update command) is the authoritative
+  // port to wait on; config is only the cold-start fallback.
+  const port = captured?.port ?? config.port ?? 10100;
+  const hostname = captured?.hostname ?? config.hostname ?? "127.0.0.1";
+  const oldPid = typeof captured?.oldPid === "number" && captured.oldPid > 0
+    ? captured.oldPid
+    : undefined;
+  let svcArgs: string[] | undefined;
+  if (serviceInstalled) {
+    try {
+      const { serviceReinstallArgs } = await import("../service");
+      svcArgs = serviceReinstallArgs();
+    } catch { /* fallback to default service install */ }
+  }
+  const cmd = restartCommand(serviceInstalled, job.installer, packageLauncherPath(), port, svcArgs);
+  const waitFn = io.waitForPort ?? reclaimListenPort;
+  const listPids = io.listListenPidsFn ?? listListenPids;
+  const verifyOcx = io.verifyOcxFn ?? verifyPidIdentity;
+  const aliveFn = io.isAliveFn ?? isProcessAlive;
+  // Pre-update PID plus any ocx still LISTENing on the captured port. After a
+  // stop-first npm self-update Windows often leaves a respawned bun/node child
+  // that is not the captured PID; treating it as protected blocks reclaim and
+  // the direct-start fallback never binds.
+  const reclaimKillAllowlist = (): number[] => {
+    const allow = new Set<number>();
+    if (oldPid != null) allow.add(oldPid);
+    for (const pid of listPids(port)) {
+      if (pid === process.pid) continue;
+      if (verifyOcx(pid) === pid) allow.add(pid);
+    }
+    return [...allow];
+  };
+  const reclaimOptsFor = (onlyKillPids: number[]) => ({
+    timeoutMs: RESTART_PORT_RECLAIM_MS,
+    intervalMs: 100,
+    scanIntervalMs: 500,
+    killOcxHolders: true,
+    // Windows scheduler wrappers can mint a *new* bun PID during the wait; keep
+    // killing every ocx listener on this port, not only the pre-wait snapshot.
+    // npm rename trees under `@scope/.opencodex-*` are classified as ocx by
+    // isOcxStartCommandLine — never kill unknown foreign claimants on this port.
+    killAllOcxOnPort: true,
+    onlyKillPids,
+  });
+
+  if (serviceInstalled) {
+    // schtasks /end often leaves the hidden cmd/wscript wrapper alive; its :loop
+    // respawns `ocx start` a few seconds later and races port reclaim. End the
+    // task again and best-effort kill those wrappers before we touch the socket.
+    stopWindowsServiceWrappersBestEffort();
+    // Stop-first update already unloaded the service; reclaim the socket, then
+    // reinstall wrappers that bake `--port`.
+    const preServiceAllow = reclaimKillAllowlist();
+    const freed = await waitFn(port, hostname, reclaimOptsFor(preServiceAllow));
+    let skipServiceInstall = false;
+    // Windows GUI update worker sets OCX_SERVICE=1 and is never elevated.
+    // `schtasks /create` will UAC-fail and can race the subsequent direct start.
+    // Keep systemd/launchd reinstall on non-Windows supervisors.
+    if (process.platform === "win32" && process.env.OCX_SERVICE === "1") {
+      updateJob(job, {}, "Skipping service reinstall from the non-elevated update worker; falling back to a direct proxy start.");
+      skipServiceInstall = true;
+    }
+    if (!freed && !skipServiceInstall) {
+      updateJob(
+        job,
+        {},
+        `Port ${port} still busy after ${Math.trunc(RESTART_PORT_RECLAIM_MS / 1000)}s; refusing to hop — reinstall may fail until the port is free.`
+          + ` ${formatPortHolders(port, listPids, verifyOcx, preServiceAllow)}`,
+      );
+      const liveAfter = listPids(port).filter(pid => pid !== process.pid && aliveFn(pid));
+      if (liveAfter.length === 0) {
+        // Non-elevated `service install` will UAC-fail anyway; skip straight to
+        // the direct-start fallthrough instead of burning another minute on it.
+        updateJob(job, {}, "Skipping service reinstall after reclaim timeout with no live holders; falling back to a direct proxy start.");
+        skipServiceInstall = true;
+      }
+    }
+    if (!skipServiceInstall) {
+      const prevBake = process.env.OCX_BAKE_PORT;
+      process.env.OCX_BAKE_PORT = String(Math.trunc(port));
+      let serviceOk = false;
+      try {
+        const run = io.runService ?? ((j, bin, args) => runLoggedCommand(j, bin, args, RESTART_TIMEOUT_MS));
+        const result = run(job, cmd.bin, cmd.args);
+        serviceOk = result.status === 0;
+        if (!serviceOk) {
+          // On Windows, `schtasks /create` requires an elevated token. The update worker
+          // inherits the (non-admin) proxy's privileges, so a service-managed install
+          // updated from the GUI or a normal terminal fails here with access denied.
+          // Falling back to a direct proxy start keeps the update from leaving the proxy
+          // stopped; the stale service manager can be refreshed later with an admin
+          // `ocx service install`.
+          //
+          // That advice is Windows-only, and on macOS/Linux it now actively misleads:
+          // `ocx service install` gained a non-zero exit for a service that registers
+          // but does not serve, so this branch fires there for a reason elevation
+          // cannot fix. Point at the command that prints the real reason instead.
+          updateJob(
+            job,
+            {},
+            `Service reinstall failed (exit ${result.status ?? "?"}); falling back to a direct proxy start.`
+            + (process.platform === "win32"
+              ? " Run 'ocx service install' as administrator to refresh the background service manager."
+              : " Run 'ocx service install' by hand to see the reason, then 'ocx service status'."),
+          );
+        }
+      } finally {
+        if (prevBake === undefined) delete process.env.OCX_BAKE_PORT;
+        else process.env.OCX_BAKE_PORT = prevBake;
+      }
+      if (serviceOk) {
+        // Exit 0 is not enough, and neither is `viable`. Registration state cannot
+        // distinguish a serving supervisor from one that registered and bound nothing:
+        // `launchctl list` reports both, and `schtasks` reports a task whose child
+        // exited immediately. Since WP2 the child asserts the port itself on
+        // macOS/Linux, but Windows still reports success from registration alone, a
+        // flapping supervisor can satisfy one probe, and the child may be an older CLI.
+        // Ask the port before skipping the fallback this branch exists to protect.
+        const viable = (io.serviceViableFn ?? isServiceViable)();
+        if (viable) {
+          if (await serviceRestartServed(job, port, hostname, io)) return;
+          updateJob(
+            job,
+            {},
+            `Service reinstall exited 0 and reported viable, but nothing answered on ${hostname}:${port} `
+            + `within ${Math.trunc((io.serviceHealthTimeoutMs ?? SERVICE_RECOVERY_HEALTH_MS) / 1000)}s; `
+            + "falling back to a direct proxy start.",
+          );
+        } else {
+          updateJob(
+            job,
+            {},
+            "Service reinstall exited 0 but the background service is not viable (stale or missing assets, disabled, or conflicting); falling back to a direct proxy start.",
+          );
+        }
+      }
+    }
+    // Fall through to the direct proxy start below so the update never leaves the
+    // proxy stopped when the service reinstall could not run or did not leave a
+    // viable supervisor.
+  }
+
+  const pid = readPid();
+  if (pid) {
+    updateJob(job, {}, `Stopping current proxy PID ${pid}.`);
+    try {
+      killProxy(pid);
+    } catch {
+      // A PID that resists taskkill must not abort recovery: reclaim + pinned start
+      // below are the path that repairs stuck Windows listeners.
+    }
+  }
+  if (serviceInstalled) stopWindowsServiceWrappersBestEffort();
+  // Reclaim the captured port before the pinned start. Spawning `--port` while the old
+  // socket is still busy is how Windows updates used to fail health checks (or hop).
+  // killAllOcxOnPort covers wrapper-respawned bun PIDs minted during the wait.
+  const directAllow = reclaimKillAllowlist();
+  const freed = await waitFn(port, hostname, reclaimOptsFor(directAllow));
+  if (!freed) {
+    const liveHolders = listPids(port).filter(pid => pid !== process.pid && aliveFn(pid));
+    updateJob(
+      job,
+      {},
+      `Port ${port} still busy after ${Math.trunc(RESTART_PORT_RECLAIM_MS / 1000)}s (reclaim could not free the socket).`
+        + ` ${formatPortHolders(port, listPids, verifyOcx, directAllow)}`,
+    );
+    if (liveHolders.length > 0) {
+      updateJob(job, {}, `Live holder(s) remain on port ${port}; not starting on another port. Retry 'ocx start --port ${port}'.`);
+      return;
+    }
+    // Dead PIDs can still own LISTEN rows. SetTcpEntry needs elevation (rc 317 on a
+    // normal update worker), so poll until netstat is empty and the start runtime can bind.
+    updateJob(
+      job,
+      {},
+      `No live holders on port ${port}; waiting for ghost LISTEN rows to clear before pinned start.`,
+    );
+    // Injected spawnStart is the unit-test seam — skip the long OS wait.
+    if (!io.spawnStart) {
+      const sleep = io.sleepMs ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
+      const cleared = await waitForGhostListenClear(port, hostname, listPids, 90_000, sleep);
+      if (cleared.accessDenied) {
+        updateJob(job, {}, "SetTcpEntry is non-elevated (access denied); relying on OS ghost-LISTEN expiry.");
+      }
+      if (!cleared.ok) {
+        updateJob(
+          job,
+          {},
+          `Ghost LISTEN rows on port ${port} did not clear in time. `
+            + `${formatPortHolders(port, listPids, verifyOcx, directAllow)} `
+            + `Retry 'ocx start --port ${port}'.`,
+        );
+        return;
+      }
+    }
+  }
+  // Injected spawnStart keeps unit tests deterministic (one call). Production path
+  // retries on missing /healthz after prepare + ghost-LISTEN clear.
+  if (io.spawnStart) {
+    io.spawnStart(job, job.installer, port);
+    return;
+  }
+  const sleep = io.sleepMs ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
+  const probe = io.probeProxy ?? (async (p: number, host?: string) => (
+    !!(await proxyIdentityAt(p, { hostname: host }))
+  ));
+  const probeIdentity = io.probeProxyIdentity ?? defaultProbeProxyIdentity;
+  const expectedVersion = typeof job.latestVersion === "string" && job.latestVersion.length > 0
+    ? job.latestVersion
+    : null;
+  // Service wrappers can respawn a listener during reclaim; if it already reports the
+  // update target version, do not spawn a second start that exits "already running".
+  {
+    const identity = await probeIdentity(port, hostname);
+    if (identity && expectedVersion && identity.version === expectedVersion) {
+      updateJob(
+        job,
+        {},
+        `Proxy already healthy on ${hostname}:${port} at ${expectedVersion}; skipping pinned start.`,
+      );
+      return;
+    }
+  }
+  const attempts = 3;
+  // Longer than published hard-pin reclaim (30s) so a slow start can still report healthy.
+  const perAttemptHealthMs = 70_000;
+  let lastChild: ChildProcess | null = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (attempt > 1) {
+      updateJob(
+        job,
+        {},
+        `Pinned start attempt ${attempt - 1} did not become healthy on port ${port}; `
+          + `retrying (${attempt}/${attempts}).`,
+      );
+      if (lastChild?.pid && aliveFn(lastChild.pid)) {
+        try { killProxy(lastChild.pid); } catch { /* best-effort */ }
+      }
+      lastChild = null;
+    }
+    preparePortForPinnedStart(job, port, listPids, aliveFn, verifyOcx);
+    const ready = await waitForGhostListenClear(
+      port,
+      hostname,
+      listPids,
+      attempt === 1 ? (freed ? 15_000 : 5_000) : 30_000,
+      sleep,
+    );
+    if (!ready.ok) {
+      updateJob(
+        job,
+        {},
+        `Port ${port} not bindable before pinned start attempt ${attempt}; `
+          + `${formatPortHolders(port, listPids, verifyOcx, directAllow)}`,
+      );
+      continue;
+    }
+    lastChild = spawnDetachedStart(job, job.installer, port);
+    const healthDeadline = Date.now() + perAttemptHealthMs;
+    while (Date.now() < healthDeadline) {
+      if (await probe(port, hostname)) return;
+      await sleep(500);
+    }
+  }
+  // Exhausted retries: do not leave a hung pinned-start child owning the port.
+  if (lastChild?.pid && aliveFn(lastChild.pid)) {
+    try { killProxy(lastChild.pid); } catch { /* best-effort */ }
+  }
+}
+
+/** Compact listen-holder summary for update-job logs when reclaim fails. */
+function formatPortHolders(
+  port: number,
+  listPids: (port: number) => number[],
+  verifyOcx: (pid: number) => number | null,
+  allow: number[],
+): string {
+  const allowSet = new Set(allow);
+  const holders = listPids(port).map(pid => {
+    const tags = [
+      verifyOcx(pid) === pid ? "ocx" : "foreign",
+      allowSet.has(pid) ? "allow" : "deny",
+      isProcessAlive(pid) ? "live" : "dead",
+    ];
+    return `${pid}(${tags.join(",")})`;
+  });
+  return `holders=[${holders.join(", ") || "none"}] allow=[${allow.join(", ") || "none"}]`;
+}
+
+/** Stop the installed Windows backend and best-effort kill surviving :loop wrappers. */
+function stopWindowsServiceWrappersBestEffort(): void {
+  if (process.platform !== "win32") return;
+  try {
+    if (readServiceBackend() === "native") {
+      stopWinswService();
+      return;
+    }
+    stopWindows();
+  } catch { /* already stopped */ }
+  killWindowsServiceWrapperProcesses();
+}
+
+/**
+ * Best-effort termination of surviving Windows scheduler launcher/wrapper processes.
+ * `schtasks /end` ends the task instance but often leaves wscript/cmd running the
+ * `:loop` batch, which brings the proxy back during post-update reclaim.
+ */
+function killWindowsServiceWrapperProcesses(): void {
+  if (process.platform !== "win32") return;
+  try {
+    const ps = [
+      "$pats = @('opencodex-service.cmd','opencodex-service-launcher.vbs');",
+      "Get-CimInstance Win32_Process | Where-Object {",
+      "  if ($_.ProcessId -eq $PID) { return $false };",
+      "  $c = $_.CommandLine; if (-not $c) { return $false };",
+      "  foreach ($p in $pats) { if ($c -like ('*' + $p + '*')) { return $true } };",
+      "  $false",
+      "} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }",
+    ].join(" ");
+    spawnSync(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+      "-Command", ps,
+    ], { stdio: "ignore", timeout: 5000, windowsHide: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Exposed for tests: drives the non-service restart path with injected io. */
+export function restartAfterUpdateForTests(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string; oldPid?: number },
+  io: RestartIo,
+): Promise<void> {
+  return restartAfterUpdate(job, captured, io);
+}
+
+function restartFailureHint(port: number): string {
+  return `Update installed, but the restarted proxy did not stay healthy on port ${port}. `
+    + `Try 'ocx start --port ${port}'. `
+    + "If the update log shows bun postinstall or EPERM warnings, "
+    + "reinstall with 'npm install -g --allow-scripts=bun @iislee/opencodex'.";
+}
+
+type AwaitHealthyResult =
+  | { ok: true }
+  | { ok: false; reason: "timeout" | "flapped" };
+
+/**
+ * Wait for an identity-checked /healthz on the captured listen target, then require a short
+ * stability window. Soft: never marks the job failed (callers decide whether to fail or retry).
+ */
+async function awaitRestartedProxyHealthy(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string },
+  io: RestartIo = {},
+): Promise<AwaitHealthyResult> {
+  // Fresh post-update starts are busy with catalog sync / OAuth; a single 750ms
+  // /healthz miss must not fail the job. Use a longer probe and tolerate brief blips.
+  const probe = io.probeProxy ?? (async (port: number, hostname?: string) => (
+    !!(await proxyIdentityAt(port, { hostname }, { timeoutMs: 2_000, attempts: 3 }))
+  ));
+  const sleep = io.sleepMs ?? (async (ms: number) => {
+    await new Promise(resolve => setTimeout(resolve, ms));
+  });
+  const now = io.now ?? (() => Date.now());
+  const port = captured.port;
+  const hostname = captured.hostname;
+  const startDeadline = now() + (io.healthTimeoutMs ?? RESTART_HEALTH_TIMEOUT_MS);
+  /** Consecutive failed probes before the stability window counts as a flap. */
+  const stabilityMissLimit = 3;
+
+  while (true) {
+    // Always make one identity-aware probe at or after the boundary. A replacement
+    // becoming healthy on the final tick must not be mistaken for a timeout.
+    const finalProbe = now() >= startDeadline;
+    if (await probe(port, hostname)) {
+      updateJob(job, {}, `Proxy reported healthy on ${hostname}:${port}; confirming it stays up...`);
+      const stableUntil = now() + RESTART_STABILITY_WINDOW_MS;
+      let misses = 0;
+      while (now() < stableUntil) {
+        if (await probe(port, hostname)) {
+          misses = 0;
+        } else {
+          misses += 1;
+          if (misses >= stabilityMissLimit) {
+            updateJob(job, {}, `Proxy became unhealthy on ${hostname}:${port} during the stability window.`);
+            return { ok: false, reason: "flapped" };
+          }
+        }
+        await sleep(500);
+      }
+      updateJob(job, {}, `Proxy stayed healthy for ${Math.trunc(RESTART_STABILITY_WINDOW_MS / 1000)}s after restart.`);
+      return { ok: true };
+    }
+    if (finalProbe) break;
+    await sleep(Math.min(250, Math.max(0, startDeadline - now())));
+  }
+
+  return { ok: false, reason: "timeout" };
+}
+
+/**
+ * Confirm that the detached/service restart really came back and stayed up. The GUI worker
+ * used to mark success immediately after spawning the new process, which hid Windows cases
+ * where npm left the bundled Bun runtime half-updated and the restarted proxy died seconds
+ * later. A healthy /healthz must appear, then remain healthy for one short stability window.
+ */
+async function confirmRestartedProxy(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string },
+  io: RestartIo = {},
+): Promise<boolean> {
+  /* [Decision Log]
+  - 목적과 의도: GUI update job이 detached restart 요청만 보고 성공 처리하지 않도록, 실제 프록시 복귀 여부를 확인한다.
+  - 기존 구현 및 제약 조건: update-job.json은 spawn/service reinstall 직후 `succeeded`로 끝났고, Windows npm/Bun 교체 실패처럼 몇 초 후 죽는 재시작을 잡지 못했다.
+  - 검토한 주요 대안: (1) 포트 점유만 확인 — 외부 프로세스/죽기 직전 프로세스를 성공으로 오인할 수 있다. (2) 무기한 /healthz 폴링 — UX가 느려지고 worker 종료 시점이 불명확하다. (3) 짧은 healthy 등장 + 안정성 창 확인 — 실제 복귀를 확인하면서도 대기 시간을 제한할 수 있다.
+  - 선택한 방식: identity-aware /healthz probe가 일정 시간 안에 나타나고, 추가 안정성 창 동안 유지되는지 확인한다.
+  - 다른 대안 대신 이 방식을 선택한 이유: GUI는 "업데이트가 설치됐지만 재시작은 실패"를 분리해 알려줘야 하며, 이 방식이 가장 적은 오탐으로 그 경계를 만든다.
+  - 장점, 단점 및 영향: 장점은 silent restart failure가 update-job 상태로 드러난다는 점이다. 단점은 설정상 성공 판정 창이 30초 도착 + 15초 안정성으로 늘어나고 경계 probe 지연이 추가될 수 있다는 점이며, 대신 실제 복귀를 더 정확히 반영한다.
+  */
+  const result = await awaitRestartedProxyHealthy(job, captured, io);
+  if (result.ok) return true;
+  const port = captured.port;
+  const hostname = captured.hostname;
+  const error = result.reason === "flapped"
+    ? `proxy restart became unhealthy on ${hostname}:${port}`
+    : `proxy restart never became healthy on ${hostname}:${port}`;
+  updateJob(job, {
+    status: "failed",
+    restarted: false,
+    error,
+  }, restartFailureHint(port));
+  return false;
+}
+
+export function confirmRestartAfterUpdateForTests(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string },
+  io: RestartIo,
+): Promise<boolean> {
+  return confirmRestartedProxy(job, captured, io);
+}
+
+async function defaultProbeProxyIdentity(
+  port: number,
+  hostname?: string,
+): Promise<RestartProxyIdentity | null> {
+  try {
+    const res = await fetch(`http://${probeHostname(hostname)}:${port}/healthz`, {
+      signal: AbortSignal.timeout(750),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json().catch(() => null)) as HealthzIdentity | null;
+    if (!isOpencodexHealthz(body)) return null;
+    return {
+      pid: typeof body?.pid === "number" ? body.pid : null,
+      ...(typeof body?.version === "string" ? { version: body.version } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Health alone is not enough to skip the GUI worker restart: a surviving pre-update
+ * process is still identity-healthy. Require update-correlated evidence — a new PID
+ * when the pre-update PID was captured, and/or /healthz reporting the job's target
+ * version when PID evidence is unavailable.
+ */
+export function npmSelfUpdateRestartEvidence(
+  job: Pick<UpdateJobState, "latestVersion">,
+  captured: { oldPid?: number },
+  identity: RestartProxyIdentity | null,
+): { ok: true; detail: string } | { ok: false; reason: string } {
+  if (!identity) return { ok: false, reason: "could not read proxy identity" };
+
+  const oldPid = typeof captured.oldPid === "number" && captured.oldPid > 0
+    ? captured.oldPid
+    : undefined;
+  const livePid = typeof identity.pid === "number" && identity.pid > 0 ? identity.pid : null;
+  const expected = typeof job.latestVersion === "string" && job.latestVersion.length > 0
+    ? job.latestVersion
+    : null;
+  const versionMatches = expected !== null && identity.version === expected;
+
+  if (oldPid !== undefined) {
+    if (livePid === oldPid) {
+      return { ok: false, reason: "still the pre-update PID" };
+    }
+    if (livePid !== null) {
+      if (expected !== null && identity.version && identity.version !== expected) {
+        return { ok: false, reason: `new pid but version ${identity.version} !== expected ${expected}` };
+      }
+      return { ok: true, detail: `pid changed ${oldPid}→${livePid}` };
+    }
+    // Pre-update PID known but healthz omitted pid — only accept matching target version.
+    if (versionMatches) return { ok: true, detail: `version ${identity.version}` };
+    return { ok: false, reason: "no PID in healthz and version did not match the update target" };
+  }
+
+  if (versionMatches) return { ok: true, detail: `version ${identity.version}` };
+  if (expected !== null && identity.version && identity.version !== expected) {
+    return { ok: false, reason: `version ${identity.version} !== expected ${expected}` };
+  }
+  return { ok: false, reason: "no pre-update PID capture and no expected-version match" };
+}
+
+/**
+ * Post-install restart for the GUI worker.
+ *
+ * npm installs run `node ocx.mjs update`, which already stops the proxy and reinstalls /
+ * starts the service (or falls back to a direct start). A second `service install` here
+ * calls `stopWindows()` on that healthy listener, then often fails elevation from the
+ * non-interactive worker — leaving the captured port (default 10100) dead until a manual
+ * restart. Prefer confirming the npm self-update's own restart first; only re-run restart
+ * when that probe fails. Bun/source installs still always take the explicit restart path.
+ *
+ * Probe-first applies only to service-managed npm installs: without a service, `ocx.mjs`
+ * only prints `ocx start` and never brings the proxy back, so waiting would always burn
+ * the full health timeout. Skipping also requires update-correlated evidence (PID change
+ * and/or target version) so a surviving pre-update process cannot look like success.
+ * After an explicit npm restart the same evidence is required again — health alone is
+ * not enough when a no-op restart or failed port reclaim leaves the old proxy up.
+ *
+ * Browser-dashboard update recovery must not require a viable Background Service: when
+ * no service is installed (or reinstall leaves a non-viable/stale manager), the explicit
+ * path always falls through to a direct `ocx start --port` so /healthz can recover.
+ */
+export async function finishGuiUpdateRestart(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string; oldPid?: number },
+  installer: Installer,
+  io: RestartIo = {},
+): Promise<boolean> {
+  if (installer === "npm") {
+    const serviceInstalled = (io.serviceInstalledFn ?? isServiceInstalled)();
+    if (serviceInstalled) {
+      // Stop-first npm update leaves a dead PID's LISTEN row. Polling /healthz for the
+      // full 30s against that zombie keeps ESTABLISHED TCBs alive and blocks bind.
+      // If nothing live owns the port, skip straight to explicit restart. A failed
+      // listener scan must not look like "no listeners" — fall back to /healthz.
+      const aliveFn = io.isAliveFn ?? isProcessAlive;
+      const scan: ListenPidScan = io.scanListenPidsFn
+        ? io.scanListenPidsFn(captured.port)
+        : io.listListenPidsFn
+          // Test seam: injected list is always a successful scan.
+          ? { ok: true, pids: io.listListenPidsFn(captured.port) }
+          : scanListenPids(captured.port);
+      const liveListeners = scan.ok
+        ? scan.pids.filter(pid => pid !== process.pid && aliveFn(pid))
+        : null;
+      if (liveListeners !== null && liveListeners.length === 0) {
+        updateJob(job, {}, "npm self-update did not leave a live listener; performing explicit restart...");
+      } else {
+        if (!scan.ok) {
+          updateJob(
+            job,
+            {},
+            "Listener scan inconclusive after npm self-update; probing /healthz before deciding on explicit restart...",
+          );
+        }
+        const already = await awaitRestartedProxyHealthy(job, captured, io);
+        if (already.ok) {
+          const identity = await (io.probeProxyIdentity ?? defaultProbeProxyIdentity)(
+            captured.port,
+            captured.hostname,
+          );
+          const evidence = npmSelfUpdateRestartEvidence(job, captured, identity);
+          if (evidence.ok) {
+            updateJob(
+              job,
+              {},
+              `Proxy already healthy on ${captured.hostname}:${captured.port} after npm self-update (${evidence.detail}); skipping redundant restart.`,
+            );
+            return true;
+          }
+          updateJob(
+            job,
+            {},
+            `npm self-update left a healthy proxy but ${evidence.reason}; performing explicit restart...`,
+          );
+        } else {
+          updateJob(job, {}, "npm self-update did not leave a healthy proxy; performing explicit restart...");
+        }
+      }
+    }
+  }
+  const restartFn = io.restartAfterUpdateFn ?? restartAfterUpdate;
+  await restartFn(job, captured, io);
+  if (installer !== "npm") {
+    // Bun/source: health alone remains enough unless a richer identity probe is supplied.
+    if (!io.probeProxyIdentity) return confirmRestartedProxy(job, captured, io);
+  }
+  return confirmNpmExplicitRestart(job, captured, io);
+}
+
+/**
+ * After an explicit npm (or identity-aware) restart, require update-correlated
+ * evidence — not merely a healthy OpenCodex listener. A no-op restart or a
+ * failed port reclaim can leave the pre-update process on the captured port;
+ * `confirmRestartedProxy` alone would treat that as success.
+ */
+async function confirmNpmExplicitRestart(
+  job: UpdateJobState,
+  captured: { port: number; hostname: string; oldPid?: number },
+  io: RestartIo = {},
+): Promise<boolean> {
+  const healthy = await awaitRestartedProxyHealthy(job, captured, io);
+  if (!healthy.ok) {
+    const port = captured.port;
+    const hostname = captured.hostname;
+    const error = healthy.reason === "flapped"
+      ? `proxy restart became unhealthy on ${hostname}:${port}`
+      : `proxy restart never became healthy on ${hostname}:${port}`;
+    updateJob(job, {
+      status: "failed",
+      restarted: false,
+      error,
+    }, restartFailureHint(port));
+    return false;
+  }
+
+  const identity = await (io.probeProxyIdentity ?? defaultProbeProxyIdentity)(
+    captured.port,
+    captured.hostname,
+  );
+  const evidence = npmSelfUpdateRestartEvidence(job, captured, identity);
+  if (!evidence.ok) {
+    updateJob(job, {
+      status: "failed",
+      restarted: false,
+      error: `proxy restart did not show update-correlated identity (${evidence.reason})`,
+    }, restartFailureHint(captured.port));
+    return false;
+  }
+
+  updateJob(
+    job,
+    {},
+    `Proxy restart confirmed on ${captured.hostname}:${captured.port} (${evidence.detail}).`,
+  );
+  return true;
+}
+
+export async function runGuiUpdateWorker(jobId: string, channel: Channel, restart: boolean): Promise<void> {
+  let job = readUpdateJob(jobId);
+  const check = checkForUpdate(channel);
+  const now = new Date().toISOString();
+  // Capture the live listen target BEFORE the update command runs: the stop-first update
+  // flow clears pid/runtime state, so this is the last moment the real port is knowable.
+  // Only trust runtime-port.json when its pid matches the live pidfile process.
+  const rt = readRuntimePort();
+  const livePid = readPid();
+  const preUpdateConfig = loadConfig();
+  const runtimeTrusted = !!(rt && livePid && rt.pid === livePid);
+  const configPort = typeof preUpdateConfig.port === "number" && preUpdateConfig.port > 0
+    ? preUpdateConfig.port
+    : 10100;
+  const captured = {
+    port: runtimeTrusted ? rt.port : configPort,
+    hostname: (runtimeTrusted ? rt.hostname : undefined) ?? preUpdateConfig.hostname ?? "127.0.0.1",
+    ...(runtimeTrusted && livePid ? { oldPid: livePid } : {}),
+  };
+  let trayWasInstalled = false;
+  let trayWasRunning = false;
+  if (!job) {
+    job = {
+      id: jobId,
+      status: "running",
+      startedAt: now,
+      updatedAt: now,
+      currentVersion: check.currentVersion,
+      latestVersion: check.latestVersion,
+      channel: check.channel,
+      installer: check.installer,
+      restart,
+      command: check.command,
+      releaseNotesUrl: check.releaseNotesUrl,
+      log: [],
+    };
+    writeJob(job);
+  }
+
+  try {
+    if (!check.canUpdate) {
+      throw new Error(check.reason ?? "No update is available");
+    }
+
+    // Pre-flight integrity metadata check (same lanes as the CLI): anomalous registry
+    // metadata for a resolved version fails the job BEFORE anything is spawned or the
+    // proxy is stopped; transient registry failure degrades to a logged skip.
+    const integrity = checkUpdatePackageIntegrity(check.latestVersion);
+    if (integrity.ok === false) {
+      updateJob(job, { status: "failed", error: integrity.reason });
+      return;
+    }
+    const integrityLine = integrity.ok === "skipped"
+      ? `Integrity pre-flight skipped: ${integrity.reason}. Proceeding best-effort.`
+      : `Verified ${PKG}@${check.latestVersion} integrity metadata ${integrity.integrity.slice(0, 24)}…`;
+
+    const cmd = updateExecutionCommand(check.installer, channel, undefined, check.latestVersion);
+    job = updateJob(job, {
+      currentVersion: check.currentVersion,
+      latestVersion: check.latestVersion,
+      installer: check.installer,
+      command: cmd.display,
+    }, integrityLine);
+
+    if (process.platform === "win32") {
+      try {
+        const { getWindowsTrayStatus, startWindowsTray, stopWindowsTray } = await import("../tray/windows");
+        const tray = getWindowsTrayStatus();
+        const trayPlan = handoffWindowsTrayForUpdate(tray, {
+          stop: () => {
+            const stopped = stopWindowsTray();
+            return { exitStatus: 0, running: stopped.running };
+          },
+          start: () => startWindowsTray(),
+        });
+        trayWasInstalled = trayPlan.refreshAfterReplacement;
+        trayWasRunning = trayPlan.restoreOnFailure;
+      } catch (error) {
+        updateJob(job, {
+          status: "failed",
+          error: `Could not stop the Windows tray; aborting before package replacement: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return;
+      }
+    }
+
+    /* [Decision Log]
+    - 목적: GUI 요청 처리 프로세스가 자신이 실행 중인 패키지를 직접 덮어쓰지 않도록 업데이트를 별도 worker에서 수행한다.
+    - 대안 분석: (1) 서버에서 runUpdate 직접 호출: process.exit/stdio/실행 파일 교체 위험. (2) GUI에서 CLI 명령 안내만 제공: 자동 업데이트 UX 부족. (3) 숨은 worker가 Node launcher/Bun 전역 명령을 실행: 상태 추적과 안전한 재시작이 가능.
+    - 선택 근거: 현재 CLI의 npm self-update 우회를 재사용하면서도 GUI 서버 요청 생명주기와 설치 작업을 분리할 수 있어 가장 안정적이다.
+    */
+    const result = runLoggedCommand(job, cmd.bin, cmd.args, UPDATE_TIMEOUT_MS);
+    if (result.status !== 0) {
+      if (trayWasRunning) {
+        try {
+          const { startWindowsTray } = await import("../tray/windows");
+          startWindowsTray();
+        } catch { /* retain the primary update failure */ }
+      }
+      updateJob(job, {
+        status: "failed",
+        exitCode: result.status,
+        signal: result.signal,
+        error: `update command failed (${result.status ?? "?"})`,
+      });
+      return;
+    }
+
+    if (trayWasInstalled) {
+      const trayArgs = [process.argv[1], ...planWindowsTrayUpdate({ installed: trayWasInstalled, running: trayWasRunning }).installArgs];
+      const tray = runLoggedCommand(job, process.execPath, trayArgs, 20_000);
+      if (tray.status !== 0) {
+        updateJob(job, {}, "Windows tray refresh failed; run 'ocx tray install'.");
+        if (trayWasRunning) runLoggedCommand(job, process.execPath, [process.argv[1], "tray", "start"], 15_000);
+      }
+    }
+
+    if (restart) {
+      job = updateJob(job, { status: "restarting" }, "Update installed. Restarting proxy...");
+      if (!(await finishGuiUpdateRestart(job, captured, check.installer))) return;
+      updateJob(job, { status: "succeeded", restarted: true }, "Restart requested and proxy is healthy.");
+      return;
+    }
+
+    updateJob(job, { status: "succeeded", restarted: false }, "Update installed. Restart the proxy to use the new version.");
+  } catch (err) {
+    if (trayWasRunning) {
+      try {
+        const { startWindowsTray } = await import("../tray/windows");
+        startWindowsTray();
+      } catch { /* retain the primary worker failure */ }
+    }
+    updateJob(job, {
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}