@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/directory-durability.js

@@ -3,7 +3,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ensureAbsoluteDirectory } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { assertDirectoryReceiptCurrentSync, copyRetainedDirectoryReceipt, createDirectoryReceiptSync, directoryReceiptAuthority, directoryReceiptIdentity, ownDirectoryReceipt, } from "./directory-receipt.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
 function directoryOpenFlags() {
     if (process.platform === "win32") {
         return "r";
@@ -36,70 +39,42 @@ function unsupportedOutcome(error) {
     const code = error.code;
     return code ? { status: "unsupported", code } : { status: "unsupported" };
 }
-function assertDirectory(identity, pathname, label) {
-    if (identity.isSymbolicLink() || !identity.isDirectory()) {
-        throw new FsSafeError("not-file", `${label} must be a real directory: ${pathname}`);
-    }
-}
 async function createDirectoryReceipt(directoryPath, label) {
-    const resolvedPath = path.resolve(directoryPath);
-    const identity = fsSync.lstatSync(resolvedPath);
-    assertDirectory(identity, resolvedPath, label);
-    return {
-        path: resolvedPath,
-        realPath: fsSync.realpathSync.native(resolvedPath),
-        identity,
-    };
-}
-function createDirectoryReceiptSync(directoryPath, label) {
-    const resolvedPath = path.resolve(directoryPath);
-    const identity = fsSync.lstatSync(resolvedPath);
-    assertDirectory(identity, resolvedPath, label);
-    return {
-        path: resolvedPath,
-        realPath: fsSync.realpathSync(resolvedPath),
-        identity,
-    };
+    return createDirectoryReceiptSync(directoryPath, label, realpathSync.native);
 }
 async function assertDirectoryReceiptCurrent(receipt, label) {
-    const currentIdentity = fsSync.lstatSync(receipt.path);
-    assertDirectory(currentIdentity, receipt.path, label);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        (fsSync.realpathSync.native(receipt.path)) !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+    assertDirectoryReceiptCurrentSync(receipt, label, realpathSync.native);
 }
-function assertDirectoryReceiptCurrentSync(receipt, label) {
-    const currentIdentity = fsSync.lstatSync(receipt.path);
-    assertDirectory(currentIdentity, receipt.path, label);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        fsSync.realpathSync(receipt.path) !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+function assertOpenDirectoryIdentity(descriptor, receipt, label) {
+    inspectFileIdentitySync(() => {
+        const opened = fsSync.fstatSync(descriptor, { bigint: true });
+        if (!opened.isDirectory()) {
+            throw new FsSafeError("not-file", `${label} must be a real directory: ${receipt.path}`);
+        }
+        return opened;
+    }, directoryReceiptAuthority(receipt).identity);
 }
 async function assertOpenDirectoryCurrent(handle, receipt, label) {
-    const openedIdentity = fsSync.fstatSync(handle.fd);
-    assertDirectory(openedIdentity, receipt.path, label);
-    if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-        throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-    }
+    assertOpenDirectoryIdentity(handle.fd, receipt, label);
     await assertDirectoryReceiptCurrent(receipt, label);
 }
 class PinnedDirectoryImpl {
     receipt;
+    #authority;
     #handle;
     #label;
     #closed = false;
     constructor(handle, receipt, label) {
         this.#handle = handle;
-        this.receipt = receipt;
+        this.#authority = receipt;
+        this.receipt = copyRetainedDirectoryReceipt(receipt);
         this.#label = label;
     }
     async assertCurrent() {
         if (this.#closed) {
             throw new FsSafeError("helper-failed", `${this.#label} pin is already closed`);
         }
-        await assertOpenDirectoryCurrent(this.#handle, this.receipt, this.#label);
+        await assertOpenDirectoryCurrent(this.#handle, this.#authority, this.#label);
     }
     async sync() {
         await this.assertCurrent();
@@ -126,9 +101,11 @@ class PinnedDirectoryImpl {
 }
 export async function pinDirectory(directory, options = {}) {
     const label = options.label ?? "directory";
-    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    const receipt = typeof directory === "string"
+        ? await createDirectoryReceipt(directory, label)
+        : ownDirectoryReceipt(directory);
     await assertDirectoryReceiptCurrent(receipt, label);
-    const handle = await fs.open(receipt.path, directoryOpenFlags());
+    const handle = await fs.open(pathForWindowsFilesystem(receipt.path), directoryOpenFlags());
     try {
         await assertOpenDirectoryCurrent(handle, receipt, label);
         return new PinnedDirectoryImpl(handle, receipt, label);
@@ -140,7 +117,9 @@ export async function pinDirectory(directory, options = {}) {
 }
 export async function syncDirectory(directory, options = {}) {
     const label = options.label ?? "directory";
-    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    const receipt = typeof directory === "string"
+        ? await createDirectoryReceipt(directory, label)
+        : ownDirectoryReceipt(directory);
     let pinned;
     try {
         pinned = await pinDirectory(receipt, { label });
@@ -161,11 +140,13 @@ export async function syncDirectory(directory, options = {}) {
 }
 export function syncDirectorySync(directory, options = {}) {
     const label = options.label ?? "directory";
-    const receipt = typeof directory === "string" ? createDirectoryReceiptSync(directory, label) : directory;
+    const receipt = typeof directory === "string"
+        ? createDirectoryReceiptSync(directory, label)
+        : ownDirectoryReceipt(directory);
     assertDirectoryReceiptCurrentSync(receipt, label);
     let descriptor;
     try {
-        descriptor = fsSync.openSync(receipt.path, directoryOpenFlags());
+        descriptor = fsSync.openSync(pathForWindowsFilesystem(receipt.path), directoryOpenFlags());
     }
     catch (error) {
         if (!isWindowsDirectoryOpenUnsupported(error)) {
@@ -175,11 +156,7 @@ export function syncDirectorySync(directory, options = {}) {
         return unsupportedOutcome(error);
     }
     try {
-        const openedIdentity = fsSync.fstatSync(descriptor);
-        assertDirectory(openedIdentity, receipt.path, label);
-        if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-            throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-        }
+        assertOpenDirectoryIdentity(descriptor, receipt, label);
         assertDirectoryReceiptCurrentSync(receipt, label);
         try {
             fsSync.fsyncSync(descriptor);
@@ -210,7 +187,9 @@ export function syncDirectoryBestEffortSync(directoryPath) {
     }
 }
 async function findExistingAncestorReceipt(targetPath, label) {
-    let currentPath = path.resolve(targetPath);
+    assertNoWindowsPathAlias(targetPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    let currentPath = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(currentPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
     while (true) {
         try {
             return await createDirectoryReceipt(currentPath, label);
@@ -228,21 +207,29 @@ async function findExistingAncestorReceipt(targetPath, label) {
     }
 }
 export async function ensureDurableDirectory(options) {
-    const directoryPath = path.resolve(options.directoryPath);
     const label = options.label ?? "directory";
+    const requestedDirectoryPath = options.directoryPath;
+    assertNoWindowsPathAlias(requestedDirectoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const directoryPath = resolvePathPreservingWindowsRoot(requestedDirectoryPath);
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const expectedInput = options.expectedExistingIdentity;
+    const expectedIdentity = expectedInput && directoryReceiptIdentity(expectedInput);
     const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
     const targetExists = ancestorReceipt.path === directoryPath;
-    if (options.expectedExistingIdentity &&
-        (!targetExists || !sameFileIdentity(options.expectedExistingIdentity, ancestorReceipt.identity))) {
+    if (expectedIdentity && !targetExists) {
         throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
     }
+    if (expectedIdentity) {
+        inspectFileIdentitySync(() => directoryReceiptAuthority(ancestorReceipt).identity, expectedIdentity);
+    }
     const ancestor = await pinDirectory(ancestorReceipt, { label });
     const pinnedDirectories = [ancestor];
     try {
         await ancestor.assertCurrent();
         if (!targetExists) {
-            if (options.create) {
-                await options.create(directoryPath);
+            const create = options.create;
+            if (create) {
+                await Reflect.apply(create, options, [directoryPath]);
             }
             else {
                 const created = await ensureAbsoluteDirectory(directoryPath, {
@@ -291,7 +278,7 @@ export async function ensureDurableDirectory(options) {
         }
         await ancestor.assertCurrent();
         await assertDirectoryReceiptCurrent(finalReceipt, label);
-        return { ...finalReceipt, parentSync };
+        return Object.assign(copyRetainedDirectoryReceipt(finalReceipt), { parentSync });
     }
     finally {
         await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));

package/node_modules/@openclaw/fs-safe/dist/directory-entry-path.d.ts

@@ -0,0 +1,2 @@
+/** Strip only trailing separators: lstat must inspect the entry, not follow a leaf link. */
+export declare function directoryEntryPath(dir: string, platform?: NodeJS.Platform): string;

package/node_modules/@openclaw/fs-safe/dist/directory-entry-path.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+/** Strip only trailing separators: lstat must inspect the entry, not follow a leaf link. */
+export function directoryEntryPath(dir, platform = process.platform) {
+    const windows = platform === "win32";
+    if (typeof dir === "string") {
+        const last = dir[dir.length - 1];
+        if (last !== "/" && (!windows || last !== "\\"))
+            return dir;
+    }
+    let rootLength = (windows ? path.win32 : path.posix).parse(dir).root.length;
+    if (windows && /^[\\/]{2}[?.][\\/]UNC[\\/]/i.test(dir)) {
+        // Node parses the namespace prefix as the root; retain the complete UNC share.
+        const uncRoot = path.win32.parse(`\\\\${dir.slice(8)}`).root;
+        if (uncRoot.length > 1)
+            rootLength = Math.max(rootLength, uncRoot.length + 6);
+    }
+    let end = dir.length;
+    while (end > rootLength && (dir[end - 1] === "/" || (windows && dir[end - 1] === "\\")))
+        end--;
+    return end === rootLength || end === dir.length ? dir : dir.slice(0, end);
+}

package/node_modules/@openclaw/fs-safe/dist/directory-guard.d.ts

@@ -1,17 +1,24 @@
 import type { BigIntStats, Stats } from "node:fs";
+import { type ExactStatIdentity, type StatObservationReceipt } from "./stat-observation.js";
 export type AsyncDirectoryGuard<T extends Stats | BigIntStats = Stats> = {
     dir: string;
     realPath: string;
     stat: T;
 };
 export type AnyAsyncDirectoryGuard = AsyncDirectoryGuard<Stats | BigIntStats>;
-export type SyncDirectoryGuard = {
-    dir: string;
+export type SyncDirectoryGuard = AsyncDirectoryGuard;
+export type DirectoryIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
     realPath: string;
-    stat: Stats;
-};
+}>;
+export declare function readDirectoryIdentity(dir: string): Promise<DirectoryIdentity>;
+export declare function assertDirectoryIdentitySync(observedPath: string, expected: Pick<DirectoryIdentity, "dev" | "ino"> & {
+    realPath?: string;
+}): void;
 export declare function createAsyncDirectoryGuard(dir: string, options: {
     bigint: true;
+    initial?: BigIntStats;
 }): Promise<AsyncDirectoryGuard<BigIntStats>>;
 export declare function createAsyncDirectoryGuard(dir: string, options?: {
     bigint?: false;
@@ -19,13 +26,30 @@ export declare function createAsyncDirectoryGuard(dir: string, options?: {
 export declare function createAsyncDirectoryGuard(dir: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
-export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
 export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
-export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard): void;
+export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
+export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard | AnyAsyncDirectoryGuard): void;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
+    bigint: true;
+}): Promise<AsyncDirectoryGuard<BigIntStats>>;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
 export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
 export declare function inspectDirectoryIdentity(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): Promise<BigIntStats>;
-//# sourceMappingURL=directory-guard.d.ts.map
+export declare function observeDirectoryIdentitySync(dir: string, options: {
+    bigint: true;
+}): BigIntStats;
+export declare function observeDirectoryIdentitySync(dir: string, options?: {
+    bigint?: false;
+}): Stats;
+export declare function inspectDirectoryIdentitySync(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">, initial?: BigIntStats, platform?: NodeJS.Platform): BigIntStats;
+export type DirectoryObservationGuard = StatObservationReceipt & {
+    dir: string;
+    realPath: string;
+};
+export declare function extendDirectoryObservationGuard(observation: StatObservationReceipt, dir: string, realPath: string): DirectoryObservationGuard;
+export declare function inspectDirectoryObservationSync(dir: string, expected?: ExactStatIdentity): StatObservationReceipt;
+export declare function assertDirectoryObservationSync(dir: string, expected: ExactStatIdentity): Stats | BigIntStats;
+export declare function assertDirectoryObservationGuardSync(guard: DirectoryObservationGuard): void;

package/node_modules/@openclaw/fs-safe/dist/directory-guard.js

@@ -2,65 +2,99 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
-export async function createAsyncDirectoryGuard(dir, options) {
-    const stat = options?.bigint ? await inspectDirectoryIdentity(dir) : fsSync.lstatSync(dir);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    return { dir, realPath: fsSync.realpathSync.native(dir), stat };
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { directoryEntryPath } from "./directory-entry-path.js";
+import { assertStatObservationSync, inspectStatObservationSync, } from "./stat-observation.js";
+export async function readDirectoryIdentity(dir) {
+    const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+    return Object.freeze({ dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
 }
-export async function assertAsyncDirectoryGuard(guard) {
-    const stat = typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint"
-        ? await inspectDirectoryIdentity(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino })
-        : fsSync.lstatSync(guard.dir);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync.native(guard.dir) !== guard.realPath) {
+export function assertDirectoryIdentitySync(observedPath, expected) {
+    const operationPath = directoryOperationPath(observedPath);
+    const expectedDev = expected.dev;
+    const expectedIno = expected.ino;
+    const expectedRealPath = expected.realPath;
+    if (expectedRealPath !== undefined)
+        assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedDev, ino: expectedIno });
+    if (expectedRealPath === undefined)
+        return;
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
+export async function createAsyncDirectoryGuard(dir, options) {
+    return captureDirectoryGuard(dir, "native", options);
+}
 export function createSyncDirectoryGuard(dir) {
-    const stat = fsSync.lstatSync(dir);
+    return captureDirectoryGuard(dir, "normalized");
+}
+function captureDirectoryGuard(dir, mode, options) {
+    const operationPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
+        : fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    return { dir, realPath: fsSync.realpathSync(dir), stat };
+    const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return { dir, realPath, stat };
+}
+export async function assertAsyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "native");
 }
 export function assertSyncDirectoryGuard(guard) {
-    const stat = fsSync.lstatSync(guard.dir);
+    assertDirectoryGuard(guard, "normalized");
+}
+function assertDirectoryGuard(guard, mode) {
+    const dir = guard.dir;
+    const operationPath = directoryOperationPath(dir);
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    const expectedStat = guard.stat;
+    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
+        ? inspectDirectoryIdentityAtPathSync(operationPath, {
+            dev: expectedIdentity.dev,
+            ino: expectedIdentity.ino,
+        })
+        : fsSync.lstatSync(operationPath);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync(guard.dir) !== guard.realPath) {
+    // Native guards check identity first; normalized numeric guards preserve
+    // canonicalization errors before their final identity comparison.
+    if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
+        ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
-    let current = path.resolve(targetPath);
-    const root = path.resolve(rootReal);
-    while (current !== root) {
-        try {
-            return await createAsyncDirectoryGuard(current, options);
-        }
-        catch (error) {
-            if (!isNotFoundPathError(error)) {
-                throw error;
-            }
-            current = path.dirname(current);
-        }
-    }
-    return await createAsyncDirectoryGuard(root, options);
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
 }
 export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
-    let current = path.resolve(targetPath);
-    const root = path.resolve(rootReal);
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
+}
+function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
+    assertNoWindowsPathAlias(rootReal, "filesystem");
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    const root = resolvePathPreservingWindowsRoot(rootReal);
     while (current !== root) {
         try {
-            return createSyncDirectoryGuard(current);
+            return captureDirectoryGuard(current, mode, options);
         }
         catch (error) {
             if (!isNotFoundPathError(error)) {
@@ -69,14 +103,77 @@ export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
             current = path.dirname(current);
         }
     }
-    return createSyncDirectoryGuard(root);
+    return captureDirectoryGuard(root, mode, options);
 }
 // Recovery receipts must retain every identity bit, including on Windows.
 export async function inspectDirectoryIdentity(dir, expected) {
-    return await inspectFileIdentity(async () => {
-        const stat = fsSync.lstatSync(dir, { bigint: true });
+    return inspectDirectoryIdentitySync(dir, expected);
+}
+function directoryOperationPath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    return pathForWindowsFilesystem(directoryEntryPath(dir));
+}
+export function observeDirectoryIdentitySync(dir, options) {
+    const entryPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? fsSync.lstatSync(entryPath, { bigint: true })
+        : fsSync.lstatSync(entryPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw directoryComponentNotDirectoryError();
+    return stat;
+}
+export function inspectDirectoryIdentitySync(dir, expected, initial, platform = process.platform) {
+    const operationPath = directoryOperationPath(dir);
+    const expectedIdentity = expected === undefined
+        ? undefined
+        : { dev: expected.dev, ino: expected.ino };
+    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity, initial, platform);
+}
+function inspectDirectoryIdentityAtPathSync(operationPath, expected, initial, platform = process.platform) {
+    return inspectFileIdentitySync(() => {
+        // Traversal can supply the first exact observation. A bounded retry still
+        // uses the admitted operation path and retains every known identity bit.
+        const stat = initial ?? fsSync.lstatSync(operationPath, { bigint: true });
+        initial = undefined;
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected, platform);
+}
+export function extendDirectoryObservationGuard(observation, dir, realPath) {
+    const guard = observation;
+    guard.dir = dir;
+    guard.realPath = realPath;
+    return guard;
+}
+// Only stat/list receipts use this metadata fast path. Recovery and publication
+// callers retain the BigIntStats contract of inspectDirectoryIdentitySync.
+export function inspectDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return inspectStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
         if (stat.isSymbolicLink() || !stat.isDirectory())
             throw directoryComponentNotDirectoryError();
         return stat;
     }, expected);
 }
+export function assertDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return assertStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationGuardSync(guard) {
+    const dir = guard.dir;
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    assertDirectoryObservationSync(dir, guard.identity);
+    const realPath = realpathSync.native(directoryOperationPath(dir));
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/directory-mode-node.d.ts

@@ -1,8 +1,21 @@
 import { type BigIntStats } from "node:fs";
 import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export declare function nodeDarwinDirectoryMetadataFlags(): number;
+export declare function nodeDirectorySearchOnlyFlags(): {
+    flags: number;
+    proc: boolean;
+} | undefined;
 /** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
 export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
     expectedIdentity?: BigIntStats;
     ownerUid?: number;
 }): Promise<DirectoryModeOwner>;
-//# sourceMappingURL=directory-mode-node.d.ts.map
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): {
+    apply(mode: number, check?: () => void): void;
+    close(): void;
+};