@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
271 lines (251 loc) • 14.7 kB
text/typescript
/**
* The connected client runtime's answer to the bound `POST /api/system/restart` (OCX-6).
*
* It is the same restart `ocx restart` drives on a standalone proxy, with one difference the
* Remote Link parity work requires: a failed restart keeps the old runtime. That is only possible
* when this process starts its own replacement, so:
*
* - Under the desktop app or a viable service supervisor the restart is refused (409
* `restart_supervised`) and the runtime keeps serving. A runtime whose only owner evidence is a
* bare OCX_SERVICE=1 is always refused (`legacy-flag`), connection ended or not (#8545). The supervisor owns this process and its
* port; handing off to it means exiting before anything proves the replacement can start.
* - Unless the connection it serves is no longer the durable one (`ocx disconnect`, or a newer
* connect). Then there is nothing to keep, and under every owner the restart hands off to the
* standalone recycle, which exits the way that owner relaunches (desktop 75, service 1) or spawns
* its own replacement. Without this a Home-driven leave over SSH could not finish under the
* desktop app or a service: `ocx restart` refused and the stale client runtime kept serving.
* - Otherwise the listener drains, a replacement `ocx start` is spawned and must answer within the
* budget. Success exits this process. A replacement that exited, or never answered and was then
* stopped, leaves this process to bind the port again, start a fresh tunnel supervisor and
* republish its records: the old runtime keeps serving and the CLI, still seeing its pid,
* reports the restart as failed.
*
* Everything runs inside {@link CLIENT_RESTART_BUDGET_MS} from acceptance.
*/
import {
CLIENT_RESTART_DRAIN_MS,
CLIENT_RESTART_READY_BY_MS,
isDesktopSupervised,
} from "../lib/system-restart-contract";
import type { OcxClientConnectionConfig } from "../types";
import { isMarkedSupervisedServiceChild } from "../service/service-child-ownership";
import { sameClientConnectionOwner, type readClientConnectionState } from "./state";
type ClientConnectionState = ReturnType<typeof readClientConnectionState>;
/**
* `service-unproven`: a service manager's marker shows it launched and owns this process, but its
* relaunch cannot be proven (for example a systemd unit started by hand while disabled). Neither
* exiting for it nor detaching from it is safe, so the restart is refused.
*
* `legacy-flag`: the only owner evidence is a bare OCX_SERVICE=1, which a service registered before
* the manager marker existed (before 2.49.0) and the proxies of ocx claude, ocx codex and ocx opencode
* all carry. Nothing tells them apart, and the owner is never inferred (not from the service
* diagnostic, not from the parent's command line), so the restart is refused with advice to
* re-register the service once (#8545 owner decision, 2026-11-16).
*/
export type ClientRestartSupervisor = "service" | "desktop" | "service-unproven" | "legacy-flag";
/** Verdicts that keep the runtime: exiting for the owner or detaching from it is not proven safe. */
export function restartRefusedByOwner(supervisor: ClientRestartSupervisor | null): supervisor is "service-unproven" | "legacy-flag" {
return supervisor === "service-unproven" || supervisor === "legacy-flag";
}
export type ClientRestartAdmission =
| { kind: "accepted"; alreadyRestarting: boolean }
| { kind: "stopping" }
| { kind: "supervised"; supervisor: ClientRestartSupervisor };
export interface ClientRestartIo {
/** A signal shutdown has claimed this runtime; it cannot admit a replacement. */
stopping?: () => boolean;
/** Which supervisor owns this process, or null when it starts its own replacement. */
supervisor(): Promise<ClientRestartSupervisor | null>;
/** The durable connection is no longer the one this runtime serves. */
connectionChanged?: () => boolean;
/**
* Positive evidence of who owns this process ({@link restartOwnerProven}). Without it the
* ended-connection recycle is never reached, and the supervisor check refuses the restart.
*/
ownerProven?: () => boolean;
/**
* Hand off to what the durable state now calls for; exits the process for its owner to relaunch.
* Receives the same supervisor verdict as the refusal path (a service only when it is viable).
*/
recycle?: (supervisor: ClientRestartSupervisor | null) => Promise<void>;
/**
* Fence syncs before anything stops: resolves false when they could not be fenced, and the
* restart is then abandoned with this runtime still serving.
*/
fence?: () => Promise<boolean>;
/** Stop the tunnel supervisor and the listener, giving in-flight requests up to `drainMs`. */
stop(drainMs: number): Promise<void>;
/** Start the replacement; resolves once it answers, rejects when none survives. */
spawnReplacement(deadlineAt: number): Promise<void>;
/** Serve again on this process: listener, fresh tunnel supervisor, records. */
resume(): Promise<void>;
exitProcess(code: number): void | Promise<void>;
now?: () => number;
sleep?: (ms: number) => Promise<void>;
warn?: (message: string) => void;
}
export interface ClientRestartController {
request(): Promise<ClientRestartAdmission>;
/** Only an accepted flight owns routing; a supervisor check does not. */
hasHandoff(): boolean;
/** Join the accepted flight before signal teardown; may reject on a failed exit callback. */
settled(): Promise<void>;
}
/** Stable, path-free label for a failure (an error message can carry a path). */
function failureCode(error: unknown): string {
const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
return typeof code === "string" && /^[A-Za-z0-9_]{1,64}$/.test(code) ? code : "failed";
}
export function createClientRestartController(io: ClientRestartIo): ClientRestartController {
const now = io.now ?? Date.now;
const sleep = io.sleep ?? Bun.sleep;
const warn = io.warn ?? ((message: string) => console.warn(message));
let flight: Promise<void> | null = null;
const run = async (acceptedAt: number): Promise<void> => {
// Let the 202 reach the CLI before the listener starts closing.
await sleep(200);
// A sync already past admission must stand down before the teardown. Without that fence it
// could commit while the listener closes, so the restart does not start; the CLI sees this
// process still serving and reports the restart as failed.
let fenced = false;
try { fenced = io.fence ? await io.fence() : true; } catch (error) { warn(`[client] restart: syncs could not be fenced (${failureCode(error)})`); }
if (!fenced) {
warn("[client] restart: in-flight syncs could not be fenced; this runtime keeps serving");
return;
}
try {
await io.stop(CLIENT_RESTART_DRAIN_MS);
} catch (error) {
warn(`[client] restart: stopping the runtime failed (${failureCode(error)}); continuing`);
}
try {
await io.spawnReplacement(acceptedAt + CLIENT_RESTART_READY_BY_MS);
} catch (error) {
warn(`[client] restart: the replacement did not start (${failureCode(error)}); this runtime keeps serving`);
try {
await io.resume();
} catch (resumeError) {
warn(`[client] restart: this runtime could not serve again (${failureCode(resumeError)}); run 'ocx start'`);
await io.exitProcess(1);
}
return;
}
await io.exitProcess(0);
};
return {
hasHandoff: () => flight !== null,
async request() {
if (io.stopping?.()) return { kind: "stopping" };
// Only positive ownership evidence opens the ended-connection recycle; without it (a bare
// OCX_SERVICE=1) the supervisor check below refuses the request as `legacy-flag`.
if (io.recycle && (io.ownerProven?.() ?? true) && io.connectionChanged?.()) {
if (flight) return { kind: "accepted", alreadyRestarting: true };
// An owner that cannot be proven to relaunch this process keeps it, connection ended or not.
const owner = await io.supervisor();
if (io.stopping?.()) return { kind: "stopping" };
if (restartRefusedByOwner(owner)) return { kind: "supervised", supervisor: owner };
if (flight) return { kind: "accepted", alreadyRestarting: true };
const recycle = io.recycle, changed = io.connectionChanged;
// Let the 202 reach the CLI before the listener closes, then confirm the connection is
// still ended: a connect that committed meanwhile keeps this runtime (the CLI reports kept).
// The recheck is the last step before the recycle, after the (asynchronous) supervisor lookup.
flight = sleep(200).then(async () => {
const supervisor = await io.supervisor();
if (io.stopping?.()) return;
if (restartRefusedByOwner(supervisor)) { warn("[client] restart: this runtime's owner could not be proven to relaunch it; it keeps serving"); return; }
if (changed()) await recycle(supervisor);
}).finally(() => { flight = null; });
return { kind: "accepted", alreadyRestarting: false };
}
const supervisor = await io.supervisor();
if (io.stopping?.()) return { kind: "stopping" };
if (supervisor) return { kind: "supervised", supervisor };
if (flight) return { kind: "accepted", alreadyRestarting: true };
flight = run(now()).finally(() => { flight = null; });
return { kind: "accepted", alreadyRestarting: false };
},
async settled() {
await flight;
},
};
}
/** Production supervision check: the desktop app, then a service that will really relaunch us. */
export async function clientRestartSupervisor(): Promise<ClientRestartSupervisor | null> {
const { diagnoseService } = await import("../service/diagnostics");
return classifyClientRestartSupervisor({ desktop: isDesktopSupervised(), env: process.env, diagnose: diagnoseService });
}
/**
* Positive evidence of who owns this process: the desktop app, a service manager's marker
* (OCX_SERVICE_MANAGED or the Windows wrapper's protocol marker, read from the environment only),
* or no OCX_SERVICE at all (every service OpenCodex registers sets it). No inference: a legacy
* Windows service recognised only from its parent's command line counts as a bare OCX_SERVICE=1.
* A bare OCX_SERVICE=1 is none of these: a service registered before the manager marker existed
* and the proxies of ocx claude, ocx codex and ocx opencode all carry it.
*/
export function restartOwnerProven(input: { desktop: boolean; env: NodeJS.ProcessEnv; managed?: (env: NodeJS.ProcessEnv) => boolean }): boolean {
return restartOwnerEvidence(input) !== null;
}
/** The owners this change handles, as a client runtime states them in its record (`restartOwner`). */
export type RestartOwner = "desktop" | "service-manager" | "none";
export const RESTART_OWNERS: readonly RestartOwner[] = ["desktop", "service-manager", "none"];
/** The classified owner from positive evidence, or null for a bare OCX_SERVICE=1 ({@link restartOwnerProven}). */
export function restartOwnerEvidence(input: { desktop: boolean; env: NodeJS.ProcessEnv; managed?: (env: NodeJS.ProcessEnv) => boolean }): RestartOwner | null {
if (input.desktop) return "desktop";
if ((input.managed ?? isMarkedSupervisedServiceChild)(input.env)) return "service-manager";
return input.env.OCX_SERVICE !== "1" ? "none" : null;
}
/** What a client runtime with a bare OCX_SERVICE=1 states in its record: no owner, and `ocx disconnect` gives the advice. */
export const LEGACY_FLAG_RESTART_OWNER = "legacy-flag";
export type RecordedRestartOwner = RestartOwner | typeof LEGACY_FLAG_RESTART_OWNER;
/** The record's `restartOwner`: the proven owner, or `legacy-flag` for a bare OCX_SERVICE=1. */
export function recordedRestartOwner(input: { desktop: boolean; env: NodeJS.ProcessEnv; managed?: (env: NodeJS.ProcessEnv) => boolean }): RecordedRestartOwner {
return restartOwnerEvidence(input) ?? LEGACY_FLAG_RESTART_OWNER;
}
/**
* Ownership and relaunch are separate facts. With a manager's marker, only a service diagnostic
* that is viable and running lets this process exit for the manager to relaunch it; otherwise it is
* `service-unproven` and keeps the runtime. A bare OCX_SERVICE=1 is `legacy-flag` whatever the
* service diagnostic says: refused, never stopped or replaced on inference (#8545).
*/
export function classifyClientRestartSupervisor(input: {
desktop: boolean;
env: NodeJS.ProcessEnv;
diagnose: () => { viable: boolean; running: boolean };
/** Manager-launched evidence; defaults to the current markers only (isMarkedSupervisedServiceChild). */
managed?: (env: NodeJS.ProcessEnv) => boolean;
}): ClientRestartSupervisor | null {
if (input.desktop) return "desktop";
// The managed marker (launchd, systemd, WinSW) or the Windows wrapper's protocol marker.
if (!(input.managed ?? isMarkedSupervisedServiceChild)(input.env)) {
return input.env.OCX_SERVICE !== "1" ? null : "legacy-flag";
}
// Relaunch needs positive evidence: viable AND running (launchd's viable also covers an
// unknown load state for its other callers; running there means loaded).
const diagnostic = input.diagnose();
return diagnostic.viable && diagnostic.running ? "service" : "service-unproven";
}
/**
* After a failed replacement: serve the same connection again only while it is still the durable
* one (same owner and link). Anything else, a disconnect or a different connection, goes to the
* recycle, which starts what the current state calls for instead of a stale client runtime.
*/
export function clientRestartRollbackAction(
served: OcxClientConnectionConfig,
current: ClientConnectionState,
): "resume" | "recycle" {
return current.kind === "connected" && sameClientConnectionOwner(current.value, served)
&& current.value.link?.linkId === served.link?.linkId
? "resume"
: "recycle";
}
/**
* Whether the served connection has provably ended: the durable state is disconnected, or names a
* different connection. Unreadable or mismatched state is not proof, so a supervised restart keeps
* refusing on it instead of exiting a runtime whose link may still work.
*/
export function clientConnectionEnded(served: OcxClientConnectionConfig, current: ClientConnectionState): boolean {
// Callers pass readClientConnectionStateWithEvidence(): "disconnected" then means a saved config
// with no client, never a missing file.
if (current.kind === "disconnected") return true;
return current.kind === "connected" && clientRestartRollbackAction(served, current) === "recycle";
}