agentera 3.0.0-dev.39 → 3.0.0-dev.41

package/dist/state/entityPublicationContext.js

@@ -1,128 +1,241 @@
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { ExactReplacementConflictError, FileReplacementError } from "./exactReplacementRecovery.js";
 import { assertValidatedProjectRoot } from "./projectRoot.js";
-import { reject } from "./write/errors.js";
-const DIRECTORY_FLAGS = fs.constants.O_RDONLY
-    | (fs.constants.O_DIRECTORY ?? 0)
-    | (fs.constants.O_NOFOLLOW ?? 0);
-const FILE_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
+import { reject, StateWriteInputError } from "./write/errors.js";
 const RECOVERY_IGNORE_BYTES = "*\n!.gitignore\n";
-function samePublished(left, right) {
-    return left.dev === right.dev
-        && left.ino === right.ino
-        && left.type === right.type
-        && left.size === right.size
-        && left.sha256 === right.sha256;
-}
-function fdPath(fd, name) {
-    return name ? `/proc/self/fd/${fd}/${name}` : `/proc/self/fd/${fd}`;
-}
+export const FILE_REPLACEMENT_RECOVERY_VERSION = "agentera.fileReplacementRecovery.v1";
+export const FILE_REPLACEMENT_METADATA_NAME = "replacement.json";
 function identity(stat) {
     return {
         dev: stat.dev,
         ino: stat.ino,
+        type: stat.mode & BigInt(fs.constants.S_IFMT),
         size: stat.size,
         mtimeNs: stat.mtimeNs,
         ctimeNs: stat.ctimeNs,
         nlink: stat.nlink,
+        mode: stat.mode,
     };
 }
