@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
text/typescript
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;
}