Skip to content

Commit 0a76a7a

Browse files
fix(utils): take the delete lock on the key the writer publishes under
deleteJsonFile locked the path it was handed. Every other writer-side entry point resolves first: guardedWrite.ts:192 and :257 and DiffViewProvider.ts:722 call withFileLock(await resolveLockKey(...), ...), and safeWriteJson.ts:346 acquires on a key that came from resolveLockKey. jsonFileRecovery.ts:80 was the odd one out, and lock identity here is lexical - acquireFileLock derives the artefact from the path with lockPathFor - so a delete asked for through a link was contending for <link>.lock while the writer held <referent>.lock. Two spellings, two locks, and no exclusion at all. The measurement that frames this: on this host a file symlink answers EPERM, so the fixture fell back to a hard link, and resolveLockKey answered two different keys for the pair (one key :: false), a writer holding the referent lock did not block the alias delete (it proceeded, and removed the alias spelling while the referent survived - readdir :: ["history_item.json"]), and the same delete asked for by the referent's own name was refused ELOCKED. The alias only becomes contention when there is a referent to resolve, which is the half this host cannot build for a file. What the alignment costs, stated as the tradeoff it is: a delete through an alias now removes the object the alias refers to and leaves the caller's own spelling standing as a dangling symlink, and the leftover-prefix scan runs against the canonical basename too. That is exclusion bought by deleting the canonical object instead of the named link. The alternative shape exists and is not implemented here: lock on the canonical key and unlink path.resolve(filePath), which keeps today's unlink semantics while still contending correctly. Choosing it is the maintainer of the public src/utils/jsonFileRecovery.ts surface, not me, because it changes what a caller of a documented helper gets. No caller in this repository exercises the difference: deleteJsonFile is referenced in three files - the module itself, its test, and TaskHistoryStore.ts - and every TaskHistoryStore call site (delete :285, deleteMany :315, removeDelegationRepairIntent :738) passes path.join(tasksDir, taskId, GlobalFileNames.historyItem), a plain name under path.join(basePath, "tasks"), never a link. Reaching the key is fail-closed, matching the write paths: resolveLockKey's catch rethrows a realpath failure that is not "not there yet", and the await sits outside withFileLock, so a filesystem that will not answer the alias question means no lock and no delete. The three TaskHistoryStore call sites swallow anything that is not ENOENT with console.warn (:286-:290, :316-:320, :739-:741), so in practice that becomes a logged best-effort skip rather than a surfaced failure - which is also what makes delete()'s existing JSDoc promise at :270-:275 ("the unlink runs under the same per-file advisory lock as safeWriteJson") literally true. recoverMissingJsonFile (jsonFileRecovery.ts:45-:46) locks the unresolved path for the same reason and is left alone here: it is the adjacent observation, named and untouched, and its rows are about a reader recovering a canonical file rather than about alias contention. Three rows, all gated with it.runIf(process.platform !== "win32"): fs.symlink on a file answers EPERM on the Windows lane (needs privilege or Developer Mode, and the lane has neither), a hard link has no referent for resolveLockKey to follow, and a junction links directories, so no Windows spelling can express what an alias delete does. They are executed by the ubuntu coverage lane, not verified locally - locally they report as 3 skipped. The gate is declared here rather than assumed. Control, and where it is executable: reverting just the key argument reddens the two alias rows on a POSIX host - the first fails where it expects ELOCKED, because <alias>.lock is free while the writer holds <referent>.lock, and the second fails because the link it expects to survive as a dangling reference is what gets unlinked - and leaves the referent-side row green, which is the point of that row: nothing about a delete asked for by the referent's own name changes. That control is likewise only executable on a POSIX host, and this commit does not claim it was run. Reads: utils/__tests__/jsonFileRecovery.test.ts - 10 passed, 3 skipped locally on Windows. The callers' lanes were run because the change is under them: TaskHistoryStore.spec.ts, .deleteSemantics, .realConcurrency, .reconciliation, .crossInstance, importRooTaskHistory, the four ClineProvider history specs, the three Task specs, safeWriteJson.interruption, abandonSubtask and delegation-concurrent - 18 files, 361 passed. tsc --noEmit -p . reports only the known junction artefact at activate/registerCommands.ts(88,102); eslint --prune-suppressions --max-warnings=0 exits 0 with src/eslint-suppressions.json left equal to HEAD.
1 parent bee03bb commit 0a76a7a

2 files changed

Lines changed: 83 additions & 1 deletion

File tree

‎src/utils/__tests__/jsonFileRecovery.test.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import * as path from "path"
55
import { acquireFileLock } from "../fileLock"
66
import { setPersistenceTraceSink } from "../../core/task-persistence/persistenceTrace"
77
import { deleteJsonFile, recoverMissingJsonFile } from "../jsonFileRecovery"
8+
import { resolveLockKey } from "../../services/file-safety/safeWriteText"
89
import { readFileWithMissingRetry } from "../../core/task-persistence/readFileWithMissingRetry"
910

