@openclaw/openshell-sandbox 2026.10.5-beta.3 → 2026.10.10-beta.1

package/node_modules/@openclaw/fs-safe/dist/copy-link.js

@@ -0,0 +1,170 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { statIdentityFromNative } from "./native-stat-identity.js";
+import { getNativeBinding } from "./native.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { timestampSeconds } from "./copy-metadata.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { noReplaceUnavailable } from "./native-noreplace.js";
+import { createSuppressedError } from "./suppressed-error.js";
+/** Shared by tree byte copying and per-file copying; never resolves the target. */
+export async function readCopyLinkTarget(source) {
+    return await fsp.readlink(source, { encoding: "buffer" });
+}
+export function assertCopyLinkAvailable() {
+    const native = getNativeBinding();
+    if (process.platform === "darwin" && !native?.createCopySymlink) {
+        throw new FsSafeError("helper-unavailable", "exclusive macOS link copying requires the native helper; link(2) follows its source");
+    }
+    if (process.platform === "win32" && (!native?.copyLinkExclusive || !native.publishCopyLink || !native.removeCopyLink)) {
+        throw new FsSafeError("helper-unavailable", "copying Windows links without following them requires the native helper");
+    }
+    if (native && process.platform !== "win32" && !native.createCopySymlink) {
+        throw new FsSafeError("helper-unavailable", "native link copying is unavailable");
+    }
+}
+export async function admitCopyLink(sourcePath, preserveMetadata, signal) {
+    const parent = await createAsyncDirectoryGuard(path.dirname(sourcePath), { bigint: true });
+    sourcePath = path.join(parent.realPath, path.basename(sourcePath));
+    const identity = fs.lstatSync(sourcePath, { bigint: true });
+    if (!identity.isSymbolicLink())
+        return undefined;
+    const target = process.platform === "win32" ? undefined : await readCopyLinkTarget(sourcePath);
+    const verifySource = async () => {
+        signal?.throwIfAborted();
+        await assertAsyncDirectoryGuard(parent);
+        const current = inspectFileIdentitySync(() => fs.lstatSync(sourcePath, { bigint: true }), identity);
+        if (!current.isSymbolicLink() || current.mtimeNs !== identity.mtimeNs || current.ctimeNs !== identity.ctimeNs) {
+            throw new FsSafeError("path-mismatch", "copy source link changed");
+        }
+    };
+    await verifySource();
+    return { kind: "link", stageBeforePublish: true, sourcePath, identity, target, preserveMetadata, signal, verifySource };
+}
+/** The caller has admitted the destination parent under Root's mutation policy. */
+export async function copyLinkAtParent(params, input, parent, native) {
+    const temporaryName = `.fs-safe-${randomUUID()}.tmp`;
+    const temporaryPath = path.join(parent.realPath, temporaryName);
+    const destination = path.join(parent.realPath, params.basename);
+    let identity;
+    let sourceParent;
+    let failure;
+    const assertStage = () => {
+        assertSyncDirectoryGuard(parent);
+        const stat = inspectFileIdentitySync(() => fs.lstatSync(temporaryPath, { bigint: true }), identity);
+        if (!stat.isSymbolicLink() || stat.nlink !== 1n)
+            throw new FsSafeError("path-mismatch", "copy link stage changed");
+    };
+    try {
+        await input.verifySource();
+        await assertAsyncDirectoryGuard(parent);
+        if (process.platform === "win32") {
+            if (!native?.binding.copyLinkExclusive)
+                throw new FsSafeError("helper-unavailable", "native Windows link copying is unavailable");
+            const sourceGuard = await createAsyncDirectoryGuard(path.dirname(input.sourcePath), { bigint: true });
+            sourceParent = await fsp.open(sourceGuard.realPath, fs.constants.O_RDONLY);
+            inspectFileIdentitySync(() => fs.fstatSync(sourceParent.fd, { bigint: true }), sourceGuard.stat);
+            await input.verifySource();
+            params.assertBeforeMutation?.();
+            assertSyncDirectoryGuard(parent);
+            identity = native.binding.copyLinkExclusive(sourceParent.fd, path.basename(input.sourcePath), native.fd, temporaryName, input.identity.dev, input.identity.ino, input.preserveMetadata, params.mode);
+        }
+        else {
+            if (native && !native.binding.createCopySymlink)
+                throw new FsSafeError("helper-unavailable", "native link copying is unavailable");
+            params.assertBeforeMutation?.();
+            assertSyncDirectoryGuard(parent);
+            if (native?.binding.createCopySymlink) {
+                const created = native.binding.createCopySymlink(native.fd, temporaryName, input.target, params.mode, input.preserveMetadata ? input.identity.atimeNs : undefined, input.preserveMetadata ? input.identity.mtimeNs : undefined);
+                identity = { dev: statIdentityFromNative(created.dev), ino: statIdentityFromNative(created.ino) };
+                if (created.errorCode)
+                    throw Object.assign(new Error(created.errorMessage), { code: created.errorCode });
+            }
+            else {
+                fs.symlinkSync(input.target, temporaryPath);
+                identity = fs.lstatSync(temporaryPath, { bigint: true });
+            }
+            if (!native && input.preserveMetadata) {
+                assertStage();
+                fs.lutimesSync(temporaryPath, timestampSeconds(input.identity.atimeNs), timestampSeconds(input.identity.mtimeNs));
+            }
+        }
+        assertStage();
+        await input.verifySource();
+        params.assertBeforeMutation?.();
+        input.signal?.throwIfAborted();
+        assertStage();
+        if (process.platform === "win32") {
+            native.binding.publishCopyLink(native.fd, temporaryName, params.basename, identity.dev, identity.ino);
+        }
+        else if (native) {
+            const renameNoReplace = native.binding.renameNoReplace;
+            if (!renameNoReplace)
+                throw new FsSafeError("helper-unavailable", "native link publication is unavailable");
+            try {
+                renameNoReplace(native.fd, temporaryName, native.fd, params.basename);
+            }
+            catch (error) {
+                const unavailable = noReplaceUnavailable(error, "link copy publication", true);
+                if (!unavailable || isFsSafeNativeRequired() || process.platform !== "linux")
+                    throw error;
+                // Linux link(2) links the symlink inode itself, never its target.
+                assertStage();
+                fs.linkSync(temporaryPath, destination);
+            }
+        }
+        else {
+            fs.linkSync(temporaryPath, destination);
+        }
+        params.onPublished?.(identity);
+        assertSyncDirectoryGuard(parent);
+        const final = inspectFileIdentitySync(() => fs.lstatSync(destination, { bigint: true }), identity);
+        if (!final.isSymbolicLink())
+            throw new FsSafeError("path-mismatch", "published copy link changed");
+        if (params.sync !== false)
+            await syncDirectoryBestEffort(parent.realPath);
+        await input.verifySource();
+        return identity;
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        let cleanupFailure;
+        try {
+            if (identity) {
+                assertSyncDirectoryGuard(parent);
+                const remaining = fs.lstatSync(temporaryPath, { bigint: true, throwIfNoEntry: false });
+                if (remaining) {
+                    inspectFileIdentitySync(() => remaining, identity);
+                    if (!remaining.isSymbolicLink())
+                        throw new FsSafeError("path-mismatch", "copy link cleanup identity changed");
+                    if (process.platform === "win32")
+                        native.binding.removeCopyLink(native.fd, temporaryName, identity.dev, identity.ino);
+                    else
+                        fs.unlinkSync(temporaryPath);
+                }
+            }
+        }
+        catch (error) {
+            cleanupFailure = { error };
+        }
+        try {
+            await sourceParent?.close();
+        }
+        catch (error) {
+            cleanupFailure = { error: cleanupFailure
+                    ? createSuppressedError(error, cleanupFailure.error, "copy link cleanup and close failed") : error };
+        }
+        if (cleanupFailure)
+            throw failure
+                ? createSuppressedError(cleanupFailure.error, failure.error, "copy link operation and cleanup failed")
+                : cleanupFailure.error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/copy-metadata.d.ts

@@ -0,0 +1,9 @@
+import { type BigIntStats } from "node:fs";
+export type CopyMetadata = Readonly<{
+    atimeNs: bigint;
+    mtimeNs: bigint;
+    restoreNative?: (fd: number) => void;
+}>;
+export declare function timestampSeconds(nanoseconds: bigint): string;
+export declare function captureCopyMetadata(fd: number, stat: BigIntStats): CopyMetadata;
+export declare function restoreCopyMetadata(fd: number, metadata: CopyMetadata | undefined): void;

package/node_modules/@openclaw/fs-safe/dist/copy-metadata.js

@@ -0,0 +1,39 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+export function timestampSeconds(nanoseconds) {
+    // Numeric strings retain fractional and pre-epoch times in Node's utimes API.
+    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
+}
+export function captureCopyMetadata(fd, stat) {
+    let restoreNative;
+    const native = getNativeBinding();
+    if (process.platform === "win32") {
+        if (native?.readCopyMetadata && native.restoreCopyMetadata) {
+            const snapshot = native.readCopyMetadata(fd);
+            const restore = native.restoreCopyMetadata.bind(native);
+            restoreNative = target => restore(target, snapshot);
+        }
+        else if (isFsSafeNativeRequired()) {
+            throw new FsSafeError("helper-unavailable", "native Windows copy metadata preservation is unavailable");
+        }
+    }
+    else if (native?.restoreCopyFileTimes) {
+        const restore = native.restoreCopyFileTimes.bind(native);
+        const { atimeNs, mtimeNs } = stat;
+        restoreNative = target => restore(target, atimeNs, mtimeNs);
+    }
+    else if (isFsSafeNativeRequired()) {
+        throw new FsSafeError("helper-unavailable", "native copy timestamp preservation is unavailable");
+    }
+    return Object.freeze({ atimeNs: stat.atimeNs, mtimeNs: stat.mtimeNs, restoreNative });
+}
+export function restoreCopyMetadata(fd, metadata) {
+    if (!metadata)
+        return;
+    if (metadata.restoreNative)
+        metadata.restoreNative(fd);
+    else
+        fs.futimesSync(fd, timestampSeconds(metadata.atimeNs), timestampSeconds(metadata.mtimeNs));
+}

package/node_modules/@openclaw/fs-safe/dist/copy-path-admission.js

@@ -5,6 +5,7 @@ import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { resolveRootPathSync, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+import { hasWindowsPathAlias } from "./windows-path-alias.js";
 function admitUncachedCopyPath(input, create = false, admittedRoot) {
     if (!path.isAbsolute(input.rootPath) || !path.isAbsolute(input.absolutePath)) {
         throw new FsSafeError("invalid-path", "copy roots and paths must be absolute");
@@ -50,15 +51,23 @@ export function createCopyPathAdmissionCache() {
     const assertParent = ({ root, parent, chain }) => {
         assertSyncDirectoryGuard(root);
         for (const guard of chain) {
+            // The full parent guard immediately below includes this exact identity.
+            if (guard === parent)
+                continue;
             inspectDirectoryIdentitySync(guard.dir, { dev: BigInt(guard.stat.dev), ino: BigInt(guard.stat.ino) });
         }
-        assertSyncDirectoryGuard(parent);
+        if (parent !== root)
+            assertSyncDirectoryGuard(parent);
         assertSyncDirectoryGuard(root);
     };
     const admit = (input, create = false) => {
         // Keep the public resolver for Windows aliases and noncanonical spellings,
         // including raw dot segments whose traversal must not be normalized away.
-        if (process.platform === "win32" || !path.isAbsolute(input.rootPath) ||
+        const ordinaryWindowsPath = process.platform !== "win32" || (/^[a-z]:\\/iu.test(input.rootPath) &&
+            !hasWindowsPathAlias(input.rootPath, "filesystem") &&
+            !hasWindowsPathAlias(input.absolutePath, "filesystem") &&
+            !input.absolutePath.slice(3).split("\\").some(segment => /[. ]$/u.test(segment) || segment.includes("~")));
+        if (!ordinaryWindowsPath || !path.isAbsolute(input.rootPath) ||
             !path.isAbsolute(input.absolutePath) || input.rootPath.includes("\0") || input.absolutePath.includes("\0") ||
             path.resolve(input.rootPath) !== input.rootPath || path.resolve(input.absolutePath) !== input.absolutePath ||
             !input.absolutePath.startsWith(input.rootPath.endsWith(path.sep) ? input.rootPath : `${input.rootPath}${path.sep}`)) {

package/node_modules/@openclaw/fs-safe/dist/copy-root-file-sync.d.ts

@@ -1,13 +1,11 @@
+import { type ExactIdentityReceipt, type ExactFileIdentity } from "./file-identity.js";
 import { type CopyPath } from "./copy-path-admission.js";
 import { type CopyCloneMode } from "./copy-policy.js";
 import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
 export type CopyRootFileSyncOptions = {
     source: CopyPath;
     destination: CopyPath;
-    expectedSourceIdentity?: {
-        dev: bigint;
-        ino: bigint;
-    };
+    expectedSourceIdentity?: ExactFileIdentity | ExactIdentityReceipt;
     clone?: CopyCloneMode;
     maxBytes?: number;
     mode?: number;

package/node_modules/@openclaw/fs-safe/dist/copy-root-file-sync.js

@@ -1,3 +1,4 @@
+import { identityFromReceipt } from "./file-identity.js";
 import fs, {} from "node:fs";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
@@ -50,7 +51,8 @@ function copyRootFileWithAdmissionSync(options, cache) {
     const targetInput = options.destination;
     const targetPath = { rootPath: targetInput.rootPath, absolutePath: targetInput.absolutePath };
     const expectedInput = options.expectedSourceIdentity;
-    const expectedSourceIdentity = expectedInput === undefined ? undefined : { dev: expectedInput.dev, ino: expectedInput.ino };
+    const expected = expectedInput === undefined ? undefined : identityFromReceipt(expectedInput);
+    const expectedSourceIdentity = expected && { dev: expected.dev, ino: expected.ino };
     const clone = resolveCopyCloneMode(options.clone, "never");
     const maxBytes = normalizeMaxBytes(options.maxBytes);
     const mode = options.mode;
@@ -68,7 +70,7 @@ function copyRootFileWithAdmissionSync(options, cache) {
     let parentOpen = false;
     let target;
     let identity;
-    const native = getNativeBinding();
+    const native = process.platform !== "win32" ? getNativeBinding("copyFileExclusiveSync", "removeStagedFile") : getNativeBinding();
     const nativeCopy = process.platform !== "win32" && native?.copyFileExclusiveSync && native.removeStagedFile
         ? native.copyFileExclusiveSync.bind(native) : undefined;
     try {

package/node_modules/@openclaw/fs-safe/dist/copy-tree-portable.js

@@ -4,12 +4,9 @@ import fsp, {} from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { assertExclusiveCreateLeaf } from "./exclusive-create.js";
+import { timestampSeconds } from "./copy-metadata.js";
+import { readCopyLinkTarget } from "./copy-link.js";
 import { assertStagedDirectoryCurrent, exactIdentityMatches, openStagedDirectory, } from "./staged-directory.js";
-function timestampSeconds(nanoseconds) {
-    // Dates discard sub-millisecond precision; negative numbers mean "now" in
-    // Node's utimes API. Numeric strings retain fractional, pre-epoch timestamps.
-    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
-}
 /** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
 export async function copyOwnedTree(source, destination, options) {
     const callerSignal = options.signal ? AbortSignal.any([options.signal]) : undefined;
@@ -145,7 +142,7 @@ export async function copyOwnedTree(source, destination, options) {
                 else if (child.isSymbolicLink()) {
                     const link = process.platform === "win32"
                         ? await fsp.readlink(childSource)
-                        : await fsp.readlink(childSource, { encoding: "buffer" });
+                        : await readCopyLinkTarget(childSource);
                     let type;
                     if (process.platform === "win32") {
                         // Older Node releases infer link type from the destination, where a

package/node_modules/@openclaw/fs-safe/dist/copy.js

@@ -21,7 +21,7 @@ function closeDescriptor(fd, failure) {
 }
 /** Inspect an existing real directory without creating probe files. */
 export function probeTreeClone(parentPath) {
-    const native = getNativeBinding();
+    const native = getNativeBinding("probeTreeClone");
     if (!native)
         return undefined;
     const parent = openStagedDirectory(assertAbsolutePathInput(parentPath));
@@ -64,9 +64,9 @@ async function materializeTree(source, destination, options, policy) {
         throw new FsSafeError("invalid-path", "clone concurrency must be an integer between 1 and 32");
     }
     const native = policy === "always"
-        ? requireNativeBinding()
+        ? requireNativeBinding("probeTreeClone", "cloneTree")
         : policy === "auto"
-            ? getNativeBinding()
+            ? getNativeBinding("probeTreeClone", "cloneTree")
             : undefined;
     const target = assertAbsolutePathInput(destination);
     const name = path.basename(target);

package/node_modules/@openclaw/fs-safe/dist/create.js

@@ -204,7 +204,7 @@ function privateDirectoryBackend() {
     if (getFsSafeNativeConfig().mode === "require") {
         throw new FsSafeError("helper-unavailable", "private directory creation requires an up-to-date native parent identity capability");
     }
-    warnNativeFallback("windows-private-directory", "Private Windows directory creation uses a slower built-in system command.");
+    warnNativeFallback("windows-private-directory", "Private Windows directory creation launches the packaged .NET helper for each check or creation.", "createPrivateDirectoryWithParentIdentity");
     return undefined;
 }
 export async function createDirectory(targetPath, options = {}) {

package/node_modules/@openclaw/fs-safe/dist/creation-boundary.js

@@ -53,17 +53,17 @@ export function assertPrivateFileCreationAvailable() {
         typeof native.verifyPrivateWindowsFile !== "function")
         unavailable();
 }
-function commandFallback() {
+function commandFallback(capability) {
     if (getFsSafeNativeConfig().mode === "require")
         unavailable();
-    warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
+    warnNativeFallback("windows-private-creation", "Private Windows creation launches the packaged .NET helper for each check or creation.", capability);
 }
 function creationOperation(name) {
     const native = getNativeBinding();
     const operation = native?.[name];
     if (typeof operation === "function")
         return operation.bind(native);
-    commandFallback();
+    commandFallback(name);
     return undefined;
 }
 /** Full Windows identity, with security validation when requested; no repairs. */
@@ -300,7 +300,10 @@ export function assertBeforeCreation(selected, permissions, assertion, kind) {
     if (permissions.private)
         assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
     assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
-    selected.assertParent();
+    // Ordinary callers enter immediately after prepareCreationPath's identical fence.
+    // A callback or private ACL inspection needs a fresh observation afterward.
+    if (assertion !== undefined || permissions.private)
+        selected.assertParent();
     if (permissions.private && kind === "directory")
         assertDarwinPrivateDirectoryMode(permissions.mode);
     if (permissions.private)

package/node_modules/@openclaw/fs-safe/dist/darwin-acl.d.ts

@@ -0,0 +1,12 @@
+export type DarwinAclInspection = {
+    kind: "none";
+} | {
+    kind: "present";
+    inheritsToFiles: boolean;
+    inheritsToDirectories: boolean;
+} | {
+    kind: "unknown";
+    reason: string;
+};
+/** Inspect one no-follow descriptor. Unknown is never evidence of no ACL. */
+export declare function inspectDarwinAcl(path: string): DarwinAclInspection;

package/node_modules/@openclaw/fs-safe/dist/darwin-acl.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import { getNativeBinding } from "./native.js";
+/** Inspect one no-follow descriptor. Unknown is never evidence of no ACL. */
+export function inspectDarwinAcl(path) {
+    if (process.platform !== "darwin")
+        return { kind: "unknown", reason: "unsupported-platform" };
+    let fd;
+    try {
+        const native = getNativeBinding();
+        if (!native?.inspectDarwinAcl)
+            return { kind: "unknown", reason: "helper-unavailable" };
+        fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        const facts = native.inspectDarwinAcl(fd);
+        if (facts.state === "absent" || facts.state === "empty")
+            return { kind: "none" };
+        if (facts.state === "present" && typeof facts.inheritsToFiles === "boolean" &&
+            typeof facts.inheritsToDirectories === "boolean") {
+            return { kind: "present", inheritsToFiles: facts.inheritsToFiles, inheritsToDirectories: facts.inheritsToDirectories };
+        }
+        return { kind: "unknown", reason: "incomplete-acl-facts" };
+    }
+    catch (error) {
+        return { kind: "unknown", reason: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}

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

@@ -1,5 +1,6 @@
+import type { ExactFileIdentity, ExactIdentityReceipt } from "./exact-identity.js";
 import { type BigIntStats, type Stats } from "node:fs";
-import type { FileIdentityStat } from "./file-identity.js";
+import type { FileIdentityInput } from "./file-identity.js";
 export type DirectorySyncOutcome = {
     status: "synced";
 } | {
@@ -10,14 +11,16 @@ export type DirectoryReceipt<T extends Stats | BigIntStats = Stats> = {
     path: string;
     realPath: string;
     identity: T;
+    exactIdentity?: ExactFileIdentity;
 };
+export type ExactDirectoryReceipt = DirectoryReceipt & ExactIdentityReceipt;
 export type DurableDirectoryReceipt = DirectoryReceipt & {
     parentSync: DirectorySyncOutcome | {
         status: "not-needed";
     };
 };
 export type PinnedDirectory = {
-    readonly receipt: DirectoryReceipt;
+    readonly receipt: ExactDirectoryReceipt;
     assertCurrent(): Promise<void>;
     sync(): Promise<DirectorySyncOutcome>;
     close(): Promise<void>;
@@ -26,7 +29,7 @@ export type EnsureDurableDirectoryOptions = {
     directoryPath: string;
     label?: string;
     mode?: number;
-    expectedExistingIdentity?: FileIdentityStat;
+    expectedExistingIdentity?: FileIdentityInput;
     create?: (directoryPath: string) => Promise<void>;
 };
 export declare function pinDirectory(directory: string | DirectoryReceipt<Stats | BigIntStats>, options?: {
@@ -40,4 +43,4 @@ export declare function syncDirectorySync(directory: string | DirectoryReceipt<S
 }): DirectorySyncOutcome;
 export declare function syncDirectoryBestEffort(directoryPath: string): Promise<void>;
 export declare function syncDirectoryBestEffortSync(directoryPath: string): void;
-export declare function ensureDurableDirectory(options: EnsureDurableDirectoryOptions): Promise<DurableDirectoryReceipt>;
+export declare function ensureDurableDirectory(options: EnsureDurableDirectoryOptions): Promise<DurableDirectoryReceipt & ExactIdentityReceipt>;

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

@@ -1,7 +1,7 @@
 import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { hasSafeFileIdentity, sameFileIdentity } from "./file-identity.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
@@ -9,6 +9,9 @@ import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservi
 import { realpathSync } from "./realpath.js";
 import { directoryEntryPath } from "./directory-entry-path.js";
 import { assertStatObservationSync, inspectStatObservationSync, } from "./stat-observation.js";
+// Numeric metadata is retained for existing internal consumers; rounded IDs
+// must never become authority for a later comparison.
+const exactGuardIdentities = new WeakMap();
 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 });
@@ -43,9 +46,19 @@ export function captureDirectoryGuard(dir, mode, options) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
+    let exactIdentity;
+    if (!hasSafeFileIdentity(stat)) {
+        const exact = fsSync.lstatSync(operationPath, { bigint: true });
+        if (exact.isSymbolicLink() || !exact.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        exactIdentity = { dev: exact.dev, ino: exact.ino };
+    }
     const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
-    return { dir, realPath, stat };
+    const guard = { dir, realPath, stat };
+    if (exactIdentity)
+        exactGuardIdentities.set(guard, exactIdentity);
+    return guard;
 }
 export async function assertAsyncDirectoryGuard(guard) {
     assertDirectoryGuard(guard, "native");
@@ -59,9 +72,11 @@ export function assertDirectoryGuard(guard, mode) {
     const expectedRealPath = guard.realPath;
     assertNoWindowsPathAlias(expectedRealPath, "filesystem");
     const expectedStat = guard.stat;
-    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const suppliedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const retainedIdentity = exactGuardIdentities.get(guard);
+    const expectedIdentity = retainedIdentity ?? suppliedIdentity;
     const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
-        ? inspectDirectoryIdentityAtPathSync(operationPath, {
+        ? retainedIdentity ? fsSync.lstatSync(operationPath, { bigint: true }) : inspectDirectoryIdentityAtPathSync(operationPath, {
             dev: expectedIdentity.dev,
             ino: expectedIdentity.ino,
         })
@@ -74,7 +89,7 @@ export function assertDirectoryGuard(guard, mode) {
     if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
-    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
+    const realPath = mode === "native" || typeof suppliedIdentity.ino === "bigint"
         ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
     if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {

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

@@ -5,6 +5,7 @@ export type DirectoryModeChecks = {
 };
 export type DirectoryModeOwner = {
     verify(check?: () => void): Promise<void>;
+    verifyCanonical?(): Promise<boolean>;
     apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
     close(): Promise<void>;
 };
@@ -12,6 +13,7 @@ export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actu
 /** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
 export declare function ownDirectoryMode(params: {
     inspect: () => Promise<number>;
+    inspectCanonical?: () => number | undefined;
     chmod: (mode: number) => Promise<void>;
     prepareChmod?: () => Promise<void>;
     verifyChmod?: () => Promise<void>;
@@ -28,6 +30,7 @@ export declare function nodeDirectorySearchOnlyFlags(): {
 export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
     expectedIdentity?: BigIntStats;
     ownerUid?: number;
+    canonicalPath?: string;
 }): Promise<DirectoryModeOwner>;
 /** Synchronous counterpart with the same no-follow, identity, and owner checks. */
 export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {

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

@@ -4,6 +4,8 @@ import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+import { nativePolicyDirectoryObserver } from "./native-policy-directory-observation.js";
 export function assertOwnedDirectory(expected, actual) {
     if (actual.isSymbolicLink() || !actual.isDirectory()) {
         throw new FsSafeError("not-file", "directory mode target must be a real directory");
@@ -23,7 +25,7 @@ export function ownDirectoryMode(params) {
         pending = operation.catch(() => undefined);
         return operation;
     };
-    return {
+    const owner = {
         verify: (check) => enqueue(async () => {
             check?.();
             await params.inspect();
@@ -79,6 +81,14 @@ export function ownDirectoryMode(params) {
             return closing;
         },
     };
+    if (params.inspectCanonical) {
+        owner.verifyCanonical = async () => {
+            let verified = false;
+            await enqueue(async () => { verified = params.inspectCanonical() !== undefined; });
+            return verified;
+        };
+    }
+    return owner;
 }
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export function nodeDarwinDirectoryMetadataFlags() {
@@ -131,7 +141,11 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
         proc = route.proc;
         return await fs.open(dirPath, route.flags | flags);
     });
+    let observer;
     try {
+        observer = options.canonicalPath === dirPath && ownerUid === undefined
+            ? nativePolicyDirectoryObserver(getNativeBinding(), handle.fd, dirPath)
+            : undefined;
         const inspect = async () => {
             const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
             assertOwnedDirectory(expected, opened);
@@ -153,8 +167,18 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
             assertOwner(opened);
             assertOwner(followed);
         };
+        const observeCanonical = observer;
         const owner = ownDirectoryMode({
             inspect,
+            inspectCanonical: observeCanonical ? () => {
+                const observed = observeCanonical();
+                if (!observed)
+                    return undefined;
+                if (observed.identity.dev !== expected.dev || observed.identity.ino !== expected.ino) {
+                    throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+                }
+                return Number(observed.identity.mode & 4095n);
+            } : undefined,
             prepareChmod: proc ? assertProcAuthority : undefined,
             verifyChmod: proc ? assertProcAuthority : undefined,
             async chmod(mode) {
@@ -165,12 +189,13 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
                     await handle.chmod(mode);
                 }
             },
-            close: () => handle.close(),
+            close: () => { observer?.dispose(); return handle.close(); },
         });
         await owner.verify();
         return owner;
     }
     catch (error) {
+        observer?.dispose();
         try {
             await handle.close();
         }