Skip to content

Commit 066f153

Browse files
fix(u5b): prove the lock key, sync created ancestors, and redact tie paths (#2357)
Review findings on this unit's own content, each with a row that fails without it: - fileLock: canonicalize each relative link referent against the link's real parent, so a writer through an alias and a writer through the referent contend for one key. - fileLock: a realpath failure that is not ENOENT/ENOTDIR means the canonical key is unknown, so propagate it rather than locking the caller's lexical spelling. Aligns the lock path with resolveLockKey, which already refuses to guess a key; the two rows that asserted the lexical fallback now assert the refusal. - fileLock: withFileLock re-derives the canonical key after acquiring the lock and, on a change, releases, retakes for the current key, and only then runs the callback. - safeWriteText: fsync every parent directory mkdir had to create (plus the directory that links them in), not just the immediate parent, so a crash cannot drop an ancestor and take the published file with it. Driven off the path mkdir reports, so no extra stat. - safeWriteText: pre-commit ancestor revalidation compares against the location the caller authorized (DirectoryIdentity.resolvedPath) so a stable symlink alias passes while a re-pointed alias still fails. - safeWriteText: correct the backup contract (post-commit failures publish, they do not roll back) and the DACL-save comment (a successful dump is kept and restored, not refused). - jsonFileRecovery: AmbiguousBackupRecencyError names basenames in its message so error telemetry cannot carry workspace paths; the full paths stay on the properties. Tests: relative-referent, inspection-failure, and lock-retarget rows; missing-referent row now walks the absent referent; tied-backup rows for a tie below the winner, for the reader entry point, and for message redaction; post-commit durability + unremovable backup row asserting contentPublished true with a PostCommitDurabilityError cause; created-ancestor fsync order plus the Windows namespace-marker mapping; alias-ancestor accept and refuse pair; Task generation row for the disposal an unmocked abort performs.
1 parent 956208e commit 066f153

7 files changed

Lines changed: 532 additions & 56 deletions

File tree

‎src/core/task/__tests__/Task.spec.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4819,6 +4819,30 @@ describe("Cline", () => {
48194819
expect(task.cancellationGeneration).toBe(1)
48204820
})
48214821

4822+
it("advances the cancellation generation for the disposal an unmocked abort performs", async () => {
4823+
// The two rows above mock dispose(), so each proves one increment in isolation. The
4824+
// sequence the guarded-write fence actually sees is an abort that tears the task down:
4825+
// requestAbort raises the fence, and the dispose() that abortTaskOnce drives raises it
4826+
// again. Nothing is mocked here, so if either increment stopped landing - or if disposal
4827+
// stopped being part of an abort - this row reads the stale value.
4828+
const task = new Task({
4829+
provider: mockProvider,
4830+
apiConfiguration: mockApiConfig,
4831+
task: "test task",
4832+
startTask: false,
4833+
})
4834+
4835+
expect(task.cancellationGeneration).toBe(0)
4836+
4837+
await task.abortTask()
4838+
4839+
expect(task.abort).toBe(true)
4840+
// Disposal never marks a task abandoned; only an explicit abandon does.
4841+
expect(task.abandoned).toBe(false)
4842+
// One from requestAbort, one from the disposal the abort performed.
4843+
expect(task.cancellationGeneration).toBe(2)
4844+
})
4845+
48224846
it("flushes pending state before TaskAborted and disposal while queue state is intact", async () => {
48234847
const task = new Task({
48244848
provider: mockProvider,

‎src/services/file-safety/__tests__/safeWriteText.spec.ts‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1588,6 +1588,169 @@ describe("safeWriteText", () => {
15881588
expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath)
15891589
})
15901590

1591+
it("publishes when a pinned ancestor is a stable symlink alias", async () => {
1592+
// A caller that authorized a chain running THROUGH an alias records the alias spelling as
1593+
// dir and the location that alias resolves to as resolvedPath. The alias's realpath differs
1594+
// from dir by definition while nothing moved, so comparing realpath(dir) against dir alone
1595+
// refused a write whose ancestry and target never changed. The (dev, ino) check is what
1596+
// still catches the alias being re-pointed; this row is the control on that.
1597+
const aliasDir = path.resolve("/tmp/alias-dir")
1598+
const realDir = path.resolve("/tmp/real-dir")
1599+
const targetPath = path.join(aliasDir, "target.txt")
1600+
vi.mocked(fs.realpath).mockImplementation(async (p: unknown) =>
1601+
path.resolve(String(p)) === aliasDir ? realDir : targetPath,
1602+
)
1603+
vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n))
1604+
vi.mocked(fs.rename).mockClear()
1605+
vi.mocked(fs.link).mockClear()
1606+
1607+
await safeWriteText(targetPath, "new data", {
1608+
expectedResolvedPath: targetPath,
1609+
expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: realDir }],
1610+
platform: "linux",
1611+
})
1612+
1613+
expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath)
1614+
})
1615+
1616+
it("refuses the publish when a pinned alias no longer resolves to the authorized location", async () => {
1617+
// resolvedPath has to stay a comparison, not an escape hatch: an alias re-pointed to a third
1618+
// location resolves to neither the location it was authorized against nor its own spelling,
1619+
// and the commit must stop there instead of publishing through the new link.
1620+
const aliasDir = path.resolve("/tmp/alias-dir")
1621+
const authorizedLocation = path.resolve("/tmp/real-dir")
1622+
const repointedTo = path.resolve("/tmp/elsewhere-dir")
1623+
const targetPath = path.join(aliasDir, "target.txt")
1624+
vi.mocked(fs.realpath).mockImplementation(async (p: unknown) =>
1625+
path.resolve(String(p)) === aliasDir ? repointedTo : targetPath,
1626+
)
1627+
vi.mocked(fs.stat).mockResolvedValue(_dirIdentity(100n))
1628+
vi.mocked(fs.rename).mockClear()
1629+
vi.mocked(fs.link).mockClear()
1630+
1631+
const error = await safeWriteText(targetPath, "new data", {
1632+
expectedResolvedPath: targetPath,
1633+
expectedAncestorIdentities: [{ dir: aliasDir, dev: 1n, ino: 100n, resolvedPath: authorizedLocation }],
1634+
platform: "linux",
1635+
}).catch((caught: unknown) => caught)
1636+
1637+
expect(error).toBeInstanceOf(AncestorReplacedError)
1638+
expect((error as AncestorReplacedError).message).toContain("no longer resolves to the authorized location")
1639+
expect(fs.rename).not.toHaveBeenCalled()
1640+
expect(fs.link).not.toHaveBeenCalled()
1641+
})
1642+
1643+
it("fsyncs every parent directory it had to create, not only the target's immediate parent", async () => {
1644+
// The commit rename makes the entry INSIDE the immediate parent durable. A grandparent this
1645+
// call created is itself an entry in ITS parent, so syncing only the immediate parent leaves
1646+
// the newer ancestors unsynced: a crash can drop the chain and take the published file with
1647+
// it. The double reports the two nested components as created, which is what mkdir answers
1648+
// on the real filesystem, so the sync order is observable: deepest first, ending with the
1649+
// directory that holds the outermost new entry. Only directories are opened with "r", so
1650+
// the calls below are directory syncs and nothing else.
1651+
const root = path.resolve("/tmp/test-dir")
1652+
const nested = path.join(root, "nested")
1653+
const deep = path.join(nested, "deep")
1654+
const targetPath = path.join(deep, "target.txt")
1655+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1656+
// The outermost component mkdir had to create, in the spelling Node answers with.
1657+
vi.mocked(fs.mkdir).mockResolvedValue(nested)
1658+
vi.mocked(fsSync.openSync).mockClear()
1659+
1660+
await safeWriteText(targetPath, "new data", { platform: "linux" })
1661+
1662+
const dirSyncs = vi
1663+
.mocked(fsSync.openSync)
1664+
.mock.calls.filter(function (call: unknown[]) {
1665+
return call[1] === "r"
1666+
})
1667+
.map(function (call: unknown[]) {
1668+
return String(call[0])
1669+
})
1670+
expect(dirSyncs).toEqual([deep, nested, root])
1671+
})
1672+
1673+
it("maps the namespace marker Windows reports for the directory it created", async () => {
1674+
// Windows answers mkdir with the created directory under the extended-length namespace,
1675+
// a different spelling from the one the write works in. The chain that decides which
1676+
// directories to fsync has to match the two, or the new ancestors go unsynced on exactly
1677+
// the platform that reports it this way - and the write still claims durability it did not
1678+
// get. The row builds the reported spelling from the same path the write resolved, so it
1679+
// asserts the mapping on both platforms.
1680+
const nested = path.resolve("C:/test-dir/nested")
1681+
const deep = path.join(nested, "deep")
1682+
const targetPath = path.join(deep, "target.txt")
1683+
const stripped = nested.startsWith("/") ? nested.slice(1) : nested
1684+
const reported = "\\\\?\\" + stripped.split("/").join("\\")
1685+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1686+
vi.mocked(fs.mkdir).mockResolvedValue(reported)
1687+
vi.mocked(fsSync.openSync).mockClear()
1688+
1689+
await safeWriteText(targetPath, "new data", { platform: "linux" })
1690+
1691+
const dirSyncs = vi
1692+
.mocked(fsSync.openSync)
1693+
.mock.calls.filter(function (call: unknown[]) {
1694+
return call[1] === "r"
1695+
})
1696+
.map(function (call: unknown[]) {
1697+
return String(call[0])
1698+
})
1699+
// The marker had to map onto the write's own paths: nothing under the marker is synced.
1700+
expect(dirSyncs).toEqual([deep, nested, path.dirname(nested)])
1701+
expect(
1702+
dirSyncs.some(function (p: string) {
1703+
return p.includes("?")
1704+
}),
1705+
).toBe(false)
1706+
})
1707+
1708+
it("reports a post-commit durability failure together with the backup it cannot remove", async () => {
1709+
// The commit rename succeeded and then the parent-directory fsync failed. Nothing is rolled
1710+
// back - the published bytes stay at the target - and the failure path still removes the
1711+
// backup. When that removal also fails the caller gets both facts: contentPublished says the
1712+
// leftover is stale beside published content, and originalError names the durability failure.
1713+
const targetPath = "/tmp/test-dir/target.txt"
1714+
const eio = Object.assign(new Error("EIO"), { code: "EIO" })
1715+
vi.mocked(fs.realpath).mockResolvedValue(targetPath)
1716+
// Only directories are opened with "r", so this fd marks the post-commit directory sync:
1717+
// the failure lands exactly after the rename instead of on the staged file's fsync.
1718+
vi.mocked(fsSync.openSync).mockImplementation(function (p: unknown, flags?: unknown): number {
1719+
return flags === "r" ? 77 : 1
1720+
})
1721+
vi.mocked(fsSync.fsyncSync).mockImplementation(function (fd: number): void {
1722+
if (fd === 77) {
1723+
throw eio
1724+
}
1725+
})
1726+
vi.mocked(fs.unlink).mockImplementation(async (p: unknown) => {
1727+
if (String(p).includes("safeWriteText.bak_")) {
1728+
throw Object.assign(new Error("EPERM"), { code: "EPERM" })
1729+
}
1730+
})
1731+
vi.mocked(fs.rename).mockClear()
1732+
1733+
const error = await safeWriteText(targetPath, "new data", {
1734+
backup: true,
1735+
platform: "linux",
1736+
}).catch((caught: unknown) => caught)
1737+
1738+
expect(error).toBeInstanceOf(OrphanedBackupAfterFailedWriteError)
1739+
const orphan = error as OrphanedBackupAfterFailedWriteError
1740+
// The commit ran: the durability failure is downstream of the rename, not before it.
1741+
expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText"), targetPath)
1742+
expect(orphan.contentPublished).toBe(true)
1743+
expect(orphan.originalError).toBeInstanceOf(PostCommitDurabilityError)
1744+
expect((orphan.cleanupError as Error).message).toBe("EPERM")
1745+
expect(orphan.message).toContain("the target holds the new content")
1746+
// Both removal attempts ran, and the failure path still cleaned what it owned.
1747+
const backupUnlinks = vi.mocked(fs.unlink).mock.calls.filter(function (call: unknown[]) {
1748+
return typeof call[0] === "string" && call[0].includes("safeWriteText.bak_")
1749+
})
1750+
expect(backupUnlinks).toHaveLength(2)
1751+
expect(fs.rmdir).toHaveBeenCalled()
1752+
})
1753+
15911754
it("refuses the publish when an authorized ancestor disappears before the commit", async () => {
15921755
const dir = path.resolve("/tmp/test-dir")
15931756
const targetPath = path.join(dir, "target.txt")

‎src/services/file-safety/safeWriteText.ts‎

Lines changed: 88 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,13 @@ export interface SafeWriteTextOptions {
1414
* a rollback source - nothing is restored on failure, because the copy never
1515
* displaced the target: before the commit the target still holds its previous
1616
* content, and after it the target holds the new content and this call removes
17-
* the copy, reporting it as OrphanedBackupAfterFailedWriteError if the removal
18-
* itself fails. When false (default) the atomic rename simply replaces the
19-
* target -- crash-safe window is zero.
17+
* the copy. A removal that fails AFTER the commit reports OrphanedPublishedBackupError
18+
* and leaves the new content at the target: nothing is rolled back, because rolling back
19+
* would replace published bytes with an older copy the caller never asked to restore. A
20+
* removal that fails after a write that never committed reports
21+
* OrphanedBackupAfterFailedWriteError, whose contentPublished says which of the two
22+
* happened. When false (default) the atomic rename simply replaces the target --
23+
* crash-safe window is zero.
2024
*/
2125
backup?: boolean
2226

@@ -74,8 +78,9 @@ export interface SafeWriteTextOptions {
7478
* The identity check is paired with a realpath comparison: moving a directory
7579
* preserves (dev, ino), and replacing its old name with a symlink to the moved
7680
* location keeps stat() matching while sending the commit to the new location.
77-
* The name must still resolve to the authorized location, not merely to the
78-
* same inode.
81+
* The name must still resolve to the location it was authorized against - the
82+
* recorded resolvedPath when the caller walked a symlink alias, and dir itself
83+
* when it recorded a plain spelling - not merely to the same inode.
7984
*/
8085
expectedAncestorIdentities?: DirectoryIdentity[]
8186
}
@@ -85,6 +90,16 @@ export type DirectoryIdentity = {
8590
dir: string
8691
dev: bigint
8792
ino: bigint
93+
/**
94+
* Where `dir` resolved to when this identity was taken (its realpath).
95+
*
96+
* A caller that authorized a chain running THROUGH a symlink alias records the alias
97+
* spelling as `dir`; that alias's realpath legitimately differs from `dir` while nothing
98+
* moved, so comparing the current realpath against `dir` alone refuses a write whose
99+
* ancestry never changed. The pre-commit revalidation compares against this value when it
100+
* is present, and against `dir` when it is not.
101+
*/
102+
resolvedPath?: string
88103
}
89104

90105
/**
@@ -306,6 +321,46 @@ export class AncestorReplacedError extends Error {
306321
}
307322
// -- helpers ---------------------------------------------------------------
308323

324+
/** fsync one directory so the entry it holds (a rename, or a newly created child) is durable. */
325+
function _syncDirectory(dir: string): void {
326+
const dirFd = fsSync.openSync(dir, "r")
327+
try {
328+
fsSync.fsyncSync(dirFd)
329+
} finally {
330+
fsSync.closeSync(dirFd)
331+
}
332+
}
333+
334+
/**
335+
* The directories *mkdir(recursive:true)* had to create for *dirPath*, outermost first.
336+
*
337+
* Node reports the outermost component it created - or nothing when the path already existed -
338+
* and that answer is the whole input, so no extra stat is needed to learn what appeared. The
339+
* commit rename only makes the entry INSIDE the immediate parent durable, and every newly
340+
* created directory is itself an entry in its own parent, so step 4b fsyncs this chain (deepest
341+
* first, after the immediate parent) and then the directory that first links it into the tree;
342+
* otherwise a crash can drop an ancestor and with it the published file.
343+
*
344+
* On Windows the reported path carries the extended-length namespace marker, which is stripped
345+
* so the chain compares in the spelling the write itself works in. An answer that is not on
346+
* this path yields nothing, rather than syncing directories this write cannot place.
347+
*/
348+
function _createdAncestorChain(createdRoot: string | undefined, dirPath: string): string[] {
349+
if (typeof createdRoot !== "string") return []
350+
const namespacePrefix = "\\\\?\\"
351+
const unprefixed = createdRoot.startsWith(namespacePrefix) ? createdRoot.slice(namespacePrefix.length) : createdRoot
352+
const root = path.resolve(unprefixed)
353+
const chain: string[] = []
354+
let cursor = dirPath
355+
for (;;) {
356+
chain.push(cursor)
357+
if (cursor === root) return chain.reverse()
358+
const parent = path.dirname(cursor)
359+
if (parent === cursor) return []
360+
cursor = parent
361+
}
362+
}
363+
309364
/** Generate a unique temp file name in the given directory. */
310365
function _tempName(dir: string, prefix: string): string {
311366
return path.join(dir, "." + prefix + "_" + Date.now() + "_" + Math.random().toString(36).substring(2) + ".tmp")
@@ -332,10 +387,11 @@ function _stagingDir(dir: string): string {
332387
}
333388

334389
/** Save the DACL of *srcPath* to a dump file on Windows.
335-
* Returns null when the dump was written, and the runner's error when it was not: the caller
336-
* refuses the publish either way and has to be able to say which failure it is refusing -
337-
* "icacls ran and failed" and "icacls could not be started at all" are different facts to act
338-
* on. Never throws. */
390+
* Returns null when the dump was written - the caller keeps it and restores it onto the
391+
* committed file at step 5 - and returns the runner's error when it was not, because the
392+
* caller refuses the publish in that case and has to be able to say which failure it is
393+
* refusing: "icacls ran and failed" and "icacls could not be started at all" are different
394+
* facts to act on. Never throws. */
339395
async function _saveDaclWindows(srcPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise<unknown> {
340396
const runner = execFileRunner ?? execFile
341397
try {
@@ -505,8 +561,10 @@ export async function safeWriteText(
505561

506562
const dirPath = path.dirname(targetPath)
507563

508-
// Ensure parent directory exists (mirrors safeWriteJson behaviour).
509-
await fs.mkdir(dirPath, { recursive: true })
564+
// Ensure parent directory exists (mirrors safeWriteJson behaviour). What mkdir reports it
565+
// created feeds step 4b's fsync of the ancestors this write introduced; see
566+
// _createdAncestorChain.
567+
const createdAncestors = _createdAncestorChain(await fs.mkdir(dirPath, { recursive: true }), dirPath)
510568
await fs.access(dirPath)
511569

512570
// Create the staging directory only when we generate the temp file there;
@@ -741,7 +799,14 @@ export async function safeWriteText(
741799
}
742800
throw error
743801
})
744-
if (resolvedDir === undefined || path.resolve(resolvedDir) !== path.resolve(expected.dir)) {
802+
// The location the caller authorized. A recorded resolvedPath is the spelling the
803+
// caller walked - an alias ancestor resolves to something else by definition, and a
804+
// stable alias must pass here; the (dev, ino) check above is what catches the alias
805+
// being re-pointed. Without a resolvedPath the authorized name is the lexical dir.
806+
const authorizedLocation = expected.resolvedPath
807+
? path.resolve(expected.resolvedPath)
808+
: path.resolve(expected.dir)
809+
if (resolvedDir === undefined || path.resolve(resolvedDir) !== authorizedLocation) {
745810
throw new AncestorReplacedError(expected.dir, "no longer resolves to the authorized location")
746811
}
747812
}
@@ -877,11 +942,17 @@ export async function safeWriteText(
877942
// changed by the commit rename is durable, not just the file content.
878943
if (platform !== "win32") {
879944
try {
880-
const dirFd = fsSync.openSync(dirPath, "r")
881-
try {
882-
fsSync.fsyncSync(dirFd)
883-
} finally {
884-
fsSync.closeSync(dirFd)
945+
_syncDirectory(dirPath)
946+
// The rename above made the entry INSIDE dirPath durable. A parent this call had to
947+
// create is itself an entry in its own parent, so syncing only the immediate parent
948+
// leaves the newer ancestors unsynced and a crash can remove the chain - taking the
949+
// published file with it. Sync deepest-first, ending with the pre-existing directory
950+
// that holds the outermost new entry.
951+
for (let i = createdAncestors.length - 2; i >= 0; i--) {
952+
_syncDirectory(createdAncestors[i])
953+
}
954+
if (createdAncestors.length > 0) {
955+
_syncDirectory(path.dirname(createdAncestors[0]))
885956
}
886957
} catch (error: unknown) {
887958
// The content rename committed, but the directory entry that

0 commit comments

Comments
 (0)