-function sameObject(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
 function sameIdentity(left, right) {
     return left.dev === right.dev
         && left.ino === right.ino
+        && left.type === right.type
         && left.size === right.size
         && left.mtimeNs === right.mtimeNs
         && left.ctimeNs === right.ctimeNs
         && left.nlink === right.nlink;
 }
-function readDescriptor(fd) {
-    const stat = fs.fstatSync(fd, { bigint: true });
-    if (!stat.isFile() || stat.size > BigInt(Number.MAX_SAFE_INTEGER)) {
-        throw new Error("state mode marker descriptor is not a readable regular file");
-    }
-    const bytes = Buffer.alloc(Number(stat.size));
-    let offset = 0;
-    while (offset < bytes.length) {
-        const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
-        if (count === 0)
-            break;
-        offset += count;
-    }
-    if (offset !== bytes.length)
-        throw new Error("state mode marker changed while its exact bytes were read");
-    return bytes;
+function sameDirectory(left, right) {
+    return right.isDirectory()
+        && !right.isSymbolicLink()
+        && left.dev === right.dev
+        && left.ino === right.ino;
 }
-function publishedIdentity(fd) {
-    const stat = fs.fstatSync(fd, { bigint: true });
-    const bytes = readDescriptor(fd);
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function publishedIdentity(file) {
     return {
-        dev: stat.dev,
-        ino: stat.ino,
-        type: stat.mode & BigInt(fs.constants.S_IFMT),
-        size: stat.size,
-        sha256: createHash("sha256").update(bytes).digest("hex"),
+        dev: file.identity.dev,
+        ino: file.identity.ino,
+        type: file.identity.type,
+        size: file.identity.size,
+        sha256: sha256(file.bytes),
     };
 }
-function matchesPublished(fd, expected) {
-    const stat = fs.fstatSync(fd, { bigint: true });
-    if (stat.dev !== expected.dev
-        || stat.ino !== expected.ino
-        || (stat.mode & BigInt(fs.constants.S_IFMT)) !== expected.type
-        || stat.size !== expected.size)
-        return false;
-    return createHash("sha256").update(readDescriptor(fd)).digest("hex") === expected.sha256;
+function matchesPublished(file, expected) {
+    const observed = publishedIdentity(file);
+    return observed.dev === expected.dev
+        && observed.ino === expected.ino
+        && observed.type === expected.type
+        && observed.size === expected.size
+        && observed.sha256 === expected.sha256;
+}
+function matchesExpected(file, expected) {
+    return Buffer.isBuffer(expected) ? file.bytes.equals(expected) : matchesPublished(file, expected);
 }
-function matchesExpected(fd, expected) {
-    return Buffer.isBuffer(expected) ? readDescriptor(fd).equals(expected) : matchesPublished(fd, expected);
+function sameStableFile(left, right) {
+    return sameIdentity(left.identity, right.identity) && left.bytes.equals(right.bytes);
 }
-function openMatches(parentFd, name, expectedFd, flags) {
-    let observed;
+function readStableFile(absolute, label) {
+    let before;
     try {
-        observed = fs.openSync(fdPath(parentFd, name), flags);
-        return sameObject(fs.fstatSync(observed, { bigint: true }), fs.fstatSync(expectedFd, { bigint: true }));
+        before = fs.lstatSync(absolute, { bigint: true });
     }
-    catch {
-        return false;
+    catch (error) {
+        throw new Error(`${label} is unavailable: ${error.message}`, { cause: error });
+    }
+    if (!before.isFile() || before.isSymbolicLink()) {
+        throw new Error(`${label} is not a safe regular file`);
+    }
+    let descriptor;
+    try {
+        descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        const opened = fs.fstatSync(descriptor, { bigint: true });
+        if (!opened.isFile() || opened.isSymbolicLink() || opened.dev !== before.dev || opened.ino !== before.ino) {
+            throw new Error(`${label} changed while it was opened`);
+        }
+        const bytes = fs.readFileSync(descriptor);
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        const pathname = fs.lstatSync(absolute, { bigint: true });
+        const openedIdentity = identity(opened);
+        if (!sameIdentity(openedIdentity, identity(after))
+            || !sameIdentity(openedIdentity, identity(pathname))
+            || BigInt(bytes.length) !== opened.size)
+            throw new Error(`${label} changed while its exact bytes were read`);
+        return { absolute, identity: identity(after), bytes };
     }
     finally {
-        if (observed !== undefined)
-            fs.closeSync(observed);
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
     }
 }
-function entryExists(parentFd, name) {
-    let fd;
+function readFileIfPresent(absolute, label) {
     try {
-        fd = fs.openSync(fdPath(parentFd, name), FILE_FLAGS);
-        return true;
+        fs.lstatSync(absolute);
     }
     catch (error) {
-        return error.code !== "ENOENT";
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return readStableFile(absolute, label);
+}
+function readStableDirectory(absolute, created = false) {
+    const stat = fs.lstatSync(absolute, { bigint: true });
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`publication directory '${absolute}' is not a safe real directory`);
+    }
+    return { absolute, dev: stat.dev, ino: stat.ino, created };
+}
+function projectLocalPath(root, absolute, allowRoot = false) {
+    const resolved = path.resolve(absolute);
+    const relative = path.relative(root.path, resolved);
+    return resolved === absolute
+        && (allowRoot || relative.length > 0)
+        && relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}
+/** Validate a recovery directory before listing or mutating anything through it. */
+export function validateEntityRecoveryDirectory(root, absolute, targetDirectory, label, expected) {
+    assertValidatedProjectRoot(root);
+    if (!projectLocalPath(root, absolute) || !projectLocalPath(root, targetDirectory, true)) {
+        throw new FileReplacementError(`${label} must be a real project-local directory under the validated project root`);
+    }
+    let directory;
+    let target;
+    try {
+        directory = readStableDirectory(absolute);
+        target = readStableDirectory(targetDirectory);
+        if (fs.realpathSync(absolute) !== absolute || fs.realpathSync(targetDirectory) !== targetDirectory) {
+            throw new Error("a directory path traverses a symbolic link");
+        }
+    }
+    catch (error) {
+        throw new FileReplacementError(`${label} must be a real project-local non-symlink directory: ${error.message}`, error);
+    }
+    if (typeof process.getuid === "function") {
+        const stat = fs.lstatSync(directory.absolute, { bigint: true });
+        if ((stat.mode & 18n) !== 0n || stat.uid !== BigInt(process.getuid())) {
+            throw new FileReplacementError(`${label} must be owned by the current user and not group/world-writable`);
+        }
+    }
+    if (directory.dev !== target.dev) {
+        throw new FileReplacementError(`${label} must share the replacement target filesystem`);
+    }
+    if (expected && (directory.absolute !== expected.absolute
+        || directory.dev !== expected.dev
+        || directory.ino !== expected.ino)) {
+        throw new FileReplacementError(`${label} changed after its recovery boundary was validated`);
+    }
+    return { absolute: directory.absolute, dev: directory.dev, ino: directory.ino };
+}
+function syncDirectory(absolute) {
+    if (process.platform === "win32")
+        return;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_DIRECTORY ?? 0));
+        fs.fsyncSync(descriptor);
+    }
+    catch (error) {
+        if (!["EINVAL", "ENOTSUP", "ENOSYS"].includes(error.code ?? ""))
+            throw error;
     }
     finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
     }
 }
-function pathBytesEqual(parentFd, name, expected) {
-    let fd;
+function syncDirectoryBestEffort(absolute) {
     try {
-        fd = fs.openSync(fdPath(parentFd, name), FILE_FLAGS);
-        return readDescriptor(fd).equals(expected);
+        syncDirectory(absolute);
     }
-    catch {
+    catch { /* The canonical rename already linearized. */ }
+}
+function safeSegments(relativeTarget, label) {
+    const segments = relativeTarget.split(/[\\/]/).filter(Boolean);
+    if (segments.length < 1
+        || path.posix.isAbsolute(relativeTarget)
+        || path.win32.isAbsolute(relativeTarget)
+        || relativeTarget.includes("\0")
+        || segments.includes("..")
+        || segments.includes("."))
+        reject({
+            class: "unsupported_target",
+            message: `${label} '${relativeTarget}' is outside the validated project path grammar`,
+            recovery: "Use one project-relative path without symbolic, dot, parent, drive, UNC, or absolute segments; no state was changed.",
+        });
+    return segments;
+}
+function relativeDisplay(root, absolute) {
+    return path.relative(root, absolute).split(path.sep).join("/");
+}
+function removeExactFile(file) {
+    const current = readFileIfPresent(file.absolute, `attempt-owned file '${file.absolute}'`);
+    if (!current || !sameStableFile(file, current))
         return false;
+    fs.unlinkSync(file.absolute);
+    return true;
+}
+function createDurableFile(absolute, bytes, mode = 0o600) {
+    let descriptor;
+    let opened;
+    try {
+        descriptor = fs.openSync(absolute, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), mode);
+        opened = identity(fs.fstatSync(descriptor, { bigint: true }));
+        fs.writeFileSync(descriptor, bytes);
+        if (typeof process.getuid === "function")
+            fs.fchmodSync(descriptor, mode);
+        fs.fsyncSync(descriptor);
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch { /* Preserve the primary failure. */ }
+            descriptor = undefined;
+        }
+        if (opened) {
+            try {
+                const current = readFileIfPresent(absolute, `failed stage '${absolute}'`);
+                if (current && sameIdentity(opened, current.identity))
+                    fs.unlinkSync(absolute);
+            }
+            catch { /* Preserve changed or partially inspectable attempt state. */ }
+        }
+        throw error;
     }
     finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
     }
-}
-function syncDirectory(fd) {
-    fs.fsyncSync(fd);
+    return readStableFile(absolute, `durable stage '${absolute}'`);
 }
 function publicationConflict(markerPath) {
     reject({
@@ -133,65 +246,28 @@ function publicationConflict(markerPath) {
     });
 }
 /**
- * Pins one entity write to the root and exact valid marker selected by mode
- * detection. Node cannot combine pathname validation and mutation atomically,
- * so publication uses held directory descriptors, validates before and after
- * every observable boundary, and rolls back only links and empty directories
- * whose descriptor identities still match this attempt. Success linearizes at
- * the final root, marker, directory-chain, and target validation.
+ * Binds mutations to a validated project and exact entity-mode marker. Every
+ * pathname and byte identity is checked at declared boundaries. Publication
+ * linearizes through standard complete-file link or rename operations; a
+ * non-cooperating writer that races after the final successful check is outside
+ * the contract and is not represented as a cross-process compare-and-swap.
  */
 export class EntityPublicationContext {
     projectRoot;
     validatedRoot;
     markerPath;
-    rootFd;
-    markerParentEntries;
-    markerFd;
-    markerIdentity;
-    markerBytes;
+    marker;
     createdDirectories = new Map();
     closed = false;
     constructor(root, markerPath, expectedBytes) {
         this.projectRoot = root.path;
         this.validatedRoot = root;
         this.markerPath = markerPath;
-        this.markerBytes = Buffer.from(expectedBytes);
-        this.rootFd = fs.openSync(root.path, DIRECTORY_FLAGS);
-        this.markerParentEntries = [];
-        let markerFd;
-        try {
-            const rootStat = fs.fstatSync(this.rootFd, { bigint: true });
-            const rootIdentity = root.identities.at(-1);
-            if (rootStat.dev !== rootIdentity.dev || rootStat.ino !== rootIdentity.ino) {
-                throw new Error(`project root '${root.path}' changed while its publication context was opened`);
-            }
-            const segments = markerPath.split("/").filter(Boolean);
-            let parentFd = this.rootFd;
-            for (const name of segments.slice(0, -1)) {
-                const fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
-                this.markerParentEntries.push({ parentFd, name, fd, created: false });
-                parentFd = fd;
-            }
-            markerFd = fs.openSync(fdPath(parentFd, segments.at(-1)), FILE_FLAGS);
-            const before = fs.fstatSync(markerFd, { bigint: true });
-            const bytes = readDescriptor(markerFd);
-            const after = fs.fstatSync(markerFd, { bigint: true });
-            if (!before.isFile() || !sameIdentity(identity(before), after) || !bytes.equals(expectedBytes)) {
-                publicationConflict(markerPath);
-            }
-            this.markerFd = markerFd;
-            this.markerIdentity = identity(after);
-            this.assertValid();
-            markerFd = undefined;
-        }
-        catch (error) {
-            if (markerFd !== undefined)
-                fs.closeSync(markerFd);
-            for (const entry of this.markerParentEntries.reverse())
-                fs.closeSync(entry.fd);
-            fs.closeSync(this.rootFd);
-            throw error;
-        }
+        const markerAbsolute = path.join(root.path, ...safeSegments(markerPath, "state mode marker"));
+        this.marker = readStableFile(markerAbsolute, `state mode marker '${markerPath}'`);
+        if (!this.marker.bytes.equals(expectedBytes))
+            publicationConflict(markerPath);
+        this.assertValid();
     }
     static open(root, markerPath, expectedBytes) {
         return new EntityPublicationContext(root, markerPath, expectedBytes);
@@ -199,500 +275,421 @@ export class EntityPublicationContext {
     pinnedPath(relativePath = "") {
         if (this.closed)
             throw new Error("entity publication context is closed");
-        return relativePath ? path.join(fdPath(this.rootFd), relativePath) : fdPath(this.rootFd);
+        if (!relativePath)
+            return this.projectRoot;
+        return path.join(this.projectRoot, ...safeSegments(relativePath, "entity publication path"));
     }
     assertValid() {
         if (this.closed)
             throw new Error("entity publication context is closed");
         assertValidatedProjectRoot(this.validatedRoot);
-        const currentRoot = fs.fstatSync(this.rootFd, { bigint: true });
-        const expectedRoot = this.validatedRoot.identities.at(-1);
-        if (currentRoot.dev !== expectedRoot.dev || currentRoot.ino !== expectedRoot.ino) {
-            throw new Error(`project root '${this.projectRoot}' changed after validation; restore the exact real directory and retry`);
+        let current;
+        try {
+            current = readStableFile(this.marker.absolute, `state mode marker '${this.markerPath}'`);
         }
-        for (const entry of this.markerParentEntries) {
-            if (!openMatches(entry.parentFd, entry.name, entry.fd, DIRECTORY_FLAGS)) {
-                publicationConflict(this.markerPath);
-            }
+        catch {
+            publicationConflict(this.markerPath);
         }
-        const parentFd = this.markerParentEntries.at(-1)?.fd ?? this.rootFd;
-        const markerName = this.markerPath.split("/").filter(Boolean).at(-1);
-        if (!openMatches(parentFd, markerName, this.markerFd, FILE_FLAGS)
-            || !sameIdentity(this.markerIdentity, fs.fstatSync(this.markerFd, { bigint: true }))
-            || !readDescriptor(this.markerFd).equals(this.markerBytes))
+        if (!sameStableFile(this.marker, current))
             publicationConflict(this.markerPath);
     }
     publishImmutable(relativeTarget, bytes) {
-        const normalized = relativeTarget.split(path.sep).join("/");
-        const segments = normalized.split("/").filter(Boolean);
-        if (segments.length < 2
-            || path.isAbsolute(relativeTarget)
-            || segments.includes("..")
-            || segments.includes("."))
-            throw new Error(`unsafe entity publication target '${relativeTarget}'`);
-        this.assertValid();
+        const segments = safeSegments(relativeTarget, "immutable entity target");
+        if (segments.length < 2)
+            throw new Error(`unsafe immutable entity target '${relativeTarget}'`);
         const directories = [];
-        const createdPaths = [];
-        let stageFd;
-        let stageName;
-        let targetLinked = false;
+        const target = path.join(this.projectRoot, ...segments);
+        let stage;
+        let published;
+        let publicationOwned = false;
         try {
-            let parentFd = this.rootFd;
-            for (const name of segments.slice(0, -1)) {
-                this.assertBoundary(directories);
-                const entryParentFd = parentFd;
-                let fd;
-                let created = false;
-                try {
-                    fd = fs.openSync(fdPath(entryParentFd, name), DIRECTORY_FLAGS);
-                }
-                catch (error) {
-                    if (error.code !== "ENOENT")
-                        throw error;
-                    this.assertBoundary(directories);
-                    fs.mkdirSync(fdPath(entryParentFd, name));
-                    created = true;
-                    fd = fs.openSync(fdPath(entryParentFd, name), DIRECTORY_FLAGS);
-                }
-                const entry = { parentFd: entryParentFd, name, fd, created };
-                directories.push(entry);
-                if (created)
-                    createdPaths.push({ relativePath: segments.slice(0, directories.length).join("/"), fd });
-                parentFd = fd;
-                if (created)
-                    syncDirectory(entryParentFd);
-                this.assertBoundary(directories);
-            }
-            const directoryFd = directories.at(-1).fd;
-            const targetName = segments.at(-1);
-            stageName = `.${targetName}.${process.pid}.${randomUUID()}.tmp`;
-            this.assertBoundary(directories);
-            stageFd = fs.openSync(fdPath(directoryFd, stageName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
-            this.assertBoundary(directories, { name: stageName, fd: stageFd });
-            fs.writeFileSync(stageFd, bytes, "utf8");
-            fs.fsyncSync(stageFd);
-            this.assertBoundary(directories, { name: stageName, fd: stageFd });
-            try {
-                this.assertBoundary(directories, { name: stageName, fd: stageFd });
-                fs.linkSync(fdPath(directoryFd, stageName), fdPath(directoryFd, targetName));
-                targetLinked = true;
+            directories.push(...this.openDirectories(segments.slice(0, -1), true));
+            const directory = directories.at(-1)?.absolute ?? this.projectRoot;
+            const existing = readFileIfPresent(target, `immutable entity target '${relativeTarget}'`);
+            if (existing) {
+                this.removeCreatedDirectories(directories);
+                return null;
             }
-            catch (error) {
-                if (error.code !== "EEXIST")
-                    throw error;
-                this.removeOwnedFile(directoryFd, stageName, stageFd);
-                stageName = undefined;
-                syncDirectory(directoryFd);
-                this.assertBoundary(directories);
+            const stagePath = path.join(directory, `.${segments.at(-1)}.${process.pid}.${randomUUID()}.tmp`);
+            stage = createDurableFile(stagePath, bytes);
+            this.assertBoundary(directories, undefined, [stage]);
+            if (readFileIfPresent(target, `immutable entity target '${relativeTarget}'`)) {
+                removeExactFile(stage);
+                stage = undefined;
                 this.removeCreatedDirectories(directories);
                 return null;
             }
-            syncDirectory(directoryFd);
-            this.assertBoundary(directories, { name: stageName, fd: stageFd }, { name: targetName, fd: stageFd });
-            this.removeOwnedFile(directoryFd, stageName, stageFd);
-            stageName = undefined;
-            syncDirectory(directoryFd);
-            this.assertBoundary(directories, undefined, { name: targetName, fd: stageFd });
-            for (const createdPath of createdPaths)
-                this.createdDirectories.set(createdPath.relativePath, identity(fs.fstatSync(createdPath.fd, { bigint: true })));
-            return publishedIdentity(stageFd);
+            try {
+                fs.linkSync(stage.absolute, target);
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    removeExactFile(stage);
+                    stage = undefined;
+                    this.removeCreatedDirectories(directories);
+                    return null;
+                }
+                throw new FileReplacementError(`immutable publication for '${relativeTarget}' failed before effects`, error);
+            }
+            syncDirectory(directory);
+            stage = readStableFile(stage.absolute, `immutable publication stage '${relativeTarget}'`);
+            published = readStableFile(target, `published entity '${relativeTarget}'`);
+            if (!published.bytes.equals(Buffer.from(bytes)) || published.identity.ino !== stage.identity.ino || published.identity.dev !== stage.identity.dev) {
+                throw new ExactReplacementConflictError(`immutable entity target '${relativeTarget}' changed at its publication boundary`);
+            }
+            publicationOwned = true;
+            this.assertBoundary(directories, published, [stage]);
+            removeExactFile(stage);
+            stage = undefined;
+            syncDirectory(directory);
+            published = readStableFile(target, `published entity '${relativeTarget}'`);
+            this.assertBoundary(directories, published);
+            for (const entry of directories.filter(({ created }) => created)) {
+                this.createdDirectories.set(relativeDisplay(this.projectRoot, entry.absolute), entry);
+            }
+            return publishedIdentity(published);
         }
         catch (error) {
-            const directoryFd = directories.at(-1)?.fd;
-            const targetName = segments.at(-1);
-            const cleanupFailures = [];
-            if (directoryFd !== undefined && stageFd !== undefined && targetLinked) {
-                try {
-                    this.removeOwnedFile(directoryFd, targetName, stageFd);
-                }
-                catch {
-                    cleanupFailures.push("entity");
-                }
-            }
-            if (directoryFd !== undefined && stageFd !== undefined && stageName !== undefined) {
-                try {
-                    this.removeOwnedFile(directoryFd, stageName, stageFd);
+            if (publicationOwned && published) {
+                if (stage) {
+                    try {
+                        if (removeExactFile(stage))
+                            stage = undefined;
+                    }
+                    catch { /* Preserve changed attempt bytes. */ }
                 }
-                catch {
-                    cleanupFailures.push("stage");
+                if (!stage) {
+                    try {
+                        const current = readFileIfPresent(target, `failed immutable publication '${relativeTarget}'`);
+                        if (current && matchesPublished(current, publishedIdentity(published)))
+                            removeExactFile(current);
+                    }
+                    catch { /* Preserve a changed successor. */ }
                 }
             }
-            if (directoryFd !== undefined) {
+            if (stage) {
                 try {
-                    syncDirectory(directoryFd);
+                    removeExactFile(stage);
                 }
-                catch {
-                    cleanupFailures.push("directory sync");
-                }
-            }
-            try {
-                this.removeCreatedDirectories(directories);
-            }
-            catch {
-                cleanupFailures.push("directory");
-            }
-            if (cleanupFailures.length > 0) {
-                throw new Error(`entity publication failed and exact rollback could not remove its ${cleanupFailures.join(", ")}; inspect the pinned project state before retrying`, { cause: error });
+                catch { /* Preserve changed attempt bytes. */ }
             }
+            this.removeCreatedDirectories(directories);
             throw error;
         }
-        finally {
-            if (stageFd !== undefined)
-                fs.closeSync(stageFd);
-            for (const entry of directories.reverse())
-                fs.closeSync(entry.fd);
-        }
     }
     publishPreowned(relativeTarget, relativeReceipt, expected) {
-        const targetSegments = relativeTarget.split(path.sep).filter(Boolean);
-        const receiptSegments = relativeReceipt.split(path.sep).filter(Boolean);
-        if ([targetSegments, receiptSegments].some((segments) => segments.length < 2 || segments.includes("..") || segments.includes("."))
-            || path.isAbsolute(relativeTarget) || path.isAbsolute(relativeReceipt))
+        const targetSegments = safeSegments(relativeTarget, "preowned target");
+        const receiptSegments = safeSegments(relativeReceipt, "preowned receipt");
+        if (targetSegments.length < 2 || receiptSegments.length < 2)
             throw new Error("unsafe preowned publication path");
         this.assertValid();
-        const receiptDirectories = [];
-        const targetDirectories = [];
-        const createdPaths = [];
-        let receiptFd;
-        let targetFd;
-        let linked = false;
+        const receipt = readStableFile(path.join(this.projectRoot, ...receiptSegments), `preowned receipt '${relativeReceipt}'`);
+        if (!matchesPublished(receipt, expected))
+            throw new Error(`preowned receipt '${relativeReceipt}' changed before publication`);
+        const directories = this.openDirectories(targetSegments.slice(0, -1), true);
+        const directory = directories.at(-1)?.absolute ?? this.projectRoot;
+        const target = path.join(directory, targetSegments.at(-1));
         try {
-            let receiptParent = this.rootFd;
-            for (const name of receiptSegments.slice(0, -1)) {
-                const fd = fs.openSync(fdPath(receiptParent, name), DIRECTORY_FLAGS);
-                receiptDirectories.push({ parentFd: receiptParent, name, fd, created: false });
-                receiptParent = fd;
-            }
-            receiptFd = fs.openSync(fdPath(receiptParent, receiptSegments.at(-1)), FILE_FLAGS);
-            const receiptIdentity = publishedIdentity(receiptFd);
-            if (!samePublished(receiptIdentity, expected))
-                throw new Error(`migration ownership receipt '${relativeReceipt}' changed`);
-            let targetParent = this.rootFd;
-            for (const [index, name] of targetSegments.slice(0, -1).entries()) {
-                this.assertBoundary(targetDirectories);
-                const parentFd = targetParent;
-                let fd;
-                let created = false;
+            this.assertBoundary(directories, undefined, [receipt]);
+            if (!readFileIfPresent(target, `preowned target '${relativeTarget}'`)) {
                 try {
-                    fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
+                    fs.linkSync(receipt.absolute, target);
+                    syncDirectory(directory);
                 }
                 catch (error) {
-                    if (error.code !== "ENOENT")
+                    if (error.code !== "EEXIST")
                         throw error;
-                    fs.mkdirSync(fdPath(parentFd, name));
-                    created = true;
-                    fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
-                    syncDirectory(parentFd);
                 }
-                targetDirectories.push({ parentFd, name, fd, created });
-                if (created)
-                    createdPaths.push({ relativePath: targetSegments.slice(0, index + 1).join("/"), fd });
-                targetParent = fd;
             }
-            const targetName = targetSegments.at(-1);
-            try {
-                fs.linkSync(fdPath(receiptParent, receiptSegments.at(-1)), fdPath(targetParent, targetName));
-                linked = true;
-                syncDirectory(targetParent);
-            }
-            catch (error) {
-                if (error.code !== "EEXIST")
-                    throw error;
-            }
-            targetFd = fs.openSync(fdPath(targetParent, targetName), FILE_FLAGS);
-            const targetIdentity = publishedIdentity(targetFd);
-            if (!sameObject(fs.fstatSync(receiptFd, { bigint: true }), fs.fstatSync(targetFd, { bigint: true })) || !samePublished(targetIdentity, expected)) {
+            const published = readStableFile(target, `preowned target '${relativeTarget}'`);
+            if (!matchesPublished(published, expected) || published.identity.dev !== receipt.identity.dev || published.identity.ino !== receipt.identity.ino) {
                 throw new Error(`canonical target '${relativeTarget}' collides with migration ownership receipt; byte-identical replacement inodes are never adopted`);
             }
-            this.assertBoundary(targetDirectories, undefined, { name: targetName, fd: targetFd });
-            for (const createdPath of createdPaths)
-                this.createdDirectories.set(createdPath.relativePath, identity(fs.fstatSync(createdPath.fd, { bigint: true })));
-            return targetIdentity;
+            this.assertBoundary(directories, published, [receipt]);
+            for (const entry of directories.filter(({ created }) => created)) {
+                this.createdDirectories.set(relativeDisplay(this.projectRoot, entry.absolute), entry);
+            }
+            return publishedIdentity(published);
         }
         catch (error) {
-            const targetParent = targetDirectories.at(-1)?.fd;
-            if (linked && targetParent !== undefined && receiptFd !== undefined)
-                this.removeOwnedFile(targetParent, targetSegments.at(-1), receiptFd);
-            this.removeCreatedDirectories(targetDirectories);
+            this.removeCreatedDirectories(directories);
             throw error;
         }
-        finally {
-            if (targetFd !== undefined)
-                fs.closeSync(targetFd);
-            if (receiptFd !== undefined)
-                fs.closeSync(receiptFd);
-            for (const entry of targetDirectories.reverse())
-                fs.closeSync(entry.fd);
-            for (const entry of receiptDirectories.reverse())
-                fs.closeSync(entry.fd);
-        }
     }
-    removeExact(relativeTarget, expected) {
-        const segments = relativeTarget.split(path.sep).filter(Boolean);
-        if (segments.length < 2 || path.isAbsolute(relativeTarget) || segments.includes("..") || segments.includes("."))
-            throw new Error(`unsafe entity rollback target '${relativeTarget}'`);
-        const directories = [];
-        let targetFd;
+    removeExact(relativeTarget, expected, verifyContext = true) {
+        const segments = safeSegments(relativeTarget, "exact removal target");
+        const directories = this.openDirectories(segments.slice(0, -1), false, true, verifyContext);
+        if (!directories)
+            return "absent";
+        const directory = directories.at(-1)?.absolute ?? this.projectRoot;
+        const target = path.join(directory, segments.at(-1));
+        const current = readFileIfPresent(target, `exact removal target '${relativeTarget}'`);
+        if (!current)
+            return "absent";
+        if (!matchesPublished(current, expected))
+            return "identity_mismatch";
+        this.assertBoundary(directories, current, [], verifyContext);
+        const confirmed = readStableFile(target, `exact removal target '${relativeTarget}'`);
+        if (!sameStableFile(current, confirmed))
+            return "identity_mismatch";
+        fs.unlinkSync(target);
+        syncDirectory(directory);
+        this.removeAttemptDirectories();
+        return "removed";
+    }
+    replaceExisting(relativeTarget, expectedBytes, bytes, maxEntityBytes) {
+        return this.replaceOwned(relativeTarget, expectedBytes, bytes, maxEntityBytes);
+    }
+    replaceVisible(relativeTarget, expectedBytes, bytes, maxEntityBytes) {
+        return this.replaceOwned(relativeTarget, expectedBytes, bytes, maxEntityBytes);
+    }
+    restoreExact(relativeTarget, expected, bytes, maxEntityBytes) {
+        return this.replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, false);
+    }
+    restoreVisible(relativeTarget, expected, bytes, maxEntityBytes) {
+        return this.replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, false);
+    }
+    close() {
+        this.closed = true;
+    }
+    replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, verifyContext = true) {
+        const segments = safeSegments(relativeTarget, "recoverable replacement target");
+        const directories = this.openDirectories(segments.slice(0, -1), false, false, verifyContext);
+        if (!directories)
+            throw new FileReplacementError(`replacement target '${relativeTarget}' is absent before publication`);
+        const directory = directories.at(-1)?.absolute ?? this.projectRoot;
+        const target = path.join(directory, segments.at(-1));
+        const baseline = readStableFile(target, `replacement target '${relativeTarget}'`);
+        if (!matchesExpected(baseline, expected)) {
+            throw new ExactReplacementConflictError(`target '${relativeTarget}' ownership or bytes changed before replacement; the detected change was preserved`);
+        }
+        if (!Number.isSafeInteger(maxEntityBytes) || maxEntityBytes < 1 || baseline.bytes.length > maxEntityBytes) {
+            throw new FileReplacementError(`target '${relativeTarget}' exact ${baseline.bytes.length}-byte baseline exceeds the authority-owned ${maxEntityBytes}-byte recovery limit`);
+        }
+        const after = Buffer.from(bytes);
+        let recovery;
+        let backup;
+        let stage;
+        let metadata;
+        let committed;
+        let renameCompleted = false;
         try {
-            let parentFd = this.rootFd;
-            for (const name of segments.slice(0, -1)) {
-                let fd;
-                try {
-                    fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
-                }
-                catch (error) {
-                    if (error.code === "ENOENT")
-                        return "absent";
-                    throw error;
-                }
-                directories.push({ parentFd, name, fd, created: false });
-                parentFd = fd;
+            recovery = this.createRecoveryAttempt(directory);
+            backup = createDurableFile(path.join(recovery.attempt.absolute, "original.previous"), baseline.bytes);
+            stage = createDurableFile(path.join(recovery.attempt.absolute, "replacement.tmp"), after, Number(baseline.identity.mode & 4095n));
+            metadata = createDurableFile(path.join(recovery.attempt.absolute, FILE_REPLACEMENT_METADATA_NAME), `${JSON.stringify({
+                schema_version: FILE_REPLACEMENT_RECOVERY_VERSION,
+                target_path: segments.join("/"),
+                before_sha256: sha256(baseline.bytes),
+                after_sha256: sha256(after),
+            })}\n`);
+            syncDirectory(recovery.attempt.absolute);
+            this.assertBoundary(directories, baseline, [backup, stage, metadata], verifyContext);
+            const boundaryTarget = readStableFile(target, `replacement target '${relativeTarget}'`);
+            if (!sameStableFile(boundaryTarget, baseline)) {
+                throw new ExactReplacementConflictError(`target '${relativeTarget}' changed at the final validation boundary; the detected change was preserved`);
             }
-            const directoryFd = directories.at(-1).fd;
-            const targetName = segments.at(-1);
             try {
-                targetFd = fs.openSync(fdPath(directoryFd, targetName), FILE_FLAGS);
+                fs.renameSync(stage.absolute, target);
+                renameCompleted = true;
             }
             catch (error) {
-                if (error.code === "ENOENT")
-                    return "absent";
+                throw new FileReplacementError(`complete-file replacement for '${relativeTarget}' failed before publication${error.code ? ` (${error.code})` : ""}`, error);
+            }
+            syncDirectory(directory);
+            syncDirectory(recovery.attempt.absolute);
+            const published = readStableFile(target, `published replacement '${relativeTarget}'`);
+            if (!published.bytes.equals(after)) {
+                throw new ExactReplacementConflictError(`target '${relativeTarget}' changed through the publication boundary`);
+            }
+            this.assertBoundary(directories, published, [backup, metadata], verifyContext);
+            committed = { previousBytes: baseline.bytes.toString("utf8"), publishedIdentity: publishedIdentity(published) };
+            this.cleanupCommittedReplacement(recovery.attempt.absolute, [backup, metadata]);
+            backup = undefined;
+            metadata = undefined;
+            stage = undefined;
+            return committed;
+        }
+        catch (error) {
+            if (committed)
+                return committed;
+            let current = null;
+            try {
+                current = readFileIfPresent(target, `replacement target '${relativeTarget}'`);
+            }
+            catch { /* Preserve all recovery evidence. */ }
+            if (!renameCompleted && error instanceof ExactReplacementConflictError) {
+                const retained = this.cleanupAttemptFiles([stage, backup, metadata]);
+                stage = undefined;
+                backup = undefined;
+                metadata = undefined;
+                if (retained.length) {
+                    throw new ExactReplacementConflictError(`${error.message}; cleanup retained changed recovery roles`, retained);
+                }
                 throw error;
             }
-            if (!matchesPublished(targetFd, expected))
-                return "identity_mismatch";
-            const rollbackName = `.${targetName}.${process.pid}.${randomUUID()}.rollback`;
-            fs.renameSync(fdPath(directoryFd, targetName), fdPath(directoryFd, rollbackName));
-            if (openMatches(directoryFd, rollbackName, targetFd, FILE_FLAGS)) {
-                this.removeOwnedFile(directoryFd, rollbackName, targetFd);
-            }
-            else {
+            if (renameCompleted && current?.bytes.equals(after) && backup) {
                 try {
-                    fs.linkSync(fdPath(directoryFd, rollbackName), fdPath(directoryFd, targetName));
-                    fs.unlinkSync(fdPath(directoryFd, rollbackName));
+                    this.assertBoundary(directories, current, [backup], false);
+                    fs.renameSync(backup.absolute, target);
+                    backup = undefined;
+                    syncDirectory(directory);
+                    const restored = readStableFile(target, `restored replacement target '${relativeTarget}'`);
+                    if (!restored.bytes.equals(baseline.bytes))
+                        throw new Error("restored bytes do not match the exact baseline");
+                    if (stage) {
+                        try {
+                            removeExactFile(stage);
+                        }
+                        catch { /* Preserve changed stage. */ }
+                        stage = undefined;
+                    }
+                    if (metadata) {
+                        try {
+                            removeExactFile(metadata);
+                        }
+                        catch { /* Preserve changed metadata. */ }
+                        metadata = undefined;
+                    }
+                    syncDirectoryBestEffort(recovery?.attempt.absolute ?? directory);
+                    throw new FileReplacementError(`${error.message}; restored exact prior bytes at '${relativeTarget}'`, error);
                 }
-                catch (error) {
-                    if (error.code !== "EEXIST")
-                        throw error;
+                catch (restoreError) {
+                    if (restoreError instanceof FileReplacementError && restoreError.cause === error)
+                        throw restoreError;
                 }
-                syncDirectory(directoryFd);
-                return "identity_mismatch";
             }
-            syncDirectory(directoryFd);
-            return "removed";
+            if (!renameCompleted && current && sameStableFile(current, baseline)) {
+                const retained = this.cleanupAttemptFiles([stage, backup, metadata]);
+                stage = undefined;
+                backup = undefined;
+                metadata = undefined;
+                if (retained.length) {
+                    throw new ExactReplacementConflictError(`${error.message}; cleanup retained changed recovery roles`, retained);
+                }
+                if (error instanceof ExactReplacementConflictError || error instanceof FileReplacementError || error instanceof StateWriteInputError)
+                    throw error;
+                throw new FileReplacementError(`${error.message}; target bytes remained unchanged`, error);
+            }
+            const retained = [backup, stage, metadata]
+                .filter((file) => Boolean(file && fs.existsSync(file.absolute)))
+                .map((file) => relativeDisplay(this.projectRoot, file.absolute));
+            throw new ExactReplacementConflictError(`${error.message}; recoverable publication did not report success and preserved the canonical target plus ${retained.length} bounded recovery role${retained.length === 1 ? "" : "s"}`, retained);
         }
         finally {
-            if (targetFd !== undefined)
-                fs.closeSync(targetFd);
-            for (const entry of directories.reverse())
-                fs.closeSync(entry.fd);
-            this.removeAttemptDirectories();
+            if (recovery)
+                this.closeRecoveryAttempt(recovery);
         }
     }
-    removeAttemptDirectories() {
-        const paths = [...this.createdDirectories.keys()].sort((left, right) => right.split("/").length - left.split("/").length);
-        for (const relativePath of paths) {
-            const segments = relativePath.split("/");
-            const descriptors = [];
-            let targetFd;
-            let parentFd = this.rootFd;
+    openDirectories(segments, create, missingIsAbsent = false, verifyContext = true) {
+        const directories = [];
+        let parent = this.projectRoot;
+        for (const segment of segments) {
+            if (verifyContext)
+                this.assertValid();
+            else
+                assertValidatedProjectRoot(this.validatedRoot);
+            const absolute = path.join(parent, segment);
+            let entry;
             try {
-                for (const name of segments.slice(0, -1)) {
-                    const fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
-                    descriptors.push(fd);
-                    parentFd = fd;
-                }
-                targetFd = fs.openSync(fdPath(parentFd, segments.at(-1)), DIRECTORY_FLAGS);
-                const expected = this.createdDirectories.get(relativePath);
-                const observed = fs.fstatSync(targetFd, { bigint: true });
-                if (observed.dev !== expected.dev || observed.ino !== expected.ino) {
-                    this.createdDirectories.delete(relativePath);
-                    continue;
-                }
-                fs.rmdirSync(fdPath(parentFd, segments.at(-1)));
-                syncDirectory(parentFd);
-                this.createdDirectories.delete(relativePath);
+                entry = readStableDirectory(absolute);
             }
             catch (error) {
-                const code = error.code ?? "";
-                if (code === "ENOENT")
-                    this.createdDirectories.delete(relativePath);
-                else if (!["ENOTEMPTY", "EEXIST"].includes(code))
+                if (error.code === "ENOENT" || error.message.includes("ENOENT")) {
+                    if (missingIsAbsent)
+                        return null;
+                    if (!create)
+                        throw error;
+                    this.assertBoundary(directories, undefined, [], verifyContext);
+                    fs.mkdirSync(absolute, 0o700);
+                    syncDirectory(parent);
+                    entry = readStableDirectory(absolute, true);
+                }
+                else
                     throw error;
             }
-            finally {
-                if (targetFd !== undefined)
-                    fs.closeSync(targetFd);
-                for (const fd of descriptors.reverse())
-                    fs.closeSync(fd);
-            }
+            directories.push(entry);
+            parent = absolute;
         }
+        return directories;
     }
-    replaceExisting(relativeTarget, expectedBytes, bytes, maxEntityBytes) {
-        return this.replaceOwned(relativeTarget, expectedBytes, bytes, maxEntityBytes);
-    }
-    restoreExact(relativeTarget, expected, bytes, maxEntityBytes) {
-        // Recovery stays bound to the pinned root and exact archived target even when context invalidation caused the primary failure.
-        return this.replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, false);
-    }
-    replaceOwned(relativeTarget, expected, bytes, maxEntityBytes, verifyContext = true) {
-        const segments = relativeTarget.split(path.sep).filter(Boolean);
-        if (segments.length < 2 || path.isAbsolute(relativeTarget) || segments.includes("..") || segments.includes("."))
-            throw new Error(`unsafe entity replacement target '${relativeTarget}'`);
-        const directories = [];
-        let targetFd;
-        let stageFd;
-        let backupFd;
-        let stageName;
-        let backupName;
-        let displacedName;
-        let displacedFd;
-        let displacementActive = false;
-        let committedResult;
-        let recovery;
-        let baselineBytes;
-        try {
-            let parentFd = this.rootFd;
-            for (const name of segments.slice(0, -1)) {
-                const fd = fs.openSync(fdPath(parentFd, name), DIRECTORY_FLAGS);
-                directories.push({ parentFd, name, fd, created: false });
-                parentFd = fd;
-            }
-            const directoryFd = directories.at(-1).fd;
-            const targetName = segments.at(-1);
-            targetFd = fs.openSync(fdPath(directoryFd, targetName), FILE_FLAGS);
-            this.assertBoundary(directories, undefined, { name: targetName, fd: targetFd }, verifyContext);
-            const previousBytes = readDescriptor(targetFd);
-            baselineBytes = previousBytes;
-            if (!matchesExpected(targetFd, expected))
-                throw new Error(`entity '${relativeTarget}' ownership changed before replacement; preserve both changes and retry explicitly`);
-            if (!Number.isSafeInteger(maxEntityBytes) || maxEntityBytes < 1 || previousBytes.length > maxEntityBytes)
-                throw new Error(`entity '${relativeTarget}' exact ${previousBytes.length}-byte baseline exceeds the authority-owned ${maxEntityBytes}-byte recovery limit`);
-            recovery = this.createRecoveryAttempt(directoryFd);
-            backupName = "original.previous";
-            backupFd = fs.openSync(fdPath(recovery.attemptFd, backupName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
-            fs.writeFileSync(backupFd, previousBytes);
-            fs.fsyncSync(backupFd);
-            const backupStat = fs.fstatSync(backupFd, { bigint: true });
-            const attemptStat = fs.fstatSync(recovery.attemptFd, { bigint: true });
-            if (!backupStat.isFile() || backupStat.dev !== attemptStat.dev || backupStat.uid !== attemptStat.uid || backupStat.nlink !== 1n || (backupStat.mode & 63n) !== 0n || !openMatches(recovery.attemptFd, backupName, backupFd, FILE_FLAGS) || !readDescriptor(backupFd).equals(previousBytes))
-                throw new Error(`entity '${relativeTarget}' exact prior-byte snapshot could not be verified before replacement`);
-            stageName = "replacement.tmp";
-            stageFd = fs.openSync(fdPath(recovery.attemptFd, stageName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
-            fs.writeFileSync(stageFd, bytes, "utf8");
-            fs.fsyncSync(stageFd);
-            this.assertBoundary(directories, undefined, { name: targetName, fd: targetFd }, verifyContext);
-            if (!openMatches(recovery.attemptFd, stageName, stageFd, FILE_FLAGS) || !openMatches(recovery.attemptFd, backupName, backupFd, FILE_FLAGS) || !readDescriptor(backupFd).equals(previousBytes))
-                throw new Error(`entity '${relativeTarget}' private recovery attempt changed before displacement`);
-            displacedName = "original.displaced";
-            fs.renameSync(fdPath(directoryFd, targetName), fdPath(recovery.attemptFd, displacedName));
-            displacementActive = true;
-            displacedFd = fs.openSync(fdPath(recovery.attemptFd, displacedName), FILE_FLAGS);
-            if (!openMatches(recovery.attemptFd, displacedName, targetFd, FILE_FLAGS) || !matchesExpected(displacedFd, expected))
-                throw new Error(`entity '${relativeTarget}' ownership changed after staging; competing bytes were preserved at the target`);
+    assertBoundary(directories, target, roles = [], verifyContext = true) {
+        if (verifyContext)
+            this.assertValid();
+        else
+            assertValidatedProjectRoot(this.validatedRoot);
+        for (const directory of directories) {
+            let current;
             try {
-                fs.linkSync(fdPath(recovery.attemptFd, stageName), fdPath(directoryFd, targetName));
-            }
-            catch (publishError) {
-                if (publishError.code === "EEXIST")
-                    throw new Error(`entity '${relativeTarget}' ownership changed during no-clobber publication; competing target bytes were preserved`, { cause: publishError });
-                throw publishError;
-            }
-            if (!this.removeOwnedFile(recovery.attemptFd, stageName, stageFd))
-                throw new Error(`entity '${relativeTarget}' replacement stage changed before cleanup`);
-            stageName = undefined;
-            syncDirectory(directoryFd);
-            syncDirectory(recovery.attemptFd);
-            this.assertBoundary(directories, undefined, { name: targetName, fd: stageFd }, verifyContext);
-            if (!openMatches(recovery.attemptFd, displacedName, targetFd, FILE_FLAGS) || !matchesExpected(displacedFd, expected))
-                throw new Error(`entity '${relativeTarget}' ownership changed through the publication boundary; competing bytes remain recoverable`);
-            committedResult = { previousBytes: previousBytes.toString("utf8"), publishedIdentity: publishedIdentity(stageFd) };
-            this.cleanupCommittedReplacement(recovery.attemptFd, [[displacedName, targetFd], [backupName, backupFd]]);
-            displacementActive = false;
-            return committedResult;
+                current = fs.lstatSync(directory.absolute, { bigint: true });
+            }
+            catch {
+                throw new ExactReplacementConflictError(`publication directory '${relativeDisplay(this.projectRoot, directory.absolute)}' changed at a validation boundary`);
+            }
+            if (!sameDirectory(directory, current)) {
+                throw new ExactReplacementConflictError(`publication directory '${relativeDisplay(this.projectRoot, directory.absolute)}' changed at a validation boundary`);
+            }
         }
-        catch (error) {
-            if (committedResult)
-                return committedResult;
-            const directoryFd = directories.at(-1)?.fd;
-            if (displacementActive && directoryFd !== undefined && targetFd !== undefined && recovery) {
-                throw this.recoverDisplacedReplacement({ directoryFd, recoveryFd: recovery.attemptFd, recoveryPath: recovery.relativePath, relativeTarget, baselineBytes: baselineBytes, backupFd, stageFd, stageName, backupName, displacedFd, displacedName, retainStage: !verifyContext, primary: error });
-            }
-            const cleanupFailures = [];
-            for (const [name, fd, label] of [[stageName, stageFd, "stage"], [backupName, backupFd, "backup"]])
-                if (name && fd !== undefined) {
-                    try {
-                        if (!recovery || !this.removeOwnedFile(recovery.attemptFd, name, fd))
-                            cleanupFailures.push(`${label} '${recovery ? path.join(recovery.relativePath, name) : name}' changed`);
-                    }
-                    catch (cleanupError) {
-                        cleanupFailures.push(`${label} '${recovery ? path.join(recovery.relativePath, name) : name}': ${cleanupError.message}`);
-                    }
-                }
-            if (cleanupFailures.length)
-                throw new Error(`${error.message}; cleanup retained attempt state: ${cleanupFailures.join("; ")}`, { cause: error });
-            throw error;
+        if (target) {
+            const current = readFileIfPresent(target.absolute, `publication target '${relativeDisplay(this.projectRoot, target.absolute)}'`);
+            if (!current || !sameStableFile(target, current)) {
+                throw new ExactReplacementConflictError(`publication target '${relativeDisplay(this.projectRoot, target.absolute)}' changed at a validation boundary`);
+            }
         }
-        finally {
-            if (displacedFd !== undefined)
-                fs.closeSync(displacedFd);
-            if (backupFd !== undefined)
-                fs.closeSync(backupFd);
-            if (stageFd !== undefined)
-                fs.closeSync(stageFd);
-            if (targetFd !== undefined)
-                fs.closeSync(targetFd);
-            for (const entry of directories.reverse())
-                fs.closeSync(entry.fd);
-            if (recovery)
-                this.closeRecoveryAttempt(recovery);
+        for (const role of roles) {
+            const current = readFileIfPresent(role.absolute, `publication role '${relativeDisplay(this.projectRoot, role.absolute)}'`);
+            if (!current || !sameStableFile(role, current)) {
+                throw new ExactReplacementConflictError(`publication recovery role '${relativeDisplay(this.projectRoot, role.absolute)}' changed at a validation boundary`);
+            }
         }
     }
-    createRecoveryAttempt(targetDirectoryFd) {
-        const rootName = ".entity-recovery";
-        const agenteraFd = fs.openSync(fdPath(this.rootFd, ".agentera"), DIRECTORY_FLAGS);
-        let rootFd;
-        let ignoreFd;
-        let ignoreCreated = false;
-        let attemptFd;
-        let attemptName;
+    createRecoveryAttempt(targetDirectory) {
+        const agentera = readStableDirectory(path.join(this.projectRoot, ".agentera"));
+        const rootPath = path.join(agentera.absolute, ".entity-recovery");
         let rootCreated = false;
+        let ignoreCreated = false;
+        let root;
+        let ignore;
+        let attempt;
         try {
             try {
-                rootFd = fs.openSync(fdPath(agenteraFd, rootName), DIRECTORY_FLAGS);
+                root = readStableDirectory(rootPath);
             }
             catch (error) {
-                if (error.code !== "ENOENT")
-                    throw new Error(`private entity recovery root '.agentera/${rootName}' cannot be opened safely: ${error.message}`, { cause: error });
-                fs.mkdirSync(fdPath(agenteraFd, rootName), 0o700);
+                if (!error.message.includes("ENOENT")) {
+                    throw new FileReplacementError(`private entity recovery root '.agentera/.entity-recovery' cannot be opened safely: ${error.message}`, error);
+                }
+                fs.mkdirSync(rootPath, 0o700);
                 rootCreated = true;
-                syncDirectory(agenteraFd);
-                rootFd = fs.openSync(fdPath(agenteraFd, rootName), DIRECTORY_FLAGS);
-            }
-            const rootStat = fs.fstatSync(rootFd, { bigint: true });
-            if ((rootStat.mode & 18n) !== 0n || (typeof process.getuid === "function" && rootStat.uid !== BigInt(process.getuid())))
-                throw new Error(`private entity recovery root '.agentera/${rootName}' must be owned by the current user and not group/world-writable`);
-            if (rootStat.dev !== fs.fstatSync(targetDirectoryFd, { bigint: true }).dev)
-                throw new Error("private entity recovery root must share the canonical entity target filesystem");
-            try {
-                ignoreFd = fs.openSync(fdPath(rootFd, ".gitignore"), FILE_FLAGS);
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    throw new Error(`private entity recovery ignore marker cannot be opened safely: ${error.message}`, { cause: error });
-                ignoreFd = fs.openSync(fdPath(rootFd, ".gitignore"), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+                syncDirectory(agentera.absolute);
+                root = readStableDirectory(rootPath, true);
+            }
+            const trustedRoot = validateEntityRecoveryDirectory(this.validatedRoot, root.absolute, targetDirectory, "private entity recovery root '.agentera/.entity-recovery'", root);
+            root = { ...trustedRoot, created: rootCreated };
+            const ignorePath = path.join(root.absolute, ".gitignore");
+            const existingIgnore = readFileIfPresent(ignorePath, "private entity recovery ignore marker");
+            if (existingIgnore)
+                ignore = existingIgnore;
+            else {
+                ignore = createDurableFile(ignorePath, RECOVERY_IGNORE_BYTES);
                 ignoreCreated = true;
-                fs.writeFileSync(ignoreFd, RECOVERY_IGNORE_BYTES, "utf8");
-                fs.fsyncSync(ignoreFd);
-            }
-            const ignoreStat = fs.fstatSync(ignoreFd, { bigint: true });
-            if (!ignoreStat.isFile() || (ignoreStat.mode & 18n) !== 0n || (typeof process.getuid === "function" && ignoreStat.uid !== BigInt(process.getuid())) || !readDescriptor(ignoreFd).equals(Buffer.from(RECOVERY_IGNORE_BYTES)))
-                throw new Error("private entity recovery ignore marker must be an owner-controlled regular file with the authoritative rules");
-            syncDirectory(rootFd);
-            for (let attempt = 0; attempt < 8; attempt += 1) {
-                const candidate = `entity-${process.pid}-${randomUUID()}`;
+            }
+            if (!ignore.bytes.equals(Buffer.from(RECOVERY_IGNORE_BYTES))) {
+                throw new FileReplacementError("private entity recovery ignore marker must contain the authoritative rules");
+            }
+            const ignoreStat = fs.lstatSync(ignore.absolute, { bigint: true });
+            if (typeof process.getuid === "function" && ((ignoreStat.mode & 18n) !== 0n || ignoreStat.uid !== BigInt(process.getuid()))) {
+                throw new FileReplacementError("private entity recovery ignore marker must be owner-controlled and not group/world-writable");
+            }
+            syncDirectory(root.absolute);
+            for (let index = 0; index < 8; index += 1) {
+                const attemptPath = path.join(root.absolute, `entity-${process.pid}-${randomUUID()}`);
                 try {
-                    fs.mkdirSync(fdPath(rootFd, candidate), 0o700);
-                    attemptName = candidate;
+                    fs.mkdirSync(attemptPath, 0o700);
+                    const opened = readStableDirectory(attemptPath, true);
+                    attempt = opened;
+                    const trusted = validateEntityRecoveryDirectory(this.validatedRoot, attemptPath, targetDirectory, `private entity recovery attempt '${relativeDisplay(this.projectRoot, attemptPath)}'`, opened);
+                    attempt = { ...trusted, created: true };
                     break;
                 }
                 catch (error) {
@@ -700,263 +697,108 @@ export class EntityPublicationContext {
                         throw error;
                 }
             }
-            if (!attemptName)
-                throw new Error("could not allocate a unique private entity recovery attempt after 8 tries");
-            attemptFd = fs.openSync(fdPath(rootFd, attemptName), DIRECTORY_FLAGS);
-            const attemptStat = fs.fstatSync(attemptFd, { bigint: true });
-            if ((attemptStat.mode & 63n) !== 0n || attemptStat.uid !== rootStat.uid || attemptStat.dev !== rootStat.dev)
-                throw new Error("private entity recovery attempt must be owner-only, owner-controlled, and on the recovery-root filesystem");
-            syncDirectory(rootFd);
-            return { agenteraFd, rootFd, attemptFd, ignoreFd, attemptName, relativePath: `.agentera/${rootName}/${attemptName}` };
+            if (!attempt)
+                throw new FileReplacementError("could not allocate a unique private entity recovery attempt after 8 tries");
+            syncDirectory(root.absolute);
+            return { root, attempt, ignore, relativePath: relativeDisplay(this.projectRoot, attempt.absolute) };
         }
         catch (error) {
-            if (attemptFd !== undefined)
-                fs.closeSync(attemptFd);
-            if (rootFd !== undefined && attemptName) {
+            if (attempt) {
                 try {
-                    fs.rmdirSync(fdPath(rootFd, attemptName));
+                    fs.rmdirSync(attempt.absolute);
                 }
-                catch { /* preserve unexpected contents */ }
+                catch { /* Preserve unexpected contents. */ }
             }
-            if (rootFd !== undefined && ignoreFd !== undefined && ignoreCreated) {
+            if (ignore && ignoreCreated) {
                 try {
-                    this.removeOwnedFile(rootFd, ".gitignore", ignoreFd);
+                    removeExactFile(ignore);
                 }
-                catch { /* preserve changed marker */ }
+                catch { /* Preserve changed marker. */ }
             }
-            if (ignoreFd !== undefined)
-                fs.closeSync(ignoreFd);
-            if (rootFd !== undefined)
-                fs.closeSync(rootFd);
-            if (rootCreated) {
+            if (root && rootCreated) {
                 try {
-                    fs.rmdirSync(fdPath(agenteraFd, rootName));
+                    fs.rmdirSync(root.absolute);
                 }
-                catch { /* preserve non-empty or changed root */ }
+                catch { /* Preserve non-empty root. */ }
             }
-            fs.closeSync(agenteraFd);
             throw error;
         }
     }
-    closeRecoveryAttempt(recovery) {
-        try {
-            if (openMatches(recovery.rootFd, recovery.attemptName, recovery.attemptFd, DIRECTORY_FLAGS)) {
-                try {
-                    fs.rmdirSync(fdPath(recovery.rootFd, recovery.attemptName));
-                    syncDirectory(recovery.rootFd);
-                }
-                catch { /* best-effort private cleanup retains non-empty or changed attempt */ }
-            }
-            const remaining = fs.readdirSync(fdPath(recovery.rootFd));
-            if (remaining.length === 1 && remaining[0] === ".gitignore" && openMatches(recovery.rootFd, ".gitignore", recovery.ignoreFd, FILE_FLAGS)) {
-                try {
-                    this.removeOwnedFile(recovery.rootFd, ".gitignore", recovery.ignoreFd);
-                    syncDirectory(recovery.rootFd);
-                }
-                catch { /* preserve marker on cleanup failure */ }
-            }
-            if (openMatches(recovery.agenteraFd, ".entity-recovery", recovery.rootFd, DIRECTORY_FLAGS)) {
-                try {
-                    fs.rmdirSync(fdPath(recovery.agenteraFd, ".entity-recovery"));
-                    syncDirectory(recovery.agenteraFd);
-                }
-                catch { /* best-effort private cleanup retains non-empty or changed root */ }
+    cleanupAttemptFiles(files) {
+        const retained = [];
+        for (const file of files) {
+            if (!file)
+                continue;
+            try {
+                if (!removeExactFile(file) && fs.existsSync(file.absolute))
+                    retained.push(relativeDisplay(this.projectRoot, file.absolute));
             }
-        }
-        catch {
-            /* committed or already-recovered state must not be reclassified by private cleanup */
-        }
-        finally {
-            for (const fd of [recovery.attemptFd, recovery.ignoreFd, recovery.rootFd, recovery.agenteraFd]) {
-                try {
-                    fs.closeSync(fd);
-                }
-                catch { /* best-effort descriptor close */ }
+            catch {
+                retained.push(relativeDisplay(this.projectRoot, file.absolute));
             }
         }
+        return retained;
     }
-    cleanupCommittedReplacement(directoryFd, links) {
-        for (const [name, fd] of links) {
-            for (let attempt = 0; attempt < 2; attempt += 1) {
-                try {
-                    this.removeOwnedFile(directoryFd, name, fd);
-                    break;
-                }
-                catch { /* committed publication remains authoritative; retry once and otherwise retain recovery link */ }
-            }
-        }
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            try {
-                syncDirectory(directoryFd);
-                break;
-            }
-            catch { /* cleanup durability is best-effort after the durable commit boundary */ }
-        }
+    cleanupCommittedReplacement(directory, files) {
+        this.cleanupAttemptFiles(files);
+        syncDirectoryBestEffort(directory);
     }
-    recoverDisplacedReplacement(state) {
-        const { directoryFd, recoveryFd, recoveryPath, relativeTarget, baselineBytes, backupFd, stageFd, displacedFd, retainStage, primary } = state;
-        const targetName = path.basename(relativeTarget);
-        const failures = [];
-        const retained = new Set();
-        let { stageName, backupName, displacedName } = state;
-        const publicPath = (name) => path.join(recoveryPath, name).split(path.sep).join("/");
-        const exactBaseline = () => Boolean(backupName && backupFd !== undefined && openMatches(recoveryFd, backupName, backupFd, FILE_FLAGS) && readDescriptor(backupFd).equals(baselineBytes));
-        const exactDisplaced = () => Boolean(displacedName && displacedFd !== undefined && openMatches(recoveryFd, displacedName, displacedFd, FILE_FLAGS));
-        const exactStage = () => Boolean(stageName && stageFd !== undefined && openMatches(recoveryFd, stageName, stageFd, FILE_FLAGS));
-        const remove = (name, fd, label) => {
-            try {
-                if (this.removeOwnedFile(recoveryFd, name, fd))
-                    return true;
-                failures.push(`${label} '${publicPath(name)}' changed before cleanup`);
-            }
-            catch (error) {
-                failures.push(`${label} '${publicPath(name)}' cleanup failed: ${error.message}`);
-            }
-            retained.add(publicPath(name));
-            return false;
-        };
-        const sync = (label) => { try {
-            syncDirectory(directoryFd);
-            syncDirectory(recoveryFd);
-            return true;
+    closeRecoveryAttempt(recovery) {
+        try {
+            fs.rmdirSync(recovery.attempt.absolute);
+            syncDirectoryBestEffort(recovery.root.absolute);
         }
-        catch (error) {
-            failures.push(`${label} directory fsync failed: ${error.message}`);
-            return false;
-        } };
-        const displacedBytes = exactDisplaced() ? readDescriptor(displacedFd) : undefined;
-        const displacedCompetitor = Boolean(displacedBytes && !displacedBytes.equals(baselineBytes));
-        const source = displacedCompetitor ? displacedName : exactBaseline() ? backupName : exactDisplaced() && displacedBytes?.equals(baselineBytes) ? displacedName : undefined;
-        const sourceFd = source === backupName ? backupFd : source === displacedName ? displacedFd : undefined;
-        if (stageFd !== undefined && openMatches(directoryFd, targetName, stageFd, FILE_FLAGS) && source && sourceFd !== undefined) {
-            try {
-                if (this.removeOwnedFile(directoryFd, targetName, stageFd))
-                    sync("replacement removal");
-                else
-                    failures.push(`published replacement '${relativeTarget}' changed before cleanup`);
+        catch {
+            return;
+        }
+        try {
+            const names = fs.readdirSync(recovery.root.absolute);
+            if (names.length === 1 && names[0] === ".gitignore") {
+                removeExactFile(recovery.ignore);
+                syncDirectoryBestEffort(recovery.root.absolute);
             }
-            catch (error) {
-                failures.push(`published replacement '${relativeTarget}' cleanup failed: ${error.message}`);
+            if (fs.readdirSync(recovery.root.absolute).length === 0) {
+                fs.rmdirSync(recovery.root.absolute);
+                syncDirectoryBestEffort(path.dirname(recovery.root.absolute));
             }
         }
-        let restoredBaseline = pathBytesEqual(directoryFd, targetName, baselineBytes);
-        let restoredCompetitor = Boolean(displacedCompetitor && displacedFd !== undefined && openMatches(directoryFd, targetName, displacedFd, FILE_FLAGS));
-        let occupied = !restoredBaseline && !restoredCompetitor && entryExists(directoryFd, targetName);
-        if (!restoredBaseline && !restoredCompetitor && !occupied && source && sourceFd !== undefined) {
+        catch { /* Preserve non-empty or changed recovery authority. */ }
+    }
+    removeCreatedDirectories(directories) {
+        for (const directory of [...directories].reverse()) {
+            if (!directory.created)
+                continue;
             try {
-                fs.linkSync(fdPath(recoveryFd, source), fdPath(directoryFd, targetName));
+                const current = fs.lstatSync(directory.absolute, { bigint: true });
+                if (!sameDirectory(directory, current))
+                    continue;
+                fs.rmdirSync(directory.absolute);
+                syncDirectoryBestEffort(path.dirname(directory.absolute));
             }
             catch (error) {
-                if (error.code !== "EEXIST")
-                    failures.push(`restoration from '${publicPath(source)}' failed: ${error.message}`);
-            }
-            restoredBaseline = pathBytesEqual(directoryFd, targetName, baselineBytes);
-            restoredCompetitor = Boolean(displacedCompetitor && displacedFd !== undefined && openMatches(directoryFd, targetName, displacedFd, FILE_FLAGS));
-            occupied = !restoredBaseline && !restoredCompetitor && entryExists(directoryFd, targetName);
-        }
-        if (restoredBaseline || restoredCompetitor) {
-            const durable = sync(restoredBaseline ? "exact baseline restoration" : "competitor restoration");
-            if (durable) {
-                if (retainStage && exactStage())
-                    retained.add(publicPath(stageName));
-                else if (exactStage() && remove(stageName, stageFd, "replacement stage"))
-                    stageName = undefined;
-                if (restoredCompetitor) {
-                    if (exactBaseline())
-                        retained.add(publicPath(backupName));
-                    else
-                        failures.push("exact baseline snapshot is unavailable");
-                    if (exactDisplaced() && remove(displacedName, displacedFd, "canonicalized competitor duplicate"))
-                        displacedName = undefined;
-                }
-                else {
-                    if (displacedCompetitor && exactDisplaced())
-                        retained.add(publicPath(displacedName));
-                    else if (exactDisplaced() && remove(displacedName, displacedFd, "displaced baseline duplicate"))
-                        displacedName = undefined;
-                    if (exactBaseline() && remove(backupName, backupFd, "baseline snapshot duplicate"))
-                        backupName = undefined;
-                }
-                sync("restoration cleanup");
-            }
-            for (const name of [backupName, displacedName, stageName])
-                if (name && entryExists(recoveryFd, name))
-                    retained.add(publicPath(name));
-            const outcome = restoredCompetitor
-                ? `recovery restored concurrent competitor bytes at '${relativeTarget}' and retained the exact discovered baseline snapshot at ${exactBaseline() ? `'${publicPath(backupName)}'` : "an unavailable path"}`
-                : `recovery restored byte-verified exact prior bytes at '${relativeTarget}'`;
-            return new Error(`${primary.message}; ${outcome}${retained.size ? `; retained recovery files: ${[...retained].join(", ")}` : ""}${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
-        }
-        if (occupied) {
-            if (exactBaseline())
-                retained.add(publicPath(backupName));
-            else
-                failures.push("exact baseline snapshot is unavailable");
-            if (displacedCompetitor && exactDisplaced())
-                retained.add(publicPath(displacedName));
-            if (sync("competing-target retention")) {
-                if (retainStage && exactStage())
-                    retained.add(publicPath(stageName));
-                else if (exactStage() && remove(stageName, stageFd, "replacement stage"))
-                    stageName = undefined;
-                if (!displacedCompetitor && exactDisplaced() && remove(displacedName, displacedFd, "displaced baseline duplicate"))
-                    displacedName = undefined;
-                sync("retention cleanup");
-            }
-            for (const name of [backupName, displacedName, stageName])
-                if (name && entryExists(recoveryFd, name))
-                    retained.add(publicPath(name));
-            return new Error(`${primary.message}; recovery preserved the competing canonical target and retained the exact discovered baseline snapshot and any displaced competitor at ${[...retained].join(", ") || "unavailable paths"}; preserve each role and resolve ownership explicitly${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
-        }
-        if (exactBaseline())
-            retained.add(publicPath(backupName));
-        if (exactDisplaced())
-            retained.add(publicPath(displacedName));
-        if (exactStage())
-            retained.add(publicPath(stageName));
-        return new Error(`${primary.message}; recovery could not restore the absent canonical target; retained role-labeled recovery files: ${[...retained].join(", ") || "none"}; restore the exact baseline or competitor explicitly before retrying${failures.length ? `; recovery issues: ${failures.join("; ")}` : ""}`, { cause: primary });
-    }
-    close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        fs.closeSync(this.markerFd);
-        for (const entry of this.markerParentEntries.reverse())
-            fs.closeSync(entry.fd);
-        fs.closeSync(this.rootFd);
-    }
-    assertBoundary(directories, stage, target, verifyContext = true) {
-        if (verifyContext)
-            this.assertValid();
-        for (const entry of directories) {
-            if (!openMatches(entry.parentFd, entry.name, entry.fd, DIRECTORY_FLAGS)) {
-                throw new Error(`entity publication directory '${entry.name}' changed during publication`);
+                if (!["ENOTEMPTY", "EEXIST", "ENOENT"].includes(error.code ?? ""))
+                    throw error;
             }
         }
-        const directoryFd = directories.at(-1)?.fd;
-        if (directoryFd !== undefined && stage && !openMatches(directoryFd, stage.name, stage.fd, FILE_FLAGS)) {
-            throw new Error("entity publication stage changed during publication");
-        }
-        if (directoryFd !== undefined && target && !openMatches(directoryFd, target.name, target.fd, FILE_FLAGS)) {
-            throw new Error("entity publication target changed during publication");
-        }
-    }
-    removeOwnedFile(parentFd, name, expectedFd) {
-        if (!openMatches(parentFd, name, expectedFd, FILE_FLAGS))
-            return false;
-        fs.unlinkSync(fdPath(parentFd, name));
-        return true;
     }
-    removeCreatedDirectories(directories) {
-        for (const entry of [...directories].reverse()) {
-            if (!entry.created || !openMatches(entry.parentFd, entry.name, entry.fd, DIRECTORY_FLAGS))
-                continue;
+    removeAttemptDirectories() {
+        const paths = [...this.createdDirectories].sort((left, right) => right[0].split("/").length - left[0].split("/").length);
+        for (const [relativePath, expected] of paths) {
             try {
-                fs.rmdirSync(fdPath(entry.parentFd, entry.name));
-                syncDirectory(entry.parentFd);
+                const current = fs.lstatSync(expected.absolute, { bigint: true });
+                if (!sameDirectory(expected, current)) {
+                    this.createdDirectories.delete(relativePath);
+                    continue;
+                }
+                fs.rmdirSync(expected.absolute);
+                syncDirectoryBestEffort(path.dirname(expected.absolute));
+                this.createdDirectories.delete(relativePath);
             }
             catch (error) {
-                if (!["ENOTEMPTY", "EEXIST", "ENOENT"].includes(error.code ?? ""))
+                const code = error.code ?? "";
+                if (code === "ENOENT")
+                    this.createdDirectories.delete(relativePath);
+                else if (!["ENOTEMPTY", "EEXIST"].includes(code))
                     throw error;
             }
         }