UNPKG

@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
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>(() => {}); }