@parall/codex-agent 1.42.0 → 1.42.1

package/dist/workspace.d.ts

@@ -1,4 +1,89 @@
 import type { AgentIdentity } from '@parall/agent-core';
+/**
+ * Config-lock timings, exported for tests.
+ *
+ * `staleMs` — a queue ticket untouched this long is treated as a crashed
+ * owner (live contenders refresh their ticket's mtime every `retryMs`, so
+ * the margin is ~400×). `waitMs` deliberately exceeds `staleMs`: a waiter
+ * facing a crashed head-of-queue outlasts the staleness threshold and skips
+ * it instead of falling through to a lockless write — the lockless fallback
+ * is a last resort, not a normal path.
+ */
+export declare const CONFIG_LOCK_TIMINGS: {
+    staleMs: number;
+    waitMs: number;
+    retryMs: number;
+};
+/**
+ * Advisory cross-process lock serializing `<codexHome>/config.toml`
+ * read-modify-write. On a local daemon machine every runtime_auth codex
+ * bridge child shares the operator's CODEX_HOME, and the daemon starts them
+ * together — without a lock, a whole-file rewrite working from a stale read
+ * can erase a trust entry another agent appended in between.
+ *
+ * Queue design (why not wx-create + steal): any scheme that renames or
+ * unlinks the SHARED lock path can, between its staleness check and the
+ * destructive op, hit a fresh lock that replaced the stale one — deleting a
+ * live holder's lock and overlapping critical sections (reproduced under
+ * 12-process contention). Here contenders queue in `config.toml.lock.d/`
+ * using Lamport's bakery protocol, and the smallest live ticket holds the
+ * lock. Two phases per enqueue: (1) create a `choosing-<token>` marker,
+ * (2) take seq = max(existing ticket seqs) + 1 and publish by atomically
+ * RENAMING the marker into `t-<seq>-<token>`. Evaluators wait while any
+ * live choosing marker exists, so a contender that read the queue but
+ * hasn't published yet can never be missed — the classic bakery guarantee.
+ * (A naive self-chosen timestamp order would race: a process descheduled
+ * between choosing its stamp and writing its ticket could insert itself
+ * before an already-running holder.) The rename-publish closes the
+ * stale-mid-choosing hole: once a frozen chooser's marker has been GC'd,
+ * its publish fails and it must re-enqueue fresh — it can never surface an
+ * old low seq under a holder elected in its absence. ENTRY is the same
+ * pattern: the elected head atomically renames its ticket into a
+ * `held-<entry-ts>-…` entry, racing any staleness eviction of that ticket
+ * on the same path — a contender revived at the staleness boundary loses
+ * the rename and re-enqueues rather than entering behind an eviction. The
+ * holder's freshness is embedded in the held name (atomic with entry), so
+ * evicting a holder needs no stat. Evaluators mirror the atomicity: after
+ * any GC attempt, or on a marker that vanished mid-scan, they take a fresh
+ * snapshot instead of electing from the old one. Ticket order is
+ * (seq, token), identical for every observer.
+ *
+ * No process ever mutates a shared path: release unlinks only the caller's
+ * own ticket, and the only cross-process destructive op is GC of entries
+ * untouched for `staleMs` — safe because live contenders refresh their
+ * ticket's mtime every `retryMs`, and names embed a per-acquisition random
+ * token so they are never reused (no identity switch on unlink).
+ *
+ * Residual (documented, not fixable without OS-level flock, which Node core
+ * does not expose): a HOLDER frozen inside `fn` for longer than `staleMs`
+ * looks crashed, gets evicted, and the next head may overlap it — `fn` is a
+ * millisecond-scale sync config write, 400× within margin. Freezes anywhere
+ * else (mid-choosing, at entry) are safe: the atomic renames fail after an
+ * eviction and the process re-enqueues. On `waitMs` timeout
+ * the mutation proceeds without the lock (warn) — blocking would wedge
+ * bridge startup. The lock coordinates bridge processes only; codex itself
+ * does not observe it, which is why bridge writes to a shared config are
+ * additionally kept rare (the trust write is a no-op after the first boot
+ * per workspace, and runtime_auth agents never write the provider block)
+ * and whole-file writes are atomic (temp + rename) so codex never reads a
+ * truncated file.
+ *
+ * Exported for tests.
+ */
+export declare function withConfigLock(codexHome: string, log: {
+    warn: (msg: string) => void;
+} | undefined, fn: () => void): void;
+/**
+ * Test-only scheduling hooks for deterministic race tests. Production code
+ * never sets these; tests use them to pause a contender at the two points
+ * where another process can act in between (barrier files stand in for the
+ * OS scheduler).
+ */
+export declare const CONFIG_LOCK_TEST_HOOKS: {
+    beforeChoosingMarker?: () => void;
+    beforeTicketPublish?: () => void;
+    beforeTicketEntry?: () => void;
+};
 /**
  * Ensure the workspace directory is marked as trusted in the global Codex
  * config so that project-level `developer_instructions` are loaded at

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAgFN;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CA6CN;AASD,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAqBN"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;CAI/B,CAAC;AAUF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,SAAS,EAChD,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAkJN;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE;IACnC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAuJP;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAqGD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAEN;AAwDD,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAqBN"}

package/dist/workspace.js

@@ -2,6 +2,406 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parse as parseToml } from 'smol-toml';
 import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity, buildSkillReferences, writeSkillFiles, } from '@parall/agent-core';
+/**
+ * Config-lock timings, exported for tests.
+ *
+ * `staleMs` — a queue ticket untouched this long is treated as a crashed
+ * owner (live contenders refresh their ticket's mtime every `retryMs`, so
+ * the margin is ~400×). `waitMs` deliberately exceeds `staleMs`: a waiter
+ * facing a crashed head-of-queue outlasts the staleness threshold and skips
+ * it instead of falling through to a lockless write — the lockless fallback
+ * is a last resort, not a normal path.
+ */
+export const CONFIG_LOCK_TIMINGS = {
+    staleMs: 10_000,
+    waitMs: 15_000,
+    retryMs: 25,
+};
+// Reused wait signal: sleepSync fires every retryMs under contention, and a
+// fresh SharedArrayBuffer per call is avoidable allocation churn.
+const SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_SIGNAL, 0, 0, ms);
+}
+/**
+ * Advisory cross-process lock serializing `<codexHome>/config.toml`
+ * read-modify-write. On a local daemon machine every runtime_auth codex
+ * bridge child shares the operator's CODEX_HOME, and the daemon starts them
+ * together — without a lock, a whole-file rewrite working from a stale read
+ * can erase a trust entry another agent appended in between.
+ *
+ * Queue design (why not wx-create + steal): any scheme that renames or
+ * unlinks the SHARED lock path can, between its staleness check and the
+ * destructive op, hit a fresh lock that replaced the stale one — deleting a
+ * live holder's lock and overlapping critical sections (reproduced under
+ * 12-process contention). Here contenders queue in `config.toml.lock.d/`
+ * using Lamport's bakery protocol, and the smallest live ticket holds the
+ * lock. Two phases per enqueue: (1) create a `choosing-<token>` marker,
+ * (2) take seq = max(existing ticket seqs) + 1 and publish by atomically
+ * RENAMING the marker into `t-<seq>-<token>`. Evaluators wait while any
+ * live choosing marker exists, so a contender that read the queue but
+ * hasn't published yet can never be missed — the classic bakery guarantee.
+ * (A naive self-chosen timestamp order would race: a process descheduled
+ * between choosing its stamp and writing its ticket could insert itself
+ * before an already-running holder.) The rename-publish closes the
+ * stale-mid-choosing hole: once a frozen chooser's marker has been GC'd,
+ * its publish fails and it must re-enqueue fresh — it can never surface an
+ * old low seq under a holder elected in its absence. ENTRY is the same
+ * pattern: the elected head atomically renames its ticket into a
+ * `held-<entry-ts>-…` entry, racing any staleness eviction of that ticket
+ * on the same path — a contender revived at the staleness boundary loses
+ * the rename and re-enqueues rather than entering behind an eviction. The
+ * holder's freshness is embedded in the held name (atomic with entry), so
+ * evicting a holder needs no stat. Evaluators mirror the atomicity: after
+ * any GC attempt, or on a marker that vanished mid-scan, they take a fresh
+ * snapshot instead of electing from the old one. Ticket order is
+ * (seq, token), identical for every observer.
+ *
+ * No process ever mutates a shared path: release unlinks only the caller's
+ * own ticket, and the only cross-process destructive op is GC of entries
+ * untouched for `staleMs` — safe because live contenders refresh their
+ * ticket's mtime every `retryMs`, and names embed a per-acquisition random
+ * token so they are never reused (no identity switch on unlink).
+ *
+ * Residual (documented, not fixable without OS-level flock, which Node core
+ * does not expose): a HOLDER frozen inside `fn` for longer than `staleMs`
+ * looks crashed, gets evicted, and the next head may overlap it — `fn` is a
+ * millisecond-scale sync config write, 400× within margin. Freezes anywhere
+ * else (mid-choosing, at entry) are safe: the atomic renames fail after an
+ * eviction and the process re-enqueues. On `waitMs` timeout
+ * the mutation proceeds without the lock (warn) — blocking would wedge
+ * bridge startup. The lock coordinates bridge processes only; codex itself
+ * does not observe it, which is why bridge writes to a shared config are
+ * additionally kept rare (the trust write is a no-op after the first boot
+ * per workspace, and runtime_auth agents never write the provider block)
+ * and whole-file writes are atomic (temp + rename) so codex never reads a
+ * truncated file.
+ *
+ * Exported for tests.
+ */
+export function withConfigLock(codexHome, log, fn) {
+    const queueDir = path.join(codexHome, 'config.toml.lock.d');
+    let ticketName = bakeryEnqueue(queueDir);
+    let ticketPath = ticketName ? path.join(queueDir, ticketName) : '';
+    let acquired = false;
+    let heldPath = '';
+    const deadline = Date.now() + CONFIG_LOCK_TIMINGS.waitMs;
+    while (ticketName && Date.now() < deadline) {
+        let names;
+        try {
+            names = fs.readdirSync(queueDir).sort();
+        }
+        catch {
+            break; // dir vanished under us — lockless fallback
+        }
+        if (!names.includes(ticketName)) {
+            // Our ticket was GC'd (we looked frozen) or wiped — re-run the full
+            // bakery enqueue rather than silently proceeding without a position.
+            ticketName = bakeryEnqueue(queueDir);
+            if (!ticketName)
+                break;
+            ticketPath = path.join(queueDir, ticketName);
+            continue;
+        }
+        const now = Date.now();
+        let rescan = false; // snapshot invalidated — re-readdir before electing
+        let blocked = false; // a live chooser/holder is ahead of us
+        let head;
+        for (const name of names) {
+            const entryPath = path.join(queueDir, name);
+            if (name.startsWith('held-')) {
+                // The holder's freshness is embedded in the name at entry time
+                // (atomic with the entry rename), so there is no stat window here.
+                const enteredAt = Number.parseInt(name.slice(5, 20), 10);
+                if (Number.isFinite(enteredAt) && now - enteredAt > CONFIG_LOCK_TIMINGS.staleMs) {
+                    // Holder frozen inside fn beyond staleMs — the documented
+                    // residual. Evict and rescan.
+                    try {
+                        fs.unlinkSync(entryPath);
+                    }
+                    catch {
+                        // released or GC'd concurrently
+                    }
+                    rescan = true;
+                    break;
+                }
+                blocked = true; // live holder — the lock is taken
+                break;
+            }
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(entryPath).mtimeMs;
+            }
+            catch {
+                // The entry vanished between readdir and stat — it did not merely
+                // leave, it may have TRANSITIONED via an atomic rename this snapshot
+                // cannot see: a choosing marker into a published ticket, or a head
+                // ticket into a live held entry (caught overlapping under the
+                // 12-process barrier test when this path skipped tickets). Never
+                // elect from a snapshot that missed a transition — rescan.
+                rescan = true;
+                break;
+            }
+            if (now - mtimeMs > CONFIG_LOCK_TIMINGS.staleMs) {
+                // Crashed contender (live ones refresh every retryMs; choosing is
+                // microsecond-scale). Unique never-reused names make this unlink
+                // safe — it cannot hit a different file than the one just observed.
+                try {
+                    fs.unlinkSync(entryPath);
+                }
+                catch {
+                    // Lost to a concurrent GC — or to the owner's atomic rename
+                    // (marker → ticket publish, or ticket → held entry).
+                }
+                // Whether the unlink won or lost, the snapshot no longer reflects
+                // the queue (a stale marker may have become a live ticket) — rescan
+                // instead of electing from stale names.
+                rescan = true;
+                break;
+            }
+            // Sorted names put `choosing-*` before `held-*` before `t-*`, so
+            // blockers are seen before any head candidate.
+            if (name.startsWith('choosing-')) {
+                blocked = true;
+                break;
+            }
+            if (name.startsWith('t-')) {
+                head = name;
+                break;
+            }
+            // Foreign file in the queue dir — ignore it.
+        }
+        if (rescan)
+            continue; // GC/publish made progress; take a fresh snapshot
+        if (!blocked && head === ticketName) {
+            // ENTRY is an atomic rename of our own ticket into a `held-<now>-…`
+            // entry. It races any GC eviction of the ticket on the same path, so
+            // exactly one side wins: if a GC saw us stale at the boundary and
+            // evicted first, our rename fails and we re-enqueue instead of
+            // entering — a revived contender can never slip into the critical
+            // section behind an eviction. The entry timestamp rides in the name,
+            // atomic with the transition itself.
+            CONFIG_LOCK_TEST_HOOKS.beforeTicketEntry?.();
+            const heldName = `held-${String(Date.now()).padStart(15, '0')}-${ticketName.slice(2)}`;
+            const candidateHeldPath = path.join(queueDir, heldName);
+            try {
+                fs.renameSync(ticketPath, candidateHeldPath);
+            }
+            catch {
+                continue; // evicted at the boundary — the missing-ticket branch re-enqueues
+            }
+            heldPath = candidateHeldPath;
+            acquired = true;
+            break;
+        }
+        try {
+            const t = new Date();
+            fs.utimesSync(ticketPath, t, t); // keep our ticket visibly live
+        }
+        catch {
+            // ticket missing — the next iteration re-enqueues
+        }
+        sleepSync(CONFIG_LOCK_TIMINGS.retryMs);
+    }
+    if (!acquired) {
+        log?.warn(`could not acquire ${queueDir}; writing config.toml without lock`);
+        // Leave the queue before writing lockless so our abandoned ticket does
+        // not block other contenders for another staleMs.
+        if (ticketName) {
+            try {
+                fs.unlinkSync(ticketPath);
+            }
+            catch {
+                // already GC'd
+            }
+        }
+    }
+    try {
+        fn();
+    }
+    finally {
+        if (acquired) {
+            try {
+                fs.unlinkSync(heldPath); // own unique name — no identity race
+            }
+            catch {
+                // evicted by a contender that saw us frozen inside fn — nothing to release
+            }
+            // The queue dir is deliberately NEVER removed: a contender may have
+            // finished mkdir but not yet created its choosing marker, and
+            // deleting the dir in that gap would send it down the lockless
+            // fallback. An empty config.toml.lock.d on disk is expected.
+        }
+    }
+}
+/**
+ * Test-only scheduling hooks for deterministic race tests. Production code
+ * never sets these; tests use them to pause a contender at the two points
+ * where another process can act in between (barrier files stand in for the
+ * OS scheduler).
+ */
+export const CONFIG_LOCK_TEST_HOOKS = {};
+/**
+ * Bakery enqueue: announce with a choosing marker, take
+ * seq = max(visible tickets) + 1, then PUBLISH BY RENAMING THE MARKER INTO
+ * THE TICKET. The rename is the linchpin against the stale-mid-choosing
+ * race: if this process froze after creating the marker and a contender
+ * GC'd it as stale (allowing others to elect and enter), the rename fails
+ * with ENOENT — the stale seq is discarded and we re-enqueue under a fresh
+ * token. Publishing and retiring the marker are one atomic step, so at no
+ * instant can an evaluator observe "no marker, and no ticket either" for an
+ * in-flight enqueue.
+ *
+ * Returns the ticket name, or null when the queue dir is unusable (caller
+ * falls back to a lockless warn-logged write).
+ */
+function bakeryEnqueue(queueDir) {
+    // A GC'd marker aborts the attempt; retry under a FRESH token so names
+    // are never reused. Being GC'd requires a >staleMs freeze mid-choosing,
+    // so two spare attempts are already generous.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const token = `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+        const markerPath = path.join(queueDir, `choosing-${token}`);
+        try {
+            fs.mkdirSync(queueDir, { recursive: true });
+            CONFIG_LOCK_TEST_HOOKS.beforeChoosingMarker?.();
+            fs.writeFileSync(markerPath, '', { flag: 'wx' });
+        }
+        catch {
+            return null;
+        }
+        try {
+            let maxSeq = 0;
+            for (const name of fs.readdirSync(queueDir)) {
+                if (!name.startsWith('t-'))
+                    continue;
+                const seq = Number.parseInt(name.slice(2, 12), 10);
+                if (Number.isFinite(seq) && seq > maxSeq)
+                    maxSeq = seq;
+            }
+            const ticketName = `t-${String(maxSeq + 1).padStart(10, '0')}-${token}`;
+            const ticketPath = path.join(queueDir, ticketName);
+            CONFIG_LOCK_TEST_HOOKS.beforeTicketPublish?.();
+            fs.renameSync(markerPath, ticketPath);
+            try {
+                // The ticket inherits the marker's mtime; refresh it so a slow
+                // choose does not hand evaluators a stale-at-birth ticket. Runs
+                // before our first head evaluation, so if a GC wins the race on the
+                // stale-born ticket we simply re-enqueue — never elect on it.
+                const t = new Date();
+                fs.utimesSync(ticketPath, t, t);
+            }
+            catch {
+                // GC'd already — the eval loop re-enqueues on the missing ticket.
+            }
+            return ticketName;
+        }
+        catch (err) {
+            // Retire our marker if it still exists (e.g. readdir failed).
+            try {
+                fs.unlinkSync(markerPath);
+            }
+            catch {
+                // already renamed or GC'd
+            }
+            if (err.code === 'ENOENT')
+                continue; // marker GC'd — fresh token
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Whole-file config writes go through temp + rename so a concurrent reader
+ * (including codex itself, which does not observe the advisory lock) never
+ * sees a truncated file. The trust-append path intentionally keeps
+ * appendFileSync — O_APPEND is atomic for these small writes and cannot
+ * clobber a concurrent append.
+ *
+ * The rename targets the file's REAL path: `config.toml` managed by a
+ * dotfiles setup is often a symlink, and renaming onto the link path would
+ * replace the link with a regular file while the real target keeps the old
+ * content. The temp file is born 0600 (never a world-readable window, even
+ * pre-chmod) and created with `wx` so a colliding path is never truncated;
+ * an existing file's mode is then restored explicitly (chmod, not
+ * open-mode, so umask cannot mask bits off), while a brand-new config stays
+ * at the restrictive 0600.
+ */
+function writeConfigAtomic(filePath, content) {
+    const realPath = resolveWriteTarget(filePath);
+    let mode;
+    try {
+        mode = fs.statSync(realPath).mode & 0o777;
+    }
+    catch {
+        // New file — keep the restrictive 0600 creation mode.
+    }
+    const tmpPath = `${realPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    let tmpCreated = false;
+    try {
+        fs.writeFileSync(tmpPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        tmpCreated = true;
+        if (mode !== undefined)
+            fs.chmodSync(tmpPath, mode);
+        fs.renameSync(tmpPath, realPath);
+    }
+    catch (err) {
+        // Clean up only what THIS call put on disk: on a wx EEXIST the path
+        // belongs to someone else and must not be unlinked. (A create that
+        // failed mid-write still left our file — code ≠ EEXIST — so it is
+        // removed.)
+        if (tmpCreated || err.code !== 'EEXIST') {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // tmp never made it to disk
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Follow symlinks (including dangling ones) to the path a write should land
+ * on. Never returns an unresolved symlink: a cycle or an over-deep chain
+ * throws instead, so the atomic rename can never silently replace a link.
+ */
+function resolveWriteTarget(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch (err) {
+        // ELOOP (cycle among existing links) and every other real error must
+        // surface; only a missing target falls through to the manual walk.
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    // Some component is missing — the path may still be a dangling symlink
+    // chain; walk it manually so the file is created where the links point.
+    const seen = new Set();
+    let p = path.resolve(filePath);
+    for (let depth = 0; depth < 40; depth++) {
+        if (seen.has(p)) {
+            throw new Error(`symlink cycle at ${p} while resolving ${filePath}`);
+        }
+        seen.add(p);
+        let link;
+        try {
+            link = fs.readlinkSync(p);
+        }
+        catch (err) {
+            const code = err.code;
+            // ENOENT (nothing here yet) and EINVAL (a real non-link file) are the
+            // two legitimate ends of a chain — create/replace at this path. Any
+            // other error is a real failure and must surface.
+            if (code === 'ENOENT' || code === 'EINVAL')
+                return p;
+            throw err;
+        }
+        p = path.resolve(path.dirname(p), link);
+    }
+    throw new Error(`symlink chain deeper than 40 while resolving ${filePath}`);
+}
 /**
  * Ensure the workspace directory is marked as trusted in the global Codex
  * config so that project-level `developer_instructions` are loaded at
@@ -13,6 +413,9 @@ import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, bui
  * the bridge from starting.
  */
 export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
+    withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
+}
+function ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log) {
     const configPath = path.join(codexHome, 'config.toml');
     const normalizedPath = path.resolve(workspaceDir);
     try {
@@ -37,8 +440,17 @@ export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
             }
         }
         const projects = parsed?.projects;
-        if (projects?.[normalizedPath]?.trust_level === 'trusted')
+        const existingTrust = projects?.[normalizedPath]?.trust_level;
+        if (existingTrust === 'trusted')
             return;
+        if (existingTrust !== undefined) {
+            // An explicit non-trusted value is a human decision — on a local
+            // runtime_auth daemon this file IS the operator's own ~/.codex config,
+            // and a workspace they deliberately marked untrusted must never be
+            // silently flipped by an agent. Leave it and surface the consequence.
+            log?.warn(`Codex config marks ${normalizedPath} as trust_level=${JSON.stringify(existingTrust)}; respecting the explicit decision — project-level developer_instructions will not load for this workspace`);
+            return;
+        }
         // TOML basic-string keys require backslash and double-quote escaping.
         const escapedPath = normalizedPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
         const sectionHeader = `[projects."${escapedPath}"]`;
@@ -68,7 +480,7 @@ export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
                         content.substring(0, afterHeader) + trustLine + '\n' + content.substring(afterHeader);
                 }
             }
-            fs.writeFileSync(configPath, content, 'utf8');
+            writeConfigAtomic(configPath, content);
         }
         else if (projects?.[normalizedPath] !== undefined) {
             // smol-toml found the section but indexOf missed it — the header
@@ -119,6 +531,9 @@ export function isParallProxyMode(env = process.env) {
  * Provider-managed: overwritten on every boot (env vars are the SSOT).
  */
 export function ensureParallProvider(codexHome, apiUrl, log) {
+    withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+}
+function ensureParallProviderLocked(codexHome, apiUrl) {
     const configPath = path.join(codexHome, 'config.toml');
     const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
     try {
@@ -158,7 +573,7 @@ export function ensureParallProvider(codexHome, apiUrl, log) {
             content = content.trimEnd() + '\n\n' + providerBlock + '\n';
         }
         fs.mkdirSync(codexHome, { recursive: true });
-        fs.writeFileSync(configPath, content, 'utf8');
+        writeConfigAtomic(configPath, content);
     }
     catch (err) {
         throw new Error(`failed to write Parall provider config: ${String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.42.0",
+  "version": "1.42.1",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "smol-toml": "^1.6.1",
-    "@parall/agent-core": "1.42.0",
-    "@parall/cli": "1.42.0",
-    "@parall/sdk": "1.42.0"
+    "@parall/agent-core": "1.42.1",
+    "@parall/cli": "1.42.1",
+    "@parall/sdk": "1.42.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/workspace.ts

@@ -11,6 +11,399 @@ import {
 } from '@parall/agent-core';
 import type { AgentIdentity } from '@parall/agent-core';
 
+/**
+ * Config-lock timings, exported for tests.
+ *
+ * `staleMs` — a queue ticket untouched this long is treated as a crashed
+ * owner (live contenders refresh their ticket's mtime every `retryMs`, so
+ * the margin is ~400×). `waitMs` deliberately exceeds `staleMs`: a waiter
+ * facing a crashed head-of-queue outlasts the staleness threshold and skips
+ * it instead of falling through to a lockless write — the lockless fallback
+ * is a last resort, not a normal path.
+ */
+export const CONFIG_LOCK_TIMINGS = {
+  staleMs: 10_000,
+  waitMs: 15_000,
+  retryMs: 25,
+};
+
+// Reused wait signal: sleepSync fires every retryMs under contention, and a
+// fresh SharedArrayBuffer per call is avoidable allocation churn.
+const SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
+
+function sleepSync(ms: number): void {
+  Atomics.wait(SLEEP_SIGNAL, 0, 0, ms);
+}
+
+/**
+ * Advisory cross-process lock serializing `<codexHome>/config.toml`
+ * read-modify-write. On a local daemon machine every runtime_auth codex
+ * bridge child shares the operator's CODEX_HOME, and the daemon starts them
+ * together — without a lock, a whole-file rewrite working from a stale read
+ * can erase a trust entry another agent appended in between.
+ *
+ * Queue design (why not wx-create + steal): any scheme that renames or
+ * unlinks the SHARED lock path can, between its staleness check and the
+ * destructive op, hit a fresh lock that replaced the stale one — deleting a
+ * live holder's lock and overlapping critical sections (reproduced under
+ * 12-process contention). Here contenders queue in `config.toml.lock.d/`
+ * using Lamport's bakery protocol, and the smallest live ticket holds the
+ * lock. Two phases per enqueue: (1) create a `choosing-<token>` marker,
+ * (2) take seq = max(existing ticket seqs) + 1 and publish by atomically
+ * RENAMING the marker into `t-<seq>-<token>`. Evaluators wait while any
+ * live choosing marker exists, so a contender that read the queue but
+ * hasn't published yet can never be missed — the classic bakery guarantee.
+ * (A naive self-chosen timestamp order would race: a process descheduled
+ * between choosing its stamp and writing its ticket could insert itself
+ * before an already-running holder.) The rename-publish closes the
+ * stale-mid-choosing hole: once a frozen chooser's marker has been GC'd,
+ * its publish fails and it must re-enqueue fresh — it can never surface an
+ * old low seq under a holder elected in its absence. ENTRY is the same
+ * pattern: the elected head atomically renames its ticket into a
+ * `held-<entry-ts>-…` entry, racing any staleness eviction of that ticket
+ * on the same path — a contender revived at the staleness boundary loses
+ * the rename and re-enqueues rather than entering behind an eviction. The
+ * holder's freshness is embedded in the held name (atomic with entry), so
+ * evicting a holder needs no stat. Evaluators mirror the atomicity: after
+ * any GC attempt, or on a marker that vanished mid-scan, they take a fresh
+ * snapshot instead of electing from the old one. Ticket order is
+ * (seq, token), identical for every observer.
+ *
+ * No process ever mutates a shared path: release unlinks only the caller's
+ * own ticket, and the only cross-process destructive op is GC of entries
+ * untouched for `staleMs` — safe because live contenders refresh their
+ * ticket's mtime every `retryMs`, and names embed a per-acquisition random
+ * token so they are never reused (no identity switch on unlink).
+ *
+ * Residual (documented, not fixable without OS-level flock, which Node core
+ * does not expose): a HOLDER frozen inside `fn` for longer than `staleMs`
+ * looks crashed, gets evicted, and the next head may overlap it — `fn` is a
+ * millisecond-scale sync config write, 400× within margin. Freezes anywhere
+ * else (mid-choosing, at entry) are safe: the atomic renames fail after an
+ * eviction and the process re-enqueues. On `waitMs` timeout
+ * the mutation proceeds without the lock (warn) — blocking would wedge
+ * bridge startup. The lock coordinates bridge processes only; codex itself
+ * does not observe it, which is why bridge writes to a shared config are
+ * additionally kept rare (the trust write is a no-op after the first boot
+ * per workspace, and runtime_auth agents never write the provider block)
+ * and whole-file writes are atomic (temp + rename) so codex never reads a
+ * truncated file.
+ *
+ * Exported for tests.
+ */
+export function withConfigLock(
+  codexHome: string,
+  log: { warn: (msg: string) => void } | undefined,
+  fn: () => void,
+): void {
+  const queueDir = path.join(codexHome, 'config.toml.lock.d');
+
+  let ticketName = bakeryEnqueue(queueDir);
+  let ticketPath = ticketName ? path.join(queueDir, ticketName) : '';
+
+  let acquired = false;
+  let heldPath = '';
+  const deadline = Date.now() + CONFIG_LOCK_TIMINGS.waitMs;
+  while (ticketName && Date.now() < deadline) {
+    let names: string[];
+    try {
+      names = fs.readdirSync(queueDir).sort();
+    } catch {
+      break; // dir vanished under us — lockless fallback
+    }
+    if (!names.includes(ticketName)) {
+      // Our ticket was GC'd (we looked frozen) or wiped — re-run the full
+      // bakery enqueue rather than silently proceeding without a position.
+      ticketName = bakeryEnqueue(queueDir);
+      if (!ticketName) break;
+      ticketPath = path.join(queueDir, ticketName);
+      continue;
+    }
+    const now = Date.now();
+    let rescan = false; // snapshot invalidated — re-readdir before electing
+    let blocked = false; // a live chooser/holder is ahead of us
+    let head: string | undefined;
+    for (const name of names) {
+      const entryPath = path.join(queueDir, name);
+      if (name.startsWith('held-')) {
+        // The holder's freshness is embedded in the name at entry time
+        // (atomic with the entry rename), so there is no stat window here.
+        const enteredAt = Number.parseInt(name.slice(5, 20), 10);
+        if (Number.isFinite(enteredAt) && now - enteredAt > CONFIG_LOCK_TIMINGS.staleMs) {
+          // Holder frozen inside fn beyond staleMs — the documented
+          // residual. Evict and rescan.
+          try {
+            fs.unlinkSync(entryPath);
+          } catch {
+            // released or GC'd concurrently
+          }
+          rescan = true;
+          break;
+        }
+        blocked = true; // live holder — the lock is taken
+        break;
+      }
+      let mtimeMs: number;
+      try {
+        mtimeMs = fs.statSync(entryPath).mtimeMs;
+      } catch {
+        // The entry vanished between readdir and stat — it did not merely
+        // leave, it may have TRANSITIONED via an atomic rename this snapshot
+        // cannot see: a choosing marker into a published ticket, or a head
+        // ticket into a live held entry (caught overlapping under the
+        // 12-process barrier test when this path skipped tickets). Never
+        // elect from a snapshot that missed a transition — rescan.
+        rescan = true;
+        break;
+      }
+      if (now - mtimeMs > CONFIG_LOCK_TIMINGS.staleMs) {
+        // Crashed contender (live ones refresh every retryMs; choosing is
+        // microsecond-scale). Unique never-reused names make this unlink
+        // safe — it cannot hit a different file than the one just observed.
+        try {
+          fs.unlinkSync(entryPath);
+        } catch {
+          // Lost to a concurrent GC — or to the owner's atomic rename
+          // (marker → ticket publish, or ticket → held entry).
+        }
+        // Whether the unlink won or lost, the snapshot no longer reflects
+        // the queue (a stale marker may have become a live ticket) — rescan
+        // instead of electing from stale names.
+        rescan = true;
+        break;
+      }
+      // Sorted names put `choosing-*` before `held-*` before `t-*`, so
+      // blockers are seen before any head candidate.
+      if (name.startsWith('choosing-')) {
+        blocked = true;
+        break;
+      }
+      if (name.startsWith('t-')) {
+        head = name;
+        break;
+      }
+      // Foreign file in the queue dir — ignore it.
+    }
+    if (rescan) continue; // GC/publish made progress; take a fresh snapshot
+    if (!blocked && head === ticketName) {
+      // ENTRY is an atomic rename of our own ticket into a `held-<now>-…`
+      // entry. It races any GC eviction of the ticket on the same path, so
+      // exactly one side wins: if a GC saw us stale at the boundary and
+      // evicted first, our rename fails and we re-enqueue instead of
+      // entering — a revived contender can never slip into the critical
+      // section behind an eviction. The entry timestamp rides in the name,
+      // atomic with the transition itself.
+      CONFIG_LOCK_TEST_HOOKS.beforeTicketEntry?.();
+      const heldName = `held-${String(Date.now()).padStart(15, '0')}-${ticketName.slice(2)}`;
+      const candidateHeldPath = path.join(queueDir, heldName);
+      try {
+        fs.renameSync(ticketPath, candidateHeldPath);
+      } catch {
+        continue; // evicted at the boundary — the missing-ticket branch re-enqueues
+      }
+      heldPath = candidateHeldPath;
+      acquired = true;
+      break;
+    }
+    try {
+      const t = new Date();
+      fs.utimesSync(ticketPath, t, t); // keep our ticket visibly live
+    } catch {
+      // ticket missing — the next iteration re-enqueues
+    }
+    sleepSync(CONFIG_LOCK_TIMINGS.retryMs);
+  }
+
+  if (!acquired) {
+    log?.warn(`could not acquire ${queueDir}; writing config.toml without lock`);
+    // Leave the queue before writing lockless so our abandoned ticket does
+    // not block other contenders for another staleMs.
+    if (ticketName) {
+      try {
+        fs.unlinkSync(ticketPath);
+      } catch {
+        // already GC'd
+      }
+    }
+  }
+  try {
+    fn();
+  } finally {
+    if (acquired) {
+      try {
+        fs.unlinkSync(heldPath); // own unique name — no identity race
+      } catch {
+        // evicted by a contender that saw us frozen inside fn — nothing to release
+      }
+      // The queue dir is deliberately NEVER removed: a contender may have
+      // finished mkdir but not yet created its choosing marker, and
+      // deleting the dir in that gap would send it down the lockless
+      // fallback. An empty config.toml.lock.d on disk is expected.
+    }
+  }
+}
+
+/**
+ * Test-only scheduling hooks for deterministic race tests. Production code
+ * never sets these; tests use them to pause a contender at the two points
+ * where another process can act in between (barrier files stand in for the
+ * OS scheduler).
+ */
+export const CONFIG_LOCK_TEST_HOOKS: {
+  beforeChoosingMarker?: () => void;
+  beforeTicketPublish?: () => void;
+  beforeTicketEntry?: () => void;
+} = {};
+
+/**
+ * Bakery enqueue: announce with a choosing marker, take
+ * seq = max(visible tickets) + 1, then PUBLISH BY RENAMING THE MARKER INTO
+ * THE TICKET. The rename is the linchpin against the stale-mid-choosing
+ * race: if this process froze after creating the marker and a contender
+ * GC'd it as stale (allowing others to elect and enter), the rename fails
+ * with ENOENT — the stale seq is discarded and we re-enqueue under a fresh
+ * token. Publishing and retiring the marker are one atomic step, so at no
+ * instant can an evaluator observe "no marker, and no ticket either" for an
+ * in-flight enqueue.
+ *
+ * Returns the ticket name, or null when the queue dir is unusable (caller
+ * falls back to a lockless warn-logged write).
+ */
+function bakeryEnqueue(queueDir: string): string | null {
+  // A GC'd marker aborts the attempt; retry under a FRESH token so names
+  // are never reused. Being GC'd requires a >staleMs freeze mid-choosing,
+  // so two spare attempts are already generous.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const token = `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    const markerPath = path.join(queueDir, `choosing-${token}`);
+    try {
+      fs.mkdirSync(queueDir, { recursive: true });
+      CONFIG_LOCK_TEST_HOOKS.beforeChoosingMarker?.();
+      fs.writeFileSync(markerPath, '', { flag: 'wx' });
+    } catch {
+      return null;
+    }
+    try {
+      let maxSeq = 0;
+      for (const name of fs.readdirSync(queueDir)) {
+        if (!name.startsWith('t-')) continue;
+        const seq = Number.parseInt(name.slice(2, 12), 10);
+        if (Number.isFinite(seq) && seq > maxSeq) maxSeq = seq;
+      }
+      const ticketName = `t-${String(maxSeq + 1).padStart(10, '0')}-${token}`;
+      const ticketPath = path.join(queueDir, ticketName);
+      CONFIG_LOCK_TEST_HOOKS.beforeTicketPublish?.();
+      fs.renameSync(markerPath, ticketPath);
+      try {
+        // The ticket inherits the marker's mtime; refresh it so a slow
+        // choose does not hand evaluators a stale-at-birth ticket. Runs
+        // before our first head evaluation, so if a GC wins the race on the
+        // stale-born ticket we simply re-enqueue — never elect on it.
+        const t = new Date();
+        fs.utimesSync(ticketPath, t, t);
+      } catch {
+        // GC'd already — the eval loop re-enqueues on the missing ticket.
+      }
+      return ticketName;
+    } catch (err) {
+      // Retire our marker if it still exists (e.g. readdir failed).
+      try {
+        fs.unlinkSync(markerPath);
+      } catch {
+        // already renamed or GC'd
+      }
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue; // marker GC'd — fresh token
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Whole-file config writes go through temp + rename so a concurrent reader
+ * (including codex itself, which does not observe the advisory lock) never
+ * sees a truncated file. The trust-append path intentionally keeps
+ * appendFileSync — O_APPEND is atomic for these small writes and cannot
+ * clobber a concurrent append.
+ *
+ * The rename targets the file's REAL path: `config.toml` managed by a
+ * dotfiles setup is often a symlink, and renaming onto the link path would
+ * replace the link with a regular file while the real target keeps the old
+ * content. The temp file is born 0600 (never a world-readable window, even
+ * pre-chmod) and created with `wx` so a colliding path is never truncated;
+ * an existing file's mode is then restored explicitly (chmod, not
+ * open-mode, so umask cannot mask bits off), while a brand-new config stays
+ * at the restrictive 0600.
+ */
+function writeConfigAtomic(filePath: string, content: string): void {
+  const realPath = resolveWriteTarget(filePath);
+  let mode: number | undefined;
+  try {
+    mode = fs.statSync(realPath).mode & 0o777;
+  } catch {
+    // New file — keep the restrictive 0600 creation mode.
+  }
+  const tmpPath = `${realPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  let tmpCreated = false;
+  try {
+    fs.writeFileSync(tmpPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    tmpCreated = true;
+    if (mode !== undefined) fs.chmodSync(tmpPath, mode);
+    fs.renameSync(tmpPath, realPath);
+  } catch (err) {
+    // Clean up only what THIS call put on disk: on a wx EEXIST the path
+    // belongs to someone else and must not be unlinked. (A create that
+    // failed mid-write still left our file — code ≠ EEXIST — so it is
+    // removed.)
+    if (tmpCreated || (err as NodeJS.ErrnoException).code !== 'EEXIST') {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // tmp never made it to disk
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Follow symlinks (including dangling ones) to the path a write should land
+ * on. Never returns an unresolved symlink: a cycle or an over-deep chain
+ * throws instead, so the atomic rename can never silently replace a link.
+ */
+function resolveWriteTarget(filePath: string): string {
+  try {
+    return fs.realpathSync(filePath);
+  } catch (err) {
+    // ELOOP (cycle among existing links) and every other real error must
+    // surface; only a missing target falls through to the manual walk.
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+  // Some component is missing — the path may still be a dangling symlink
+  // chain; walk it manually so the file is created where the links point.
+  const seen = new Set<string>();
+  let p = path.resolve(filePath);
+  for (let depth = 0; depth < 40; depth++) {
+    if (seen.has(p)) {
+      throw new Error(`symlink cycle at ${p} while resolving ${filePath}`);
+    }
+    seen.add(p);
+    let link: string;
+    try {
+      link = fs.readlinkSync(p);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // ENOENT (nothing here yet) and EINVAL (a real non-link file) are the
+      // two legitimate ends of a chain — create/replace at this path. Any
+      // other error is a real failure and must surface.
+      if (code === 'ENOENT' || code === 'EINVAL') return p;
+      throw err;
+    }
+    p = path.resolve(path.dirname(p), link);
+  }
+  throw new Error(`symlink chain deeper than 40 while resolving ${filePath}`);
+}
+
 /**
  * Ensure the workspace directory is marked as trusted in the global Codex
  * config so that project-level `developer_instructions` are loaded at
@@ -25,6 +418,14 @@ export function ensureWorkspaceTrusted(
   codexHome: string,
   workspaceDir: string,
   log?: { warn: (msg: string) => void },
+): void {
+  withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
+}
+
+function ensureWorkspaceTrustedLocked(
+  codexHome: string,
+  workspaceDir: string,
+  log?: { warn: (msg: string) => void },
 ): void {
   const configPath = path.join(codexHome, 'config.toml');
   const normalizedPath = path.resolve(workspaceDir);
@@ -52,7 +453,20 @@ export function ensureWorkspaceTrusted(
     }
 
     const projects = parsed?.projects as Record<string, Record<string, unknown>> | undefined;
-    if (projects?.[normalizedPath]?.trust_level === 'trusted') return;
+    const existingTrust = projects?.[normalizedPath]?.trust_level;
+    if (existingTrust === 'trusted') return;
+    if (existingTrust !== undefined) {
+      // An explicit non-trusted value is a human decision — on a local
+      // runtime_auth daemon this file IS the operator's own ~/.codex config,
+      // and a workspace they deliberately marked untrusted must never be
+      // silently flipped by an agent. Leave it and surface the consequence.
+      log?.warn(
+        `Codex config marks ${normalizedPath} as trust_level=${JSON.stringify(
+          existingTrust,
+        )}; respecting the explicit decision — project-level developer_instructions will not load for this workspace`,
+      );
+      return;
+    }
 
     // TOML basic-string keys require backslash and double-quote escaping.
     const escapedPath = normalizedPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
@@ -82,7 +496,7 @@ export function ensureWorkspaceTrusted(
             content.substring(0, afterHeader) + trustLine + '\n' + content.substring(afterHeader);
         }
       }
-      fs.writeFileSync(configPath, content, 'utf8');
+      writeConfigAtomic(configPath, content);
     } else if (projects?.[normalizedPath] !== undefined) {
       // smol-toml found the section but indexOf missed it — the header
       // uses non-canonical TOML formatting. Appending would create a
@@ -138,6 +552,10 @@ export function ensureParallProvider(
   apiUrl: string,
   log?: { warn: (msg: string) => void },
 ): void {
+  withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+}
+
+function ensureParallProviderLocked(codexHome: string, apiUrl: string): void {
   const configPath = path.join(codexHome, 'config.toml');
   const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
 
@@ -178,7 +596,7 @@ export function ensureParallProvider(
     }
 
     fs.mkdirSync(codexHome, { recursive: true });
-    fs.writeFileSync(configPath, content, 'utf8');
+    writeConfigAtomic(configPath, content);
   } catch (err) {
     throw new Error(`failed to write Parall provider config: ${String(err)}`);
   }