@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
636 lines (612 loc) • 32.4 kB
text/typescript
import { randomUUID } from "node:crypto";
import { readDesktopDisconnectReceipt } from "../claude/desktop-remote-store";
import { flushLinkDiagnostics, recordLinkDiagnostic } from "../link/diagnostics";
import { existsSync } from "node:fs";
import type { Server } from "bun";
import { siblingRuntimeField, withSiblingMarker } from "../codex/sibling-start";
import { issueSiblingHandoff } from "../codex/sibling-handoff";
import { loadConfig, withConfigMutationLockSync } from "../config";
import { readRuntimePort, removePid, removeRuntimePort, writePid, writeRuntimePort, type ClientStopOwner, type RuntimePortState } from "../config/process-state";
import { currentServingCommand } from "../config/serving-runtimes";
import { installCrashGuards } from "../lib/crash-guard";
import { observeLocalCredentials } from "../local-credentials/runtime-observation";
import { verifiedHomeConnection } from "./link-connection";
import { createLocalAttestationSecret } from "../lib/local-management-attestation";
import { loadServiceTokenFromFile, serviceApiTokenFingerprint } from "../lib/service-secrets";
import { handledSignalExitCode } from "../lib/handled-signal-exit";
import {
CLIENT_RESTART_REBIND_WAIT_MS,
DESKTOP_RESTART_EXIT_CODE,
DESKTOP_SUPERVISED_ENV,
DESKTOP_SUPERVISED_PORT_WAIT_MS,
isDesktopSupervised,
} from "../lib/system-restart-contract";
import { findAvailablePort, isAddrInUse, PortUnavailableError, waitForPortAvailable } from "../server/ports";
import type { ReplacementStartRequest } from "../server/restart-replacement";
import type { OcxClientConnectionConfig } from "../types";
import { createLinkKeySource } from "./link-ingress";
import { HOME_INITIATED_LINK_TUNNEL } from "./link-relay";
import { clientInitiatedLinkReadiness, createHomeInitiatedLinkReadiness } from "./link-readiness";
import { createClientLinkSupervisor, type ClientLinkSupervisor } from "./link-tunnel";
import { clientLinkStatePath, isChildInitiatedLink, recordChildInitiatedLink } from "./link-state";
import { startMachineListener, type MachineListenerDeps } from "./machine-listener";
import { startHubRelayLeaseRefresh } from "./hub-relay";
import { currentHubRelayAdmission } from "./hub-session";
import { isLinkConnection, linkStopConnectionOwner, pendingClientConnectMayOwnToken, readClientConnectionState, readClientConnectionStateWithEvidence, sameClientConnectionOwner } from "./state";
import { withClientLifecycleSync } from "./lifecycle-lock";
import { clientConnectionEnded, clientRestartRollbackAction, clientRestartSupervisor, createClientRestartController, LEGACY_FLAG_RESTART_OWNER, restartOwnerEvidence, type ClientRestartController, type RecordedRestartOwner, type RestartOwner } from "./runtime-restart";
import { createLinkParityReporter, type LinkParityReporter } from "./link-parity-reporter";
import { restoreLinkClientRoutingBeforeExit } from "./stop-routing";
import { observeClientStopOwner } from "./stop-teardown-owner";
import { SUPERVISOR_MARKER_ENVS } from "../lib/supervisor-markers";
import { markClientRuntimeStopping, markClientRuntimeStoppingWithRetry } from "./sync-runtime";
import { startRouteIntentTick, type RouteIntentTick } from "../integrations/route-intent-tick";
import { startRouteIntentWatch, type RouteIntentRuntimeWatch } from "./route-intent-watch";
let activeServer: Server<unknown> | null = null;
let activePort: number | null = null;
let activeSupervisor: ClientLinkSupervisor | null = null;
let activeReporter: LinkParityReporter | null = null;
let activeRouteWatch: RouteIntentRuntimeWatch | null = null;
let activeRouteSync: RouteIntentTick | null = null;
let activeHubRelayRefresh: { stop(): void } | null = null;
// The local-credential observer lives exactly while this process serves (status attestation).
// Every path that stops serving stops it, including a recycle back to standalone.
let activeCredentialObservation: { stop(): void } | null = null;
let recycleScheduled = false;
let recycleTimer: ReturnType<typeof setTimeout> | undefined;
let recycleFlight: Promise<void> | null = null;
let clientStopping = false;
let explicitClientStopRequested: boolean | undefined;
let explicitClientStopOwner: ClientStopOwner | undefined;
let standaloneRecycleAllowed = () => !clientStopping;
/**
* When this runtime's process started (OCX-6, P5): what `/healthz` reports as `startedAt` and the
* Child reports to its Home. A Home settings apply recorded after it means this runtime predates it.
*/
export const CLIENT_RUNTIME_STARTED_AT = new Date(Date.now() - process.uptime() * 1000).toISOString();
/**
* How long link mode waits for its configured port: the budget a hard-pinned `ocx start --port`
* gives `reclaimListenPort` (`src/cli/index.ts`).
*/
export const LINK_PORT_WAIT_MS = 60_000;
/** How long a pinned port is re-probed after the reclaim wait before the start gives up on it. */
export const PINNED_PREFER_RETRY_MS = 5_000;
/**
* Link mode's port-reclaim budget. Under the desktop app the whole wait (this plus
* {@link PINNED_PREFER_RETRY_MS}) ends inside the app's 30-second startup deadline, so the app sees
* this start either serve or exit instead of giving up on it first.
*/
export function linkPortWaitMs(desktopSupervised: boolean = isDesktopSupervised()): number {
return desktopSupervised ? DESKTOP_SUPERVISED_PORT_WAIT_MS : LINK_PORT_WAIT_MS;
}
/** Bind attempts when the port is taken between the free-port probe and `Bun.serve`. */
const LINK_BIND_ATTEMPTS = 3;
export interface ClientRuntimeIo {
/** Link-mode port budget; defaults to {@link LINK_PORT_WAIT_MS}. */
portWaitMs?: number;
startListener?: typeof startMachineListener;
/** Which supervisor owns this process for a bound restart; tests replace the production check. */
restartSupervisor?: () => Promise<"service" | "desktop" | null>;
}
export interface StandaloneRecycleIo {
spawnReplacement?: (request: ReplacementStartRequest) => Promise<void>;
exitProcess?: (code: number) => void;
configuredPort?: () => number | undefined;
isDesktopSupervised?: () => boolean;
/** A service that will really relaunch this process; defaults to the OCX_SERVICE marker. */
serviceSupervised?: () => boolean;
}
function cleanup(): void {
removePid(process.pid);
removeRuntimePort(process.pid);
}
/**
* What this runtime publishes in `runtime-port.json`. The attestation secret is what the desktop app
* reads to authenticate the runtime it started (`desktop/src-tauri/src/auth.rs`); a record without one
* reads as unusable there, the same as a standalone start's record would.
*/
export function clientRuntimeRecord(
pid: number,
port: number,
attestationSecret: string = createLocalAttestationSecret(),
owner: RecordedRestartOwner | null = recordedOwner(),
): RuntimePortState {
let command: string[] | undefined;
try { command = currentServingCommand(); } catch { /* no reliable relaunch identity; update admission fails closed */ }
return { pid, port, hostname: "127.0.0.1", attestationSecret, ...(command ? { command } : {}), ...siblingRuntimeField(),
...(clientStopping ? { clientStopping: true as const } : {}),
...(explicitClientStopRequested !== undefined ? { clientStopRequested: explicitClientStopRequested } : {}),
...(explicitClientStopOwner ? { clientStopOwner: explicitClientStopOwner } : {}), ...(owner ? { restartOwner: owner } : {}) };
}
/** Evaluated once: the launch environment and parent of this process do not change. */
let ownerMemo: { value: RestartOwner | null } | undefined;
function classifiedOwner(): RestartOwner | null {
ownerMemo ??= { value: restartOwnerEvidence({ desktop: isDesktopSupervised(), env: process.env }) };
return ownerMemo.value;
}
const ownerProven = (): boolean => classifiedOwner() !== null;
/** The record's owner: the proven one, or legacy-flag for a bare OCX_SERVICE=1 (#8545; recordedRestartOwner). */
const recordedOwner = (): RecordedRestartOwner => classifiedOwner() ?? LEGACY_FLAG_RESTART_OWNER;
export function standaloneRecycleEnv(
env: NodeJS.ProcessEnv,
disconnectedTokenFingerprint: string,
): NodeJS.ProcessEnv {
const childEnv = { ...env };
// A detached replacement is nobody's child: not the desktop app's, not a service's, not a Windows
// wrapper's. It must carry no supervisor marker it would otherwise misread as its own.
for (const name of SUPERVISOR_MARKER_ENVS) delete childEnv[name];
delete childEnv.OCX_SERVICE;
const admissionToken = childEnv.OPENCODEX_API_AUTH_TOKEN?.trim();
if (admissionToken && serviceApiTokenFingerprint(admissionToken) !== disconnectedTokenFingerprint) {
// A surviving env token shadows OCX_API_TOKEN_FILE entirely, so nothing below can
// reintroduce the disconnected token.
return childEnv;
}
if (admissionToken) delete childEnv.OPENCODEX_API_AUTH_TOKEN;
// The respawned `ocx start` loads OCX_API_TOKEN_FILE into OPENCODEX_API_AUTH_TOKEN when the
// env token is absent, so vet the file by content: drop the pointer when it is unreadable or
// holds the disconnected token, keep it when it holds a different operator credential.
if (!childEnv.OCX_API_TOKEN_FILE?.trim()) return childEnv;
const fileToken = loadServiceTokenFromFile(childEnv);
if (fileToken === null || serviceApiTokenFingerprint(fileToken) === disconnectedTokenFingerprint) {
delete childEnv.OCX_API_TOKEN_FILE;
}
return childEnv;
}
export function scheduleStandaloneRecycle(disconnectedTokenFingerprint: string): void {
if (recycleScheduled || !standaloneRecycleAllowed()) return;
recycleScheduled = true;
recycleTimer = setTimeout(() => {
recycleTimer = undefined;
if (!standaloneRecycleAllowed()) { recycleScheduled = false; return; }
recycleFlight = recycleStandalone(disconnectedTokenFingerprint).finally(() => { recycleFlight = null; });
void recycleFlight.catch(error => { if (!clientStopping) throw error; });
}, 50);
if (typeof recycleTimer === "object" && "unref" in recycleTimer) recycleTimer.unref();
}
function configuredTcpPort(): number | undefined {
try {
const port = loadConfig().port;
return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : undefined;
} catch {
return undefined;
}
}
function errorCode(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 async function recycleStandalone(
disconnectedTokenFingerprint: string,
io: StandaloneRecycleIo = {},
): Promise<void> {
// The configured port when the listener never recorded one: the recycle still owes a proxy.
const port = activePort ?? (io.configuredPort ?? configuredTcpPort)();
const exit = io.exitProcess ?? ((code: number) => { process.exit(code); });
// Capture the one-use sibling handoff before this process removes its runtime record.
const serviceSupervised = (io.serviceSupervised ?? (() => process.env.OCX_SERVICE === "1"))();
const replacementEnv = port && !serviceSupervised
? withSiblingMarker(standaloneRecycleEnv(process.env, disconnectedTokenFingerprint), issueSiblingHandoff)
: null;
activeCredentialObservation?.stop(); activeCredentialObservation = null;
activeHubRelayRefresh?.stop(); activeHubRelayRefresh = null;
activeReporter?.stop(); activeReporter = null;
activeRouteWatch?.stop(); activeRouteWatch = null;
activeRouteSync?.stop(); activeRouteSync = null;
try {
await activeSupervisor?.stop();
} catch (error) {
console.warn(`[client] link supervisor stop failed: ${error instanceof Error ? error.message : String(error)}`);
}
activeSupervisor = null;
try {
activeServer?.stop(true);
} catch (error) {
console.warn(`[client] listener stop failed: ${error instanceof Error ? error.message : String(error)}`);
}
cleanup();
await flushLinkDiagnostics();
// Recycling back to standalone after `ocx disconnect` must actually bring a standalone
// proxy back, under every launch shape.
//
// Under the desktop app that spawned us: exit 75 and let the app start the standalone
// runtime, so it keeps owning it (tray Stop, Quit) instead of losing it to a detached child.
if ((io.isDesktopSupervised ?? isDesktopSupervised)()) {
exit(DESKTOP_RESTART_EXIT_CODE);
return;
}
// Unsupervised: spawn the replacement ourselves and exit 0.
//
// Supervised (`OCX_SERVICE=1`): do NOT spawn — the supervisor owns the process, and a
// second copy would fight it for the port. But exit 0 does not work either: the real
// supervisor configs are failure-only (systemd `Restart=on-failure`, WinSW
// `<onfailure action="restart"/>`, the Task Scheduler ERRORLEVEL loop), so a clean exit
// reads as "the service finished" and nothing restarts. The client stayed down until the
// operator noticed. Exit 1 is what those configs are watching for, and it is the same
// policy the dashboard recycle already uses (src/server/management/system-restart.ts).
//
// launchd's KeepAlive is failure-only too (`SuccessfulExit` false), so exit 1 is what
// relaunches it as well; an exit 0 would leave the job stopped.
if (serviceSupervised) {
exit(1);
return;
}
if (port === undefined) {
console.warn("[client] no valid port to restart the standalone proxy on; run 'ocx start'");
exit(1);
return;
}
if (!replacementEnv) throw new Error("Standalone recycle has no replacement environment.");
// Wait until the replacement answers (it retries an early exit) instead of exiting the moment
// it spawned: a replacement that died unseen left no proxy and nothing to report it.
try {
const spawnReplacement = io.spawnReplacement
?? (async (request: ReplacementStartRequest) => (await import("../server/restart-replacement")).spawnReplacementStart(request));
await spawnReplacement({
port,
waitForHealth: true,
// A sibling's replacement stays a sibling even if the owner is down while it probes.
env: replacementEnv,
});
} catch (error) {
console.warn(`[client] the standalone replacement did not start (${errorCode(error)}); run 'ocx start'`);
exit(1);
return;
}
exit(0);
}
/**
* Bind the client listener. Link mode is pinned to the configured port because Codex routes to it:
* like a hard-pinned `ocx start --port`, it waits for a port that a restarting parent is still
* releasing, never kills the holder and never hops. The waits run only while the port is busy; a
* free port binds on the first probe.
*/
export async function bindClientListener(
request: {
state: OcxClientConnectionConfig;
linkMode: boolean;
preferred: number;
explicitPort: boolean;
configuredPort: number;
} & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel" | "linkReadiness" | "linkConnectionGeneration" | "restart">,
io: ClientRuntimeIo = {},
): Promise<{ server: Server<unknown>; port: number }> {
const { linkMode } = request;
const portWaitMs = io.portWaitMs ?? (linkMode ? linkPortWaitMs() : LINK_PORT_WAIT_MS);
const deadline = Date.now() + portWaitMs;
const busy = (cause: unknown) => new Error(
`link mode needs port ${request.configuredPort}; free it or change port`,
{ cause },
);
let port: number;
try {
if (linkMode) {
const { reclaimListenPort } = await import("../server/port-reclaim");
await reclaimListenPort(request.configuredPort, "127.0.0.1", {
timeoutMs: portWaitMs,
intervalMs: 100,
scanIntervalMs: 500,
killOcxHolders: false,
dropTcpRows: true,
});
}
port = await findAvailablePort(request.preferred, "127.0.0.1", {
preferRetryMs: request.explicitPort ? PINNED_PREFER_RETRY_MS : 750,
preferRetryIntervalMs: 50,
allowEphemeralFallback: linkMode ? false : !request.explicitPort,
});
} catch (error) {
if (linkMode && error instanceof PortUnavailableError) throw busy(error);
throw error;
}
const startListener = io.startListener ?? startMachineListener;
for (let attempt = 1; ; attempt += 1) {
try {
const server = startListener(port, {
state: request.state,
machineApi: { scheduleStandaloneRecycle },
...(request.linkStatus ? { linkStatus: request.linkStatus } : {}),
...(request.linkKeySource ? { linkKeySource: request.linkKeySource } : {}),
...(request.linkTunnel ? { linkTunnel: request.linkTunnel } : {}),
...(request.linkReadiness ? { linkReadiness: request.linkReadiness } : {}),
...(request.linkConnectionGeneration ? { linkConnectionGeneration: request.linkConnectionGeneration } : {}),
...(request.restart ? { restart: request.restart } : {}),
});
return { server, port: server.port ?? port };
} catch (error) {
// Check-then-bind: the port can be taken between the probe and Bun.serve.
if (!linkMode || !isAddrInUse(error)) throw error;
const waitMs = Math.max(1_000, deadline - Date.now());
if (attempt >= LINK_BIND_ATTEMPTS
|| !(await waitForPortAvailable(port, "127.0.0.1", { timeoutMs: waitMs, intervalMs: 100 }))) {
throw busy(error);
}
}
}
}
export async function startClientRuntime(
options: { port?: number; block?: boolean; afterPublish?: () => void } = {},
io: ClientRuntimeIo = {},
): Promise<void> {
const state = readClientConnectionState();
if (state.kind !== "connected") throw new Error(`client runtime refused: client state is ${state.kind}`);
const config = loadConfig();
const linkMode = isLinkConnection(state.value);
const clientLinkOwner = linkMode ? linkStopConnectionOwner(state.value) : null;
if (linkMode && (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535)) {
throw new Error("link mode requires a valid local config port");
}
const preferred = linkMode ? config.port : options.port ?? config.port ?? 10100;
// Share one cached key source between the listener and its tunnel supervisor.
const linkKey = linkMode ? createLinkKeySource(state.value.tokenFingerprint) : undefined;
// Joins made before the marker existed get one now, while their sidecar is still here.
if (linkMode && state.value.link) {
try { recordChildInitiatedLink(state.value.link.linkId); } catch { /* the sidecar check below still applies */ }
}
const supervised = linkMode && existsSync(clientLinkStatePath());
// A Child with no sidecar and no record of joining itself was connected by its Home over
// `ssh -R`; that link keeps 2.67.0's unproven forward. A Child-initiated link that lost its
// sidecar gets no gate at all, so the relay refuses it.
const homeInitiated = linkMode && !supervised && !!state.value.link
&& !isChildInitiatedLink(state.value.link.linkId);
// One secret for the life of this process: a rollback republishes the same identity.
const attestationSecret = createLocalAttestationSecret();
// Bind, start a fresh tunnel supervisor and publish. Runs once at start and again when a failed
// restart rolls back (OCX-6); the stopped supervisor cannot be started twice, so each call builds one.
// The port this process actually serves on; a rollback binds exactly this one again.
let servedPort = preferred;
const observeExplicitStop = (): boolean => {
const current = readRuntimePort(process.pid);
if (current?.port === servedPort && current.attestationSecret === attestationSecret && current.clientStopRequested !== undefined) {
explicitClientStopRequested = current.clientStopRequested;
explicitClientStopOwner = current.clientStopOwner;
clientStopping = true;
}
return explicitClientStopRequested === true
&& (!explicitClientStopOwner || observeClientStopOwner(explicitClientStopOwner) !== "confirmed-stale");
};
// An unpublishable rollback closes the new listener before the caller considers a recycle.
const serve = async (rollback?: { port: number; portWaitMs: number }): Promise<boolean> => {
const supervisor = supervised
? createClientLinkSupervisor({
diagnostic: recordLinkDiagnostic,
onLinkEnded: () => scheduleStandaloneRecycle(state.value.tokenFingerprint),
linkKey,
})
: null;
// What `/readyz` reports about the link: the supervisor's tunnel, or for a Home-initiated
// link the shared relay preflight. A link with neither refuses every relayed request.
const link = state.value.link;
const linkReadiness: MachineListenerDeps["linkReadiness"] = !linkMode ? undefined
: supervisor ? () => clientInitiatedLinkReadiness(supervisor.status())
: homeInitiated && link && linkKey
? createHomeInitiatedLinkReadiness({ target: { tunnelPort: link.tunnelPort, linkId: link.linkId, apiKeyId: state.value.apiKeyId }, linkKey })
: () => ({ ready: false, reason: "tunnel_unavailable" });
const { server, port: boundPort } = await bindClientListener({
state: state.value,
linkMode,
// A rollback takes back exactly the port it gave up: never the preferred one, never another.
preferred: rollback?.port ?? preferred,
explicitPort: rollback !== undefined || options.port !== undefined,
configuredPort: config.port,
restart: { attestationSecret, startedAt: CLIENT_RUNTIME_STARTED_AT, ...(linkMode ? { linkStopFence: true as const } : {}), request: () => restartController.request() },
...(linkMode ? { linkStatus: () => activeSupervisor?.status() ?? { kind: "stopped" as const }, linkKeySource: linkKey } : {}),
...(supervisor ? { linkTunnel: supervisor } : homeInitiated ? { linkTunnel: HOME_INITIATED_LINK_TUNNEL } : {}),
...(linkReadiness ? { linkReadiness } : {}),
...(supervisor ? { linkConnectionGeneration: () => supervisor.connectionGeneration() }
: homeInitiated && link ? { linkConnectionGeneration: () => verifiedHomeConnection(link.linkId) } : {}),
}, rollback === undefined ? io : { ...io, portWaitMs: rollback.portWaitMs });
const publishRecord = (): void => {
// A parent stop can arrive after restart admission. Never clear its fence on rollback;
// a fresh process has another attestation identity and cannot inherit this request.
if (rollback) observeExplicitStop();
writePid(process.pid);
// A new generation refuses commits from syncs admitted before the failed restart.
writeRuntimePort({ ...clientRuntimeRecord(process.pid, boundPort, attestationSecret), servingGeneration: randomUUID(),
clientLinkOwner });
};
const activate = (): void => {
activeServer = server;
activePort = boundPort;
servedPort = boundPort;
activeSupervisor = supervisor;
supervisor?.start();
activeCredentialObservation ??= observeLocalCredentials();
if (!linkMode) {
activeHubRelayRefresh ??= startHubRelayLeaseRefresh(state.value.managementUrl,
(method, target) => currentHubRelayAdmission(state.value, method, target));
}
if (linkMode && state.value.link && linkKey) {
activeReporter = createLinkParityReporter({ connection: state.value, linkKey, runtimeStartedAt: CLIENT_RUNTIME_STARTED_AT });
activeReporter.start();
const scheduler = startRouteIntentTick(state.value, { onApplied: () => activeReporter?.requestReport() });
activeRouteSync = scheduler;
activeRouteWatch = startRouteIntentWatch(state.value, linkKey, { requestSync: () => scheduler.requestSync() });
}
};
if (!rollback) {
publishRecord();
activate();
return true;
}
// Admission and publication are synchronous after bind. A busy lock must close the
// rebound listener before yielding. Link takes C to preserve an explicit stop fence.
const publishIfOwned = () => {
if (clientRestartRollbackAction(state.value, readClientConnectionState()) === "recycle") return false;
publishRecord();
return true;
};
let published = false;
try {
published = withClientLifecycleSync(() => linkMode ? withConfigMutationLockSync(publishIfOwned) : publishIfOwned());
} catch { /* failed admission */ }
if (published) activate();
else {
try { await server.stop(true); } catch { /* never published */ }
}
return published;
};
// Stop everything this process serves, giving in-flight requests up to `drainMs`.
const stopServing = async (drainMs: number): Promise<void> => {
activeCredentialObservation?.stop();
activeCredentialObservation = null;
activeHubRelayRefresh?.stop(); activeHubRelayRefresh = null;
activeReporter?.stop();
activeReporter = null;
activeRouteWatch?.stop(); activeRouteWatch = null;
activeRouteSync?.stop(); activeRouteSync = null;
try {
await activeSupervisor?.stop();
} catch (error) {
console.warn(`[client] link supervisor stop failed: ${error instanceof Error ? error.message : String(error)}`);
}
activeSupervisor = null;
const server = activeServer;
activeServer = null;
if (!server) return;
let timer: ReturnType<typeof setTimeout> | undefined;
try {
await Promise.race([
Promise.resolve(server.stop(false)),
new Promise<void>(resolve => { timer = setTimeout(resolve, drainMs); }),
]);
} catch { /* closed below */ } finally {
if (timer) clearTimeout(timer);
}
try { await server.stop(true); } catch { /* already closed */ }
};
let shuttingDown = false;
standaloneRecycleAllowed = () => {
try {
if (shuttingDown || observeExplicitStop()) return false;
if (!clientStopping) return true;
// A retained sync fence is not an active exit. Only a completed disconnect of this exact
// served owner permits recovery; partial cleanup, a new connect or uncertain state cannot.
return withConfigMutationLockSync(() => {
if (observeExplicitStop()) return false;
const receipt = readDesktopDisconnectReceipt();
return ownerProven() && !pendingClientConnectMayOwnToken()
&& readClientConnectionStateWithEvidence().kind === "disconnected"
&& receipt.kind === "valid" && receipt.value.phase === "complete"
&& sameClientConnectionOwner(receipt.value.owner, state.value)
&& receipt.value.tokenFingerprint === state.value.tokenFingerprint;
});
} catch { return false; }
};
const restartController: ClientRestartController = createClientRestartController({
stopping: () => !standaloneRecycleAllowed(),
supervisor: io.restartSupervisor ?? clientRestartSupervisor,
connectionChanged: () => clientConnectionEnded(state.value, readClientConnectionStateWithEvidence()),
ownerProven,
recycle: supervisor => recycleStandalone(state.value.tokenFingerprint, {
isDesktopSupervised: () => supervisor === "desktop",
serviceSupervised: () => supervisor === "service",
}),
// Fence Link syncs before the teardown: a sync already past admission would otherwise keep
// writing client files and receipts while the listener closes. Marking the record makes every
// later commit stand down under C; the replacement's record, or the fresh generation a rollback
// publishes, keeps those syncs refused and admits new ones. A mark that cannot be written
// abandons the restart before anything stops.
fence: async () => !linkMode || await markClientRuntimeStoppingWithRetry({ pid: process.pid, port: servedPort, attestationSecret }, {
mark: () => withConfigMutationLockSync(() => {
if (observeExplicitStop()) throw new Error("client_stop_requested");
markClientRuntimeStopping({ pid: process.pid, port: servedPort, attestationSecret });
}),
}),
stop: stopServing,
spawnReplacement: async deadlineAt => {
const { replacementStartEnvironment } = await import("../server/management/system-restart");
const { spawnReplacementStart } = await import("../server/restart-replacement");
await spawnReplacementStart(
{ port: activePort ?? config.port, waitForHealth: true, env: replacementStartEnvironment(true), notReady: "terminate" },
{ deadlineAt },
);
},
resume: async () => {
const recycleAfterRollback = () => {
if (standaloneRecycleAllowed()) return recycleStandalone(state.value.tokenFingerprint);
};
// The connection may have changed while the replacement was starting (`ocx disconnect`, a
// new connect). Serving the old one again would be a stale runtime nothing recycles; hand
// off to the recycle, which starts whatever the durable state now calls for.
if (clientRestartRollbackAction(state.value, readClientConnectionState()) === "recycle") {
await recycleAfterRollback();
return;
}
if (!(await serve({ port: servedPort, portWaitMs: CLIENT_RESTART_REBIND_WAIT_MS }))) {
await recycleAfterRollback();
}
},
exitProcess: async code => {
try { await flushLinkDiagnostics(); }
finally { process.exit(code); }
},
});
installCrashGuards();
// serve() publishes the pid and runtime record; the ownership lease is released only after it.
await serve();
options.afterPublish?.();
const shutdown = (signal?: NodeJS.Signals) => {
if (shuttingDown) return;
shuttingDown = true;
clientStopping = true;
if (recycleTimer) {
clearTimeout(recycleTimer);
recycleTimer = undefined;
recycleScheduled = false;
}
const fenceSync = () => {
if (!linkMode) return true;
try { markClientRuntimeStopping({ pid: process.pid, port: servedPort, attestationSecret }); return true; }
catch { return false; }
};
let syncFenced = fenceSync();
void (async () => {
// An accepted restart owns its replacement and rollback. A successful handoff exits
// inside that flight; a rollback finishes before this signal tears the runtime down.
if (restartController.hasHandoff()) await restartController.settled().catch(() => {});
if (recycleFlight) await recycleFlight.catch(() => {});
// A rollback may have republished its runtime record while shutdown joined it.
syncFenced = !linkMode || await markClientRuntimeStoppingWithRetry({ pid: process.pid, port: servedPort, attestationSecret });
activeCredentialObservation?.stop();
activeCredentialObservation = null;
activeHubRelayRefresh?.stop(); activeHubRelayRefresh = null;
activeReporter?.stop();
activeReporter = null;
activeRouteWatch?.stop(); activeRouteWatch = null;
activeRouteSync?.stop(); activeRouteSync = null;
try {
await activeSupervisor?.stop();
} catch (error) {
console.warn(`[client] link supervisor stop failed: ${error instanceof Error ? error.message : String(error)}`);
}
activeSupervisor = null;
const restored = linkMode ? await restoreLinkClientRoutingBeforeExit(state.value, {
syncFenced, runtime: { pid: process.pid, port: servedPort, attestationSecret },
}) : null;
if (restored && !restored.success) console.error(`[client] ${restored.message}`);
if (restored?.retainListener) {
// Keep the stopping record and socket. Another signal can retry after the operator
// repairs the retained file/ownership evidence; no background sync can reapply it.
shuttingDown = false;
return;
}
try {
activeServer?.stop(true);
} catch (error) {
console.warn(`[client] listener stop failed: ${error instanceof Error ? error.message : String(error)}`);
} finally {
// Keep stopping admission visible through the last await. Cleanup and exit are adjacent.
try { await flushLinkDiagnostics(); } finally { cleanup(); }
// launchd relaunches only unsuccessful exits; an external signal must still count.
if (restored?.success === false) process.exit(1);
else process.exit(handledSignalExitCode(signal));
}
})();
};
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);
if (process.platform !== "win32") process.on("SIGHUP", shutdown);
process.on("exit", cleanup);
if (options.block ?? true) await new Promise<void>(() => {});
}