A local-first multi-agent app development platform, built on PenguinHarness
/**
* Per-file serialization for the file-writing tools (edit_file / write_file).
*
* Both tools are a read-modify-write: stat the file, read its content, compute the new
* content, replace it with a temp file + rename. The rename makes the replacement itself
* indivisible, but nothing guards the sequence around it — and the engine runs a turn's
* approved tool calls concurrently, as do subagents sharing this process. Two edits of one
* file therefore both read the original bytes, both compute from them, and the later rename
* wins: one edit is silently lost while both calls report success. A process-wide mutex
* keyed by the file turns the whole read-modify-write into one critical section, so a later
* writer reads what the earlier one landed, and an `old_string` the earlier edit removed
* fails to match instead of overwriting it.
*
* The scope is this process only. No OS-level file lock is taken, so another process writing
* the same file — a separate CLI run, an editor, the user's own shell — is not serialized
* against these tools; there the atomic rename remains the whole guarantee, and a reader
* sees the old bytes or the new ones but never a mix. Reads are not locked for the same
* reason.
*/
import path from "node:path";
import { realpath } from "node:fs/promises";
/**
* One key's queue: the promise a newly arriving caller waits behind, and how many callers
* have entered it without leaving yet — the holder plus everyone queued. The count is what
* says when the entry can go: it reaches zero only once nobody is inside the critical
* section and nobody is waiting to be, which a settled tail alone would not tell us.
*/
interface LockChain {
tail: Promise<void>;
callers: number;
}
const chains = new Map<string, LockChain>();
/**
* The mutex key for an already-resolved path: its real path, so every name for one file
* folds onto one key — a symlink and the file it points at, a path crossing a linked
* directory, `a/../a/x.txt` and `a/x.txt`.
*
* A path that does not exist yet keys on its deepest real ancestor plus the segments below
* it, so a `write_file` that creates the file and an `edit_file` that follows share one key.
* Stopping at the immediate parent is not enough: `write_file` creates missing parent
* directories, so the directory a file will live in is itself routinely still absent when the
* key is taken, and an unresolved name would put the creating call on a different key from
* every call that follows it wherever the Workspace is reached through a link (on macOS every
* temporary directory is, via `/var` → `/private/var`). A resolution failure is absorbed
* rather than raised: a lock key is no place to report an errno — the tool's own stat, read or
* write reports it, in the wording the model reads — so a path that cannot be resolved at all
* (a link cycle) still keys on the real directory holding it. The worst case is a key nothing
* else shares, which is exactly the unserialized behaviour that preceded the lock.
*/
export async function fileLockKey(resolvedPath: string): Promise<string> {
try {
return await realpath(resolvedPath);
} catch {
// Nothing there yet (ENOENT/ENOTDIR), or a path that cannot be resolved at all.
}
const below = [path.basename(resolvedPath)];
let ancestor = path.dirname(resolvedPath);
for (;;) {
try {
return path.join(await realpath(ancestor), ...below);
} catch {
const parent = path.dirname(ancestor);
// dirname is a fixpoint at the root, where there is nothing left to fold onto.
if (parent === ancestor) return path.resolve(resolvedPath);
below.unshift(path.basename(ancestor));
ancestor = parent;
}
}
}
/** The rejection a queued caller gets when its signal fires before its turn arrives. */
function abortError(): Error {
// Named the way Node's own aborted fs calls name it, which is what the tools classify on.
const err = new Error("The operation was aborted");
err.name = "AbortError";
return err;
}
/**
* Waits for `ahead` to drain, or rejects as soon as `signal` fires.
*
* `ahead` is settled with `resolve` on both outcomes: a predecessor's failure is its own
* caller's business and must not deny the next caller its turn.
*/
async function waitForTurn(ahead: Promise<void>, signal?: AbortSignal): Promise<void> {
if (signal === undefined) {
await ahead;
return;
}
if (signal.aborted) throw abortError();
let onAbort: () => void = () => undefined;
try {
await new Promise<void>((resolve, reject) => {
onAbort = (): void => reject(abortError());
signal.addEventListener("abort", onAbort, { once: true });
void ahead.then(resolve, resolve);
});
} finally {
signal.removeEventListener("abort", onAbort);
}
}
/**
* Runs `fn` with exclusive hold of `key`, callers served in arrival order.
*
* A caller whose `signal` fires while it is still queued rejects with an `AbortError` and
* never runs `fn` — its slot collapses and the callers behind it move up. A rejection from
* `fn` propagates to its own caller and nothing else: the queue is released from a `finally`
* and the next caller runs regardless. The key's entry is removed once the last caller in
* its queue is done, so a long-lived process does not accumulate one entry per file it has
* ever written.
*/
export async function withFileLock<T>(
key: string,
fn: () => Promise<T>,
signal?: AbortSignal,
): Promise<T> {
let chain = chains.get(key);
if (chain === undefined) {
chain = { tail: Promise.resolve(), callers: 0 };
chains.set(key, chain);
}
chain.callers += 1;
const ahead = chain.tail;
let finish: () => void = () => undefined;
const turn = new Promise<void>((resolve) => {
finish = resolve;
});
// The new tail: everything already queued, then this call's own turn. `turn` only ever
// resolves, so the chain cannot carry a rejection into the callers behind it.
chain.tail = ahead.then(() => turn);
const held = chain;
const leave = (): void => {
// Releases this call's turn first, so a caller that gave up while queued hands its place
// straight to the one behind it.
finish();
held.callers -= 1;
if (held.callers === 0 && chains.get(key) === held) chains.delete(key);
};
try {
await waitForTurn(ahead, signal);
} catch (err) {
leave();
throw err;
}
try {
return await fn();
} finally {
leave();
}
}
/** Keys with a live queue — the no-growth property, observable for the test that pins it. */
export function pendingFileLocks(): number {
return chains.size;
}