Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(core): edit_file and write_file serialize per file (#709)

Yaowei Zheng3c8b02a34d0e
diff --git a/changelog/unreleased/2026-09-12-file-tool-lock.md b/changelog/unreleased/2026-09-12-file-tool-lock.md
new file mode 100644
index 00000000..335afa6a
--- /dev/null
+++ b/changelog/unreleased/2026-09-12-file-tool-lock.md
@@ -0,0 +1,33 @@
+# edit_file and write_file serialize per file
+
+- **Date:** 2026-09-12
+- **Type:** fix
+- **Scope:** `core`, `docs`
+- **PR:** [#709](https://github.com/Prism-Shadow/penguin-harness/pull/709)
+
+[中文版](2026-09-12-file-tool-lock.zh.md)
+
+`edit_file` and `write_file` hold a per-file mutex across their whole read-modify-write. Both tools
+read a file, compute the new content and replace it with an atomic temp-file + rename, and the
+engine runs a turn's approved tool calls concurrently — so two edits of one file, whether from one
+turn or from two subagents in the same process, both read the original bytes and the later rename
+won. One edit was silently lost while both calls reported success.
+
+## Details
+
+- **The key is the file's real path**, so every name that reaches one file folds onto one key: a
+ symlink and the file it points at, a path crossing a linked directory. A path that does not exist
+ yet keys on its deepest real ancestor plus the segments below it — `write_file` creates missing
+ parents, so the directory is often still absent too — and a `write_file` that creates the file and
+ an `edit_file` that follows therefore share one key. Resolution failures are absorbed rather than
+ raised, leaving the tool's own error wording intact.
+- **The lock spans the read and the write**: stat, read, match, atomic write. The diff rendering and
+ the tool's output happen after it is released. A call interrupted while queued behind another
+ writer ends as `aborted`, the same as one interrupted during its own read or write.
+- **An `old_string` an earlier edit removed now fails.** Two concurrent edits of the same
+ `old_string` without `replace_all` end as one replacement plus the existing `old_string not found`
+ message, instead of the second edit overwriting the first.
+- **`read_file` takes no lock** — the atomic rename already leaves a reader with either the old
+ content or the new one, never a mix.
+- **The scope is one process.** No OS-level file lock is taken, so a separate CLI run, an editor or
+ the user's own shell writing the same file is not serialized against these tools.
diff --git a/changelog/unreleased/2026-09-12-file-tool-lock.zh.md b/changelog/unreleased/2026-09-12-file-tool-lock.zh.md
new file mode 100644
index 00000000..c741439f
--- /dev/null
+++ b/changelog/unreleased/2026-09-12-file-tool-lock.zh.md
@@ -0,0 +1,26 @@
+# edit_file 与 write_file 按文件串行
+
+- **Date:** 2026-09-12
+- **Type:** fix
+- **Scope:** `core`, `docs`
+- **PR:** [#709](https://github.com/Prism-Shadow/penguin-harness/pull/709)
+
+[English](2026-09-12-file-tool-lock.md)
+
+`edit_file` 与 `write_file` 的整段读-改-写现在由按文件的互斥锁护住。两个工具都是读入文件、算出新内容、再以临时
+文件 + rename 原子替换,而引擎会并行执行一轮里已批准的工具调用——因此对同一文件的两次编辑,无论来自同一轮还是
+同进程的两个子会话,都读到原始内容,最后落盘的 rename 胜出。其中一次编辑被静默丢弃,而两次调用都报告成功。
+
+## 细节
+
+- **锁以文件的真实路径为键**,因此指向同一文件的每个名字都归并到同一个键:软链接与它指向的文件,以及穿过软链接
+ 目录的路径。尚不存在的路径以其最深层可解析的祖先目录加上其下各段为键——`write_file` 会补建缺失的父目录,所在目录
+ 往往同样尚不存在——因此创建文件的 `write_file` 与随后的 `edit_file` 共用一个键。解析失败被吸收而不抛出,工具
+ 原有的报错文案得以保留。
+- **锁覆盖读与写整段**:stat、读取、匹配、原子写入。diff 渲染与工具输出都在释放锁之后进行。在另一个写入者后面
+ 排队期间被中断的调用以 `aborted` 收尾,与在自己的读或写期间被中断一致。
+- **先前编辑已删去的 `old_string` 现在会失败。** 不开 `replace_all` 时对同一 `old_string` 的两次并行编辑,结果
+ 是一次替换加上既有的 `old_string not found` 报错,而不是后者覆盖前者。
+- **`read_file` 不加锁**——rename 原子替换已经保证读到的要么是旧内容、要么是新内容,不会是两者的混合。
+- **锁只覆盖本进程。** 不使用操作系统级文件锁,因此另起的 CLI 进程、编辑器或用户自己的 shell 对同一文件的写入
+ 不与这两个工具串行。
diff --git a/packages/core/src/environment/tools/edit-file.ts b/packages/core/src/environment/tools/edit-file.ts
index e2c8041d..e193aaeb 100644
--- a/packages/core/src/environment/tools/edit-file.ts
+++ b/packages/core/src/environment/tools/edit-file.ts
@@ -12,7 +12,9 @@
* crash mid-write cannot leave the file half-edited; a symlinked path is followed to the
* file it names, the same way the read that produced the diff was. Relative paths resolve
* against the Workspace; absolute paths are allowed (tools run with the user's full
- * permissions, same as the shell tool).
+ * permissions, same as the shell tool). Read-modify-write on one file is serialized against
+ * write_file and against other edit_file calls in this process (see internal/file-lock.ts),
+ * so two concurrent edits of one file are applied one after the other.
*
* Division of responsibility with Environment (see environment.ts): non-streaming — yields
* one final text delta; failures are explanatory text finalized as `failed`; anything
@@ -28,6 +30,7 @@ import type { OmniMessage } from "../../omnimessage/index.js";
import type { ToolDefinitionConfig } from "../../interfaces/index.js";
import type { BuiltinTool, ToolExecutionContext, ToolResult } from "./types.js";
import { atomicWriteFile } from "../../internal/atomic-write.js";
+import { fileLockKey, withFileLock } from "../../internal/file-lock.js";
import { buildReplacementHunks, renderHunk } from "./diff.js";
import { missingPathHint } from "./path-hint.js";
import { describeArgumentError } from "./tool-arguments.js";
@@ -55,6 +58,91 @@ function countOccurrences(haystack: string, needle: string): number {
return count;
}
+/** What the locked section leaves for the generator to report once the file's lock is released. */
+type EditOutcome =
+ | { kind: "fatal"; text: string }
+ | { kind: "aborted" }
+ | { kind: "ok"; content: string; replaced: number };
+
+/**
+ * The locked half of one edit: stat, read, match `old_string`, write the result back
+ * atomically. It returns an outcome instead of yielding because it runs while the file's
+ * mutex is held — the deltas go out afterwards, rendered from `content`, the bytes as this
+ * call found them (which, queued behind another edit of the same file, already include it).
+ */
+async function applyEdit(params: {
+ resolved: string;
+ filePath: string;
+ oldString: string;
+ newString: string;
+ replaceAll: boolean;
+ signal?: AbortSignal;
+}): Promise<EditOutcome> {
+ const { resolved, filePath, oldString, newString, replaceAll, signal } = params;
+ let content: string;
+ let fileMode: number | undefined;
+ try {
+ const st = await stat(resolved);
+ if (st.isDirectory()) {
+ return { kind: "fatal", text: `Cannot edit "${filePath}": it is a directory.` };
+ }
+ fileMode = st.mode & 0o777;
+ content = await readFile(resolved, { encoding: "utf8", ...(signal ? { signal } : {}) });
+ } catch (err) {
+ if (signal?.aborted) return { kind: "aborted" };
+ const code = (err as NodeJS.ErrnoException).code;
+ // ENOTDIR is the same mistake seen one segment later (a file used as a directory),
+ // so it gets the same diagnosis instead of a raw errno message.
+ if (code === "ENOENT" || code === "ENOTDIR") {
+ const hint = await missingPathHint(resolved);
+ return {
+ kind: "fatal",
+ text: `File not found: "${filePath}". edit_file only edits existing files — check the path (absolute paths are supported), or use write_file to create it.${hint}`,
+ };
+ }
+ const message = err instanceof Error ? err.message : String(err);
+ return { kind: "fatal", text: `Failed to read "${filePath}": ${message}` };
+ }
+ if (signal?.aborted) return { kind: "aborted" };
+
+ const occurrences = countOccurrences(content, oldString);
+ if (occurrences === 0) {
+ // A CRLF file is the classic silent mismatch: text copied from read_file's display
+ // has bare \n while the file has \r\n — say so explicitly.
+ const crlfHint = content.includes("\r\n")
+ ? " Note: the file uses CRLF (\\r\\n) line endings — a multi-line old_string must include the \\r characters."
+ : "";
+ return {
+ kind: "fatal",
+ text: `old_string not found in "${filePath}". Make sure it matches the file content exactly, including whitespace and indentation.${crlfHint}`,
+ };
+ }
+ if (occurrences > 1 && !replaceAll) {
+ return {
+ kind: "fatal",
+ text: `old_string occurs ${occurrences} times in "${filePath}". Add surrounding context to make it unique, or set replace_all to true to replace every occurrence.`,
+ };
+ }
+
+ const replaceStart = content.indexOf(oldString);
+ const newContent = replaceAll
+ ? content.split(oldString).join(newString)
+ : content.slice(0, replaceStart) + newString + content.slice(replaceStart + oldString.length);
+ try {
+ await atomicWriteFile(resolved, newContent, {
+ ...(fileMode !== undefined ? { mode: fileMode } : {}),
+ ...(signal ? { signal } : {}),
+ followSymlinks: true,
+ });
+ } catch (err) {
+ if (signal?.aborted) return { kind: "aborted" };
+ const message = err instanceof Error ? err.message : String(err);
+ return { kind: "fatal", text: `Failed to write "${filePath}": ${message}` };
+ }
+
+ return { kind: "ok", content, replaced: replaceAll ? occurrences : 1 };
+}
+
/**
* edit_file builtin tool: reads the file, validates the uniqueness of `old_string`,
* writes the replaced content back atomically, and reports a unified diff of the change.
@@ -116,73 +204,29 @@ export function createEditFileTool(definition: ToolDefinitionConfig): BuiltinToo
const replaceAll = args["replace_all"] === true;
const resolved = path.resolve(ctx.workspaceDir, filePath);
- let content: string;
- let fileMode: number | undefined;
- try {
- const st = await stat(resolved);
- if (st.isDirectory()) {
- yield delta(`Cannot edit "${filePath}": it is a directory.`);
- return { stopReason: "fatal" };
- }
- fileMode = st.mode & 0o777;
- content = await readFile(resolved, { encoding: "utf8", ...(signal ? { signal } : {}) });
- } catch (err) {
- if (signal?.aborted) return { stopReason: "aborted" };
- const code = (err as NodeJS.ErrnoException).code;
- // ENOTDIR is the same mistake seen one segment later (a file used as a directory),
- // so it gets the same diagnosis instead of a raw errno message.
- if (code === "ENOENT" || code === "ENOTDIR") {
- const hint = await missingPathHint(resolved);
- yield delta(
- `File not found: "${filePath}". edit_file only edits existing files — check the path (absolute paths are supported), or use write_file to create it.${hint}`,
- );
- } else {
- const message = err instanceof Error ? err.message : String(err);
- yield delta(`Failed to read "${filePath}": ${message}`);
+ // One file, one writer at a time: the read and the write that follows it are a single
+ // critical section, so a concurrent edit lands entirely before or entirely after this
+ // one instead of being overwritten by it.
+ const key = await fileLockKey(resolved);
+ const outcome = await withFileLock(
+ key,
+ () => applyEdit({ resolved, filePath, oldString, newString, replaceAll, signal }),
+ signal,
+ ).catch((err: unknown): EditOutcome => {
+ // Interrupted while queued behind another writer on the same file — the same
+ // `aborted` the read and the write report, reached one step earlier.
+ if (signal?.aborted || (err as { name?: string } | null)?.name === "AbortError") {
+ return { kind: "aborted" };
}
+ throw err;
+ });
+ if (outcome.kind === "aborted") return { stopReason: "aborted" };
+ if (outcome.kind === "fatal") {
+ yield delta(outcome.text);
return { stopReason: "fatal" };
}
- if (signal?.aborted) return { stopReason: "aborted" };
-
- const occurrences = countOccurrences(content, oldString);
- if (occurrences === 0) {
- // A CRLF file is the classic silent mismatch: text copied from read_file's display
- // has bare \n while the file has \r\n — say so explicitly.
- const crlfHint = content.includes("\r\n")
- ? " Note: the file uses CRLF (\\r\\n) line endings — a multi-line old_string must include the \\r characters."
- : "";
- yield delta(
- `old_string not found in "${filePath}". Make sure it matches the file content exactly, including whitespace and indentation.${crlfHint}`,
- );
- return { stopReason: "fatal" };
- }
- if (occurrences > 1 && !replaceAll) {
- yield delta(
- `old_string occurs ${occurrences} times in "${filePath}". Add surrounding context to make it unique, or set replace_all to true to replace every occurrence.`,
- );
- return { stopReason: "fatal" };
- }
-
- const replaceStart = content.indexOf(oldString);
- const newContent = replaceAll
- ? content.split(oldString).join(newString)
- : content.slice(0, replaceStart) +
- newString +
- content.slice(replaceStart + oldString.length);
- try {
- await atomicWriteFile(resolved, newContent, {
- ...(fileMode !== undefined ? { mode: fileMode } : {}),
- ...(signal ? { signal } : {}),
- followSymlinks: true,
- });
- } catch (err) {
- if (signal?.aborted) return { stopReason: "aborted" };
- const message = err instanceof Error ? err.message : String(err);
- yield delta(`Failed to write "${filePath}": ${message}`);
- return { stopReason: "fatal" };
- }
+ const { content, replaced } = outcome;
- const replaced = replaceAll ? occurrences : 1;
// Git-style unified diff of the changed regions, self-budgeted below the tool's
// output cap so the leading summary line (and the elision note) always survive
// Environment's front-keep truncation.
diff --git a/packages/core/src/environment/tools/write-file.ts b/packages/core/src/environment/tools/write-file.ts
index 96893d5a..b970b0b4 100644
--- a/packages/core/src/environment/tools/write-file.ts
+++ b/packages/core/src/environment/tools/write-file.ts
@@ -12,7 +12,10 @@
* half-written; a symlinked path is followed to the file it names, so the link survives
* and the content lands where it points. Relative paths resolve against the Workspace;
* absolute paths are allowed (tools run with the user's full permissions, same as the
- * shell tool).
+ * shell tool). The write is serialized against edit_file and other write_file calls on the
+ * same file in this process (see internal/file-lock.ts), so a concurrent edit of that file
+ * applies either to the content this call replaced or to the content it wrote — never
+ * computed from the one and written over the other.
* For surgical changes to an existing file, edit_file is the better tool — this one
* replaces the whole content.
*
@@ -26,6 +29,7 @@
import path from "node:path";
import { mkdir, readFile, stat } from "node:fs/promises";
import { atomicWriteFile, resolveWriteTarget } from "../../internal/atomic-write.js";
+import { fileLockKey, withFileLock } from "../../internal/file-lock.js";
import { buildLineDiffHunks, renderHunk } from "./diff.js";
import { partialToolCallOutput } from "../../omnimessage/index.js";
import type { OmniMessage } from "../../omnimessage/index.js";
@@ -55,6 +59,67 @@ function countLines(content: string): number {
return lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
}
+/** What the locked section leaves for the generator to report once the file's lock is released. */
+type WriteOutcome =
+ | { kind: "fatal"; text: string }
+ | { kind: "aborted" }
+ | { kind: "ok"; existed: boolean; previous: string | null };
+
+/**
+ * The locked half of one write: decide created-vs-overwrote, read the previous content back
+ * for the diff, create the parent directory and write the content atomically. It returns an
+ * outcome instead of yielding because it runs while the file's mutex is held — the diff is
+ * rendered afterwards, against the content that was actually replaced.
+ */
+async function applyWrite(params: {
+ resolved: string;
+ filePath: string;
+ content: string;
+ signal?: AbortSignal;
+}): Promise<WriteOutcome> {
+ const { resolved, filePath, content, signal } = params;
+ // Determine created-vs-overwrote before writing; also reject directories up front
+ // (writeFile's raw EISDIR is not model-friendly).
+ let existed = false;
+ let fileMode: number | undefined;
+ let previous: string | null = null; // Previous content, for the overwrite diff
+ try {
+ const st = await stat(resolved);
+ if (st.isDirectory()) {
+ return { kind: "fatal", text: `Cannot write "${filePath}": it is a directory.` };
+ }
+ existed = true;
+ fileMode = st.mode & 0o777; // Preserved across the atomic temp-file + rename write
+ // Read the old content back for the diff — bounded: a huge or unreadable/binary
+ // previous file simply gets no diff (never a failure).
+ if (st.size <= DIFF_SOURCE_CAP_BYTES) {
+ const bytes = await readFile(resolved);
+ if (!bytes.includes(0)) previous = bytes.toString("utf8");
+ }
+ } catch {
+ // Missing file (or unstatable path): proceed to create; real write errors surface below.
+ }
+ if (signal?.aborted) return { kind: "aborted" };
+
+ try {
+ // The parent to create is the one holding the file that will actually be written:
+ // through a symlink that is the target's directory, not the link's (a link pointing
+ // into a directory that does not exist yet is created the way `>` would).
+ await mkdir(path.dirname(await resolveWriteTarget(resolved)), { recursive: true });
+ await atomicWriteFile(resolved, content, {
+ ...(fileMode !== undefined ? { mode: fileMode } : {}),
+ ...(signal ? { signal } : {}),
+ followSymlinks: true,
+ });
+ } catch (err) {
+ if (signal?.aborted) return { kind: "aborted" };
+ const message = err instanceof Error ? err.message : String(err);
+ return { kind: "fatal", text: `Failed to write "${filePath}": ${message}` };
+ }
+
+ return { kind: "ok", existed, previous };
+}
+
/**
* write_file builtin tool: creates parent directories as needed and writes the full
* content, reporting created/overwrote plus the written size.
@@ -91,46 +156,28 @@ export function createWriteFileTool(definition: ToolDefinitionConfig): BuiltinTo
}
const resolved = path.resolve(ctx.workspaceDir, filePath);
- // Determine created-vs-overwrote before writing; also reject directories up front
- // (writeFile's raw EISDIR is not model-friendly).
- let existed = false;
- let fileMode: number | undefined;
- let previous: string | null = null; // Previous content, for the overwrite diff
- try {
- const st = await stat(resolved);
- if (st.isDirectory()) {
- yield delta(`Cannot write "${filePath}": it is a directory.`);
- return { stopReason: "fatal" };
- }
- existed = true;
- fileMode = st.mode & 0o777; // Preserved across the atomic temp-file + rename write
- // Read the old content back for the diff — bounded: a huge or unreadable/binary
- // previous file simply gets no diff (never a failure).
- if (st.size <= DIFF_SOURCE_CAP_BYTES) {
- const bytes = await readFile(resolved);
- if (!bytes.includes(0)) previous = bytes.toString("utf8");
+ // One file, one writer at a time: the previous content this call reads back and the
+ // content it writes are a single critical section, so a concurrent edit of the same
+ // file is applied either before this write or on top of it.
+ const key = await fileLockKey(resolved);
+ const outcome = await withFileLock(
+ key,
+ () => applyWrite({ resolved, filePath, content, signal }),
+ signal,
+ ).catch((err: unknown): WriteOutcome => {
+ // Interrupted while queued behind another writer on the same file — the same
+ // `aborted` the write itself reports, reached one step earlier.
+ if (signal?.aborted || (err as { name?: string } | null)?.name === "AbortError") {
+ return { kind: "aborted" };
}
- } catch {
- // Missing file (or unstatable path): proceed to create; real write errors surface below.
- }
- if (signal?.aborted) return { stopReason: "aborted" };
-
- try {
- // The parent to create is the one holding the file that will actually be written:
- // through a symlink that is the target's directory, not the link's (a link pointing
- // into a directory that does not exist yet is created the way `>` would).
- await mkdir(path.dirname(await resolveWriteTarget(resolved)), { recursive: true });
- await atomicWriteFile(resolved, content, {
- ...(fileMode !== undefined ? { mode: fileMode } : {}),
- ...(signal ? { signal } : {}),
- followSymlinks: true,
- });
- } catch (err) {
- if (signal?.aborted) return { stopReason: "aborted" };
- const message = err instanceof Error ? err.message : String(err);
- yield delta(`Failed to write "${filePath}": ${message}`);
+ throw err;
+ });
+ if (outcome.kind === "aborted") return { stopReason: "aborted" };
+ if (outcome.kind === "fatal") {
+ yield delta(outcome.text);
return { stopReason: "fatal" };
}
+ const { existed, previous } = outcome;
const lines = countLines(content);
const bytes = Buffer.byteLength(content, "utf8");
diff --git a/packages/core/src/internal/file-lock.ts b/packages/core/src/internal/file-lock.ts
new file mode 100644
index 00000000..b0248cab
--- /dev/null
+++ b/packages/core/src/internal/file-lock.ts
@@ -0,0 +1,159 @@
+/**
+ * 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;
+}
diff --git a/packages/core/test/file-lock.test.ts b/packages/core/test/file-lock.test.ts
new file mode 100644
index 00000000..38fd77d8
--- /dev/null
+++ b/packages/core/test/file-lock.test.ts
@@ -0,0 +1,143 @@
+/**
+ * Behavior tests for the per-file mutex behind edit_file / write_file: callers are served in
+ * arrival order, a failing or an interrupted caller leaves the queue intact, the map holding
+ * the queues comes back empty, and one file gets one key no matter which name reaches it —
+ * including a name that does not exist yet, which is the key a write_file creating the file
+ * and an edit_file following it have to share.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileLockKey, pendingFileLocks, withFileLock } from "../src/internal/file-lock.js";
+
+/** A promise plus its resolver, so a test decides when the holder of the lock finishes. */
+function gate(): { wait: Promise<void>; open: () => void } {
+ let open: () => void = () => undefined;
+ const wait = new Promise<void>((resolve) => {
+ open = resolve;
+ });
+ return { wait, open };
+}
+
+let dir: string;
+
+beforeEach(async () => {
+ dir = await mkdtemp(path.join(tmpdir(), "penguin-filelock-"));
+});
+
+afterEach(async () => {
+ await rm(dir, { recursive: true, force: true });
+});
+
+describe("withFileLock", () => {
+ it("runs callers one at a time, in arrival order", async () => {
+ const order: string[] = [];
+ const held = gate();
+ const first = withFileLock("k", async () => {
+ order.push("first-in");
+ await held.wait;
+ order.push("first-out");
+ });
+ const second = withFileLock("k", async () => {
+ order.push("second");
+ });
+ const third = withFileLock("k", async () => {
+ order.push("third");
+ });
+ held.open();
+ await Promise.all([first, second, third]);
+ expect(order).toEqual(["first-in", "first-out", "second", "third"]);
+ });
+
+ it("reports a caller's failure to that caller and still serves the next one", async () => {
+ const failing = withFileLock("k", async () => {
+ throw new Error("boom");
+ });
+ const next = withFileLock("k", async () => "next");
+ await expect(failing).rejects.toThrow("boom");
+ await expect(next).resolves.toBe("next");
+ });
+
+ it("rejects a caller interrupted while it waits, without running it", async () => {
+ const held = gate();
+ let ran = false;
+ const holder = withFileLock("k", () => held.wait);
+ const controller = new AbortController();
+ const interrupted = withFileLock(
+ "k",
+ async () => {
+ ran = true;
+ },
+ controller.signal,
+ );
+ const behind = withFileLock("k", async () => "behind");
+ controller.abort();
+ const err = await interrupted.then(
+ () => new Error("the interrupted caller resolved"),
+ (e: unknown) => e,
+ );
+ expect((err as Error).name).toBe("AbortError");
+ held.open();
+ await holder;
+ // The interrupted caller dropped out of the queue; the one behind it still got its turn.
+ await expect(behind).resolves.toBe("behind");
+ expect(ran).toBe(false);
+ });
+
+ it("keeps no entry for a key once its queue has drained", async () => {
+ await withFileLock("k", async () => undefined);
+ expect(pendingFileLocks()).toBe(0);
+ const held = gate();
+ const holder = withFileLock("k", () => held.wait);
+ const waiter = withFileLock("k", async () => undefined);
+ expect(pendingFileLocks()).toBe(1);
+ held.open();
+ await Promise.all([holder, waiter]);
+ expect(pendingFileLocks()).toBe(0);
+ });
+});
+
+describe("fileLockKey", () => {
+ it("gives a file that does not exist yet the key it will have once created", async () => {
+ const target = path.join(dir, "later.txt");
+ const beforeCreation = await fileLockKey(target);
+ await writeFile(target, "created\n");
+ expect(beforeCreation).toBe(await fileLockKey(target));
+ expect(beforeCreation).toBe(await realpath(target));
+ });
+
+ it("gives a file under a directory that does not exist yet that same key", async () => {
+ // write_file creates the missing parents, so the whole directory is routinely still
+ // absent when the key is taken — and reaching it through a linked ancestor is the
+ // ordinary case, not an exotic one (macOS puts every temporary directory behind
+ // `/var` → `/private/var`). Keyed on the unresolved name, the call that creates the file
+ // and every call after it would take different locks.
+ await mkdir(path.join(dir, "real-root"));
+ await symlink(path.join(dir, "real-root"), path.join(dir, "linked-root"));
+ const target = path.join(dir, "linked-root", "created", "later.txt");
+ const beforeAnything = await fileLockKey(target);
+ await mkdir(path.dirname(target), { recursive: true });
+ await writeFile(target, "created\n");
+ expect(beforeAnything).toBe(await fileLockKey(target));
+ expect(beforeAnything).toBe(await realpath(target));
+ });
+
+ it("folds a symlink onto the file it points at", async () => {
+ await writeFile(path.join(dir, "real.txt"), "x\n");
+ await symlink("real.txt", path.join(dir, "link.txt"));
+ expect(await fileLockKey(path.join(dir, "link.txt"))).toBe(
+ await fileLockKey(path.join(dir, "real.txt")),
+ );
+ });
+
+ it("keys an unresolvable path on itself instead of failing", async () => {
+ // A link cycle: the tools report ELOOP in their own wording, so the key must not throw
+ // before they get there.
+ await symlink("b.txt", path.join(dir, "a.txt"));
+ await symlink("a.txt", path.join(dir, "b.txt"));
+ expect(await fileLockKey(path.join(dir, "a.txt"))).toBe(
+ path.join(await realpath(dir), "a.txt"),
+ );
+ });
+});
diff --git a/packages/core/test/file-tools.test.ts b/packages/core/test/file-tools.test.ts
index d0d2946e..420b9fdc 100644
--- a/packages/core/test/file-tools.test.ts
+++ b/packages/core/test/file-tools.test.ts
@@ -831,3 +831,81 @@ describe("edit_file / write_file — symlinked targets", () => {
expect((await readdir(tmp)).filter((e) => e.includes(".tmp-"))).toEqual([]);
});
});
+
+describe("edit_file / write_file — one file, concurrent writers", () => {
+ const edit = () => createEditFileTool(def(EDIT_FILE_NAME, "rw"));
+ const write = () => createWriteFileTool(def(WRITE_FILE_NAME, "rw"));
+
+ it("applies eight concurrent edits of one file without losing any", async () => {
+ const markers = Array.from({ length: 8 }, (_, i) => `marker-${i + 1}`);
+ await writeFile(path.join(tmp, "markers.txt"), `${markers.join("\n")}\n`);
+ const outcomes = await Promise.all(
+ markers.map((marker) =>
+ run(
+ edit(),
+ { file_path: "markers.txt", old_string: marker, new_string: `done-${marker}` },
+ tmp,
+ ),
+ ),
+ );
+ for (const { result, text } of outcomes) {
+ expect(result?.stopReason).toBeUndefined();
+ expect(text).toContain("Replaced 1 occurrence");
+ }
+ // Every edit read the file after the one before it landed, so all eight are in there.
+ const final = await readFile(path.join(tmp, "markers.txt"), "utf8");
+ expect(final).toBe(`${markers.map((m) => `done-${m}`).join("\n")}\n`);
+ expect(final).not.toMatch(/(^|\n)marker-/);
+ });
+
+ it("fails the second edit of the same old_string instead of overwriting the first", async () => {
+ await writeFile(path.join(tmp, "same.txt"), "alpha\nbeta\n");
+ const outcomes = await Promise.all([
+ run(edit(), { file_path: "same.txt", old_string: "beta", new_string: "one" }, tmp),
+ run(edit(), { file_path: "same.txt", old_string: "beta", new_string: "two" }, tmp),
+ ]);
+ const succeeded = outcomes.filter((o) => o.result?.stopReason === undefined);
+ const failed = outcomes.filter((o) => o.result?.stopReason === "fatal");
+ expect(succeeded).toHaveLength(1);
+ expect(failed).toHaveLength(1);
+ // The loser read the winner's content, where its old_string no longer exists.
+ expect(failed[0]!.text).toContain('old_string not found in "same.txt"');
+ expect(["alpha\none\n", "alpha\ntwo\n"]).toContain(
+ await readFile(path.join(tmp, "same.txt"), "utf8"),
+ );
+ });
+
+ it("serializes a write_file against an edit_file of the same file", async () => {
+ await writeFile(path.join(tmp, "both.txt"), "keep\nshared\nold-tail\n");
+ const [written, edited] = await Promise.all([
+ run(write(), { file_path: "both.txt", content: "fresh\nshared\nnew-tail\n" }, tmp),
+ run(edit(), { file_path: "both.txt", old_string: "shared", new_string: "edited" }, tmp),
+ ]);
+ expect(written.result?.stopReason).toBeUndefined();
+ expect(edited.result?.stopReason).toBeUndefined();
+ // `shared` is in both contents, so the edit succeeds either way and the file alone
+ // cannot tell the orders apart: unserialized, a write that renames last also leaves its
+ // own content behind. What separates them is what the SECOND call read — each renders
+ // its diff against the bytes it found, so the loser of the lock has to have seen the
+ // winner's result.
+ const final = await readFile(path.join(tmp, "both.txt"), "utf8");
+ if (final === "fresh\nedited\nnew-tail\n") {
+ expect(edited.text).toContain("\n fresh\n"); // The edit read what the write landed.
+ } else {
+ expect(final).toBe("fresh\nshared\nnew-tail\n");
+ expect(written.text).toContain("\n-edited\n"); // The write read what the edit landed.
+ }
+ });
+
+ it("serializes edits reaching one file through a symlink and through its target", async () => {
+ await writeFile(path.join(tmp, "real.conf"), "one\ntwo\n");
+ await symlink("real.conf", path.join(tmp, "link.conf"));
+ const outcomes = await Promise.all([
+ run(edit(), { file_path: "real.conf", old_string: "one", new_string: "ONE" }, tmp),
+ run(edit(), { file_path: "link.conf", old_string: "two", new_string: "TWO" }, tmp),
+ ]);
+ for (const { result } of outcomes) expect(result?.stopReason).toBeUndefined();
+ // Both names resolve to one lock key, so neither edit was computed from stale content.
+ expect(await readFile(path.join(tmp, "real.conf"), "utf8")).toBe("ONE\nTWO\n");
+ });
+});
diff --git a/packages/docs/content/tools.en.md b/packages/docs/content/tools.en.md
index 98a7fe8d..ab59e177 100644
--- a/packages/docs/content/tools.en.md
+++ b/packages/docs/content/tools.en.md
@@ -133,7 +133,7 @@ On POSIX, Ctrl-C sends `SIGINT` to the session's process group, interrupting the
### File tools
-`read_file` / `edit_file` / `write_file` run with the user's full permissions, same as the shell tool; relative paths resolve against the Workspace and absolute paths are allowed. A symlinked path is followed to the file it names — reads, edits and writes all land on that file, and the link stays a link. They are non-streaming (a single final output) and never throw — failures come back as explanatory text with `stop_reason: failed`.
+`read_file` / `edit_file` / `write_file` run with the user's full permissions, same as the shell tool; relative paths resolve against the Workspace and absolute paths are allowed. A symlinked path is followed to the file it names — reads, edits and writes all land on that file, and the link stays a link. They are non-streaming (a single final output) and never throw — failures come back as explanatory text with `stop_reason: failed`. `edit_file` and `write_file` serialize per file within the server process, keyed by the file's real path — a symlink and its target are one file — so parallel edits of one file are applied one after another, and an `old_string` an earlier edit removed fails to match instead of overwriting it; writes from other processes are outside that lock.
`read_file` reads images as well as text. A png/jpeg/gif/webp file up to 5MB — recognized by its magic number, then by its extension — or an http(s) URL in `file_path` (a URL is only ever an image source; the response content-type is consulted first) takes the image branch, and what comes back depends on the Session model's vision flag: a model that accepts images gets the image itself as image content (the text output is a one-line `image/png, 123.4 kB`), while a text-only model gets the Project's configured `vision_model` answering `prompt` (default: a detailed description), streamed as the tool's text output — the image never enters that Session's history. Without a `vision_model`, an image read on a text-only Session fails with an explanation asking the user to pick one in the model settings. See [Models & Providers](/models). The branch is decided by the `VisionDescriberService` the SDK injects into the Environment for text-only Sessions only, so one config entry (no `forModel`) serves both model classes.
diff --git a/packages/docs/content/tools.zh.md b/packages/docs/content/tools.zh.md
index 1bda0e13..666f0a6d 100644
--- a/packages/docs/content/tools.zh.md
+++ b/packages/docs/content/tools.zh.md
@@ -132,7 +132,7 @@ POSIX 上 Ctrl-C 向会话进程组发送 `SIGINT`,中断前台命令。Window
### 文件工具
-`read_file` / `edit_file` / `write_file` 与 Shell 工具一样以用户完整权限运行:相对路径按 Workspace 解析,也接受绝对路径。软链接路径会被解析到它指向的文件——读取、编辑、写入都落在该文件上,链接本身仍然是链接。三者均为非流式(一次性输出最终结果),从不抛异常——失败以解释性文本收尾,`stop_reason` 为 `failed`。
+`read_file` / `edit_file` / `write_file` 与 Shell 工具一样以用户完整权限运行:相对路径按 Workspace 解析,也接受绝对路径。软链接路径会被解析到它指向的文件——读取、编辑、写入都落在该文件上,链接本身仍然是链接。三者均为非流式(一次性输出最终结果),从不抛异常——失败以解释性文本收尾,`stop_reason` 为 `failed`。`edit_file` 与 `write_file` 在服务端进程内按文件串行,以文件的真实路径为键——软链接与它指向的文件算同一个文件——因此对同一文件的并行编辑会被逐个应用,先前编辑已删去的 `old_string` 会匹配失败而不是覆盖它;其他进程的写入不在这把锁的覆盖范围内。
`read_file` 也读图片。png/jpeg/gif/webp 文件(不超过 5MB,先按魔数、再按扩展名识别)或 `file_path` 里的 http(s) URL(URL 只作图片来源,优先看响应的 content-type)走读图分支,返回什么取决于 Session 模型的 vision 标记:接受图片的模型拿到图片本身作为图像内容(文本输出只有一行 `image/png, 123.4 kB`);text-only 模型拿到的是 Project 配置的 `vision_model` 对 `prompt`(缺省为详细描述)的回答,以流式文本作为工具输出——图片不进入该 Session 的历史。未配置 `vision_model` 时,text-only Session 的读图以解释性错误失败,请用户到模型设置中选一个。见 [模型与 Provider](/models)。分支由 SDK 仅为 text-only Session 注入 Environment 的 `VisionDescriberService` 决定,因此同一条配置条目(不带 `forModel`)同时服务两类模型。