@openclaw/fs-safe 0.20.0 → 0.21.1

package/dist/root-directory-list.js

@@ -1,3 +1,4 @@
+import { isUtf8 } from "node:buffer";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -11,8 +12,25 @@ import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
+function directoryEntryName(bytes) {
+    if (!isUtf8(bytes)) {
+        throw new FsSafeError("invalid-path", "directory entry name is not valid UTF-8");
+    }
+    return bytes.toString("utf8");
+}
+async function readDirectoryEntryName(handle) {
+    const entry = await handle.read();
+    // Bun returns the raw Buffer directly; Node returns a Dirent whose name is a Buffer.
+    // Node's Dir types still declare only string names.
+    return entry === null ? undefined
+        : directoryEntryName(Buffer.isBuffer(entry) ? entry : entry.name);
+}
+function openDirectoryNames(directory) {
+    return fs.opendir(directory, { bufferSize: 1, encoding: "buffer" });
+}
 export function pathStatFromStats(stat) {
     const mtimeMs = typeof stat.mtimeMs === "bigint"
         ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
@@ -173,14 +191,7 @@ function normalizeInitialDirectoryError(error) {
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
-        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
-            receipt.directoryGuard.dir !== directory ||
-            receipt.target !== receipt.directoryGuard ||
-            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
-                !receipt.directoryGuard.stat.isDirectory())) {
-            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
-        }
-        guard = receipt.directoryGuard;
+        guard = directoryGuardFromReceipt(directory, receipt);
     }
     else {
         try {
@@ -192,13 +203,23 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
 }
+function directoryGuardFromReceipt(directory, receipt) {
+    if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+        receipt.directoryGuard.dir !== directory ||
+        receipt.target !== receipt.directoryGuard ||
+        (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+            !receipt.directoryGuard.stat.isDirectory())) {
+        throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+    }
+    return receipt.directoryGuard;
+}
 async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     let entries;
     try {
         const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
         if (beforeObservation)
             await beforeObservation(guard.realPath, withFileTypes);
-        const names = (await fs.readdir(guard.realPath)).sort();
+        const names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName).sort();
         entries = withFileTypes
             ? names.map(name => ({
                 name,
@@ -221,19 +242,30 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         await assertRootDirectoryObservationGuard(root, guard);
     return entries;
 }
-export async function openRootDirectoryListing(root, directory, options) {
-    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);
+export async function openRootDirectoryListing(root, directory, options, receipt) {
+    if (options.exactIdentity && options.order !== "filesystem")
+        throw new TypeError("exact entry identities require filesystem order");
+    let guard;
+    if (receipt) {
+        guard = directoryGuardFromReceipt(directory, receipt);
+    }
+    else {
+        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.
+        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);
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -248,23 +280,29 @@ export async function openRootDirectoryListing(root, directory, options) {
     const close = async () => {
         const owned = handle;
         handle = undefined;
-        await owned?.close();
+        try {
+            await owned?.close();
+        }
+        catch (error) {
+            options.onCleanupFailure?.(error);
+            throw error;
+        }
     };
     try {
         await assertCurrent();
         if (options.order === "filesystem") {
             // A one-entry buffer keeps the truncation lookahead independent of width.
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
         }
         else if (options.snapshot) {
-            snapshot = await listGuardedDirectoryPath(root, guard, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
             while (true) {
                 await assertCurrent();
-                const name = (await handle.read())?.name;
+                const name = await readDirectoryEntryName(handle);
                 await assertCurrent();
                 if (name === undefined)
                     break;
@@ -276,7 +314,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             await close();
         }
         else {
-            names = await fs.readdir(guard.realPath);
+            names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName);
         }
         await assertCurrent();
         names?.sort();
@@ -361,17 +399,30 @@ export async function openRootDirectoryListing(root, directory, options) {
                         return { kind: "limit", name: pendingLimit };
                     return;
                 }
-                await assertCurrent();
-                const name = (await handle.read())?.name;
-                await assertCurrent();
-                if (name === undefined)
-                    return;
-                if (!options.admitEntry())
-                    return { kind: "limit", name };
-                // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
-                await assertCurrent();
-                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+                for (;;) {
+                    await assertCurrent();
+                    const name = await readDirectoryEntryName(handle);
+                    await assertCurrent();
+                    if (name === undefined)
+                        return;
+                    if (!options.admitEntry())
+                        return { kind: "limit", name };
+                    // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                    const pathname = path.join(guard.realPath, name);
+                    let observed;
+                    try {
+                        observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname) };
+                    }
+                    catch (error) {
+                        await assertCurrent();
+                        if (options.skipVanished && isNotFoundPathError(error))
+                            continue;
+                        throw error;
+                    }
+                    await assertCurrent();
+                    return { kind: "entry", entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+                }
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

package/dist/root-handle-context.d.ts

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export declare function registerRootHandleContext(handle: object, context: RootContext): void;
+export declare function rootHandleContext(handle: object): RootContext;

package/dist/root-handle-context.js

@@ -0,0 +1,12 @@
+import { FsSafeError } from "./errors.js";
+const contexts = new WeakMap();
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export function registerRootHandleContext(handle, context) {
+    contexts.set(handle, context);
+}
+export function rootHandleContext(handle) {
+    const context = contexts.get(handle);
+    if (!context)
+        throw new FsSafeError("invalid-path", "watch requires a genuine fs-safe Root");
+    return context;
+}

package/dist/root-impl.d.ts

@@ -5,7 +5,7 @@ import { type ReadResult } from "./read-opened-file.js";
 import { type RootEntriesOptions } from "./root-entries.js";
 import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
-import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
+import { type RootWalkEntry, type RootWalkOptions, type RootWalkSymlinkPolicy } from "./root-walk.js";
 import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
@@ -54,7 +54,7 @@ export interface Root {
     }): Promise<DirEntry[]>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare class RootHandle implements Root {
     private readonly context;
@@ -97,7 +97,7 @@ export declare class RootHandle implements Root {
     }): Promise<DirEntry[]>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
     entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
-    walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 export declare function rootFromDirectoryGuard(guard: {

package/dist/root-impl.js

@@ -51,6 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from "node:crypto";
+import { registerRootHandleContext } from "./root-handle-context.js";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -85,7 +86,7 @@ import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-li
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -199,6 +200,7 @@ export class RootHandle {
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
+        registerRootHandleContext(this, context);
     }
     mutationOptions(options) {
         return {
@@ -409,9 +411,13 @@ export class RootHandle {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
             rootReal: this.context.rootReal,
+            observeRoot: () => createRootObservationGuard(this.context),
             stat: relative => this.stat(relative),
-            list: async (relative, listingOptions) => {
+            list: async (relative, listingOptions, receipt) => {
                 validatePinnedRelativePath(relative);
+                if (receipt) {
+                    return await openRootDirectoryListing(this.context, receipt.targetPath, listingOptions, receipt);
+                }
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },

package/dist/root-move-noreplace.js

@@ -4,7 +4,7 @@ import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard } from "./directory
 import { FsSafeError } from "./errors.js";
 import { assertMutationNotDenied } from "./deny-mutations.js";
 import { openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
-import { getNativeBinding } from "./native.js";
+import { requireNativeBinding } from "./native.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
@@ -78,8 +78,8 @@ export async function movePathNoReplaceNative(root, params, paths) {
             throw error;
         // Advisory fast rejection only. renameNoReplace owns the collision decision.
     }
-    const binding = getNativeBinding();
-    if (!binding || typeof binding.renameNoReplace !== "function") {
+    const binding = requireNativeBinding();
+    if (typeof binding.renameNoReplace !== "function") {
         throw new FsSafeError("helper-unavailable", "native no-replace move is unavailable");
     }
     const rootAdmission = await openNativeRootAdmission(binding, {

package/dist/root-walk.d.ts

@@ -1,17 +1,21 @@
+import type { DirectoryObservationGuard } from "./directory-guard.js";
+import { type RootPathObservationReceipt } from "./root-path.js";
 import type { RootDirectoryListing, RootDirectoryListingOptions } from "./root-directory-list.js";
 import type { PathStat } from "./types.js";
-export type RootWalkSymlinkPolicy = "skip" | "follow-within-root";
+export type RootWalkSymlinkPolicy = "skip" | "follow-within-root" | "include";
+type LegacyRootWalkSymlinkPolicy = Exclude<RootWalkSymlinkPolicy, "include">;
 export type RootWalkLimitBehavior = "truncate" | "throw";
 export type RootWalkDirectoryErrorBehavior = "throw" | "skip-and-report";
 export type RootWalkEntryFilterResult = "include" | "skip" | "skip-subtree";
-export type RootWalkDataEntryKind = "file" | "directory" | "other";
-export type RootWalkEntryKind = RootWalkDataEntryKind | "directory-error" | "truncated";
-export type RootWalkDataEntry = {
+export type RootWalkDataEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = "file" | "directory" | "other" | ("include" extends Policy ? "symlink" : never);
+export type RootWalkEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntryKind<Policy> | "directory-error" | "truncated";
+type WalkEntryOfKind<Kind extends RootWalkDataEntryKind<RootWalkSymlinkPolicy>> = {
     relativePath: string;
-    kind: RootWalkDataEntryKind;
+    kind: Kind;
     size: number;
 };
-export type RootWalkEntry = RootWalkDataEntry | {
+export type RootWalkDataEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = WalkEntryOfKind<RootWalkDataEntryKind> | ("include" extends Policy ? WalkEntryOfKind<"symlink"> : never);
+export type RootWalkEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntry<Policy> | {
     relativePath: string;
     kind: "truncated";
     size: 0;
@@ -21,21 +25,24 @@ export type RootWalkEntry = RootWalkDataEntry | {
     size: 0;
     error: unknown;
 };
-export type RootWalkEntryFilter = (entry: RootWalkDataEntry) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
-export type RootWalkOptions = {
+export type RootWalkEntryFilter<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = (entry: RootWalkDataEntry<Policy>) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
+export type RootWalkOptions<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = {
     maxDepth?: number;
     maxEntries?: number;
     order?: "sorted" | "filesystem";
-    symlinkPolicy: RootWalkSymlinkPolicy;
+    symlinkPolicy: Policy;
     signal?: AbortSignal;
     limitBehavior?: RootWalkLimitBehavior;
-    entryFilter?: RootWalkEntryFilter;
+    entryFilter?: RootWalkEntryFilter<Policy>;
     onDirectoryError?: RootWalkDirectoryErrorBehavior;
 };
+type AnyRootWalkOptions = RootWalkOptions | RootWalkOptions<"include"> | RootWalkOptions<RootWalkSymlinkPolicy>;
+type AnyRootWalkEntry = RootWalkEntry<RootWalkSymlinkPolicy>;
 type RootWalkCapability = {
     rootReal: string;
+    observeRoot(): Promise<DirectoryObservationGuard | undefined>;
     stat(relativePath: string): Promise<PathStat>;
-    list(relativePath: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+    list(relativePath: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;
 };
-export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
+export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: AnyRootWalkOptions): AsyncGenerator<AnyRootWalkEntry>;
 export {};

package/dist/root-walk.js

@@ -1,8 +1,14 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { expandRelativePathWithHome } from "./root-context.js";
-import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+import { resolveRootPath, resolveRootPathWithObservation, ROOT_PATH_ALIAS_POLICIES, RootPathObservationError, } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
+function filterEntry(options, entry) {
+    if (entry.kind === "symlink") {
+        return options.symlinkPolicy === "include" ? options.entryFilter?.(entry) ?? "include" : "skip";
+    }
+    return options.entryFilter?.(entry) ?? "include";
+}
 function validateBudget(name, value) {
     if (value === undefined)
         return Number.POSITIVE_INFINITY;
@@ -24,7 +30,7 @@ function limitEntry(relativePath) {
     return { relativePath, kind: "truncated", size: 0 };
 }
 export async function* walkRoot(root, relativePath, options) {
-    if (!["skip", "follow-within-root"].includes(options.symlinkPolicy)) {
+    if (!["skip", "follow-within-root", "include"].includes(options.symlinkPolicy)) {
         throw new TypeError(`invalid root walk symlink policy: ${String(options.symlinkPolicy)}`);
     }
     if (options.order !== undefined && !["sorted", "filesystem"].includes(options.order)) {
@@ -62,24 +68,50 @@ export async function* walkRoot(root, relativePath, options) {
             throw error;
         return { relativePath: directory, kind: "directory-error", size: 0, error };
     };
-    async function* visit(directory, depth) {
+    async function* visit(directory, depth, admittedChildPath) {
         options.signal?.throwIfAborted();
         let listing;
+        let canonicalDirectory;
         try {
             const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
-            const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
-            const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, expandedDirectory),
+            const noFollowChildSymlinks = depth > 0 && options.symlinkPolicy !== "follow-within-root";
+            const includeChild = depth > 0 && options.symlinkPolicy === "include";
+            const resolution = {
+                absolutePath: admittedChildPath ?? path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
-                policy: skipChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
-            });
-            if (skipChildSymlinks && resolvedDirectory.kind === "symlink")
-                return;
+                policy: noFollowChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            };
+            let receipt;
+            let resolvedDirectory;
+            if (includeChild) {
+                const rootGuard = await root.observeRoot();
+                if (!rootGuard) {
+                    throw new FsSafeError("helper-unavailable", "root walk requires an exact directory observation");
+                }
+                const observed = await resolveRootPathWithObservation({
+                    ...resolution,
+                    rootIdentity: rootGuard.identity,
+                }, { kind: "directory", rootGuard });
+                resolvedDirectory = observed.resolved;
+                receipt = observed.receipt;
+            }
+            else {
+                resolvedDirectory = await resolveRootPath(resolution);
+            }
+            if (noFollowChildSymlinks && resolvedDirectory.kind === "symlink") {
+                if (options.symlinkPolicy === "skip")
+                    return;
+                throw new FsSafeError("path-mismatch", `root walk directory became a symlink: ${directory}`);
+            }
             if (!resolvedDirectory.exists || resolvedDirectory.kind !== "directory") {
                 throw new FsSafeError("not-file", `root walk path is not a directory: ${directory || "."}`);
             }
+            if (includeChild && (!receipt || receipt.directoryGuard.realPath !== resolvedDirectory.canonicalPath)) {
+                throw new FsSafeError("path-mismatch", "root walk directory observation was not retained");
+            }
+            canonicalDirectory = resolvedDirectory.canonicalPath;
             if (visitedDirectories.has(resolvedDirectory.canonicalPath)) {
                 return;
             }
@@ -97,10 +129,10 @@ export async function* walkRoot(root, relativePath, options) {
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
                 admitEntry,
-            });
+            }, receipt);
         }
         catch (error) {
-            yield onDirectoryError(directory, error);
+            yield onDirectoryError(directory, error instanceof RootPathObservationError ? error.error : error);
             return;
         }
         // A thrown undefined still needs to be retained if closing also fails.
@@ -131,10 +163,9 @@ export async function* walkRoot(root, relativePath, options) {
                 const entry = next.entry;
                 let kind = entryKind(entry);
                 let size = entry.size;
-                if (kind === "symlink") {
-                    if (options.symlinkPolicy === "skip") {
-                        continue;
-                    }
+                if (kind === "symlink" && options.symlinkPolicy === "skip")
+                    continue;
+                if (kind === "symlink" && options.symlinkPolicy === "follow-within-root") {
                     const resolved = await resolveRootPath({
                         absolutePath: path.resolve(root.rootReal, child),
                         rootPath: root.rootReal,
@@ -149,7 +180,7 @@ export async function* walkRoot(root, relativePath, options) {
                     size = target.size;
                 }
                 const walkEntry = { relativePath: child, kind, size };
-                let filterResult = options.entryFilter?.(walkEntry) ?? "include";
+                let filterResult = filterEntry(options, walkEntry);
                 if (typeof filterResult !== "string") {
                     filterResult = (await filterResult) ?? "include";
                     options.signal?.throwIfAborted();
@@ -177,7 +208,7 @@ export async function* walkRoot(root, relativePath, options) {
                     yield onLimit(child);
                     return;
                 }
-                yield* visit(child, depth + 1);
+                yield* visit(child, depth + 1, options.symlinkPolicy === "include" ? path.join(canonicalDirectory, name) : undefined);
                 if (truncated)
                     return;
             }

package/dist/sidecar-lock-acquire.js

@@ -290,9 +290,9 @@ export async function acquireSidecarLock(options, context) {
                     }
                     await handle.writeFile(raw, "utf8");
                 }
-                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd), ownershipToken };
+                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd, { bigint: true }), ownershipToken };
                 createdSnapshot = snapshot;
-                if (snapshot.stat.nlink === 0) {
+                if (snapshot.stat.nlink === 0n) {
                     await handle.close();
                     handle = null;
                     await waitForRetry();
@@ -361,7 +361,7 @@ export async function acquireSidecarLock(options, context) {
                     if (handle) {
                         failedSnapshot ??= { payload: null };
                         try {
-                            failedSnapshot.stat = fsSync.fstatSync(handle.fd);
+                            failedSnapshot.stat = fsSync.fstatSync(handle.fd, { bigint: true });
                         }
                         catch {
                             // Best-effort cleanup of a failed exclusive create.

package/dist/sidecar-lock-reclaim.d.ts

@@ -1,4 +1,4 @@
-import { type Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { Root } from "./root-impl.js";
 export type SidecarLockStaleSnapshot = {
     lockPath: string;
@@ -9,7 +9,7 @@ export type SidecarLockStaleSnapshot = {
 export type SidecarLockSnapshot = {
     raw?: string;
     payload: unknown;
-    stat?: Stats;
+    stat?: Stats | BigIntStats;
     ownershipToken?: string;
 };
 type SidecarLockRawSnapshot = Omit<SidecarLockSnapshot, "payload"> & {

package/dist/sidecar-lock-reclaim.js

@@ -90,7 +90,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
                     raw,
-                    stat: opened.stat,
+                    stat: fsSync.fstatSync(opened.handle.fd, { bigint: true }),
                 };
             }
             finally {
@@ -99,7 +99,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         }
         let before;
         try {
-            before = fsSync.lstatSync(lockPath);
+            before = fsSync.lstatSync(lockPath, { bigint: true });
         }
         catch (error) {
             before = missingSnapshotPath(error);
@@ -132,7 +132,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = fsSync.fstatSync(handle.fd);
+        const opened = fsSync.fstatSync(handle.fd, { bigint: true });
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -144,7 +144,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
         let after;
         try {
-            after = fsSync.lstatSync(lockPath);
+            after = fsSync.lstatSync(lockPath, { bigint: true });
         }
         catch (error) {
             after = missingSnapshotPath(error);
@@ -159,7 +159,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
 }
 function lstatSidecarLockSync(lockPath) {
     try {
-        return fsSync.lstatSync(lockPath);
+        return fsSync.lstatSync(lockPath, { bigint: true });
     }
     catch (error) {
         return missingSnapshotPath(error);
@@ -189,7 +189,7 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = fsSync.fstatSync(fd);
+        const opened = fsSync.fstatSync(fd, { bigint: true });
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);

package/dist/sidecar-lock.js

@@ -50,7 +50,7 @@ function resolveManagerState(key) {
 function snapshotMatchesSync(lockPath, observed) {
     let fd;
     try {
-        const beforeStat = fsSync.lstatSync(lockPath);
+        const beforeStat = fsSync.lstatSync(lockPath, { bigint: true });
         if (!beforeStat.isFile()) {
             return false;
         }
@@ -60,17 +60,17 @@ function snapshotMatchesSync(lockPath, observed) {
                 : 0) |
             (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
         fd = fsSync.openSync(lockPath, openFlags);
-        const openedStat = fsSync.fstatSync(fd);
+        const openedStat = fsSync.fstatSync(fd, { bigint: true });
         // Token-owned files can have different descriptor/path identities on VirtioFS.
         // Require a known descriptor identity without rejecting that supported drift.
         if (!openedStat.isFile() || !sameFileIdentityForCleanup(openedStat, openedStat)) {
             return false;
         }
-        if (observed.raw !== undefined && openedStat.size !== Buffer.byteLength(observed.raw)) {
+        if (observed.raw !== undefined && openedStat.size !== BigInt(Buffer.byteLength(observed.raw))) {
             return false;
         }
         const raw = fsSync.readFileSync(fd, "utf8");
-        const afterStat = fsSync.lstatSync(lockPath);
+        const afterStat = fsSync.lstatSync(lockPath, { bigint: true });
         if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
             return false;
         }