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..7b48a75056
--- /dev/null
+++ b/src/services/file-safety/__tests__/safeWriteText.spec.ts
@@ -0,0 +1,1612 @@
+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)
+ })
+
+ 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", () => {
+ 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..ab1de108f9
--- /dev/null
+++ b/src/services/file-safety/safeWriteText.ts
@@ -0,0 +1,685 @@
+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
+ }
+}
+
+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
+ * 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.
+ * 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 (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. 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((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))
+ }
+ 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/__tests__/lockKeyAlignment.spec.ts b/src/utils/__tests__/lockKeyAlignment.spec.ts
new file mode 100644
index 0000000000..c2c323f223
--- /dev/null
+++ b/src/utils/__tests__/lockKeyAlignment.spec.ts
@@ -0,0 +1,85 @@
+// 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)
+ })
+})
diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts
index 49807ea154..8d1717eb49 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"
/**
@@ -27,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, {