@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
431 lines (422 loc) • 23 kB
text/typescript
/**
* config-write-lock.ts — one advisory lock for every opencodex-originated
* `config.toml` write.
*
* Why a second lock next to the existing two: the injector's SQLite lock N
* serializes injection against injection, and the prompt-layers lock serializes
* prompt edits against prompt edits. Neither covers the writers BETWEEN them —
* the feature scalars in `features.ts`, the `ocx restore`/`removeCodexConfig`
* transforms, and the journal replay each did their own unlocked read → edit →
* `atomicWriteFile`. Each write is individually atomic, but a foreign rewrite
* landing between any writer's read and its rename was silently discarded:
* a features edit could drop an injection's freshly-written routing keys, a
* remove could drop a prompt projection committed a millisecond earlier.
*
* This lock closes that class at its source rather than per call site: every
* opencodex writer reads `config.toml` and renames over it while holding
* `<config>.ocx-write.lock`, so no cooperating writer can be computed against
* stale bytes and none can land mid-section.
*
* What it deliberately does NOT cover:
* - Codex itself knows nothing about the file; upstream's own rewrites cannot
* be serialized from here. That residual is why the injector's witness and
* the drift healer still exist.
* - Lock ordering: prompt-layers commit() takes the prompt store lock first,
* then this one; the injector takes this one first, then N, then C — and the
* coordinated restore path follows that same file-first order
* (`restoreNativeCodexAsyncImpl` acquires this lock before its `withCodexWriteLock`
* journal replay), so no cross-lock inversion remains. Synchronous
* acquisition fails fast; asynchronous acquisition has a bounded wait.
* - The injector's held section contains awaits (`withCodexWriteLock` is
* async), so the lock must NOT be implicitly reentrant — a same-process
* writer that slipped inside on a process-global check would interleave
* mid-section. Reentrancy is explicit instead: a caller that already holds
* the file passes its handle (`heldConfigWriteLock`) to the writer it
* calls.
* - Acquisition is a single attempt for synchronous writers: the section under
* this lock is a handful of file operations, so a busy result means the
* caller reports "locked" and the operator retries — the same contract the
* prompt store lock already exposes. Async callers (the injector) use the
* bounded wait in `acquireConfigWriteLock`.
*/
import { atomicWriteFileStreamed, type AtomicWriteHooks } from "../config/atomic-write";
import { lstatSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import { createHash, randomUUID } from "node:crypto";
import { basename, dirname, join, resolve } from "node:path";
import { release, stillHeld, tryAcquire, type AcquireResult, type LockHandle } from "./prompt-lock";
interface Destination { canonical: string; inode: string | null }
const destinations = new WeakMap<LockHandle, Destination>();
interface ConfigWriteRecovery {
canonical: string;
preimage: Buffer | null;
identity: string | null;
refreshBeforeSpawn: boolean;
}
const recoveries = new WeakMap<LockHandle, ConfigWriteRecovery>();
export class ConfigWriteParentMissing extends Error {
constructor(readonly path: string) { super(`Codex configuration parent is missing or unresolved at ${path}`); }
}
type ConfigWriteAcquireResult = AcquireResult | { ok: false; error: "missing-parent"; detail: string };
function destination(path: string): Destination {
const absolute = resolve(path);
let canonical: string;
try { canonical = realpathSync.native(absolute); }
catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
try { canonical = join(realpathSync.native(dirname(absolute)), basename(absolute)); }
catch (parentError) {
if ((parentError as NodeJS.ErrnoException).code === "ENOENT") throw new ConfigWriteParentMissing(dirname(absolute));
throw parentError;
}
}
try {
const stat = statSync(canonical, { bigint: true });
return { canonical, inode: `${stat.dev}:${stat.ino}` };
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
return { canonical, inode: null };
}
}
/** Symlink aliases share the lock beside their canonical write destination. */
export function configWriteLockPath(configPath: string): string {
return `${destination(configPath).canonical}.ocx-write.lock`;
}
export const CONFIG_WRITE_LOCKED_MESSAGE =
"another opencodex process is writing Codex configuration — retry shortly";
export type ConfigWriteLockOutcome<T> =
| { ok: true; value: T }
| Exclude<ConfigWriteAcquireResult, { ok: true }>;
function acquire(configPath: string): ConfigWriteAcquireResult {
let target: Destination;
try { target = destination(configPath); }
catch (error) {
if (error instanceof ConfigWriteParentMissing) return { ok: false, error: "missing-parent", detail: error.path };
throw error;
}
const acquired = tryAcquire(`${target.canonical}.ocx-write.lock`);
if (!acquired.ok) return acquired;
try {
// A preceding writer may atomically replace the file before releasing the lock.
// Capture the inode only after acquisition, while retaining the canonical-path gate.
const current = destination(configPath);
if (current.canonical !== target.canonical || !stillHeld(acquired.handle)) {
release(acquired.handle);
return { ok: false, error: "unsafe", detail: acquired.handle.path };
}
// Preserve caller-owned unreadable/non-regular errors, but do not mistake a
// dangling link (realpath's fallback) or a fresh replacement for proven absence.
try {
const entry = lstatSync(current.canonical, { bigint: true });
if (entry.isSymbolicLink() || `${entry.dev}:${entry.ino}` !== current.inode) throw new ConfigWriteDestinationChanged();
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT" || current.inode !== null) throw error;
}
destinations.set(acquired.handle, current);
return acquired;
} catch (error) {
release(acquired.handle);
throw error;
}
}
export function withConfigWriteLock<T>(configPath: string, run: (handle: LockHandle) => T): ConfigWriteLockOutcome<T> {
const acquired = acquire(configPath);
if (!acquired.ok) return acquired;
try { return { ok: true, value: run(acquired.handle) }; }
finally { release(acquired.handle); }
}
export function configWriteLockHeld(handle: LockHandle): boolean { return stillHeld(handle); }
export function releaseConfigWriteLock(handle: LockHandle): void { release(handle); }
export type { LockHandle };
export function assertConfigWriteDestination(configPath: string, held: LockHandle): string {
const current = destination(configPath);
const expected = destinations.get(held);
if (!stillHeld(held) || held.path !== `${current.canonical}.ocx-write.lock`
|| (expected && (current.canonical !== expected.canonical || current.inode !== expected.inode))) {
throw new Error("Codex configuration destination changed; files and recovery evidence were preserved.");
}
if (!expected) destinations.set(held, current);
return current.canonical;
}
/** A writer advances the witness only through its confirmed publication hook. */
export function publishConfigWrite<T>(configPath: string, held: LockHandle, run: (destination: string, hooks: AtomicWriteHooks) => T): T {
const canonical = assertConfigWriteDestination(configPath, held);
return run(canonical, {
validateBeforeRename: () => { assertConfigWriteDestination(configPath, held); },
afterRename: () => {
const payloadKnown = payloadDigestPending.delete(held);
const recovery = recoveries.get(held);
if (recovery?.canonical === canonical) recovery.identity = canonicalFileIdentity(canonical);
const after = destination(configPath);
if (!stillHeld(held) || after.canonical !== canonical) throw new Error("Codex configuration destination changed; recovery evidence was preserved.");
destinations.set(held, after);
// A payload-aware publisher records the digest of what it wrote; this re-read only
// covers writers whose bytes this process never sees (a native child, the empty file).
// Known limit for a native child: the `codex` CLI renames its own file and exits, and this
// re-read runs after it exits, so a write by a non-OpenCodex process (the Codex app, an
// editor) landing between the child's rename and this line is recorded as OpenCodex's and a
// later compensation in the same section could revert it. The child cannot report its bytes.
if (!payloadKnown) publishedConfigDigests.set(held, fileDigest(canonical));
const watched = targets.get(held);
if (watched) for (const [path, expected] of watched) if (expected.canonical === canonical) watched.set(path, after);
},
});
}
/** config.toml no longer holds the bytes a writer decided from; nothing was written. */
export class ConfigWriteContentChanged extends Error {
readonly retryable = true;
constructor() {
super("Codex config.toml changed while OpenCodex was writing it; nothing was overwritten. Retry the command.");
}
}
/**
* The digest of the config.toml bytes this lock section last published, `null` for a removal,
* `undefined` when it published none. Compensation reverts only a file still holding them.
*/
const publishedConfigDigests = new WeakMap<LockHandle, string | null>();
const payloadDigestPending = new WeakSet<LockHandle>();
export function publishedConfigDigest(held: LockHandle): string | null | undefined {
return publishedConfigDigests.get(held);
}
/** Called by a publisher that knows its payload, before the rename's afterRename hook runs. */
export function recordPublishedConfigDigest(held: LockHandle, digest: string | null): void {
publishedConfigDigests.set(held, digest);
payloadDigestPending.add(held);
}
export function configDigest(bytes: string | null): string | null {
return bytes === null ? null : createHash("sha256").update(bytes).digest("hex");
}
function fileDigest(path: string): string | null {
try { return createHash("sha256").update(readFileSync(path)).digest("hex"); }
catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
}
/** Native children use the acquisition witness, never a fresh home resolution. */
export class ConfigWriteDestinationChanged extends Error {
readonly retryable = false;
constructor(message = "Codex configuration destination changed; files and recovery evidence were preserved.") { super(message); }
}
/** Refuse before transition staging: native Codex always writes home/config.toml. */
export function assertNativeConfigWriteDestination(configPath: string, held: LockHandle): string {
let canonical: string;
try { canonical = assertConfigWriteDestination(configPath, held); }
catch { throw new ConfigWriteDestinationChanged(); }
const home = realpathSync.native(dirname(canonical));
if (basename(canonical) !== "config.toml" || canonical !== join(home, "config.toml")) {
throw new ConfigWriteDestinationChanged("Native feature changes are unavailable when config.toml is a symlink to a differently named file.");
}
return canonical;
}
function canonicalFileIdentity(canonical: string): string | null {
const current = destination(canonical);
if (current.canonical !== canonical) throw new Error("canonical configuration target was redirected");
let stat;
try { stat = lstatSync(canonical, { bigint: true }); }
catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT" && current.inode === null) return null;
throw error;
}
if (!stat.isFile() || `${stat.dev}:${stat.ino}` !== current.inode) throw new Error("canonical configuration target is not the observed regular file");
return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
}
/** Capture before the first write; nested native children share the same recovery scope. */
export function withConfigWriteRecovery<T>(
configPath: string, held: LockHandle, run: () => T,
options: { refreshBeforeSpawn?: boolean; preimage?: Buffer; requireMatchingPreimage?: boolean } = {},
): T {
const nested = recoveries.get(held);
if (nested && !options.requireMatchingPreimage) return run();
let canonical: string;
try { canonical = assertConfigWriteDestination(configPath, held); }
catch { throw new ConfigWriteDestinationChanged(); }
const identity = canonicalFileIdentity(canonical);
const preimage = identity === null ? null : readFileSync(canonical);
if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged();
if (options.requireMatchingPreimage && (!options.preimage || !preimage?.equals(options.preimage))) {
throw new ConfigWriteDestinationChanged();
}
if (nested && (nested.canonical !== canonical || nested.identity !== identity)) throw new ConfigWriteDestinationChanged();
if (nested) return run();
const recovery: ConfigWriteRecovery = {
canonical, identity, preimage: options.preimage ?? preimage,
refreshBeforeSpawn: options.refreshBeforeSpawn === true && options.preimage === undefined,
};
recoveries.set(held, recovery);
try {
const value = run();
assertConfigWriteDestination(configPath, held);
return value;
} catch (error) {
// Refused before this scope published anything: there is nothing to recover.
if (error instanceof ConfigWriteContentChanged && recovery.identity === identity) throw error;
let changed = error instanceof ConfigWriteDestinationChanged;
try { assertConfigWriteDestination(configPath, held); } catch { changed = true; }
try {
const validateRecovery = (targetPath = canonical) => {
if (targetPath !== canonical || !stillHeld(held) || held.path !== `${canonical}.ocx-write.lock`
|| canonicalFileIdentity(canonical) !== recovery.identity) {
throw new Error("canonical configuration target changed before recovery");
}
};
validateRecovery();
// A pre-write refusal leaves the original entry intact, including its inode.
const unchanged = recovery.identity === identity && (recovery.preimage === preimage
|| (recovery.preimage !== null && preimage !== null && recovery.preimage.equals(preimage)));
if (!unchanged) {
if (recovery.preimage === null) { validateRecovery(); if (recovery.identity !== null) unlinkSync(canonical); }
else atomicWriteFileStreamed(canonical, fd => writeFileSync(fd, recovery.preimage!), { validateBeforeRename: validateRecovery });
}
destinations.set(held, destination(canonical));
} catch (recoveryError) {
let evidence = "recovery evidence could not be persisted";
try {
const recoveryPath = `${canonical}.ocx-native-preimage.${randomUUID()}`;
atomicWriteFileStreamed(recoveryPath, fd => writeFileSync(fd, recovery.preimage ?? Buffer.from('{"preimage":"absent"}\n')));
evidence = `recovery evidence retained at ${recoveryPath}`;
} catch { /* Preserve the refusal and diagnostic even when evidence storage fails. */ }
throw new ConfigWriteDestinationChanged(`Codex configuration destination changed; canonical preimage recovery refused: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}; ${evidence}.`);
}
if (changed) throw new ConfigWriteDestinationChanged(`${error instanceof Error ? error.message : String(error)}; canonical preimage restored and recovery evidence preserved.`);
throw error;
} finally { recoveries.delete(held); }
}
export function runConfigWriteChild(
configPath: string, held: LockHandle,
run: (env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void,
transitionPreimage?: Buffer,
): void {
withConfigWriteRecovery(configPath, held, () => {
const canonical = assertNativeConfigWriteDestination(configPath, held);
const recovery = recoveries.get(held)!;
let readyToSpawn = false;
const validateBeforeSpawn = () => {
readyToSpawn = false;
assertNativeConfigWriteDestination(configPath, held);
const identity = canonicalFileIdentity(canonical);
const bytes = identity === null ? null : readFileSync(canonical);
if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged();
if (recovery.refreshBeforeSpawn) { recovery.preimage = bytes; recovery.identity = identity; }
readyToSpawn = true;
};
publishConfigWrite(configPath, held, (_canonical, hooks) => {
const env = { ...process.env };
// Windows env names are case-insensitive; wrappers may honor Orca's override.
for (const key of Object.keys(env)) {
if (["CODEX_HOME", "ORCA_CODEX_HOME"].includes(key.toUpperCase())) delete env[key];
}
env.CODEX_HOME = realpathSync.native(dirname(canonical));
validateBeforeSpawn();
try { run(env, validateBeforeSpawn); }
// Even a failed child can replace config.toml. Observe only after it entered.
finally {
try { if (readyToSpawn) hooks.afterRename?.(canonical); }
catch { throw new ConfigWriteDestinationChanged(); }
}
});
}, { refreshBeforeSpawn: true, preimage: transitionPreimage });
}
export function withConfigWriteLockHeld<T>(
configPath: string, held: LockHandle | undefined, run: (handle: LockHandle) => T,
): ConfigWriteLockOutcome<T> {
if (held !== undefined) {
try { assertConfigWriteDestination(configPath, held); }
catch { return { ok: false, error: "unsafe", detail: held.path }; }
return { ok: true, value: run(held) };
}
return withConfigWriteLock(configPath, run);
}
const RETRY_MIN_MS = 25;
const RETRY_MAX_MS = 75;
export const CONFIG_WRITE_LOCK_WAIT_MS = 2_000;
export async function acquireConfigWriteLock(
configPath: string,
options: { timeoutMs?: number; nowMs?: () => number; sleep?: (ms: number) => Promise<void> } = {},
): Promise<ConfigWriteAcquireResult> {
const timeoutMs = options.timeoutMs ?? CONFIG_WRITE_LOCK_WAIT_MS;
if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 10_000) throw new RangeError("Invalid config lock timeout");
const now = options.nowMs ?? (() => performance.now());
const sleep = options.sleep ?? (ms => new Promise(done => setTimeout(done, ms)));
const deadline = now() + timeoutMs;
for (;;) {
const acquired = acquire(configPath);
if (acquired.ok || acquired.error !== "locked") return acquired;
const remaining = deadline - now();
if (timeoutMs === 0 || remaining <= 0) return { ok: false, error: "locked" };
await sleep(Math.max(1, Math.min(remaining,
RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS + 1)))));
}
}
const targets = new WeakMap<LockHandle, Map<string, Destination>>();
export function watchConfigWriteTargets(held: LockHandle, paths: readonly string[]): void {
let watched = targets.get(held);
if (!watched) { watched = new Map(); targets.set(held, watched); }
for (const path of paths) if (!watched.has(path)) watched.set(path, destination(path));
}
export function publishConfigWriteTarget<T>(
configPath: string, held: LockHandle, path: string, run: (destination: string, hooks: AtomicWriteHooks) => T,
): T {
assertConfigWriteDestination(configPath, held);
watchConfigWriteTargets(held, [path]);
const watched = targets.get(held)!, expected = watched.get(path)!, current = destination(path);
if (expected.canonical !== current.canonical || expected.inode !== current.inode) {
throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
}
if (path === configPath) {
const value = publishConfigWrite(configPath, held, run);
return value;
}
return run(current.canonical, {
validateBeforeRename: () => {
assertConfigWriteDestination(configPath, held);
const now = destination(path);
if (expected.canonical !== now.canonical || expected.inode !== now.inode) throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
},
afterRename: () => {
assertConfigWriteDestination(configPath, held);
const after = destination(path);
if (after.canonical !== current.canonical) throw new Error("Codex artifact destination changed; recovery evidence was preserved.");
watched.set(path, after);
},
});
}
export function removeConfigWriteEntry(configPath: string, held: LockHandle, path: string): void {
assertConfigWriteDestination(configPath, held);
watchConfigWriteTargets(held, [path]);
const watched = targets.get(held)!;
const expected = watched.get(path)!;
const current = destination(path);
if (expected.canonical !== current.canonical || expected.inode !== current.inode
|| current.canonical !== join(realpathSync.native(dirname(resolve(path))), basename(resolve(path)))) {
throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
}
if (expected.inode === null) return;
const entry = join(realpathSync.native(dirname(resolve(path))), basename(resolve(path)));
const identity = (file: { dev: bigint; ino: bigint }) => `${file.dev}:${file.ino}`;
const before = lstatSync(entry, { bigint: true });
if (before.isSymbolicLink() || !before.isFile() || identity(before) !== expected.inode) {
throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
}
assertConfigWriteDestination(configPath, held);
const now = lstatSync(entry, { bigint: true });
if (now.isSymbolicLink() || !now.isFile() || identity(now) !== expected.inode) {
throw new Error("Codex artifact destination changed; files and recovery evidence were preserved.");
}
unlinkSync(entry);
assertConfigWriteDestination(configPath, held);
const after = destination(path);
if (after.inode !== null || after.canonical !== expected.canonical) {
throw new Error("Codex artifact destination changed; recovery evidence was preserved.");
}
watched.set(path, after);
}
export function configWriteLockFailureMessage(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>): string {
if (failure.error === "missing-parent") return `Codex configuration parent is missing or unresolved at ${failure.detail}; no files were changed.`;
return failure.error === "unsafe"
? `Unsafe Codex configuration lock at ${failure.detail}; deliberate removal is required. Files and recovery evidence were preserved.`
: CONFIG_WRITE_LOCKED_MESSAGE;
}
export class ConfigWriteLockRefusal extends Error {
readonly retryable: boolean;
constructor(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>) {
super(configWriteLockFailureMessage(failure));
this.retryable = failure.error === "locked";
}
}