@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/replace-file-descriptor.js

@@ -2,9 +2,8 @@ import { syncFileBestEffort, syncFileBestEffortSync } from "./file-sync.js";
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+import { ownDirectoryMode } from "./directory-mode-owner.js";
 export async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
     try {
@@ -15,7 +14,12 @@ export async function syncDirectoryBestEffort(fsModule, dirPath) {
         // Best-effort on platforms/filesystems that do not support directory fsync.
     }
     finally {
-        await handle?.close().catch(() => undefined);
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Best-effort close also covers synchronous adapter throws.
+        }
     }
 }
 export function syncDirectoryBestEffortSync(fsModule, dirPath) {
@@ -48,12 +52,7 @@ function assertDirectory(identity, dirPath) {
     if (identity.isSymbolicLink() || !identity.isDirectory()) {
         throw new FsSafeError("not-file", `Atomic replace parent must be a real directory: ${dirPath}`);
     }
-}
-function assertSameDirectory(expected, opened, dirPath) {
-    assertDirectory(opened, dirPath);
-    if (!sameFileIdentity(expected, opened)) {
-        throw new FsSafeError("path-mismatch", `Atomic replace parent changed before its mode could be applied: ${dirPath}`);
-    }
+    return identity;
 }
 export async function pinDirectoryForMode(params) {
     // Node does not enforce POSIX directory modes on Windows, and its directory
@@ -63,15 +62,16 @@ export async function pinDirectoryForMode(params) {
         return;
     }
     const expected = params.fsModule === fs
-        ? syncFs.lstatSync(params.dirPath) : await params.fsModule.lstat(params.dirPath);
-    assertDirectory(expected, params.dirPath);
+        ? inspectFileIdentitySync(() => assertDirectory(syncFs.lstatSync(params.dirPath, { bigint: true }), params.dirPath))
+        : await inspectFileIdentity(async () => assertDirectory(await params.fsModule.lstat(params.dirPath, { bigint: true }), params.dirPath));
     const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
     try {
         const owner = ownDirectoryMode({
             async inspect() {
-                const opened = params.fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
-                assertOwnedDirectory(expected, opened);
-                return opened.mode & 0o7777;
+                const opened = params.fsModule === fs
+                    ? inspectFileIdentitySync(() => assertDirectory(syncFs.fstatSync(handle.fd, { bigint: true }), params.dirPath), expected)
+                    : await inspectFileIdentity(async () => assertDirectory(await handle.stat({ bigint: true }), params.dirPath), expected);
+                return Number(opened.mode & 4095n);
             },
             chmod: (mode) => handle.chmod(mode),
             close: () => handle.close(),
@@ -98,11 +98,10 @@ export function applyDirectoryModeSync(params) {
     if (process.platform === "win32") {
         return;
     }
-    const expected = params.fsModule.lstatSync(params.dirPath);
-    assertDirectory(expected, params.dirPath);
+    const expected = inspectFileIdentitySync(() => assertDirectory(params.fsModule.lstatSync(params.dirPath, { bigint: true }), params.dirPath));
     const fd = params.fsModule.openSync(params.dirPath, directoryOpenFlags());
     try {
-        assertSameDirectory(expected, params.fsModule.fstatSync(fd), params.dirPath);
+        inspectFileIdentitySync(() => assertDirectory(params.fsModule.fstatSync(fd, { bigint: true }), params.dirPath), expected);
         // chmod ignores file-type bits; mask so raw stat modes are tolerated.
         params.fchmodSync?.(fd, params.mode & 0o7777);
     }

package/dist/replace-file-mode.d.ts

@@ -1,3 +1,2 @@
 import type { Stats } from "node:fs";
 export declare function inheritedRegularFileMode(stat: Stats): number;
-//# sourceMappingURL=replace-file-mode.d.ts.map

package/dist/replace-file-rename-policy.d.ts

@@ -4,4 +4,3 @@ export declare function validateRenameIdentity(policy: RenameIdentityPolicy | un
 export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
 export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
 export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;
-//# sourceMappingURL=replace-file-rename-policy.d.ts.map

package/dist/replace-file-temp-owner.d.ts

@@ -1,45 +1,45 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
+import { type TempPathRegistration } from "./temp-cleanup.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
 export type AtomicTempFailure = Readonly<{
     error: unknown;
 }>;
 export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
-export declare class AsyncAtomicTempOwner {
-    #private;
+declare class AtomicTempOwner<Resource> {
     readonly pathname: string;
+    protected resource: Resource | undefined;
+    protected recordedIdentity: BigIntStats | undefined;
+    protected exists: boolean;
+    protected unregister: TempPathRegistration;
     constructor(pathname: string);
     start(): void;
     readonly onIdentity: (identity: BigIntStats) => void;
+    get identity(): BigIntStats;
+    markRenamed(): void;
+    protected takeResource(): Resource | undefined;
+}
+export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
     adopt(temp: {
         handle: FileHandle;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
     assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
-    markRenamed(): void;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): Promise<void>;
 }
-export declare class SyncAtomicTempOwner {
-    #private;
-    readonly pathname: string;
-    constructor(pathname: string);
-    start(): void;
-    readonly onIdentity: (identity: BigIntStats) => void;
+export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
     adopt(temp: {
         fd: number;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
     assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
-    markRenamed(): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
@@ -47,4 +47,3 @@ export declare class SyncAtomicTempOwner {
     }): void;
 }
 export {};
-//# sourceMappingURL=replace-file-temp-owner.d.ts.map

package/dist/replace-file-temp-owner.js

@@ -57,6 +57,15 @@ function cleanupFailure(originalFailure, cleanupError) {
     }
     return isErrorValue(cleanupError) ? cleanupError : new Error(describeFailure(cleanupError));
 }
+function closeFailure(closeError, params, cleanupFailure) {
+    return {
+        error: cleanupFailure
+            ? new AggregateError([cleanupFailure.error, closeError], "Atomic temp cleanup and close failed")
+            : params.originalFailure
+                ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                : closeError,
+    };
+}
 async function cleanupOwnedPath(params) {
     try {
         await removeOwnedPath(params);
@@ -92,36 +101,48 @@ function cleanupOwnedPathSync(params) {
         return false;
     }
 }
-export class AsyncAtomicTempOwner {
+class AtomicTempOwner {
     pathname;
-    #handle;
-    #identity;
-    #exists = false;
-    #unregister;
+    resource;
+    recordedIdentity;
+    exists = false;
+    unregister;
     constructor(pathname) {
         this.pathname = pathname;
-        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
+        this.unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
     }
     start() {
-        this.#exists = true;
+        this.exists = true;
     }
     onIdentity = (identity) => {
-        this.#identity = identity;
-        this.#unregister.setIdentity(identity);
+        this.recordedIdentity = identity;
+        this.unregister.setIdentity(identity);
     };
-    adopt(temp) {
-        this.#handle = temp.handle;
-        this.onIdentity(temp.identity);
-    }
     get identity() {
-        if (!this.#identity)
+        if (!this.recordedIdentity)
             throw new Error("Atomic temp owner has no identity");
-        return this.#identity;
+        return this.recordedIdentity;
+    }
+    markRenamed() {
+        this.exists = false;
+        this.unregister();
+    }
+    takeResource() {
+        // A throwing close may already have released the descriptor for reuse.
+        const resource = this.resource;
+        this.resource = undefined;
+        return resource;
+    }
+}
+export class AsyncAtomicTempOwner extends AtomicTempOwner {
+    adopt(temp) {
+        this.resource = temp.handle;
+        this.onIdentity(temp.identity);
     }
     async assertCurrent(fsModule, pathname = this.pathname) {
         const opened = await inspectFileIdentity(async () => {
-            const stat = fsModule === fs ? syncFs.fstatSync(this.#handle.fd, { bigint: true })
-                : await this.#handle.stat({ bigint: true });
+            const stat = fsModule === fs ? syncFs.fstatSync(this.resource.fd, { bigint: true })
+                : await this.resource.stat({ bigint: true });
             assertOwnedFile(stat, pathname, false);
             return stat;
         }, this.identity);
@@ -134,7 +155,7 @@ export class AsyncAtomicTempOwner {
             }, opened);
         }
         catch (error) {
-            if (error.code === "ENOENT") {
+            if (hasErrorCode(error, "ENOENT")) {
                 throw missingOwnedFile(pathname, error);
             }
             throw error;
@@ -146,7 +167,7 @@ export class AsyncAtomicTempOwner {
             return;
         }
         catch (error) {
-            if (!(error instanceof FsSafeError) || error.code !== "path-mismatch" || !expectedHash) {
+            if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
@@ -156,7 +177,7 @@ export class AsyncAtomicTempOwner {
                 published = await fsModule.open(pathname, PUBLISHED_READ_FLAGS);
             }
             catch (error) {
-                if (error.code === "ELOOP") {
+                if (hasErrorCode(error, "ELOOP")) {
                     throw new FsSafeError("symlink", `Atomic replace published file became a symlink: ${pathname}`, {
                         cause: error,
                     });
@@ -178,30 +199,30 @@ export class AsyncAtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            const previousHandle = this.#handle;
-            this.#handle = undefined;
+            const previousHandle = this.takeResource();
             await previousHandle?.close();
-            this.#handle = published;
-            this.#identity = identity;
+            this.resource = published;
+            this.recordedIdentity = identity;
             published = undefined;
         }
         finally {
-            await published?.close().catch(() => undefined);
+            try {
+                await published?.close();
+            }
+            catch {
+                // Preserve the selected verification or previous-handle close failure.
+            }
         }
     }
-    markRenamed() {
-        this.#exists = false;
-        this.#unregister();
-    }
     async finish(params) {
         let deferredFailure;
-        let cleanupComplete = !this.#exists;
-        if (this.#exists) {
+        let cleanupComplete = !this.exists;
+        if (this.exists) {
             try {
                 cleanupComplete = await cleanupOwnedPath({
                     fsModule: params.fsModule,
                     pathname: this.pathname,
-                    identity: this.#identity,
+                    identity: this.recordedIdentity,
                     originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
@@ -211,54 +232,26 @@ export class AsyncAtomicTempOwner {
             }
         }
         if (cleanupComplete)
-            this.#unregister();
-        const handle = this.#handle;
-        this.#handle = undefined;
+            this.unregister();
+        const handle = this.takeResource();
         try {
             await handle?.close();
         }
         catch (closeError) {
-            deferredFailure = {
-                error: deferredFailure
-                    ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
-                    : params.originalFailure
-                        ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
-                        : closeError,
-            };
+            deferredFailure = closeFailure(closeError, params, deferredFailure);
         }
         if (deferredFailure)
             throw deferredFailure.error;
     }
 }
-export class SyncAtomicTempOwner {
-    pathname;
-    #fd;
-    #identity;
-    #exists = false;
-    #unregister;
-    constructor(pathname) {
-        this.pathname = pathname;
-        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
-    }
-    start() {
-        this.#exists = true;
-    }
-    onIdentity = (identity) => {
-        this.#identity = identity;
-        this.#unregister.setIdentity(identity);
-    };
+export class SyncAtomicTempOwner extends AtomicTempOwner {
     adopt(temp) {
-        this.#fd = temp.fd;
+        this.resource = temp.fd;
         this.onIdentity(temp.identity);
     }
-    get identity() {
-        if (!this.#identity)
-            throw new Error("Atomic temp owner has no identity");
-        return this.#identity;
-    }
     assertCurrent(fsModule, pathname = this.pathname) {
         const opened = inspectFileIdentitySync(() => {
-            const stat = fsModule.fstatSync(this.#fd, { bigint: true });
+            const stat = fsModule.fstatSync(this.resource, { bigint: true });
             assertOwnedFile(stat, pathname, false);
             return stat;
         }, this.identity);
@@ -270,7 +263,7 @@ export class SyncAtomicTempOwner {
             }, opened);
         }
         catch (error) {
-            if (error.code === "ENOENT") {
+            if (hasErrorCode(error, "ENOENT")) {
                 throw missingOwnedFile(pathname, error);
             }
             throw error;
@@ -282,7 +275,7 @@ export class SyncAtomicTempOwner {
             return;
         }
         catch (error) {
-            if (!(error instanceof FsSafeError) || error.code !== "path-mismatch" || !expectedHash) {
+            if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
@@ -292,7 +285,7 @@ export class SyncAtomicTempOwner {
                 publishedFd = fsModule.openSync(pathname, PUBLISHED_READ_FLAGS);
             }
             catch (error) {
-                if (error.code === "ELOOP") {
+                if (hasErrorCode(error, "ELOOP")) {
                     throw new FsSafeError("symlink", `Atomic replace published file became a symlink: ${pathname}`, {
                         cause: error,
                     });
@@ -312,11 +305,10 @@ export class SyncAtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            const previousFd = this.#fd;
-            this.#fd = undefined;
+            const previousFd = this.takeResource();
             fsModule.closeSync(previousFd);
-            this.#fd = publishedFd;
-            this.#identity = identity;
+            this.resource = publishedFd;
+            this.recordedIdentity = identity;
             publishedFd = undefined;
         }
         finally {
@@ -330,19 +322,15 @@ export class SyncAtomicTempOwner {
             }
         }
     }
-    markRenamed() {
-        this.#exists = false;
-        this.#unregister();
-    }
     finish(params) {
         let deferredFailure;
-        let cleanupComplete = !this.#exists;
-        if (this.#exists) {
+        let cleanupComplete = !this.exists;
+        if (this.exists) {
             try {
                 cleanupComplete = cleanupOwnedPathSync({
                     fsModule: params.fsModule,
                     pathname: this.pathname,
-                    identity: this.#identity,
+                    identity: this.recordedIdentity,
                     originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
@@ -352,21 +340,14 @@ export class SyncAtomicTempOwner {
             }
         }
         if (cleanupComplete)
-            this.#unregister();
-        if (this.#fd !== undefined) {
-            const fd = this.#fd;
-            this.#fd = undefined;
+            this.unregister();
+        const fd = this.takeResource();
+        if (fd !== undefined) {
             try {
                 params.fsModule.closeSync(fd);
             }
             catch (closeError) {
-                deferredFailure = {
-                    error: deferredFailure
-                        ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
-                        : params.originalFailure
-                            ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
-                            : closeError,
-                };
+                deferredFailure = closeFailure(closeError, params, deferredFailure);
             }
         }
         if (deferredFailure)

package/dist/replace-file.d.ts

@@ -56,4 +56,3 @@ export type ReplaceFileAtomicResult = {
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicWithDirectorySync(options: ReplaceFileAtomicOptions, syncParent?: (directoryPath: string) => Promise<unknown>): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
-//# sourceMappingURL=replace-file.d.ts.map

package/dist/replace-file.js

@@ -12,13 +12,7 @@ import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
-function isRetryableRenameError(error) {
-    return error.code === "EBUSY";
-}
-function isPermissionRenameError(error) {
-    const code = error.code;
-    return code === "EPERM" || code === "EEXIST";
-}
+import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
@@ -28,11 +22,12 @@ async function renameWithRetry(params) {
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 await sleep(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 await copyFallbackReplace({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -59,11 +54,12 @@ function renameWithRetrySync(params) {
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 sleepSync(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 copyFallbackReplaceSync({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -114,7 +110,7 @@ async function resolveMode(options, filePath) {
         stat = fsModule === fs ? syncFs.lstatSync(filePath) : await fsModule.lstat(filePath);
     }
     catch (error) {
-        if (error.code === "ENOENT") {
+        if (hasErrorCode(error, "ENOENT")) {
             return defaultMode;
         }
         throw error;
@@ -132,7 +128,7 @@ function resolveModeSync(options, filePath) {
         stat = fsModule.lstatSync(filePath);
     }
     catch (error) {
-        if (error.code !== "ENOENT") {
+        if (!hasErrorCode(error, "ENOENT")) {
             throw error;
         }
     }

package/dist/retained-directory-replacement.d.ts

@@ -23,4 +23,3 @@ export declare class RetainedDirectoryReplacement {
     close(): void;
 }
 export {};
-//# sourceMappingURL=retained-directory-replacement.d.ts.map

package/dist/root-boundary.d.ts

@@ -27,4 +27,3 @@ export declare function admitPathInsideRoot(params: {
         ino: bigint;
     }>) => void;
 }): AdmittedRootPath | undefined;
-//# sourceMappingURL=root-boundary.d.ts.map

package/dist/root-context.d.ts

@@ -41,4 +41,3 @@ export declare function resolvePathInRoot(root: RootContext, relativePath: strin
     rootWithSep: string;
     resolved: string;
 }>;
-//# sourceMappingURL=root-context.d.ts.map

package/dist/root-create-input.d.ts

@@ -14,4 +14,3 @@ export declare function rethrowCreateInputError(error: unknown): never;
 export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
 export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
 export {};
-//# sourceMappingURL=root-create-input.d.ts.map

package/dist/root-directory-creation.d.ts

@@ -10,4 +10,3 @@ export declare function mkdirPathFallback(root: RootContext, resolved: {
     rootReal: string;
     resolved: string;
 }, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;
-//# sourceMappingURL=root-directory-creation.d.ts.map

package/dist/root-directory-list.d.ts

@@ -36,4 +36,3 @@ export type RootDirectoryListingOptions = {
     admitEntry(): boolean;
 };
 export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
-//# sourceMappingURL=root-directory-list.d.ts.map

package/dist/root-directory-list.js

@@ -2,7 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
-import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, extendDirectoryObservationGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
 import { isNotFoundPathError } from "./path.js";
@@ -73,7 +73,18 @@ export async function assertRootDirectoryObservationGuard(root, guard) {
         }
         return;
     }
-    await assertRootIdentityCurrent(root);
+    if ("identity" in guard && typeof root.rootIdentity.dev === "bigint" &&
+        typeof root.rootIdentity.ino === "bigint") {
+        try {
+            assertDirectoryObservationSync(root.rootReal, root.rootIdentity);
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+    }
+    else {
+        await assertRootIdentityCurrent(root);
+    }
     try {
         if ("identity" in guard)
             assertDirectoryObservationGuardSync(guard);
@@ -215,9 +226,15 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     return entries;
 }
 export async function openRootDirectoryListing(root, directory, options) {
-    const guard = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+    const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
         throw normalizeDirectoryError(error);
     });
+    // Retain exact admission identities; metadata rechecks can use numeric Stats
+    // only when every identity component is losslessly representable.
+    const guard = extendDirectoryObservationGuard({
+        stat: admitted.stat,
+        identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+    }, admitted.dir, admitted.realPath);
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
         await assertRootDirectoryObservationGuard(root, guard);

package/dist/root-directory.d.ts

@@ -20,4 +20,3 @@ export declare function ensureDirectoryWithinRoot(params: {
     defaultDirName?: string;
     mode?: number;
 }): Promise<DirectoryResult>;
-//# sourceMappingURL=root-directory.d.ts.map

package/dist/root-entries.d.ts

@@ -8,4 +8,3 @@ export type RootEntriesOptions = {
     symlinks?: SymlinkPolicy;
 };
 export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;
-//# sourceMappingURL=root-entries.d.ts.map

package/dist/root-errors.d.ts

@@ -10,4 +10,3 @@ export declare function normalizePinnedPathError(error: unknown, details?: FsSaf
 export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
-//# sourceMappingURL=root-errors.d.ts.map

package/dist/root-file-final-admission.d.ts

@@ -16,6 +16,5 @@ export type CanonicalRootObservation = {
 export declare function observeCanonicalRoot(ioFs: RootFileAdmissionFs, rootPath: string): CanonicalRootObservation;
 export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs, root: Extract<CanonicalRootObservation, {
     ok: true;
-}>, boundaryLabel: string): PinnedOpenSyncFinalAdmission;
+}>, boundaryLabel: string, rejectHardlinks?: boolean): PinnedOpenSyncFinalAdmission;
 export {};
-//# sourceMappingURL=root-file-final-admission.d.ts.map

package/dist/root-file-final-admission.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { hardlinkedPathNotAllowedError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 function rootIdentityMismatch(cause) {
@@ -51,7 +52,7 @@ export function observeCanonicalRoot(ioFs, rootPath) {
 function resolveConsumedPath(ioFs, filePath) {
     return ioFs === fs ? realpathSync.native(filePath) : ioFs.realpathSync(filePath);
 }
-export function createRootFileFinalAdmission(ioFs, root, boundaryLabel) {
+export function createRootFileFinalAdmission(ioFs, root, boundaryLabel, rejectHardlinks = true) {
     const inspectRoot = (candidateRootPath, expected) => {
         inspectCanonicalRoot(ioFs, candidateRootPath, expected);
     };
@@ -69,7 +70,9 @@ export function createRootFileFinalAdmission(ioFs, root, boundaryLabel) {
             throw new FsSafeError("outside-workspace", `resolved path escapes ${boundaryLabel}`);
         }
         try {
-            inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            const current = inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            if (rejectHardlinks && current.isFile() && current.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
         }
         catch (error) {
             if (isExpectedPathError(error)) {