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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsindex 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): BuiltinTooconst 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdindex 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.mdindex 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`)同时服务两类模型。