From f0d2c1bda84ab99edd5156a1092029cbc15a188d Mon Sep 17 00:00:00 2001
From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com>
Date: Thu, 12 Nov 2026 13:48:16 +0800
Subject: [PATCH 1/5] fix(safe-write,read-file): publish through the guarded
text writer and its readers
Unit 1 of the split plan for pull 1913, carried on the branch 1913 already tracks. It holds the guarded
text writer and everything that reads through it: the new src/services/file-safety/safeWriteText with its
canonical key walk, the staging and durability errors, the ancestor and dangling-link refusals, the
ReadFileTool and indentation-reader recovery, the lock-key handover in fileLock, and the specs for each of
them. The JSON publish layer and its MCP call sites are not here; they travel in unit 2, which brings the
consumers of resolvePublishTarget and canonicalDirKey and adds the export keyword back with them. In this
unit the only non-test importer of this file is src/utils/fileLock.ts and it asks for resolveLockKey
alone, so those two names are declared without export here rather than exported for a consumer that has
not arrived yet, and no knip config entry is added to cover them.
---
src/core/tools/ReadFileTool.ts | 117 +-
src/core/tools/__tests__/readFileTool.spec.ts | 1208 ++++++++++++-
src/eslint-suppressions.json | 2 +-
.../indentation-reader-unicode.spec.ts | 9 +
.../misc/__tests__/indentation-reader.spec.ts | 82 +
src/integrations/misc/indentation-reader.ts | 19 +-
.../safeWriteText.integration.spec.ts | 70 +
.../__tests__/safeWriteText.spec.ts | 1553 +++++++++++++++++
src/services/file-safety/safeWriteText.ts | 660 +++++++
.../__tests__/fileLock.canonicalKey.spec.ts | 71 +
src/utils/fileLock.ts | 13 +-
11 files changed, 3791 insertions(+), 13 deletions(-)
create mode 100644 src/services/file-safety/__tests__/safeWriteText.integration.spec.ts
create mode 100644 src/services/file-safety/__tests__/safeWriteText.spec.ts
create mode 100644 src/services/file-safety/safeWriteText.ts
create mode 100644 src/utils/__tests__/fileLock.canonicalKey.spec.ts
diff --git a/src/core/tools/ReadFileTool.ts b/src/core/tools/ReadFileTool.ts
index e4e69b30ad..f80212eda8 100644
--- a/src/core/tools/ReadFileTool.ts
+++ b/src/core/tools/ReadFileTool.ts
@@ -17,13 +17,14 @@ import type { ReadFileParams, ReadFileMode, ReadFileToolParams, FileEntry, LineR
import { isLegacyReadFileParams, type ClineSayTool } from "@roo-code/types"
import { Task } from "../task/Task"
+import { versionTokenOfStat } from "../../utils/versionToken"
import { formatResponse } from "../prompts/responses"
import { RecordSource } from "../context-tracking/FileContextTrackerTypes"
import { isPathOutsideWorkspace } from "../../utils/pathUtils"
import { getReadablePath } from "../../utils/path"
import { extractTextFromFile, addLineNumbers, getSupportedBinaryFormats } from "../../integrations/misc/extract-text"
import { readWithIndentation, readWithSlice } from "../../integrations/misc/indentation-reader"
-import { DEFAULT_LINE_LIMIT } from "../prompts/tools/native-tools/read_file"
+import { DEFAULT_LINE_LIMIT, MAX_LINE_LENGTH } from "../prompts/tools/native-tools/read_file"
import type { ToolUse, PushToolResult } from "../../shared/tools"
import {
@@ -215,14 +216,49 @@ export class ReadFileTool extends BaseTool<"read_file"> {
// Read text file content with lossy UTF-8 conversion
// Reading as Buffer first allows graceful handling of non-UTF8 bytes
// (they become U+FFFD replacement characters instead of throwing)
+ // A2 (epic #1375): capture the on-disk token before the read so a mutation
+ // landing mid-read is detected by the post-read stat below.
+ const preReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined)
const buffer = await fs.readFile(fullPath)
const fileContent = buffer.toString("utf-8")
- const result = this.processTextFile(fileContent, entry)
+ // A lossy decode is not the whole file: the model never saw those bytes.
+ const lossyDecode = !Buffer.from(fileContent).equals(buffer)
+ // S4b follow-up (#46 / epic #1375): processTextFile reports whether the
+ // returned content is the whole file; the observation below records that
+ // scope so the write guard can deny full-file updates built on a partial view.
+ const processed = this.processTextFile(fileContent, entry)
await task.fileContextTracker.trackFileContext(relPath, "read_tool" as RecordSource)
+ // A2 (plan #33 / epic #1375): record the observed on-disk version for the future write guard.
+ // The token is captured before AND after the read; the target is observed only
+ // when both match — a mutation between the two stats means the content the model
+ // received is not the on-disk state, and observing it would let a later write
+ // match a token the model never saw. A stat failure leaves the target
+ // unobserved and never fails the read.
+ // A task that was cancelled or disposed while this read was awaiting I/O must
+ // not record an observation: disposeOnce() has retired the registry, and the
+ // content this turn produced will never be acted on. Skipping also drops the
+ // post-read stat work for a task that no longer has a consumer.
+ if (!task.abort) {
+ const postReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined)
+ // Re-checked after the await: the guard above cannot see a cancellation
+ // that lands while the stat is in flight, and that read belongs to a run
+ // that will never act on it.
+ if (preReadStats && postReadStats && !task.abort) {
+ const preReadToken = versionTokenOfStat(preReadStats)
+ if (preReadToken === versionTokenOfStat(postReadStats)) {
+ task.observationRegistry.observe(
+ fullPath,
+ preReadToken,
+ processed.complete && !lossyDecode,
+ )
+ }
+ }
+ }
+
updateFileResult(relPath, {
- nativeContent: `File: ${relPath}\n${result}`,
+ nativeContent: `File: ${relPath}\n${processed.content}`,
})
} catch (error) {
const errorMsg = error instanceof Error ? error.message : String(error)
@@ -266,8 +302,14 @@ export class ReadFileTool extends BaseTool<"read_file"> {
/**
* Process a text file according to the requested mode.
+ *
+ * Returns the content string plus whether that content is the complete
+ * file (S4b follow-up #46 / epic #1375): slice mode is complete only
+ * when it starts at line 1, returns every line, and was not truncated;
+ * indentation mode is never complete because it returns semantic blocks
+ * of the file, not the file itself.
*/
- private processTextFile(content: string, entry: InternalFileEntry): string {
+ private processTextFile(content: string, entry: InternalFileEntry): { content: string; complete: boolean } {
const mode = entry.mode || "slice"
if (mode === "indentation") {
@@ -300,7 +342,15 @@ export class ReadFileTool extends BaseTool<"read_file"> {
output += `\n\nIncluded ranges: ${rangeStr} (total: ${result.totalLines} lines)`
}
- return output
+ if (result.hasClippedLines) {
+ // A returned line can still be a partial view: clipping is reported
+ // separately from the omission notice, because the block may show
+ // every line it includes in truncated form.
+ output += `\nNote: Some lines in this view exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.`
+ }
+
+ // Indentation mode returns semantic blocks: never a complete file view.
+ return { content: output, complete: false }
}
// Slice mode (default): simple offset/limit reading
@@ -323,11 +373,27 @@ export class ReadFileTool extends BaseTool<"read_file"> {
To read more: Use the read_file tool with offset=${nextOffset} and limit=${limit}.
${result.content}`
+ if (result.hasClippedLines) {
+ // The slice cut lines off and also clipped long lines inside it, so both
+ // notices belong to the response.
+ output += `\nNote: Some lines in this view exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.`
+ }
+ } else if (result.hasClippedLines) {
+ // Every line was returned, so there is no later offset to read: report the
+ // clipping without a next-offset hint, and keep the read incomplete so a
+ // full-file replacement cannot be built from a clipped line.
+ output = `IMPORTANT: Some lines exceed ${MAX_LINE_LENGTH} characters and were clipped in this view. ${offset1 === 1 ? "The file was read in full" : `The returned slice starts at line ${offset1} and reaches the end of the file`}, but the clipped lines were not shown in full.\n${result.content}`
} else if (result.returnedLines === 0 && result.totalLines === 0) {
output = "Note: File is empty"
}
- return output
+ // Complete only when the slice starts at line 1, returned every line, and
+ // showed every line in full (returnedLines === totalLines follows from the
+ // first two conditions): a partial start, a truncated tail, or a clipped
+ // line means the model did not see the whole file.
+ const complete = offset0 === 0 && !result.wasTruncated && !result.hasClippedLines
+
+ return { content: output, complete }
}
/**
@@ -770,9 +836,20 @@ export class ReadFileTool extends BaseTool<"read_file"> {
}
// Read text file
- const rawContent = await fs.readFile(fullPath, "utf8")
+ // A2 (epic #1375): capture the on-disk token before the read so a mutation
+ // landing mid-read is detected by the post-read stat below.
+ const preReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined)
+ const rawBuffer = await fs.readFile(fullPath)
+ const rawContent = rawBuffer.toString("utf-8")
+ // Same contract: a lossy decode is a partial view.
+ const lossyDecode = !Buffer.from(rawContent).equals(rawBuffer)
// Handle line ranges if specified
+ // S4b follow-up (#46 / epic #1375): a line-range read returns only the requested
+ // ranges, and a slice truncated to DEFAULT_LINE_LIMIT returns only the head of
+ // the file — record such observations as partial so the write guard denies a
+ // full-file update built on them.
+ let readComplete = false
let content: string
if (entry.lineRanges && entry.lineRanges.length > 0) {
const lines = rawContent.split("\n")
@@ -792,8 +869,16 @@ export class ReadFileTool extends BaseTool<"read_file"> {
// Read with default limits using slice mode
const result = readWithSlice(rawContent, 0, DEFAULT_LINE_LIMIT)
content = result.content
+ readComplete = !result.wasTruncated && !result.hasClippedLines
if (result.wasTruncated) {
content += `\n\n[File truncated: showing ${result.returnedLines} of ${result.totalLines} total lines]`
+ if (result.hasClippedLines) {
+ // Both notices: the slice was truncated and a line inside it was
+ // clipped.
+ content += `\n\n[Some lines exceed the per-line length cap and were clipped in this view]`
+ }
+ } else if (result.hasClippedLines) {
+ content += `\n\n[Some lines exceed the per-line length cap and were clipped in this view]`
}
}
@@ -801,6 +886,24 @@ export class ReadFileTool extends BaseTool<"read_file"> {
// Track file in context
await task.fileContextTracker.trackFileContext(relPath, "read_tool")
+
+ // A2 (plan #33 / epic #1375): mirror the native path — record the observed
+ // on-disk version so legacy-format reads also feed the future write guard.
+ // Observe only when the pre-read and post-read tokens match (a mutation between
+ // them means the returned content is not the on-disk state). A stat failure
+ // leaves the target unobserved and never fails the read.
+ // Same contract as the native path: an aborted or disposed task records nothing.
+ if (!task.abort) {
+ const postReadStats = await fs.stat(fullPath, { bigint: true }).catch(() => undefined)
+ // Re-checked after the await, as on the native path: a cancel landing
+ // during the stat must still record nothing.
+ if (preReadStats && postReadStats && !task.abort) {
+ const preReadToken = versionTokenOfStat(preReadStats)
+ if (preReadToken === versionTokenOfStat(postReadStats)) {
+ task.observationRegistry.observe(fullPath, preReadToken, readComplete && !lossyDecode)
+ }
+ }
+ }
} catch (error) {
const errorMsg = error instanceof Error ? error.message : String(error)
results.push(`File: ${relPath}\nError: ${errorMsg}`)
diff --git a/src/core/tools/__tests__/readFileTool.spec.ts b/src/core/tools/__tests__/readFileTool.spec.ts
index 52e04415ea..4a000a5154 100644
--- a/src/core/tools/__tests__/readFileTool.spec.ts
+++ b/src/core/tools/__tests__/readFileTool.spec.ts
@@ -14,13 +14,18 @@
import os from "os"
import path from "path"
+import type { Stats } from "fs"
+
+import type { LegacyReadFileParams } from "@roo-code/types"
import type { ToolUse } from "../../../shared/tools"
import type { Task, ToolExecutionContext } from "../../task/Task"
import { isBinaryFile } from "isbinaryfile"
+import { MAX_LINE_LENGTH } from "../../prompts/tools/native-tools/read_file"
import { readFileTool } from "../ReadFileTool"
+import { ObservationRegistry } from "../../task/observationRegistry"
import { formatResponse } from "../../prompts/responses"
import { validateImageForProcessing, processImageFile, isSupportedImageFormat } from "../helpers/imageHelpers"
import { extractTextFromFile, getSupportedBinaryFormats } from "../../../integrations/misc/extract-text"
@@ -135,13 +140,26 @@ interface MockTaskOptions {
rooIgnoreAllowed?: boolean
maxImageFileSize?: number
maxTotalImageSize?: number
+ observationRegistry?: ObservationRegistry
+ aborted?: boolean
}
function createMockTask(options: MockTaskOptions = {}) {
- const { supportsImages = false, rooIgnoreAllowed = true, maxImageFileSize = 5, maxTotalImageSize = 20 } = options
+ const {
+ supportsImages = false,
+ rooIgnoreAllowed = true,
+ maxImageFileSize = 5,
+ maxTotalImageSize = 20,
+ aborted = false,
+ } = options
return {
cwd: "/test/workspace",
+ // Mirror Task.abort: disposal and cancellation both set it before the loop resumes.
+ abort: aborted,
+ // Mirror Task: every task always owns an observation registry (A2, #1375).
+ // Tests asserting on observations pass their own instance via options.
+ observationRegistry: options.observationRegistry ?? new ObservationRegistry(),
api: {
getModel: vi.fn().mockReturnValue({
info: { supportsImages },
@@ -188,7 +206,18 @@ describe("ReadFileTool", () => {
vi.clearAllMocks()
// Default mock implementations
- mockedFsStat.mockResolvedValue({ isDirectory: () => false } as any)
+ // The stat default carries BigIntStats fields (A2, epic #1375): reads now
+ // token-ize the pre/post stats, so the default must look like a real bigint stat.
+ // Tests overriding it do so per-call with mockResolvedValue(Once).
+ mockedFsStat.mockResolvedValue({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats)
mockedIsBinaryFile.mockResolvedValue(false)
mockedFsReadFile.mockResolvedValue(Buffer.from("test content"))
mockedReadWithSlice.mockReturnValue({
@@ -975,7 +1004,7 @@ describe("ReadFileTool", () => {
mockTask.ask.mockResolvedValue({ response: "yesButtonClicked", text: undefined, images: undefined })
// fs.readFile with "utf8" encoding returns a string, not a Buffer
- mockedFsReadFile.mockResolvedValue("line1\nline2\nline3\nline4\nline5" as any)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("line1\nline2\nline3\nline4\nline5"))
await readFileTool.execute(
{ files: [{ path: "test.ts", lineRanges: [{ start: 2, end: 4 }] }] } as any,
@@ -1347,6 +1376,64 @@ describe("ReadFileTool", () => {
expect(callbacks.pushToolResult).toHaveBeenCalledWith(expect.stringContaining("To read more"))
})
+ it("should show a clipping notice in indentation mode separately from the omission notice", async () => {
+ const mockTask = createMockTask()
+ const callbacks = createMockCallbacks()
+
+ mockedFsReadFile.mockResolvedValue(Buffer.from("content"))
+ mockedReadWithIndentation.mockReturnValue({
+ content: "1 | block",
+ returnedLines: 10,
+ totalLines: 100,
+ wasTruncated: false,
+ hasClippedLines: true,
+ includedRanges: [[1, 10]],
+ })
+
+ await readFileTool.execute(
+ {
+ path: "test.ts",
+ mode: "indentation",
+ indentation: { anchor_line: 1 },
+ },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0] as string
+ expect(pushed).toContain("clipped in this view")
+ expect(pushed).not.toContain("File content truncated")
+ })
+
+ it("should report clipping alongside truncation in indentation mode", async () => {
+ const mockTask = createMockTask()
+ const callbacks = createMockCallbacks()
+
+ mockedFsReadFile.mockResolvedValue(Buffer.from("content"))
+ mockedReadWithIndentation.mockReturnValue({
+ content: "1 | block",
+ returnedLines: 50,
+ totalLines: 200,
+ wasTruncated: true,
+ hasClippedLines: true,
+ includedRanges: [[1, 50]],
+ })
+
+ await readFileTool.execute(
+ {
+ path: "test.ts",
+ mode: "indentation",
+ indentation: { anchor_line: 1 },
+ },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0] as string
+ expect(pushed).toContain("File content truncated")
+ expect(pushed).toContain("clipped in this view")
+ })
+
it("should include range information in indentation mode when not truncated", async () => {
const mockTask = createMockTask()
const callbacks = createMockCallbacks()
@@ -1688,5 +1775,1120 @@ describe("ReadFileTool", () => {
expect(mockTask.didToolFailInCurrentTurn).toBe(true)
})
+
+ describe("observation registry", () => {
+ // Indices of fs.stat calls against a path ending in fileName, filtered by
+ // whether the call passed { bigint: true }. Counting matching calls is
+ // the load-bearing form here: toHaveBeenCalledWith asserts membership,
+ // which the directory-check stat alone satisfies, and it cannot tell a
+ // skipped stat from one that ran.
+ const usesBigintOptions = (options: unknown): boolean =>
+ typeof options === "object" && options !== null && (options as { bigint?: unknown }).bigint === true
+ const statCallsMatching = (fileName: string, bigint: boolean): number[] =>
+ mockedFsStat.mock.calls
+ .map((_, index) => index)
+ .filter((index) => {
+ const [statPath, options] = mockedFsStat.mock.calls[index]
+ return String(statPath).endsWith(fileName) && usesBigintOptions(options) === bigint
+ })
+ // Vitest records invocationCallOrder parallel to mock.calls; comparing it
+ // against the readFile call tells the pre-read observation stat from the
+ // post-read one instead of trusting positional order by eye.
+ const statOrderBeforeRead = (statIndex: number): boolean =>
+ mockedFsStat.mock.invocationCallOrder[statIndex] < mockedFsReadFile.mock.invocationCallOrder[0]
+ it("records an observation on successful read of an existing file", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ // Override the beforeEach default stat mock with proper BigIntStats.
+ mockedFsStat.mockResolvedValue({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ // Spy on observe to capture the exact key used (Windows path.resolve may use backslashes).
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks)
+
+ // Verify the tool called observe exactly once with a valid token.
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, calledVersion] = observeSpy.mock.calls[0]
+ expect(calledPath).toContain("existing.ts")
+ expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/)
+
+ // Verify get() returns the same data using the spy-captured key.
+ const obs = reg.get(calledPath)
+ expect(obs).toBeDefined()
+ expect(obs!.version).toBe(calledVersion)
+ // Regression evidence: both observation stats must be bigint stats.
+ // Count the calls that match - correct path AND { bigint: true } -
+ // because a membership assertion passes on its own: the read path
+ // also stats the same path without options for the directory check.
+ const bigintStatIndexes = statCallsMatching("existing.ts", true)
+ expect(bigintStatIndexes).toHaveLength(2)
+ // Neither observation stat is a plain stat: the directory check stays
+ // the only stat without options...
+ expect(statCallsMatching("existing.ts", false)).toHaveLength(1)
+ // ...and the two bigint stats bracket the read: exactly one before it
+ // (pre-read observation) and exactly one after (post-read observation).
+ expect(bigintStatIndexes.filter((index) => statOrderBeforeRead(index))).toHaveLength(1)
+ expect(bigintStatIndexes.filter((index) => !statOrderBeforeRead(index))).toHaveLength(1)
+ })
+
+ it("a failed read (absent path) leaves the registry size 0 and does not throw", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsReadFile.mockRejectedValue(new Error("ENOENT"))
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "missing.ts" }, mockTask as unknown as Task, callbacks)
+
+ // observationRegistry is guaranteed present because we passed it in createMockTask.
+ const reg = mockTask.observationRegistry
+ expect(reg).toBeDefined()
+ expect(reg!.size).toBe(0)
+ })
+
+ it("records an observation for legacy-format reads of existing files", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Typed legacy (pre-refactor) params: the multi-file format with the
+ // _legacyFormat discriminant (see LegacyReadFileParams).
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, calledVersion] = observeSpy.mock.calls[0]
+ expect(calledPath).toContain("legacy.ts")
+ expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/)
+ // Regression evidence, same contract on the legacy path: count the
+ // matching calls (correct path AND { bigint: true }) instead of
+ // asserting membership, which the directory-check stat alone satisfies.
+ const bigintStatIndexes = statCallsMatching("legacy.ts", true)
+ expect(bigintStatIndexes).toHaveLength(2)
+ expect(statCallsMatching("legacy.ts", false)).toHaveLength(1)
+ // The two bigint stats bracket the read: pre-read before it, post-read after.
+ expect(bigintStatIndexes.filter((index) => statOrderBeforeRead(index))).toHaveLength(1)
+ expect(bigintStatIndexes.filter((index) => !statOrderBeforeRead(index))).toHaveLength(1)
+ })
+
+ it("does not observe when the file mutates between the pre-read and post-read stats", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const preStats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ }
+ // A mutation lands mid-read: the post-read stat differs.
+ const postStats = { ...preStats, size: BigInt(301) }
+
+ // Call order: directory check, pre-read stat, post-read stat.
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockResolvedValueOnce(preStats as unknown as Stats)
+ .mockResolvedValueOnce(postStats as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "mutated.ts" }, mockTask as unknown as Task, callbacks)
+
+ // The read itself succeeded, but the target stays unobserved: the content the
+ // model received is not the on-disk state, so observing it would let a later
+ // write match a token the model never saw.
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ })
+
+ it("records nothing when the task is aborted before the post-read stat (native path)", async () => {
+ // Task.disposeOnce() sets abort before an awaited read resumes, and abortTask()
+ // sets it on cancellation. The read still answers the model, but the observation -
+ // and the post-read stat work behind it - must not repopulate a retired registry.
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ aborted: true,
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ // The abort must skip only the post-read observation: the pre-read
+ // observation stat is still issued, and no bigint stat follows the
+ // read. Counted by matching calls (correct path AND { bigint: true }):
+ // a membership assertion cannot tell "post-stat skipped" from
+ // "post-stat ran".
+ const bigintStatIndexes = statCallsMatching("existing.ts", true)
+ expect(bigintStatIndexes).toHaveLength(1)
+ // The single bigint stat ran before the read: it is the pre-read one.
+ expect(statOrderBeforeRead(bigintStatIndexes[0])).toBe(true)
+ // The directory-check stat is untouched: still exactly one plain stat.
+ expect(statCallsMatching("existing.ts", false)).toHaveLength(1)
+ })
+
+ it("records nothing when the task is aborted before the post-read stat (legacy path)", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ aborted: true,
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ // Same contract on the legacy path: the pre-read observation stat is
+ // still issued and the post-read one is skipped - counted by matching
+ // calls, not by membership.
+ const bigintStatIndexes = statCallsMatching("legacy.ts", true)
+ expect(bigintStatIndexes).toHaveLength(1)
+ expect(statOrderBeforeRead(bigintStatIndexes[0])).toBe(true)
+ expect(statCallsMatching("legacy.ts", false)).toHaveLength(1)
+ })
+
+ it("records nothing when the task is cancelled while the post-read stat is in flight (native path)", async () => {
+ // The guard before the stat cannot see a cancellation that lands DURING the
+ // stat. The re-check before observe() is what keeps a read that belongs to a
+ // cancelled run out of the registry - and out of a registry that disposal has
+ // already retired.
+ const mockTask = createMockTask({ observationRegistry: new ObservationRegistry() })
+ const callbacks = createMockCallbacks()
+
+ const stats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) // directory check
+ .mockResolvedValueOnce(stats) // pre-read
+ .mockImplementationOnce(async () => {
+ // The cancel lands while this await is pending.
+ mockTask.abort = true
+ return stats
+ }) // post-read
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "existing.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ // The read itself still answered the model; only the observation is withheld.
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ })
+
+ it("records nothing when the task is cancelled while the post-read stat is in flight (legacy path)", async () => {
+ const mockTask = createMockTask({ observationRegistry: new ObservationRegistry() })
+ const callbacks = createMockCallbacks()
+
+ const stats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ // Cast: the mock only implements the members the tool and versionToken read.
+ } as unknown as Stats
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats) // directory check
+ .mockResolvedValueOnce(stats) // pre-read
+ .mockImplementationOnce(async () => {
+ // The cancel lands while this await is pending.
+ mockTask.abort = true
+ return stats
+ }) // post-read
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ })
+
+ it("leaves the target unobserved without failing the read when the pre-read stat fails", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ // Directory check OK; the pre-read stat fails (caught, target unobserved).
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockRejectedValueOnce(new Error("EACCES"))
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "stat-fail.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ // The read still succeeds — a stat failure never fails the read.
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ // Assert the pushed payload, not just that something was pushed.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("File: stat-fail.ts")
+ expect(pushed).toContain("test content")
+ expect(pushed).not.toContain("Error:")
+ })
+
+ it("leaves the target unobserved without failing the read when the post-read stat fails", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const okStats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ }
+ // Directory check and pre-read stat OK; the post-read stat fails.
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockResolvedValueOnce(okStats as unknown as Stats)
+ .mockRejectedValueOnce(new Error("EACCES"))
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute({ path: "post-stat-fail.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ // Assert the pushed payload, not just that something was pushed.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("File: post-stat-fail.ts")
+ expect(pushed).toContain("test content")
+ expect(pushed).not.toContain("Error:")
+ })
+
+ it("legacy format: does not observe when the file mutates between the pre-read and post-read stats", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const preStats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ }
+ // Call order: directory check, pre-read stat, post-read stat (mutated).
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockResolvedValueOnce(preStats as unknown as Stats)
+ .mockResolvedValueOnce({ ...preStats, size: BigInt(301) } as unknown as Stats)
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-mutated.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ })
+
+ it("legacy format: leaves the target unobserved when a stat fails without failing the read", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ // Directory check OK; the pre-read stat fails (caught, target unobserved).
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockRejectedValueOnce(new Error("EACCES"))
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-stat-fail.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ // Assert the pushed payload, not just that something was pushed.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("File: legacy-stat-fail.ts")
+ expect(pushed).toContain("test content")
+ expect(pushed).not.toContain("Error:")
+ })
+ it("legacy format: leaves the target unobserved when the post-read stat fails", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const okStats = {
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ }
+ // Directory check and pre-read stat OK; the post-read stat fails.
+ mockedFsStat
+ .mockResolvedValueOnce({ isDirectory: () => false } as unknown as Stats)
+ .mockResolvedValueOnce(okStats as unknown as Stats)
+ .mockRejectedValueOnce(new Error("EACCES"))
+ mockedIsBinaryFile.mockResolvedValue(false)
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-post-stat-fail.ts" }],
+ _legacyFormat: true,
+ }
+
+ // Cast: the mock task only implements the members ReadFileTool.execute touches.
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).not.toHaveBeenCalled()
+ expect(reg.size).toBe(0)
+ expect(mockTask.didToolFailInCurrentTurn).toBe(false)
+ // Assert the pushed payload, not just that something was pushed.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("File: legacy-post-stat-fail.ts")
+ expect(pushed).toContain("test content")
+ expect(pushed).not.toContain("Error:")
+ })
+ it("two separate Task-owned registries are independent", async () => {
+ const regA = new ObservationRegistry()
+ const regB = new ObservationRegistry()
+ regA.observe("/shared.ts", "v1")
+ expect(regA.get("/shared.ts")!.version).toBe("v1")
+ expect(regB.get("/shared.ts")).toBeUndefined()
+ regB.observe("/shared.ts", "v2")
+ expect(regA.get("/shared.ts")!.version).toBe("v1")
+ expect(regB.get("/shared.ts")!.version).toBe("v2")
+ })
+ })
+
+ describe("read completeness scope (S4b follow-up #46)", () => {
+ // The stat mock only implements the members the tool and versionToken read.
+ const bigintStats = (): Stats =>
+ ({
+ isDirectory: () => false,
+ dev: BigInt(1),
+ ino: BigInt(2),
+ size: BigInt(300),
+ mtimeNs: BigInt(4_000_000_000n),
+ ctimeNs: BigInt(5_000_000_000n),
+ }) as unknown as Stats
+
+ it("native: a full, untruncated slice read from line 1 records a complete observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 2,
+ wasTruncated: false,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute({ path: "full.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, calledVersion, calledComplete] = observeSpy.mock.calls[0]
+ expect(calledPath).toContain("full.ts")
+ expect(calledVersion).toMatch(/^\d+:\d+:\d+:\d+:\d+$/)
+ expect(calledComplete).toBe(true)
+ expect(reg.get(calledPath)!.complete).toBe(true)
+ })
+
+ it("native: a truncated slice read records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a",
+ returnedLines: 1,
+ totalLines: 5,
+ wasTruncated: true,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute(
+ { path: "trunc.ts", offset: 1, limit: 1 },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ expect(reg.get(calledPath)!.complete).toBe(false)
+ })
+
+ it("native: a full read whose line content was clipped records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 2,
+ wasTruncated: false,
+ hasClippedLines: true,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute({ path: "clipped.ts" }, mockTask as unknown as Task, callbacks)
+
+ const [, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ // Every line was returned, so the notice must not point at a next
+ // offset that is beyond the file.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("clipped in this view")
+ expect(pushed).not.toContain("To read more")
+ // The notice is added on top of the read, it does not replace it.
+ expect(pushed).toContain("1 | a")
+ })
+
+ it("native: a clipped full read joins the notice and the read with the exact separator", async () => {
+ // Review row 4202836427: in the clipped-but-not-truncated branch the two
+ // sentences and the read are joined by a specific separator, and that join is
+ // what tells the model every line was returned but some were cut. Assert the
+ // separator and both ends of the response rather than a loose substring.
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\n"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 2,
+ wasTruncated: false,
+ hasClippedLines: true,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute(
+ { path: "clipped-full.ts", offset: 1 },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ // The header line and the notice are adjacent: the notice is the first thing
+ // after the file identity, and the character cap it names is the one the tool
+ // actually applied.
+ expect(
+ pushed.startsWith(
+ `File: clipped-full.ts\nIMPORTANT: Some lines exceed ${MAX_LINE_LENGTH} characters and were clipped in this view.`,
+ ),
+ ).toBe(true)
+ expect(pushed).toContain(
+ "were clipped in this view. The file was read in full, but the clipped lines were not shown in full.",
+ )
+ expect(pushed.endsWith("were not shown in full.\n1 | a\n2 | b")).toBe(true)
+ expect(pushed).toContain("The file was read in full")
+ // Every line was returned, so the notice must not advertise a next offset.
+ expect(pushed).not.toContain("To read more")
+ // The read stays incomplete: the clipped tails were never shown, so a
+ // full-file replacement must not be built from this view.
+ const [, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ })
+ it("native: a clipped slice that starts after line 1 names the slice instead of claiming a full read", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne\n"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "3 | c\n4 | d",
+ returnedLines: 2,
+ totalLines: 5,
+ wasTruncated: false,
+ hasClippedLines: true,
+ includedRanges: [[3, 4]],
+ })
+
+ await readFileTool.execute(
+ { path: "clipped-slice.ts", offset: 3 },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("clipped in this view")
+ // Lines 1-2 were omitted, so the notice must describe the slice that was
+ // returned rather than claim the whole file was read.
+ expect(pushed).toContain("starts at line 3")
+ expect(pushed).not.toContain("The file was read in full")
+ expect(pushed).toContain("3 | c")
+ })
+
+ it("native: a truncated slice that also clipped a line reports both notices", async () => {
+ // A long line inside a slice that also cut lines off is a plausible case,
+ // and the response has to say both things.
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 3,
+ wasTruncated: true,
+ hasClippedLines: true,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute({ path: "both.ts" }, mockTask as unknown as Task, callbacks)
+
+ const [, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("Showing lines 1-2 of 3 total lines")
+ expect(pushed).toContain("clipped in this view")
+ })
+
+ it("native: an offset read that is not truncated still records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "4 | d\n5 | e",
+ returnedLines: 2,
+ totalLines: 5,
+ wasTruncated: false,
+ includedRanges: [[4, 5]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute(
+ { path: "offset.ts", offset: 4, limit: 2 },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [_calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ })
+
+ it("native: an indentation-mode block read records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("function f() { return 1 }"))
+ mockedReadWithIndentation.mockReturnValue({
+ content: "10 | function f() {",
+ wasTruncated: false,
+ includedRanges: [[10, 20]],
+ totalLines: 100,
+ returnedLines: 11,
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute(
+ { path: "indent.ts", mode: "indentation" },
+ mockTask as unknown as Task,
+ callbacks,
+ )
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [_calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ })
+
+ it("legacy: a line-range read records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc\nd\ne"))
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "ranges.ts", lineRanges: [{ start: 2, end: 4 }] }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledPath).toContain("ranges.ts")
+ expect(calledComplete).toBe(false)
+ })
+
+ it("legacy: a full, untruncated slice read records a complete observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 2,
+ wasTruncated: false,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-full.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [_calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(true)
+
+ // Nothing was omitted and nothing was clipped, so no note is added.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).not.toContain("clipped in this view")
+ expect(pushed).not.toContain("total lines")
+ })
+
+ it("legacy: a full read with a clipped line records a partial observation and reports the clipping", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 2,
+ wasTruncated: false,
+ hasClippedLines: true,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-clipped.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ const [, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+
+ // Every line was returned, so the note reports the clipping instead of
+ // a showing-N-of-N count that would point past the file.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("clipped in this view")
+ expect(pushed).not.toContain("showing 2 of 2 total lines")
+ })
+
+ it("legacy: a truncated slice that also clipped a line reports both notices", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\n2 | b",
+ returnedLines: 2,
+ totalLines: 3,
+ wasTruncated: true,
+ hasClippedLines: true,
+ includedRanges: [[1, 2]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-both.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ const [, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("showing 2 of 3 total lines")
+ expect(pushed).toContain("clipped in this view")
+ })
+
+ it("legacy: a slice truncated to the default limit records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(Buffer.from("a\nb\nc"))
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a",
+ returnedLines: 1,
+ totalLines: 5000,
+ wasTruncated: true,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-trunc.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [_calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+
+ // Lines were omitted here, so the note reports the omitted range rather
+ // than clipping.
+ const pushed = callbacks.pushToolResult.mock.calls[0][0]
+ expect(pushed).toContain("showing 1 of 5000 total lines")
+ })
+
+ it("native: a read whose bytes did not survive the UTF-8 decode records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ // 0xFF is not valid UTF-8, so the model receives U+FFFD instead of the byte.
+ const raw = Buffer.from([0x61, 0xff])
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(raw)
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\uFFFD",
+ returnedLines: 1,
+ totalLines: 1,
+ wasTruncated: false,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute({ path: "lossy.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ expect(reg.get(calledPath)!.complete).toBe(false)
+ })
+
+ // Positive control for the row above: EF BF BD is valid UTF-8, so a file that already
+ // carries a U+FFFD decodes and re-encodes to the same bytes and the read is complete. The
+ // row above asserts only the partial direction, and it would still pass if the writer marked
+ // every U+FFFD it saw as a lossy decode.
+ it("native: a file that already contains a U+FFFD byte sequence is a complete read", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const raw = Buffer.from([0x61, 0xef, 0xbf, 0xbd])
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(raw)
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\uFFFD",
+ returnedLines: 1,
+ totalLines: 1,
+ wasTruncated: false,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ await readFileTool.execute({ path: "already-lossy.ts" }, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(true)
+ expect(reg.get(calledPath)!.complete).toBe(true)
+ })
+
+ it("legacy: a read whose bytes did not survive the UTF-8 decode records a partial observation", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const raw = Buffer.from([0x61, 0xff])
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(raw)
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\uFFFD",
+ returnedLines: 1,
+ totalLines: 1,
+ wasTruncated: false,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-lossy.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(false)
+ expect(reg.get(calledPath)!.complete).toBe(false)
+ })
+ // Positive control for the row above: EF BF BD is valid UTF-8, so a file that already
+ // carries a U+FFFD decodes and re-encodes to the same bytes and the read is complete. The
+ // row above asserts only the partial direction, and it would still pass if the writer marked
+ // every U+FFFD it saw as a lossy decode.
+ it("legacy: a file that already contains a U+FFFD byte sequence is a complete read", async () => {
+ const mockTask = createMockTask({
+ observationRegistry: new ObservationRegistry(),
+ })
+ const callbacks = createMockCallbacks()
+
+ const raw = Buffer.from([0x61, 0xef, 0xbf, 0xbd])
+ mockedFsStat.mockResolvedValue(bigintStats())
+ mockedIsBinaryFile.mockResolvedValue(false)
+ mockedFsReadFile.mockResolvedValue(raw)
+ mockedReadWithSlice.mockReturnValue({
+ content: "1 | a\uFFFD",
+ returnedLines: 1,
+ totalLines: 1,
+ wasTruncated: false,
+ includedRanges: [[1, 1]],
+ })
+
+ const reg = mockTask.observationRegistry!
+ const observeSpy = vi.spyOn(reg, "observe")
+
+ const legacyParams: LegacyReadFileParams = {
+ files: [{ path: "legacy-already-lossy.ts" }],
+ _legacyFormat: true,
+ }
+
+ await readFileTool.execute(legacyParams, mockTask as unknown as Task, callbacks)
+
+ expect(observeSpy).toHaveBeenCalledTimes(1)
+ const [calledPath, , calledComplete] = observeSpy.mock.calls[0]
+ expect(calledComplete).toBe(true)
+ expect(reg.get(calledPath)!.complete).toBe(true)
+ })
+ })
})
})
diff --git a/src/eslint-suppressions.json b/src/eslint-suppressions.json
index ae3d504003..f3714cd1f5 100644
--- a/src/eslint-suppressions.json
+++ b/src/eslint-suppressions.json
@@ -861,7 +861,7 @@
},
"core/tools/__tests__/readFileTool.spec.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 96
+ "count": 94
}
},
"core/tools/__tests__/runSlashCommandTool.spec.ts": {
diff --git a/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts b/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts
index bfc397cf09..1d41ac30f3 100644
--- a/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts
+++ b/src/integrations/misc/__tests__/indentation-reader-unicode.spec.ts
@@ -74,6 +74,7 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 3,
returnedLines: 1,
wasTruncated: true,
+ hasClippedLines: true,
})
expect(Buffer.from(result.content).toString("utf8")).toBe(result.content)
})
@@ -89,6 +90,8 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 3,
returnedLines: 1,
wasTruncated: true,
+ // The returned line is clipped, so the flag belongs to the result.
+ hasClippedLines: true,
})
expect(Buffer.from(result.content).toString("utf8")).toBe(result.content)
})
@@ -104,6 +107,8 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 5,
returnedLines: 3,
wasTruncated: false,
+ // The block shows every line it includes, but one is clipped.
+ hasClippedLines: true,
})
expect(Buffer.from(result.content).toString("utf8")).toBe(result.content)
})
@@ -115,6 +120,7 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 1,
returnedLines: 1,
wasTruncated: false,
+ hasClippedLines: true,
})
expect(readWithSlice("")).toEqual({
content: "1 | ",
@@ -122,6 +128,7 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 1,
returnedLines: 1,
wasTruncated: false,
+ hasClippedLines: false,
})
})
@@ -132,6 +139,7 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 1,
returnedLines: 0,
wasTruncated: false,
+ hasClippedLines: false,
})
expect(readWithIndentation(longLine, { anchorLine: 0 })).toEqual({
content: "Error: anchor_line 0 is out of range (1-1)",
@@ -139,6 +147,7 @@ describe("Unicode clipping through the existing readers", () => {
totalLines: 1,
returnedLines: 0,
wasTruncated: false,
+ hasClippedLines: false,
})
})
})
diff --git a/src/integrations/misc/__tests__/indentation-reader.spec.ts b/src/integrations/misc/__tests__/indentation-reader.spec.ts
index a092dff8fc..622a150235 100644
--- a/src/integrations/misc/__tests__/indentation-reader.spec.ts
+++ b/src/integrations/misc/__tests__/indentation-reader.spec.ts
@@ -1,4 +1,5 @@
import { describe, it, expect } from "vitest"
+import { MAX_LINE_LENGTH } from "../../../core/prompts/tools/native-tools/read_file"
import {
parseLines,
formatWithLineNumbers,
@@ -278,11 +279,45 @@ describe("readWithSlice", () => {
expect(result.wasTruncated).toBe(true)
})
+ it("reports a clipped line separately from omitted lines", () => {
+ // Every line is returned, but formatWithLineNumbers clips a line longer
+ // than MAX_LINE_LENGTH, so the model did not see the whole file.
+ const lines = ["x".repeat(MAX_LINE_LENGTH + 10), "short"].join("\n")
+ const result = readWithSlice(lines, 0, 10)
+
+ expect(result.returnedLines).toBe(2)
+ expect(result.wasTruncated).toBe(false)
+ expect(result.hasClippedLines).toBe(true)
+ })
+
+ it("keeps a slice complete when a line is exactly at the length cap", () => {
+ // formatWithLineNumbers clips only lines strictly longer than the cap, so a
+ // line at exactly MAX_LINE_LENGTH is shown in full and the read is complete.
+ const lines = ["x".repeat(MAX_LINE_LENGTH), "short"].join("\n")
+ const result = readWithSlice(lines, 0, 10)
+
+ expect(result.returnedLines).toBe(2)
+ expect(result.wasTruncated).toBe(false)
+ expect(result.hasClippedLines).toBe(false)
+ })
+
+ it("flags clipping when any line is clipped, not only when every line is", () => {
+ // The first line is clipped and the second is shown in full: some lines are
+ // a partial view even though every line was returned.
+ const lines = ["y".repeat(MAX_LINE_LENGTH + 1), "short"].join("\n")
+ const result = readWithSlice(lines, 0, 10)
+
+ expect(result.returnedLines).toBe(2)
+ expect(result.hasClippedLines).toBe(true)
+ })
+
it("should handle offset beyond file end", () => {
const result = readWithSlice(SIMPLE_CODE, 1000, 10)
expect(result.returnedLines).toBe(0)
expect(result.content).toContain("Error: offset 1001 is beyond file end")
+ // No line was returned, so nothing could have been clipped.
+ expect(result.hasClippedLines).toBe(false)
})
it("should handle negative offset", () => {
@@ -296,6 +331,53 @@ describe("readWithSlice", () => {
// ─── readWithIndentation Tests ────────────────────────────────────────────────
describe("readWithIndentation", () => {
+ it("reports an out-of-range anchor as an error with no clipping", () => {
+ const result = readWithIndentation(SIMPLE_CODE, { anchorLine: 1000 })
+
+ expect(result.content).toContain("out of range")
+ expect(result.returnedLines).toBe(0)
+ expect(result.hasClippedLines).toBe(false)
+ })
+
+ it("flags a clipped line in the single-line limit case", () => {
+ // finalLimit === 1 returns only the anchor line, and formatWithLineNumbers
+ // clips it when it exceeds the cap: the flag must still be set.
+ const code = ["short()", `long(${"x".repeat(MAX_LINE_LENGTH + 5)})`, "tail()"].join("\n")
+ const result = readWithIndentation(code, { anchorLine: 2, limit: 1 })
+
+ expect(result.returnedLines).toBe(1)
+ expect(result.hasClippedLines).toBe(true)
+ })
+
+ it("keeps the single-line limit case unflagged when the line fits the cap", () => {
+ // Clipping is strictly-longer-than-cap, so a line at exactly the cap is
+ // shown in full and the read carries no clipping flag.
+ const code = ["short()", `fits(${"y".repeat(MAX_LINE_LENGTH - 6)})`, "tail()"].join("\n")
+ const result = readWithIndentation(code, { anchorLine: 2, limit: 1 })
+
+ expect(result.returnedLines).toBe(1)
+ expect(result.hasClippedLines).toBe(false)
+ })
+
+ it("flags a clipped line inside an expanded block", () => {
+ // The expansion returns every line of the block, but the long one is
+ // clipped in the returned view: the flag must be set even with no
+ // omission.
+ const code = ["start()", `long(${"x".repeat(MAX_LINE_LENGTH + 1)})`, "end()"].join("\n")
+ const result = readWithIndentation(code, { anchorLine: 2, limit: 10 })
+
+ expect(result.returnedLines).toBeGreaterThan(1)
+ expect(result.hasClippedLines).toBe(true)
+ })
+
+ it("keeps an expanded block unflagged when every line fits the cap", () => {
+ const code = ["start()", "mid()", "end()"].join("\n")
+ const result = readWithIndentation(code, { anchorLine: 2, limit: 10 })
+
+ expect(result.returnedLines).toBeGreaterThan(1)
+ expect(result.hasClippedLines).toBe(false)
+ })
+
describe("basic block extraction", () => {
it("should extract content around the anchor line", () => {
const result = readWithIndentation(PYTHON_CODE, {
diff --git a/src/integrations/misc/indentation-reader.ts b/src/integrations/misc/indentation-reader.ts
index 43e86a47ad..ff324738a3 100644
--- a/src/integrations/misc/indentation-reader.ts
+++ b/src/integrations/misc/indentation-reader.ts
@@ -58,8 +58,10 @@ export interface IndentationReadResult {
totalLines: number
/** Lines actually returned */
returnedLines: number
- /** Whether output was truncated due to limit */
+ /** Whether output was truncated because lines were omitted */
wasTruncated: boolean
+ /** Whether any returned line was clipped by the per-line length cap */
+ hasClippedLines?: boolean
}
// ─── Constants ────────────────────────────────────────────────────────────────
@@ -244,6 +246,7 @@ export function readWithIndentation(content: string, options: IndentationReadOpt
totalLines,
returnedLines: 0,
wasTruncated: false,
+ hasClippedLines: false,
}
}
@@ -276,6 +279,9 @@ export function readWithIndentation(content: string, options: IndentationReadOpt
totalLines,
returnedLines: 1,
wasTruncated: totalLines > 1,
+ // The single-line case is no exception to the clipping contract:
+ // formatWithLineNumbers clips this line when it exceeds the cap.
+ hasClippedLines: lines[anchorIdx].content.length > MAX_LINE_LENGTH,
}
}
@@ -358,6 +364,10 @@ export function readWithIndentation(content: string, options: IndentationReadOpt
totalLines,
returnedLines: result.length,
wasTruncated: wasTruncated && result.length < totalLines,
+ // The expansion path reports clipping like the slice path: a block can
+ // return every line it includes and still hide content behind the
+ // per-line length cap.
+ hasClippedLines: result.some((line) => line.content.length > MAX_LINE_LENGTH),
}
}
@@ -386,6 +396,7 @@ export function readWithSlice(
totalLines,
returnedLines: 0,
wasTruncated: false,
+ hasClippedLines: false,
}
}
@@ -393,6 +404,11 @@ export function readWithSlice(
const endIdx = Math.min(offset + limit, totalLines)
const selectedLines = lines.slice(offset, endIdx)
const wasTruncated = endIdx < totalLines
+ // A returned line can still be a partial view: formatWithLineNumbers clips a
+ // line longer than MAX_LINE_LENGTH, so a slice that returned every line may
+ // still hide content. Clipping is reported separately from omission so the
+ // caller does not suggest a next offset that is beyond the file.
+ const hasClippedLines = selectedLines.some((line) => line.content.length > MAX_LINE_LENGTH)
// Format output
const formattedContent = formatWithLineNumbers(selectedLines)
@@ -403,5 +419,6 @@ export function readWithSlice(
totalLines,
returnedLines: selectedLines.length,
wasTruncated,
+ hasClippedLines,
}
}
diff --git a/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts b/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts
new file mode 100644
index 0000000000..4a3ee6e8e5
--- /dev/null
+++ b/src/services/file-safety/__tests__/safeWriteText.integration.spec.ts
@@ -0,0 +1,70 @@
+import * as fs from "fs/promises"
+import * as os from "os"
+import * as path from "path"
+
+import { safeWriteText } from "../safeWriteText"
+
+// No fs mocks in this file: the point is to assert what a real filesystem ends up
+// holding after a publish attempt, which the mocked spec cannot show. The failure is
+// provoked with real filesystem semantics rather than with a stubbed call.
+describe("safeWriteText against a real filesystem", () => {
+ let dir: string
+
+ beforeEach(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "safe-write-text-int-"))
+ })
+
+ afterEach(async () => {
+ await fs.rm(dir, { recursive: true, force: true })
+ })
+
+ it("publishes the new bytes and leaves no staging or backup residue", async () => {
+ const targetPath = path.join(dir, "target.txt")
+ await fs.writeFile(targetPath, "old bytes")
+
+ // No platform override: the real platform's own durability and ACL steps run, and this
+ // case is the successful restore. A failed restore now throws DaclRestoreError after
+ // the commit rename has already happened (the focused unit test "win32 DACL: a failed
+ // restore is an error and the dump is still unlinked" covers that path), so on a
+ // machine where icacls cannot put a saved ACL back into a throwaway temp directory
+ // this publish reports that error instead of resolving, and the residue assertions
+ // below are reached only where the restore worked.
+ await safeWriteText(targetPath, "new bytes", { backup: true })
+
+ expect(await fs.readFile(targetPath, "utf8")).toBe("new bytes")
+ expect(await fs.readdir(dir)).toEqual(["target.txt"])
+ })
+
+ it("leaves the target bytes untouched when the commit cannot replace it", async () => {
+ // A regular file cannot be renamed over a directory, so the backup copy and
+ // the commit both fail on a real filesystem with no mocking at all.
+ const targetPath = path.join(dir, "target-dir")
+ await fs.mkdir(targetPath)
+ const inside = path.join(targetPath, "payload.txt")
+ await fs.writeFile(inside, "original bytes")
+
+ await expect(safeWriteText(targetPath, "new data", { backup: true })).rejects.toThrow()
+
+ // The directory and its content are exactly as they were, and no backup copy
+ // or staging directory was left behind next to them.
+ expect(await fs.readFile(inside, "utf8")).toBe("original bytes")
+ expect(await fs.readdir(dir)).toEqual(["target-dir"])
+ })
+
+ it("cleans up the staging file when the commit rename itself fails", async () => {
+ // With backup:false the backup step is skipped, so this is the only shape of
+ // this scenario that reaches Step 4: the rename of the staging FILE over the
+ // target DIRECTORY fails (EISDIR / ENOTDIR / EPERM depending on platform), and
+ // the cleanup must remove the staging file. The backup:true case above bails
+ // out in the backup step and never exercises the commit-failure path.
+ const targetPath = path.join(dir, "target-dir")
+ await fs.mkdir(targetPath)
+ const inside = path.join(targetPath, "payload.txt")
+ await fs.writeFile(inside, "original bytes")
+
+ await expect(safeWriteText(targetPath, "new data", { backup: false })).rejects.toThrow()
+
+ expect(await fs.readFile(inside, "utf8")).toBe("original bytes")
+ expect(await fs.readdir(dir)).toEqual(["target-dir"])
+ })
+})
diff --git a/src/services/file-safety/__tests__/safeWriteText.spec.ts b/src/services/file-safety/__tests__/safeWriteText.spec.ts
new file mode 100644
index 0000000000..fc8f30e212
--- /dev/null
+++ b/src/services/file-safety/__tests__/safeWriteText.spec.ts
@@ -0,0 +1,1553 @@
+import * as fs from "fs/promises"
+import * as fsSync from "fs"
+import { execFile } from "child_process"
+import type { ChildProcess } from "child_process"
+import * as path from "path"
+
+import {
+ DaclInspectionError,
+ DaclRestoreError,
+ PostCommitDurabilityError,
+ resolveLockKey,
+ safeWriteText,
+ StagingPathError,
+} from "../safeWriteText"
+
+// Full mock for fs/promises — all methods are vi.fn() stubs
+vi.mock("fs/promises", () => ({
+ copyFile: vi.fn(),
+ chmod: vi.fn(),
+ mkdir: vi.fn(),
+ access: vi.fn(),
+ rename: vi.fn(),
+ unlink: vi.fn(),
+ rmdir: vi.fn(),
+ realpath: vi.fn(),
+ lstat: vi.fn(),
+ readlink: vi.fn(),
+}))
+
+// Full mock for fs — all sync methods are vi.fn() stubs. Stats is a bare
+// class stub so tests can build minimal Stats stand-ins via its prototype.
+vi.mock("fs", () => ({
+ openSync: vi.fn(),
+ writeSync: vi.fn(),
+ closeSync: vi.fn(),
+ mkdirSync: vi.fn(),
+ fsyncSync: vi.fn(),
+ chmodSync: vi.fn(),
+ fchmodSync: vi.fn(),
+ statSync: vi.fn(),
+ Stats: class Stats {},
+}))
+
+// Mock child_process.execFile (callback-based — must invoke callback to resolve)
+vi.mock("child_process", () => ({
+ execFile: vi.fn((cmd, args, opts, cb) => {
+ if (typeof cb === "function") cb(null)
+ }),
+}))
+
+// Minimal stand-in for the ChildProcess that callback-form execFile returns.
+const fakeChild = { kill: () => true } as unknown as ChildProcess
+
+// Helper that mirrors safeWriteText's path resolution exactly
+function _resolvedTarget(filePath: string): string {
+ return path.resolve(filePath)
+}
+function _dirPath(filePath: string): string {
+ return path.dirname(_resolvedTarget(filePath))
+}
+// Minimal Stats stand-in: the SUT only reads `.mode` from it.
+// Async lstat stand-in: the SUT only asks whether the path is a link or a file.
+// Built on the Stats prototype so the mock value still satisfies fsSync.Stats.
+function _fileStats(isLink: boolean): fsSync.Stats {
+ const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats
+ s.isSymbolicLink = () => isLink
+ s.isFile = () => !isLink
+ return s
+}
+
+// fs.BigIntStats is a type-only export (fs.BigIntStats is undefined at runtime), so the stand-in is
+// a Stats object carrying bigint ino/dev - exactly what fs.lstat(path, { bigint: true }) hands
+// back at runtime.
+function _fileStatsWithIdentity(ino: bigint, dev: bigint): fsSync.BigIntStats {
+ // Double assertion: the runtime value is the Stats stand-in, the type is the bigint variant.
+ const s = _fileStats(false) as unknown as fsSync.BigIntStats
+ s.ino = ino
+ s.dev = dev
+ return s
+}
+
+function mockDefaults(): void {
+ vi.resetAllMocks()
+ // After resetAllMocks, vi.fn() returns undefined — restore promise defaults.
+ vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+ vi.mocked(fs.access).mockResolvedValue(undefined)
+ vi.mocked(fs.rename).mockResolvedValue(undefined)
+ vi.mocked(fs.unlink).mockResolvedValue(undefined)
+ vi.mocked(fs.rmdir).mockResolvedValue(undefined)
+ // Existing-target default: a regular 0o644 file.
+ vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o644))
+ // Staged-file default: a regular file, not a link, so a caller-supplied
+ // tempPath passes the location and file-type check by default.
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false))
+}
+function _stats(mode: number): fsSync.Stats {
+ const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats
+ Object.assign(s, { mode })
+ return s
+}
+
+// ── Test 1: staging file created then cleaned after success ────────────────
+
+describe("safeWriteText", () => {
+ beforeEach(() => {
+ mockDefaults()
+ // Default sync-write behaviour: report that all requested bytes were
+ // written. The Buffer overload passes (fd, buffer, offset, length),
+ // so the fourth argument is the requested length.
+ vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) =>
+ typeof args[3] === "number" ? args[3] : 0,
+ )
+ })
+
+ describe("staging and cleanup", () => {
+ it("creates a temp file in the staging dir, fsyncs it, renames to target, and cleans up on success", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1) // fd=1
+ vi.mocked(fsSync.closeSync).mockReturnValue(undefined)
+
+ await safeWriteText(targetPath, "hello world", { platform: "linux" })
+
+ // staging dir was created with private permissions — use
+ // stringContaining to handle Windows path resolution
+ expect(fsSync.mkdirSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), {
+ recursive: true,
+ mode: 0o700,
+ })
+ // a pre-existing staging dir is repaired to private permissions too
+ expect(fsSync.chmodSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), 0o700)
+
+ // temp file was opened for writing with the existing target's mode
+ // (default 0o644 from the statSync default mock)
+ expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o644)
+
+ // content was written as a buffer (partial-write loop, full write)
+ expect(fsSync.writeSync).toHaveBeenCalledWith(1, Buffer.from("hello world", "utf8"), 0, 11)
+
+ // fsync (sync form) was called on the fd
+ expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+
+ // file was closed
+ expect(fsSync.closeSync).toHaveBeenCalledWith(1)
+
+ // atomic rename happened — realpath mock returns targetPath, so that's the dest
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // no unlink of temp (it's now the committed file; DACL skipped via platform:linux)
+ expect(fs.unlink).not.toHaveBeenCalled()
+ })
+
+ it("removes the now-empty staging directory after a successful self-staged commit", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "hello", { platform: "linux" })
+
+ // the staging subdir is removed best-effort after the commit rename
+ // (stringContaining: the SUT and the test helper resolve Windows
+ // drive-relative paths differently, as in the existing staging tests)
+ expect(fs.rmdir).toHaveBeenCalledTimes(1)
+ expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"))
+ // the win32 DACL restore gate must stay closed on other platforms:
+ // no icacls save or restore is attempted
+ expect(execFile).not.toHaveBeenCalled()
+ })
+
+ it("still removes the staging directory when no options are supplied at all", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ // options is undefined: the self-staged check and the optional-chained
+ // DACL runner lookup must not dereference it
+ await expect(safeWriteText(targetPath, "hello")).resolves.toBeUndefined()
+
+ expect(fs.rmdir).toHaveBeenCalledTimes(1)
+ expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"))
+ if (process.platform === "win32") {
+ // default platform is win32: the DACL save + restore still ran
+ // through the default icacls path (options?.execFileRunner must
+ // not throw when options is undefined)
+ expect(vi.mocked(execFile)).toHaveBeenCalledTimes(2)
+ expect(vi.mocked(fs.unlink)).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
+ }
+ })
+
+ it("does not remove the staging directory when the caller supplies its own tempPath", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const callerTemp = "/tmp/test-dir/caller-staged.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "hello", { platform: "linux", tempPath: callerTemp })
+
+ // the caller owns its temp file's directory; safeWriteText must not
+ // rmdir a directory it did not create
+ expect(fs.rmdir).not.toHaveBeenCalled()
+ })
+
+ it("a failed staging-dir removal never fails the committed write", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fs.rmdir).mockRejectedValue(Object.assign(new Error("ENOTEMPTY"), { code: "ENOTEMPTY" }))
+
+ await expect(safeWriteText(targetPath, "hello", { platform: "linux" })).resolves.toBeUndefined()
+
+ // the commit rename still happened and the rmdir error was swallowed
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), targetPath)
+ expect(fs.rmdir).toHaveBeenCalledTimes(1)
+ expect(fs.rmdir).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"))
+ })
+
+ it("gives each self-staged write its own staging directory so a concurrent write cannot remove it", async () => {
+ const targetA = "/tmp/test-dir/target-a.txt"
+ const targetB = "/tmp/test-dir/target-b.txt"
+ vi.mocked(fs.realpath).mockImplementation((p) => Promise.resolve(p as string))
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetA, "a", { platform: "linux" })
+ await safeWriteText(targetB, "b", { platform: "linux" })
+
+ // Two self-staged writes in the same directory must not share one staging
+ // directory: the first write's best-effort rmdir would otherwise delete the
+ // directory the second write had created but not yet opened (ENOENT on openSync).
+ const created = vi.mocked(fsSync.mkdirSync).mock.calls.map((c) => String(c[0]))
+ const staging = created.filter((p) => p.includes(".file-safety-staging_"))
+ expect(staging).toHaveLength(2)
+ expect(staging[0]).not.toBe(staging[1])
+ // Uniqueness comes from the documented name shape
+ //
/.file-safety-staging__: pinning the shape
+ // keeps the separator and the random suffix meaningful, not just the prefix.
+ for (const dir of staging) {
+ expect(dir).toMatch(/\.file-safety-staging_\d+_[a-z0-9]+$/)
+ }
+ const removed = vi.mocked(fs.rmdir).mock.calls.map((c) => String(c[0]))
+ expect(removed).toEqual([staging[0], staging[1]])
+ })
+
+ it("removes its own staging directory when a self-staged write fails", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fs.rename).mockRejectedValue(Object.assign(new Error("EACCES"), { code: "EACCES" }))
+
+ await expect(safeWriteText(targetPath, "hello", { platform: "linux" })).rejects.toThrow("EACCES")
+
+ // The failed write's temp file is unlinked, then the directory it
+ // created is removed — a failed write must not leave an empty
+ // .file-safety-staging directory behind.
+ // mkdirSync created this write's staging directory; the temp file lives
+ // inside it, so the unlink targets a path under that directory.
+ const staging = vi.mocked(fsSync.mkdirSync).mock.calls.map((c) => String(c[0]))
+ expect(staging).toHaveLength(1)
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining(staging[0]))
+ expect(fs.rmdir).toHaveBeenCalledWith(staging[0])
+ // The directory is only empty after its temp file is gone, so the
+ // unlink must happen before the rmdir.
+ expect(vi.mocked(fs.unlink).mock.invocationCallOrder[0]).toBeLessThan(
+ vi.mocked(fs.rmdir).mock.invocationCallOrder[0],
+ )
+ })
+
+ it("does not remove a staging directory it did not create when a caller-staged write fails", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const callerTemp = "/tmp/test-dir/caller-staged.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fs.rename).mockRejectedValue(Object.assign(new Error("EACCES"), { code: "EACCES" }))
+
+ await expect(
+ safeWriteText(targetPath, "hello", { platform: "linux", tempPath: callerTemp }),
+ ).rejects.toThrow("EACCES")
+
+ // The caller owns that directory: only the caller's temp file is cleaned,
+ // never a rmdir of a directory safeWriteText never created.
+ expect(fs.unlink).toHaveBeenCalledWith(callerTemp)
+ expect(fs.rmdir).not.toHaveBeenCalled()
+ })
+ })
+
+ it("win32: a rejecting async onWarning does not displace the caller's error or leak an unhandled rejection", async () => {
+ // TypeScript accepts an async sink where a void callback is expected, so the
+ // wrapper has to attach a handler to the returned promise: an unhandled
+ // rejection can end the process under Node's default mode. The notice exercised
+ // here is the retained-backup one - the DACL notices became refusals - so a sink
+ // failure now has to be reported without displacing the error the caller catches.
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The DACL save succeeds and only the restore fails: the publish commits and
+ // reports its retained backup copy through the sink.
+ let icaclsCalls = 0
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ icaclsCalls++
+ if (typeof cb === "function") cb(icaclsCalls === 1 ? null : new Error("icacls restore error"), "", "")
+ return fakeChild
+ })
+ const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+ await expect(
+ safeWriteText(targetPath, "data", {
+ platform: "win32",
+ backup: true,
+ onWarning: async () => {
+ throw new Error("async sink down")
+ },
+ }),
+ ).rejects.toBeInstanceOf(DaclRestoreError)
+
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ // The rejection is reported through the fallback sink rather than surfacing as an
+ // unhandled rejection.
+ expect(consoleWarn).toHaveBeenCalledWith(expect.stringContaining("onWarning callback rejected"))
+ consoleWarn.mockRestore()
+ })
+
+ // ── Test 2: fsync ordering ───────────────────────────────────────────────
+
+ describe("fsync ordering", () => {
+ it("calls fsync on the fd before close, and rename after close", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // Verify call order: openSync(temp) → writeSync → fsyncSync(temp)
+ // → closeSync(temp) → rename. On POSIX the parent directory is then
+ // opened and fsynced after the commit rename, so openSync/fsyncSync/
+ // closeSync each have a second (directory) call.
+ expect(vi.mocked(fsSync.openSync).mock.calls.length).toBe(2)
+ expect(vi.mocked(fsSync.writeSync).mock.calls.length).toBe(1)
+ expect(vi.mocked(fsSync.fsyncSync).mock.calls.length).toBe(2)
+ expect(vi.mocked(fsSync.closeSync).mock.calls.length).toBe(2)
+
+ // the temp file was fully closed before the commit rename
+ expect(vi.mocked(fsSync.closeSync).mock.calls[0][0]).toBe(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ // The title promises the order, so compare the invocations rather than
+ // only count them: a rename before closeSync, or a close before fsync,
+ // would not be a durable commit.
+ const fsyncOrder = vi.mocked(fsSync.fsyncSync).mock.invocationCallOrder[0]
+ const closeOrder = vi.mocked(fsSync.closeSync).mock.invocationCallOrder[0]
+ const renameOrder = vi.mocked(fs.rename).mock.invocationCallOrder[0]
+ expect(fsyncOrder).toBeLessThan(closeOrder)
+ expect(closeOrder).toBeLessThan(renameOrder)
+ })
+ })
+
+ // ── Test 3: simulated failure between write and rename leaves target intact ──
+
+ describe("crash/torn-write safety", () => {
+ it("simulated failure between fsync and rename leaves the target byte-identical and no temp left behind", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC"))
+
+ await expect(safeWriteText(targetPath, "new data", { platform: "linux" })).rejects.toThrow("ENOSPC")
+
+ // rename was attempted (the failure point)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // temp file was cleaned up on failure
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+
+ // backup was NOT created (backup:false by default), so target is untouched
+ // The only rename call was temp→target, not a rollback rename
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ })
+
+ it("a post-commit backup cleanup failure is non-fatal: the target stays committed and no temp is left behind", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The post-commit backup unlink (SUT step 6) fails — the write must
+ // still succeed; an orphaned backup is the documented acceptable
+ // outcome, so the failure is swallowed instead of rolling back.
+ vi.mocked(fs.unlink).mockRejectedValueOnce(new Error("EPERM"))
+
+ await safeWriteText(targetPath, "data", { backup: true, platform: "linux" })
+
+ // the commit rename (temp -> target) still happened; it is the only rename
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // the failing cleanup was the post-commit backup unlink
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+
+ // the staging temp was already committed by the rename; nothing
+ // temp-shaped is unlinked afterwards
+ expect(fs.unlink).not.toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+ })
+
+ it("a failed post-commit directory fsync does not roll the backup back over the published content", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const dirPath = path.dirname(targetPath)
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ // The file fd opens normally; the parent-directory open after the commit
+ // rename fails, which is the post-commit durability failure.
+ vi.mocked(fsSync.openSync).mockImplementation((target) => {
+ if (String(target) === dirPath) throw new Error("EBADF")
+ return 1
+ })
+
+ await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow(
+ PostCommitDurabilityError,
+ )
+
+ // The commit rename already published the new content, and the backup was only
+ // ever a copy: the target was never moved, so there is nothing to rename back.
+ expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // The durability failure is reported, not swallowed - and the backup copy is not
+ // left beside the target where no caller could find it.
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ })
+ })
+
+ // ── Test 4: backup:true keeps old safeWriteJson semantics, copy-based ──
+
+ describe("backup:true", () => {
+ it("copies target -> backup before commit without moving the target, deletes the copy on success", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "new data", { backup: true })
+
+ // target was accessed (exists check)
+ expect(fs.access).toHaveBeenCalledWith(targetPath)
+
+ // The backup is a copy: the canonical target is never moved away, so readers
+ // never see a missing file and no later step can clobber a concurrent publish.
+ expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.rename).not.toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_"))
+
+ // the only rename is the atomic commit temp -> target
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // backup copy was deleted on success
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ })
+
+ it("a failed commit does not move the target, so nothing has to be rolled back", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The commit rename is the only rename in the flow and it fails.
+ vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC"))
+
+ await expect(safeWriteText(targetPath, "new data", { backup: true })).rejects.toThrow("ENOSPC")
+
+ // The target never left its path, so there is no restore rename and the
+ // pre-write content is still what a reader sees at targetPath.
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_"))
+
+ // Both the backup copy and the staging temp are cleaned up on failure.
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+ })
+
+ it("creates the backup privately before its content exists, then fsyncs it", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "new data", { backup: true })
+
+ // The destination must exist with a private mode before copyFile writes anything
+ // into it: copyFile chooses the destination mode itself, so a restrictive target
+ // could otherwise leave a group/world-readable copy that a later chmod cannot
+ // undo. "wx" also means a pre-existing path is never silently reused.
+ const seedOpen = vi.mocked(fsSync.openSync).mock.calls.find(function (call) {
+ return String(call[0]).includes("safeWriteText.bak_") && call[1] === "wx"
+ })
+ expect(seedOpen).toBeDefined()
+ expect(seedOpen?.[2]).toBe(0o600)
+ const seedOrder = vi.mocked(fsSync.openSync).mock.invocationCallOrder[
+ vi.mocked(fsSync.openSync).mock.calls.indexOf(seedOpen!)
+ ]
+ expect(seedOrder).toBeLessThan(vi.mocked(fs.copyFile).mock.invocationCallOrder[0])
+
+ // The chmod keeps a copied read-only attribute (Windows) from breaking the fsync
+ // open, and keeps a backup of a permissive file private.
+ expect(fs.copyFile).toHaveBeenCalledWith(targetPath, expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.chmod).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"), 0o600)
+ expect(vi.mocked(fs.chmod).mock.invocationCallOrder[0]).toBeGreaterThan(
+ vi.mocked(fs.copyFile).mock.invocationCallOrder[0],
+ )
+
+ // The copy is then opened for fsync with the writable flag.
+ const backupOpen = vi.mocked(fsSync.openSync).mock.calls.find(function (call) {
+ return String(call[0]).includes("safeWriteText.bak_") && call[1] === "r+"
+ })
+ expect(backupOpen).toBeDefined()
+ })
+
+ it("a failed backup flush is reported and leaves no partial backup behind", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The copy lands, but the fsync of the copy fails: the retained content is not
+ // known to be durable, so the write must not proceed on a half-written backup.
+ // The staged temp is fsynced earlier with a different handle, so target the
+ // backup's fd specifically.
+ vi.mocked(fsSync.openSync).mockImplementation((p: unknown) =>
+ String(p).includes("safeWriteText.bak_") ? 7 : 1,
+ )
+ vi.mocked(fsSync.fsyncSync).mockImplementation((fd: unknown) => {
+ if (fd === 7) {
+ throw new Error("EIO")
+ }
+ })
+
+ await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow(
+ "EIO",
+ )
+
+ // Nothing was published, and the incomplete copy is removed rather than left
+ // next to the target looking like a usable backup.
+ expect(fs.rename).not.toHaveBeenCalled()
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+ })
+
+ it("a backup copy that fails part-way is removed, not left as a usable-looking backup", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The destination is seeded with openSync("wx") BEFORE any content exists at it,
+ // and the copy then fails part-way: the name is there, holding a partial copy of
+ // nothing usable. Cleanup has to key off the attempt, not off a copy that
+ // succeeded, or this file outlives the failed write beside the target.
+ vi.mocked(fs.copyFile).mockRejectedValue(Object.assign(new Error("EIO"), { code: "EIO" }))
+
+ await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow(
+ "EIO",
+ )
+
+ // Nothing was published, and the half-written copy is removed rather than left
+ // next to the target looking like a backup someone could restore.
+ expect(fs.rename).not.toHaveBeenCalled()
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+ })
+
+ it("backup:true when target does not exist: no backup created, just commit", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // fs.access resolves for dirPath check, but rejects for target check (backup path)
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" }
+ })
+
+ await safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })
+
+ // no backup rename (target didn't exist)
+ expect(fs.access).toHaveBeenCalledWith(targetPath)
+
+ // only one rename: temp -> target
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+ // no unlink (no backup to delete; DACL skipped via platform:linux)
+ expect(fs.unlink).not.toHaveBeenCalled()
+ })
+ })
+
+ // ── Test 5: win32 DACL path ──────────────────────────────────────────────
+
+ describe("win32 DACL", () => {
+ it.skipIf(process.platform !== "win32")(
+ "copies target DACL onto staging file via icacls before rename on Windows",
+ async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ await safeWriteText(targetPath, "data", { platform: "win32" })
+
+ // icacls dump + restore were called (execFile is callback-based mock)
+ expect(execFile).toHaveBeenCalledTimes(2)
+ },
+ )
+
+ it("non-win32: DACL path is unreachable when platform is not win32", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // icacls was NOT called on non-win32
+ expect(execFile).not.toHaveBeenCalled()
+ })
+
+ it("win32 DACL failure refuses the publish instead of renaming over the target", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // icacls dump fails — the callback-based mock must invoke cb with an error.
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ if (typeof cb === "function") cb(new Error("icacls error"), "", "")
+ return fakeChild
+ })
+
+ // Captured once: calling safeWriteText twice here would double-count the single
+ // icacls attempt asserted below.
+ const refusal = await safeWriteText(targetPath, "data", { platform: "win32" }).catch(
+ (error: unknown) => error,
+ )
+
+ expect(refusal).toBeInstanceOf(DaclInspectionError)
+ // The class alone does not pin the contract: swapping the phase or dropping the
+ // target path still satisfies toBeInstanceOf, and both are caller-visible - the
+ // phase says which check refused, the path names the file the caller must not
+ // assume was saved.
+ expect(refusal).toMatchObject({
+ name: "DaclInspectionError",
+ phase: "save",
+ targetPath,
+ message: expect.stringContaining("its DACL could not be saved"),
+ })
+
+ // Contract change (Security Boundaries row): a target whose DACL could not be
+ // saved is no longer replaced by a file that inherits different rights.
+ expect(fs.rename).not.toHaveBeenCalled()
+ // one icacls attempt only: a failed capture must not try to restore
+ expect(execFile).toHaveBeenCalledTimes(1)
+ })
+
+ it("win32: refuses the publish without an onWarning notice when the DACL cannot be saved", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ if (typeof cb === "function") cb(new Error("icacls error"), "", "")
+ return fakeChild
+ })
+ const warnings: string[] = []
+
+ await expect(
+ safeWriteText(targetPath, "data", { platform: "win32", onWarning: (m) => warnings.push(m) }),
+ ).rejects.toBeInstanceOf(DaclInspectionError)
+
+ // Contract change: the refusal replaces the warning. There is no replacement whose
+ // access rights could have changed, so no notice is emitted for a write that did
+ // not happen - a warning beside a refused publish would let a caller that ignores
+ // the error still read the write as a save.
+ expect(fs.rename).not.toHaveBeenCalled()
+ expect(warnings).toHaveLength(0)
+ })
+
+ it("win32: refuses the publish when the target cannot be checked for DACL preservation", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The target exists but is not readable: that is not "absent", and skipping DACL
+ // preservation has to stop the publish rather than be reported beside it.
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (String(p) === targetPath) {
+ throw Object.assign(new Error("EACCES"), { code: "EACCES" })
+ }
+ })
+ const warnings: string[] = []
+
+ // Captured once: a second call would double-count the assertions below.
+ const refusal = await safeWriteText(targetPath, "data", {
+ platform: "win32",
+ onWarning: (m) => warnings.push(m),
+ }).catch((error: unknown) => error)
+
+ expect(refusal).toBeInstanceOf(DaclInspectionError)
+ expect(refusal).toMatchObject({
+ name: "DaclInspectionError",
+ phase: "inspect",
+ targetPath,
+ message: expect.stringContaining("its access rights could not be checked"),
+ })
+
+ // Contract change: "there but unreadable" is no longer a reason to publish blind.
+ // The publish is refused before any icacls runs, and nothing is warned about a
+ // write that did not happen.
+ expect(execFile).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ expect(warnings).toHaveLength(0)
+ })
+
+ // The refusals sit inside the try whose catch performs the cleanup, so a refused
+ // publish is cleaned up by that handler and by nothing else. Counted, not matched
+ // with toHaveBeenCalledWith: that matcher passes however many times the same path
+ // is passed, so it cannot see a cleanup that runs twice.
+ it("win32: a refused publish removes its staged file and staging directory exactly once", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ if (typeof cb === "function") cb(new Error("icacls error"), "", "")
+ return fakeChild
+ })
+
+ await expect(safeWriteText(targetPath, "data", { platform: "win32" })).rejects.toBeInstanceOf(
+ DaclInspectionError,
+ )
+
+ const unlinkCalls = vi.mocked(fs.unlink).mock.calls.map((call) => String(call[0]))
+ const rmdirCalls = vi.mocked(fs.rmdir).mock.calls.map((call) => String(call[0]))
+ expect(unlinkCalls.filter((p) => p.includes("safeWriteText_"))).toHaveLength(1)
+ expect(rmdirCalls.filter((p) => p.includes(".file-safety-staging"))).toHaveLength(1)
+ })
+
+ // Warning delivery is advisory: it must not be able to change what the caller learns.
+ it("win32: a throwing onWarning does not replace the error the caller receives", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The DACL save succeeds and the restore fails, so the notice this sink throws on
+ // is the retained-backup one delivered from the failure handler.
+ let icaclsCalls = 0
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ icaclsCalls++
+ if (typeof cb === "function") cb(icaclsCalls === 1 ? null : new Error("icacls restore error"), "", "")
+ return fakeChild
+ })
+ const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+ const failure = await safeWriteText(targetPath, "data", {
+ platform: "win32",
+ backup: true,
+ onWarning: () => {
+ throw new Error("callback down")
+ },
+ }).catch((error: unknown) => error)
+
+ // A broken notice cannot turn a refused publish into an unreported one, and cannot
+ // swallow the write either: the caller still holds the DACL error.
+ expect(failure).toBeInstanceOf(DaclRestoreError)
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+ // The sink really was reached, so this is not a test that passes because no
+ // notice was ever delivered.
+ expect(consoleWarn).toHaveBeenCalledWith(expect.stringContaining("onWarning callback failed"))
+ consoleWarn.mockRestore()
+ })
+
+ it("win32 DACL: a partial dump left by a failed save is removed and never restored", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // icacls save fails — a real icacls may have written a partial dump
+ // before erroring, so the dump path must be cleaned up and must never
+ // be used for a restore.
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ if (typeof cb === "function") cb(new Error("icacls save error"), "", "")
+ return fakeChild
+ })
+
+ await expect(safeWriteText(targetPath, "data", { platform: "win32" })).rejects.toBeInstanceOf(
+ DaclInspectionError,
+ )
+
+ // Contract change: the publish is refused, so nothing is renamed. Only the save was
+ // attempted, and the partial dump is still removed below.
+ expect(fs.rename).not.toHaveBeenCalled()
+ expect(execFile).toHaveBeenCalledTimes(1)
+ const saveArgs = vi.mocked(execFile).mock.calls[0]?.[1]
+ expect(saveArgs?.[1]).toBe("/save")
+ // the dump path (possibly partially created by icacls) was unlinked
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
+ })
+
+ it("win32 DACL save args are [targetPath, /save, dumpPath, /T] before backup rename", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { backup: true, platform: "win32" })
+
+ // icacls was called twice (save + restore)
+ expect(execFile).toHaveBeenCalledTimes(2)
+
+ // First call: save DACL from target before backup rename
+ const firstCall = vi.mocked(execFile).mock.calls[0]
+ expect(firstCall[0]).toBe("icacls")
+ expect(firstCall[1]).toEqual([targetPath, "/save", expect.stringContaining("safeWriteText.acl"), "/T"])
+
+ // Second call: restore DACL onto directory after commit rename
+ const secondCall = vi.mocked(execFile).mock.calls[1]
+ expect(secondCall[0]).toBe("icacls")
+ expect(secondCall[1]).toEqual([
+ expect.stringContaining("/tmp/test-dir"),
+ "/restore",
+ expect.stringContaining("safeWriteText.acl"),
+ ])
+
+ // dump file was unlinked after restore
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
+ })
+
+ it("win32 DACL save runs before the backup copy, not after it", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ // The title is about order, so assert the order the mocks were actually
+ // called in. If the save ran after the backup copy the dump could describe a
+ // file that a concurrent publish had already replaced.
+ await safeWriteText(targetPath, "data", { backup: true, platform: "win32" })
+
+ const callOrder = vi.mocked(execFile).mock.invocationCallOrder
+ const copyOrder = vi.mocked(fs.copyFile).mock.invocationCallOrder
+ const renameOrder = vi.mocked(fs.rename).mock.invocationCallOrder
+ const saveCall = callOrder[0]
+ const restoreCall = callOrder[1]
+ const backupCopy = copyOrder[0]
+ const commitRename = renameOrder[0]
+
+ expect(saveCall).toBeLessThan(backupCopy)
+ expect(backupCopy).toBeLessThan(commitRename)
+ expect(commitRename).toBeLessThan(restoreCall)
+ })
+
+ it("win32 DACL: a failed restore is an error and the dump is still unlinked", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ const warnings: string[] = []
+
+ // icacls save succeeds, restore fails
+ let callCount = 0
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ callCount++
+ if (typeof cb === "function") {
+ cb(callCount === 1 ? null : new Error("icacls restore error"), "", "")
+ }
+ return fakeChild
+ })
+
+ const failure = await safeWriteText(targetPath, "data", {
+ platform: "win32",
+ onWarning: (m) => warnings.push(m),
+ }).catch((error: unknown) => error)
+
+ expect(failure).toBeInstanceOf(DaclRestoreError)
+ // The class alone does not pin the contract: the committed path is what a caller
+ // needs in order to tell which file answers to different rights than it did.
+ expect(failure).toMatchObject({
+ name: "DaclRestoreError",
+ targetPath,
+ message: expect.stringContaining("could not be restored"),
+ })
+
+ // The content did commit before the restore failed, so the rename happened exactly
+ // once even though the publish reports an error.
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+
+ // Contract change: the changed access rights are an error the caller receives, not
+ // a notice beside a write that resolved. With no backup copy in play there is no
+ // leftover to name, so this publish stays silent and reports through the error.
+ expect(warnings).toHaveLength(0)
+
+ // dump file was still unlinked in finally
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.acl"))
+ })
+
+ it("win32 DACL: a failed restore keeps the backup copy that still carries the original access rights", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ const warnings: string[] = []
+ let callCount = 0
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ callCount++
+ if (typeof cb === "function") cb(callCount === 1 ? null : new Error("icacls restore error"), "", "")
+ return fakeChild
+ })
+
+ await expect(
+ safeWriteText(targetPath, "data", {
+ platform: "win32",
+ backup: true,
+ onWarning: (m) => warnings.push(m),
+ }),
+ ).rejects.toBeInstanceOf(DaclRestoreError)
+
+ // The publish committed, and the copy made from the file it replaced is the only
+ // artifact left holding the access rights that could not be restored. Removing it
+ // would destroy the recovery path for exactly the fact the error reports, so the
+ // failure handler must leave it in place. Counted, because toHaveBeenCalledWith
+ // cannot see a second unlink of the same path.
+ const unlinks = vi.mocked(fs.unlink).mock.calls.map((call) => String(call[0]))
+ expect(unlinks.filter((p) => p.includes("safeWriteText.bak_"))).toHaveLength(0)
+ expect(fs.rename).toHaveBeenCalledTimes(1)
+
+ // The retained path is named to the human: this primitive has no structured result
+ // to carry it on, and an invisible leftover is worse than a visible one.
+ expect(warnings.filter((m) => m.includes("safeWriteText.bak_"))).toHaveLength(1)
+ })
+
+ it("win32 DACL: a failed restore reaches the caller-staged publish safeWriteJson hands in", async () => {
+ // safeWriteJson stages its own temp file and calls in with backup:true, so this is
+ // the shape its callers actually see: the publish must reject rather than resolve
+ // over a file whose rights changed, and keep the copy that still carries them.
+ const targetPath = "/tmp/test-dir/target.txt"
+ const callerTemp = "/tmp/test-dir/caller-staged.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ let callCount = 0
+ vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+ callCount++
+ if (typeof cb === "function") cb(callCount === 1 ? null : new Error("icacls restore error"), "", "")
+ return fakeChild
+ })
+
+ const outcome = await safeWriteText(targetPath, "", {
+ platform: "win32",
+ backup: true,
+ tempPath: callerTemp,
+ }).then(
+ () => "resolved" as const,
+ (error: unknown) => error,
+ )
+
+ // Not "resolved": no caller can observe success for a publish whose DACL was not
+ // preserved.
+ expect(outcome).toBeInstanceOf(DaclRestoreError)
+ expect(fs.rename).toHaveBeenCalledWith(callerTemp, targetPath)
+ const unlinks = vi.mocked(fs.unlink).mock.calls.map((call) => String(call[0]))
+ expect(unlinks.filter((p) => p.includes("safeWriteText.bak_"))).toHaveLength(0)
+ })
+
+ it("win32 DACL: when target does not exist, no save/restore/dump", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ // fs.access rejects for targetPath (ENOENT), but resolves for dirPath
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" }
+ return undefined
+ })
+
+ await safeWriteText(targetPath, "data", { platform: "win32" })
+
+ // icacls was NOT called (target absent → skip DACL entirely)
+ expect(execFile).not.toHaveBeenCalled()
+
+ // no dump file created or unlinked
+ expect(fs.unlink).not.toHaveBeenCalled()
+ })
+ })
+
+ // ── Test 6: pre-written temp path (tempPath option) ──────────────────────
+
+ describe("pre-written temp path", () => {
+ it("uses the provided tempPath, fsyncs it, and renames to target", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ const customTempPath = "/tmp/test-dir/custom-temp.tmp"
+
+ // platform:linux skips DACL entirely so this test focuses on tempPath only
+ await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+ // openSync was called on the custom temp path (r+ mode for fsync)
+ expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+
+ // fsync was called
+ expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+
+ // rename happened — realpath mock returns targetPath
+ expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+
+ // no unlink of custom temp (caller's concern; DACL skipped via platform:linux)
+ expect(fs.unlink).not.toHaveBeenCalled()
+
+ // a caller-supplied tempPath must not create the staging directory
+ expect(fsSync.mkdirSync).not.toHaveBeenCalled()
+ })
+
+ it("applies the existing target's mode to a caller-supplied tempPath before publishing", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600))
+ vi.mocked(fsSync.openSync).mockReturnValue(2)
+
+ const customTempPath = "/tmp/test-dir/custom-temp.tmp"
+
+ await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+ // the caller-staged temp is fchmod'd to the restrictive target mode so
+ // the atomic rename cannot widen a 0o600 target (CWE-732 regression)
+ expect(fsSync.fchmodSync).toHaveBeenCalledWith(2, 0o600)
+ expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+ expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+ })
+
+ it("keeps the temp's default mode when the target does not exist yet (ENOENT)", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fsSync.statSync).mockImplementation(() => {
+ throw enoent
+ })
+ vi.mocked(fsSync.openSync).mockReturnValue(2)
+
+ const customTempPath = "/tmp/test-dir/custom-temp.tmp"
+
+ await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+ // no existing target, so nothing to preserve and no fchmod on the temp
+ expect(fsSync.fchmodSync).not.toHaveBeenCalled()
+ expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+ })
+
+ it("propagates a non-ENOENT stat failure rather than defaulting the mode (caller-staged)", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
+ vi.mocked(fsSync.statSync).mockImplementation(() => {
+ throw eacces
+ })
+ vi.mocked(fsSync.openSync).mockReturnValue(2)
+
+ const customTempPath = "/tmp/test-dir/custom-temp.tmp"
+
+ // A target that cannot be stat'd is not a fresh target: publishing with
+ // the default mode would widen a restrictive target through the rename.
+ await expect(
+ safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" }),
+ ).rejects.toThrow("EACCES")
+ expect(fsSync.fchmodSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("propagates a non-ENOENT stat failure rather than defaulting the mode (self-staged)", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ const eio = Object.assign(new Error("EIO: i/o error"), { code: "EIO" })
+ vi.mocked(fsSync.statSync).mockImplementation(() => {
+ throw eio
+ })
+
+ // The mode is read before the temp is opened, so a real I/O failure stops
+ // the write before anything is staged.
+ await expect(safeWriteText(targetPath, "hello world", { platform: "linux" })).rejects.toThrow("EIO")
+ expect(fsSync.openSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("opens the temp before applying a read-only target's mode (0o444 does not block the open)", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o444))
+ vi.mocked(fsSync.openSync).mockReturnValue(3)
+
+ const customTempPath = "/tmp/test-dir/custom-temp.tmp"
+
+ await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+ // a 0o444 target must not make openSync(tempPath, "r+") fail: the mode
+ // is applied with fchmodSync on the already-open fd, after the open
+ expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+ expect(fsSync.fchmodSync).toHaveBeenCalledWith(3, 0o444)
+ const openIdx = vi.mocked(fsSync.openSync).mock.invocationCallOrder[0]
+ const fchmodIdx = vi.mocked(fsSync.fchmodSync).mock.invocationCallOrder[0]
+ expect(openIdx).toBeLessThan(fchmodIdx)
+ expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+ })
+
+ it("applies the existing target's exact mode to the self-staged temp (umask must not narrow it)", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o664))
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // openSync's creation mode is narrowed by the process umask (0o664 -> 0o644 with
+ // the common 0o022), and the rename publishes the temp's mode onto the target,
+ // so the existing target's mode must be applied on the fd before the commit.
+ expect(fsSync.fchmodSync).toHaveBeenCalledWith(1, 0o664)
+ const openIdx = vi.mocked(fsSync.openSync).mock.invocationCallOrder[0]
+ const fchmodIdx = vi.mocked(fsSync.fchmodSync).mock.invocationCallOrder[0]
+ expect(openIdx).toBeLessThan(fchmodIdx)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ })
+
+ it("does not fchmod the self-staged temp for a fresh target", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fsSync.statSync).mockImplementation(() => {
+ throw enoent
+ })
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // Nothing exists to preserve: the default creation mode is the intended one.
+ expect(fsSync.fchmodSync).not.toHaveBeenCalled()
+ })
+ })
+
+ // ── Test 7: symlink handling (Finding 4 regression test) ─────────────────
+
+ describe("symlink handling", () => {
+ it("a write through a symlink commits onto the resolved referent, never the link path", async () => {
+ const linkPath = "/tmp/links/link.txt"
+ const referentPath = "/tmp/targets/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(referentPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(linkPath, "new-content", { platform: "linux" })
+
+ // The commit rename must target the realpath result (the referent), never the link itself —
+ // that is what guarantees a write through a symlink replaces the referent's content
+ // and preserves the link.
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), referentPath)
+ expect(fs.rename).not.toHaveBeenCalledWith(expect.anything(), linkPath)
+ })
+
+ it("when realpath reports ENOENT (target absent), uses the given path as-is", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }))
+ // lstat reports the path itself as absent, so this is a new target and
+ // the fallback is allowed.
+ vi.mocked(fs.lstat).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }))
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // rename still happened with the fallback path (path.resolve on /tmp → C:\tmp)
+ const resolvedFallback = _resolvedTarget(targetPath)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), resolvedFallback)
+ })
+
+ it("propagates a dangling symlink instead of writing through the link path", async () => {
+ // realpath resolves the referent, so a link whose target is missing reports
+ // ENOENT. Falling back to the link path would replace the symlink with a
+ // regular file, so the error must propagate and nothing may be committed.
+ const linkPath = "/tmp/test-dir/dangling-link.txt"
+ vi.mocked(fs.realpath).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }))
+ const linkStats = Object.create(fsSync.Stats.prototype) as fsSync.Stats
+ linkStats.isSymbolicLink = () => true
+ vi.mocked(fs.lstat).mockResolvedValue(linkStats)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await expect(safeWriteText(linkPath, "data", { platform: "linux" })).rejects.toThrow("ENOENT")
+
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+ })
+
+ // ── Test 8: review fixes (permissions, partial writes, resolution, durability) ──
+
+ describe("review fixes", () => {
+ it("preserves the target's restrictive mode and tolerates a failed staging-dir permission repair", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600))
+ // a pre-existing staging dir may fail its best-effort permission repair
+ vi.mocked(fsSync.chmodSync).mockImplementationOnce(() => {
+ throw new Error("EACCES")
+ })
+
+ await safeWriteText(targetPath, "secret", { platform: "linux" })
+
+ // the staging file inherits the target's 0o600 mode and the write commits
+ expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o600)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ })
+
+ it("falls back to the 0o644 default when the target does not exist yet", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ vi.mocked(fsSync.statSync).mockImplementation(() => {
+ throw Object.assign(new Error("ENOENT"), { code: "ENOENT" })
+ })
+
+ await safeWriteText(targetPath, "fresh", { platform: "linux" })
+
+ expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o644)
+ })
+
+ it("loops on short writes until the full content is durable before fsync", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const content = "0123456789" // 10 bytes
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ const buffer = Buffer.from(content, "utf8")
+ // first write (offset 0) reports 4 bytes (short write); the loop continues
+ vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) =>
+ args[2] === 0 ? 4 : typeof args[3] === "number" ? args[3] : 0,
+ )
+
+ await safeWriteText(targetPath, content, { platform: "linux" })
+
+ // [0,10) reports 4 bytes, then [4,10) writes the remaining 6
+ expect(fsSync.writeSync).toHaveBeenCalledTimes(2)
+ expect(fsSync.writeSync).toHaveBeenNthCalledWith(1, 1, buffer, 0, 10)
+ expect(fsSync.writeSync).toHaveBeenNthCalledWith(2, 1, buffer, 4, 6)
+ expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ })
+
+ it("fsyncs the parent directory after the commit rename on POSIX", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ // temp fd=1 then parent-dir fd=2 - distinct fds prove the ordering
+ vi.mocked(fsSync.openSync).mockReturnValueOnce(1).mockReturnValue(2)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // the directory fsync (fd 2) happens only after the file fsync (fd 1);
+ // the dir path assertion is path-agnostic (stringContaining) because
+ // path.dirname renders the same input differently on Windows
+ expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("test-dir"), "r")
+ expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(1, 1)
+ expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(2, 2)
+ expect(fsSync.closeSync).toHaveBeenCalledWith(2)
+ })
+
+ it("reports a failed parent-directory fsync instead of claiming a durable write", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync)
+ .mockReturnValueOnce(1)
+ .mockImplementationOnce(() => {
+ throw new Error("EBADF")
+ })
+
+ // The content rename committed, so the caller can still find the data at
+ // the target; what the write cannot claim is that the directory entry
+ // reached the disk. Returning success here would claim durability the
+ // filesystem did not grant.
+ await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toThrow(
+ PostCommitDurabilityError,
+ )
+
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+ })
+
+ it("propagates realpath errors (EACCES and code-less) instead of the fallback path", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
+ vi.mocked(fs.realpath).mockRejectedValueOnce(eacces)
+ await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(eacces)
+ expect(fs.rename).not.toHaveBeenCalled()
+
+ const plain = new Error("resolution failed")
+ vi.mocked(fs.realpath).mockRejectedValueOnce(plain)
+ await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(plain)
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("backup:true propagates access errors (EACCES and code-less) instead of skipping the backup", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const eacces = Object.assign(new Error("EACCES"), { code: "EACCES" })
+ const plain = new Error("access failed")
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // each write accesses dirPath then target; only the target access rejects
+ const rejectTarget = (error: Error) => async (p: unknown) => {
+ if (typeof p === "string" && p.endsWith("target.txt")) throw error
+ }
+ vi.mocked(fs.access)
+ .mockImplementationOnce(rejectTarget(eacces))
+ .mockImplementationOnce(rejectTarget(eacces))
+ .mockImplementationOnce(rejectTarget(plain))
+ .mockImplementationOnce(rejectTarget(plain))
+
+ await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toEqual(
+ expect.objectContaining({ code: "EACCES" }),
+ )
+ await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toThrow(
+ "access failed",
+ )
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+ })
+ describe("content bytes", () => {
+ const targetPath = "/tmp/enc-dir/target.txt"
+
+ beforeEach(() => {
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ })
+
+ it("stages UTF-8 bytes for string content", async () => {
+ await safeWriteText(targetPath, "héllo", { platform: "linux" })
+ expect(fsSync.writeSync).toHaveBeenCalledWith(1, Buffer.from("héllo", "utf8"), 0, 6)
+ })
+
+ it("publishes caller-supplied bytes unchanged instead of re-encoding them", async () => {
+ // The extension host encodes a document with VS Code's own codec, which
+ // covers the legacy code pages and BOMs Node cannot represent, and hands
+ // the result over: those bytes must reach the commit rename exactly as
+ // they were given.
+ const bytes = Buffer.from([0x00, 0x68, 0x00, 0x69])
+ await safeWriteText(targetPath, bytes, { platform: "linux" })
+ expect(fsSync.writeSync).toHaveBeenCalledWith(1, bytes, 0, 4)
+ })
+ })
+})
+
+// ── Test 12: lock key, staging path, and post-commit durability ─────────────
+
+describe("resolveLockKey", () => {
+ beforeEach(() => mockDefaults())
+
+ it("canonicalizes the parent directory, not just the file", async () => {
+ vi.mocked(fs.realpath).mockImplementation(async (target) => {
+ const key = String(target)
+ if (key === "/tmp/linkdir/file.json") return "/real/dir/file.json"
+ if (key === "/real/dir") return "/real/dir"
+ return key
+ })
+
+ // The key is the canonical directory plus the basename, so a symlinked
+ // ancestor and its referent share one lock.
+ await expect(resolveLockKey("/tmp/linkdir/file.json")).resolves.toBe(path.join("/real/dir", "file.json"))
+ })
+
+ it("computes a key for a dangling link, which resolvePublishTarget refuses", async () => {
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true))
+ // Only the link path is read, so a single answer is enough and keeps the mock's
+ // return type matching fs.promises.readlink.
+ vi.mocked(fs.readlink).mockResolvedValue("referent.json")
+
+ // Mid-commit a peer writer renames the referent away and back, so the key
+ // must still be computable while the link dangles.
+ await expect(resolveLockKey("/tmp/linkdir/file.json")).resolves.toBe(
+ path.resolve(path.join("/tmp/linkdir", "referent.json")),
+ )
+ })
+
+ it("terminates on a two-link cycle instead of walking forever", async () => {
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true))
+ // Every readlink answers with the same link, so an unbounded walk would
+ // never end; the bounded walk returns the key it actually reached.
+ vi.mocked(fs.readlink).mockImplementation(async () => "a.json")
+
+ await expect(resolveLockKey("/tmp/linkdir/a.json")).resolves.toBe(
+ path.resolve(path.join("/tmp/linkdir", "a.json")),
+ )
+ expect(fs.readlink).toHaveBeenCalledTimes(8)
+ })
+})
+
+describe("caller-supplied staging path", () => {
+ beforeEach(() => mockDefaults())
+
+ it("rejects a staging file outside the target's directory before writing anything", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+
+ // A rename across filesystems fails with EXDEV, and a path elsewhere lets
+ // a caller publish an unrelated file onto the target.
+ await expect(
+ safeWriteText(targetPath, "data", { tempPath: "/tmp/other-dir/x.tmp", platform: "linux" }),
+ ).rejects.toThrow(StagingPathError)
+ expect(fsSync.openSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("rejects a staging path that is a symlink", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true))
+
+ // Renaming a link over the target publishes whatever the link points at.
+ await expect(
+ safeWriteText(targetPath, "data", { tempPath: "/tmp/test-dir/x.tmp", platform: "linux" }),
+ ).rejects.toThrow(StagingPathError)
+ expect(fsSync.openSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("rejects a staging path that is the target itself", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ // Same inode and device for the supplied staging path and the target: the
+ // failure handler would unlink the only copy of the content, so a failed
+ // write would delete the file it was meant to protect.
+ const stats = _fileStatsWithIdentity(42n, 7n)
+ vi.mocked(fs.lstat).mockResolvedValue(stats)
+
+ await expect(safeWriteText(targetPath, "data", { tempPath: targetPath, platform: "linux" })).rejects.toThrow(
+ StagingPathError,
+ )
+ expect(fsSync.openSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ // The comparison is only sound when both stats are read as bigint: on NTFS/ReFS the file
+ // identifiers exceed Number.MAX_SAFE_INTEGER.
+ // Filter on the options, not the spelling: path.resolve prefixes a drive letter on Windows,
+ // so the two identity reads are the calls that asked for options at all.
+ const identityLookups = vi.mocked(fs.lstat).mock.calls.filter((c) => c[1] !== undefined)
+ expect(identityLookups.length).toBeGreaterThanOrEqual(2)
+ for (const c of identityLookups) {
+ expect(c[1]).toEqual({ bigint: true })
+ }
+ expect(fs.unlink).not.toHaveBeenCalled()
+ })
+
+ it("rejects when the target identity cannot be compared for a reason other than a missing target", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ // A hard-linked staging file shares the target's inode, so the identity comparison is the only thing
+ // between this write and a rename onto the very file the guard protects. An EACCES from the target
+ // lstat must not be mistaken for "there is no target".
+ const stagingStats = _fileStatsWithIdentity(42n, 7n)
+ vi.mocked(fs.lstat).mockImplementation(async (p) => {
+ if (String(p) === targetPath) {
+ throw Object.assign(new Error("EACCES"), { code: "EACCES" })
+ }
+ return stagingStats
+ })
+
+ await expect(
+ safeWriteText(targetPath, "data", { tempPath: "/tmp/test-dir/hardlink.txt", platform: "linux" }),
+ ).rejects.toThrow("Staging file could not be compared with the target")
+ expect(fsSync.openSync).not.toHaveBeenCalled()
+ expect(fs.rename).not.toHaveBeenCalled()
+ // Both identity reads must ask for bigint stats, or the comparison silently falls
+ // back to rounded numbers on NTFS/ReFS.
+ const identityLookups = vi.mocked(fs.lstat).mock.calls.filter((c) => c[1] !== undefined)
+ expect(identityLookups).toHaveLength(2)
+ for (const c of identityLookups) {
+ expect(c[1]).toEqual({ bigint: true })
+ }
+ })
+})
+
+describe("cleanup when a backed-up write fails before commit", () => {
+ beforeEach(() => mockDefaults())
+
+ it("releases the staged file, its copy and its own staging directory before throwing", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+ // The commit rename is the only rename in this flow and it fails.
+ vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC"))
+
+ await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toThrow("ENOSPC")
+
+ // The staging file and this write's own directory must not leak, and neither may
+ // the backup copy: the target still holds the pre-write content on disk.
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+ expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+ const stagingDirs = vi.mocked(fsSync.mkdirSync).mock.calls.map((call) => String(call[0]))
+ expect(stagingDirs.length).toBe(1)
+ expect(fs.rmdir).toHaveBeenCalledWith(stagingDirs[0])
+
+ const failingRenameOrder = vi.mocked(fs.rename).mock.invocationCallOrder[0]
+ const unlinkOrder = vi.mocked(fs.unlink).mock.invocationCallOrder[0]
+ const rmdirOrder = vi.mocked(fs.rmdir).mock.invocationCallOrder[0]
+ expect(unlinkOrder).toBeGreaterThan(failingRenameOrder)
+ expect(rmdirOrder).toBeGreaterThan(failingRenameOrder)
+ })
+})
+
+describe("resolvePublishTarget", () => {
+ beforeEach(() => mockDefaults())
+
+ it("propagates an lstat failure that is not ENOENT instead of falling back to the link path", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockRejectedValue(eacces)
+
+ // A failed lstat says nothing about whether the path is a link, so the
+ // fallback would publish through a link we were not allowed to inspect.
+ await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(eacces)
+ expect(fs.rename).not.toHaveBeenCalled()
+ })
+
+ it("still falls back to the given path when lstat also reports the path as absent", async () => {
+ const targetPath = "/tmp/test-dir/target.txt"
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockRejectedValue(enoent)
+ vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+ await safeWriteText(targetPath, "data", { platform: "linux" })
+
+ // The fallback is the resolved path, not the string that was handed in.
+ expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), path.resolve(targetPath))
+ })
+})
+
+describe("resolveLockKey when the parent directory does not exist yet", () => {
+ beforeEach(() => mockDefaults())
+
+ it("canonicalizes through the nearest existing ancestor instead of the literal parent", async () => {
+ // Two writers must take ONE lock: the one whose parent directory is already there,
+ // and the one racing to create it. Resolving only the immediate parent and falling
+ // back to its literal spelling on ENOENT gave them different keys whenever an
+ // ancestor was a symlink or a Windows short name, so a read-modify-write under the
+ // advisory lock lost one side.
+ const aliasDir = path.resolve("/tmp/alias-parent")
+ const canonicalDir = path.resolve("/tmp/real-parent")
+ const nested = path.join(aliasDir, "nested")
+ const target = path.join(nested, "history_item.json")
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false))
+ vi.mocked(fs.realpath).mockImplementation(async (p) => {
+ const s = String(p)
+ if (s === target || s === nested) {
+ throw Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ }
+ if (s === aliasDir) {
+ return canonicalDir
+ }
+ return s
+ })
+
+ expect(await resolveLockKey(target)).toBe(path.join(canonicalDir, "nested", "history_item.json"))
+ })
+
+ it("propagates a realpath failure that is not ENOENT instead of guessing a key", async () => {
+ // A realpath that fails for another reason says nothing about the canonical form;
+ // returning a literal key would silently put this writer on a different lock.
+ const target = path.join(path.resolve("/tmp/test-dir"), "history_item.json")
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false))
+ // Not a link: the walk must reach the canonicalization step, which is where the
+ // non-ENOENT failure has to surface.
+ vi.mocked(fs.readlink).mockRejectedValue(
+ Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }),
+ )
+ vi.mocked(fs.realpath).mockImplementation(async (p) => {
+ if (String(p) === target) return target
+ throw Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
+ })
+
+ await expect(resolveLockKey(target)).rejects.toThrow("EACCES")
+ })
+})
diff --git a/src/services/file-safety/safeWriteText.ts b/src/services/file-safety/safeWriteText.ts
new file mode 100644
index 0000000000..8f7a924810
--- /dev/null
+++ b/src/services/file-safety/safeWriteText.ts
@@ -0,0 +1,660 @@
+import * as fs from "fs/promises"
+import * as fsSync from "fs"
+import * as path from "path"
+import { execFile } from "child_process"
+
+import { getErrorCode } from "../../utils/errorCode"
+
+export interface SafeWriteTextOptions {
+ /**
+ * When true, keep the old-file semantics without ever removing the target: the
+ * previous content is copied to a hidden backup path and flushed before the
+ * commit rename, the commit rename atomically replaces the target, and on success
+ * the backup copy is deleted. A failure before the commit leaves the target
+ * untouched (there is nothing to roll back) and removes the backup copy. When
+ * false (default) the atomic rename simply replaces the target.
+ */
+ backup?: boolean
+
+ /**
+ * Platform override for testing. When omitted the real process.platform
+ * value is used. Set to "win32" or "linux" / "darwin" from tests so that
+ * both branches are reachable without needing a real Windows runner.
+ */
+ platform?: string
+
+ /**
+ * Custom execFile runner for testing (e.g. vi.fn). When omitted the real
+ * child_process.execFile is used.
+ */
+ execFileRunner?: typeof execFile
+
+ /**
+ * Sink for non-fatal safety notices. The notice that still reaches it is a leftover: the backup
+ * copy kept beside the target after a Windows DACL restore failed, named with its path. A DACL
+ * that could not be captured is no longer a notice here - the publish is refused with
+ * DaclInspectionError before anything is committed - and a saved DACL that could not be put back
+ * after the commit arrives as DaclRestoreError rather than a warning, so neither reaches this
+ * sink. Defaults to console.warn.
+ */
+ onWarning?: (message: string) => void
+
+ /**
+ * Pre-written temp path to use for the commit phase. When provided,
+ * safeWriteText skips creating its own staging file and uses this path
+ * instead (it still fsyncs before rename). Useful when a caller has
+ * already written data to a temp file via a custom stream.
+ */
+ tempPath?: string
+}
+
+/**
+ * A caller-supplied staging path that is not a file this write may publish: it
+ * sits outside the target's directory (so the commit rename would cross
+ * filesystems) or is not a regular file. Rejecting it before any write keeps the
+ * target from being replaced by whatever the path points at.
+ */
+export class StagingPathError extends Error {
+ readonly stagingPath: string
+
+ constructor(message: string, stagingPath: string) {
+ super(message)
+ this.name = "StagingPathError"
+ this.stagingPath = stagingPath
+ }
+}
+
+/**
+ * The commit rename succeeded but the parent-directory fsync did not, so the
+ * directory entry is not known to be durable. The content is at the target; the
+ * caller cannot assume it survives a crash. Reported as its own error so a
+ * successful return never claims durability the filesystem did not grant.
+ */
+export class PostCommitDurabilityError extends Error {
+ readonly targetPath: string
+
+ constructor(targetPath: string, cause: unknown) {
+ super(
+ "The rename committed but the parent directory could not be fsynced -- the content is at the target path reported on this error, and the directory entry may not be durable.",
+ { cause },
+ )
+ this.name = "PostCommitDurabilityError"
+ this.targetPath = targetPath
+ }
+}
+
+/**
+ * The target exists but its access rights could not be inspected or saved, so publishing would
+ * replace it with a file that inherits different rights. On Windows the publish is refused before
+ * anything is committed: a save that silently widened who can read the file is not a save the
+ * caller can trust, and nothing has been published yet, so the target still holds its content.
+ */
+export class DaclInspectionError extends Error {
+ constructor(
+ readonly targetPath: string,
+ readonly phase: "inspect" | "save",
+ readonly causeError: unknown,
+ ) {
+ const detail = phase === "save" ? "its DACL could not be saved" : "its access rights could not be checked"
+ super(`safeWriteText: refusing to publish over ${targetPath} because ${detail}`)
+ this.name = "DaclInspectionError"
+ }
+}
+
+/**
+ * The content is committed but the saved DACL could not be put back on it, so the file at the
+ * target answers to different access rights than the one it replaced. Reported as an error rather
+ * than a warning: no caller can observe success for a publish whose DACL was not preserved. The
+ * failure handler keeps this write's backup copy for it - that copy is the only artifact still
+ * carrying the access rights of the file the publish replaced.
+ */
+export class DaclRestoreError extends Error {
+ constructor(
+ readonly targetPath: string,
+ readonly causeError: unknown,
+ ) {
+ super(`safeWriteText: content committed at ${targetPath}, but its saved access rights could not be restored`)
+ this.name = "DaclRestoreError"
+ }
+}
+// -- helpers ---------------------------------------------------------------
+
+/** Generate a unique temp file name in the given directory. */
+function _tempName(dir: string, prefix: string): string {
+ return path.join(dir, "." + prefix + "_" + Date.now() + "_" + Math.random().toString(36).substring(2) + ".tmp")
+}
+
+/** Create a private per-write staging sub-directory inside *dir*. The name is
+ * unique per write, so concurrent writes never collide on their temp names and
+ * never remove a staging directory another write is still using: with one shared
+ * name, one write's best-effort rmdir could delete the directory another write
+ * had just created but not yet opened, failing its openSync with ENOENT. */
+function _stagingDir(dir: string): string {
+ const sd = path.join(dir, ".file-safety-staging_" + Date.now() + "_" + Math.random().toString(36).substring(2))
+ // mode:0o700 protects a freshly created staging dir; the best-effort chmod
+ // repairs a pre-existing one (mkdirSync with recursive:true never chmods an
+ // existing directory), so staged temp files are never group/world readable.
+ fsSync.mkdirSync(sd, { recursive: true, mode: 0o700 })
+ try {
+ fsSync.chmodSync(sd, 0o700)
+ } catch {
+ // best-effort: chmod denied or unavailable; a fresh dir was still
+ // created with the requested mode
+ }
+ return sd
+}
+
+/** Save the DACL of *srcPath* to a dump file on Windows.
+ * Returns true when the dump was written successfully; false otherwise.
+ * Never throws — callers treat failure as "skip DACL handling". */
+async function _saveDaclWindows(srcPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise {
+ const runner = execFileRunner ?? execFile
+ try {
+ await new Promise((resolve, reject) => {
+ runner("icacls", [srcPath, "/save", dumpPath, "/T"], { windowsHide: true }, (err) =>
+ err ? reject(err) : resolve(),
+ )
+ })
+ return true
+ } catch {
+ return false
+ }
+}
+
+/** Restore a DACL dump onto *dirPath* on Windows.
+ * Returns whether icacls succeeded; the caller reports a failure. */
+async function _restoreDaclWindows(
+ dirPath: string,
+ dumpPath: string,
+ execFileRunner?: typeof execFile,
+): Promise {
+ const runner = execFileRunner ?? execFile
+ try {
+ await new Promise((resolve, reject) => {
+ runner("icacls", [dirPath, "/restore", dumpPath], { windowsHide: true }, (err) =>
+ err ? reject(err) : resolve(),
+ )
+ })
+ return true
+ } catch {
+ return false
+ }
+}
+
+// -- public API ------------------------------------------------------------
+
+/**
+ * Resolve the publish target: the symlink referent when the given path is an
+ * existing symlink, the path itself otherwise. Only ENOENT (target absent yet)
+ * may fall back to the given path; any other resolution error (EACCES, EIO, ...)
+ * propagates so a broken or unreadable symlink is never written through its
+ * link path. Callers that stage a temp file themselves must stage it beside
+ * the resolved path: the commit is a rename onto the referent, and a rename
+ * across filesystems fails with EXDEV.
+ */
+async function resolvePublishTarget(absoluteFilePath: string): Promise {
+ return fs.realpath(absoluteFilePath).catch(async (error: unknown) => {
+ if (getErrorCode(error) !== "ENOENT") throw error
+ // ENOENT also covers a dangling symlink, which must never be written through.
+ // Only a lstat that also reports the path as absent may fall back to the
+ // given path; a real lstat failure (EACCES, EIO) says nothing about whether
+ // the path is a link, so falling back would write through a link we were
+ // simply not allowed to inspect.
+ const linkStat = await fs.lstat(absoluteFilePath).catch((lstatError: unknown) => {
+ if (getErrorCode(lstatError) === "ENOENT") return undefined
+ throw lstatError
+ })
+ if (linkStat?.isSymbolicLink()) throw error
+ return absoluteFilePath
+ })
+}
+
+/**
+ * Canonicalize the parent directory and re-join the basename. fs.realpath
+ * canonicalizes every component, including a symlinked ancestor directory or a
+ * Windows 8.3 short name, so a lock key must be canonical even when the file
+ * itself is not there yet -- otherwise the key for one file depends on whether
+ * the file exists when the key is computed, and two writers take two locks.
+ */
+
+async function canonicalDirKey(absoluteFilePath: string): Promise {
+ const dirPath = path.dirname(absoluteFilePath)
+ // Walk up to the nearest ancestor that EXISTS, canonicalize that, and re-join the
+ // components that are not there yet. Falling back to the unresolved spelling of the
+ // whole parent - what a single realpath(...).catch(() => dirPath) used to do - makes
+ // the key depend on whether the directory happens to exist: a writer whose parent is
+ // already there canonicalizes through a symlinked ancestor (or a short name) while a
+ // writer racing to create the same directory gets the literal spelling, so the two
+ // take different locks for one file and a read-modify-write loses one side.
+ // A realpath failure that is not "not there yet" says nothing about the canonical
+ // form, so it is propagated rather than papered over with a key that may be wrong.
+ let cursor = dirPath
+ const missing: string[] = []
+ for (;;) {
+ const canonical = await fs.realpath(cursor).catch((error: unknown) => {
+ if (getErrorCode(error) === "ENOENT") return undefined
+ throw error
+ })
+ if (canonical !== undefined) {
+ return path.join(canonical, ...missing.reverse(), path.basename(absoluteFilePath))
+ }
+ missing.push(path.basename(cursor))
+ const parent = path.dirname(cursor)
+ if (parent === cursor) {
+ // Every component up to the root is missing: there is nothing to canonicalize
+ // against, and the literal path is the only key left.
+ return path.join(dirPath, path.basename(absoluteFilePath))
+ }
+ cursor = parent
+ }
+}
+
+/**
+ * Lock key for a publish target: the symlink referent when the path is an
+ * existing symlink, the path itself otherwise. Unlike resolvePublishTarget this
+ * tolerates a dangling link, because the lock key has to be computable while a
+ * peer writer is mid-commit (a publish renames the staged file onto the referent,
+ * and backup mode keeps a copy beside it).
+ * The walk is bounded so a two-link cycle terminates, and every key it returns is
+ * canonicalized through canonicalDirKey.
+ */
+export async function resolveLockKey(absoluteFilePath: string): Promise {
+ try {
+ return await canonicalDirKey(await resolvePublishTarget(absoluteFilePath))
+ } catch {
+ // A real readlink throws for anything that is not a link, so a normal chain
+ // ends the walk. Two links that point at each other never would, so the
+ // walk is bounded and callers use the key they actually reached.
+ let key = absoluteFilePath
+ for (let depth = 0; depth < 8; depth++) {
+ const target = await fs.readlink(key).catch(() => undefined)
+ if (target === undefined) return await canonicalDirKey(key)
+ key = await canonicalDirKey(path.resolve(path.dirname(key), target))
+ }
+ return await canonicalDirKey(key)
+ }
+}
+
+/**
+ * Publish text by staging beside the resolved target and committing with a rename.
+ *
+ * @internal Production callers of this file use resolvePublishTarget and
+ * resolveLockKey; the write entry point itself has no production caller while #2350
+ * decides which primitive main keeps, so it is tagged internal instead of being
+ * reported as an unused export.
+ */
+export async function safeWriteText(
+ filePath: string,
+ content: string | Uint8Array,
+ options?: SafeWriteTextOptions,
+): Promise {
+ const absoluteFilePath = path.resolve(filePath)
+
+ // Resolve the symlink referent (see resolvePublishTarget).
+ const targetPath = await resolvePublishTarget(absoluteFilePath)
+ const dirPath = path.dirname(targetPath)
+
+ // Ensure parent directory exists (mirrors safeWriteJson behaviour).
+ await fs.mkdir(dirPath, { recursive: true })
+ await fs.access(dirPath)
+
+ // Create the staging directory only when we generate the temp file there;
+ // callers supplying their own tempPath (e.g. safeWriteJson) must not be left
+ // with an empty .file-safety-staging directory behind. Track the directory this
+ // write created so its cleanup removes its own directory, not a shared one.
+ let stagingDir: string | null = null
+ let tempPath: string
+ if (options?.tempPath) {
+ // A caller-supplied staging file is only safe when it is the file this
+ // write is staging, not an arbitrary path. Two properties are checked:
+ // it must sit beside the resolved target (a rename across filesystems
+ // fails with EXDEV, and a path elsewhere lets a caller publish an
+ // unrelated file onto the target), and it must be a regular file rather
+ // than a link — renaming a link over the target publishes whatever the
+ // link points at, which is the same trust problem as writing through a
+ // dangling symlink in resolvePublishTarget.
+ const supplied = path.resolve(options.tempPath)
+ if (path.dirname(supplied) !== path.resolve(dirPath)) {
+ throw new StagingPathError(
+ `Staging file must sit in the target's directory (${dirPath}), got ${supplied}`,
+ supplied,
+ )
+ }
+ // BigInt stats: on NTFS/ReFS the file identity can exceed Number.MAX_SAFE_INTEGER, and
+ // a rounded number makes two different files look identical (rejecting a valid staging
+ // file) or hides a real alias.
+ const stagingStat = await fs.lstat(supplied, { bigint: true })
+ if (stagingStat.isSymbolicLink() || !stagingStat.isFile()) {
+ throw new StagingPathError(
+ `Staging file must be a regular file, not ${stagingStat.isSymbolicLink() ? "a symlink" : "another file type"}`,
+ supplied,
+ )
+ }
+ // A staging path that is the target would be unlinked by the failure handler
+ // while it still holds the only copy of the content, so a failed write would
+ // delete the file it was meant to protect. Compare identities, not spellings:
+ // an alias of the target is the same hazard.
+ // Only a missing target may be skipped: an EACCES/ELOOP/ENOTDIR here means the
+ // identity comparison could not be made, and treating that as "no target" would let a
+ // staging alias reach the commit and let cleanup delete the file it was meant to
+ // protect.
+ const targetStat = await fs.lstat(targetPath, { bigint: true }).catch((error: unknown) => {
+ if (getErrorCode(error) !== "ENOENT") {
+ throw new StagingPathError("Staging file could not be compared with the target", supplied)
+ }
+ return null
+ })
+ if (
+ targetStat &&
+ typeof stagingStat.ino === "bigint" &&
+ typeof targetStat.ino === "bigint" &&
+ stagingStat.ino === targetStat.ino &&
+ stagingStat.dev === targetStat.dev
+ ) {
+ throw new StagingPathError("Staging file must not be the target itself", supplied)
+ }
+ // The caller's own path is used as given; only the check is canonical.
+ tempPath = options.tempPath
+ } else {
+ stagingDir = _stagingDir(dirPath)
+ tempPath = _tempName(stagingDir, "safeWriteText")
+ }
+
+ let backupPath: string | null = null
+ let releaseBackupOnSuccess = false
+ // Set once the commit rename has published the new content. After that point the
+ // backup is no longer a safe restore source: rolling it back would overwrite
+ // content the caller can already observe at the target path.
+ // Non-null only when the win32 step-2 block saved a successful DACL dump:
+ // it gates the step-5 restore and is tracked for the cleanup unlinks.
+ let daclDumpPath: string | null = null
+ // Warning delivery must never abort the write: the notice below describes a leftover
+ // beside a committed file, and a caller whose callback throws (a UI sink, a logger that is
+ // mid-restart) must not turn that into a different failure than the one the caller is told
+ // about. Declared above the try so the failure handler can report a retained backup through it.
+ const warn = (message: string) => {
+ const report = (label: string, error: unknown) => {
+ console.warn(
+ `safeWriteText: onWarning callback ${label}: ${error instanceof Error ? error.message : String(error)}`,
+ )
+ }
+ try {
+ const sink = options?.onWarning ?? ((m: string) => console.warn(m))
+ const result: unknown = sink(message)
+ // A sink may be async - TypeScript accepts a value-returning callback where
+ // a void one is expected. Awaiting it would let warning delivery delay a
+ // write that has already committed (and hang it if the sink never settles),
+ // while leaving the promise unhandled turns a rejection into an unhandled
+ // rejection, which under Node's default mode can end the process after a
+ // successful write. Attach a handler without awaiting.
+ if (result instanceof Promise) {
+ result.catch((error: unknown) => report("rejected", error))
+ }
+ } catch (error: unknown) {
+ report("failed", error)
+ }
+ }
+ try {
+ // -- Step 1: write content to staging temp file -------------------
+ if (!options?.tempPath) {
+ // Preserve the existing target's permissions: the staging file must
+ // not be published wider than the file it replaces (a 0o600 target
+ // must not become 0o644 through the atomic rename).
+ // Encode before opening the staging file: an encoding Node cannot
+ // represent must not leave a half-written temp file behind.
+ // A string is encoded as UTF-8; bytes handed in by the caller (the
+ // extension host encodes a document with VS Code's own codec, which
+ // covers the legacy code pages Node cannot represent) are published
+ // unchanged.
+ const buffer = Buffer.from(content)
+ let targetMode = 0o644 // default for a fresh target
+ let targetExists = false
+ try {
+ targetMode = fsSync.statSync(targetPath).mode & 0o777
+ targetExists = true
+ } catch (error: unknown) {
+ if (getErrorCode(error) !== "ENOENT") throw error
+ // target does not exist yet - keep the default
+ }
+ // openSync's creation mode is narrowed by the process umask, so an
+ // existing 0o664 target would be published as 0o644 through the
+ // rename. Apply the existing target's exact mode on the fd, as the
+ // caller-staged branch does; a fresh target keeps the default mode.
+ const fd = fsSync.openSync(tempPath, "w", targetMode)
+ try {
+ if (targetExists) {
+ fsSync.fchmodSync(fd, targetMode)
+ }
+ // Loop until every byte is written: writeSync can report a short
+ // (partial) write, and publishing a truncated staging file would
+ // commit corrupt content.
+ let offset = 0
+ while (offset < buffer.length) {
+ offset += fsSync.writeSync(fd, buffer, offset, buffer.length - offset)
+ }
+ fsSync.fsyncSync(fd)
+ } finally {
+ fsSync.closeSync(fd)
+ }
+ } else {
+ // Preserve the existing target's mode (CWE-732): the caller-staged
+ // temp carries its own creation mode, and publishing it as-is would
+ // widen a restrictive target (e.g. 0o600 -> 0o644) through rename.
+ // The mode is applied with fchmodSync on the open fd (AFTER openSync):
+ // chmodSync on the path before the open would make a read-only target
+ // (0o400/0o444) fail openSync(tempPath, "r+") with EACCES.
+ let targetMode: number | null = null
+ try {
+ targetMode = fsSync.statSync(targetPath).mode & 0o777
+ } catch (error: unknown) {
+ if (getErrorCode(error) !== "ENOENT") throw error
+ // target does not exist yet - keep the temp's default mode
+ }
+ const fd = fsSync.openSync(tempPath, "r+")
+ try {
+ if (targetMode !== null) {
+ fsSync.fchmodSync(fd, targetMode)
+ }
+ fsSync.fsyncSync(fd)
+ } finally {
+ fsSync.closeSync(fd)
+ }
+ }
+
+ // -- Step 2 (win32): save DACL BEFORE the backup copy -----------
+ const platform = options?.platform ?? process.platform
+ if (platform === "win32") {
+ let accessError: unknown = null
+ try {
+ await fs.access(targetPath) // target exists?
+ } catch (error: unknown) {
+ accessError = error
+ }
+ if (accessError === null) {
+ const dumpPath = _tempName(dirPath, "safeWriteText.acl")
+ const saved = await _saveDaclWindows(targetPath, dumpPath, options?.execFileRunner)
+ if (saved) {
+ // Only a successfully saved dump may be restored onto the
+ // committed file (step 5).
+ daclDumpPath = dumpPath
+ } else {
+ // A failed icacls may have left a partial dump behind;
+ // remove it now (best-effort) so no partial dump survives and
+ // no later step can restore from it.
+ await fs.unlink(dumpPath).catch(() => {})
+ // The target exists and its DACL could not be captured, so the commit rename
+ // would replace it with a file that inherits different access rights, and nothing
+ // here can verify an equivalent restrictive ACL on that replacement. The publish is
+ // refused instead of warned about: a save that silently changed who can read the
+ // file is not a save the caller can trust. Nothing is committed yet, so the target
+ // still holds its content, and this throw lands in the handler at the bottom of
+ // this try - the one place that removes the staged file and this write's own
+ // staging directory - so a refused publish strands neither.
+ throw new DaclInspectionError(targetPath, "save", null)
+ }
+ } else if (getErrorCode(accessError) !== "ENOENT") {
+ // Not "absent": the target is there but its access rights could not be read
+ // (EACCES, ...), so publishing would replace a file whose rights this call never
+ // learned. Same rule as the failed save above: refuse before anything is committed.
+ throw new DaclInspectionError(targetPath, "inspect", accessError)
+ }
+ }
+ try {
+ // -- Step 3 (backup:true): durable copy target -> backup ----
+ if (options?.backup) {
+ try {
+ await fs.access(targetPath)
+ backupPath = _tempName(dirPath, "safeWriteText.bak")
+ // Copy, never move. Renaming the target away leaves the canonical path absent for
+ // the whole commit window: readers see a missing file, and a concurrent
+ // writer can create a new target that a later rollback would destroy. A copy
+ // keeps the target present, so the step 4 rename is the only change to the
+ // canonical path. The copy is flushed so the retained content survives a crash.
+ try {
+ // Create the destination BEFORE any content exists at it, with the mode fixed
+ // at open time. fs.copyFile picks the destination mode itself (the platform
+ // creation mask subject to umask on some platforms, the source's mode - or its
+ // read-only attribute - on others), so letting it create the file would either
+ // leave a restrictive target's bytes briefly readable to others, or leave the
+ // copy unwritable so the fsync open below fails with EACCES. open() ignores its
+ // mode argument for an existing file, so this 0o600 survives the copy on POSIX;
+ // the chmod afterwards is what clears a copied read-only attribute on Windows
+ // and keeps a backup of a permissive file private.
+ const seedFd = fsSync.openSync(backupPath, "wx", 0o600)
+ fsSync.closeSync(seedFd)
+ await fs.copyFile(targetPath, backupPath)
+ await fs.chmod(backupPath, 0o600)
+ // "r+" not "r": fsync on a read-only handle is EPERM on Windows, and the same
+ // flag the staged temp file uses above.
+ const backupFd = fsSync.openSync(backupPath, "r+")
+ try {
+ fsSync.fsyncSync(backupFd)
+ } finally {
+ fsSync.closeSync(backupFd)
+ }
+ } catch (backupError: unknown) {
+ // A partial backup must not outlive this attempt: it is not a complete copy
+ // of anything, and once the write fails nothing else removes it.
+ await fs.unlink(backupPath).catch(() => {})
+ backupPath = null
+ throw backupError
+ }
+ releaseBackupOnSuccess = true
+ } catch (err: unknown) {
+ if (getErrorCode(err) !== "ENOENT") throw err
+ }
+ }
+
+ // -- Step 4: atomic rename temp -> target ---------------------
+ await fs.rename(tempPath, targetPath)
+
+ // -- Step 4b (POSIX): fsync the parent directory so the directory entry
+ // changed by the commit rename is durable, not just the file content.
+ if (platform !== "win32") {
+ try {
+ const dirFd = fsSync.openSync(dirPath, "r")
+ try {
+ fsSync.fsyncSync(dirFd)
+ } finally {
+ fsSync.closeSync(dirFd)
+ }
+ } catch (error: unknown) {
+ // The content rename committed, but the directory entry that
+ // points at it is not known to be durable. Reporting success
+ // here would let a caller believe the write survives a crash,
+ // so the failure is surfaced as its own error: the caller can
+ // still find the content at the target, it just cannot rely on
+ // the directory entry having reached the disk.
+ throw new PostCommitDurabilityError(targetPath, error)
+ }
+ }
+
+ // -- Step 5 (win32): restore DACL AFTER commit rename ---------
+ // daclDumpPath is non-null only when the win32 step-2 block saved a
+ // successful dump, so this gate is closed on every other platform
+ // and on every failed save.
+ if (daclDumpPath !== null) {
+ const restoredDir = path.dirname(targetPath)
+ const restored = await _restoreDaclWindows(restoredDir, daclDumpPath, options?.execFileRunner)
+ if (!restored) {
+ // The content is committed, but the published file answers to a different DACL
+ // from the one that was saved, and nothing here verified an equivalent
+ // restrictive ACL on the replacement. This reaches the caller as an error rather
+ // than a warning: no caller can observe success for a publish whose DACL was not
+ // preserved. The handler at the bottom of this try keeps the backup copy for this
+ // error instead of rolling the published content back, so the throw reports the
+ // changed access rights without undoing a write the caller can already observe.
+ throw new DaclRestoreError(targetPath, null)
+ }
+ }
+
+ // -- Step 6 (backup:true): delete backup on success -----------
+ if (releaseBackupOnSuccess && backupPath) {
+ try {
+ await fs.unlink(backupPath)
+ } catch {
+ // non-fatal — orphaned backup is acceptable
+ }
+ }
+ } finally {
+ // Unlink DACL dump regardless of success/failure in this span.
+ if (daclDumpPath !== null) {
+ await fs.unlink(daclDumpPath).catch(() => {})
+ }
+ }
+
+ // tempPath is now the committed file; no cleanup needed.
+
+ // Best-effort: remove the now-empty staging directory. Self-staged
+ // writes only, and only this write's own directory: a per-write directory
+ // cannot be the one another concurrent write is still using. A failure must
+ // never un-commit a published file, so the removal swallows all errors.
+ if (stagingDir) {
+ await fs.rmdir(stagingDir).catch(() => {})
+ }
+ } catch (originalError: unknown) {
+ // Only a pre-commit failure can restore the backup. Once the commit rename
+ // published, a later failure (for example the post-commit directory fsync)
+ // must not overwrite the published content with the old file.
+ if (backupPath && releaseBackupOnSuccess) {
+ if (originalError instanceof DaclRestoreError) {
+ // The one post-commit failure that keeps its copy. The published file answers to
+ // the descriptor its staging file was created with, and this copy - made from the
+ // file the publish replaced, so on Windows it carries that file's security
+ // attributes - is the only artifact left holding the access rights that could not
+ // be restored. Deleting it would destroy the only recovery path for exactly the
+ // fact the error reports, so the copy stays and its path is named to the human:
+ // the caller already holds the error, and this primitive reports a leftover on
+ // the warning sink because it has no structured result to carry it on.
+ warn(
+ `${originalError.message}; its backup copy is kept at ${backupPath} and still carries the access rights of the file it replaced.`,
+ )
+ } else {
+ // Nothing to restore: the backup is a copy, so the target still holds whatever
+ // the commit left there - before the commit that is the pre-write content, and
+ // after it the published content. Either way the copy has served its purpose
+ // and must not be left beside the target where no caller can find it.
+ await fs.unlink(backupPath).catch(() => {})
+ }
+ backupPath = null
+ }
+ try {
+ await fs.unlink(tempPath).catch(() => {})
+ } catch {
+ // cleanup failure is non-fatal
+ }
+
+ // A failed self-staged write must not leave its staging directory behind.
+ // Only the directory this write created, and only after its temp file is
+ // gone, so the directory is empty and the removal stays best-effort.
+ if (stagingDir) {
+ await fs.rmdir(stagingDir).catch(() => {})
+ }
+
+ if (daclDumpPath !== null) {
+ await fs.unlink(daclDumpPath).catch(() => {})
+ }
+
+ throw originalError
+ }
+}
diff --git a/src/utils/__tests__/fileLock.canonicalKey.spec.ts b/src/utils/__tests__/fileLock.canonicalKey.spec.ts
new file mode 100644
index 0000000000..c60afdc56b
--- /dev/null
+++ b/src/utils/__tests__/fileLock.canonicalKey.spec.ts
@@ -0,0 +1,71 @@
+// npx vitest run utils/__tests__/fileLock.canonicalKey.spec.ts
+
+import path from "path"
+import type { BigIntStats } from "fs"
+import * as fs from "fs/promises"
+import * as lockfile from "proper-lockfile"
+import { withFileLock } from "../fileLock"
+import { resolveLockKey } from "../../services/file-safety/safeWriteText"
+
+vi.mock("proper-lockfile", () => ({
+ lock: vi.fn(async () => async () => {}),
+ unlock: vi.fn(async () => {}),
+}))
+
+vi.mock("fs/promises", async () => {
+ const actual = await vi.importActual("fs/promises")
+ return { ...actual, realpath: vi.fn(), lstat: vi.fn(), readlink: vi.fn() }
+})
+
+const mockedRealpath = vi.mocked(fs.realpath)
+const mockedLstat = vi.mocked(fs.lstat)
+const mockedReadlink = vi.mocked(fs.readlink)
+const mockedLock = vi.mocked(lockfile.lock)
+
+const dir = path.resolve(path.join(path.sep + "work", "history"))
+const referent = path.join(dir, "item.json")
+const alias = path.join(dir, "alias.json")
+
+beforeEach(() => {
+ mockedRealpath.mockReset()
+ mockedLstat.mockReset()
+ mockedReadlink.mockReset()
+ mockedLock.mockReset()
+ // alias.json is a symlink to item.json; everything else resolves to itself.
+ mockedRealpath.mockImplementation(async (target) => (target === alias ? referent : String(target)))
+ // fs/promises types lstat as returning BigIntStats and this mock only ever needs
+ // isSymbolicLink(), so the assertion is single-step and names the subset the double
+ // actually fakes. AGENTS.md asks for a reason next to a cast a typed API cannot
+ // express: no test in this file reads a bigint field, so no bigint field is faked.
+ mockedLstat.mockImplementation(async () => ({ isSymbolicLink: () => false }) as BigIntStats)
+ mockedReadlink.mockRejectedValue(Object.assign(new Error("not a link"), { code: "EINVAL" }))
+})
+
+describe("withFileLock lock-key canonicalization", () => {
+ it("locks the canonical referent that safeWriteJson locks, not the raw alias", async () => {
+ // The compound-atomicity contract of task-history deletion is that an
+ // unlink under this helper and a safeWriteJson read-modify-write on the
+ // same file serialize. That holds only while both compute ONE key:
+ // safeWriteJson locks resolveLockKey(target), so withFileLock must too.
+ // Locking the raw alias here would watch a different lock file and let
+ // the deletion interleave with the merge write.
+ await withFileLock(alias, async () => undefined)
+
+ expect(mockedLock).toHaveBeenCalledTimes(1)
+ expect(mockedLock.mock.calls[0][0]).toBe(referent)
+ // The shared-key contract stated directly: whatever safeWriteJson would
+ // lock for the same path is exactly what this helper locked.
+ expect(mockedLock.mock.calls[0][0]).toBe(await resolveLockKey(alias))
+ })
+
+ it("hands the operation the caller's own path so its unlink keeps alias semantics", async () => {
+ // unlink(alias) removes the link; unlink(referent) removes the target
+ // file. Deletion must act on the path the caller named, even though the
+ // lock is taken on the canonical key.
+ const seen: string[] = []
+ await withFileLock(alias, async (absoluteFilePath) => {
+ seen.push(absoluteFilePath)
+ })
+ expect(seen).toEqual([alias])
+ })
+})
diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts
index 49807ea154..6ca7004566 100644
--- a/src/utils/fileLock.ts
+++ b/src/utils/fileLock.ts
@@ -1,5 +1,6 @@
import * as path from "path"
import { tracePersistenceEvent } from "../core/task-persistence/persistenceTrace"
+import { resolveLockKey } from "../services/file-safety/safeWriteText"
import * as lockfile from "proper-lockfile"
/**
@@ -73,7 +74,17 @@ export async function withFileLock(
options?: FileLockOptions,
): Promise {
const absoluteFilePath = path.resolve(filePath)
- const releaseLock = await acquireFileLock(absoluteFilePath, options)
+ // Lock the canonical key - the same one safeWriteJson computes - so a symlink
+ // alias and its referent take ONE lock. Locking the raw path here would let a
+ // deletion through this helper run concurrently with a safeWriteJson
+ // read-modify-write on the referent (the two would watch different lock
+ // files), breaking the compound atomicity the deletion contract promises.
+ // The operation still receives the caller's resolved path: its own file
+ // operations (e.g. the task-history unlink) must keep the caller's alias
+ // semantics - unlinking the referent instead of the alias would delete a
+ // different directory entry.
+ const lockKey = await resolveLockKey(absoluteFilePath)
+ const releaseLock = await acquireFileLock(lockKey, options)
let result: T
try {
From bf215bb4d878b01714be0551d507ba296c778eb4 Mon Sep 17 00:00:00 2001
From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com>
Date: Fri, 13 Nov 2026 09:11:36 +0800
Subject: [PATCH 2/5] fix(file-lock): take the canonical lock key once, inside
acquireFileLock
Every caller of the shared advisory lock protocol gets its key computed here, so a symlink alias and its referent take one lock and safeWriteJson serializes with withFileLock instead of watching a second lock file. withFileLock still hands its operation the caller's resolved path so a task-history unlink keeps alias semantics. Answers review comment 4545130063 on pull 1913.
---
src/utils/fileLock.ts | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts
index 6ca7004566..8d1717eb49 100644
--- a/src/utils/fileLock.ts
+++ b/src/utils/fileLock.ts
@@ -28,7 +28,17 @@ export interface FileLockOptions {
* while holding it.
*/
export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> {
- const absoluteFilePath = path.resolve(filePath)
+ // Lock the canonical key - the referent of a symlink alias - so an alias and its
+ // referent take ONE lock. Every caller of this protocol, safeWriteJson included,
+ // gets the key computed here: a caller that passed the raw spelling would watch a
+ // different lock file than the write it means to serialize with, which is how a
+ // deletion through withFileLock could run beside a safeWriteJson read-modify-write
+ // on the referent and break the compound atomicity the deletion contract promises.
+ // withFileLock still hands its operation the caller's resolved path, because the
+ // operation's own file operations (the task-history unlink) must keep the caller's
+ // alias semantics - unlinking the referent instead of the alias would delete a
+ // different directory entry.
+ const absoluteFilePath = await resolveLockKey(path.resolve(filePath))
if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath })
try {
return await lockfile.lock(absoluteFilePath, {
@@ -74,17 +84,7 @@ export async function withFileLock(
options?: FileLockOptions,
): Promise {
const absoluteFilePath = path.resolve(filePath)
- // Lock the canonical key - the same one safeWriteJson computes - so a symlink
- // alias and its referent take ONE lock. Locking the raw path here would let a
- // deletion through this helper run concurrently with a safeWriteJson
- // read-modify-write on the referent (the two would watch different lock
- // files), breaking the compound atomicity the deletion contract promises.
- // The operation still receives the caller's resolved path: its own file
- // operations (e.g. the task-history unlink) must keep the caller's alias
- // semantics - unlinking the referent instead of the alias would delete a
- // different directory entry.
- const lockKey = await resolveLockKey(absoluteFilePath)
- const releaseLock = await acquireFileLock(lockKey, options)
+ const releaseLock = await acquireFileLock(absoluteFilePath, options)
let result: T
try {
From cf7ab260f98c175b0e1ce416335196f92a85cc38 Mon Sep 17 00:00:00 2001
From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com>
Date: Fri, 13 Nov 2026 09:11:37 +0800
Subject: [PATCH 3/5] test(file-lock): pin one lock key for withFileLock and
safeWriteJson
Pairing test for review comment 4545130063: both doors must lock the canonical referent of a symlink alias. Removing the canonicalization from acquireFileLock makes both rows fail, so the test is the ask and not a mirror of the fix.
---
src/utils/__tests__/lockKeyAlignment.spec.ts | 83 ++++++++++++++++++++
1 file changed, 83 insertions(+)
create mode 100644 src/utils/__tests__/lockKeyAlignment.spec.ts
diff --git a/src/utils/__tests__/lockKeyAlignment.spec.ts b/src/utils/__tests__/lockKeyAlignment.spec.ts
new file mode 100644
index 0000000000..768df5b963
--- /dev/null
+++ b/src/utils/__tests__/lockKeyAlignment.spec.ts
@@ -0,0 +1,83 @@
+// Pairing test for the ask in review comment 4545130063 on pull 1913, "Use the same lock key as
+// `safeWriteJson`." withFileLock (the door a task-history deletion comes through) and safeWriteJson
+// share ONE advisory lock protocol inside acquireFileLock, so for a symlink alias both must lock the
+// canonical referent key. Take the canonicalization out of acquireFileLock and both callers fall back
+// to the caller's raw spelling: both rows below fail there, which is what makes this an answer to the
+// ask rather than a mirror of the fix.
+import * as fs from "fs/promises"
+import * as os from "os"
+import * as path from "path"
+import type { BigIntStats } from "fs"
+import * as lockfile from "proper-lockfile"
+import { safeWriteJson } from "../safeWriteJson"
+import { withFileLock } from "../fileLock"
+import { resolveLockKey } from "../../services/file-safety/safeWriteText"
+
+vi.mock("proper-lockfile", () => ({
+ lock: vi.fn(async () => async () => {}),
+ unlock: vi.fn(async () => {}),
+}))
+
+vi.mock("fs/promises", async () => {
+ const actual = await vi.importActual("fs/promises")
+ return { ...actual, realpath: vi.fn(), lstat: vi.fn(), readlink: vi.fn() }
+})
+
+const mockedRealpath = vi.mocked(fs.realpath)
+const mockedLstat = vi.mocked(fs.lstat)
+const mockedReadlink = vi.mocked(fs.readlink)
+const mockedLock = vi.mocked(lockfile.lock)
+
+let dir = ""
+let referent = ""
+let alias = ""
+
+beforeAll(async () => {
+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "lockkey-alignment-"))
+ referent = path.join(dir, "task.json")
+ alias = path.join(dir, "alias.json")
+ await fs.writeFile(referent, "{}", "utf8")
+})
+
+afterAll(async () => {
+ if (dir) await fs.rm(dir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+ mockedRealpath.mockReset()
+ mockedLstat.mockReset()
+ mockedReadlink.mockReset()
+ mockedLock.mockReset()
+ // alias.json is a symlink to task.json; every other path resolves to itself.
+ mockedRealpath.mockImplementation(async (target) => (String(target) === alias ? referent : String(target)))
+ // fs/promises types lstat as returning BigIntStats and this double only ever needs isSymbolicLink().
+ // AGENTS.md asks for a reason beside a cast a typed API cannot express: no row in this file reads a
+ // bigint field, so no bigint field is faked.
+ mockedLstat.mockImplementation(async () => ({ isSymbolicLink: () => false }) as BigIntStats)
+ mockedReadlink.mockRejectedValue(Object.assign(new Error("not a link"), { code: "EINVAL" }))
+})
+
+describe("lock-key alignment between withFileLock and safeWriteJson", () => {
+ it("locks the canonical referent for an alias, whichever door the caller comes through", async () => {
+ await withFileLock(alias, async () => undefined)
+ const deletionKey = mockedLock.mock.calls[0][0]
+ await safeWriteJson(alias, { pinned: 1 })
+ const writeKeys = mockedLock.mock.calls.map((call) => call[0])
+ const writeKey = writeKeys[writeKeys.length - 1]
+ expect(deletionKey).toBe(referent)
+ expect(writeKey).toBe(referent)
+ expect(deletionKey).toBe(writeKey)
+ expect(deletionKey).toBe(await resolveLockKey(alias))
+ })
+
+ it("keeps one key for a plain path and hands the operation its own path", async () => {
+ let seenByOperation = ""
+ await withFileLock(referent, async (absoluteFilePath) => { seenByOperation = absoluteFilePath })
+ const plainKey = mockedLock.mock.calls[0][0]
+ await safeWriteJson(referent, { pinned: 2 })
+ const plainWriteKeys = mockedLock.mock.calls.map((call) => call[0])
+ expect(plainKey).toBe(plainWriteKeys[plainWriteKeys.length - 1])
+ expect(plainKey).toBe(await resolveLockKey(referent))
+ expect(seenByOperation).toBe(referent)
+ })
+})
From b011b047b9e0f94ec1c8f1886e7120576face228 Mon Sep 17 00:00:00 2001
From: f0-1528 <136036952+easonLiangWorldedtech@users.noreply.github.com>
Date: Sun, 15 Nov 2026 16:09:51 +0800
Subject: [PATCH 4/5] f01528 style repair: format the lock-key alignment spec
to the repository pinned prettier style
---
src/utils/__tests__/lockKeyAlignment.spec.ts | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/src/utils/__tests__/lockKeyAlignment.spec.ts b/src/utils/__tests__/lockKeyAlignment.spec.ts
index 768df5b963..c2c323f223 100644
--- a/src/utils/__tests__/lockKeyAlignment.spec.ts
+++ b/src/utils/__tests__/lockKeyAlignment.spec.ts
@@ -72,7 +72,9 @@ describe("lock-key alignment between withFileLock and safeWriteJson", () => {
it("keeps one key for a plain path and hands the operation its own path", async () => {
let seenByOperation = ""
- await withFileLock(referent, async (absoluteFilePath) => { seenByOperation = absoluteFilePath })
+ await withFileLock(referent, async (absoluteFilePath) => {
+ seenByOperation = absoluteFilePath
+ })
const plainKey = mockedLock.mock.calls[0][0]
await safeWriteJson(referent, { pinned: 2 })
const plainWriteKeys = mockedLock.mock.calls.map((call) => call[0])
From 6546e93bad70e75b4afe3d3eb8012018fe7b4a86 Mon Sep 17 00:00:00 2001
From: "user.email" <136036952+easonLiangWorldedtech@users.noreply.github.com>
Date: Sun, 15 Nov 2026 18:57:20 +0800
Subject: [PATCH 5/5] fix(file-safety): stop resolveLockKey guessing a lock key
for an unreadable path
resolveLockKey caught every error resolvePublishTarget rethrows, and it mapped
every readlink failure to undefined. A path this process could not read still
produced a lock key, built from the literal spelling instead of the canonical
one, so a writer that could read the parent directory and a writer that could
not took two locks for one file and a read-modify-write under them lost a side.
Only ENOENT, meaning "this path is not there yet", may start the bounded
fallback walk, and readlink only ends it for the codes that honestly answer
"there is no link to follow": ENOENT, EINVAL and ENOTDIR. A code that says
nothing about the link (EACCES, ELOOP, EIO) propagates from both halves, which
is what resolvePublishTarget and canonicalDirKey already do.
Adds the three regression tests the review asked for inside describe(
"resolveLockKey"): one for each propagating half, and one pinning the honest
EINVAL/ENOTDIR fallback so a dangling link, a link swapped for a plain file,
and a two-link cycle all still get a key. Lines 1336 to 1363 of the spec are
unchanged.
Review context: pull 1913, review comment 5909008553.
---
.../__tests__/safeWriteText.spec.ts | 59 +++++++++++++++++++
src/services/file-safety/safeWriteText.ts | 31 +++++++++-
2 files changed, 87 insertions(+), 3 deletions(-)
diff --git a/src/services/file-safety/__tests__/safeWriteText.spec.ts b/src/services/file-safety/__tests__/safeWriteText.spec.ts
index fc8f30e212..7b48a75056 100644
--- a/src/services/file-safety/__tests__/safeWriteText.spec.ts
+++ b/src/services/file-safety/__tests__/safeWriteText.spec.ts
@@ -1361,6 +1361,65 @@ describe("resolveLockKey", () => {
)
expect(fs.readlink).toHaveBeenCalledTimes(8)
})
+
+ it("propagates a search-permission failure on the publish target instead of guessing a key", async () => {
+ // A parent directory this process may not search fails realpath on the path with EACCES
+ // while realpath of that same directory still succeeds - exactly the shape in which the
+ // fallback walk returns a plausible key. Swallowing the EACCES would give this writer a
+ // key built from the literal path while a writer that could search the directory gets
+ // the canonical one, so two writers would take two locks for one file and a
+ // read-modify-write under them would lose one side.
+ const alias = path.resolve("/tmp/unsearchable/file.json")
+ const canonicalDir = path.resolve("/tmp/canonical-parent")
+ const eacces = Object.assign(new Error("EACCES: permission denied, " + alias), { code: "EACCES" })
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(false))
+ vi.mocked(fs.realpath).mockImplementation(async (p) => {
+ const s = String(p)
+ if (s === alias) throw eacces
+ if (s === path.dirname(alias)) return canonicalDir
+ return s
+ })
+ // Everything the fallback walk needs is set up to answer, so the only thing this
+ // test can react to is what resolveLockKey does with the EACCES.
+ vi.mocked(fs.readlink).mockRejectedValue(enoent)
+
+ await expect(resolveLockKey(alias)).rejects.toMatchObject({ code: "EACCES" })
+ expect(fs.readlink).not.toHaveBeenCalled()
+ })
+
+ it("propagates a readlink failure whose code says nothing about the link", async () => {
+ // realpath answers ENOENT and lstat answers symlink: a dangling link, the case this
+ // function exists to tolerate. The readlink then fails with EIO, which says nothing
+ // about whether the path is a link - a failing share, a short read - and answering
+ // that with the literal path would put this writer on a lock keyed by a spelling no
+ // other writer computes.
+ const alias = path.resolve("/tmp/dangling/file.json")
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ const eio = Object.assign(new Error("EIO: i/o error, readlink"), { code: "EIO" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true))
+ vi.mocked(fs.readlink).mockRejectedValue(eio)
+
+ await expect(resolveLockKey(alias)).rejects.toMatchObject({ code: "EIO" })
+ })
+
+ it("ends the walk when readlink honestly answers that there is no link to follow", async () => {
+ // EINVAL is what readlink answers when the lstat saw a link and the readlink found a
+ // plain file, and ENOTDIR when a component stopped being a directory mid-walk. Both
+ // are truthful answers of "there is no link here", so the walk still ends at the key
+ // reached instead of propagating: only codes that carry no information about the link
+ // may stop this function from returning a key.
+ const alias = path.resolve("/tmp/swapped/file.json")
+ const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+ vi.mocked(fs.realpath).mockRejectedValue(enoent)
+ vi.mocked(fs.lstat).mockResolvedValue(_fileStats(true))
+ for (const code of ["EINVAL", "ENOTDIR"]) {
+ vi.mocked(fs.readlink).mockRejectedValue(Object.assign(new Error(code + ": readlink"), { code }))
+ await expect(resolveLockKey(alias)).resolves.toBe(alias)
+ }
+ expect(fs.readlink).toHaveBeenCalledTimes(2)
+ })
})
describe("caller-supplied staging path", () => {
diff --git a/src/services/file-safety/safeWriteText.ts b/src/services/file-safety/safeWriteText.ts
index 8f7a924810..ab1de108f9 100644
--- a/src/services/file-safety/safeWriteText.ts
+++ b/src/services/file-safety/safeWriteText.ts
@@ -249,6 +249,14 @@ async function canonicalDirKey(absoluteFilePath: string): Promise {
}
}
+const NO_LINK_ERROR_CODES = new Set(["ENOENT", "EINVAL", "ENOTDIR"])
+
+/** Whether a link-walk failure carries a code that means "there is no link to follow here". */
+function isNoLinkFailure(error: unknown): boolean {
+ const code = getErrorCode(error)
+ return code !== undefined && NO_LINK_ERROR_CODES.has(code)
+}
+
/**
* Lock key for a publish target: the symlink referent when the path is an
* existing symlink, the path itself otherwise. Unlike resolvePublishTarget this
@@ -257,17 +265,34 @@ async function canonicalDirKey(absoluteFilePath: string): Promise {
* and backup mode keeps a copy beside it).
* The walk is bounded so a two-link cycle terminates, and every key it returns is
* canonicalized through canonicalDirKey.
+ * A parent directory this process may not search makes realpath fail with EACCES on the
+ * path while canonicalDirKey can still canonicalize through that directory, so only
+ * ENOENT - "this path is not there yet" - may start the fallback walk; every other
+ * failure of resolvePublishTarget propagates. A readlink failure likewise only ends the
+ * walk when its code means "no link to follow" (ENOENT, EINVAL, ENOTDIR): a code that
+ * says nothing about the link (EACCES, ELOOP, EIO) propagates too, because a key guessed
+ * from a path this process could not read hands out a second lock for one file.
*/
export async function resolveLockKey(absoluteFilePath: string): Promise {
try {
return await canonicalDirKey(await resolvePublishTarget(absoluteFilePath))
- } catch {
+ } catch (error) {
+ // Only "this path is not there yet" may start the fallback walk. Any other failure of
+ // resolvePublishTarget (EACCES or EIO on a parent directory among them) says nothing
+ // about the chain, and a key built from the literal path would put this writer on a
+ // different lock than a writer that could read the directory.
+ if (getErrorCode(error) !== "ENOENT") throw error
// A real readlink throws for anything that is not a link, so a normal chain
// ends the walk. Two links that point at each other never would, so the
- // walk is bounded and callers use the key they actually reached.
+ // walk is bounded and callers use the key they actually reached. A failure whose
+ // code means "no link to follow" ends the walk the same way; any other failure
+ // propagates instead of ending the walk with undefined.
let key = absoluteFilePath
for (let depth = 0; depth < 8; depth++) {
- const target = await fs.readlink(key).catch(() => undefined)
+ const target = await fs.readlink(key).catch((readlinkError: unknown) => {
+ if (isNoLinkFailure(readlinkError)) return undefined
+ throw readlinkError
+ })
if (target === undefined) return await canonicalDirKey(key)
key = await canonicalDirKey(path.resolve(path.dirname(key), target))
}