1011
vi.mock("fs/promises", async () => {
@@ -101,6 +102,72 @@ describe("reader recovery", () => {
101102
await expect(fs.access(backup)).resolves.toBeUndefined()
102103
})
103104

105+
// The three rows below need a file symlink. `fs.symlink` on a file answers EPERM on the Windows
106+
// lane, which has neither privilege nor Developer Mode, and no other Windows spelling carries the
107+
// meaning: a hard link has no referent for resolveLockKey to follow, and a junction links
108+
// directories. So these run on the non-Windows lanes - executed there by the ubuntu coverage run,
109+
// not verified locally - and the claim they pin is a POSIX claim about what an alias delete does.
110+
const itPosix = it.runIf(process.platform !== "win32")
111+
112+
itPosix("contends with the writer holding the referent lock when asked for through an alias", async () => {
113+
const alias = path.join(dir, "history_item_alias.json")
114+
await fs.writeFile(target, JSON.stringify({ committed: true }))
115+
await fs.symlink(target, alias)
116+
// The row is only about the key. If the two spellings did not resolve to the same lock, the
117+
// delete below would be contending for a name no writer ever takes, and the refusal would
118+
// prove nothing about the alignment.
119+
expect(await resolveLockKey(alias)).toBe(await resolveLockKey(target))
120+
const release = await acquireFileLock(target)
121+
try {
122+
await expect(deleteJsonFile(alias)).rejects.toMatchObject({ code: "ELOCKED" })
123+
// Refused, so it touched nothing: not the referent, and not the backup beside it.
124+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
125+
expect(JSON.parse(await fs.readFile(backup, "utf8"))).toEqual({ committed: true })
126+
expect((await fs.lstat(alias)).isSymbolicLink()).toBe(true)
127+
} finally {
128+
await release()
129+
}
130+
// Once the writer is gone the same call goes through, and it removes the referent.
131+
await deleteJsonFile(alias)
132+
await expect(fs.stat(target)).rejects.toMatchObject({ code: "ENOENT" })
133+
})
134+
135+
itPosix("removes the referent an alias names, leaving the link standing and unreadable", async () => {
136+
const alias = path.join(dir, "history_item_alias.json")
137+
await fs.writeFile(target, JSON.stringify({ committed: true }))
138+
await fs.symlink(target, alias)
139+
await deleteJsonFile(alias)
140+
// This is what the alignment costs, and it is a change from unlinking the name the caller
141+
// passed: the spelling the caller asked about is still there, and reading through it now
142+
// answers ENOENT because what it pointed at is gone. The leftover prefixes come from the
143+
// referent's basename too, so the backup is removed under either spelling.
144+
expect((await fs.lstat(alias)).isSymbolicLink()).toBe(true)
145+
await expect(fs.stat(alias)).rejects.toMatchObject({ code: "ENOENT" })
146+
await expect(fs.readFile(alias, "utf8")).rejects.toMatchObject({ code: "ENOENT" })
147+
await expect(fs.access(backup)).rejects.toMatchObject({ code: "ENOENT" })
148+
})
149+
150+
itPosix("asks the referent-side delete for the same lock it asked for before", async () => {
151+
const alias = path.join(dir, "history_item_alias.json")
152+
await fs.writeFile(target, JSON.stringify({ committed: true }))
153+
await fs.symlink(target, alias)
154+
// Asked for by the referent's own name nothing here is new: that delete already contended
155+
// with the referent lock, because its key was always the referent. The alignment is only
156+
// visible from the alias side, which is why the row asserts both halves - the contention that
157+
// was already there, and the outcome that is unchanged by the change.
158+
const release = await acquireFileLock(target)
159+
try {
160+
await expect(deleteJsonFile(target)).rejects.toMatchObject({ code: "ELOCKED" })
161+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
162+
} finally {
163+
await release()
164+
}
165+
await deleteJsonFile(target)
166+
await expect(fs.stat(target)).rejects.toMatchObject({ code: "ENOENT" })
167+
expect((await fs.lstat(alias)).isSymbolicLink()).toBe(true)
168+
await expect(fs.readFile(alias, "utf8")).rejects.toMatchObject({ code: "ENOENT" })
169+
})
170+
104171
it("does not create a missing task directory", async () => {
105172
await fs.rm(dir, { recursive: true })
106173
await expect(recoverMissingJsonFile(target)).resolves.toBe(false)

‎src/utils/jsonFileRecovery.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { getErrorCode } from "./errorCode"
55
import { tracePersistenceEvent } from "../core/task-persistence/persistenceTrace"
66

77
import { withFileLock } from "./fileLock"
8+
import { resolveLockKey } from "../services/file-safety/safeWriteText"
89

910
function getTempFilePrefix(absoluteFilePath: string, kind: "new" | "bak"): string {
1011
return `.${path.basename(absoluteFilePath)}.${kind}_`
@@ -75,9 +76,23 @@ export async function recoverMissingJsonFile(
7576
* Delete recoverable leftovers before the canonical file under the writer's
7677
* lock. Failure preserves the canonical copy, rather than authorizing recovery
7778
* of a stale backup after a successful deletion. Missing files are harmless.
79+
*
80+
* The lock is taken on the key `safeWriteJson` publishes under - `resolveLockKey`,
81+
* which follows an existing symlink to the file it refers to - so a delete asked for
82+
* through an alias contends with the writer that holds the referent's lock, and what
83+
* the unlink removes is the referent: the link the caller named survives as a dangling
84+
* symlink, and a caller that wants its own spelling removed has to remove it itself.
85+
* Computing that key is fail-closed. If the filesystem will not answer what the path
86+
* refers to, the delete does not happen at all and the caller receives that error
87+
* rather than an unlocked deletion under a key that names something else.
7888
*/
7989
export async function deleteJsonFile(filePath: string): Promise<void> {
80-
await withFileLock(filePath, async (absoluteFilePath) => {
90+
// Resolved before the lock is taken, the way guardedWrite.ts:192 and DiffViewProvider.ts:722
91+
// resolve for a write. The key below is the one the writer holds, so the contention is real,
92+
// and everything the loop unlinks is named from it: for an alias that is the referent, its
93+
// leftovers, and the backup prefix built from the referent's basename rather than the
94+
// spelling the caller passed in.
95+
await withFileLock(await resolveLockKey(path.resolve(filePath)), async (absoluteFilePath) => {
8196
let entries: string[]
8297
try {
8398
entries = await fs.readdir(path.dirname(absoluteFilePath))

0 commit comments

Comments
 (0)