UNPKG

@bitkyc08/opencodex

Version:

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

942 lines (870 loc) • 44 kB
import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; import { delimiter, dirname, join, posix, resolve, win32 } from "node:path"; import { expandUserPath, getConfigDir } from "../config"; import { atomicWriteFileStreamed } from "../config/atomic-write"; import { resolveCodexHomeDir, type CodexHomeDeps } from "../codex/home"; import { resolveCodexSqliteHome } from "../codex/paths"; import { durableBunRuntime, type BunRuntimeSource, type DurableBunRuntime } from "../lib/bun-runtime"; import { WINSW_SHA256, WINSW_VERSION } from "../lib/winsw"; import { isTransientServiceLauncherPath } from "../lib/transient-service-path"; export { filterTransientServicePath, isTransientServiceLauncherPath } from "../lib/transient-service-path"; import { isProtectedHomeUnderTest, isTestHomeGuardArmed } from "../lib/test-home-guard"; import { isStandaloneBinary } from "../lib/standalone"; import { inspectInstallStateBytes, parseInstallStateRecord, parseOwnershipClaim, SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, SERVICE_OWNERSHIP_PROTOCOL_VERSION, selectAuthoritativeServiceState, serviceStateFingerprint, serviceStateFilesFor, } from "./install-state-contract.mjs"; import type { ServiceStateRecordEvidence } from "./state-record.mjs"; import { assertServiceStateLocksOwned, withServiceStateLocks, type ServiceStateLockHooks } from "./state-lock"; import { withOwnershipMutationLease, type OwnershipMutationLeaseOptions } from "./ownership-mutation-lease.mjs"; import { assessServiceTakeoverCompatibility, sameServiceTakeoverCompatibility, type ManagingCliObservation, type ServiceTakeoverCompatibility, } from "./ownership-compatibility"; /** * Written only by the launchd plist and the systemd unit. `OCX_SERVICE=1` cannot stand in * for it: `ocx claude` and `ocx opencode` set that on the proxies they spawn to borrow its * routing-preservation meaning, so a proxy carrying it is not necessarily the managed job. */ export const SERVICE_MANAGED_ENV = "OCX_SERVICE_MANAGED"; export const LABEL = "com.opencodex.proxy"; export const TASK = "opencodex-proxy"; export { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, SERVICE_OWNERSHIP_PROTOCOL_VERSION }; // This module lives one level below the original src/service.ts, so path-relative // lookups anchored at that file's directory go through this constant instead. export const serviceSourceDir = dirname(import.meta.dir); export type ServiceBackend = "scheduler" | "native"; export function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string | null } { // Bake the bundled Bun (manager-owned global package directory, survives `ocx update`) rather than // a transient system Bun, so launchd/systemd/schtasks keep resolving even if a // standalone Bun is later removed. The CLI entry lives at src/cli/index.ts. // // Path and provenance come from ONE resolution so the marker can never describe a // different binary than the one actually baked. return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: runtime.source === "standalone" || isStandaloneBinary() ? null : join(serviceSourceDir, "cli", "index.ts"), }; } export function serviceLauncherPathDiagnostic( state: ServiceInstallState | null = readServiceInstallState(), platform: NodeJS.Platform = process.platform, repairing = false, ): string | null { const launcher = state?.launcherPath; if (!launcher || !isTransientServiceLauncherPath(launcher, platform)) return null; return `STALE temporary launcher path (${launcher}) from a shell-local version manager — ` + (repairing ? "replacing it with a durable launcher or package-local Bun runtime" : "run 'ocx service repair' to replace it with a durable launcher or package-local Bun runtime"); } /** * The stable `ocx` launcher to bake into a systemd unit, or null to fall back to the * Bun + CLI pair. * * `cliEntry()` resolves both of its paths from `import.meta.dir`, so they point INSIDE * the installed package tree. Under a version manager that tree is a versioned directory: * `~/.local/share/mise/installs/npm-opencodex/2.35.0/...`. An upgrade installs 2.36.0 and * deletes 2.35.0, after which the unit's `exec <old-bun> <old-cli>` cannot resolve, and * `Restart=on-failure` turns that into a restart loop (#2898). The shim in * `~/.local/share/mise/shims/ocx` survives the upgrade and dispatches to whatever version * is current, so it is the durable thing to name. * * Deliberately LEXICAL. Resolving the symlink would write the versioned target back into * the unit and reintroduce the bug — the indirection is the entire point. * * Only an absolute path is accepted. A bare `ocx` would be re-resolved through `PATH` on * every restart, which turns a service definition into a PATH-hijacking surface; naming * one validated absolute file keeps the target fixed at install time. * * The RECORDED launcher wins over a fresh PATH walk. `ocx service repair` runs from * whatever shell the operator (or `ocx update`, or a tray helper) happened to have, and a * context without `ocx` on `PATH` used to resolve null here — rewriting a working * launcher-form plist into the version-pinned Bun + CLI pair and then booting the healthy * job out to load it (#4236, defect 1g). A launcher that is still an executable file is * the thing the installed service already runs, so repair must keep naming it; only a * recorded launcher that has disappeared falls through to discovery. * * That preference is NOT macOS-only: `installSystemd` resolves this same function, so a * Linux `ocx service repair` from a PATH-less context keeps the `ExecStart` the unit * already has instead of rewriting it to the version-pinned pair — the #2898 shape this * function exists to avoid. The failure mode it prevents is milder there (systemd * `daemon-reload` + `restart` does not evict-then-maybe-nothing the way launchd did), but * the rewrite was the same, so the behavior is deliberately shared rather than branched. */ export function stableLauncherEntry(deps: { env?: NodeJS.ProcessEnv; isExecutableFile?: (path: string) => boolean; pathDelimiter?: string; state?: ServiceInstallState | null; platform?: NodeJS.Platform; } = {}): string | null { const env = deps.env ?? process.env; const platform = deps.platform ?? process.platform; const pathTools = platform === "win32" ? win32 : posix; const isExecutableFile = deps.isExecutableFile ?? ((path: string): boolean => { try { if (!statSync(path).isFile()) return false; accessSync(path, fsConstants.X_OK); return true; } catch { return false; } }); const recorded = (deps.state === undefined ? readServiceInstallState() : deps.state)?.launcherPath; if (recorded && !isTransientServiceLauncherPath(recorded, platform) && pathTools.isAbsolute(recorded) && isExecutableFile(recorded)) return recorded; const entries = (env.PATH ?? "").split(deps.pathDelimiter ?? delimiter); for (const entry of entries) { if (!entry || isTransientServiceLauncherPath(entry, platform) || !pathTools.isAbsolute(entry)) continue; const candidate = pathTools.join(entry, "ocx"); if (isExecutableFile(candidate)) return candidate; } return null; } export function plistPath(): string { return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`); } export function logPath(): string { return join(getConfigDir(), "service.log"); } export function serviceLogPath(): string { return logPath(); } export function windowsServiceScriptPath(): string { return join(getConfigDir(), "opencodex-service.cmd"); } export function windowsLauncherVbsPath(): string { return join(getConfigDir(), "opencodex-service-launcher.vbs"); } export function windowsTaskXmlPath(): string { return join(getConfigDir(), "opencodex-service-task.xml"); } export function serviceStatePath(): string { return join(getConfigDir(), "service-state.json"); } function defaultOpenCodexHome(): string { return resolve(join(homedir(), ".opencodex")); } export function serviceStatePathsForOpenCodexHome(opencodexHome: string): string[] { return serviceStateFilesFor(opencodexHome, defaultOpenCodexHome()); } export function serviceStatePaths(): string[] { const paths = serviceStatePathsForOpenCodexHome(currentOpenCodexHome()); if (!isTestHomeGuardArmed()) return paths; /* * Under an armed test process the legacy default-home entry IS the developer's real * `~/.opencodex/service-state.json`. It is there so an install made before * OPENCODEX_HOME was set can still be found, but it means a test whose OPENCODEX_HOME * points at a sandbox still writes their live install state — observed while building * the launchd repair coverage: one case replaced the real record's codexHome and * opencodexHome with temp-directory paths. Drop it rather than deny the write, so the * sandbox path keeps working and the real one is simply not in the list. * * The predicate is the guard's own, not a local `resolve()` compare: the guard * canonicalizes through `realpath`, and on macOS a sandbox under `/var/folders/...` * resolves to `/private/var/folders/...`, so two spellings of one directory must not * decide this. */ return paths.filter(path => !isProtectedHomeUnderTest(dirname(path))); } /** * The state paths a WRITE may use. Same list, but an empty one is an error instead of a * silent no-op. * * With OPENCODEX_HOME unset under an armed test process, `currentOpenCodexHome()` falls * back to the real `~/.opencodex` (`os.homedir()` ignores `$HOME`), the filter above then * removes every candidate, and `writeServiceInstallState` wrote NOTHING while reporting * success — a test asserting on install state would read the previous run's record, or * none. Fail the way `assertNotRealHomeUnderTest` does, naming the fix. */ function serviceStateWritePaths(): string[] { const paths = serviceStatePaths(); if (paths.length > 0) return paths; throw new Error( "refusing to write service install state with no writable state path: every candidate " + "resolved to the real OpenCodex home and was filtered out. Point OPENCODEX_HOME at a " + "temp directory for this test (the preload does it for every invocation; something " + "deleted the variable without restoring it).", ); } export function currentCodexHome(deps: CodexHomeDeps = {}): string { // Service ownership must identify the same home as the runtime. In WSL an // unset CODEX_HOME can resolve to the single Windows Desktop home rather than // Linux ~/.codex; recording the fallback here creates a false foreign owner. return resolveCodexHomeDir(deps); } export function currentCodexSqliteHomeAbsolute(target: "native" | "windows" = "native"): string | undefined { const raw = process.env.CODEX_SQLITE_HOME?.trim(); if (!raw) return undefined; const expanded = expandUserPath(raw); // Service artifacts can be rendered by cross-platform tests and repair tooling, so an // already-absolute path for the TARGET platform is preserved rather than re-anchored // against the writing host. `resolve()` is host-relative in both directions: on a POSIX // host it turns `C:\data` into `<cwd>/C:\data`, and on a Windows host it turns `/tmp/x` // into `D:\tmp\x` — neither is a path the target can use. A relative value still resolves, // because a service unit has no meaningful working directory. // // CODEX_HOME and OPENCODEX_HOME are carried through literally, so without this the same // generated file disagreed with itself about two variables holding the same kind of value. if (target === "windows") { return win32.isAbsolute(expanded) ? win32.normalize(expanded) : resolve(expanded); } return posix.isAbsolute(expanded) ? posix.normalize(expanded) : resolve(expanded); } export function currentOpenCodexHome(): string { // getConfigDir() already resolves OPENCODEX_HOME with ~ expansion; keep the // install-state comparison on the same normalization or `~/...` values falsely // fail the environment-match check depending on cwd. return getConfigDir(); } export function normalizePathForCompare(path: string): string { const resolved = resolve(path); return process.platform === "win32" ? resolved.toLowerCase() : resolved; } export interface ServiceInstallState { version: 1 | 2; codexHome: string; opencodexHome: string; /** Effective Codex SQLite home used by this service's history integration. */ codexSqliteHome?: string; /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */ bunPath?: string; cliPath?: string | null; /** * launchd and systemd. The stable `ocx` launcher the service definition actually invokes, * when one was found. Present means `bunPath`/`cliPath` are provenance for the install, * NOT what the service runs — so staleness must be judged against THIS path instead. A version-manager * upgrade replaces the directory those two point into while the launcher survives, and * checking the old pair would report a stale service that is in fact healthy. */ launcherPath?: string; /** v2: which Windows backend was chosen at install; absent (v1/legacy) means scheduler. */ backend?: ServiceBackend; winswVersion?: string; winswSha256?: string; /** * Bumped by every write through {@link swapServiceInstallState}; the compare-and-swap * token. Absent means a record written before this field existed, which compares equal * to 0 so the first swap over it still lands. */ revision?: number; /** Who owns the running proxy. Absent means the CLI install that registered the service. */ ownership?: ServiceOwnership; /** * The highest consent generation this record has ever carried, kept across a release. * * Without it the counter is an ABA token: granting, releasing and granting again produces * generation 1 twice, and an app-local record holding the first 1 would read the second * one as its own prior consent. */ consentGenerationCeiling?: number; /** Written only by CLIs whose start/repair/update paths honor a desktop claim. */ ownershipProtocolVersion?: number; } /** * The two kinds of installation that can own the proxy. * * `cli` is the npm (or standalone) `ocx` install that registered the background service. * `desktop` is the packaged app, which brings its own bundled runtime. */ export type ServiceOwner = "cli" | "desktop"; /** * Durable ownership, recorded in the shared service install state. * * Ownership used to be a boolean the desktop shell recomputed at every launch from whether * it happened to spawn a child, so a restart silently demoted the app back to guest and * "ask once, then own permanently" could not be expressed at all. This record is the thing * that survives the restart. * * ABSENT IS NOT UNOWNED. Every installation that predates this field has no record, and the * npm service registration is what owns the runtime there, so absence has to keep meaning * exactly that. */ export interface ServiceOwnership { readonly owner: ServiceOwner; /** * Opaque identity of the owning INSTALLATION — not of the user, the machine or the * account. The desktop app keeps the same value in its own app-local store, and comparing * the two through {@link ownershipGrantedTo} is how a reinstalled app tells its own prior * consent from another installation's. */ readonly installId: string; /** * Increments once per ownership grant. Re-recording the same owner and install id leaves * it alone, so a relaunch cannot inflate it and "exactly one increment per takeover" is * an assertion a test can make. */ readonly consentGeneration: number; } /** * Validate an ownership claim read off disk. * * Returns the ORIGINAL object rather than a rebuilt one: a newer writer may carry fields * this version does not know about, and rebuilding would drop them on the next preserve — * which is the same lost-field failure this whole record exists to stop. */ export function parseServiceOwnership(value: unknown): ServiceOwnership | null { return parseOwnershipClaim(value) as ServiceOwnership | null; } /** * The record contract lives in `install-state-contract.mjs` so the Node launcher validates * exactly what this reader validates. It used to keep a weaker copy, and a record that fails * this contract while merely lacking an `ownership` field read there as "nobody owns the * runtime" — which is permission to stop a foreign runtime and reactivate the npm service. */ export function parseServiceInstallState(value: unknown): ServiceInstallState | null { return parseInstallStateRecord(value) as ServiceInstallState | null; } /** * What an install bakes into the record: the homes, the provenance paths and the backend. * * Everything here is rebuilt from the CURRENT process on every write, which is the point — * it describes the install that just ran. {@link ServiceInstallState.ownership} deliberately * is not part of it. */ function installProvenanceRecord(backend: ServiceBackend, launcherPath?: string | null): ServiceInstallState { const { bun, cli } = cliEntry(); const codexHome = currentCodexHome(); return { version: 2, codexHome, opencodexHome: currentOpenCodexHome(), codexSqliteHome: resolveCodexSqliteHome({ codexHome }), bunPath: bun, cliPath: cli, ownershipProtocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION, ...(launcherPath ? { launcherPath } : {}), backend, ...(backend === "native" ? { winswVersion: WINSW_VERSION, winswSha256: WINSW_SHA256 } : {}), }; } /** * Record an install, PRESERVING whatever owns the runtime. * * Every install, repair, update and stop path ends here, and each one used to hand this * function a freshly rebuilt record that simply replaced the file. That is why ownership * cannot be an ordinary field written by whoever ran last: a repair kicked off by a tray * helper, or by `ocx update`, would erase a takeover the user had consented to and hand the * runtime back to the npm launcher without saying anything. Preserving it here is what makes * the consent durable. */ export function writeServiceInstallState( backend: ServiceBackend = "scheduler", launcherPath?: string | null, deps: ServiceStateSwapDeps = {}, ): void { swapServiceInstallState(current => ({ ...installProvenanceRecord(backend, launcherPath), ...preservedConsent(current), }), deps); } /** The ownership half of a record: the claim itself plus the generation high-water mark. */ function preservedConsent( current: ServiceInstallState | null, ): Pick<ServiceInstallState, "ownership" | "consentGenerationCeiling"> { const ownership = current?.ownership; const ceiling = Math.max(current?.consentGenerationCeiling ?? 0, ownership?.consentGeneration ?? 0); return { ...(ownership ? { ownership } : {}), ...(ceiling > 0 ? { consentGenerationCeiling: ceiling } : {}), }; } export function readServiceInstallState(): ServiceInstallState | null { const resolved = resolveServiceState(); return resolved.kind === "state" ? resolved.state : null; } /** Raised when a non-cooperating writer prevents a stable authoritative commit. */ export class ServiceStateConflictError extends Error { constructor(readonly path: string, readonly attempts: number) { super( `service install state at ${path} was rewritten by another process during all ${attempts} ` + "compare-and-swap attempts; a stable commit could not be verified. Re-run the command.", ); this.name = "ServiceStateConflictError"; } } export interface ServiceStateSwapDeps { /** Test seam: which state paths to write. Defaults to every writable state path. */ paths?: readonly string[]; /** How many times to re-read and recompute before giving up. */ attempts?: number; /** * Test seam: runs immediately before each commit. It is the only place a competing writer * can be interleaved deterministically, which is what makes the revision check testable * rather than a claim in a comment. */ beforeCommit?: (attempt: number) => void; /** How long to wait for another process to release the anchor lock. */ lockWaitMs?: number; /** Deterministic lock seams for failure-order tests. */ lockHooks?: ServiceStateLockHooks; /** Atomic publisher seam. The callback must run immediately before its commit point. */ commitStateFile?: (path: string, serialized: string, validate: () => void) => void; /** A mirror failure occurs after the authority committed and is therefore diagnostic. */ onMirrorError?: (path: string, error: unknown) => void; /** Allows consented mutations to preserve a machine-readable unknown-subject error. */ unknownStateError?: (reason: string) => Error; /** Shared with update/install/start so replacement and ownership mutation cannot overlap. */ mutationLease?: OwnershipMutationLeaseOptions; } export interface ServiceStateMutationContext { readonly revision: number; } const SERVICE_STATE_SWAP_ATTEMPTS = 5; function authoritativeState( paths: readonly string[], unknownStateError?: (reason: string) => Error, ): { current: ServiceInstallState | null; revision: number; fingerprint: string } { const selected = selectAuthoritativeServiceState( inspectServiceStateEvidence(paths) as readonly ServiceStateRecordEvidence[], ); if (selected.kind === "unknown") { throw unknownStateError?.(selected.reason) ?? new Error(`${selected.reason}; nothing was written`); } if (selected.kind === "none") return { current: null, revision: 0, fingerprint: "none" }; const current = selected.state as ServiceInstallState; return { current, revision: selected.revision, fingerprint: serviceStateFingerprint(current) }; } function commitServiceStateFile(path: string, serialized: string, validate: () => void): void { atomicWriteFileStreamed(path, descriptor => { writeFileSync(descriptor, serialized, { encoding: "utf8" }); }, { validateBeforeRename: validate }); } /** * Read the recorded state, compute the next one from it, and commit it only if nothing else * moved the record in between. * * `mutate` may return null to mean "nothing to change", which writes nothing and leaves the * file — including its absence — exactly as it was. * * WHAT THE REVISION CHECK IS. The anchor is re-read immediately before the commit and the * committed bytes are read back immediately after, so a writer that landed on either side of * the window is DETECTED and the whole read-modify-write runs again against the new base. * The comparison is over the serialized record rather than the revision number alone, * because two writers racing from one base both compute the same next revision — identical * bytes mean nothing was lost, and differing bytes mean something was. * * The final path is the authority. With a custom home that is the legacy default-home path — * the only path every writer can derive — and the active-home path is a compatibility mirror. * The authority's atomic rename is the commit point. A mirror failure is reported but cannot * roll back or reclassify the already committed mutation; the next writer repairs the mirror. */ export function swapServiceInstallState( mutate: (current: ServiceInstallState | null, context: ServiceStateMutationContext) => ServiceInstallState | null, deps: ServiceStateSwapDeps = {}, ): ServiceInstallState | null { const paths = deps.paths ?? serviceStateWritePaths(); const authority = paths.at(-1); if (authority === undefined) throw new Error("refusing to swap service install state with no state path"); const mirrors = paths.filter(path => path !== authority); const attempts = deps.attempts ?? SERVICE_STATE_SWAP_ATTEMPTS; const publish = deps.commitStateFile ?? commitServiceStateFile; return withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => { for (let attempt = 0; attempt < attempts; attempt += 1) { const base = authoritativeState(paths, deps.unknownStateError); const candidate = mutate(base.current, { revision: base.revision }); if (candidate === null) return base.current; if (base.revision >= Number.MAX_SAFE_INTEGER) { throw new Error("service state revision is exhausted; refusing to publish an unversioned mutation"); } const next: ServiceInstallState = { ...candidate, revision: base.revision + 1 }; const serialized = JSON.stringify(next, null, 2) + "\n"; deps.beforeCommit?.(attempt); assertServiceStateLocksOwned(paths); const fresh = authoritativeState(paths, deps.unknownStateError); if (fresh.revision !== base.revision || fresh.fingerprint !== base.fingerprint) continue; const validate = () => assertServiceStateLocksOwned(paths); publish(authority, serialized, validate); const committed = authoritativeState([authority]); if (committed.revision !== next.revision || committed.fingerprint !== serviceStateFingerprint(next)) continue; for (const mirror of mirrors) { try { publish(mirror, serialized, validate); } catch (error) { (deps.onMirrorError ?? ((path, cause) => console.warn( `service state committed, but compatibility mirror ${path} could not be refreshed: ${cause instanceof Error ? cause.message : String(cause)}`, )))(mirror, error); } } return next; } throw new ServiceStateConflictError(authority, attempts); }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), deps.mutationLease); } export interface RemoveServiceStateDeps { readonly paths?: readonly string[]; readonly unlink?: (path: string) => void; readonly lockWaitMs?: number; readonly lockHooks?: ServiceStateLockHooks; } /** * Delete mirrors first and the authority last under the same ownership locks. * * A crash or mirror error before the final unlink leaves the authority in place, so a stale * mirror can never become a migration source and resurrect a released desktop claim. */ export function removeServiceInstallStateRecords(deps: RemoveServiceStateDeps = {}): void { const paths = deps.paths ?? serviceStateWritePaths(); const authority = paths.at(-1); if (!authority) return; const unlink = deps.unlink ?? unlinkSync; withOwnershipMutationLease(paths, () => withServiceStateLocks(paths, () => { for (const mirror of paths.slice(0, -1)) { assertServiceStateLocksOwned(paths); if (existsSync(mirror)) unlink(mirror); } assertServiceStateLocksOwned(paths); if (existsSync(authority)) unlink(authority); }, { waitMs: deps.lockWaitMs, hooks: deps.lockHooks }), { waitMs: deps.lockWaitMs }); } /** The recorded owner of ONE already-read record, or null. Prefer {@link resolveServiceOwnership}. */ export function serviceOwnership(state: ServiceInstallState | null = readServiceInstallState()): ServiceOwnership | null { return state?.ownership ?? null; } /** * What every state path, together, says about who owns the runtime. * * An unknown resolution is the answer that matters. \`readServiceInstallState\` collapses * unreadable, malformed and absent into one null, and a caller that reads that null as "the * CLI owns it" will re-enable the npm launcher over a claim it merely failed to read — the * exact demotion the record exists to prevent. Absence is the only thing that may mean no * claim. */ export type ServiceStateResolution = | { readonly kind: "none"; readonly revision: 0; readonly needsRepair: false } | { readonly kind: "state"; readonly state: ServiceInstallState; readonly revision: number; readonly needsRepair: boolean } | { readonly kind: "unknown"; readonly reason: string }; export type ServiceOwnershipSubject = | { readonly kind: "none"; readonly revision: number } | { readonly kind: "owned"; readonly ownership: ServiceOwnership; readonly revision: number }; export type ServiceOwnershipResolution = ServiceOwnershipSubject | { readonly kind: "unknown"; readonly reason: string }; export function resolveServiceState( evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(), ): ServiceStateResolution { const selected = selectAuthoritativeServiceState(evidence as readonly ServiceStateRecordEvidence[]); if (selected.kind === "unknown") return selected; if (selected.kind === "none") return selected; return { kind: "state", state: selected.state as ServiceInstallState, revision: selected.revision, needsRepair: selected.needsRepair, }; } export function resolveServiceOwnership( evidence: readonly ServiceStateEvidence[] = inspectServiceStateEvidence(), ): ServiceOwnershipResolution { const state = resolveServiceState(evidence); if (state.kind === "unknown") return state; if (state.kind === "none" || !state.state.ownership) return { kind: "none", revision: state.revision }; return { kind: "owned", ownership: state.state.ownership, revision: state.revision }; } export function sameServiceOwnershipSubject( left: ServiceOwnershipSubject, right: ServiceOwnershipSubject, ): boolean { if (left.kind !== right.kind || left.revision !== right.revision) return false; if (left.kind === "none" || right.kind === "none") return true; return left.ownership.owner === right.ownership.owner && left.ownership.installId === right.ownership.installId && left.ownership.consentGeneration === right.ownership.consentGeneration; } function sameServiceOwnershipIdentity(left: ServiceOwnershipSubject, right: ServiceOwnershipSubject): boolean { if (left.kind !== right.kind) return false; if (left.kind === "none" || right.kind === "none") return true; return left.ownership.owner === right.ownership.owner && left.ownership.installId === right.ownership.installId && left.ownership.consentGeneration === right.ownership.consentGeneration; } function serviceOwnershipSubject( state: ServiceInstallState | null, revision: number, ): ServiceOwnershipSubject { return state?.ownership ? { kind: "owned", ownership: state.ownership, revision } : { kind: "none", revision }; } export class ServiceOwnershipSubjectMismatchError extends Error { readonly code = "service-ownership-subject-mismatch" as const; constructor(readonly expected: ServiceOwnershipSubject, readonly actual: ServiceOwnershipSubject) { super("service ownership changed after consent; resolve again and ask for fresh approval"); this.name = "ServiceOwnershipSubjectMismatchError"; } } export class ServiceOwnershipSubjectUnknownError extends Error { readonly code = "service-ownership-subject-unknown" as const; constructor(readonly expected: ServiceOwnershipSubject, readonly reason: string) { super(`service ownership could not be revalidated after consent (${reason}); nothing was written`); this.name = "ServiceOwnershipSubjectUnknownError"; } } export class ServiceTakeoverCompatibilityChangedError extends Error { readonly code = "service-takeover-compatibility-changed" as const; constructor(readonly actual: ServiceTakeoverCompatibility) { super("the managing CLI compatibility changed after consent; resolve again and ask for fresh approval"); this.name = "ServiceTakeoverCompatibilityChangedError"; } } /** * Whether the packaged desktop app owns the runtime. * * This is the predicate `ocx service repair` and `ocx update` consult before they would * re-enable, rewrite or restart the npm service registration. The registration itself is * kept either way — the maintainer's decision is that the user's install is never deleted, * so this marker is the only thing that makes the takeover durable. */ export function desktopOwnsService(state: ServiceInstallState | null = readServiceInstallState()): boolean { return serviceOwnership(state)?.owner === "desktop"; } /** * THE COMPARISON RULE. An installation holds the recorded grant only when both the kind of * owner and the install id match its own. * * The desktop app calls this at launch with the install id from its app-local store. True * means this very installation already has consent and must not ask again. False with a * non-null `ownership` means a DIFFERENT installation owns the runtime — a reinstalled app, * or a second copy — and consent has to be asked before taking over. Null means nothing is * recorded and the npm install still owns it. */ export function ownershipGrantedTo( ownership: ServiceOwnership | null, owner: ServiceOwner, installId: string, ): boolean { return ownership !== null && ownership.owner === owner && ownership.installId === installId; } /** * The record an ownership write lands on when no install state exists yet. * * Deliberately carries no `bunPath`, `cliPath` or `launcherPath`: those are baked BY AN * INSTALL, and a takeover is not one. Recording the claiming process's own paths as install * provenance would make `ocx service status` describe a registration nobody created. */ function ownershipBaseRecord(current: ServiceInstallState | null): ServiceInstallState { if (current) return current; const codexHome = currentCodexHome(); return { version: 2, codexHome, opencodexHome: currentOpenCodexHome(), codexSqliteHome: resolveCodexSqliteHome({ codexHome }), backend: "scheduler", }; } /** * Record `claim` as the runtime's owner and return what was written. * * Idempotent by design: re-recording the same owner and install id leaves the consent * generation alone, so every relaunch of an app that already has consent is a no-op on the * number. A different owner or a different install id is a new grant and increments it once. */ export interface RecordServiceOwnerRequest { readonly owner: ServiceOwner; readonly installId: string; readonly expectedSubject: ServiceOwnershipSubject; readonly expectedCompatibility: Extract<ServiceTakeoverCompatibility, { kind: "supported" }>; } export interface RecordServiceOwnerDeps extends ServiceStateSwapDeps { /** Re-observes BOTH the registered manager and the current PATH manager inside the lock. */ readonly observeManagers: () => Readonly<Record<"service-registration" | "path", ManagingCliObservation>>; } export function recordServiceOwner( request: RecordServiceOwnerRequest, deps: RecordServiceOwnerDeps, ): Extract<ServiceOwnershipSubject, { kind: "owned" }> { if (!request.installId) throw new Error("refusing to record service ownership without an install id"); if (!request.expectedSubject || request.expectedCompatibility?.kind !== "supported") { throw new Error("refusing to record service ownership without the exact approved subject and compatibility token"); } if (!deps || typeof deps.observeManagers !== "function") { throw new Error("refusing to record service ownership without a managing-CLI revalidation callback"); } const { observeManagers, ...swapDeps } = deps; let recorded: ServiceOwnership | null = null; const committed = swapServiceInstallState((current, context) => { const actualSubject = serviceOwnershipSubject(current, context.revision); if (!sameServiceOwnershipSubject(request.expectedSubject, actualSubject)) { throw new ServiceOwnershipSubjectMismatchError(request.expectedSubject, actualSubject); } let managers: Readonly<Record<"service-registration" | "path", ManagingCliObservation>>; try { managers = observeManagers(); } catch (error) { throw new ServiceTakeoverCompatibilityChangedError({ kind: "blocked", reason: "managing-cli-unknown", detail: error instanceof Error ? error.message : String(error), minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, }); } const compatibility = assessServiceTakeoverCompatibility({ state: current, subject: actualSubject, managers, }); if (!sameServiceTakeoverCompatibility(request.expectedCompatibility, compatibility)) { throw new ServiceTakeoverCompatibilityChangedError(compatibility); } const previous = current?.ownership ?? null; // The ceiling, not just the live claim: a grant that was released left its number // behind on purpose, so a later grant cannot reuse it. const floor = Math.max(previous?.consentGeneration ?? 0, current?.consentGenerationCeiling ?? 0); if (floor >= Number.MAX_SAFE_INTEGER) { throw new Error("service ownership consent generation is exhausted; nothing was written"); } recorded = { owner: request.owner, installId: request.installId, consentGeneration: previous && ownershipGrantedTo(previous, request.owner, request.installId) ? previous.consentGeneration : floor + 1, }; return { ...ownershipBaseRecord(current), ownership: recorded, consentGenerationCeiling: Math.max(floor, recorded.consentGeneration), }; }, { ...swapDeps, unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(request.expectedSubject, reason), }); if (recorded === null || !committed?.ownership || committed.revision === undefined) { throw new Error("service ownership was not recorded"); } return { kind: "owned", ownership: committed.ownership, revision: committed.revision }; } /** * Drop a recorded owner and return what was dropped, or null when nothing was recorded. * * Writes nothing when there is no claim to release, so asking about an unowned runtime never * creates an install record describing a service nobody registered. */ export interface ReleaseServiceOwnerDeps extends ServiceStateSwapDeps { /** Service install refreshes provenance first; that known write may advance only revision. */ readonly allowRevisionAdvance?: boolean; } export function releaseServiceOwner( expectedSubject: ServiceOwnershipSubject, deps: ReleaseServiceOwnerDeps = {}, ): ServiceOwnership | null { const { allowRevisionAdvance = false, ...swapDeps } = deps; let released: ServiceOwnership | null = null; swapServiceInstallState((current, context) => { const actualSubject = serviceOwnershipSubject(current, context.revision); const matches = allowRevisionAdvance ? sameServiceOwnershipIdentity(expectedSubject, actualSubject) && actualSubject.revision >= expectedSubject.revision : sameServiceOwnershipSubject(expectedSubject, actualSubject); if (!matches) throw new ServiceOwnershipSubjectMismatchError(expectedSubject, actualSubject); released = current?.ownership ?? null; if (!current?.ownership) return null; const { ownership: _released, ...withoutOwnership } = current; // Keep the number. Dropping it makes the generation an ABA token: grant, release, grant // again would produce 1 twice, and an app-local record still holding the first 1 would // read the second grant as its own prior consent. return { ...withoutOwnership, consentGenerationCeiling: Math.max( current.consentGenerationCeiling ?? 0, current.ownership.consentGeneration, ), }; }, { ...swapDeps, unknownStateError: reason => new ServiceOwnershipSubjectUnknownError(expectedSubject, reason), }); return released; } /** What ONE state path said. Absent, unreadable and invalid are different answers. */ export type ServiceStateEvidence = | { readonly path: string; readonly kind: "absent" } | { readonly path: string; readonly kind: "unreadable"; readonly reason: string } | { readonly path: string; readonly kind: "invalid" } | { readonly path: string; readonly kind: "valid"; readonly state: ServiceInstallState }; /** * Every state path, with what each one said. * * The final path is authoritative; earlier paths are compatibility mirrors and the * migration source only while the authority is absent. Keeping the raw evidence separate * lets the selector distinguish migration, degraded mirrors and unordered conflicts. */ export function inspectServiceStateEvidence( paths: readonly string[] = serviceStatePaths(), ): readonly ServiceStateEvidence[] { return paths.map(path => ( inspectInstallStateBytes(path, at => readFileSync(at, "utf8")) as ServiceStateEvidence )); } /** The homes this process is actually using, for comparison against a claim. */ export function currentServiceHomes(deps: CodexHomeDeps = {}): { codexHome: string; opencodexHome: string } { return { codexHome: currentCodexHome(deps), opencodexHome: currentOpenCodexHome() }; } export function serviceHomeMatches(a: string, b: string): boolean { return normalizePathForCompare(a) === normalizePathForCompare(b); } export type ServicePathComparison = "same" | "different" | "unknown"; /** * Tri-state physical-home compare. A realpath failure (EACCES, EPERM, a * vanished directory, transient I/O) is "unknown", not "different": callers * deciding whether a home is foreign must not turn an unreadable resolution * into a definitive mismatch. Lifecycle guards may still fail closed on * "unknown". */ export function compareServicePathToInstall(recorded: string, current: string, deps: CodexHomeDeps = {}): ServicePathComparison { if (serviceHomeMatches(recorded, current)) return "same"; const realpath = deps.realpathSync ?? realpathSync; let currentPhysical: string; try { currentPhysical = realpath(current); } catch { return "unknown"; } try { return serviceHomeMatches(realpath(recorded), currentPhysical) ? "same" : "different"; } catch (error) { // The spellings already differ. A recorded path that no longer exists cannot be an alias of // the current home, so it stays a mismatch (a stale mount keeps the foreign-owner refusal); // only an error that leaves existence unproven, such as EACCES, is indeterminate. const code = (error as NodeJS.ErrnoException | null)?.code; return code === "ENOENT" || code === "ENOTDIR" ? "different" : "unknown"; } } /** Lexical compare first; when spellings differ, compare the directories both resolve to so a * junction or symlink spelling recorded by an older install still names the same home. * Fails closed on an indeterminate resolution — ownership classification needs the * tri-state {@link compareServicePathToInstall} instead. */ export function servicePathMatchesInstall(recorded: string, current: string, deps: CodexHomeDeps = {}): boolean { return compareServicePathToInstall(recorded, current, deps) === "same"; } export function serviceCodexHomeMatchesInstall(recordedHome: string, deps: CodexHomeDeps = {}): boolean { return servicePathMatchesInstall(recordedHome, currentCodexHome(deps), deps); } /** Single accessor for backend-sensitive service code — v1/legacy state maps to scheduler. */ export function readServiceBackend(): ServiceBackend { return readServiceInstallState()?.backend === "native" ? "native" : "scheduler"; } /** * The `ocx` argv that refreshes an already-installed service after an update. * * `repair` discovers the installed backend itself. A healthy Windows scheduler task only * gets refreshed assets plus a restart; a stale live definition is re-registered and may * require elevation. `install` always reaches `/create`, so using repair here avoids an * unnecessary admin prompt for the common healthy update path. * * The historical export name is kept for callers outside this module. */ export function serviceReinstallArgs(): string[] { return ["service", "repair"]; } /** The `ocx` argv that registers a service from scratch, preserving the chosen backend. */ export function serviceInstallArgs(): string[] { return readServiceBackend() === "native" ? ["service", "install", "--native"] : ["service", "install"]; }