From 945b24d20ddcdf9493ff42eedce46746060555c1 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:16:24 +0800 Subject: [PATCH 01/22] fix(utils): key the advisory file lock by identity, not by path spelling acquireFileLock keyed proper-lockfile on path.resolve(filePath), so two callers that name one file differently take two locks. On NTFS the spelling-preserving canonicalizers cannot fix that: fs.realpath and fs.realpathSync return whatever spelling they are handed and only fs.realpathSync.native expands an 8.3 alias, while stat answers both spellings with the same dev+ino. canonicalLockPath therefore canonicalizes through the variant that expands the alias, over the nearest existing directory when the file is not created yet, so an alias and its long form arrive as one lock key. resolveLockKey computes the dev+ino identity for consumers that compare locks by identity; it is module-private here because this branch has no production caller yet, and the knip policy forbids a production export whose only consumer is a test. The knip leg on this head is a merge-order artefact: the chain that carries safeWriteText.ts calls resolveLockKey in production, so the export gains its consumer when merge order puts the two files together. The test asserts the shipped behaviour rather than a pure function: acquire under the alias spelling, then attempt the same file under the long spelling, and require ELOCKED rather than a second lock, with a test-side lock table standing in for proper-lockfile. The 8.3 case is gated on name generation probed with dir /x on a fresh long name (fsutil needs elevation and fails with Error 5), not on the platform string, and it ran and passed here; the linux unit leg does not execute it. Reported on #2356. No suppression count changed. --- src/utils/__tests__/fileLock.test.ts | 107 ++++++++++++++++++++++++++- src/utils/fileLock.ts | 56 +++++++++++++- 2 files changed, 160 insertions(+), 3 deletions(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 92637fe7a0..2c4c096a3c 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -1,5 +1,11 @@ +import { spawnSync } from "child_process" +import * as fs from "fs" +import * as os from "os" +import * as path from "path" + import * as lockfile from "proper-lockfile" -import { acquireFileLock, LOCK_STALE_MS, withFileLock } from "../fileLock" + +import { acquireFileLock, canonicalLockPath, LOCK_STALE_MS, withFileLock } from "../fileLock" vi.mock("proper-lockfile", () => ({ lock: vi.fn() })) @@ -32,3 +38,102 @@ describe("file lock protocol", () => { expect(release).toHaveBeenCalledOnce() }) }) + +/** + * 8.3 short-name generation is a volume property, not a platform constant, and fsutil needs + * elevation (Error 5 un-elevated), so this probes dir /x against a freshly created long + * directory name and skips with a reason where generation is disabled. Asserting alias + * unification on a volume with generation off would produce a green that cannot fail, which is + * worse than a skip that says what it did. Locally the probe found a short name (A-REAL~1 for a + * 47-character name) and the alias case below executed and passed; the linux leg does not + * execute it. The name is deliberately not passed as a dir argument: dir /x lists that + * directory's contents, whose header line is the only line containing the name, which reads as + * generation being off when it is not. + */ +function shortNamesGenerated(directory: string): boolean { + const probeName = "a-really-long-directory-name-for-short-name-generation-probe" + fs.mkdirSync(path.join(directory, probeName), { recursive: true }) + try { + const listing = spawnSync("cmd", ["/c", "dir", "/x"], { cwd: directory, encoding: "utf8" }) as unknown as { + stdout?: string + } + const line = + String(listing.stdout ?? "") + .split(/\r?\n/) + .find((entry) => entry.includes(probeName)) ?? "" + const fields = line.split(/\s+/).filter((field) => field.length > 0) + return fields.some((field) => /~\d/.test(field)) + } finally { + fs.rmSync(path.join(directory, probeName), { recursive: true, force: true }) + } +} + +describe("one lock per file, not one lock per spelling", () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "fileLock-key-")) + const generatesShortNames = process.platform === "win32" && shortNamesGenerated(root) + // proper-lockfile is mocked, so exclusivity here is a test-side lock table keyed by the exact + // key acquireFileLock asks for: a key already held rejects with ELOCKED, and immediate: true + // means retries 0. The property under test is whether two spellings of one file arrive as + // one key or as two, which is exactly what that table can decide. + const held: string[] = [] + beforeEach(() => { + held.length = 0 + vi.mocked(lockfile.lock).mockImplementation(async (target: unknown) => { + const key = String(target) + if (held.indexOf(key) >= 0) { + throw Object.assign(new Error("ELOCKED: " + key), { code: "ELOCKED" }) + } + held.push(key) + return async () => { + const at = held.indexOf(key) + if (at >= 0) { + held.splice(at, 1) + } + } + }) + }) + const aliasOf = (longPath: string): string => { + const directory = path.dirname(longPath) + const listing = spawnSync("cmd", ["/c", "dir", "/x"], { cwd: directory, encoding: "utf8" }) as unknown as { + stdout?: string + } + const line = + String(listing.stdout ?? "") + .split(/\r?\n/) + .find((entry) => entry.includes(path.basename(longPath))) ?? "" + const fields = line.split(/\s+/).filter((field) => field.length > 0) + const short = fields.find((field) => /~\d/.test(field)) + return short ? path.join(directory, short) : longPath + } + const itAlias = generatesShortNames ? it : it.skip + itAlias("takes one lock for an 8.3 alias and its long form, not a second one", async () => { + const longDir = path.join(root, "a-really-long-directory-name-for-alias-lock-testing") + fs.mkdirSync(longDir, { recursive: true }) + const file = path.join(longDir, "history.json") + fs.writeFileSync(file, "{}", "utf8") + const aliasFile = path.join(aliasOf(longDir), "history.json") + expect(fs.statSync(aliasFile).ino).toBe(fs.statSync(file).ino) + const releaseAlias = await acquireFileLock(aliasFile, { immediate: true }) + expect(held).toHaveLength(1) + await expect(acquireFileLock(file, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + expect(held[0]).toBe(canonicalLockPath(file)) + await releaseAlias() + }) + it("takes separate locks for two different files in one directory", async () => { + const a = path.join(root, "a.json") + const b = path.join(root, "b.json") + fs.writeFileSync(a, "{}", "utf8") + fs.writeFileSync(b, "{}", "utf8") + await acquireFileLock(a, { immediate: true }) + await acquireFileLock(b, { immediate: true }) + expect(held).toHaveLength(2) + }) + it("takes one lock for one not-yet-existing path and a different one for another name", async () => { + const missingA = path.join(root, "missing-a.json") + const missingB = path.join(root, "missing-b.json") + await acquireFileLock(missingA, { immediate: true }) + await expect(acquireFileLock(missingA, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + await acquireFileLock(missingB, { immediate: true }) + expect(held).toHaveLength(2) + }) +}) diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index 49807ea154..bac5698c56 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -1,3 +1,4 @@ +import * as fs from "fs" import * as path from "path" import { tracePersistenceEvent } from "../core/task-persistence/persistenceTrace" import * as lockfile from "proper-lockfile" @@ -26,8 +27,59 @@ export interface FileLockOptions { * returned function exactly once and must not acquire the same lock again * while holding it. */ +function statIdentity(target: string): string | null { + try { + const stats = fs.statSync(target) + return String(stats.dev) + ":" + String(stats.ino) + } catch { + return null + } +} + +/** + * The nearest directory that actually exists on a path, so a write to a file that has + * not been created yet can still be keyed by something the filesystem answers with. + */ +function nearestExistingDirectory(absolutePath: string): { directory: string; relative: string[] } { + const relative: string[] = [] + let current = absolutePath + while (path.dirname(current) !== current) { + relative.unshift(path.basename(current)) + current = path.dirname(current) + if (statIdentity(current) !== null) { + return { directory: current, relative } + } + } + return { directory: current, relative } +} + +/** + * The spelling a lock artefact should be created under: the canonical spelling of the + * nearest existing directory, re-joined with the components that do not exist yet. This is + * what makes an 8.3 alias and its long form take one lock, and it stays a spelling - the key + * above is the identity, and callers that compare locks compare that. + */ +export function canonicalLockPath(filePath: string): string { + const absolute = path.resolve(filePath) + if (statIdentity(absolute) !== null) { + try { + return fs.realpathSync.native(absolute) + } catch { + return absolute + } + } + const { directory, relative } = nearestExistingDirectory(absolute) + let canonicalDirectory = directory + try { + canonicalDirectory = fs.realpathSync.native(directory) + } catch { + canonicalDirectory = directory + } + return relative.length === 0 ? canonicalDirectory : path.join(canonicalDirectory, ...relative) +} + export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> { - const absoluteFilePath = path.resolve(filePath) + const absoluteFilePath = canonicalLockPath(filePath) if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath }) try { return await lockfile.lock(absoluteFilePath, { @@ -72,7 +124,7 @@ export async function withFileLock( operation: (absoluteFilePath: string) => Promise, options?: FileLockOptions, ): Promise { - const absoluteFilePath = path.resolve(filePath) + const absoluteFilePath = canonicalLockPath(filePath) const releaseLock = await acquireFileLock(absoluteFilePath, options) let result: T From 151406a5e2362a610d232fbf8eb60e792d071b62 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:39:16 +0800 Subject: [PATCH 02/22] fix(fileLock): key locks on file identity and hand callers their own spelling The lock resource is the file's identity: the device and inode of the nearest directory that exists, plus the components below it that do not exist yet. Two spellings of one file - an 8.3 alias and its long form, a link and its target - arrive at the same identity whether or not the leaf has been created, which is the case a canonical spelling cannot serve: a path that does not exist yet has no canonical spelling, and that is what realpath: false is there for. No path is canonicalised any more. realpathSync.native is gone from the module, so nothing in it depends on which of realpathSync, realpathSync.native and realpath expands an 8.3 spelling. The artefact stays .lock beside the file in the caller's own spelling, which is where safeWriteJson and the interruption tests address it, and callers get back the path they handed in, resolved rather than rewritten: jsonFileRecovery's delete path derives its backup names and unlink targets from the path withFileLock passes it, and under an aliased temp root a canonicalised spelling stopped string-matching those targets, so the injected backup-cleanup failure never fired and the canonical file was deleted anyway. Measured on node 22.23.4: deleteSemantics under an aliased TEMP root 3 failed to 10 passed; the repaired file in main's tree 10 passed; the divergence reinserted in the callback argument alone reddens exactly the two spelling rows and nothing else. --- src/utils/__tests__/fileLock.test.ts | 66 +++++++++++++++++++++++++++- src/utils/fileLock.ts | 51 ++++++++++++--------- 2 files changed, 94 insertions(+), 23 deletions(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 2c4c096a3c..d2ec7dfbdc 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -5,7 +5,7 @@ import * as path from "path" import * as lockfile from "proper-lockfile" -import { acquireFileLock, canonicalLockPath, LOCK_STALE_MS, withFileLock } from "../fileLock" +import { acquireFileLock, canonicalLockKey, LOCK_STALE_MS, withFileLock } from "../fileLock" vi.mock("proper-lockfile", () => ({ lock: vi.fn() })) @@ -21,6 +21,7 @@ describe("file lock protocol", () => { stale: LOCK_STALE_MS, update: 10000, realpath: false, + lockfilePath: path.resolve("history.json") + ".lock", retries: { retries: 35, factor: 1, minTimeout: 1000, maxTimeout: 1000 }, }), ) @@ -79,6 +80,9 @@ describe("one lock per file, not one lock per spelling", () => { beforeEach(() => { held.length = 0 vi.mocked(lockfile.lock).mockImplementation(async (target: unknown) => { + // The table keys on the key acquireFileLock hands the library: the file's identity, not + // either spelling. Two spellings of one file therefore arrive as one key, which is what + // this table can decide; the artefact location is asserted separately. const key = String(target) if (held.indexOf(key) >= 0) { throw Object.assign(new Error("ELOCKED: " + key), { code: "ELOCKED" }) @@ -116,9 +120,29 @@ describe("one lock per file, not one lock per spelling", () => { const releaseAlias = await acquireFileLock(aliasFile, { immediate: true }) expect(held).toHaveLength(1) await expect(acquireFileLock(file, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) - expect(held[0]).toBe(canonicalLockPath(file)) + expect(canonicalLockKey(aliasFile)).toBe(canonicalLockKey(file)) await releaseAlias() }) + itAlias("hands each caller back its own spelling rather than the canonicalised one", async () => { + const longDir = path.join(root, "a-really-long-directory-name-for-spelling-control") + fs.mkdirSync(longDir, { recursive: true }) + const file = path.join(longDir, "history.json") + fs.writeFileSync(file, "{}", "utf8") + const aliasFile = path.join(aliasOf(longDir), "history.json") + expect(fs.statSync(aliasFile).ino).toBe(fs.statSync(file).ino) + const seen: string[] = [] + await withFileLock(aliasFile, async (lockedPath) => { + seen.push(lockedPath) + }) + await withFileLock(file, async (lockedPath) => { + seen.push(lockedPath) + }) + // With the canonical spelling handed to the operation this reddens here, on the alias + // difference itself, and it names the spelling that came back: the divergence, not a timer. + expect(seen[0]).toBe(path.resolve(aliasFile)) + expect(seen[1]).toBe(path.resolve(file)) + expect(seen[0]).not.toBe(seen[1]) + }) it("takes separate locks for two different files in one directory", async () => { const a = path.join(root, "a.json") const b = path.join(root, "b.json") @@ -137,3 +161,41 @@ describe("one lock per file, not one lock per spelling", () => { expect(held).toHaveLength(2) }) }) + +/** + * A link is the portable member of the same class as an 8.3 alias: two spellings of one + * directory, one referent. Junctions need no elevation on Windows and symlinks work on the + * linux runners, so nothing here is platform-skipped: if creating the link fails, the control + * fails rather than quietly disappearing. + */ +describe("two spellings of one referent share one key", () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "fileLock-link-")) + const real = path.join(root, "real") + const link = path.join(root, "link") + fs.mkdirSync(real, { recursive: true }) + fs.symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir") + + it("keys both spellings of a written file to one identity", () => { + const file = path.join(real, "history.json") + fs.writeFileSync(file, "{}", "utf8") + expect(canonicalLockKey(file)).toBe(canonicalLockKey(path.join(link, "history.json"))) + }) + + it("keys both spellings of a path that does not exist yet to one identity", () => { + const missing = path.join("deep", "history.json") + expect(canonicalLockKey(path.join(real, missing))).toBe(canonicalLockKey(path.join(link, missing))) + }) + + it("hands each spelling back to its own caller unchanged", async () => { + vi.mocked(lockfile.lock).mockResolvedValue(async () => {}) + const seen: string[] = [] + await withFileLock(path.join(link, "history.json"), async (lockedPath) => { + seen.push(lockedPath) + }) + await withFileLock(path.join(real, "history.json"), async (lockedPath) => { + seen.push(lockedPath) + }) + expect(seen[0]).toBe(path.resolve(path.join(link, "history.json"))) + expect(seen[1]).toBe(path.resolve(path.join(real, "history.json"))) + }) +}) diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index bac5698c56..912f739fa3 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -54,35 +54,44 @@ function nearestExistingDirectory(absolutePath: string): { directory: string; re } /** - * The spelling a lock artefact should be created under: the canonical spelling of the - * nearest existing directory, re-joined with the components that do not exist yet. This is - * what makes an 8.3 alias and its long form take one lock, and it stays a spelling - the key - * above is the identity, and callers that compare locks compare that. + * The identity a lock is keyed on: the device and inode of the nearest directory that actually + * exists, plus the components below it that do not exist yet. An 8.3 alias and its long form, a + * link and its target, and a case variant on a case-insensitive volume all arrive at the same + * identity, whether or not the leaf has been created. That is the case a canonical spelling + * cannot serve: a leaf that does not exist yet has no canonical spelling, which is what the + * `realpath: false` in `acquireFileLock` is there for. And nothing here rewrites a caller's + * path - the key is for comparing locks, never for opening files - so the strings callers hand + * to unlink and readFile stay the strings those callers built. */ -export function canonicalLockPath(filePath: string): string { +export function canonicalLockKey(filePath: string): string { const absolute = path.resolve(filePath) - if (statIdentity(absolute) !== null) { - try { - return fs.realpathSync.native(absolute) - } catch { - return absolute - } - } const { directory, relative } = nearestExistingDirectory(absolute) - let canonicalDirectory = directory - try { - canonicalDirectory = fs.realpathSync.native(directory) - } catch { - canonicalDirectory = directory + const identity = statIdentity(directory) + if (identity === null) { + // Not even a root of the path exists yet, so there is no identity to key on and the + // resolved path is the one thing every caller of it computes alike. + return absolute } - return relative.length === 0 ? canonicalDirectory : path.join(canonicalDirectory, ...relative) + return identity + ":" + relative.join("/") +} + +/** + * Where the artefact lives: beside the file in the caller's own spelling. The key above is the + * identity, and the artefact stays a path, because `safeWriteJson` and the interruption tests + * address `.lock` directly - moving it is what made a green suite red, so the location is + * pinned by a test rather than left to taste. + */ +function lockArtefactPath(absolutePath: string): string { + return absolutePath + ".lock" } export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> { - const absoluteFilePath = canonicalLockPath(filePath) + const absoluteFilePath = path.resolve(filePath) + const lockfilePath = lockArtefactPath(absoluteFilePath) if (options?.waitForStaleLock) tracePersistenceEvent("json-lock-wait", { filePath: absoluteFilePath }) try { - return await lockfile.lock(absoluteFilePath, { + return await lockfile.lock(canonicalLockKey(absoluteFilePath), { + lockfilePath, stale: LOCK_STALE_MS, update: 10000, // Update mtime every 10 seconds to prevent staleness if operation is long realpath: false, // the file may not exist yet, which is acceptable @@ -124,7 +133,7 @@ export async function withFileLock( operation: (absoluteFilePath: string) => Promise, options?: FileLockOptions, ): Promise { - const absoluteFilePath = canonicalLockPath(filePath) + const absoluteFilePath = path.resolve(filePath) const releaseLock = await acquireFileLock(absoluteFilePath, options) let result: T From 812ba359b624ccc86264b35b27369de7e40c2e00 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:25:00 +0800 Subject: [PATCH 03/22] test(utils): decide cross-spelling exclusion with the real library The mocked suite keys its lock table on the string acquireFileLock hands the library and never looks at lockfilePath, so a change that gave two spellings different on-disk artefacts would have left it green. Delegate the mock to the real proper-lockfile for one suite and assert, for a junction and for an 8.3 alias, that the two spellings resolve to one artefact inode and that the second acquire rejects ELOCKED while the first holds it. Placing the artefact by the caller's spelling reddens exactly those two rows and leaves the key-equality rows green, which is the coverage the review asked for. Create each suite's temporary root in beforeAll and remove it in afterAll: the roots were made during collection and survived every run of the file, including runs where the alias rows were skipped. --- src/utils/__tests__/fileLock.test.ts | 166 ++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 30 deletions(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index d2ec7dfbdc..58e1dbad2c 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -46,8 +46,8 @@ describe("file lock protocol", () => { * directory name and skips with a reason where generation is disabled. Asserting alias * unification on a volume with generation off would produce a green that cannot fail, which is * worse than a skip that says what it did. Locally the probe found a short name (A-REAL~1 for a - * 47-character name) and the alias case below executed and passed; the linux leg does not - * execute it. The name is deliberately not passed as a dir argument: dir /x lists that + * 47-character name) and the alias cases below executed and passed; the linux leg does not + * execute them. The name is deliberately not passed as a dir argument: dir /x lists that * directory's contents, whose header line is the only line containing the name, which reads as * generation being off when it is not. */ @@ -69,20 +69,63 @@ function shortNamesGenerated(directory: string): boolean { } } +/** + * The 8.3 alias of a path, read from the dir /x listing of its directory. Used by both the + * key-equality suite and the real-lock suite below, so it lives at module scope: a volume with + * generation off returns the long path unchanged, which is why every caller gates on + * shortNamesGenerated first. + */ +function aliasOf(longPath: string): string { + const directory = path.dirname(longPath) + const listing = spawnSync("cmd", ["/c", "dir", "/x"], { cwd: directory, encoding: "utf8" }) as unknown as { + stdout?: string + } + const line = + String(listing.stdout ?? "") + .split(/\r?\n/) + .find((entry) => entry.includes(path.basename(longPath))) ?? "" + const fields = line.split(/\s+/).filter((field) => field.length > 0) + const short = fields.find((field) => /~\d/.test(field)) + return short ? path.join(directory, short) : longPath +} + +/** + * A temporary root for one suite, created when that suite runs and removed when it ends, + * including when a test inside it fails. Creating the root in the describe body left one root + * and its fixtures on disk for every collection of this file, including runs where the suite's + * tests were skipped. + */ +function useTemporaryRoot(prefix: string): () => string { + let root = "" + beforeAll(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), prefix)) + }) + afterAll(() => { + if (root) { + fs.rmSync(root, { recursive: true, force: true }) + } + }) + return () => root +} + describe("one lock per file, not one lock per spelling", () => { - const root = fs.mkdtempSync(path.join(os.tmpdir(), "fileLock-key-")) - const generatesShortNames = process.platform === "win32" && shortNamesGenerated(root) + const root = useTemporaryRoot("fileLock-key-") + let generatesShortNames = false // proper-lockfile is mocked, so exclusivity here is a test-side lock table keyed by the exact // key acquireFileLock asks for: a key already held rejects with ELOCKED, and immediate: true // means retries 0. The property under test is whether two spellings of one file arrive as // one key or as two, which is exactly what that table can decide. const held: string[] = [] + beforeAll(() => { + generatesShortNames = process.platform === "win32" && shortNamesGenerated(root()) + }) beforeEach(() => { held.length = 0 vi.mocked(lockfile.lock).mockImplementation(async (target: unknown) => { // The table keys on the key acquireFileLock hands the library: the file's identity, not // either spelling. Two spellings of one file therefore arrive as one key, which is what - // this table can decide; the artefact location is asserted separately. + // this table can decide; whether they also land on one on-disk artefact is asserted + // separately, against the real library. const key = String(target) if (held.indexOf(key) >= 0) { throw Object.assign(new Error("ELOCKED: " + key), { code: "ELOCKED" }) @@ -96,22 +139,17 @@ describe("one lock per file, not one lock per spelling", () => { } }) }) - const aliasOf = (longPath: string): string => { - const directory = path.dirname(longPath) - const listing = spawnSync("cmd", ["/c", "dir", "/x"], { cwd: directory, encoding: "utf8" }) as unknown as { - stdout?: string - } - const line = - String(listing.stdout ?? "") - .split(/\r?\n/) - .find((entry) => entry.includes(path.basename(longPath))) ?? "" - const fields = line.split(/\s+/).filter((field) => field.length > 0) - const short = fields.find((field) => /~\d/.test(field)) - return short ? path.join(directory, short) : longPath - } - const itAlias = generatesShortNames ? it : it.skip + // The volume probe runs in beforeAll, so the gate is decided when the suite runs rather than + // when it is collected, and the alias tests skip with a reason instead of disappearing. + const itAlias = (name: string, fn: () => Promise) => + it(name, async (context) => { + if (!generatesShortNames) { + return context.skip() + } + await fn() + }) itAlias("takes one lock for an 8.3 alias and its long form, not a second one", async () => { - const longDir = path.join(root, "a-really-long-directory-name-for-alias-lock-testing") + const longDir = path.join(root(), "a-really-long-directory-name-for-alias-lock-testing") fs.mkdirSync(longDir, { recursive: true }) const file = path.join(longDir, "history.json") fs.writeFileSync(file, "{}", "utf8") @@ -124,7 +162,7 @@ describe("one lock per file, not one lock per spelling", () => { await releaseAlias() }) itAlias("hands each caller back its own spelling rather than the canonicalised one", async () => { - const longDir = path.join(root, "a-really-long-directory-name-for-spelling-control") + const longDir = path.join(root(), "a-really-long-directory-name-for-spelling-control") fs.mkdirSync(longDir, { recursive: true }) const file = path.join(longDir, "history.json") fs.writeFileSync(file, "{}", "utf8") @@ -144,8 +182,8 @@ describe("one lock per file, not one lock per spelling", () => { expect(seen[0]).not.toBe(seen[1]) }) it("takes separate locks for two different files in one directory", async () => { - const a = path.join(root, "a.json") - const b = path.join(root, "b.json") + const a = path.join(root(), "a.json") + const b = path.join(root(), "b.json") fs.writeFileSync(a, "{}", "utf8") fs.writeFileSync(b, "{}", "utf8") await acquireFileLock(a, { immediate: true }) @@ -153,8 +191,8 @@ describe("one lock per file, not one lock per spelling", () => { expect(held).toHaveLength(2) }) it("takes one lock for one not-yet-existing path and a different one for another name", async () => { - const missingA = path.join(root, "missing-a.json") - const missingB = path.join(root, "missing-b.json") + const missingA = path.join(root(), "missing-a.json") + const missingB = path.join(root(), "missing-b.json") await acquireFileLock(missingA, { immediate: true }) await expect(acquireFileLock(missingA, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) await acquireFileLock(missingB, { immediate: true }) @@ -169,11 +207,15 @@ describe("one lock per file, not one lock per spelling", () => { * fails rather than quietly disappearing. */ describe("two spellings of one referent share one key", () => { - const root = fs.mkdtempSync(path.join(os.tmpdir(), "fileLock-link-")) - const real = path.join(root, "real") - const link = path.join(root, "link") - fs.mkdirSync(real, { recursive: true }) - fs.symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir") + const root = useTemporaryRoot("fileLock-link-") + let real = "" + let link = "" + beforeAll(() => { + real = path.join(root(), "real") + link = path.join(root(), "link") + fs.mkdirSync(real, { recursive: true }) + fs.symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir") + }) it("keys both spellings of a written file to one identity", () => { const file = path.join(real, "history.json") @@ -199,3 +241,67 @@ describe("two spellings of one referent share one key", () => { expect(seen[1]).toBe(path.resolve(path.join(real, "history.json"))) }) }) + +/** + * The mocked suites above decide key equality and nothing else: the mock keys on the string + * acquireFileLock hands it and never looks at lockfilePath, so a change that gave two spellings + * two different on-disk artefacts would have left them green. These delegate the mock to the + * real library, the way the McpHub settings-creation integration spec does, so the outcome is + * decided by the artefact the filesystem resolves - which is the mutual-exclusion claim the + * alias-keyed fix actually makes. + */ +describe("two spellings contend with the real library", () => { + const root = useTemporaryRoot("fileLock-real-") + let generatesShortNames = false + let actualLock: typeof lockfile.lock + beforeAll(async () => { + actualLock = (await vi.importActual("proper-lockfile")).lock + generatesShortNames = process.platform === "win32" && shortNamesGenerated(root()) + }) + beforeEach(() => { + vi.mocked(lockfile.lock).mockImplementation((target, options) => actualLock(target, options)) + }) + + // Both spellings name one directory once the filesystem resolves them, so the artefacts are + // one directory and the library refuses the second caller. Asserting that the artefacts + // share an inode is what pins this down: a placement keyed on the spelling would land two + // directories here, the second acquire would succeed, and the suite above would stay green. + async function expectOneLockAcrossSpellings(firstPath: string, secondPath: string): Promise { + fs.mkdirSync(path.dirname(firstPath), { recursive: true }) + fs.writeFileSync(firstPath, "{}", "utf8") + const release = await acquireFileLock(firstPath, { immediate: true }) + try { + expect(fs.existsSync(secondPath + ".lock")).toBe(true) + expect(fs.statSync(secondPath + ".lock").ino).toBe(fs.statSync(firstPath + ".lock").ino) + await expect(acquireFileLock(secondPath, { immediate: true })).rejects.toMatchObject({ + code: "ELOCKED", + }) + } finally { + await release() + } + const released = await acquireFileLock(secondPath, { immediate: true }) + await released() + expect(fs.existsSync(firstPath + ".lock")).toBe(false) + } + + it("blocks the other spelling of a junction path while one holds the real lock", async () => { + const real = path.join(root(), "real") + const link = path.join(root(), "link") + fs.mkdirSync(real, { recursive: true }) + fs.symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir") + await expectOneLockAcrossSpellings(path.join(link, "history.json"), path.join(real, "history.json")) + }) + + it("blocks the other spelling of an 8.3 alias while one holds the real lock", async (context) => { + if (!generatesShortNames) { + return context.skip() + } + const longDir = path.join(root(), "a-really-long-directory-name-for-real-lock-alias-testing") + fs.mkdirSync(longDir, { recursive: true }) + const file = path.join(longDir, "history.json") + fs.writeFileSync(file, "{}", "utf8") + const aliasFile = path.join(aliasOf(longDir), "history.json") + expect(fs.statSync(aliasFile).ino).toBe(fs.statSync(file).ino) + await expectOneLockAcrossSpellings(aliasFile, file) + }) +}) From 20343f818a7af671c285e77818c7c7c27ff9bd2d Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:12:59 +0800 Subject: [PATCH 04/22] fix(utils): read the lock identity in bigint so large inodes stay distinct fs.statSync hands back dev and ino as plain numbers unless BigInts are asked for, and above 2^53 an inode stops being a distinct number: 17451448568457636 and 17451448568457637 are adjacent integers and one double. Stringifying that number for the lock key therefore loses information silently and can key two neighbouring directories alike. Read the identity with { bigint: true }, which is lossless, and add a regression row whose statSync double answers plain stats with rounded numbers and BigInts only when asked - a double that always returned BigInts would be green before the fix. Co-Authored-By: Claude --- src/utils/__tests__/fileLock.test.ts | 74 ++++++++++++++++++++++++++++ src/utils/fileLock.ts | 5 +- 2 files changed, 78 insertions(+), 1 deletion(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 58e1dbad2c..6f3d2fb432 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -9,6 +9,27 @@ import { acquireFileLock, canonicalLockKey, LOCK_STALE_MS, withFileLock } from " vi.mock("proper-lockfile", () => ({ lock: vi.fn() })) +type StatSyncOverride = ( + target: string, + options?: { bigint?: boolean }, +) => { dev: number | bigint; ino: number | bigint } + +/** + * A delegating filesystem double, armed only by the inode-precision suite below. Everything else + * in this file keeps using the real filesystem, because the wrapper forwards to the actual module + * whenever no override is installed. + */ +let statSyncOverride: StatSyncOverride | null = null + +vi.mock("fs", async (importOriginal) => { + const actual = await importOriginal() + const statSync = ((target: string, options?: unknown) => + statSyncOverride === null + ? (actual.statSync as (path: string, opts?: unknown) => unknown)(target, options) + : statSyncOverride(target, options as { bigint?: boolean } | undefined)) as typeof actual.statSync + return { ...actual, statSync } +}) + describe("file lock protocol", () => { beforeEach(() => vi.clearAllMocks()) @@ -305,3 +326,56 @@ describe("two spellings contend with the real library", () => { await expectOneLockAcrossSpellings(aliasFile, file) }) }) + +/** + * The identity is a string built from device and inode, and node hands those over as plain numbers + * unless asked otherwise. Above 2^53 an inode is no longer a distinct number - 17451448568457636 + * and 17451448568457637 are adjacent integers and one double - so the identity has to be read with + * `{ bigint: true }` or two neighbouring directories collapse into one key and one lock. + * + * The double is the row: it answers a plain stat with **rounded numbers**, the way node does, and + * hands back BigInts only when the caller asks for them. A double that returned BigInts + * unconditionally would read green before the fix and prove nothing about the numeric path. + */ +describe("identity keeps inodes above 2^53 distinct", () => { + const inodeLow = 17451448568457636n + const inodeHigh = 17451448568457637n + const dev = 7n + // Two existing directories one inode apart, each holding a file of the same name, so the only + // thing that can separate the two keys is the inode the identity is built from. These paths are + // synthetic - the fake statSync answers for them - so nothing is created on disk. + const precisionRoot = path.resolve("zoo-identity-precision") + const directoryLow = path.join(precisionRoot, "a") + const directoryHigh = path.join(precisionRoot, "b") + + let statCalls: Array<{ target: string; bigintRequested: boolean }> = [] + beforeEach(() => { + statCalls = [] + statSyncOverride = (target, options) => { + const bigintRequested = options?.bigint === true + statCalls.push({ target, bigintRequested }) + const ino = target === directoryLow ? inodeLow : target === directoryHigh ? inodeHigh : 1n + // Fidelity: BigInts only when they were asked for, rounded numbers otherwise. + return bigintRequested ? { dev, ino } : { dev: Number(dev), ino: Number(ino) } + } + }) + afterEach(() => { + statSyncOverride = null + }) + + it("pairs the adjacent inodes named by the precision loss", () => { + expect(Number(inodeLow)).toBe(Number(inodeHigh)) + expect(String(inodeLow)).not.toBe(String(inodeHigh)) + }) + + it("keys two directories one inode apart above 2^53 by different identities", () => { + const low = canonicalLockKey(path.join(directoryLow, "history.json")) + const high = canonicalLockKey(path.join(directoryHigh, "history.json")) + expect(low).not.toBe(high) + }) + + it("asks the filesystem for the identity in bigint form", () => { + canonicalLockKey(path.join(directoryLow, "history.json")) + expect(statCalls.some((call) => call.bigintRequested)).toBe(true) + }) +}) diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index 912f739fa3..0ea669e157 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -29,7 +29,10 @@ export interface FileLockOptions { */ function statIdentity(target: string): string | null { try { - const stats = fs.statSync(target) + // BigInt stats, because the identity is a string and a plain number is not lossless: two + // adjacent inodes above 2^53 are the same Number, so the numeric form can key two + // neighbouring directories alike and let them share a lock nobody asked for. + const stats = fs.statSync(target, { bigint: true }) return String(stats.dev) + ":" + String(stats.ino) } catch { return null From 2d75cda5ec99f543789cdc63d9a2cfc05b1ef2d8 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 20:28:00 +0800 Subject: [PATCH 05/22] docs(utils): state that the lock identity converges aliasing above the leaf and not at it --- src/utils/fileLock.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index 0ea669e157..821518f214 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -58,13 +58,18 @@ function nearestExistingDirectory(absolutePath: string): { directory: string; re /** * The identity a lock is keyed on: the device and inode of the nearest directory that actually - * exists, plus the components below it that do not exist yet. An 8.3 alias and its long form, a - * link and its target, and a case variant on a case-insensitive volume all arrive at the same - * identity, whether or not the leaf has been created. That is the case a canonical spelling - * cannot serve: a leaf that does not exist yet has no canonical spelling, which is what the - * `realpath: false` in `acquireFileLock` is there for. And nothing here rewrites a caller's - * path - the key is for comparing locks, never for opening files - so the strings callers hand - * to unlink and readFile stay the strings those callers built. + * exists, plus the components below it that do not exist yet. Aliasing at or above that directory + * converges - an 8.3 alias of it, a link to it, and a case variant of it on a case-insensitive + * volume all arrive at the same identity, because the identity is the directory's and only the + * surviving components are compared. Aliasing OF THE FINAL COMPONENT does not: those components + * are compared as the strings the caller wrote, so an 8.3 alias of the file itself, or a case + * variant of it, arrives as a second key - and lockArtefactPath names the artefact by + * concatenating that same spelling, so it arrives as a second artefact beside it, and two writers + * that believe they hold the same lock do not. A canonical spelling cannot serve the general + * case here: a leaf that does not exist yet has no canonical spelling, which is what the + * `realpath: false` in `acquireFileLock` is there for. And nothing here rewrites a caller's path + * - the key is for comparing locks, never for opening files - so the strings callers hand to + * unlink and readFile stay the strings those callers built. */ export function canonicalLockKey(filePath: string): string { const absolute = path.resolve(filePath) From ff5fbc58709b4beef4182c9139095e3aac62772a Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 20:31:13 +0800 Subject: [PATCH 06/22] fix(utils): name the lock artefact by the spelling the volume holds for the leaf, and contend the two spellings against the real library --- src/utils/__tests__/fileLock.test.ts | 31 ++++++++++++++++++++++++++++ src/utils/fileLock.ts | 14 ++++++++----- src/utils/lockLeafSpelling.ts | 29 ++++++++++++++++++++++++++ 3 files changed, 69 insertions(+), 5 deletions(-) create mode 100644 src/utils/lockLeafSpelling.ts diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 6f3d2fb432..dd3c8980ed 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -325,6 +325,37 @@ describe("two spellings contend with the real library", () => { expect(fs.statSync(aliasFile).ino).toBe(fs.statSync(file).ino) await expectOneLockAcrossSpellings(aliasFile, file) }) + + // The two rows above alias a directory: once the filesystem resolves the two spellings the + // artefacts are one directory no matter what the artefact is named by. These two spellings differ + // in the final component only, so the spelling the artefact name is built from is what decides + // whether the callers contend. A placement that concatenates the caller's own leaf spelling lands + // two artefacts here, lets the second caller through, and leaves every mocked suite above green - + // which is why this one delegates to the real library and asserts the artefact directory too. + it("blocks the other spelling of an 8.3 alias of the leaf while one holds the real lock", async (context) => { + if (!generatesShortNames) { + return context.skip() + } + const directory = path.join(root(), "leaf-alias-lock") + fs.mkdirSync(directory, { recursive: true }) + const longLeaf = path.join(directory, "task-history-leaf-for-alias-lock-testing.json") + fs.writeFileSync(longLeaf, "{}", "utf8") + const aliasLeaf = aliasOf(longLeaf) + expect(aliasLeaf).not.toBe(longLeaf) + expect(fs.statSync(aliasLeaf).ino).toBe(fs.statSync(longLeaf).ino) + const release = await acquireFileLock(aliasLeaf, { immediate: true }) + try { + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([ + "task-history-leaf-for-alias-lock-testing.json.lock", + ]) + await expect(acquireFileLock(longLeaf, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + } finally { + await release() + } + const released = await acquireFileLock(longLeaf, { immediate: true }) + await released() + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) + }) }) /** diff --git a/src/utils/fileLock.ts b/src/utils/fileLock.ts index 821518f214..cdd0ad1b28 100644 --- a/src/utils/fileLock.ts +++ b/src/utils/fileLock.ts @@ -2,6 +2,7 @@ import * as fs from "fs" import * as path from "path" import { tracePersistenceEvent } from "../core/task-persistence/persistenceTrace" import * as lockfile from "proper-lockfile" +import { canonicalLeafSpelling } from "./lockLeafSpelling" /** * Shared staleness window for per-file advisory locks. This module owns the @@ -84,13 +85,16 @@ export function canonicalLockKey(filePath: string): string { } /** - * Where the artefact lives: beside the file in the caller's own spelling. The key above is the - * identity, and the artefact stays a path, because `safeWriteJson` and the interruption tests - * address `.lock` directly - moving it is what made a green suite red, so the location is - * pinned by a test rather than left to taste. + * Where the artefact lives: beside the file, named by the spelling the volume holds for that leaf, + * so two spellings of one file contend with one another instead of each taking its own lock. The + * key above is the identity, and the artefact stays a path, because `safeWriteJson` and the + * interruption tests address `.lock` directly - moving it is what made a green suite red, so + * the location is pinned by a test rather than left to taste. Only the final component is + * re-spelled: a caller that reaches the file through a junction or an 8.3 alias of a DIRECTORY + * still gets the artefact inside that directory, because the re-spelling never moves the file. */ function lockArtefactPath(absolutePath: string): string { - return absolutePath + ".lock" + return canonicalLeafSpelling(absolutePath) + ".lock" } export async function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise> { diff --git a/src/utils/lockLeafSpelling.ts b/src/utils/lockLeafSpelling.ts new file mode 100644 index 0000000000..c132e823c5 --- /dev/null +++ b/src/utils/lockLeafSpelling.ts @@ -0,0 +1,29 @@ +import * as fs from "fs" +import * as path from "path" + +/** + * The spelling an artefact should be named by when one file is spelled more than one way. An 8.3 + * alias, a case variant on a case-insensitive volume, and the long form all name one directory + * entry, and only one of those spellings can be the name of the artefact if two writers are to + * contend at all. The native realpath is the call that answers this: it reports the spelling the + * volume itself holds, which plain `fs.realpathSync` does not - on a Windows volume with 8.3 + * generation on, `fs.realpathSync` hands an alias straight back, so it converges nothing, while + * the native call returns the long form for both the alias and a case variant of it. Only the + * final component is re-spelled, never the directory: `fileLock` deliberately passes + * `realpath: false` to the lock library because the file may not exist yet, and the artefact has + * to stay beside the file the caller named. Where the volume has no spelling to report - the leaf + * is not created yet, or it is a link whose target is gone - the call throws and the caller's own + * spelling is returned unchanged, which is the behaviour today. + */ +export function canonicalLeafSpelling(absolutePath: string): string { + try { + const volumeSpelling = path.basename(fs.realpathSync.native(absolutePath)) + return volumeSpelling === path.basename(absolutePath) + ? absolutePath + : path.join(path.dirname(absolutePath), volumeSpelling) + } catch { + // Nothing to converge: a leaf that does not exist yet has no volume spelling, and a dangling + // link has no target to name. Refusing the write for either would be worse than today. + return absolutePath + } +} From 7feb8a12112bcddeeedf2315a08cca493acdd977 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 20:49:13 +0800 Subject: [PATCH 07/22] test(utils): cover the link-named leaf on the linux arm, where it is the only spelling the volume can hand back --- src/utils/__tests__/fileLock.test.ts | 59 ++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index dd3c8980ed..51bad9eecf 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -356,6 +356,65 @@ describe("two spellings contend with the real library", () => { await released() expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) }) + + // The rows above alias a directory, and on ext4 a case variant is a different file and an 8.3 alias + // does not exist, so the only way the final component is spelled more than one way on the linux arm + // is a leaf that is itself a link. These two rows are the linux arm's version of the two rows above, + // gated the other way round: they run where the 8.3 rows skip and skip where they run. + const itPosixLeaf = (name: string, fn: () => Promise) => + it(name, async (context) => { + if (process.platform === "win32") { + return context.skip() + } + await fn() + }) + + itPosixLeaf( + "blocks the target of a link while the link holds the real lock, on one artefact named by the target", + async () => { + const directory = path.join(root(), "link-leaf-lock") + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, "{}", "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync("history.json", link) + expect(fs.statSync(link).ino).toBe(fs.statSync(target).ino) + const release = await acquireFileLock(link, { immediate: true }) + try { + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([ + "history.json.lock", + ]) + await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + } finally { + await release() + } + const released = await acquireFileLock(target, { immediate: true }) + await released() + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) + }, + ) + + itPosixLeaf("keeps a link's artefact in the caller's directory when its target lives elsewhere", async () => { + const directory = path.join(root(), "far-link-lock") + const elsewhere = path.join(root(), "far-link-target") + fs.mkdirSync(directory, { recursive: true }) + fs.mkdirSync(elsewhere, { recursive: true }) + const target = path.join(elsewhere, "history.json") + fs.writeFileSync(target, "{}", "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync(target, link) + const release = await acquireFileLock(link, { immediate: true }) + try { + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual(["history.json.lock"]) + expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) + const besideTarget = await acquireFileLock(target, { immediate: true }) + await besideTarget() + } finally { + await release() + } + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) + expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) + }) }) /** From 685ddda9a13310f79590c990cae08033d84b300a Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Mon, 9 Nov 2026 21:34:52 +0800 Subject: [PATCH 08/22] test(utils): pin the leaf substitution on a stubbed volume spelling, so it is proved where no volume would hand back two spellings --- src/utils/__tests__/fileLock.test.ts | 39 ++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 51bad9eecf..33ba1cb0b9 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -182,6 +182,45 @@ describe("one lock per file, not one lock per spelling", () => { expect(canonicalLockKey(aliasFile)).toBe(canonicalLockKey(file)) await releaseAlias() }) + + // The portable half of the leaf-spelling coverage. The 8.3 row above needs a volume that hands + // back two spellings of one entry and the real-library link rows below need a filesystem that + // lets a leaf be a link; this one needs neither. It substitutes the spelling the volume reports + // and asserts the artefact acquireFileLock asks the library to create, so dropping the + // substitution fails here on every platform, not only where a second spelling exists by luck. + it("names the artefact by the spelling the volume reports for the leaf, not by the caller's", async () => { + const directory = path.join(root(), "substituted-leaf-lock") + fs.mkdirSync(directory, { recursive: true }) + const callerPath = path.join(directory, "history-item.json") + const volumePath = path.join(directory, "HISTORY-ITEM.JSON") + fs.writeFileSync(callerPath, "{}", "utf8") + // fs's namespace types these properties read-only, and the module double forwards to the real + // realpathSync object, so the substitution is installed by reading the callable through a + // mutable view of it and restoring the original function in the finally below. + const realpathModule: { native: (target: string) => string } = fs.realpathSync + const actualNative = realpathModule.native + try { + realpathModule.native = (target: string) => + target === path.resolve(callerPath) ? volumePath : actualNative(target) + const release = await acquireFileLock(callerPath, { immediate: true }) + try { + const call = vi.mocked(lockfile.lock).mock.calls.at(-1) + expect(call?.[1]?.lockfilePath).toBe(path.join(directory, "HISTORY-ITEM.JSON.lock")) + expect(String(call?.[0])).toBe(canonicalLockKey(path.resolve(callerPath))) + expect(fs.existsSync(path.join(directory, "HISTORY-ITEM.JSON.lock"))).toBe(false) + expect(fs.existsSync(path.join(directory, "history-item.json.lock"))).toBe(false) + } finally { + await release() + } + } finally { + realpathModule.native = actualNative + } + const after = await acquireFileLock(callerPath, { immediate: true }) + await after() + expect(vi.mocked(lockfile.lock).mock.calls.at(-1)?.[1]?.lockfilePath).toBe( + path.join(directory, "history-item.json.lock"), + ) + }) itAlias("hands each caller back its own spelling rather than the canonicalised one", async () => { const longDir = path.join(root(), "a-really-long-directory-name-for-spelling-control") fs.mkdirSync(longDir, { recursive: true }) From d76bbfd4f9f7a81cf517a9727c7cbc3bf5926677 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Tue, 10 Nov 2026 00:48:02 +0800 Subject: [PATCH 09/22] utils: pin the shared artefact, the queued writer, and the release order Three rows in src/utils/__tests__/fileLock.test.ts, run against the real library: - contends an unrelated sibling named like the link target against the link's lock - keeps a waiting writer at the caller-named artefact across a leaf-link replacement, and merges into the referent that answers when it proceeds - refuses a second key on a held artefact, and a late release from the writer that let go plus two identity rows: keys whose digits concatenate alike, and the no-ancestor fallback. Verified on Linux node v22.23.4: pristine 19 passed | 4 skipped (23); with the leaf-spelling call removed 5 failed; with the artefact composed from the resolved target 7 failed; restored green. Test-only commit: no executable line changes, so the priced 33 counted lines at 5319fe91fb is unchanged and no local Stryker preflight was run - this box cannot spawn .bin/stryker. --- src/utils/__tests__/fileLock.test.ts | 178 +++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 33ba1cb0b9..bd54acfe41 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -454,6 +454,143 @@ describe("two spellings contend with the real library", () => { expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) }) + + // The row above proves the artefact lands in the caller's directory. It does not prove what + // happens when the caller's own directory already holds a file with the target's name, and that + // collision is not hypothetical - it is what the lock does. The sibling is a different inode with + // its own content and its own canonical key, and it still contends on the one artefact name the + // volume spelling hands both of them. + itPosixLeaf("contends an unrelated sibling named like the link target against the link's lock", async () => { + const directory = path.join(root(), "sibling-collision") + const elsewhere = path.join(root(), "sibling-target") + fs.mkdirSync(directory, { recursive: true }) + fs.mkdirSync(elsewhere, { recursive: true }) + const target = path.join(elsewhere, "history.json") + fs.writeFileSync(target, JSON.stringify({ writer: "target" }), "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync(target, link) + const sibling = path.join(directory, "history.json") + fs.writeFileSync(sibling, JSON.stringify({ writer: "sibling" }), "utf8") + expect(fs.realpathSync.native(link)).toBe(fs.realpathSync.native(target)) + expect(fs.statSync(sibling).ino).not.toBe(fs.statSync(link).ino) + expect(canonicalLockKey(link)).not.toBe(canonicalLockKey(sibling)) + const release = await acquireFileLock(link, { immediate: true }) + try { + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual(["history.json.lock"]) + await expect(acquireFileLock(sibling, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + } finally { + await release() + } + const afterRelease = await acquireFileLock(sibling, { immediate: true }) + await afterRelease() + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) + expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) + }) + + // A leaf link replaced while a second writer queues is the case the persistence-integrity check + // asked for. The contract it has to assert is the one the filesystem offers: convergence happens + // inside one directory, so the artefact directory does not follow the target. Both artefacts are + // named here, the queue is observed at the caller-named one, and the merged content is read back + // from both coexisting targets - constructed as two live files with two live caller paths, and the + // replacement is an atomic rename of a freshly created link over the old one, so no recycled inode + // is load-bearing. + itPosixLeaf( + "keeps a waiting writer at the caller-named artefact across a leaf-link replacement, and merges into the referent that answers when it proceeds", + async () => { + const readMerged = (target: string): { merge: string; writer?: string } => + JSON.parse(fs.readFileSync(target, "utf8")) as { merge: string; writer?: string } + const callerDir = path.join(root(), "retarget-caller") + const targetDir = path.join(root(), "retarget-target") + fs.mkdirSync(callerDir, { recursive: true }) + fs.mkdirSync(targetDir, { recursive: true }) + const firstTarget = path.join(targetDir, "history.json") + fs.writeFileSync(firstTarget, JSON.stringify({ merge: "first" }), "utf8") + const secondTarget = path.join(callerDir, "history-content.json") + fs.writeFileSync(secondTarget, JSON.stringify({ merge: "second" }), "utf8") + const callerPath = path.join(callerDir, "history.json") + fs.symlinkSync(firstTarget, callerPath) + const callerArtefact = path.join(callerDir, "history.json.lock") + const targetArtefact = path.join(targetDir, "history.json.lock") + let releaseFirst: (() => Promise) | null = null + let releaseSecond: (() => Promise) | null = null + let waitingSeen = "not started" + try { + releaseFirst = await acquireFileLock(callerPath, { immediate: true }) + const firstBase = readMerged(callerPath) + fs.writeFileSync(callerPath, JSON.stringify({ ...firstBase, writer: "first" }), "utf8") + expect(fs.existsSync(callerArtefact)).toBe(true) + const throughTarget = await acquireFileLock(firstTarget, { immediate: true }) + expect(fs.existsSync(targetArtefact)).toBe(true) + await throughTarget() + const waitingWriter = acquireFileLock(callerPath) + waitingSeen = await Promise.race([ + waitingWriter.then(() => "settled while the first writer still held"), + new Promise((resolve) => { + setTimeout(() => resolve("still queued"), 300) + }), + ]) + const replacement = path.join(callerDir, "history.json.next") + fs.symlinkSync(secondTarget, replacement) + fs.renameSync(replacement, callerPath) + await releaseFirst() + releaseFirst = null + releaseSecond = await waitingWriter + expect(fs.readdirSync(callerDir).filter((name) => name.endsWith(".lock"))).toEqual([ + "history.json.lock", + ]) + const secondBase = readMerged(callerPath) + fs.writeFileSync(callerPath, JSON.stringify({ ...secondBase, writer: "second" }), "utf8") + } finally { + if (releaseFirst !== null) { + await releaseFirst() + } + if (releaseSecond !== null) { + await releaseSecond() + } + } + expect(waitingSeen).toBe("still queued") + expect(fs.existsSync(callerArtefact)).toBe(false) + expect(fs.existsSync(targetArtefact)).toBe(false) + expect(readMerged(firstTarget)).toEqual({ merge: "first", writer: "first" }) + expect(readMerged(secondTarget)).toEqual({ merge: "second", writer: "second" }) + }, + ) + + // The third pre-merge row asks about overlapping acquisitions and releases, and about one library key + // owning two different artefacts at once. Measured before asserting: an acquisition that arrives at an + // artefact another key already holds rejects ELOCKED - on this volume the artefact carries the lock, so + // a second key cannot fork a second lock onto it - and a release called a second time, after another + // writer has taken the artefact, rejects ERELEASED and leaves that writer's artefact where it is. Each + // writer then releases through the function it was handed, and neither directory is left holding one. + itPosixLeaf("refuses a second key on a held artefact, and a late release from the writer that let go", async () => { + const directory = path.join(root(), "release-order") + const elsewhere = path.join(root(), "release-target") + fs.mkdirSync(directory, { recursive: true }) + fs.mkdirSync(elsewhere, { recursive: true }) + const target = path.join(elsewhere, "history.json") + fs.writeFileSync(target, JSON.stringify({ writer: "target" }), "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync(target, link) + const sibling = path.join(directory, "history.json") + fs.writeFileSync(sibling, JSON.stringify({ writer: "sibling" }), "utf8") + expect(canonicalLockKey(link)).not.toBe(canonicalLockKey(sibling)) + const releaseLink = await acquireFileLock(link, { immediate: true }) + let releaseSibling: (() => Promise) | null = null + try { + await expect(acquireFileLock(sibling, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + const queued = acquireFileLock(sibling) + await releaseLink() + releaseSibling = await queued + await expect(releaseLink()).rejects.toMatchObject({ code: "ERELEASED" }) + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual(["history.json.lock"]) + } finally { + if (releaseSibling !== null) { + await releaseSibling() + } + } + expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) + expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) + }) }) /** @@ -507,4 +644,45 @@ describe("identity keeps inodes above 2^53 distinct", () => { canonicalLockKey(path.join(directoryLow, "history.json")) expect(statCalls.some((call) => call.bigintRequested)).toBe(true) }) + + // The identity and the surviving components are joined with a separator, and a separator is only + // decoration until two widths concatenate alike: device 1 inode 23 and device 12 inode 3 build the + // same digit run, and device 1 inode 2 followed by a file named 3history.json builds the same run as + // device 1 inode 23 followed by history.json. These paths are synthetic - the fake statSync answers + // for them - and the doubles return plain numbers for both spellings because the row is about widths, + // not about the bigint read the row above already pins, so the only thing that can keep the three + // keys apart is the separator the unit composes them with. + it("keeps identities whose digits concatenate alike apart", () => { + const directoryWide = path.join(precisionRoot, "wide") + const directoryWideConcat = path.join(precisionRoot, "wide-concat") + const directoryShift = path.join(precisionRoot, "shift") + statSyncOverride = (target) => { + const fabricated: Record = { + [directoryWide]: { dev: 1, ino: 23 }, + [directoryWideConcat]: { dev: 12, ino: 3 }, + [directoryShift]: { dev: 1, ino: 2 }, + } + return fabricated[path.resolve(target)] ?? { dev: 1, ino: 99 } + } + const wide = canonicalLockKey(path.join(directoryWide, "history.json")) + const sameConcat = canonicalLockKey(path.join(directoryWideConcat, "history.json")) + const shifted = canonicalLockKey(path.join(directoryShift, "3history.json")) + expect(wide).not.toBe(sameConcat) + expect(wide).not.toBe(shifted) + expect(sameConcat).not.toBe(shifted) + }) + + // Every ancestor missing is the fall-through at the end of nearestExistingDirectory, and that is the + // only way to reach the fallback that hands back the caller's own path: with no identity anywhere the + // key has to be the resolved path, because nothing on the filesystem has answered with an identity to + // build one from. Mutating that fall-through's return to an empty object is equivalent here - an + // undefined directory statSyncs to null and lands on the same fallback - so this row covers the line + // without killing that mutant, and says so rather than claiming a kill. + it("falls back to the caller's own path when no ancestor has an identity", () => { + statSyncOverride = () => { + throw Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" }) + } + const uncreated = path.resolve(path.join(precisionRoot, "uncreated", "nested", "history.json")) + expect(canonicalLockKey(uncreated)).toBe(uncreated) + }) }) From c90647c7a1699c3623943b1d145b8ac4653d667a Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Tue, 10 Nov 2026 04:09:36 +0800 Subject: [PATCH 10/22] test(utils): release the fileLock link lock from finally when a row fails before release The release-order row took the link lock outside its try/finally, so an assertion failure between acquisition and release left the renewal timer armed while teardown removed the lock directory, and the next stat in the same process raised ECOMPROMISED inside an unrelated row. Ownership is tracked before the acquisition and the link is released in finally unless the row already released it, which the row itself asserts with ERELEASED. --- src/utils/__tests__/fileLock.test.ts | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index bd54acfe41..869f96c0e9 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -574,12 +574,19 @@ describe("two spellings contend with the real library", () => { const sibling = path.join(directory, "history.json") fs.writeFileSync(sibling, JSON.stringify({ writer: "sibling" }), "utf8") expect(canonicalLockKey(link)).not.toBe(canonicalLockKey(sibling)) - const releaseLink = await acquireFileLock(link, { immediate: true }) + // Ownership is tracked before anything is acquired: if the assertion below fails between + // taking the link lock and releasing it, the release still has to run, because teardown + // removes the lock directory and a renewal timer still armed on it raises ECOMPROMISED + // inside some later row. + let releaseLink: (() => Promise) | null = null + let linkReleased = false let releaseSibling: (() => Promise) | null = null try { + releaseLink = await acquireFileLock(link, { immediate: true }) await expect(acquireFileLock(sibling, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) const queued = acquireFileLock(sibling) await releaseLink() + linkReleased = true releaseSibling = await queued await expect(releaseLink()).rejects.toMatchObject({ code: "ERELEASED" }) expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual(["history.json.lock"]) @@ -587,6 +594,9 @@ describe("two spellings contend with the real library", () => { if (releaseSibling !== null) { await releaseSibling() } + if (releaseLink !== null && !linkReleased) { + await releaseLink() + } } expect(fs.readdirSync(directory).filter((name) => name.endsWith(".lock"))).toEqual([]) expect(fs.readdirSync(elsewhere).filter((name) => name.endsWith(".lock"))).toEqual([]) From c433c1fc4e86ef25ce5ed4d06759c18542f9be2c Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:15:11 +0800 Subject: [PATCH 11/22] test(utils): contend the fileLock artefact from a second process The mocked suites can only model contention inside one process: they hand proper-lockfile a function of the test making, so a second caller is refused because a table says so rather than because a directory on disk already exists. Mutual exclusion is implemented by mkdir on lockfilePath, so whether two writers exclude each other turns entirely on whether they name one and the same artefact, and the artefact is named by the spelling the volume reports for the leaf. Add a describe that runs the other process for real: a child node process against the unmocked library, keyed by the module own canonicalLockKey and asked to take the artefact the rule produces. It reports the path it settled on and the acquire outcome through a trace file the child appends to synchronously, because piped stdout is written asynchronously and a child that ends the process loses the lines it just wrote. Four cases and one control: - the module holds and a second process arriving by the same spelling is refused ELOCKED on the path the module placed, which is the one artefact; - a foreign holder alone keeps this process out, and this process is admitted once that process ends and releases; - on Windows, a module holding through the 8.3 alias of the leaf refuses a second process that arrives by that alias, on the long-name artefact, because the rule asks the volume for the leaf before it names anything; - the control names the artefact by the callers own spelling instead, and the same pair of writers then lands on two artefacts and both get in; - on POSIX the same shape is asserted for a link used as the leaf. The child is plain CommonJS in a template literal: loading fileLock.ts from a child fails with ERR_MODULE_NOT_FOUND on the extensionless persistenceTrace import in its own chain, so the child restates only the artefact naming rule and takes the key from the module. The exported lock of proper-lockfile 4.1.2 is its promise wrapper and ignores a callback argument, so the child chains then and catch. Refs: 2368 --- src/utils/__tests__/fileLock.test.ts | 371 ++++++++++++++++++++++++++- 1 file changed, 370 insertions(+), 1 deletion(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 869f96c0e9..5b51f13f2d 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -1,6 +1,7 @@ -import { spawnSync } from "child_process" +import { spawn, spawnSync } from "child_process" import * as fs from "fs" import * as os from "os" +import { createRequire } from "module" import * as path from "path" import * as lockfile from "proper-lockfile" @@ -696,3 +697,371 @@ describe("identity keeps inodes above 2^53 distinct", () => { expect(canonicalLockKey(uncreated)).toBe(uncreated) }) }) +/** + * A second OS process contending for the same artefact, run by the suite below against the real lock + * library with no mocks. The mocked suites above can only model contention inside one process: they + * hand `proper-lockfile` a function of the test's making, so a second caller is refused because a + * table says so, not because a directory on disk already exists. What is under test here is whether + * the module and another process land on one and the same path, since the library implements mutual + * exclusion by `mkdir` on `lockfilePath` and reports `ELOCKED` when that path is already there, so + * two spellings that produced two artefacts would let both writers in and no assertion in this file + * would notice. + * + * The child is plain CommonJS inside a template literal rather than a TypeScript import: loading + * `fileLock.ts` from a child fails with ERR_MODULE_NOT_FOUND on the extensionless + * `../core/task-persistence/persistenceTrace` import, which is the module's own import chain, and the + * child therefore restates the one rule it needs - the artefact naming of `lockLeafSpelling`, naming + * the artefact by the spelling the volume reports for the leaf and falling back to the caller's own + * spelling where the volume has none - while the key comes from the module's `canonicalLockKey`, + * computed by the parent and passed in, so the child decides nothing else for itself. + * + * The handshake is a trace file the child appends to synchronously, not its stdout. Node writes to a + * piped stdout asynchronously, including on Windows, so a child that ends the process can lose the + * lines it wrote a moment before: that is what the first version of this suite did, and it failed on + * an empty buffer rather than on the lock. `appendFileSync` cannot be truncated that way, and the + * child sets `process.exitCode` instead of calling `process.exit`, so nothing is cut off at all. + * The exported `lock` of proper-lockfile 4.1.2 is its promise wrapper, measured at this head in + * `index.js`: `module.exports = lock` over `async function lock(file, options)`, which takes no callback, + * so a callback passed as a third argument is dropped without a word and the child would sit forever + * holding a lock it never told anyone about. The child therefore chains `.then` and `.catch`, which is + * the same shape `fileLock.ts` itself awaits. + */ +const HOLDER_SCRIPT = `const fs = require("fs") +const path = require("path") +const lockfile = require(process.env.DSH_LOCK_MODULE) +const spelling = process.env.DSH_LOCK_SPELLING +const trace = process.env.DSH_LOCK_TRACE +const holdMs = Number(process.env.DSH_LOCK_HOLD_MS || 0) +function traceLine(line) { + fs.appendFileSync(trace, line + "\\n", "utf8") +} +let artefact = (function (target) { + let leaf + try { + leaf = path.basename(fs.realpathSync.native(target)) + } catch { + leaf = path.basename(target) + } + return path.join(path.dirname(target), leaf) + ".lock" +})(spelling) +if (process.env.DSH_LOCK_NAIVE === "1") { + artefact = path.join(path.dirname(spelling), path.basename(spelling)) + ".lock" +} +traceLine("ARTEFACT " + artefact) +lockfile.lock(process.env.DSH_LOCK_KEY, { lockfilePath: artefact, stale: 31000, update: 10000, realpath: false, retries: 0 }) + .then((release) => { + if (typeof release !== "function") { + traceLine("OUTCOME failed no-release-function") + process.exitCode = 1 + return + } + traceLine("OUTCOME held") + const letGo = () => { + release().then(() => { + traceLine("RELEASED") + process.exitCode = 0 + }).catch((releaseError) => { + traceLine("RELEASE-FAILED " + String(releaseError.code)) + process.exitCode = 1 + }) + } + if (holdMs > 0) { + setTimeout(letGo, holdMs) + return + } + letGo() + }) + .catch((error) => { + traceLine("OUTCOME failed " + String(error.code)) + process.exitCode = 1 + })` + +interface HolderHandle { + pid: number | undefined + tracePath: string + childOutput: () => string + waitForExit: () => Promise +} + +/** + * Start the other process. `mode: "try"` asks it to take the lock and end, which is what a contention + * assertion needs; `mode: "hold"` makes it hold for six seconds so the suite can assert from this + * process that a live foreign holder is enough to keep the module out. + */ +function startLockHolder( + spelling: string, + mode: "try" | "hold", + lockModule: string, + directory: string, + traceName: string, + naive = false, +): HolderHandle { + const tracePath = path.join(directory, traceName) + const child = spawn(process.execPath, ["-e", HOLDER_SCRIPT], { + cwd: process.cwd(), + stdio: ["ignore", "pipe", "pipe"], + windowsHide: true, + env: { + ...process.env, + NO_COLOR: "1", + DSH_LOCK_MODULE: lockModule, + DSH_LOCK_SPELLING: spelling, + DSH_LOCK_TRACE: tracePath, + DSH_LOCK_HOLD_MS: mode === "hold" ? "6000" : "0", + DSH_LOCK_NAIVE: naive ? "1" : "0", + DSH_LOCK_KEY: canonicalLockKey(path.resolve(spelling)), + }, + }) + let output = "" + const note = (chunk: string): void => { + output += chunk + } + if (child.stdout) { + child.stdout.setEncoding("utf8") + child.stdout.on("data", note) + } + if (child.stderr) { + child.stderr.setEncoding("utf8") + child.stderr.on("data", note) + } + return { + pid: child.pid, + tracePath, + childOutput: () => (output.length > 400 ? output.slice(-400) : output), + waitForExit: () => + new Promise((resolve) => { + if (child.exitCode !== null) { + resolve(child.exitCode) + return + } + child.once("close", (code) => resolve(code)) + }), + } +} + +/** Read one line of the child's trace file, waiting at most `timeoutMs` for it to appear. */ +async function readHolderTrace( + tracePath: string, + marker: string, + timeoutMs: number, + childOutput: () => string, +): Promise { + const deadline = Date.now() + timeoutMs + for (;;) { + let content = "" + try { + content = fs.readFileSync(tracePath, "utf8") + } catch { + content = "" + } + const hit = content.split("\n").find((line) => line.startsWith(marker)) + if (hit) { + return hit.trim() + } + if (Date.now() > deadline) { + throw new Error( + `no "${marker}" in ${tracePath} within ${timeoutMs} ms; trace was ${JSON.stringify(content)} and the child said ${JSON.stringify(childOutput())}`, + ) + } + await new Promise((sleep) => setTimeout(sleep, 25)) + } +} + +function traceArtefact(traceLineText: string): string { + const hit = traceLineText.match(/ARTEFACT (.+)/) + if (!hit) { + throw new Error(`the child never reported an artefact path; trace line was ${JSON.stringify(traceLineText)}`) + } + return hit[1].trim() +} + +function traceOutcome(traceLineText: string): string { + const hit = traceLineText.match(/OUTCOME (\S+)(?: (\S+))?/) + if (!hit) { + throw new Error(`the child never reported an acquire outcome; trace line was ${JSON.stringify(traceLineText)}`) + } + return hit[2] ? hit[1] + " " + hit[2] : hit[1] +} + +function artefactsOf(directory: string): string[] { + return fs + .readdirSync(directory) + .filter((name) => name.endsWith(".lock")) + .sort() +} + +describe("another process contends for the same artefact", () => { + const root = useTemporaryRoot("fileLock-crossproc-") + let actualLock: typeof lockfile.lock + let lockModule = "" + let generatesShortNames = false + let traceIndex = 0 + beforeAll(async () => { + actualLock = (await vi.importActual("proper-lockfile")).lock + // The child requires the library by path: it runs with no module resolution context of its own. + lockModule = createRequire(import.meta.url).resolve("proper-lockfile") + generatesShortNames = process.platform === "win32" && shortNamesGenerated(root()) + }) + beforeEach(() => { + vi.mocked(lockfile.lock).mockImplementation((target, options) => actualLock(target, options)) + }) + + function scenario(name: string): { directory: string; target: string } { + const directory = path.join(root(), name) + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, "{}", "utf8") + return { directory, target } + } + + function nextTraceName(): string { + traceIndex += 1 + return `holder-trace-${traceIndex}.txt` + } + + it( + "refuses a second process that arrives by the same spelling while the module holds", + { timeout: 30000 }, + async () => { + const { directory, target } = scenario("same-spelling-held") + const release = await acquireFileLock(target, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + const holder = startLockHolder(target, "try", lockModule, directory, nextTraceName()) + const artefactLine = await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceArtefact(artefactLine)).toBe(path.join(directory, "history.json.lock")) + expect(traceOutcome(outcomeLine)).toBe("failed ELOCKED") + expect(await holder.waitForExit()).toBe(1) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + await release() + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + it( + "keeps this process out while another process holds, and admits it once that process ends", + { timeout: 30000 }, + async () => { + const { directory, target } = scenario("same-spelling-free") + const holder = startLockHolder(target, "hold", lockModule, directory, nextTraceName()) + await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceOutcome(outcomeLine)).toBe("held") + if (typeof holder.pid !== "number") { + throw new Error( + `the holder child never reported a pid; it said ${JSON.stringify(holder.childOutput())}`, + ) + } + expect(process.kill(holder.pid, 0)).toBe(true) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + expect(await holder.waitForExit()).toBe(0) + const traceNow = fs.readFileSync(holder.tracePath, "utf8") + expect(traceNow.split("\n")).toContain("RELEASED") + expect(artefactsOf(directory)).toEqual([]) + const admitted = await acquireFileLock(target, { immediate: true }) + await admitted() + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + const itWindowsLeafAlias = (name: string, fn: () => Promise) => + it(name, { timeout: 30000 }, async (context) => { + if (!generatesShortNames) { + return context.skip() + } + await fn() + }) + + itWindowsLeafAlias( + "refuses a second process arriving by the 8.3 alias of the leaf while the module holds the alias", + async () => { + const directory = path.join(root(), "leaf-alias-crossproc") + fs.mkdirSync(directory, { recursive: true }) + const longLeaf = path.join(directory, "task-history-leaf-for-crossproc-alias-testing.json") + fs.writeFileSync(longLeaf, "{}", "utf8") + const aliasLeaf = aliasOf(longLeaf) + expect(aliasLeaf).not.toBe(longLeaf) + const release = await acquireFileLock(aliasLeaf, { immediate: true }) + const placed = ["task-history-leaf-for-crossproc-alias-testing.json.lock"] + expect(artefactsOf(directory)).toEqual(placed) + const holder = startLockHolder(aliasLeaf, "try", lockModule, directory, nextTraceName()) + const artefactLine = await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceArtefact(artefactLine)).toBe(path.join(directory, placed[0])) + expect(traceOutcome(outcomeLine)).toBe("failed ELOCKED") + expect(await holder.waitForExit()).toBe(1) + expect(artefactsOf(directory)).toEqual(placed) + await release() + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + // The negative control for the alias case above. Name the artefact by the caller's own spelling, the + // way a module that never consulted the volume would, and this same pair of writers lands on two + // artefacts and both get in. That is the shape the bots described, and it is the spelling rule that + // keeps it out of the suite; if the module ever fell back to the caller's spelling the case below would + // go red rather than pass for the wrong reason. + itWindowsLeafAlias( + "lets a second process in when the artefact is named by the caller's spelling instead of the volume's", + async () => { + const directory = path.join(root(), "leaf-alias-crossproc-control") + fs.mkdirSync(directory, { recursive: true }) + const longLeaf = path.join(directory, "task-history-leaf-for-crossproc-control-testing.json") + fs.writeFileSync(longLeaf, "{}", "utf8") + const aliasLeaf = aliasOf(longLeaf) + expect(aliasLeaf).not.toBe(longLeaf) + const release = await acquireFileLock(aliasLeaf, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["task-history-leaf-for-crossproc-control-testing.json.lock"]) + // Hold, rather than take-and-release, so that both artefacts are on disk at the moment of looking. + const holder = startLockHolder(aliasLeaf, "hold", lockModule, directory, nextTraceName(), true) + const artefactLine = await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + const callerNamed = (path.basename(aliasLeaf) + ".lock").toLowerCase() + const moduleNamed = "task-history-leaf-for-crossproc-control-testing.json.lock" + expect(traceArtefact(artefactLine).toLowerCase()).toBe(path.join(directory, callerNamed).toLowerCase()) + expect(callerNamed).not.toBe(moduleNamed) + expect(traceOutcome(outcomeLine)).toBe("held") + expect( + artefactsOf(directory) + .map((name) => name.toLowerCase()) + .sort(), + ).toEqual([callerNamed, moduleNamed].sort()) + expect(await holder.waitForExit()).toBe(0) + expect(fs.readFileSync(holder.tracePath, "utf8").split("\n")).toContain("RELEASED") + await release() + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + const itPosixLeaf = (name: string, fn: () => Promise) => + it(name, { timeout: 30000 }, async (context) => { + if (process.platform === "win32") { + return context.skip() + } + await fn() + }) + + itPosixLeaf( + "refuses a second process arriving by the target of a link while the module holds the link", + async () => { + const directory = path.join(root(), "link-leaf-crossproc") + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, "{}", "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync("history.json", link) + const release = await acquireFileLock(link, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + const holder = startLockHolder(link, "try", lockModule, directory, nextTraceName()) + const artefactLine = await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceArtefact(artefactLine)).toBe(path.join(directory, "history.json.lock")) + expect(traceOutcome(outcomeLine)).toBe("failed ELOCKED") + expect(await holder.waitForExit()).toBe(1) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + await release() + expect(artefactsOf(directory)).toEqual([]) + }, + ) +}) From 87bc9cf8e497bdf0f38dbdd5e0cf4777cf12c425 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Wed, 11 Nov 2026 22:04:46 +0800 Subject: [PATCH 12/22] test(utils): coexist an unrelated lock, queue a merge writer, let go the renewal The three open review rows on 1395 each ask for a regression case against the fileLock artefact. These three suites are those cases, and each carries its own control so that a green row is not green for the wrong reason. An unrelated lock and a held leaf coexist while the alias contends. The leaf lock and a sibling lock with its own name and its own inode are held at the same time on two artefacts, a foreign process arriving by the leaf's 8.3 alias is refused on the long-name artefact while both locks are live, and a foreign process arriving at the sibling gets in and is refused again from outside. The alias probe and the sibling probe share the launcher, the directory and the assertions and end in opposite outcomes, so neither statement rides on the other. A posix twin holds a link and an unrelated sibling and refuses a process arriving at the link's target. A writer that had to wait merges into what landed while it waited. A foreign process holds the artefact and writes through it while this process queues two safeWriteJson merge writes behind it, and all three keys land through one artefact. The paired rows then make one process wait behind a lock this process holds, and differ only in when it reads the base it merges into: re-read after admission and the key that landed meanwhile survives, read before it ever tried and that key is lost - and the second row asserts the loss, so the first row proves the re-read rather than merely the absence of damage. A replaced referent lets go both locks and the renewal timer. With the referent renamed over under a held lock, a second acquisition is refused on the artefact the first lock armed, and the timer ledger shows the library's renewal outstanding while that lock is held, unchanged across an attempt that never owned the artefact, and cancelled by the release. Both releases, both artefacts and the body that survived are asserted. The renewal is watched by wrapping setTimeout and clearTimeout for one row and counting only the calls whose stack names the library, because the library hands that timer to unref() at lib/lockfile.js:180-181 and an un-ref-ed timer is invisible to process.getActiveResourcesInfo() - measured on this box: 1 before unref, 0 after. The instrument proves itself inside the rows: had the attribution matched nothing, the armed counts would be zero and the rows would be red. Gates on this box (node v25.9.0 against a head pinning 22.23.4): vitest.misc.config.ts on utils/__tests__/fileLock.test.ts - 29 passed, 8 skipped of 37, 19.75s, the two posix twins skipped on win32 and every other row executed; prettier --check clean after --write; eslint --max-warnings=0 exit 0, and the file has no entry in src/eslint-suppressions.json before or after; tsc --noEmit -p src/tsconfig.json exit 0 with no diagnostics. Refs: 2368 Refs: 1395 --- src/utils/__tests__/fileLock.test.ts | 616 ++++++++++++++++++++++++++- 1 file changed, 613 insertions(+), 3 deletions(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index 5b51f13f2d..b54ce070ea 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -7,6 +7,7 @@ import * as path from "path" import * as lockfile from "proper-lockfile" import { acquireFileLock, canonicalLockKey, LOCK_STALE_MS, withFileLock } from "../fileLock" +import { safeWriteJson } from "../safeWriteJson" vi.mock("proper-lockfile", () => ({ lock: vi.fn() })) @@ -732,9 +733,19 @@ const lockfile = require(process.env.DSH_LOCK_MODULE) const spelling = process.env.DSH_LOCK_SPELLING const trace = process.env.DSH_LOCK_TRACE const holdMs = Number(process.env.DSH_LOCK_HOLD_MS || 0) +const retries = Number(process.env.DSH_LOCK_RETRIES || 0) +const baseMode = process.env.DSH_LOCK_BASE +const writeKey = process.env.DSH_LOCK_WRITE_KEY || "" function traceLine(line) { fs.appendFileSync(trace, line + "\\n", "utf8") } +function readBody(target) { + try { + return JSON.parse(fs.readFileSync(target, "utf8")) + } catch { + return {} + } +} let artefact = (function (target) { let leaf try { @@ -748,7 +759,11 @@ if (process.env.DSH_LOCK_NAIVE === "1") { artefact = path.join(path.dirname(spelling), path.basename(spelling)) + ".lock" } traceLine("ARTEFACT " + artefact) -lockfile.lock(process.env.DSH_LOCK_KEY, { lockfilePath: artefact, stale: 31000, update: 10000, realpath: false, retries: 0 }) +const staleBase = baseMode === "before" ? readBody(spelling) : null +if (baseMode === "before") { + traceLine("BASE-BEFORE " + JSON.stringify(staleBase)) +} +lockfile.lock(process.env.DSH_LOCK_KEY, { lockfilePath: artefact, stale: 31000, update: 10000, realpath: false, retries: retries }) .then((release) => { if (typeof release !== "function") { traceLine("OUTCOME failed no-release-function") @@ -756,6 +771,14 @@ lockfile.lock(process.env.DSH_LOCK_KEY, { lockfilePath: artefact, stale: 31000, return } traceLine("OUTCOME held") + if (writeKey) { + const base = baseMode === "before" ? staleBase : readBody(spelling) + traceLine(baseMode === "before" ? "BASE-USED " + JSON.stringify(base) : "BASE-UNDER-LOCK " + JSON.stringify(base)) + const merged = Object.assign({}, base) + merged[writeKey] = 1 + fs.writeFileSync(spelling, JSON.stringify(merged), "utf8") + traceLine("WROTE " + JSON.stringify(readBody(spelling))) + } const letGo = () => { release().then(() => { traceLine("RELEASED") @@ -783,10 +806,23 @@ interface HolderHandle { waitForExit: () => Promise } +interface HolderOptions { + /** Milliseconds to hold before releasing; overrides the mode default. */ + holdMs?: number + /** A key the child merges into the file under its own lock; empty means no write. */ + writeKey?: string + /** Where the child reads the base it merges into: after admission, or before it ever tried. */ + baseMode?: "under" | "before" + /** Retry budget the child hands the library, so it can be the writer that has to wait. */ + retries?: number +} + /** * Start the other process. `mode: "try"` asks it to take the lock and end, which is what a contention * assertion needs; `mode: "hold"` makes it hold for six seconds so the suite can assert from this - * process that a live foreign holder is enough to keep the module out. + * process that a live foreign holder is enough to keep the module out. The options turn the same child + * into the two shapes the persistence and lifecycle rows need: a writer that lands while others queue, + * and a writer that has to queue behind a lock this process is holding. */ function startLockHolder( spelling: string, @@ -795,6 +831,7 @@ function startLockHolder( directory: string, traceName: string, naive = false, + options: HolderOptions = {}, ): HolderHandle { const tracePath = path.join(directory, traceName) const child = spawn(process.execPath, ["-e", HOLDER_SCRIPT], { @@ -807,7 +844,10 @@ function startLockHolder( DSH_LOCK_MODULE: lockModule, DSH_LOCK_SPELLING: spelling, DSH_LOCK_TRACE: tracePath, - DSH_LOCK_HOLD_MS: mode === "hold" ? "6000" : "0", + DSH_LOCK_HOLD_MS: String(options.holdMs ?? (mode === "hold" ? 6000 : 0)), + DSH_LOCK_RETRIES: String(options.retries ?? 0), + DSH_LOCK_BASE: options.baseMode ?? "under", + DSH_LOCK_WRITE_KEY: options.writeKey ?? "", DSH_LOCK_NAIVE: naive ? "1" : "0", DSH_LOCK_KEY: canonicalLockKey(path.resolve(spelling)), }, @@ -1065,3 +1105,573 @@ describe("another process contends for the same artefact", () => { }, ) }) + +/** + * A shallow merge of two decoded JSON bodies: the shape every merge callback below hands + * `safeWriteJson`, and the shape the child script performs with `Object.assign`. The one assertion is + * the step the guard cannot make for TypeScript - an `unknown` that passed `typeof value === "object"` + * is still not a record, and an array would spread into numeric keys rather than into nothing. + */ +const asRecord = (value: unknown): Record => + value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record) : {} + +const mergeRecords = (existing: unknown, incoming: unknown): unknown => ({ + ...asRecord(existing), + ...asRecord(incoming), +}) + +/** Merge one key into a JSON file, onto whatever the file holds at the moment of writing. */ +function writeMergedKey(filePath: string, key: string): void { + const base = asRecord(JSON.parse(fs.readFileSync(filePath, "utf8"))) + fs.writeFileSync(filePath, JSON.stringify({ ...base, [key]: 1 }), "utf8") +} + +function readJsonBody(filePath: string): Record { + return JSON.parse(fs.readFileSync(filePath, "utf8")) as Record +} + +/** The JSON payload of one line the child traced. */ +function tracePayload(traceLineText: string, marker: string): Record { + const hit = traceLineText.trim().match(new RegExp("^" + marker + " (.+)$")) + if (!hit) { + throw new Error(`no "${marker}" payload in the trace line ${JSON.stringify(traceLineText)}`) + } + return JSON.parse(hit[1]) as Record +} + +interface TimerLedger { + armed(): number + cancelled(): number + outstanding(): number + delays: number[] + restore(): void +} + +/** + * Count the timers proper-lockfile arms and the ones it cancels, attributed by the stack of the call + * that armed them. The obvious instrument is not available here: the library hands its renewal timer to + * `unref()` at `lib/lockfile.js:180-181`, and an un-ref-ed timer drops out of + * `process.getActiveResourcesInfo()` - measured on this box, one live `setInterval` counts 1 and the + * same timer after `unref()` counts 0 - so the renewal has to be watched where it is created, by + * wrapping `setTimeout` and `clearTimeout` for the length of one row and counting only the calls whose + * stack names the library. Every other timer in the process gets back exactly what it asked for. + * + * The assertions below are load-bearing rather than decorative: on this platform `setTimeout` and + * `clearTimeout` are overload unions, and a wrapper that hands the callback, the delay and any further + * arguments through unchanged cannot be written without asserting past the union. vitest and node both + * arm timers with extra arguments, so dropping them here would change the run instead of only watching + * it, which is the difference between an instrument and a disturbance. + */ +function watchLibraryTimers(): TimerLedger { + const setOriginal = globalThis.setTimeout as unknown as (...callArguments: unknown[]) => unknown + const clearOriginal = globalThis.clearTimeout as unknown as (handle: unknown) => void + const armedHandles = new Set() + const delays: number[] = [] + let armed = 0 + let cancelled = 0 + globalThis.setTimeout = ((callback: unknown, ms?: unknown, ...rest: unknown[]): unknown => { + const stack = new Error().stack ?? "" + const handle = setOriginal(callback, ms, ...rest) + if (stack.includes("proper-lockfile")) { + armed += 1 + delays.push(Number(ms)) + armedHandles.add(handle) + } + return handle + }) as typeof globalThis.setTimeout + globalThis.clearTimeout = ((handle: unknown): void => { + if (armedHandles.delete(handle)) { + cancelled += 1 + } + clearOriginal(handle) + }) as typeof globalThis.clearTimeout + return { + armed: () => armed, + cancelled: () => cancelled, + outstanding: () => armed - cancelled, + delays, + restore: () => { + globalThis.setTimeout = setOriginal as typeof globalThis.setTimeout + globalThis.clearTimeout = clearOriginal as typeof globalThis.clearTimeout + }, + } +} + +/** + * The reviewer-bot's "Regression Evidence" row asks for a real-library test that holds the link and + * unrelated sibling locks concurrently while keeping the alias contention. Two thirds of that already + * has a name in this file: the two 8.3 alias rows and the junction row in the suite above run against + * the unmocked library, and so does "contends an unrelated sibling named like the link target against + * the link's lock", which proves the collision a *similarly named* sibling causes. What none of them + * proves is the coexistence half - that a sibling with its own name and its own inode takes its own + * artefact and that both writers then hold locks at the same time - nor that a held lock is a directory + * on a volume rather than a table entry in this process, which only a second process can show. The + * middle row is the control that tells those two statements apart: the same launcher, the same + * directory, the same trace assertions, and opposite outcomes for the alias of the held leaf and for + * the unrelated sibling, so no row here can be green because the harness refused everything or admitted + * everything. + */ +describe("an unrelated lock and a held leaf coexist while the alias contends", () => { + const root = useTemporaryRoot("fileLock-coheld-") + let actualLock: typeof lockfile.lock + let lockModule = "" + let generatesShortNames = false + let traceIndex = 0 + beforeAll(async () => { + actualLock = (await vi.importActual("proper-lockfile")).lock + lockModule = createRequire(import.meta.url).resolve("proper-lockfile") + generatesShortNames = process.platform === "win32" && shortNamesGenerated(root()) + }) + beforeEach(() => { + vi.mocked(lockfile.lock).mockImplementation((target, options) => actualLock(target, options)) + }) + + function scenario(name: string, leafName: string): { directory: string; target: string } { + const directory = path.join(root(), name) + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, leafName) + fs.writeFileSync(target, '{"pre":1}', "utf8") + return { directory, target } + } + + function nextTraceName(): string { + traceIndex += 1 + return `coheld-trace-${traceIndex}.txt` + } + + const itVolumeAlias = (name: string, fn: () => Promise) => + it(name, { timeout: 30000 }, async (context) => { + if (!generatesShortNames) { + return context.skip() + } + await fn() + }) + + const itPosixLeaf = (name: string, fn: () => Promise) => + it(name, { timeout: 30000 }, async (context) => { + if (process.platform === "win32") { + return context.skip() + } + await fn() + }) + + itVolumeAlias( + "holds the leaf lock and an unrelated sibling lock at once and still refuses the alias of the held leaf", + async () => { + const { directory, target } = scenario("coheld-alias", "task-history-leaf-for-coheld-lock-testing.json") + const sibling = path.join(directory, "state-sidecar-leaf-for-coheld-lock-testing.json") + fs.writeFileSync(sibling, '{"pre":1}', "utf8") + const aliasLeaf = aliasOf(target) + expect(aliasLeaf).not.toBe(target) + const releaseLeaf = await acquireFileLock(target, { immediate: true }) + // The coexistence half: a sibling with its own name and its own inode has to get in. + const releaseSibling = await acquireFileLock(sibling, { immediate: true }) + const bothPlaced = [ + "state-sidecar-leaf-for-coheld-lock-testing.json.lock", + "task-history-leaf-for-coheld-lock-testing.json.lock", + ].sort() + expect(artefactsOf(directory)).toEqual(bothPlaced) + expect(canonicalLockKey(target)).not.toBe(canonicalLockKey(sibling)) + expect(artefactsOf(directory)[0]).not.toBe(artefactsOf(directory)[1]) + // The alias half inside the same row: a foreign process arriving by the 8.3 spelling of the + // held leaf is refused on the long-name artefact, which is the point the row on #1395 holds open. + const aliasProbe = startLockHolder(aliasLeaf, "try", lockModule, directory, nextTraceName()) + const aliasArtefact = await readHolderTrace(aliasProbe.tracePath, "ARTEFACT", 15000, aliasProbe.childOutput) + const aliasOutcome = await readHolderTrace(aliasProbe.tracePath, "OUTCOME", 15000, aliasProbe.childOutput) + expect(traceArtefact(aliasArtefact)).toBe( + path.join(directory, "task-history-leaf-for-coheld-lock-testing.json.lock"), + ) + expect(traceOutcome(aliasOutcome)).toBe("failed ELOCKED") + expect(await aliasProbe.waitForExit()).toBe(1) + // And the sibling's lock is a directory on a volume rather than bookkeeping in this process: + // a foreign process arriving at the sibling is refused too, on the sibling's own artefact. + const siblingProbe = startLockHolder(sibling, "try", lockModule, directory, nextTraceName()) + const siblingArtefact = await readHolderTrace( + siblingProbe.tracePath, + "ARTEFACT", + 15000, + siblingProbe.childOutput, + ) + const siblingOutcome = await readHolderTrace( + siblingProbe.tracePath, + "OUTCOME", + 15000, + siblingProbe.childOutput, + ) + expect(traceArtefact(siblingArtefact)).toBe( + path.join(directory, "state-sidecar-leaf-for-coheld-lock-testing.json.lock"), + ) + expect(traceOutcome(siblingOutcome)).toBe("failed ELOCKED") + expect(await siblingProbe.waitForExit()).toBe(1) + expect(artefactsOf(directory)).toEqual(bothPlaced) + await releaseLeaf() + await releaseSibling() + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + itVolumeAlias("admits a second process locking the unrelated sibling while the leaf lock is held", async () => { + const { directory, target } = scenario("coheld-sibling-free", "task-history-leaf-for-sibling-admission.json") + const sibling = path.join(directory, "state-sidecar-leaf-for-sibling-admission.json") + fs.writeFileSync(sibling, '{"pre":1}', "utf8") + const releaseLeaf = await acquireFileLock(target, { immediate: true }) + const holder = startLockHolder(sibling, "hold", lockModule, directory, nextTraceName(), false, { + holdMs: 1500, + }) + await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceOutcome(outcomeLine)).toBe("held") + expect(artefactsOf(directory)).toEqual([ + "state-sidecar-leaf-for-sibling-admission.json.lock", + "task-history-leaf-for-sibling-admission.json.lock", + ]) + expect(await holder.waitForExit()).toBe(0) + expect(fs.readFileSync(holder.tracePath, "utf8").split("\n")).toContain("RELEASED") + await releaseLeaf() + expect(artefactsOf(directory)).toEqual([]) + }) + + itPosixLeaf( + "holds a link lock and an unrelated sibling lock at once and refuses a process arriving at the target", + async () => { + const directory = path.join(root(), "coheld-link") + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, '{"pre":1}', "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync("history.json", link) + const sibling = path.join(directory, "state-sidecar.json") + fs.writeFileSync(sibling, '{"pre":1}', "utf8") + expect(fs.statSync(link).ino).toBe(fs.statSync(target).ino) + const releaseLink = await acquireFileLock(link, { immediate: true }) + const releaseSibling = await acquireFileLock(sibling, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock", "state-sidecar.json.lock"]) + expect(canonicalLockKey(link)).not.toBe(canonicalLockKey(sibling)) + const probe = startLockHolder(target, "try", lockModule, directory, nextTraceName()) + const probeArtefact = await readHolderTrace(probe.tracePath, "ARTEFACT", 15000, probe.childOutput) + const probeOutcome = await readHolderTrace(probe.tracePath, "OUTCOME", 15000, probe.childOutput) + expect(traceArtefact(probeArtefact)).toBe(path.join(directory, "history.json.lock")) + expect(traceOutcome(probeOutcome)).toBe("failed ELOCKED") + expect(await probe.waitForExit()).toBe(1) + expect(artefactsOf(directory)).toEqual(["history.json.lock", "state-sidecar.json.lock"]) + await releaseLink() + await releaseSibling() + expect(artefactsOf(directory)).toEqual([]) + }, + ) +}) + +/** + * The "Persistence Integrity" row asks for a cross-process test with a waiting writer and concurrent + * safeWriteJson merge writes. The cross-process suite above proves admission and refusal but no writer + * in it ever wrote a body through the lock, and the merge rows above never leave this process. These + * three rows put a writer in another process with a queue in front of it. The first lands a foreign + * writer and this process's two concurrent merge writers onto one file through one artefact. The second + * and third are one scenario told twice with a single flag between them: a process that has to wait + * behind a lock this process is holding, which either re-reads the file after it is admitted or merges + * into the copy it read before it ever tried. The second keeps the key that landed while it waited, the + * third loses it. Without the third row the second only proves that nothing was lost, which is not the + * same as proving that the re-read under the lock is the thing that kept it. + */ +describe("a writer that had to wait merges into what landed while it waited", () => { + const root = useTemporaryRoot("fileLock-merge-wait-") + let actualLock: typeof lockfile.lock + let lockModule = "" + let traceIndex = 0 + beforeAll(async () => { + actualLock = (await vi.importActual("proper-lockfile")).lock + lockModule = createRequire(import.meta.url).resolve("proper-lockfile") + }) + beforeEach(() => { + vi.mocked(lockfile.lock).mockImplementation((target, options) => actualLock(target, options)) + }) + + // The queue this module builds when the artefact belongs to someone else: for a plain call + // fileLock.ts:119-125 hands the library five retries after the first attempt, capped at 1000 ms + // each, so attempts land at about 0, 100, 300, 700, 1500 and 2500 ms and a queued writer gives up + // after roughly 2.5 seconds. Two consequences shape the rows below: a foreign hold has to end + // inside that horizon or the queued writers of this process would fail rather than wait, and a row + // that sits behind another process gets a minute of row budget rather than the fifteen seconds the + // faster rows here get. + function scenario(name: string): { directory: string; target: string } { + const directory = path.join(root(), name) + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, '{"pre":1}', "utf8") + return { directory, target } + } + + function nextTraceName(): string { + traceIndex += 1 + return "merge-trace-" + traceIndex + ".txt" + } + + it( + "lands two concurrent merge writers and a foreign writer into one file through one artefact", + { timeout: 60000 }, + async () => { + const { directory, target } = scenario("merge-three-writers") + // One second, which is inside the 2.5 s the two merge writers below are willing to wait, so + // they are admitted on their third or fourth attempt instead of exhausting the budget. + const holder = startLockHolder(target, "hold", lockModule, directory, nextTraceName(), false, { + holdMs: 1000, + writeKey: "child", + baseMode: "under", + }) + const artefactLine = await readHolderTrace(holder.tracePath, "ARTEFACT", 15000, holder.childOutput) + const outcomeLine = await readHolderTrace(holder.tracePath, "OUTCOME", 15000, holder.childOutput) + expect(traceArtefact(artefactLine)).toBe(path.join(directory, "history.json.lock")) + expect(traceOutcome(outcomeLine)).toBe("held") + // The foreign writer read its base after it was admitted, which is the only reason its key is + // still in the file at the end of the row. + const foreignBase = await readHolderTrace(holder.tracePath, "BASE-UNDER-LOCK", 15000, holder.childOutput) + expect(tracePayload(foreignBase, "BASE-UNDER-LOCK")).toEqual({ pre: 1 }) + // Both of these arrive at a file another process holds, so both take the retry path described + // above, and neither resolves until its own write has landed under its own lock. A rejection + // here fails the row, so awaiting them is the assertion that both got in. + await Promise.all([ + safeWriteJson(target, { writerA: 1 }, { merge: mergeRecords }), + safeWriteJson(target, { writerB: 1 }, { merge: mergeRecords }), + ]) + expect(await holder.waitForExit()).toBe(0) + expect(readJsonBody(target)).toEqual({ pre: 1, child: 1, writerA: 1, writerB: 1 }) + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + it( + "re-reads under the lock when the process that had to wait is admitted after another key landed", + { timeout: 60000 }, + async () => { + const { directory, target } = scenario("merge-waiter-under") + const release = await acquireFileLock(target, { immediate: true }) + const waiter = startLockHolder(target, "hold", lockModule, directory, nextTraceName(), false, { + holdMs: 0, + writeKey: "child", + baseMode: "under", + retries: 5, + }) + await readHolderTrace(waiter.tracePath, "ARTEFACT", 15000, waiter.childOutput) + // Measured rather than assumed: this process wrote while the other one had still not been + // admitted, which is what makes it a waiting writer at all rather than a second writer that + // merely ran later. + expect(fs.readFileSync(waiter.tracePath, "utf8")).not.toContain("OUTCOME held") + writeMergedKey(target, "writerA") + await release() + const outcomeLine = await readHolderTrace(waiter.tracePath, "OUTCOME", 25000, waiter.childOutput) + expect(traceOutcome(outcomeLine)).toBe("held") + const baseLine = await readHolderTrace(waiter.tracePath, "BASE-UNDER-LOCK", 15000, waiter.childOutput) + expect(tracePayload(baseLine, "BASE-UNDER-LOCK")).toEqual({ pre: 1, writerA: 1 }) + expect(await waiter.waitForExit()).toBe(0) + expect(readJsonBody(target)).toEqual({ pre: 1, writerA: 1, child: 1 }) + expect(artefactsOf(directory)).toEqual([]) + }, + ) + + it( + "loses the key that landed while it waited when the waiting process merges against a base read before it tried", + { timeout: 60000 }, + async () => { + const { directory, target } = scenario("merge-waiter-before") + const release = await acquireFileLock(target, { immediate: true }) + const waiter = startLockHolder(target, "hold", lockModule, directory, nextTraceName(), false, { + holdMs: 0, + writeKey: "child", + baseMode: "before", + retries: 5, + }) + const beforeLine = await readHolderTrace(waiter.tracePath, "BASE-BEFORE", 15000, waiter.childOutput) + expect(tracePayload(beforeLine, "BASE-BEFORE")).toEqual({ pre: 1 }) + expect(fs.readFileSync(waiter.tracePath, "utf8")).not.toContain("OUTCOME held") + writeMergedKey(target, "writerA") + await release() + const outcomeLine = await readHolderTrace(waiter.tracePath, "OUTCOME", 25000, waiter.childOutput) + expect(traceOutcome(outcomeLine)).toBe("held") + const usedLine = await readHolderTrace(waiter.tracePath, "BASE-USED", 15000, waiter.childOutput) + expect(tracePayload(usedLine, "BASE-USED")).toEqual({ pre: 1 }) + expect(await waiter.waitForExit()).toBe(0) + const content = readJsonBody(target) + expect(content).toEqual({ pre: 1, child: 1 }) + expect(content).not.toHaveProperty("writerA") + expect(artefactsOf(directory)).toEqual([]) + }, + ) +}) + +/** + * The "Lifecycle Resource Cleanup" row asks for a regression test that acquires after replacement while + * the first lock is still held, and then checks both releases and the timer cleanup. The posix row that + * holds two locks on one referent after the directory it lived in was replaced already covers + * acquire-after-replacement and the disappearance of both artefacts, and it names the compromised-lock + * hazard the renewal can hit; what none of the existing rows does is look at the renewal timer at all, + * and the acquire-after-replacement row never runs on the platform this suite is being run on. These + * rows put the replacement and the renewal in one row where the row executes. The second row is the + * control that makes the first row's arithmetic mean something: it shows a renewal timer sitting + * outstanding while a lock is held, shows an attempt that never owned the artefact adding nothing + * outstanding, and shows the release being the thing that cancels it, so a row that ends balanced is + * balanced because the release let go and not because nothing was ever armed. + */ +describe("a replaced referent lets go both locks and the renewal timer", () => { + const root = useTemporaryRoot("fileLock-timer-") + let actualLock: typeof lockfile.lock + beforeAll(async () => { + actualLock = (await vi.importActual("proper-lockfile")).lock + }) + beforeEach(() => { + vi.mocked(lockfile.lock).mockImplementation((target, options) => actualLock(target, options)) + }) + + function scenario(name: string, leafName: string): { directory: string; target: string } { + const directory = path.join(root(), name) + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, leafName) + fs.writeFileSync(target, '{"pre":1}', "utf8") + return { directory, target } + } + + it( + "lets go both locks and the renewal timer when the referent is replaced under a held lock", + { timeout: 30000 }, + async () => { + const { directory, target } = scenario("timer-replaced-referent", "history.json") + const ledger = watchLibraryTimers() + let releaseFirst: (() => Promise) | null = null + let releaseSecond: (() => Promise) | null = null + try { + releaseFirst = await acquireFileLock(target, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + // The renewal the library armed for this lock: fileLock.ts asks for update 10000 at + // fileLock.ts:108, the library clamps it against the staleness window at + // lib/lockfile.js:220-221, and lib/lockfile.js:109 is where the timer is armed. + expect(ledger.armed()).toBeGreaterThanOrEqual(1) + expect(ledger.outstanding()).toBe(1) + expect(ledger.delays).toContain(10000) + const replacement = path.join(directory, "history.json.next") + fs.writeFileSync(replacement, '{"replaced":1}', "utf8") + fs.renameSync(replacement, target) + expect(readJsonBody(target)).toEqual({ replaced: 1 }) + // The half the row is named for: an acquisition attempted after the referent was replaced, + // while the first lock is still held. The leaf name survived the replacement, so the volume + // still spells the file the same way, so this is refused on the artefact the first one + // armed rather than quietly taking a second lock beside it. + await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + expect(ledger.outstanding()).toBe(1) + await releaseFirst() + releaseFirst = null + // The release is what cancels the renewal: lib/lockfile.js:288 clears the update timeout + // before it removes the artefact, and the artefact going is the other half of the same call. + expect(ledger.cancelled()).toBe(ledger.armed()) + expect(ledger.outstanding()).toBe(0) + expect(artefactsOf(directory)).toEqual([]) + releaseSecond = await acquireFileLock(target, { immediate: true }) + expect(ledger.outstanding()).toBe(1) + writeMergedKey(target, "writer") + await releaseSecond() + releaseSecond = null + expect(ledger.outstanding()).toBe(0) + expect(artefactsOf(directory)).toEqual([]) + expect(readJsonBody(target)).toEqual({ replaced: 1, writer: 1 }) + } finally { + ledger.restore() + if (releaseFirst !== null) { + await releaseFirst() + } + if (releaseSecond !== null) { + await releaseSecond() + } + } + }, + ) + + it( + "keeps a renewal timer outstanding until the lock that armed it is let go, and arms none for an attempt that never owned the artefact", + { timeout: 30000 }, + async () => { + const { directory, target } = scenario("timer-outstanding", "history.json") + const ledger = watchLibraryTimers() + let release: (() => Promise) | null = null + try { + release = await acquireFileLock(target, { immediate: true }) + expect(ledger.armed()).toBeGreaterThanOrEqual(1) + expect(ledger.outstanding()).toBe(1) + const armedBeforeAttempt = ledger.armed() + await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + expect(ledger.armed()).toBe(armedBeforeAttempt) + expect(ledger.outstanding()).toBe(1) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + await release() + release = null + expect(ledger.cancelled()).toBe(ledger.armed()) + expect(ledger.outstanding()).toBe(0) + expect(artefactsOf(directory)).toEqual([]) + } finally { + ledger.restore() + if (release !== null) { + await release() + } + } + }, + ) + + const itPosixLeaf = (name: string, fn: () => Promise) => + it(name, { timeout: 30000 }, async (context) => { + if (process.platform === "win32") { + return context.skip() + } + await fn() + }) + + itPosixLeaf( + "lets go both locks and the renewal timer when a link target is replaced under a held lock", + async () => { + const directory = path.join(root(), "timer-link-replaced") + fs.mkdirSync(directory, { recursive: true }) + const target = path.join(directory, "history.json") + fs.writeFileSync(target, '{"pre":1}', "utf8") + const link = path.join(directory, "history-link.json") + fs.symlinkSync("history.json", link) + const ledger = watchLibraryTimers() + let releaseFirst: (() => Promise) | null = null + let releaseSecond: (() => Promise) | null = null + try { + releaseFirst = await acquireFileLock(link, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + expect(ledger.outstanding()).toBe(1) + expect(ledger.delays).toContain(10000) + const nextTarget = path.join(directory, "history.json.next") + fs.writeFileSync(nextTarget, '{"replaced":1}', "utf8") + const nextLink = path.join(directory, "history-link.json.next") + fs.symlinkSync("history.json.next", nextLink) + fs.renameSync(nextLink, link) + expect(fs.realpathSync(link)).toBe(nextTarget) + // The other half of acquire-after-replacement: the replacement moved the referent, so the + // volume now spells the leaf differently, so the process that arrives second is admitted on + // its own artefact while the first lock is still held. Both renewals are outstanding at the + // same time here, and both releases have to let go of their own. + releaseSecond = await acquireFileLock(link, { immediate: true }) + expect(artefactsOf(directory)).toEqual(["history.json.lock", "history.json.next.lock"]) + expect(ledger.outstanding()).toBe(2) + // The second lock is a directory on a volume, not bookkeeping: a third arrival at the new + // target itself is refused on the artefact the second lock armed. + await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) + await releaseSecond() + releaseSecond = null + expect(ledger.outstanding()).toBe(1) + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + await releaseFirst() + releaseFirst = null + expect(ledger.cancelled()).toBe(ledger.armed()) + expect(ledger.outstanding()).toBe(0) + expect(artefactsOf(directory)).toEqual([]) + } finally { + ledger.restore() + if (releaseFirst !== null) { + await releaseFirst() + } + if (releaseSecond !== null) { + await releaseSecond() + } + } + }, + ) +}) From 9d21fc309f41ae7fdeb8ab9d0c8efa979d8ef9b4 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Wed, 11 Nov 2026 23:28:29 +0800 Subject: [PATCH 13/22] test(utils): assert the shared lock record the identity key gives, not a pairing it never promised The ubuntu coverage leg failed this row with "Lock is not acquired/owned by you" thrown from the row itself, frame lockfile.js:285 reached through fileLock.test.ts:1669, and the assertion the row had expected to fail never appeared because a throw inside finally replaces the error already propagating. The release was the compensating failure, not the first one. The cause is the pairing, not the product. canonicalLockKey keys on dev:ino of the nearest existing directory and carries the leaf as the caller wrote it, so the referent a link points at never enters the key; lockArtefactPath names the artefact by realpath of the leaf, so replacing the link target moves the artefact name and leaves the key where it was. proper-lockfile keeps one in-process record per key - it assigns locks[file] with no guard at lockfile.js:243 and deletes it unconditionally at :290 - so the second arrival on the same spelling replaces the first holder record instead of taking a second one. The row asserted two independently releasable records, which is what its comment claimed and the design never promised. The row now asserts what the identity key actually gives: two artefacts on one record, the third arrival refused on the second artefact, the second release landing and the first release throwing ENOTACQUIRED with its artefact left on a volume it can no longer name to the library. Every artefact-level assertion is kept, because those measured true. Releases go through a wrapper so a runner that can execute the row reports the first failure rather than the compensating one, and the renewal the refused release never reaches is cancelled in the finally instead of firing after the row ends against a deleted artefact. The same pairing measured against the real library outside any link: one key, artefacts history.json.lock then history.json.next.lock, second release clean, first release ENOTACQUIRED, artefact still on disk, one renewal still armed. On this box the row itself cannot run - it needs a file symlink and fs.symlinkSync returns EPERM here - so it skips and the assertions above are the library-level reproduction, not a local pass. Reproduced and verified locally: vitest misc leg on this file 29 passed 8 skipped, prettier --check clean, eslint --max-warnings=0 exit 0 with no suppression entry, tsc --noEmit exit 0. No --no-verify was used and no pre-commit or commit-msg hook exists in this checkout to run. Co-Authored-By: Claude --- src/utils/__tests__/fileLock.test.ts | 68 ++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 14 deletions(-) diff --git a/src/utils/__tests__/fileLock.test.ts b/src/utils/__tests__/fileLock.test.ts index b54ce070ea..98bfcb6f57 100644 --- a/src/utils/__tests__/fileLock.test.ts +++ b/src/utils/__tests__/fileLock.test.ts @@ -1145,6 +1145,7 @@ interface TimerLedger { outstanding(): number delays: number[] restore(): void + cancelOutstanding(): void } /** @@ -1190,6 +1191,15 @@ function watchLibraryTimers(): TimerLedger { cancelled: () => cancelled, outstanding: () => armed - cancelled, delays, + cancelOutstanding: () => { + // Handles that were cancelled on their own are already out of the set, so what is left here is + // exactly the renewals still armed, and each of them counts as cancelled when this clears it. + for (const handle of armedHandles) { + clearOriginal(handle) + cancelled += 1 + } + armedHandles.clear() + }, restore: () => { globalThis.setTimeout = setOriginal as typeof globalThis.setTimeout globalThis.clearTimeout = clearOriginal as typeof globalThis.clearTimeout @@ -1622,7 +1632,7 @@ describe("a replaced referent lets go both locks and the renewal timer", () => { }) itPosixLeaf( - "lets go both locks and the renewal timer when a link target is replaced under a held lock", + "a replaced link target shares one record, so the second release lands and the first throws ENOTACQUIRED", async () => { const directory = path.join(root(), "timer-link-replaced") fs.mkdirSync(directory, { recursive: true }) @@ -1631,8 +1641,31 @@ describe("a replaced referent lets go both locks and the renewal timer", () => { const link = path.join(directory, "history-link.json") fs.symlinkSync("history.json", link) const ledger = watchLibraryTimers() + // What the key consults, and what it does not, because the two part company here and that is the + // behaviour this row states. canonicalLockKey walks the path by basename and keys on dev:ino of the + // nearest directory that exists, so the leaf rides along as the string the caller wrote and the + // referent a link points at never enters the key. lockArtefactPath does consult the referent: it names + // the artefact by fs.realpathSync.native of the leaf, re-spelling only the final component. Replacing + // the link target therefore moves the artefact name and leaves the key where it was. The library keeps + // one in-process record per key - it assigns locks[file] with no guard at lockfile.js:243 and deletes + // it unconditionally at :290 - so the second arrival, arriving on the same spelling the first caller + // wrote, replaces the first holder's record instead of taking a second one. The artefacts really are + // two, as the rows below measure; the records are not, and this group's title holds only for the + // plain-file case above, where one referent means one record and both releases land. let releaseFirst: (() => Promise) | null = null let releaseSecond: (() => Promise) | null = null + // Releases are wrapped, and that is not cosmetics. A throw inside finally replaces the error already + // propagating, and at the head this row replaces an unwrapped release here threw ENOTACQUIRED over + // whatever the body had failed at, so the runner printed only the release frame at line 1669 and the + // first failure never appeared. Wrapped, the body's own failure is what a runner reports. + const releaseQuietly = async (release: () => Promise): Promise => { + try { + await release() + return null + } catch (releaseError) { + return releaseError instanceof Error ? releaseError : new Error(String(releaseError)) + } + } try { releaseFirst = await acquireFileLock(link, { immediate: true }) expect(artefactsOf(directory)).toEqual(["history.json.lock"]) @@ -1644,33 +1677,40 @@ describe("a replaced referent lets go both locks and the renewal timer", () => { fs.symlinkSync("history.json.next", nextLink) fs.renameSync(nextLink, link) expect(fs.realpathSync(link)).toBe(nextTarget) - // The other half of acquire-after-replacement: the replacement moved the referent, so the - // volume now spells the leaf differently, so the process that arrives second is admitted on - // its own artefact while the first lock is still held. Both renewals are outstanding at the - // same time here, and both releases have to let go of their own. + // The volume now spells the leaf differently, so a second arrival is admitted on its own artefact + // while the first holder's artefact is still there. releaseSecond = await acquireFileLock(link, { immediate: true }) expect(artefactsOf(directory)).toEqual(["history.json.lock", "history.json.next.lock"]) expect(ledger.outstanding()).toBe(2) - // The second lock is a directory on a volume, not bookkeeping: a third arrival at the new - // target itself is refused on the artefact the second lock armed. + // The second lock is a directory on a volume, not bookkeeping: a third arrival at the new target + // itself is refused on the artefact the second lock armed. await expect(acquireFileLock(target, { immediate: true })).rejects.toMatchObject({ code: "ELOCKED" }) - await releaseSecond() + // The record names the second arrival, so the second release is the one that lands. + expect(await releaseQuietly(releaseSecond)).toBeNull() releaseSecond = null + expect(artefactsOf(directory)).toEqual(["history.json.lock"]) + // The first holder has an artefact left on a volume it can no longer name to the library: its + // record was replaced by the second arrival and deleted by the second release, so its own release + // is refused with ENOTACQUIRED before it can clear its renewal timer, which is why one renewal is + // still outstanding after both holders have tried to let go. + const firstReleaseError = await releaseQuietly(releaseFirst) + expect(firstReleaseError).toMatchObject({ code: "ENOTACQUIRED" }) expect(ledger.outstanding()).toBe(1) expect(artefactsOf(directory)).toEqual(["history.json.lock"]) - await releaseFirst() releaseFirst = null - expect(ledger.cancelled()).toBe(ledger.armed()) - expect(ledger.outstanding()).toBe(0) - expect(artefactsOf(directory)).toEqual([]) } finally { ledger.restore() if (releaseFirst !== null) { - await releaseFirst() + await releaseQuietly(releaseFirst) } if (releaseSecond !== null) { - await releaseSecond() + await releaseQuietly(releaseSecond) } + // The refused release never reached the clearTimeout at lockfile.js:288, so its renewal timer is + // still armed and would fire after this row ends, utimes a deleted artefact and be reported + // compromised by a callback that rethrows outside any test. Cancelled here rather than left to the + // 10 second renewal to find out. + ledger.cancelOutstanding() } }, ) From f1a79dfb09ae824acb70d2b5377b7351bd086133 Mon Sep 17 00:00:00 2001 From: Eason Liang <136036952+easonLiangWorldedtech@users.noreply.github.com> Date: Thu, 12 Nov 2026 07:38:18 +0800 Subject: [PATCH 14/22] test(utils): load the production module in the cross-process child and gate the waits Four dispositions from comment 4543975553 on #2368, one per reviewed hunk. Root 4538510000 (Major, fileLock.test.ts:756). The child was plain CommonJS that restated the artefact rule and hardcoded a 31000 window, because plain node cannot load fileLock.ts: its extensionless ../core/task-persistence/persistenceTrace import fails with ERR_MODULE_NOT_FOUND. The parent now registers the repository's own tsx loader and runs the child as node --input-type=module --import -e