UNPKG

@bitkyc08/opencodex

Version:

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

1,001 lines (947 loc) • 46.7 kB
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs"; import { randomUUID } from "node:crypto"; import { Database } from "bun:sqlite"; import { isAbsolute, join, relative, resolve, sep } from "node:path"; import type { GenerationContext } from "./state-store-sweeper"; import { renameAtomicFile } from "./windows-atomic-replace"; import { canonicalRootUnchanged, elevatedRemovalRefusal, ownedEntryPresent, removeOwnedEntry, rootIdentity, uninstallRunsElevated, type RootIdentity, } from "./config-ownership-removal"; export const CONFIG_OWNER_FILE = ".opencodex-owner.json"; export const CONFIG_UNINSTALL_MANIFEST = ".opencodex-uninstall.json"; /** * Cross-process lock for every manifest read-modify-write (#8093). It is the OS-held SQLite write * lock that `src/config/mutation-lock.ts` uses: `BEGIN IMMEDIATE` on this file, released when the * handle closes, including at process exit or crash, so there is no stale owner to recover. */ export const CONFIG_OWNERSHIP_LOCK = ".opencodex-uninstall.lock"; const OWNERSHIP_LOCK_SIDECARS = ["-journal", "-wal", "-shm"] as const; /** The section under the lock is a few file operations; a longer wait means a stuck holder. */ const OWNERSHIP_LOCK_WAIT_MS = 50; /** A registration found the uninstall tombstone and wrote nothing. */ export class ConfigUninstallInProgressError extends Error { readonly code = "CONFIG_UNINSTALL_IN_PROGRESS"; constructor() { // No path: this message can reach logs, and the config root can name the user. super("opencodex uninstall is in progress for this config directory; run `ocx uninstall` again to finish it before writing new state there."); this.name = "ConfigUninstallInProgressError"; } } export class ConfigOwnershipLockError extends Error { readonly code = "CONFIG_OWNERSHIP_LOCK_UNAVAILABLE"; constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "ConfigOwnershipLockError"; } } export type ConfigRemovalResult = { status: "absent" | "removed" | "partial" | "refused"; reason?: string; residualPaths: string[]; }; type ConfigOwner = { version: 1; ownerId: string; root: string; }; type ConfigUninstallManifest = ConfigOwner & { paths: string[]; /** Tombstone: set under the lock before uninstall snapshots `paths`; registrations then refuse. */ uninstallStartedAt?: number; }; const METADATA_MAX_BYTES = 64 * 1024; const MANIFEST_MAX_PATHS = 1024; const INITIAL_OWNED_PATHS = [ ".star-prompted", "artifacts", "auth.json", "auth.store.lock", "admin-api-token", "catalog-backup.json", "claude-env.sh", "codex-accounts.json", "codex-runtime-clamp.json", "codex-runtime.json", "codex-shim.autorestore.lock", "codex-shim.json", "config.json", "config-mutation.sqlite", "config-mutation.sqlite-journal", "config-mutation.sqlite-shm", "config-mutation.sqlite-wal", "codex-affinity.sqlite", "codex-affinity.sqlite-journal", "codex-affinity.sqlite-shm", "codex-affinity.sqlite-wal", "local-credentials.json", "local-credential-observers", "local-credential-publication.sqlite", "local-credential-publication.sqlite-journal", "crash.log", "kimi-device-id", "mimo-client-id", "ocx.pid", "opencodex-service-launcher.vbs", "opencodex-service-task.xml", "opencodex-service.cmd", "opencodex-tray-offline.ico", "opencodex-tray-offline-update.ico", "opencodex-tray-online.ico", "opencodex-tray-online-update.ico", "opencodex-tray-warning.ico", "opencodex-tray-warning-update.ico", "opencodex-tray.ps1", "responses-state.json", "runtime-port.json", "service-api-token", "service-state.json", "service.log", "system-env-port", "thought-signature-replay.json", "tray-heartbeat.json", "tray-state.json", "update-job.json", "usage-debug.jsonl", "usage.jsonl", "version.json", "winsw", ] as const; /** * Room an uninstall rerun may use past the usual caps, under its tombstone, to record the opencodex * files its own cleanup recreates (the config mutation database, for one). Only initially owned * names qualify, each at most once, so a full manifest from an older version cannot strand them and * the manifest stays bounded. */ const RECOVERY_RESERVE_PATHS = INITIAL_OWNED_PATHS.length; const RECOVERY_RESERVE_BYTES = INITIAL_OWNED_PATHS.reduce((total, name) => total + Buffer.byteLength(name) + 8, 0); const ownershipCache = new Map<string, { owner: ConfigOwner; manifest: ConfigUninstallManifest; } | null>(); let lastReconciledGeneration = 0; /** * Manifest identity (dev:ino:size:mtime) this process last observed under the ownership lock. * A cached path returns without locking only while the manifest is still that file, so a * tombstone written by another process sends even an already-recorded path to the locked check. */ const lockedManifestIdentity = new Map<string, string>(); const warnedFullManifest = new Set<string>(); /** * The metadata state in which a creation wait already ran out for a home, keyed as * {@link ownershipCache}. An unowned home whose manifest and owner marker keep the same identity * has no publication left to wait for (a stopped creation, or a corrupt marker), so a registration * must not pay the bounded wait again; either file changing re-arms a single wait. */ const expiredCreationWait = new Map<string, string>(); /** * Open while this process runs `ocx uninstall` itself. Its own registrations then skip the * tombstone check: the same process runs removeOwnedConfigState afterwards, whose locked snapshot * includes whatever they add, so nothing it records is orphaned. Without this, a rerun after an * interrupted uninstall would refuse its own teardown steps (the config mutation lock records * its database) before it reached the remover that finishes the job. Other processes still refuse. */ let teardownDepth = 0; type UninstallStep = "snapshot-removed" | "owner-deleted" | "lock-retired"; let uninstallStepHookForTests: ((step: UninstallStep) => void) | undefined; /** * Test seam, called inside uninstall's single lock hold: after it removed its snapshot, and after it * deleted the owner marker. A hook that throws stops the run there, as a crash would. */ export function setUninstallStepHookForTests(hook: ((step: UninstallStep) => void) | undefined): void { uninstallStepHookForTests = hook; } /** Mark this process as the uninstaller until the returned release runs. */ export function beginConfigOwnershipTeardown(): () => void { teardownDepth += 1; let released = false; return () => { if (released) return; released = true; teardownDepth -= 1; // Nothing this scope observed may let a later call skip the tombstone check. lockedManifestIdentity.clear(); }; } function manifestIdentity(configDir: string): string | undefined { try { const entry = lstatSync(join(configDir, CONFIG_UNINSTALL_MANIFEST), { bigint: true }); return entry.isFile() ? `${entry.dev}:${entry.ino}:${entry.size}:${entry.mtimeNs}` : undefined; } catch { return undefined; } } /** * Which file each ownership metadata name refers to while a manifest exists, in the same * dev:ino:size:mtime terms {@link manifestIdentity} uses, or null when no manifest exists: without * one the publication wait ends in a single pass, so there is no spent wait to remember. The * manifest is replaced atomically and the owner marker written once, so either file changing * produces a new identity and re-arms a single wait. */ function creationWaitIdentity(configDir: string): string | null { const describe = (name: string): string | null => { try { const entry = lstatSync(join(configDir, name), { bigint: true }); return `${entry.dev}:${entry.ino}:${entry.size}:${entry.mtimeNs}`; } catch (error) { const code = (error as NodeJS.ErrnoException).code; return code === "ENOENT" ? null : `unreadable:${code ?? "unknown"}`; } }; const manifest = describe(CONFIG_UNINSTALL_MANIFEST); return manifest === null ? null : `${manifest}|${describe(CONFIG_OWNER_FILE)}`; } export function listLiveConfigOwnershipRoots(currentConfigDir: string): ReadonlySet<string> { const currentRoot = ownershipCacheKey(currentConfigDir); const roots = new Set<string>([currentRoot]); for (const [root, ownership] of ownershipCache) { if (root === currentRoot) continue; if (ownership?.manifest.paths.some(rel => existsSync(join(root, ...rel.split("/"))))) { roots.add(root); } } return roots; } export function reconcileConfigOwnershipRoots(context: GenerationContext): number { if (context.generation <= lastReconciledGeneration) return 0; let removed = 0; for (const [root, ownership] of ownershipCache) { if (context.configRoots.has(root)) continue; const hasLiveOwnedPath = ownership?.manifest.paths.some(rel => existsSync(join(root, ...rel.split("/")))); if (hasLiveOwnedPath) continue; ownershipCache.delete(root); expiredCreationWait.delete(root); removed += 1; } lastReconciledGeneration = context.generation; return removed; } function ownershipCacheKey(configDir: string): string { const key = resolve(configDir); return process.platform === "win32" ? key.toLowerCase() : key; } function samePath(left: string, right: string): boolean { return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right; } function readBoundedJson(path: string, maxBytes = METADATA_MAX_BYTES): unknown { return readBoundedJsonSized(path, maxBytes).value; } function readBoundedJsonSized(path: string, maxBytes: number): { value: unknown; size: number } { const metadata = lstatSync(path); if (!metadata.isFile() || metadata.isSymbolicLink()) { throw new Error("ownership metadata is not a regular file"); } // Size first, so an oversized file is refused before it is read; the read is rechecked for a // file that grew in between. if (metadata.size > maxBytes) throw new Error("ownership metadata is too large"); const bytes = readFileSync(path); if (bytes.length > maxBytes) throw new Error("ownership metadata is too large"); return { value: JSON.parse(bytes.toString("utf8")) as unknown, size: bytes.length }; } function isOwner(value: unknown): value is ConfigOwner { if (!value || typeof value !== "object" || Array.isArray(value)) return false; const owner = value as Record<string, unknown>; return owner.version === 1 && typeof owner.ownerId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(owner.ownerId) && typeof owner.root === "string"; } function isManifest(value: unknown): value is ConfigUninstallManifest { if (!isOwner(value)) return false; const { paths, uninstallStartedAt } = value as Record<string, unknown>; return Array.isArray(paths) && paths.length <= MANIFEST_MAX_PATHS + (uninstallStartedAt === undefined ? 0 : RECOVERY_RESERVE_PATHS) && paths.every(path => typeof path === "string") && (uninstallStartedAt === undefined || Number.isSafeInteger(uninstallStartedAt)); } function canonicalRoot(configDir: string): string { return realpathSync.native(resolve(configDir)); } function manifestRelativePath(configDir: string, candidatePath: string): string | null { const root = resolve(configDir); const candidate = resolve(candidatePath); const rel = relative(root, candidate); if ( !rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) ) return null; const normalized = rel.split(sep).join("/"); if (normalized.split("/").some(part => !part || part === "." || part === ".." || part.includes("\\"))) { return null; } if (normalized === CONFIG_OWNER_FILE || normalized === CONFIG_UNINSTALL_MANIFEST) return null; if (normalized === CONFIG_OWNERSHIP_LOCK || OWNERSHIP_LOCK_SIDECARS.some(suffix => normalized === `${CONFIG_OWNERSHIP_LOCK}${suffix}`)) { return null; } return normalized; } function loadOwnership(configDir: string): { owner: ConfigOwner; manifest: ConfigUninstallManifest } | null { const ownerPath = join(configDir, CONFIG_OWNER_FILE); const manifestPath = join(configDir, CONFIG_UNINSTALL_MANIFEST); if (!existsSync(ownerPath) || !existsSync(manifestPath)) return null; try { const owner = readBoundedJson(ownerPath); // A tombstoned manifest may use the reserve: a home written by an older version can hold a // manifest up to the limit, and uninstall must still resume after adding its tombstone. const read = readBoundedJsonSized(manifestPath, TOMBSTONED_MANIFEST_MAX_BYTES); const manifest = read.value; if (isManifest(manifest) && manifest.uninstallStartedAt === undefined && read.size > METADATA_MAX_BYTES) return null; const root = canonicalRoot(configDir); if ( !isOwner(owner) || !isManifest(manifest) || owner.ownerId !== manifest.ownerId || !samePath(owner.root, root) || !samePath(manifest.root, root) ) return null; return { owner, manifest }; } catch { return null; } } function createOwnership(configDir: string): { owner: ConfigOwner; manifest: ConfigUninstallManifest } | null { const rootStat = lstatSync(configDir); if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || readdirSync(configDir).length !== 0) return null; const owner: ConfigOwner = { version: 1, ownerId: randomUUID(), root: canonicalRoot(configDir), }; const manifest: ConfigUninstallManifest = { ...owner, paths: [...INITIAL_OWNED_PATHS] }; // Manifest first, owner marker second; uninstall deletes them in the reverse order (owner marker, // then manifest). Both leave a manifest without an owner marker in between, told apart by the // tombstone: creation's manifest never carries one, so a home still being created is never // mistaken for a stopped uninstall. writeFileSync(join(configDir, CONFIG_UNINSTALL_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600, }); try { writeFileSync(join(configDir, CONFIG_OWNER_FILE), `${JSON.stringify(owner, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600, }); } catch (error) { try { unlinkSync(join(configDir, CONFIG_UNINSTALL_MANIFEST)); } catch { /* incomplete metadata fails closed */ } throw error; } return { owner, manifest }; } /** Temporary names `writeManifest` uses; one left behind means a write stopped before its rename. */ const MANIFEST_TEMP_PATTERN = new RegExp(`^${CONFIG_UNINSTALL_MANIFEST.replace(/\./g, "\\.")}\\.\\d+\\.[0-9a-f-]{36}\\.tmp$`); /** * Under the lock no manifest write is in progress, so such a temporary file is abandoned. It is * removed only when its content shows `writeManifest` wrote it for this home: a manifest carrying * this home's random owner id and root. Any other file with a matching name, a truncated write * included, is kept, and uninstall reports it as a residual path. */ function removeAbandonedMetadataTemps(configDir: string, owner: ConfigOwner): void { for (const name of readdirSync(configDir)) { if (!MANIFEST_TEMP_PATTERN.test(name)) continue; const path = join(configDir, name); let content: unknown; try { content = readBoundedJson(path, TOMBSTONED_MANIFEST_MAX_BYTES); } catch { continue; } if (!isManifest(content) || content.ownerId !== owner.ownerId || !samePath(content.root, owner.root)) continue; unlinkSync(path); } } /** Room the `uninstallStartedAt` tombstone needs on top of a registration's manifest. */ const TOMBSTONE_RESERVE_BYTES = 64; /** Largest manifest uninstall accepts once tombstoned: the tombstone and the recovery reserve on top. */ const TOMBSTONED_MANIFEST_MAX_BYTES = METADATA_MAX_BYTES + TOMBSTONE_RESERVE_BYTES + RECOVERY_RESERVE_BYTES; function serializeManifest(manifest: ConfigUninstallManifest): string { return `${JSON.stringify(manifest, null, 2)}\n`; } function writeManifest(configDir: string, manifest: ConfigUninstallManifest): void { const path = join(configDir, CONFIG_UNINSTALL_MANIFEST); const temp = `${path}.${process.pid}.${randomUUID()}.tmp`; writeFileSync(temp, serializeManifest(manifest), { encoding: "utf8", mode: 0o600 }); try { // Same Windows sharing-violation tolerance the config writer has: a // scanner holding the manifest must not turn uninstall bookkeeping into a // hard failure. renameAtomicFile(temp, path, undefined, "config-ownership"); } catch (error) { try { unlinkSync(temp); } catch { /* best effort */ } throw error; } } function fileIdentity(path: string): string { const entry = lstatSync(path, { bigint: true }); if (!entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1n) { throw new ConfigOwnershipLockError("config ownership lock is not a single-link regular file"); } return `${entry.dev}:${entry.ino}`; } /** * Run `run` while holding the ownership lock. Callers create ownership metadata first: the lock * file is never created in a root that has none, so a refused uninstall of a legacy home leaves it * untouched. Returns `undefined` without running `run` when the root disappeared, which only * happens once an uninstall has finished. */ function withOwnershipLock<T>(configDir: string, run: () => T): { value: T } | undefined { const path = join(configDir, CONFIG_OWNERSHIP_LOCK); const ownerPath = join(configDir, CONFIG_OWNER_FILE); const manifestPath = join(configDir, CONFIG_UNINSTALL_MANIFEST); for (let attempt = 0; attempt < 3; attempt += 1) { // Never lock (and so never create the lock file in) a root without ownership metadata. A // tombstoned manifest alone is an uninstall that stopped after deleting the owner marker. if (!existsSync(ownerPath) && !existsSync(manifestPath)) return undefined; try { writeFileSync(path, "", { flag: "wx", mode: 0o600 }); } catch (error) { const code = (error as NodeJS.ErrnoException).code; if (code === "ENOENT") return undefined; if (code !== "EEXIST") throw error; } let before: string; try { before = fileIdentity(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; } let database: Database | undefined; try { database = new Database(path, { create: false, readwrite: true }); acquireImmediate(database); } catch (cause) { try { database?.close(); } catch { /* acquisition already failed */ } // A waiter whose lock file was unlinked by a finishing uninstall fails on the stale handle // (macOS reports SQLITE_IOERR_VNODE); it retries against whatever the path names now. if (lockFileChanged(path, before)) continue; const code = cause && typeof cause === "object" && "code" in cause ? String((cause as { code?: unknown }).code) : ""; throw new ConfigOwnershipLockError( code === "SQLITE_BUSY" ? "config ownership metadata is busy in another opencodex process" : "could not lock config ownership metadata", { cause }, ); } try { // Uninstall unlinks the lock file last; a waiter that locked the unlinked file retries. if (lockFileChanged(path, before)) continue; return { value: run() }; } finally { // A holder that finds the metadata gone (a finished uninstall) retires the lock it held, and // only that file: a new installation may already have created its own lock at the same path. // It unlinks the file while still holding it, so a process that takes the old file afterwards // sees the path change and retries instead of working beside a new installation's lock. // Windows refuses to delete a file any handle has open, this one included, so there the // unlink is retried after release and succeeds only when no other process has the file open. const finished = !existsSync(ownerPath) && !existsSync(manifestPath); const retired = !finished || unlinkLockFile(path, before); if (finished && retired) uninstallStepHookForTests?.("lock-retired"); try { database.exec("ROLLBACK"); } catch { /* close below still releases the OS lock */ } try { database.close(); } catch { /* the OS lock is released with the handle */ } if (!retired) unlinkLockFile(path, before); if (finished) removeEmptyLockSidecars(configDir); } } throw new ConfigOwnershipLockError("config ownership lock kept changing while it was acquired"); } function lockFileChanged(path: string, before: string): boolean { try { return fileIdentity(path) !== before; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return true; throw error; } } /** * `BEGIN IMMEDIATE` with SQLite's own busy wait off, retried only briefly. A registration's section * under the lock is a few file operations, so a cooperating holder usually releases within * milliseconds. The retry is synchronous: while another process holds the lock (a paused holder, or * an uninstall removing files) it blocks the calling thread for at most * {@link OWNERSHIP_LOCK_WAIT_MS}, then throws, and the caller reports the registration or uninstall * as busy. */ function acquireImmediate(database: Database): void { database.exec("PRAGMA busy_timeout = 0"); const deadline = Date.now() + OWNERSHIP_LOCK_WAIT_MS; for (;;) { try { database.exec("BEGIN IMMEDIATE"); return; } catch (error) { const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : ""; if (code !== "SQLITE_BUSY" || Date.now() >= deadline) throw error; Bun.sleepSync(2); } } } /** * Unlink the lock file `before` identifies; a file another installation put at the path is left * alone. True once the path no longer names that file. */ function unlinkLockFile(path: string, before: string): boolean { try { if (lockFileChanged(path, before)) return true; unlinkSync(path); return true; } catch { return false; // uninstall reports what remains } } /** * Remove the lock's SQLite sidecars once released. SQLite deletes the journal its own transaction * created when that transaction ends, and the lock never writes data, so a sidecar this module left * is empty. A sidecar name holding data, or a link, is not provably ours: it stays and uninstall * reports it. */ function removeEmptyLockSidecars(configDir: string): void { for (const suffix of OWNERSHIP_LOCK_SIDECARS) { const path = join(configDir, `${CONFIG_OWNERSHIP_LOCK}${suffix}`); try { const entry = lstatSync(path); if (entry.isFile() && !entry.isSymbolicLink() && entry.nlink === 1 && entry.size === 0) unlinkSync(path); } catch { /* absent, or uninstall reports it */ } } } /** Initialize only an empty or already-owned root; do not claim a candidate path. */ export function initializeConfigOwnership(configDir: string): boolean { const cacheKey = ownershipCacheKey(configDir); if (!existsSync(configDir)) { ownershipCache.delete(cacheKey); expiredCreationWait.delete(cacheKey); mkdirSync(configDir, { recursive: true, mode: 0o700 }); } let ownership = ownershipCache.get(cacheKey); if (ownership === undefined || ownership === null) { // A previously unowned home can enter creation later; use the same bounded publication wait, // but spend it at most once per unchanged metadata pair. A manifest left without a valid // owner marker — a stopped creation, or a corrupt marker — is not a creation still in // progress, and registrations run on the request path: charging each of them the full wait // stalls every request to that home. Either file changing re-arms a single wait. const observed = creationWaitIdentity(configDir); if (observed !== null && expiredCreationWait.get(cacheKey) === observed) { // A spent wait suppresses only the wait itself, never the reload: the identity it keeps // may already name a completed pair. One plain load stays cheap for an unchanged invalid // pair and lets a valid one register instead of sticking unowned. ownership = loadOwnership(configDir); if (ownership !== null) expiredCreationWait.delete(cacheKey); } else { ownership = loadOrCreateOwnership(configDir); const current = creationWaitIdentity(configDir); // Record only the identity the wait actually ran out on: unchanged across it, so its last // failed read describes the same state. A pair that changed during the wait, including one // that completed just after that read, spends its own wait on the next registration. if (ownership === null && current !== null && current === observed) expiredCreationWait.set(cacheKey, current); else expiredCreationWait.delete(cacheKey); } ownershipCache.set(cacheKey, ownership); } return ownership !== null; } /** * The metadata of an uninstall that stopped after deleting the owner marker: a valid, tombstoned * manifest for this root and no owner marker. Uninstall deletes the owner marker first and the * manifest last, so this state carries the owner id, the root and the exact snapshot. Creation * writes an untombstoned manifest first, so it never looks like this. */ function tombstonedManifestWithoutOwner(configDir: string): { owner: ConfigOwner; manifest: ConfigUninstallManifest } | null { if (existsSync(join(configDir, CONFIG_OWNER_FILE))) return null; const path = join(configDir, CONFIG_UNINSTALL_MANIFEST); if (!existsSync(path)) return null; try { const manifest = readBoundedJsonSized(path, TOMBSTONED_MANIFEST_MAX_BYTES).value; if (!isManifest(manifest) || manifest.uninstallStartedAt === undefined || !samePath(manifest.root, canonicalRoot(configDir))) return null; return { owner: { version: 1, ownerId: manifest.ownerId, root: manifest.root }, manifest }; } catch { return null; } } /** Ownership for uninstall: the usual pair, or the tombstoned manifest a stopped uninstall left. */ function loadOwnershipForUninstall(configDir: string): { owner: ConfigOwner; manifest: ConfigUninstallManifest } | null { return loadOwnership(configDir) ?? tombstonedManifestWithoutOwner(configDir); } /** How long an uncached or unowned registration waits for another process creating the same home. */ const CONCURRENT_CREATION_WAIT_MS = 100; /** * Load the ownership metadata, or create it in an empty root. Two processes can start on the same * absent home: the loser of the exclusive manifest write, or one that sees the manifest before the * complete owner marker (creation writes them in that order), waits briefly and loads the winner's metadata * instead of caching the home as unowned for the rest of its life. */ function loadOrCreateOwnership(configDir: string): { owner: ConfigOwner; manifest: ConfigUninstallManifest } | null { const deadline = Date.now() + CONCURRENT_CREATION_WAIT_MS; for (;;) { const loaded = loadOwnership(configDir); if (loaded) return loaded; try { const created = createOwnership(configDir); if (created) return created; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; } // Exclusive create publishes the owner file name before its JSON bytes are complete. // Only a valid matching pair proves ownership; file presence alone must not end this wait. const creating = existsSync(join(configDir, CONFIG_UNINSTALL_MANIFEST)) && !tombstonedManifestWithoutOwner(configDir); if (!creating || Date.now() >= deadline) return loadOwnership(configDir); Bun.sleepSync(5); } } type RecordOutcome = { ownership: { owner: ConfigOwner; manifest: ConfigUninstallManifest }; recorded: boolean; identity: string | undefined; }; /** What a registration did: recorded the path, found no ownership to record it in, or found the manifest full. */ export type OwnedPathRegistration = "recorded" | "unowned" | "full"; export function recordOwnedConfigPath(configDir: string, candidatePath: string): boolean { return registerOwnedConfigPath(configDir, candidatePath) === "recorded"; } /** * Read-only: whether the manifest lists `candidatePath` or one of its ancestors ("listed"), lists * neither ("unlisted"), or the home has no ownership metadata ("unowned"). Writes nothing; throws * {@link ConfigUninstallInProgressError} under an uninstall tombstone, as a registration would. */ export function configPathOwnership(configDir: string, candidatePath: string): "listed" | "unlisted" | "unowned" { const current = loadOwnership(configDir) ?? tombstonedManifestWithoutOwner(configDir); if (!current) return "unowned"; if (current.manifest.uninstallStartedAt !== undefined && teardownDepth === 0) throw new ConfigUninstallInProgressError(); const parts = manifestRelativePath(configDir, candidatePath)?.split("/") ?? []; return parts.some((_, index) => current.manifest.paths.includes(parts.slice(0, index + 1).join("/"))) ? "listed" : "unlisted"; } function entryExists(path: string): boolean { try { lstatSync(path); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; } } /** * {@link recordOwnedConfigPath} with the reason a path was not recorded, for callers that must tell * an unowned home (keep working as before) from an owned home whose manifest is full (whatever they * create there survives uninstall). */ export function registerOwnedConfigPath(configDir: string, candidatePath: string): OwnedPathRegistration { const rel = manifestRelativePath(configDir, candidatePath); if (!rel) return "unowned"; const cacheKey = ownershipCacheKey(configDir); if (initializeConfigOwnership(configDir)) { const ownership = ownershipCache.get(cacheKey); if (!ownership) return "unowned"; if (ownership.manifest.paths.includes(rel)) { const seen = lockedManifestIdentity.get(cacheKey); if (seen !== undefined && seen === manifestIdentity(configDir)) return "recorded"; } } else if (!tombstonedManifestWithoutOwner(configDir)) { return "unowned"; } else if (teardownDepth === 0) { // Between uninstall's two final unlinks only the tombstoned manifest remains. That is an // uninstall finishing (or stopped there), not an unowned home. throw new ConfigUninstallInProgressError(); } // Read-modify-write against the manifest on disk, never the cache: another process may have // recorded paths or started an uninstall since this one cached it (#8093). let locked: { value: RecordOutcome | null } | undefined; try { locked = withOwnershipLock(configDir, (): RecordOutcome | null => { let current = loadOwnership(configDir); if (!current) { // A process that cached the ownership before uninstall deleted the owner marker lands here. const stopped = tombstonedManifestWithoutOwner(configDir); if (!stopped) return null; if (teardownDepth === 0) throw new ConfigUninstallInProgressError(); current = stopped; } const tombstoned = current.manifest.uninstallStartedAt !== undefined; if (tombstoned && teardownDepth === 0) throw new ConfigUninstallInProgressError(); if (current.manifest.paths.includes(rel)) return { ownership: current, recorded: true, identity: manifestIdentity(configDir) }; // Under a tombstone only this process's own uninstall rerun registers: it records a path it is // about to create, so its remover takes that path too, and never adopts an existing entry the // snapshot does not list (with or without the owner marker). if (tombstoned && entryExists(join(configDir, ...rel.split("/")))) return null; const manifest = { ...current.manifest, paths: [...current.manifest.paths, rel].sort() }; // A manifest over either cap would fail validation and strand every recorded path. The byte // check leaves room for the tombstone uninstall adds later. Under the tombstone, an initially // owned name may use the recovery reserve instead. const bytes = Buffer.byteLength(serializeManifest(manifest)); const withinCaps = manifest.paths.length <= MANIFEST_MAX_PATHS && bytes + TOMBSTONE_RESERVE_BYTES <= METADATA_MAX_BYTES; const withinRecovery = tombstoned && (INITIAL_OWNED_PATHS as readonly string[]).includes(rel) && manifest.paths.length <= MANIFEST_MAX_PATHS + RECOVERY_RESERVE_PATHS && bytes <= TOMBSTONED_MANIFEST_MAX_BYTES; if (!withinCaps && !withinRecovery) { return { ownership: current, recorded: false, identity: manifestIdentity(configDir) }; } writeManifest(configDir, manifest); return { ownership: { owner: current.owner, manifest }, recorded: true, identity: manifestIdentity(configDir) }; }); } catch (error) { if (!(error instanceof ConfigOwnershipLockError)) throw error; // A busy lock blocks nothing for a path the manifest already lists. The manifest is replaced // atomically, so an unlocked read is a consistent version: accept the path unless that version // carries an uninstall tombstone. Only a new path needs the lock, and it still fails here. const current = loadOwnership(configDir) ?? tombstonedManifestWithoutOwner(configDir); if (current?.manifest.uninstallStartedAt !== undefined && teardownDepth === 0) throw new ConfigUninstallInProgressError(); if (current?.manifest.paths.includes(rel)) return "recorded"; throw error; } if (!locked?.value) { ownershipCache.delete(cacheKey); lockedManifestIdentity.delete(cacheKey); return "unowned"; } // A tombstoned manifest is never cached or remembered for the fast path: only the teardown scope // may register under it, and once that scope ends every call must see the tombstone again. if (locked.value.ownership.manifest.uninstallStartedAt !== undefined) { ownershipCache.delete(cacheKey); lockedManifestIdentity.delete(cacheKey); } else { ownershipCache.set(cacheKey, locked.value.ownership); if (locked.value.identity === undefined) lockedManifestIdentity.delete(cacheKey); else lockedManifestIdentity.set(cacheKey, locked.value.identity); } if (!locked.value.recorded && !warnedFullManifest.has(cacheKey)) { warnedFullManifest.add(cacheKey); // Uninstall still reports such a file as a residual path; it just cannot remove it. console.warn("[opencodex] The config ownership manifest is full; new files will not be removed by uninstall."); } return locked.value.recorded ? "recorded" : "full"; } /** * What a finished uninstall can leave when a lock file could not be unlinked (Windows keeps a file * another process holds open): nothing but this module's lock files. Without ownership metadata * nothing proves where such a name came from, so only files that hold no data qualify: the lock is * a SQLite transaction that never writes, so its file and any sidecar stay empty. The main lock file * must be among them, and each one is a single-link regular file. Anything else is refused untouched. */ function onlyOwnershipLockFilesRemain(configDir: string): boolean { const names = readdirSync(configDir); const lockNames = new Set([CONFIG_OWNERSHIP_LOCK, ...OWNERSHIP_LOCK_SIDECARS.map(suffix => `${CONFIG_OWNERSHIP_LOCK}${suffix}`)]); return names.includes(CONFIG_OWNERSHIP_LOCK) && names.every(name => { if (!lockNames.has(name)) return false; const entry = lstatSync(join(configDir, name)); return entry.isFile() && !entry.isSymbolicLink() && entry.nlink === 1 && entry.size === 0; }); } /** Remove leftover lock files only if no other process holds the lock (an uninstall still finishing). */ function removeIdleLockFiles(configDir: string): "removed" | "busy" { const path = join(configDir, CONFIG_OWNERSHIP_LOCK); const before = fileIdentity(path); const database = new Database(path, { create: false, readwrite: true }); try { acquireImmediate(database); } catch (error) { try { database.close(); } catch { /* acquisition already failed */ } if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "SQLITE_BUSY") return "busy"; throw error; } let same: boolean; try { same = !lockFileChanged(path, before); } finally { try { database.exec("ROLLBACK"); } catch { /* close releases it */ } database.close(); } // Taking the lock proved no process holds it. The files are checked again only after release, // because while held SQLite keeps this transaction's own rollback journal beside the lock file and // deletes it when the transaction ends. Nothing else takes the lock in between: without ownership // metadata no registration locks this root, creation never claims a nonempty one, and a second run // of this cleanup removes the same files. if (!same || !onlyOwnershipLockFilesRemain(configDir)) return "busy"; if (!unlinkLockFile(path, before)) throw new Error("the ownership lock file could not be removed"); removeEmptyLockSidecars(configDir); return "removed"; } /** The elevated-run check; null when the run is not elevated. */ function privilegeCheck(configDir: string): { refusal: string | null } | null { if (!uninstallRunsElevated()) return null; return { refusal: elevatedRemovalRefusal(configDir) }; } /** * Read-only check `ocx uninstall` runs before its first teardown step: the reason an elevated run * must not touch this home, or null. The remover repeats it before taking the lock. */ export function uninstallPrivilegeRefusal(configDir: string): string | null { return privilegeCheck(configDir)?.refusal ?? null; } export function removeOwnedConfigState(configDir: string): ConfigRemovalResult { ownershipCache.delete(ownershipCacheKey(configDir)); lockedManifestIdentity.delete(ownershipCacheKey(configDir)); if (!existsSync(configDir)) return { status: "absent", residualPaths: [] }; const root = lstatSync(configDir); if (!root.isDirectory() || root.isSymbolicLink()) { return { status: "refused", reason: "config ownership root is not a real directory", residualPaths: [configDir], }; } // Everything below works on the canonical root, resolved once here, so no later step goes back // through the spelling the caller passed. Residual paths are reported in that spelling. let canonical: string; let identity: RootIdentity; try { canonical = canonicalRoot(configDir); identity = rootIdentity(canonical); } catch { return { status: "refused", reason: "config ownership root is not a real directory", residualPaths: [configDir] }; } const result = removeCanonicalOwnedConfigState(canonical, identity); return { ...result, residualPaths: result.residualPaths.map(path => callerSpelling(path, canonical, configDir)) }; } function callerSpelling(path: string, canonical: string, configDir: string): string { if (path === canonical) return configDir; const rel = relative(canonical, path); return rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel) ? join(configDir, rel) : path; } function removeCanonicalOwnedConfigState(configDir: string, identity: RootIdentity): ConfigRemovalResult { // `configDir` is the canonical root resolved once by the caller, and `identity` the directory it // named then. It is never resolved again: each step below that acts on it first confirms it is still // that directory, a real one resolving to itself. A change before anything is written is refused; // one found later ends the run partial, and the tombstone lets a rerun finish. const rootChanged: ConfigRemovalResult = { status: "refused", reason: "the config directory changed while uninstall ran; run 'ocx uninstall' again", residualPaths: [configDir], }; const rootMoved: ConfigRemovalResult = { status: "partial", reason: "the config directory changed while uninstall ran; run 'ocx uninstall' again", residualPaths: [configDir], }; ownershipCache.delete(ownershipCacheKey(configDir)); lockedManifestIdentity.delete(ownershipCacheKey(configDir)); // Before the lock exists or anything is written, so a refused elevated run changes nothing. const privilege = privilegeCheck(configDir); if (privilege?.refusal) return { status: "refused", reason: privilege.refusal, residualPaths: [configDir] }; if (!canonicalRootUnchanged(configDir, identity)) return rootChanged; if (!loadOwnershipForUninstall(configDir)) { // A finished uninstall whose lock file could not be unlinked (Windows keeps a file another // process holds open) leaves only lock files. They are removed once no process holds the lock. if (onlyOwnershipLockFilesRemain(configDir)) { try { if (removeIdleLockFiles(configDir) === "busy") { return { status: "refused", reason: "another opencodex process holds the ownership lock; retry shortly", residualPaths: [configDir] }; } rmdirSync(configDir); return { status: "removed", residualPaths: [] }; } catch (error) { return { status: "partial", reason: `could not remove the ownership lock: ${error instanceof Error ? error.message : String(error)}`, residualPaths: readdirSync(configDir).map(name => join(configDir, name)), }; } } return { status: "refused", reason: "config ownership metadata is missing or invalid", residualPaths: [configDir], }; } // One lock hold covers the whole run: validate, tombstone, snapshot, remove the snapshot, delete // the owner marker and then the manifest. While it is held no other process can record a path (a // listed path read without the lock sees the tombstone and refuses, a new path needs the lock), // and a second uninstall is refused as busy, so nothing can be recorded or recreated behind this // run. A run interrupted at any point leaves the tombstoned manifest, which carries the owner id, // the root and the exact snapshot, so a rerun finishes from it. let outcome: ConfigRemovalResult; try { const locked = withOwnershipLock(configDir, (): ConfigRemovalResult => { const ownership = loadOwnershipForUninstall(configDir); if (!ownership) { return { status: "refused", reason: "config ownership metadata is missing or invalid", residualPaths: [configDir] }; } for (const rel of ownership.manifest.paths) { if (manifestRelativePath(configDir, join(configDir, ...rel.split("/"))) !== rel) { return { status: "refused", reason: "config ownership manifest contains an unsafe path", residualPaths: [configDir] }; } } // Checked again under the lock and before the tombstone: the manifest, ownership, modes and the // tree may all have changed since the unlocked check. const lockedRefusal = privilege ? elevatedRemovalRefusal(configDir) : null; if (lockedRefusal) return { status: "refused", reason: lockedRefusal, residualPaths: [configDir] }; if (!canonicalRootUnchanged(configDir, identity)) return rootChanged; if (ownership.manifest.uninstallStartedAt === undefined) { writeManifest(configDir, { ...ownership.manifest, uninstallStartedAt: Date.now() }); } if (!canonicalRootUnchanged(configDir, identity)) return rootMoved; removeAbandonedMetadataTemps(configDir, ownership.owner); const rootPath = configDir; const elevatedUid = process.platform !== "win32" && uninstallRunsElevated() ? process.geteuid?.() : undefined; for (const rel of ownership.manifest.paths) { const parts = rel.split("/"); const path = join(configDir, ...parts); try { // lstat-based: a listed symlink whose target is gone is still ours to unlink, and a link on // the way to an entry is reported rather than read as absence. if (ownedEntryPresent(rootPath, parts)) removeOwnedEntry(rootPath, parts, { elevatedUid, rootIdentity: identity }); } catch (error) { return { status: "partial", reason: `could not remove owned path ${rel}: ${error instanceof Error ? error.message : String(error)}`, residualPaths: [path], }; } } uninstallStepHookForTests?.("snapshot-removed"); if (!canonicalRootUnchanged(configDir, identity)) return rootMoved; try { // Owner marker first, manifest last: until the end the tombstoned manifest stays as the record // a rerun resumes from, and creation (manifest first) never leaves that state. try { unlinkSync(join(configDir, CONFIG_OWNER_FILE)); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } uninstallStepHookForTests?.("owner-deleted"); unlinkSync(join(configDir, CONFIG_UNINSTALL_MANIFEST)); } catch (error) { return { status: "partial", reason: `could not remove ownership metadata: ${error instanceof Error ? error.message : String(error)}`, residualPaths: readdirSync(configDir).map(name => join(configDir, name)), }; } return { status: "removed", residualPaths: [] }; }); outcome = locked?.value ?? { status: "refused", reason: "config ownership metadata is missing or invalid", residualPaths: [configDir] }; } catch (error) { outcome = { status: "refused", reason: `could not lock the ownership manifest: ${error instanceof Error ? error.message : String(error)}`, residualPaths: [configDir], }; } if (outcome.status !== "removed") return outcome; if (!canonicalRootUnchanged(configDir, identity)) return rootMoved; // The lock holder retired its own lock file on release; one that remains (Windows) is reported. const residualPaths = readdirSync(configDir).map(name => join(configDir, name)); if (residualPaths.length > 0) { return { status: "partial", reason: "unowned files remain in the config directory", residualPaths, }; } try { rmdirSync(configDir); } catch (error) { return { status: "partial", reason: `could not remove the empty config directory: ${error instanceof Error ? error.message : String(error)}`, residualPaths: [configDir], }; } return { status: "removed", residualPaths: [] }; }