UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,341 lines • 72 kB
import { guardedRun, guardedSpawn, guardedSpawnSync } from "./mutation-guard.mjs";
import { probeSpawn, probeSpawnSync } from "./mutation-guard.mjs";
import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
import { manualUpdateFailureGuidance } from "./update-failure-guidance.mjs";
import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
import { proxyIdentityAt } from "../server/proxy-liveness";
import { probeProxyLiveness } from "./proxy-liveness-probe.mjs";
import { verifyOrchestratedInstall } from "./orchestrated-tree.mjs";
import { decidePostStopUpdate } from "./stop-decision.mjs";
import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, isAbsolute, join, resolve } from "node:path";
import { getConfigDir, getConfigPath, loadConfig } from "../config";
import { runConfigPreflight } from "./config-preflight";
import { readPid, readRuntimePort, getRuntimePortPath } from "../config/process-state";
import { pendingTeardownOutstanding } from "../config/pending-teardown";
import type { ServiceOwnership } from "../service/state";
import { planUpdateRuntimeHandling, planStoppedRuntimeRecovery, inspectPackageRuntimeLiveness } from "./runtime-ownership.mjs";
import { unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
import { withUpdateOwnershipLease, readUpdateRuntimeTarget } from "./ownership-transaction";
import { createUpdateServiceHomePolicy, parseUpdateWorkerHome, UPDATE_PACKAGE_ONLY_EXIT_CODE } from "./service-home-policy.mjs";
import { npmInvocation } from "./npm-invocation.mjs";
import { pnpmInvocation, pnpmInvocationForPath, resolvePnpmCommands } from "./pnpm-invocation.mjs";
import { detectInstallOwnershipFromPath } from "./install-detection.mjs";
import type {
  DetectedInstall,
  InstallOwnership as PackageInstallOwnership,
  MiseInstallOwner,
} from "./install-detection.d.mts";
import {
  pnpmOwnerInvocation,
  pnpmOwnerEnvironment,
  readPnpmGlobalPackage,
  resolvePnpmGlobalOwner,
  runPnpmGlobalUpdate,
} from "./pnpm-global-install.mjs";
import type { PnpmGlobalOwner, PnpmGlobalOwnerResult } from "./pnpm-global-install.mjs";
import { checkRegistryPackageIntegrity } from "./registry-integrity.mjs";
import {
  npmCachePreflightFailureMessage,
  runNpmCachePreflight,
} from "./npm-cache-preflight.mjs";
import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
import { withoutSiblingMarker } from "../codex/sibling-start";
import { packageVersion } from "../lib/package-version";
import { isStandaloneModuleUrl } from "../lib/standalone";
import { selfLaunchArgv } from "../lib/self-launch-argv";
import { createLegacyUpdateSession, createOrchestratedChildSession, decodeOrchestratedExpect } from "./orchestrated-session.mjs";
import { runPosixInstallerSync } from "./posix-install-supervisor.mjs";
import { runWindowsInstallerSync } from "./npm-install.mjs";
import { staleUpdateMarkerHint } from "./sync-update-mutex.mjs";
import { protectOrchestratedWorkerSignals } from "./orchestrated-child.mjs";
import type { OrchestratedChildArgs } from "./orchestrated-arguments.mjs";
import { PNPM_READ_CWD, withPnpmCommandCwd, pnpmReadEnvironment } from "./pnpm-read-policy.mjs";
import {
  freshServingPid, hasRestartableServiceManager, readParentPid, readServiceManagerPid, restartServiceManagerJob,
  supervisionVerdict, unsettledManagerWarning, unsupervisedRuntimeWarning,
} from "./supervised-recovery.mjs";

/**
 * A `codex-history-backup-*.json` surviving a stop means the native-history restore was
 * skipped (locked state DB) — routed threads stay hidden in the Codex app until a retry.
 */
export function historyRestoreIncomplete(configDir = getConfigDir()): boolean {
  try {
    return readdirSync(configDir).some(
      name => name.startsWith("codex-history-backup-") && name.endsWith(".json"),
    );
  } catch {
    return false;
  }
}

export const PKG = "@bitkyc08/opencodex";
const HERE = dirname(fileURLToPath(import.meta.url)); // .../opencodex/src/update

export type Installer = DetectedInstall | "standalone";
export const STANDALONE_UPDATE_HINT = "Update via OpenCodex Desktop (Check for Updates…), on a Windows Desktop installation from a terminal or remote session with 'ocx update --desktop', or reinstall the standalone binary from GitHub Releases.";
export type Channel = "latest" | "preview";
export type InstallOwnership = PackageInstallOwnership | { installer: "standalone" };
export type { MiseInstallOwner };

/** Infer how opencodex is installed from the running module's path. */
export function detectInstall(moduleUrl = import.meta.url): Installer {
  return detectInstallOwnership(moduleUrl).installer;
}

/** Resolve installer ownership and verified mise update guidance for this package. */
export function detectInstallOwnership(moduleUrl = import.meta.url): InstallOwnership {
  if (isStandaloneModuleUrl(moduleUrl)) return { installer: "standalone" };
  return detectInstallOwnershipFromPath(dirname(fileURLToPath(moduleUrl)), { exists: existsSync });
}

export function miseUpdateCommand(
  ownership: InstallOwnership = detectInstallOwnership(),
): string | null {
  return ownership.installer === "mise" && ownership.owner
    ? `mise upgrade ${ownership.owner.tool}`
    : null;
}

function packageRoot(): string {
  return resolve(HERE, "..", "..");
}

function runningPnpmShimPath(invoked = process.argv[1]): string | undefined {
  if (!invoked) return undefined;
  const name = invoked.replaceAll("\\", "/").split("/").at(-1)?.toLowerCase();
  if (!new Set(["ocx", "opencodex", "ocx.cmd", "opencodex.cmd", "ocx.ps1", "opencodex.ps1"]).has(name ?? "")) {
    return undefined;
  }
  return resolve(invoked);
}

function runPnpmCandidate(
  commandPath: string,
  args: readonly string[],
  capture = false,
  probeSpawn: typeof probeSpawnSync = probeSpawnSync,
  probeEnv: NodeJS.ProcessEnv = process.env,
  owner?: PnpmGlobalOwner,
): { status: number | null; stdout?: string | null; stderr?: string | null } {
  const invocation = owner ? pnpmOwnerInvocation(owner, args, process.platform, probeEnv) : pnpmInvocationForPath(commandPath, args);
  if (!invocation) return { status: 1 };
  return withPnpmCommandCwd(args, cwd => probeSpawn(invocation.file, invocation.args, {
    stdio: capture ? "pipe" : "ignore",
    encoding: "utf8",
    timeout: 20_000,
    windowsHide: true,
    cwd,
    env: pnpmReadEnvironment(unprivilegedOwnershipMutationEnvironment(owner ? pnpmOwnerEnvironment(owner, probeEnv) : probeEnv)),
    ...invocation.options,
  }));
}

/** Resolve the exact pnpm executable/group/bin that own this package. */
export function resolveCurrentPnpmGlobalOwner(
  invoked = process.argv[1],
  deps: { commandPaths?: readonly string[]; spawn?: typeof probeSpawnSync; env?: NodeJS.ProcessEnv } = {},
): PnpmGlobalOwnerResult {
  const probeSpawn = deps.spawn ?? probeSpawnSync;
  return resolvePnpmGlobalOwner({
    packageName: PKG,
    packagePath: packageRoot(),
    commandPaths: deps.commandPaths ?? resolvePnpmCommands(),
    runningShimPath: runningPnpmShimPath(invoked),
    runPnpm: (commandPath, args, capture, owner) => runPnpmCandidate(commandPath, args, capture, probeSpawn, deps.env, owner),
    env: deps.env ?? process.env,
  });
}

function ownerPnpmTarget(
  owner: PnpmGlobalOwner,
  args: readonly string[],
): { bin: string; args: string[]; options: { windowsVerbatimArguments?: boolean }; env: Record<string, string | undefined> } | null {
  const invocation = pnpmOwnerInvocation(owner, args);
  if (!invocation) return null;
  return {
    bin: invocation.file,
    args: invocation.args,
    options: invocation.options,
    env: invocation.env,
  };
}

export function runOwnedPnpm(
  owner: PnpmGlobalOwner,
  args: readonly string[],
  capture: boolean,
  stdio: "inherit" | "pipe" | "ignore" = capture ? "pipe" : "inherit",
  probeSpawn: typeof probeSpawnSync = probeSpawnSync,
  authorizeMutation: (kind: "package") => boolean = () => ["root", "bin", "list", "config", "view", "--version"].includes(args[0] ?? "")
    || (args[0] === "store" && args[1] === "path" && args.length === 3
      && args[2]?.startsWith("--dir=") === true && isAbsolute(args[2].slice("--dir=".length))),
  session?: Pick<ReturnType<typeof createOrchestratedChildSession>, "retainInstallerFence" | "noteUntrackedInstaller" | "confirmInstallerExit">,
  markerPath = join(getConfigDir(), "update-orchestrated.json"),
): { status: number | null; stdout?: string | null; stderr?: string | null; processTreeExited?: boolean } {
  const target = ownerPnpmTarget(owner, args);
  if (!target) return { status: 1 };
  const mutating = ["add", "install", "update", "remove", "uninstall"].includes(args[0] ?? "");
  try { return withPnpmCommandCwd(args, cwd => {
    if (mutating && !capture && session && authorizeMutation("package")) {
      const env = pnpmReadEnvironment(unprivilegedOwnershipMutationEnvironment(target.env));
      if (process.platform === "win32") {
        session.noteUntrackedInstaller();
        const result = runWindowsInstallerSync({ file: target.bin, args: target.args, options: target.options }, { cwd, env, authorizeMutation, markerPath });
        if (result.processTreeExited && Number.isInteger(result.status)) session.confirmInstallerExit();
        else { session.retainInstallerFence(); return { ...result, processTreeExited: false }; }
        return result;
      }
      const result = runPosixInstallerSync({ file: target.bin, args: target.args, markerPath, cwd, env, authorizeMutation });
      if (!Number.isInteger(result.status) || result.signal || !result.groupExited || result.groupKilled !== false || result.processTreeExited === false) {
        session.retainInstallerFence();
        return { ...result, processTreeExited: false };
      }
      return { ...result, processTreeExited: true };
    }
    const result = authorizeMutation("package") ? guardedSpawnSync(authorizeMutation, "package", target.bin, target.args, {
    stdio,
    encoding: "utf8",
    timeout: 180_000,
    windowsHide: true,
    // Reads probe from the package dir; `add -g`/rollback children run from a neutral
    // directory so a Windows cwd handle never pins open the package pnpm is replacing.
    cwd,
    env: pnpmReadEnvironment(unprivilegedOwnershipMutationEnvironment(target.env)),
    ...target.options,
    }, probeSpawn) : { status: 1, signal: null };
    if (mutating && (!Number.isInteger(result.status) || result.signal)) session?.retainInstallerFence();
    return result;
  }); } catch (error) { if (mutating) session?.retainInstallerFence(); throw error; }
}

/** Re-read the owning group's active package and return its verified launcher. */
export function resolvePnpmActiveLauncher(owner: PnpmGlobalOwner): string | null {
  if (owner.globalStore && !Array.isArray(owner.virtualStoreDirs)) return null;
  const active = readPnpmGlobalPackage(
    PKG,
    (args, capture = false) => runOwnedPnpm(owner, args, capture),
    undefined,
    {
      owner,
      expectedGlobalDir: owner.globalDir,
      expectedGlobalRoot: owner.globalRoot,
      globalBinDir: owner.globalBinDir,
    },
  );
  return active.ok ? join(active.path, "bin", "ocx.mjs") : null;
}

export function currentVersion(): string {
  return packageVersion("?");
}

export function defaultUpdateTag(current: string): Channel {
  return current.includes("-preview.") ? "preview" : "latest";
}

export function updateTag(current: string): Channel {
  const tagIndex = process.argv.indexOf("--tag");
  const explicit = tagIndex !== -1 ? process.argv[tagIndex + 1] : undefined;
  if (explicit === "preview" || explicit === "latest") return explicit;
  return defaultUpdateTag(current);
}

type SpawnTarget = {
  bin: string;
  args: string[];
  options: { windowsVerbatimArguments?: boolean };
  env?: Record<string, string | undefined>;
};

export type RegistrySpawnTarget = SpawnTarget;

function npmSpawnTarget(args: readonly string[]): SpawnTarget | null {
  const invocation = npmInvocation(args);
  if (!invocation) return null;
  return { bin: invocation.file, args: invocation.args, options: invocation.options };
}

function pnpmSpawnTarget(args: readonly string[], owner?: PnpmGlobalOwner, env?: NodeJS.ProcessEnv): SpawnTarget | null {
  if (owner) {
    const invocation = pnpmOwnerInvocation(owner, args, process.platform, env);
    if (!invocation) return null;
    return {
      bin: invocation.file,
      args: invocation.args,
      options: invocation.options,
      env: invocation.env,
    };
  }
  const invocation = pnpmInvocation(args);
  if (!invocation) return null;
  return { bin: invocation.file, args: invocation.args, options: invocation.options };
}

export function registrySpawnTarget(
  installer: Installer,
  args: readonly string[],
  owner?: PnpmGlobalOwner,
  env?: NodeJS.ProcessEnv,
): SpawnTarget | null {
  if (installer === "standalone") return null;
  // A pnpm command without an owner would silently fall back to the first PATH
  // candidate. That is unsafe when multiple PNPM_HOME installations expose the
  // same version, so registry queries use the same hard binding as mutation.
  return installer === "pnpm"
    ? owner ? pnpmSpawnTarget(args, owner, env) : null
    : npmSpawnTarget(args);
}

function selectedPnpmOwner(owner?: PnpmGlobalOwner, probeSpawn?: typeof probeSpawnSync, env?: NodeJS.ProcessEnv): PnpmGlobalOwner | undefined {
  if (owner) return owner;
  const result = resolveCurrentPnpmGlobalOwner(undefined, { spawn: probeSpawn, env });
  return result.ok ? result.owner : undefined;
}

function updateSpawnTarget(bin: string, args: readonly string[]): SpawnTarget | null {
  if (bin === "npm") return npmSpawnTarget(args);
  if (bin === "pnpm") return pnpmSpawnTarget(args);
  if (process.platform === "win32" && bin === "bun") {
    return { bin: process.execPath, args: [...args], options: {} };
  }
  return { bin, args: [...args], options: {} };
}

/**
 * The GUI update worker sets OCX_SERVICE=1 and has stdio ignored — inheriting that for
 * Background package-manager children can open stacked visible consoles on Windows.
 * Pipe instead and relay bounded output after the child exits. (Ported from PR #167.)
 */
function updateChildStdio(): "inherit" | "pipe" {
  if (process.env.OCX_SERVICE === "1") return "pipe";
  if (typeof process.stdout.isTTY === "boolean" && !process.stdout.isTTY) return "pipe";
  return "inherit";
}

function logSpawnOutput(label: string, result: { stdout?: string | Buffer | null; stderr?: string | Buffer | null }): void {
  const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
  const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
  if (stdout) console.log(stdout.length > 4000 ? `${label}${stdout.slice(-4000)}` : stdout);
  if (stderr) console.error(stderr.length > 4000 ? `${label}${stderr.slice(-4000)}` : stderr);
}

function shellQuote(value: string): string {
  if (process.platform === "win32") return `"${value.replaceAll("\"", "\\\"")}"`;
  return `'${value.replaceAll("'", "'\\''")}'`;
}

function launcherStartHint(launcher: string, port: number): string {
  return `${shellQuote(process.execPath)} ${shellQuote(launcher)} start --port ${Math.trunc(port)}`;
}

/** Latest published version from the registry (best-effort; null if the manager isn't available). */
export function latestVersion(
  tag: string,
  installer: Installer = detectInstall(),
  owner?: PnpmGlobalOwner,
  probeSpawn: typeof probeSpawnSync = probeSpawnSync,
  probeEnv?: NodeJS.ProcessEnv,
): string | null {
  const resolvedOwner = installer === "pnpm" ? selectedPnpmOwner(owner, probeSpawn, probeEnv) : undefined;
  if (installer === "pnpm" && !resolvedOwner) return null;
  const manager = registrySpawnTarget(installer, ["view", `${PKG}@${tag}`, "version"], resolvedOwner, probeEnv);
  if (!manager) return null;
  const r = probeSpawn(manager.bin, manager.args, {
    encoding: "utf8",
    timeout: 12000,
    windowsHide: true,
    cwd: installer === "pnpm" ? PNPM_READ_CWD : undefined,
    env: installer === "pnpm"
      ? pnpmReadEnvironment(unprivilegedOwnershipMutationEnvironment(manager.env ?? probeEnv ?? process.env))
      : unprivilegedOwnershipMutationEnvironment(manager.env ?? probeEnv ?? process.env),
    ...manager.options,
  });
  return r.status === 0 && typeof r.stdout === "string" ? (r.stdout.trim() || null) : null;
}

/** The global-install command opencodex would run to update on this channel. */
export function updateCommand(installer: Installer, tag: Channel, resolvedVersion?: string | null): { bin: string; args: string[] } {
  if (installer === "standalone") throw new Error(STANDALONE_UPDATE_HINT);
  if (installer === "mise") {
    throw new Error("mise-owned installations must be upgraded through mise");
  }
  // Immutable target: when the registry resolved a concrete version, install exactly
  // that version — the dist-tag can move between resolution and install (TOCTOU).
  const target = resolvedVersion || tag;
  if (installer === "bun") return { bin: "bun", args: ["add", "-g", `${PKG}@${target}`] };
  if (installer === "pnpm") {
    return { bin: "pnpm", args: ["add", "-g", "--allow-build=bun", `${PKG}@${target}`] };
  }
  const bin = "npm";
  // npm 12 blocks dependency lifecycle scripts by default, and bun's postinstall is what
  // copies the selected @oven/bun-* executable into bun/bin. Without this narrow approval
  // the install succeeds but leaves bun's un-downloaded placeholder, so the next `ocx`
  // cannot start (#8361). npm 6 through 11 run bun's postinstall anyway and install with the
  // flag on global installs, so it is unconditional rather than version-gated; some npm 11
  // releases print an "Unknown cli config" warning for it and still install.
  const args = ["install", "-g", "--allow-scripts=bun", `${PKG}@${target}`];
  return { bin, args };
}

/** Human-readable form of {@link updateCommand}, used in the update prompt label. */
export function updateCommandStr(installer: Installer, tag: Channel, resolvedVersion?: string | null): string {
  const { bin, args } = updateCommand(installer, tag, resolvedVersion);
  return `${bin} ${args.join(" ")}`;
}

/**
 * Pre-flight integrity metadata check (NOT independent tamper-proofing — the installer
 * verifies tarballs against the same registry metadata). Two failure lanes:
 *  - transient registry failure (spawn error/timeout/nonzero exit) → `{ ok: "skipped" }`
 *    so registry absence never turns into an unconditional update failure;
 *  - successful query with missing/malformed SRI → `{ ok: false }` (anomalous
 *    metadata — fail closed BEFORE the running proxy is stopped).
 * `dist.integrity` may be a quoted, space-separated multi-hash list; any sha512 token passes.
 */
export function checkUpdatePackageIntegrity(
  version: string | null,
  probeSpawn: typeof probeSpawnSync = probeSpawnSync,
  installer: Installer = detectInstall(),
  owner?: PnpmGlobalOwner,
): { ok: true; integrity: string } | { ok: false; reason: string } | { ok: "skipped"; reason: string } {
  const resolvedOwner = installer === "pnpm" ? selectedPnpmOwner(owner) : undefined;
  if (installer === "pnpm" && !resolvedOwner) {
    return { ok: false, reason: "could not identify pnpm's owning global installation" };
  }
  const manager = registrySpawnTarget(installer, ["view", `${PKG}@${version}`, "dist.integrity"], resolvedOwner);
  if (!manager) return { ok: "skipped", reason: `${installer} executable was not found on a trusted PATH entry` };
  const result = checkRegistryPackageIntegrity(PKG, version, args => {
    const target = registrySpawnTarget(installer, args, resolvedOwner);
    if (!target) return { status: 1 };
    return probeSpawn(target.bin, target.args, {
      encoding: "utf8",
      timeout: 12000,
      windowsHide: true,
      cwd: installer === "pnpm" ? PNPM_READ_CWD : undefined,
      env: installer === "pnpm"
        ? pnpmReadEnvironment(unprivilegedOwnershipMutationEnvironment(target.env ?? process.env))
        : unprivilegedOwnershipMutationEnvironment(target.env ?? process.env),
      ...target.options,
    });
  });
  return result;
}

/**
 * The recorded runtime owner, in the shape the shared update rule reads.
 *
 * Fails CLOSED. A resolution this process could not obtain is not evidence that nobody owns
 * the runtime, and treating it as such is how an unreadable record reactivates the npm
 * launcher over a takeover the user consented to.
 */
interface RuntimeOwnershipObservation {
  readonly ownership: ServiceOwnership | null;
  readonly ownershipUnknown: boolean;
  readonly subjectToken: string;
}

async function resolvedRuntimeOwnership(): Promise<RuntimeOwnershipObservation> {
  try {
    const { resolveServiceOwnership } = await import("../service");
    const resolution = resolveServiceOwnership();
    if (resolution.kind === "owned") return {
      ownership: resolution.ownership,
      ownershipUnknown: false,
      subjectToken: JSON.stringify(["owned", resolution.revision, resolution.ownership]),
    };
    if (resolution.kind === "none") return {
      ownership: null,
      ownershipUnknown: false,
      subjectToken: JSON.stringify(["none", resolution.revision]),
    };
    return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
  } catch {
    return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
  }
}

/**
 * `ocx update` fallback for source checkouts and Bun global installs. npm and pnpm global installs
 * are updated in the Node bin launcher before Bun starts, so Windows does not replace the running
 * Bun binary.
 */
export async function runUpdate(child?: Extract<OrchestratedChildArgs, { ok: true }>): Promise<void> {
  let session: ReturnType<typeof createOrchestratedChildSession> | undefined;
  if (child) {
    try {
      const expect = decodeOrchestratedExpect(child.expect);
      session = createOrchestratedChildSession({ home: getConfigDir(), resultPath: child.resultPath, resultCapability: child.resultCapability, expect, notAfter: child.notAfter,
        verifyIdentity: async () => (await import("./orchestrated-entry")).verifyOrchestratedChildIdentity(expect, child.version) });
      if (!session.start().ok) { process.exitCode = 10; return; }
      protectOrchestratedWorkerSignals();
    } catch (error) {
      console.error(`Orchestrated update preflight failed: ${error instanceof Error ? error.message : String(error)}`);
      process.exitCode = 1;
      return;
    }
  } else {
    session = createLegacyUpdateSession({ home: getConfigDir() });
    const started = session.start();
    if (!started.ok) {
      console.error(`opencodex: ${started.error}`);
      if (started.staleMarker) for (const line of staleUpdateMarkerHint(getConfigDir())) console.error(line);
      process.exitCode = 1;
      return;
    }
    process.once("exit", () => session?.finishPreflight());
  }
  try { await runUpdateWithSession(child, session); }
  finally { session?.finishPreflight(); }
}

async function runUpdateWithSession(child: Extract<OrchestratedChildArgs, { ok: true }> | undefined,
  session: ReturnType<typeof createOrchestratedChildSession> | undefined): Promise<void> {
  const ownership = detectInstallOwnership();
  const installer = ownership.installer;
  if (child && installer !== "bun") { process.exitCode = 1; return; }
  const current = currentVersion();
  const tag = updateTag(current);
  console.log(`opencodex v${current} (installed via ${installer}, tag ${tag})`);

  if (installer === "mise") {
    const command = miseUpdateCommand(ownership);
    if (command) {
      console.error(`OpenCodex is externally managed by mise. Update it with: ${command}`);
    } else {
      console.error(
        "OpenCodex appears to be managed by mise, but its ownership metadata is unreadable or inconsistent. Repair the mise installation metadata before updating.",
      );
    }
    process.exitCode = 1;
    return;
  }

  if (installer === "standalone") {
    console.error(STANDALONE_UPDATE_HINT);
    process.exitCode = 1;
    return;
  }

  if (installer === "source") {
    console.log("Running from a source checkout — update with:  git pull && bun install");
    return;
  }

  const ownerResult = installer === "pnpm" ? resolveCurrentPnpmGlobalOwner() : undefined;
  if (installer === "pnpm" && (!ownerResult || !ownerResult.ok)) {
    console.error(`⚠️  ${ownerResult?.reason ?? "Could not identify pnpm's owning global installation"}. Aborting before stopping the proxy.`);
    process.exit(1);
  }
  const owner = ownerResult?.ok ? ownerResult.owner : undefined;
  const latest = child?.version ?? latestVersion(tag, installer, owner);
  if (latest && latest === current) {
    console.log(`Already on the latest ${tag} version (v${latest}).`);
    if (child) process.exitCode = 1;
    return;
  }

  // Pre-flight integrity metadata check — runs BEFORE the proxy is stopped so an
  // anomalous registry entry aborts without unloading the running service.
  const integrity = checkUpdatePackageIntegrity(latest, probeSpawnSync, installer, owner);
  if (integrity.ok === false) {
    console.error(`⚠️  ${integrity.reason} — aborting the update before stopping the proxy.`);
    if (child) { process.exitCode = 1; return; }
    process.exit(1);
  }
  if (integrity.ok === "skipped") {
    console.warn(`⚠️  Integrity pre-flight skipped: ${integrity.reason}. Proceeding best-effort.`);
  } else {
    console.log(`Verified ${PKG}@${latest} integrity metadata ${integrity.integrity.slice(0, 24)}…`);
  }

  if (installer === "npm") {
    const cachePreflight = runNpmCachePreflight();
    if (!cachePreflight.ok) {
      console.error(`⚠️  ${npmCachePreflightFailureMessage(cachePreflight.reason)}. Aborting before stopping the proxy.`);
      process.exit(1);
    }
  }

  const { bin, args: cmdArgs } = updateCommand(installer, tag, latest);
  const target = installer === "pnpm" && owner
    ? pnpmSpawnTarget(cmdArgs, owner)
    : updateSpawnTarget(bin, cmdArgs);
  if (!target) {
    console.error(`⚠️  Could not resolve ${bin} from a trusted absolute PATH entry; aborting before stopping the proxy.`);
    if (child) { process.exitCode = 1; return; }
    process.exit(1);
  }

  const { serviceStatePaths } = await import("../service");
  let mutationStarted = false, completed = false, installerUncertain = false, installedRoot: string | undefined;
  let updateExitCode: number | undefined;
  try {
  updateExitCode = await withUpdateOwnershipLease(serviceStatePaths(), async mutation => {
  // Ownership inspection imports the service CLI, which reaches this update entry again.
  // Load it only after entering the lease; the policy itself stays a dependency-free import.
  const { inspectUpdateServiceHome } = await import("./service-home-authority");
  const homePolicy = createUpdateServiceHomePolicy(inspectUpdateServiceHome, message => console.warn(message), process.argv.includes("--update-package-only"), parseUpdateWorkerHome(process.argv));
  if (!homePolicy.authorizeMutation("package")) return 1;
  const configPath = getConfigPath(), configPreflight = runConfigPreflight(configPath);
  if (!configPreflight.ok) {
    console.error(`⚠️  Configuration preflight failed for ${configPath}; aborting update before stopping services.`);
    if (configPreflight.error) console.error(`    ${configPreflight.error}`);
    if (configPreflight.reason === "read_error") {
      console.error("    Inspect the config path, permissions, and any symlink target; correct them or restore a readable regular config from a trusted backup, then retry.");
      console.error("    'ocx config validate' may report defaults if a symlink target is missing; it does not change the file.");
    } else {
      console.error("    Run 'ocx config validate' to diagnose the configuration; it does not change the file. Back up and correct the file, then retry.");
    }
    return 1;
  }

  // Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
  // unloads it, so a successful update must repair/restart it afterwards.
  let serviceWasInstalled = false;
  try {
    const { isServiceInstalled } = await import("../service");
    serviceWasInstalled = homePolicy.serviceAllowed && isServiceInstalled();
  } catch { /* best-effort */ }
  // What this update may do to the runtime. A desktop takeover vetoes both the stop and the
  // service refresh below; see `planUpdateRuntimeHandling` for why each half is wrong.
  const supervisionLatch = createSupervisionLatch();
  const observeSupervision = () => supervisionLatch.observe(inspectDesktopSupervision());
  const initialOwnership = await resolvedRuntimeOwnership();
  const runtimePlan = planUpdateRuntimeHandling({
    ...initialOwnership,
    serviceInstalled: serviceWasInstalled,
    supervision: observeSupervision(),
  });
  if (runtimePlan.notice) console.log(runtimePlan.notice);
  if (!runtimePlan.mayReplacePackage) {
    console.error("⚠️  Update stopped before tray handoff, runtime stop, or package replacement because runtime authority does not permit it.");
    return 1;
  }
  if (session) {
    const admission = await session.enterMutation();
    if (!admission.ok) return 10;
    mutationStarted = true;
  }
  let trayWasInstalled = false;
  let trayWasRunning = false;
  if (!homePolicy.packageOnly && process.platform === "win32") {
    try {
      const { getWindowsTrayStatus, guardedStartWindowsTray, guardedStopWindowsTray } = await import("./guarded-tray-ops");
      const tray = getWindowsTrayStatus();
      if (!homePolicy.authorizeMutation("tray")) return 1;
      let trayStopAttempted = false;
      const trayPlan = handoffWindowsTrayForUpdate(tray, {
        stop: () => {
          if (!homePolicy.authorizeMutation("tray")) throw new Error("Automatic update tray handoff refused; check 'ocx service status'.");
          trayStopAttempted = true;
          const stopped = guardedStopWindowsTray(homePolicy.authorizeMutation);
          return { exitStatus: 0, running: stopped.running };
        },
        start: () => { if (trayStopAttempted && homePolicy.authorizeMutation("own-tray")) guardedStartWindowsTray(homePolicy.authorizeMutation); },
      });
      trayWasInstalled = trayPlan.refreshAfterReplacement;
      trayWasRunning = trayPlan.restoreOnFailure;
    } catch (error) {
      console.error(`⚠️  Could not stop the Windows tray; aborting before package replacement: ${error instanceof Error ? error.message : String(error)}`);
      return 1;
    }
  }

  // Capture listen target before stop clears runtime state (same contract as GUI update worker).
  // Prefer a live runtime record; a stale crashed leftover must not override config.port.
  const preUpdateConfig = loadConfig();
  const preUpdateRt = readRuntimePort();
  const livePid = readPid();
  const runtimeTrusted = !!(preUpdateRt && livePid && preUpdateRt.pid === livePid);
  const configPort = typeof preUpdateConfig.port === "number" && preUpdateConfig.port > 0
    ? preUpdateConfig.port
    : 10100;
  const capturedListen = {
    port: runtimeTrusted ? preUpdateRt.port : configPort,
    hostname: (runtimeTrusted ? preUpdateRt.hostname : undefined) ?? preUpdateConfig.hostname ?? "127.0.0.1",
    ...(runtimeTrusted && livePid ? { oldPid: livePid } : {}),
  };

  const currentPackageRuntimeLiveness = () => inspectPackageRuntimeLiveness({
    capturedTarget: capturedListen,
    readCurrentTarget: () => readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname),
    probe: target => probeProxyLiveness(target.port, target.hostname),
  }).overall;
  const hadRuntimeState = serviceWasInstalled || !!livePid || !!preUpdateRt;

  let stopAttempted = false;
  let postUpdateLauncher = installer === "pnpm" && owner
    ? join(owner.packagePath, "bin", "ocx.mjs")
    : join(packageRoot(), "bin", "ocx.mjs");
  let postUpdateLauncherUsable = true;
  const sameOwner = (current: RuntimeOwnershipObservation) => {
    const before = initialOwnership.ownership, after = current.ownership;
    return before?.owner === after?.owner && before?.installId === after?.installId
      && before?.consentGeneration === after?.consentGeneration;
  };
  /** `"vetoed"`: another owner holds the runtime, so not starting is the correct outcome. */
  const startProxyDirectly = async (): Promise<boolean | "vetoed" | "refused"> => {
    // Every caller, including error recovery, owns the lock and fresh home proof here.
    try { mutation.reacquire(); } catch {
      console.warn("⚠️  Recovery could not acquire runtime ownership; run 'ocx service repair' or 'ocx start' manually after the other operation finishes.");
      return false;
    }
    if (!homePolicy.authorizeMutation("runtime")) return "refused";
    const ownership = await resolvedRuntimeOwnership();
    const supervision = observeSupervision();
    const plan = planUpdateRuntimeHandling({ ...ownership, serviceInstalled: false, supervision });
    if (!homePolicy.authorizeMutation("runtime")) return "refused";
    if (!sameOwner(ownership) || !plan.mayStopRuntime) {
      console.warn(supervision
        ? "OpenCodex Desktop supervises the proxy; no CLI runtime was restored."
        : plan.notice);
      return homePolicy.authorizeMutation("publish") ? "vetoed" : "refused";
    }
    if (!postUpdateLauncherUsable || !existsSync(postUpdateLauncher)) return false;
    // An ordinary owner: a stray sibling marker would otherwise mark it before any probe.
    const env = mutation.controlEnvironment(withoutSiblingMarker(process.env));
    delete env.OCX_SERVICE;
    // Not launched by a supervisor: none of its markers (src/lib/supervisor-markers.ts) may ride along.
    for (const name of ["OCX_DESKTOP_SUPERVISED", "OCX_SERVICE_MANAGED", "OCX_WINDOWS_WRAPPER_PROTOCOL"]) delete env[name];
    const runtimeEnv = withProcessRuntimeProvenance(env);
    if (!homePolicy.authorizeMutation("runtime")) return "refused";
    const child = guardedSpawn(homePolicy.authorizeMutation, "runtime", process.execPath, [postUpdateLauncher, "start", "--port", String(capturedListen.port)], {
      detached: true, stdio: "ignore", windowsHide: true, env: runtimeEnv,
    });
    let failed = false;
    child.once("error", () => { failed = true; });
    child.unref();
    const deadline = Date.now() + 30_000;
    while (!failed && Date.now() < deadline) {
      const current = readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname);
      if (current.kind === "target" && current.target.port === capturedListen.port
        && await proxyIdentityAt(current.target.port, { hostname: current.target.hostname, expectedPid: current.target.pid },
          { timeoutMs: 1500, deadlineAt: deadline, attempts: 1 })) return homePolicy.authorizeMutation("publish") ? true : "refused";
      await Bun.sleep(Math.min(100, Math.max(0, deadline - Date.now())));
    }
    console.warn("⚠️  Recovery did not report a healthy proxy before its deadline; run 'ocx service repair' or 'ocx start'.");
    return false;
  };
  // #7043: before any detached start, ask launchd/systemd to restart the job it already holds,
  // and count it only when the serving proxy is that job. Runs unleased: the manager's child
  // cannot join this lease (#5760). `"unsettled"` means the manager may still finish the restart,
  // so no competing proxy may be started.
  const restartThroughServiceManager = async (): Promise<"supervised" | "failed" | "unsettled" | "refused" | "vetoed"> => {
    if (!hasRestartableServiceManager()) return "failed";
    mutation.release();
    const owner = await resolvedRuntimeOwnership();
    if (!homePolicy.authorizeMutation("runtime")) return "refused";
    if (!homePolicy.serviceAllowed) return "failed";
    if (!sameOwner(owner) || !planUpdateRuntimeHandling({ ...owner, serviceInstalled: true,
      supervision: observeSupervision() }).mayRestoreService) return homePolicy.authorizeMutation("publish") ? "vetoed" : "refused";
    console.log("🔁 Asking the service manager to restart the background service...");
    const before = readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname);
    const staleRecordPid = before.kind === "target" ? before.target.pid : null;
    if (!homePolicy.authorizeMutation("service")) return homePolicy.authorizeMutation("runtime") ? "failed" : "refused";
    const restarted = restartServiceManagerJob({}, homePolicy.authorizeMutation);
    if (!restarted.ok && restarted.refused) return "refused";
    const unsettled = !restarted.ok && restarted.unsettled === true;
    let verdict: ReturnType<typeof supervisionVerdict> | { kind: "failed"; reason: string };
    if (!restarted.ok && !unsettled) {
      verdict = { kind: "failed", reason: restarted.reason };
    } else {
      let servingPid: number | null = null;
      const deadline = Date.now() + 30_000;
      while (servingPid === null && Date.now() < deadline) {
        const current = readUpdateRuntimeTarget(getRuntimePortPath(), capturedListen.hostname);
        if (current.kind === "target" && current.target.port === capturedListen.port
          && freshServingPid(current.target.pid, staleRecordPid) !== null
          && await proxyIdentityAt(current.target.port, { hostname: current.target.hostname, expectedPid: current.target.pid },
            { timeoutMs: 1500, deadlineAt: deadline, attempts: 1 })) servingPid = current.target.pid;
        else await Bun.sleep(Math.min(100, Math.max(0, deadline - Date.now())));
      }
      verdict = supervisionVerdict({ servingPid, managerPid: readServiceManagerPid(), parentPid: pid => readParentPid(pid) });
    }
    if (verdict.kind === "supervised") {
      if (!homePolicy.authorizeMutation("publish")) return "refused";
      guardedRun(homePolicy.authorizeMutation, "publish", console.log, [`✅ Proxy is healthy on port ${capturedListen.port} under the service manager (pid ${verdict.managerPid}).`]);
      return "supervised";
    }
    if (unsettled) {
      console.warn(unsettledManagerWarning(capturedListen.port));
      return "unsettled";
    }
    console.warn(`⚠️  The service manager did not recover a supervised proxy: ${verdict.reason}.`);
    return "failed";
  };
  /** Direct start as the last resort for a managed install: never reported as full recovery. */
  const startUnsupervisedFallback = async (): Promise<"vetoed" | "refused" | "started" | "failed"> => {
    const started = await startProxyDirectly();
    if (started === "vetoed" || started === "refused") return started;
    if (started) console.warn(unsupervisedRuntimeWarning(capturedListen.port));
    return started ? "started" : "failed";
  };
  const recoverStoppedRuntime = async (reason: string): Promise<void> => {
    try {
      const planRecovery = async () => {
        const current = await resolvedRuntimeOwnership();
        return planStoppedRuntimeRecovery({
          stopAttempted, ...current, sameOwner: sameOwner(current), supervision: observeSupervision(),
          liveness: currentPackageRuntimeLiveness(), serviceInstalled: serviceWasInstalled,
          launcherUsable: postUpdateLauncherUsable && existsSync(postUpdateLauncher), hadRuntimeState,
        });
      };
      let recovery = await planRecovery();
      if (!homePolicy.authorizeMutation("runtime")) return;
      if (recovery.action === "service") {
        // The service manager starts the proxy outside this process tree, so it
        // cannot join this lease, and holding it through the repair's health wait
        // keeps that proxy from starting (#5760). Release it, then decide again —
        // a claim could have landed while the repair ran unleased.
        mutation.release();
        if (!homePolicy.authorizeMutation("runtime")) return;
        recovery = await planRecovery();
      }
      if (recovery.reason === "desktop-supervised") {
        console.log("OpenCodex Desktop supervises the proxy; no CLI runtime was restored.");
      } else if (recovery.action === "manual") {
        console.warn(`⚠️  ${reason}; runtime recovery requires manual review (${recovery.reason}).`);
      } else if (recovery.action === "service") {
        const { serviceReinstallArgs, isServiceViable } = await import("../service");
        if (!homePolicy.authorizeMutation("runtime")) return;
        if (!homePolicy.serviceAllowed) { await startProxyDirectly(); return; }
        recovery = await planRecovery();
        if (recovery.action !== "service") {
          console.warn("Runtime authority changed before service recovery; no CLI runtime was restored.");
          return;
        }
        if (!homePolicy.authorizeMutation("runtime")) return;
        if (!homePolicy.serviceAllowed) { await startProxyDirectly(); return; }
        if (!homePolicy.authorizeMutation("service")) { if (homePolicy.authorizeMutation("runtime")) await startProxyDirectly(); return; }
        const service = guardedSpawnSync(homePolicy.authorizeMutation, "service", process.execPath, [postUpdateLauncher, ...serviceReinstallArgs()], {
          stdio: updateChildStdio(), windowsHide: true,
          env: mutation.controlEnvironment({ ...process.env, OCX_BAKE_PORT: String(capturedListen.port) }),
        });
        if (!homePolicy.authorizeMutation("runtime")) return;
        if (!homePolicy.serviceAllowed) { await startProxyDirectly(); return; }
        if (service.status !== 0 || !isServiceViable()) {
          // Ownership may have moved while the refresh ran unleased; only a recovery plan that
          // still names the service may restart the manager's job.
          if ((await planRecovery()).action === "service") {
            if (!homePolicy.authorizeMutation("runtime")) return;
            const managed = await restartThroughServiceManager();
            if (managed !== "failed") return;
          }
          // The refresh ran unleased; a claim could have landed meanwhile, so take
          // the lease back before re-reading ownership and authorizing a direct start.
          mutation.reacquire();
          const nowOwned = await resolvedRuntimeOwnership();
          const fallback = planStoppedRuntimeRecovery({
            stopAttempted, ...nowOwned, sameOwner: sameOwner(nowOwned), supervision: observeSupervision(),
            liveness: currentPackageRuntimeLiveness(), serviceInstalled: false,
            launcherUsable: postUpdateLauncherUsable && existsSync(postUpdateLauncher), hadRuntimeState,
          });
          if (fallback.action === "direct") await startUnsupervisedFallback();
          else console.warn("⚠️  Service recovery was not confirmed; no second proxy was started.");
        }
      } else if (recovery.action === "direct") {
        // No-op while the lease is held; re-locks if the service branch released it.
        mutation.reacquire();
        await startProxyDirectly();
      }
    } catch {
      console.warn("⚠️  Runtime recovery could not be verified; run 'ocx service repair' or 'ocx start' after checking ownership.");
    }
  };

  try {
  // Never replace package files under a live proxy: the running server dynamic-imports
  // modules after startup, so an in-place update leaves it executing mixed old/new code.
  // Gate on the service and the runtime-port record too, not just the pid file — a
  // service-managed or orphaned proxy can be live while ocx.pid is stale/missing.
  //
  // An outstanding pending-teardown receipt is a fourth reason to run the stop. After a
  // parent crashed mid-deferral all three of the other signals can be absent while the
  // shared client config still points at a proxy that is gone; installing over that
  // silently skips the recovery the receipt was written to trigger (#3008).
  // Full `ocx stop` semantics (drain, service stop, restore).

  if (homePolicy.packageOnly && pendingTeardownOutstanding()) {
    console.error("Pending teardown requires manual recovery before package replacement; run 'ocx stop' from the owning installation.");
    return 1;
  }
  if (!homePolicy.packageOnly && runtimePlan.mayStopRuntime && (serviceWasInstalled || readPid() || readRuntimePort() || pendingTeardownOutstanding())) {
    if (!homePolicy.authorizeMutation("runtime")) return 1;
    const preStopPlan = planUpdateRuntimeHandling({
      ...(await resolvedRuntimeOwnership()),
      serviceInstalled: serviceWasInstalled,
      supervision: supervisionLatch.observe(inspectDesktopSupervision({ targetPid: runtimeTrusted ? livePid : undefined })),
    });
    if (!preStopPlan.mayStopRuntime) {
      console.error(preStopPlan.notice);
      return 1;
    }
    stopAttempted = true;
    console.log("⏹  Stopping the running proxy before updating...");
    const stopStdio = updateChildStdio();
    if (!homePolicy.authorizeMutation("runtime")) return 1;
    if (serviceWasInstalled && !homePolicy.serviceAllowed) {
      console.warn("Service authority changed before proxy stop; check 'ocx service status' before retrying the update.");
      return 1;
    }
    if (!homePolicy.authorizeMutation(serviceWasInstalled ? "service" : "runtime")) return 1;
    const stop = guardedSpawnSync(homePolicy.authorizeMutation, serviceWasInstalled ? "service" : "runtime", process.execPath, selfLaunchArgv(["stop"]), {
      env: mutation.controlEnvironment(),
      stdio: stopStdio,
      encoding: stopStdio === "pipe" ? "utf8" : undefined,
      windowsHide: true,
    });
    if (stopStdio === "pipe") logSpawnOutput("", stop);
    // One decision, shared with the package launcher (#3008). The two lanes disagreeing about
    // the same situation is how this shipped fixed on one side only. Absent PID and runtime
    // files are weak evidence - a crashed-but-listening proxy leaves none - so the captured
    // endpoint is asked, and `null` from proxyIdentityAt covers refusal AND timeout alike.
    const identity = await proxyIdentityAt(capturedListen.port, { hostname: capturedListen.hostname });
    const decision = decidePostStopUpdate({
      status: stop.status,
      hasRuntimeState: !!(readPid() || readRuntimePort()),
      // Re-checked AFTER the stop: a quarantined receipt lets the stop itself succeed
      // (there is nothing left to stop), so a pre-stop check alone let the retry install
      // over a teardown that never ran.
      teardownOutstanding: pendingTeardownOutstanding(),
      liveness: identity ? "live" : probeProxyLiveness(capturedListen.port, capturedListen.hostname),
    });
    const historyOnlyStop = decision.reason === "history-only";
    if (!decision.proceed) {
      if (trayWasRunning) {
        try {
          const { guardedStartWindowsTray } = await import("./guarded-tray-ops");
          if (homePolicy.authorizeMutation("own-tray")) guardedStartWindowsTray(homePolicy.authorizeMutation);
        } catch { /* preserve the proxy stop failure */ }
      }
      if (decision.reason === "teardown-outstanding") {
        console.error("⚠️  A shared teardown from an earlier stop is still outstanding and needs manual review; aborting the update.");
        console.error("    Confirm no proxy is running, run 'ocx restore', then remove the pending-teardown file in your opencodex home.");
      } else {
        console.error(decision.reason === "proxy-unknown"
          ? `⚠️  Could not confirm the proxy on ${capturedListen.hostname}:${capturedListen.port} is stopped; aborting the update. Run 'ocx stop' and retry.`
          : "⚠️  Could not stop the running proxy; aborting the update. Run 'ocx stop' and retry.");
      }
      return 1;
    }
    if (historyOnlyStop || historyRestoreIncomplete()) {
      console.warn(
        "⚠️  Codex resume-history metadata restore is incomplete (a backup manifest remains).\n" +
        "    The DB may be busy or the manifest/target may need review; untracked routed history is intentionally unchanged.\n" +
        "    After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
      );
    }
    if (decision.reason === "history-deferred") {
      // Not the same warning: nothing was restored here. Saying "history metadata is
      // incomplete" would imply config and catalog came back, and an operator who
      // believed that would not know a teardown is still owed.
      console.warn(
        "⚠️  The shared teardown was refused by the Codex history preflight and restored nothing.\n" +
        "    Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
        "    The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
      );
    }
  }

  const installStdio = updateChildStdio();
  let r: {
    status: number | null;
    signal?: NodeJS.Signals | null;
    stdout?: string | Buffer | null;
    stderr?: string | Buffer | null;
  } | null = null;
  let replacementRefusal: string | null = null;
  // Re-read durable ownership and live supervision before package replacement.
  // Desktop supervision and foreign/unknown ownership veto replacement.
  // Plain unknown supervision preserves the existing ownership/liveness decision.
  const replacementOwnership = await resolvedRuntimeOwnership();
  const replacementPlan = planUpdateRuntimeHandling({
    ...replacementOwnership,
    serviceInstalled: serviceWasInstalled,
    supervision: observeSupervision(),
  });
  const replacementLiveness = currentPackageRuntimeLiveness();
  if (!homePolicy.authorizeMutation("package") || replacementOwnership.subjectToken !== initialOwnership.subjectToken
    || !replacementPlan.mayReplacePackage
    || replacementLiveness !== "dead") {
    replacementRefusal = replacementPlan.notice
      ?? (replacementLiveness === "live"
        ? "⚠️  Update stopped because a proxy became live after the stop decision; rerun from the beginning."
        : "⚠️  Update stopped because runtime ownership or liveness changed after the stop decision; rerun from the beginning.");
  } else {
  console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);

  // Every post-update action below receives the verified active launcher.
  if (installer === "pnpm") {
    let update: ReturnType<typeof runPnpmGlobalUpdate>;
    installerUncertain = true;
    try {
      if (!homePolicy.authorizeMutation("package")) return 1;
      update = runPnpmGlobalUpdate({
        packageName: PKG,
        currentVersion: current,
        targetVersion: latest || undefined,
        tag,
        owner: owner!,
        runningPackagePath: packageRoot(),
        runPnpm: (args, capture = false) => homePolicy.authorizeMutation("package") ? runOwnedPnpm(
          owner!,
          args,
          capture,
          capture ? "pipe" : installStdio,
          probeSpawnSync, homePolicy.authorizeMutation, session,
        ) : { status: 1, stdout: "", stderr: "" },
        log: line => console.log(line),
      });
    } catch {
      // A thrown verifier/runner error means the active group is unknown. Mark the
      // launcher unusable and let the failure lane report a manual recovery path.
      update = {
        ok: false,
        phase: "rollback",
        rolledBack: false,
        processTreeExited: false,
        error: "pnpm update failed unexpectedly; active package could not be verified",
      };
      session?.retainInstallerFence();
    }
    installerUncertain = !update.ok && update.processTreeExited === false;
    if (update.ok) {
      postUpdateLauncher = join(update.path, "bin", "ocx.mjs");
      postUpdateLauncherUsable = true;
      r = { status: 0, signal: null, stdout: "", stderr: "" };
    } else {
      postUpdateLauncherUsable = Boolean(update.activePath);
      if (update.activePath) postUpdateLauncher = join(update.activePath, "bin", "ocx.mjs");
      console.error(`⚠️  ${update.error}${update.rolledBack ? "." : " Manual recovery may be required."}`);
      r = { status: 1, signal: null, stdout: "", stderr: "" };
    }
  } else {
    if (!homePolicy.authorizeMutation("package")) return 1;
    installerUncertain = true;
    if (session && process.platform === "win32") {
      session.noteUntrackedInstaller();
      const supervised = runWindowsInstallerSync({ file: target.bin, args: target.args, options: target.options }, {
        env: mutation.unprivilegedEnvironment(), authorizeMutation: homePolicy.authorizeMutation,
        markerPath: join(getConfigDir(), "update-orchestrated.json"),
      });
      if (supervised.processTreeExited === true && Number.isInteger(supervised.status)) session.confirmInstallerExit();
      else session.retainInstallerFence();
      r = supervised;
      installerUncertain = supervised.processTreeExited !== true || !Number.isInteger(supervised.status);
    } else if (session) {
      try {
        const supervised = runPosixInstallerSync({ file: target.bin, args: target.args,
          markerPath: join(getConfigDir(), "update-orchestrated.json"),
          authorizeMutation: homePolicy.authorizeMutation, env: mutation.unprivilegedEnvironment() });
        installerUncertain = !Number.isInteger(supervised.status) || Boolean(supervised.signal) || !supervised.groupExited || supervised.groupKilled !== false || supervised.processTreeExited === false;
        if (installerUncertain) session.retainInstallerFence();
        r = supervised;
      } catch (error) { session.retainInstallerFence(); throw error; }
    } else r = guardedSpawnSync(homePolicy.authorizeMutation, "package", target.bin, target.args, {
      stdio: installStdio,
      encoding: installStdio === "pipe" ? "utf8" : undefined,
      // The parent watchdog reports overrun without killing an active transaction.
      timeout: child ? undefined : 180000,
      windowsHide: true,
      ...target.options,
      env: mutation.unprivilegedEnvironment(),
    });
    if (!session) installerUncertain = r.status === null;
  }
  if (r && installStdio === "pipe") logSpawnOutput("", r);
  }
  if (replacementRefusal) {
    await recoverStoppedRuntime("package replacement was refused");
    if (trayWasRunning) {
      try {
        const { guardedStartWindowsTray } = await import("./guarded-tray-ops");
        if (homePolicy.authorizeMutation("own-tray")) guardedStartWindowsTray(homePolicy.authorizeMutation);
      } catch { /* preserve the ownership refusal */ }
    }
    console.error(replacementRefusal);
    return 1;
  }
  if (!r) throw new Error("update replacement returned no result");
  if (installerUncertain) { console.error("Installer termination was not confirmed; update recovery is deferred."); return 1; }
  if (session && r.status === 0 && latest) {
    const root = realpathSync.native(packageRoot());
    if (verifyOrchestratedInstall(root, latest, "bun")) installedRoot = root;
  }
  const postInstallPlan = planUpdateRuntimeHandling({
    ...(await resolvedRuntimeOwnership()),
    serviceInstalled: serviceWasInstalled,
    supervision: observeSupervision(),
  });
  if (r.status === 0) {
    if (homePolicy.packageOnly) {
      if (!homePolicy.authorizeMutation("package-publish")) return 1;
      guardedRun(homePolicy.authorizeMutation, "package-publish", console.log, [`\n✅ Updated${latest ? ` to v${latest}` : ""}.`]);
      homePolicy.check(homePolicy.initial);
      console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, capturedListen.port)}`);
      if (!homePolicy.authorizeMutation("package-publish")) return 1;
      return process.argv.includes("--update-worker-result") ? UPDATE_PACKAGE_ONLY_EXIT_CODE : undefined;
    }
    // Authority gates every post-replacement control action (shim, tray, service), like
    // the Node launcher; refusal may only restore the own tray stopped before replacement.
    const restoreOwnStoppedTray = () => {
      if (trayWasRunning && postUpdateLauncherUsable && existsSync(postUpdateLauncher)) {
        try {
          if (!homePolicy.authorizeMutation("own-tray")) return;
          guardedSpawnSync(homePolicy.authorizeMutation, "own-tray", process.execPath, [postUpdateLauncher, "tray", "start"], {
            stdio: "ignore", windowsHide: true, timeout: 15_000, env: mutation.unprivilegedEnvironment(),
          });
        } catch { /* preserve the authority refusal */ }
      }
    };
    if (!homePolicy.authorizeMutation("publish")) {
      restoreOwnStoppedTray();
      return 1;
    }
    guardedRun(homePolicy.authorizeMutation, "publish", console.log, [`\n✅ Updated${latest ? ` to v${latest}` : ""}.`]);
    if (!postInstallPlan.mayStopRuntime) console.warn("Runtime authority does not permit CLI recovery; no service was refreshed or proxy started.");
    // Re-enter through the verified active package launcher. This keeps the Codex
    // shim, tray, service and proxy recovery paths on the same package/group that
    // pnpm selected, including when the update changed the global link target.
    let isCodexShimInstalled: (() => boolean) | undefined;
    try {
      ({ isCodexShimInstalled } = await import("../codex/shim"));
    } catch {
      console.warn("⚠️  Shim repair skipped; run 'ocx codex-shim install'.");
    }
    // The module load above is the last await before the control actions below; a home
    // change landing while it was in flight must veto the shim rewrite and the tray
    // refresh, not only the later service checks.
    if (!homePolicy.authorizeMutation("runtime")) {
      restoreOwnStoppedTray();
      return 1;
    }
    // The filesystem probe is part of the guarded recovery: a throw after package
    // replacement degrades to the warning below instead of escaping the update.
    try {
      if (isCodexShimInstalled?.()) {
        if (!homePolicy.authorizeMutation("shim")) { restoreOwnStoppedTray(); return 1; }
        const shim = guardedSpawnSync(homePolicy.authorizeMutation, "shim", process.execPath, [postUpdateLauncher, "codex-shim", "install"], {
          stdio: "inherit",
          windowsHide: true,
          env: mutation.unprivilegedEnvironment(),
        });
        if (shim.status !== 0) console.warn("⚠️  Shim repair skipped: run 'ocx codex-shim install'.");
      }
    } catch {
      console.warn("⚠️  Shim repair skipped; run 'ocx codex-shim install'.");
    }
    if (trayWasInstalled) {
      const trayArgs = planWindowsTrayUpdate({ installed: trayWasInstalled, running: trayWasRunning }).installArgs;
      if (!homePolicy.authorizeMutation("tray")) { restoreOwnStoppedTray(); return 1; }
      const tray = guardedSpawnSync(homePolicy.authorizeMutation, "tray", process.execPath, [postUpdateLauncher, ...trayArgs], { stdio: "inherit", windowsHide: true, env: mutation.unprivilegedEnvironment() });
      if (tray.status === 0) {
        console.log("🔧 Refreshed Windows tray startup paths.");
      } else {
        console.warn("⚠️  Windows tray refresh failed. Run 'ocx tray install'.");
        if (trayWasRunning && homePolicy.authorizeMutation("own-tray")) guardedSpawnSync(homePolicy.authorizeMutation, "own-tray", process.execPath, [postUpdateLauncher, "tray", "start"], { stdio: "ignore", windowsHide: true, env: mutation.unprivilegedEnvironment() });
      }
    }
    if (!homePolicy.authorizeMutation("publish")) { restoreOwnStoppedTray(); return 1; }
    // The stop above unloaded any managed service; repair it with the NEW files
    // (spawn the fresh cli.ts so updated code writes the baked paths) so a
    // launchd/schtasks/systemd user isn't left with the background proxy down.
    if (!homePolicy.serviceAllowed && postInstallPlan.mayStopRuntime) {
      if (stopAttempted) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
      console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, capturedListen.port)}`);
      return homePolicy.authorizeMutation("publish") ? undefined : 1;
    }
    if (postInstallPlan.mayRestoreService) {
      let homeRefused = false;
      const mayRefresh = async () => {
        if (!homePolicy.authorizeMutation("runtime")) { homeRefused = true; return false; }
        const ownership = await resolvedRuntimeOwnership();
        const supervision = observeSupervision();
        const plan = planUpdateRuntimeHandling({ ...ownership, serviceInstalled: true, supervision });
        if (!homePolicy.authorizeMutation("runtime")) { homeRefused = true; return false; }
        if (!plan.mayRestoreService) console.warn(supervision
          ? "OpenCodex Desktop supervises the proxy; CLI recovery was skipped. Use the app's updater (tray → Check for Updates)."
          : plan.notice);
        return plan.mayRestoreService && homePolicy.serviceAllowed;
      };
      if (!await mayRefresh()) {
        if (homeRefused) return 1;
        if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
        return homePolicy.authorizeMutation("publish") ? undefined : 1;
      }
      console.log("🔁 Refreshing the background service with the updated files...");
      const { serviceReinstallArgs } = await import("../service");
      const { guardedReclaimListenPort: reclaimListenPort } = await import("./guarded-port-reclaim");
      if (!homePolicy.authorizeMutation("runtime")) return 1;
      // Latched reclaim authority: once a mid-wait probe denies, the latch stays
      // closed — a transient re-match must not reopen kill/drop or the busy-port path.
      let reclaimDenied = false;
      const reclaimGate = () => {
        try { reclaimDenied ||= !homePolicy.authorizeMutation("runtime"); } catch { reclaimDenied = true; }
        return !reclaimDenied;
      };
      const freed = await reclaimListenPort(capturedListen.port, capturedListen.hostname, {
        timeoutMs: 30_000,
        intervalMs: 100,
        scanIntervalMs: 500,
        killOcxHolders: capturedListen.oldPid != null,
        onlyKillPids: capturedListen.oldPid != null ? [capturedListen.oldPid] : [],
        // The wait's internal awaits can span a home change; gate each kill/drop.
        mayMutateFn: reclaimGate,
      });
      if (!freed && !reclaimGate()) return 1; // a latched denial already refused
      if (!freed) {
        console.warn(`⚠️  Port ${capturedListen.port} still busy after 30s; repairing service with pinned --port ${capturedListen.port} anyway (refusing to hop).`);
      }
      // `service repair` re-activates a manager whose `ocx start` child is not a
      // process descendant and cannot join this lease; held through its serving
      // wait, the lease makes that child die at the acquire deadline (#5760).
      // The kill-authorizing reclaim above already ran under the lease.
      mutation.release();
      if (!homePolicy.authorizeMutation("runtime")) return 1;
      if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
      const prevBake = process.env.OCX_BAKE_PORT;
      process.env.OCX_BAKE_PORT = String(capturedListen.port);
      try {
        if (!await mayRefresh()) {
          if (homeRefused) return 1;
          if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
          return homePolicy.authorizeMutation("publish") ? undefined : 1;
        }
        const svcStdio = updateChildStdio();
        if (!homePolicy.authorizeMutation("runtime")) return 1;
        if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
        if (!homePolicy.authorizeMutation("service")) return homePolicy.authorizeMutation("runtime") && [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
        const svc = guardedSpawnSync(homePolicy.authorizeMutation, "service", process.execPath, [postUpdateLauncher, ...serviceReinstallArgs()], {
          env: mutation.controlEnvironment(),
          stdio: svcStdio,
          encoding: svcStdio === "pipe" ? "utf8" : undefined,
          windowsHide: true,
        });
        if (!homePolicy.authorizeMutation("runtime")) return 1;
        if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
        if (svcStdio === "pipe") logSpawnOutput("", svc);
        const serviceRefreshed = svc.status === 0;
        let serviceViable = serviceRefreshed;
        if (serviceRefreshed) {
          try {
            const { isServiceViable } = await import("../service");
            serviceViable = isServiceViable();
          } catch {
            serviceViable = false;
          }
        }
        if (!serviceRefreshed || !serviceViable) {
          // #7043: the manager first. Only a proxy it owns counts as recovered; everything
          // below this line leaves an unsupervised runtime and exits non-zero.
          if (!await mayRefresh()) {
            if (homeRefused) return 1;
            if (!homePolicy.serviceAllowed) return [true, "vetoed"].includes(await startProxyDirectly()) && homePolicy.authorizeMutation("publish") ? undefined : 1;
            return homePolicy.authorizeMutation("publish") ? undefined : 1;
          }
          if (!homePolicy.authorizeMutation("runtime")) return 1;
          const managed = await restartThroughServiceManager();
          if (managed === "supervised" || managed === "vetoed") return homePolicy.authorizeMutation("publish") ? undefined : 1;
          if (managed === "unsettled") return 1;
          if (managed === "refused") return 1;
          // Repair normally avoids elevation for a healthy scheduler task, but a stale
          // definition may require guarded create/elevation. It can also fail — or exit 0
          // while leaving stale/missing assets that never start
          // the proxy. Fall back to a direct detached proxy start so the update
          // never leaves the user without a running proxy — but only when the port is free.
          if (!freed) {
            console.warn(
              serviceRefreshed
                ? "⚠️  Service refresh left a non-viable manager and the captured port is still busy; not starting on another port."
                : "⚠️  Service refresh failed and the captured port is still busy; not starting on another port.",
            );
            console.warn(process.platform === "win32"
              ? `   Run 'ocx service repair', then 'ocx start --port ${capturedListen.port}'.`
              : `   Run 'ocx service repair' to see the reason, then 'ocx start --port ${capturedListen.port}'.`);
          } else {
            // Re-read rather than reuse the plan from before the package install: the app can
            // claim the runtime during an update that takes minutes, and the refusal the
            // repair above just returned is indistinguishable from any other failure here.
            // The refresh above ran outside the lease — take it back so this re-read and
            // the direct start stay serialized with a claim that landed in that window.
            // A claim that outlasts the wait is reported here: the package is already
            // swapped, so the unexpected-failure recovery below would run a second,
            // unleased repair and surface the raw lock error instead.
            try {
              mutation.reacquire();
            } catch {
              console.warn("⚠️  Updated, but another process kept the runtime ownership lease claimed, so no proxy was started.");
              console.warn(`   Run 'ocx service repair', then 'ocx start --port ${capturedListen.port}'.`);
              return 1;
            }
            const fallbackOwnership = await resolvedRuntimeOwnership();
            const supervision = observeSupervision();
            const nowOwned = planUpdateRuntimeHandling({
              ...fallbackOwnership,
              serviceInstalled: true,
              supervision,
            });
            if (!homePolicy.authorizeMutation("runtime")) return 1;
            if (!nowOwned.mayStopRuntime) {
              console.warn(supervision
                ? "OpenCodex Desktop supervises the proxy; CLI recovery was skipped. Use the app's updater (tray → Check for Updates)."
                : nowOwned.notice ?? "⚠️  The background runtime is owned elsewhere; not starting a second proxy.");
              return homePolicy.authorizeMutation("publish") ? undefined : 1;
            }
            console.warn(
              serviceRefreshed
                ? "⚠️  Service refresh left a non-viable manager (stale or missing assets) — starting the proxy directly instead."
                : "⚠️  Service refresh failed — starting the proxy directly instead.",
            );
            // Elevation is a Windows-only remedy; elsewhere the refresh fails for
            // reasons `ocx service repair` reports directly (since it now verifies
            // the service actually serves).
            console.warn(process.platform === "win32"
              ? "   Run 'ocx service repair' to refresh the background service."
              : "   Run 'ocx service repair' to refresh the background service and see why it failed.");
            // An ownership veto is the correct outcome, not a degraded one.
            if (await startUnsupervisedFallback() === "vetoed") return homePolicy.authorizeMutation("publish") ? undefined : 1;
            return 1;
          }
        }
      } finally {
        if (prevBake === undefined) delete process.env.OCX_BAKE_PORT;
        else process.env.OCX_BAKE_PORT = prevBake;
      }
    } else if (postInstallPlan.mayStopRuntime) {
      console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, capturedListen.port)}`);
    }
    if (!homePolicy.authorizeMutation("publish")) return 1;
  } else {
    if (stopAttempted && trayWasRunning && postUpdateLauncherUsable) {
      if (homePolicy.authorizeMutation("own-tray"))
      guardedSpawnSync(homePolicy.authorizeMutation, "own-tray", process.execPath, [postUpdateLauncher, "tray", "start"], { stdio: "ignore", windowsHide: true, env: mutation.unprivilegedEnvironment() });
    }
    await recoverStoppedRuntime("package update failed");
    console.error(`\n⚠️  Update failed (${bin} exit ${r.status ?? "?"}). ${manualUpdateFailureGuidance({ bin, args: cmdArgs, owner }).join("\n")}`);
    return 1;
  }
  } catch (error) {
    if (!installerUncertain) await recoverStoppedRuntime("update failed unexpectedly");
    if (trayWasRunning && !installerUncertain) {
      try { const { guardedStartWindowsTray } = await import("./guarded-tray-ops"); if (homePolicy.authorizeMutation("own-tray")) guardedStartWindowsTray(homePolicy.authorizeMutation); } catch { /* retain original failure */ }
    }
    throw error;
  }
  });
  completed = true;
  } finally {
    if (session && mutationStarted) session.finish(installedRoot
      ? { phase: "installed", activeRoot: installedRoot, ...(!completed || updateExitCode ? { recoveryFailed: true, error: "runtime-unhealthy" } : {}) }
      : { phase: "failed", error: installerUncertain ? "installer-timeout" : "update-failed", ...(installerUncertain ? { terminationConfirmed: false } : {}) });
  }
  if (updateExitCode) {
    if (child) process.exitCode = updateExitCode;
    else process.exit(updateExitCode);
  } else if (child && !mutationStarted) process.exitCode = 1;
}