@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write.js

@@ -55,21 +55,18 @@ import path from "node:path";
 import { inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { runPinnedWriteWindows } from "./native-pinned-write-windows.js";
+import { capturePolicyAwareWindowsParent } from "./native-policy-parent-windows.js";
 import { openNativeParentAdmission, openNativeRootAdmission } from "./native-parent-admission.js";
 import { assertNativeStaging, writeNativeStage } from "./native-staged-file.js";
 import { captureNativeFdClose } from "./native-binding.js";
+import { NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
 import { assertPolicyStagedDirectoryCurrent, assertStagedDirectoryCurrent, describePolicyStagedDirectory, describeStagedDirectory, refreshPolicyStagedDirectoryObservation, } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
+import { errorCauseOptions } from "./root-errors.js";
 import { isNotFoundPathError, isSymlinkOpenError } from "./path.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
-function relativeParentSegments(relativeParentPath) {
-    return relativeParentPath.split("/").filter(Boolean);
-}
-function prospectiveTargetPath(parentPath, parentRoute, offset, basename) {
-    return joinPathSegmentRoute(parentPath, parentRoute, offset, basename);
-}
 function sameAbsolutePath(left, right) {
     return path.relative(path.resolve(left), path.resolve(right)) === "";
 }
@@ -99,12 +96,8 @@ function normalizePolicyParentOpenError(error, params) {
     if (!isSymlinkOpenError(error))
         return error;
     return params.mutationAdmission?.rejectParentSymlinks
-        ? new FsSafeError("symlink", "symlink path component not allowed", {
-            cause: error instanceof Error ? error : undefined,
-        })
-        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        ? new FsSafeError("symlink", "symlink path component not allowed", errorCauseOptions(error))
+        : new FsSafeError("path-mismatch", "native write parent changed during policy admission", errorCauseOptions(error));
 }
 async function describePosixParent(parentFd, pathname) {
     const parentPath = realpathSync.native(pathname);
@@ -118,8 +111,8 @@ async function describePosixParent(parentFd, pathname) {
         observation: checkedMutationDirectory(parentPath, directory.realPath, parentPathStat),
     };
 }
-function describePolicyPosixParent(parentFd, pathname) {
-    const policyDirectory = describePolicyStagedDirectory(parentFd, pathname);
+function describePolicyPosixParent(binding, parentFd, pathname) {
+    const policyDirectory = describePolicyStagedDirectory(parentFd, pathname, binding);
     return {
         parentFd,
         parentPath: policyDirectory.directory.realPath,
@@ -131,11 +124,12 @@ function describePolicyPosixParent(parentFd, pathname) {
 }
 function policyParentCaptureDeopt(error) {
     return error instanceof FsSafeError &&
+        !(error instanceof NativePolicyDirectoryMismatch) &&
         (error.code === "path-mismatch" || error.code === "not-file");
 }
-function tryDescribePolicyPosixParent(parentFd, pathname) {
+function tryDescribePolicyPosixParent(binding, parentFd, pathname) {
     try {
-        return describePolicyPosixParent(parentFd, pathname);
+        return describePolicyPosixParent(binding, parentFd, pathname);
     }
     catch (error) {
         if (!policyParentCaptureDeopt(error))
@@ -149,183 +143,221 @@ function assertPosixParentCurrent(parent) {
         : assertStagedDirectoryCurrent(parent.directory);
 }
 async function capturePolicyAwarePosixParent(binding, params, rootFd, directoryFlags) {
-    const closeFd = captureNativeFdClose(binding);
-    const segments = relativeParentSegments(params.relativeParentPath);
-    const parentSpelling = segments.length
-        ? path.join(params.rootPath, ...segments)
-        : params.rootPath;
-    const segmentRoute = createPathSegmentRoute(segments);
-    const initialTarget = prospectiveTargetPath(params.rootPath, segmentRoute, 0, params.basename);
-    let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
-    if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
-        retainedTargetPath = undefined;
-    }
-    // Preserve the one-open hot path when the complete parent still exists.
-    // Policy is attached only after the opened descriptor is associated with its
-    // current canonical pathname, so a contained redirect cannot retain the old
-    // preflight authorization.
-    let completeParentFd;
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
-    }
-    catch (error) {
-        if (error?.code !== "ENOENT" || !params.mkdir)
-            throw error;
-    }
-    if (completeParentFd !== undefined) {
-        const parentFd = completeParentFd;
+        const closeFd = captureNativeFdClose(binding);
+        const observationDisposers = new Map();
+        const disposeObservation = (fd) => {
+            const dispose = observationDisposers.get(fd);
+            observationDisposers.delete(fd);
+            dispose?.();
+        };
+        const observationScope = __addDisposableResource(env_1, {
+            [Symbol.dispose]() { for (const dispose of observationDisposers.values())
+                dispose(); },
+        }, false);
+        const capturePolicyParent = (fd, pathname) => {
+            const captured = tryDescribePolicyPosixParent(binding, fd, pathname);
+            const dispose = captured?.policyDirectory?.disposeObservation;
+            if (dispose)
+                observationDisposers.set(fd, dispose);
+            return captured;
+        };
+        const segments = params.relativeParentPath.split("/").filter(Boolean);
+        const parentSpelling = segments.length
+            ? path.join(params.rootPath, ...segments)
+            : params.rootPath;
+        const segmentRoute = createPathSegmentRoute(segments);
+        const initialTarget = joinPathSegmentRoute(params.rootPath, segmentRoute, 0, params.basename);
+        let retainedTargetPath = params.mutationAdmission?.beginParentWalk?.();
+        if (retainedTargetPath && !sameAbsolutePath(retainedTargetPath, initialTarget)) {
+            retainedTargetPath = undefined;
+        }
+        // Preserve the one-open hot path when the complete parent still exists.
+        // Policy is attached only after the opened descriptor is associated with its
+        // current canonical pathname, so a contained redirect cannot retain the old
+        // preflight authorization.
+        let completeParentFd;
         try {
-            let admitted = retainedTargetPath
-                ? tryDescribePolicyPosixParent(parentFd, parentSpelling)
-                : undefined;
-            if (!admitted) {
-                retainedTargetPath = undefined;
-                admitted = await describePosixParent(parentFd, parentSpelling);
-            }
-            const targetPath = path.join(admitted.parentPath, params.basename);
-            await authorizePinnedMutation(params, {
-                targetPath,
-                mutationPath: targetPath,
-                phase: "parent",
-            });
-            assertPosixParentCurrent(admitted);
-            return admitted;
+            completeParentFd = binding.openBeneath(rootFd, params.relativeParentPath, directoryFlags).fd;
         }
         catch (error) {
-            closeFd(parentFd);
-            throw error;
+            if (error?.code !== "ENOENT" || !params.mkdir) {
+                // A mechanism rejection must not hide canonical denial/symlink policy.
+                // This admission only classifies failure; it cannot authorize a retry.
+                await authorizePinnedMutation(params, {
+                    targetPath: initialTarget, mutationPath: initialTarget, phase: "parent",
+                });
+                throw normalizePolicyParentOpenError(error, params);
+            }
         }
-    }
-    // The canonical preflight spelling has no intentional symlinks in its
-    // existing prefix. Walk missing-parent cases one direct child at a time so
-    // every existing/opened object is authorized and every mkdir is authorized
-    // before dispatch. O_NOFOLLOW makes a concurrently introduced link fail
-    // before the next component can be created through it.
-    const secureDirectoryFlags = directoryFlags | (fsSync.constants.O_NOFOLLOW ?? 0);
-    let currentFd = rootFd;
-    let currentOwnedFd;
-    let currentPath = params.rootPath;
-    let current = retainedTargetPath
-        ? tryDescribePolicyPosixParent(rootFd, currentPath)
-        : undefined;
-    if (!current) {
-        retainedTargetPath = undefined;
-        current = await describePosixParent(rootFd, currentPath);
-    }
-    try {
-        await authorizePinnedMutation(params, {
-            targetPath: retainedTargetPath ?? initialTarget,
-            mutationPath: retainedTargetPath ?? initialTarget,
-            phase: "parent",
-        });
-        assertPosixParentCurrent(current);
-        for (let index = 0; index < segments.length; index += 1) {
-            const segment = segments[index];
-            const childPath = path.join(currentPath, segment);
-            let childFd;
-            let createdByMkdir = false;
-            let createReceipt;
+        if (completeParentFd !== undefined) {
+            const parentFd = completeParentFd;
             try {
-                childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
-            }
-            catch (openError) {
-                if (!isNotFoundPathError(openError)) {
-                    throw normalizePolicyParentOpenError(openError, params);
+                let admitted = retainedTargetPath
+                    ? capturePolicyParent(parentFd, parentSpelling)
+                    : undefined;
+                if (!admitted) {
+                    retainedTargetPath = undefined;
+                    admitted = await describePosixParent(parentFd, parentSpelling);
                 }
-                const targetPath = retainedTargetPath ?? prospectiveTargetPath(currentPath, segmentRoute, index, params.basename);
-                const request = Object.freeze({
+                const targetPath = path.join(admitted.parentPath, params.basename);
+                await authorizePinnedMutation(params, {
                     targetPath,
-                    mutationPath: childPath,
-                    phase: "parent-create",
+                    mutationPath: targetPath,
+                    phase: "parent",
                 });
-                createReceipt = params.mutationAdmission?.tryAuthorizeAtParent?.(request, current.observation);
-                if (!createReceipt) {
-                    createReceipt = await authorizePinnedMutation(params, request);
-                    assertPosixParentCurrent(current);
-                }
-                params.assertBeforeMutation?.();
-                // Do not carry pathname freshness across the live authority callback.
-                assertPosixParentCurrent(current);
-                createdByMkdir = mkdirPolicyChild(binding, currentFd, segment, 0o777);
+                assertPosixParentCurrent(admitted);
+                return admitted;
+            }
+            catch (error) {
+                disposeObservation(parentFd);
+                closeFd(parentFd);
+                throw error;
+            }
+        }
+        // The canonical preflight spelling has no intentional symlinks in its
+        // existing prefix. Walk missing-parent cases one direct child at a time so
+        // every existing/opened object is authorized and every mkdir is authorized
+        // before dispatch. O_NOFOLLOW makes a concurrently introduced link fail
+        // before the next component can be created through it.
+        const secureDirectoryFlags = directoryFlags | (fsSync.constants.O_NOFOLLOW ?? 0);
+        let currentFd = rootFd;
+        let currentOwnedFd;
+        let currentPath = params.rootPath;
+        let current = retainedTargetPath
+            ? capturePolicyParent(rootFd, currentPath)
+            : undefined;
+        if (!current) {
+            retainedTargetPath = undefined;
+            current = await describePosixParent(rootFd, currentPath);
+        }
+        try {
+            await authorizePinnedMutation(params, {
+                targetPath: retainedTargetPath ?? initialTarget,
+                mutationPath: retainedTargetPath ?? initialTarget,
+                phase: "parent",
+            });
+            assertPosixParentCurrent(current);
+            for (let index = 0; index < segments.length; index += 1) {
+                const segment = segments[index];
+                const childPath = path.join(currentPath, segment);
+                let childFd;
+                let createdByMkdir = false;
+                let createReceipt;
                 try {
                     childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
                 }
-                catch (createdOpenError) {
-                    throw normalizePolicyParentOpenError(createdOpenError, params);
-                }
-            }
-            let child;
-            try {
-                const acceleratedChild = retainedTargetPath
-                    ? tryDescribePolicyPosixParent(childFd, childPath)
-                    : undefined;
-                if (acceleratedChild) {
-                    child = acceleratedChild;
-                }
-                else {
-                    retainedTargetPath = undefined;
-                    child = await describePosixParent(childFd, childPath);
-                }
-                if (!sameAbsolutePath(child.parentPath, childPath))
-                    retainedTargetPath = undefined;
-                let childAuthorization;
-                if (createdByMkdir && createReceipt && params.mutationAdmission?.advanceCreatedDirectory) {
-                    let evidence;
+                catch (openError) {
+                    if (!isNotFoundPathError(openError)) {
+                        throw normalizePolicyParentOpenError(openError, params);
+                    }
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(currentPath, segmentRoute, index, params.basename);
+                    const request = Object.freeze({
+                        targetPath,
+                        mutationPath: childPath,
+                        phase: "parent-create",
+                    });
+                    createReceipt = params.mutationAdmission?.tryAuthorizeAtParent?.(request, current.observation);
+                    if (!createReceipt) {
+                        createReceipt = await authorizePinnedMutation(params, request);
+                        assertPosixParentCurrent(current);
+                    }
+                    params.assertBeforeMutation?.();
+                    // Do not carry pathname freshness across the live authority callback.
+                    assertPosixParentCurrent(current);
+                    createdByMkdir = mkdirPolicyChild(binding, currentFd, segment, 0o777);
                     try {
-                        const parent = current.policyDirectory
-                            ? refreshPolicyStagedDirectoryObservation(current.policyDirectory)
-                            : checkedMutationDirectory(currentPath, current.directory.realPath, assertStagedDirectoryCurrent(current.directory));
-                        evidence = Object.freeze({
-                            admission: createReceipt,
-                            parent,
-                            child: child.observation,
-                        });
+                        childFd = binding.openBeneath(currentFd, segment, secureDirectoryFlags).fd;
                     }
-                    catch {
-                        // Leave failed evidence to the full ordered admission below.
+                    catch (createdOpenError) {
+                        throw normalizePolicyParentOpenError(createdOpenError, params);
                     }
-                    if (evidence) {
-                        childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
+                }
+                let child;
+                try {
+                    const acceleratedChild = retainedTargetPath
+                        ? capturePolicyParent(childFd, childPath)
+                        : undefined;
+                    if (acceleratedChild) {
+                        child = acceleratedChild;
+                    }
+                    else {
+                        retainedTargetPath = undefined;
+                        child = await describePosixParent(childFd, childPath);
+                    }
+                    if (!sameAbsolutePath(child.parentPath, childPath))
+                        retainedTargetPath = undefined;
+                    let childAuthorization;
+                    if (createdByMkdir && createReceipt && params.mutationAdmission?.advanceCreatedDirectory) {
+                        let evidence;
+                        try {
+                            const parent = current.policyDirectory
+                                ? refreshPolicyStagedDirectoryObservation(current.policyDirectory)
+                                : checkedMutationDirectory(currentPath, current.directory.realPath, assertStagedDirectoryCurrent(current.directory));
+                            evidence = Object.freeze({
+                                admission: createReceipt,
+                                parent,
+                                child: child.observation,
+                            });
+                        }
+                        catch {
+                            // Leave failed evidence to the full ordered admission below.
+                        }
+                        if (evidence) {
+                            childAuthorization = params.mutationAdmission.advanceCreatedDirectory(evidence);
+                        }
+                    }
+                    const targetPath = retainedTargetPath ?? joinPathSegmentRoute(child.parentPath, segmentRoute, index + 1, params.basename);
+                    const request = Object.freeze({
+                        targetPath,
+                        mutationPath: targetPath,
+                        phase: "parent",
+                    });
+                    childAuthorization ??= params.mutationAdmission?.tryAuthorizeAtParent?.(request, child.observation);
+                    if (!childAuthorization) {
+                        await authorizePinnedMutation(params, request);
+                        assertPosixParentCurrent(child);
                     }
                 }
-                const targetPath = retainedTargetPath ?? prospectiveTargetPath(child.parentPath, segmentRoute, index + 1, params.basename);
-                const request = Object.freeze({
-                    targetPath,
-                    mutationPath: targetPath,
-                    phase: "parent",
-                });
-                childAuthorization ??= params.mutationAdmission?.tryAuthorizeAtParent?.(request, child.observation);
-                if (!childAuthorization) {
-                    await authorizePinnedMutation(params, request);
-                    assertPosixParentCurrent(child);
+                catch (error) {
+                    disposeObservation(childFd);
+                    closeFd(childFd);
+                    throw error;
+                }
+                const previousOwnedFd = currentOwnedFd;
+                disposeObservation(current.parentFd);
+                currentOwnedFd = child.parentFd;
+                currentFd = child.parentFd;
+                currentPath = child.parentPath;
+                current = child;
+                if (previousOwnedFd !== undefined)
+                    closeFd(previousOwnedFd);
+                if (index === segments.length - 1) {
+                    currentOwnedFd = undefined;
+                    return child;
                 }
             }
-            catch (error) {
-                closeFd(childFd);
-                throw error;
-            }
-            const previousOwnedFd = currentOwnedFd;
-            currentOwnedFd = child.parentFd;
-            currentFd = child.parentFd;
-            currentPath = child.parentPath;
-            current = child;
-            if (previousOwnedFd !== undefined)
-                closeFd(previousOwnedFd);
-            if (index === segments.length - 1) {
-                currentOwnedFd = undefined;
-                return child;
+            // Empty relative parents are handled by the complete-parent fast path.
+            throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+        }
+        finally {
+            if (currentOwnedFd !== undefined) {
+                disposeObservation(currentOwnedFd);
+                closeFd(currentOwnedFd);
             }
         }
-        // Empty relative parents are handled by the complete-parent fast path.
-        throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
     }
     finally {
-        if (currentOwnedFd !== undefined)
-            closeFd(currentOwnedFd);
+        __disposeResources(env_1);
     }
 }
 export async function runPinnedWriteNative(binding, params) {
-    const env_1 = { stack: [], error: void 0, hasError: false };
+    const env_2 = { stack: [], error: void 0, hasError: false };
     try {
         const closeFd = captureNativeFdClose(binding);
         const windows = process.platform === "win32";
@@ -333,18 +365,21 @@ export async function runPinnedWriteNative(binding, params) {
             assertNativeStaging(binding);
         }
         const directoryFlags = fsSync.constants.O_RDONLY | (fsSync.constants.O_DIRECTORY ?? 0);
+        const completeCreate = params.overwrite === false && params.input.kind !== "file" && params.input.stageBeforePublish === true;
         const rootAdmission = await openNativeRootAdmission(binding, {
             rootPath: params.rootPath,
             rootIdentity: params.rootIdentity,
             operation: "native write",
+            reportCloseErrors: completeCreate,
         });
         const root = rootAdmission.root;
-        const posixRoot = __addDisposableResource(env_1, windows ? undefined : root, true);
+        const posixRoot = __addDisposableResource(env_2, windows ? undefined : root, true);
         let parentFd;
         let windowsOwnsDirectories = false;
+        let admissionFailure;
         // Until stage construction takes ownership, even admission failures must close
         // the raw POSIX parent. Disposal preserves both admission and close failures.
-        const parentGuard = __addDisposableResource(env_1, {
+        const parentGuard = __addDisposableResource(env_2, {
             [Symbol.dispose]() {
                 if (!windows && parentFd !== undefined) {
                     closeFd(parentFd);
@@ -355,14 +390,18 @@ export async function runPinnedWriteNative(binding, params) {
             let parentPath;
             let directory;
             let parentPathStat;
-            let policyParentAdmitted = false;
             if (!windows && params.mutationAdmission) {
                 const admitted = await capturePolicyAwarePosixParent(binding, params, root.fd, directoryFlags);
                 parentFd = admitted.parentFd;
                 parentPath = admitted.parentPath;
                 directory = admitted.directory;
                 parentPathStat = admitted.parentPathStat;
-                policyParentAdmitted = true;
+            }
+            else if (windows && params.mutationAdmission) {
+                const admitted = await capturePolicyAwareWindowsParent(binding, params, rootAdmission);
+                parentFd = admitted.fd;
+                parentPath = admitted.guard.realPath;
+                parentPathStat = admitted.guard.stat;
             }
             else {
                 if (params.mkdir) {
@@ -375,15 +414,6 @@ export async function runPinnedWriteNative(binding, params) {
                 directory = admitted.stagedDirectory;
                 parentPathStat = admitted.guard.stat;
             }
-            if (!policyParentAdmitted && params.mutationAdmission) {
-                const targetPath = path.join(parentPath, params.basename);
-                await authorizePinnedMutation(params, {
-                    targetPath,
-                    mutationPath: targetPath,
-                    phase: "parent",
-                });
-                await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })));
-            }
             const verificationGuard = { dir: parentPath, realPath: parentPath, stat: parentPathStat };
             if (params.overwrite === false) {
                 try {
@@ -405,8 +435,13 @@ export async function runPinnedWriteNative(binding, params) {
             parentFd = undefined;
             return await writeNativeStage(binding, ownedParent, closeFd, directory, params, verificationGuard);
         }
+        catch (error) {
+            admissionFailure = { error };
+            throw error;
+        }
         finally {
             if (windows && !windowsOwnsDirectories) {
+                const closeErrors = [];
                 if (parentFd !== undefined) {
                     // Match the Windows leaf cleanup contract: an admission or identity
                     // failure remains primary, while every owned directory is still given
@@ -415,20 +450,28 @@ export async function runPinnedWriteNative(binding, params) {
                     try {
                         closeFd(parentFd);
                     }
-                    catch {
-                        // Best effort while propagating the operation failure.
+                    catch (error) {
+                        closeErrors.push(error);
                     }
                 }
-                await root.close().catch(() => undefined);
+                try {
+                    await root.close();
+                }
+                catch (error) {
+                    closeErrors.push(error);
+                }
+                if (completeCreate && closeErrors.length > 0) {
+                    throw new AggregateError([...(admissionFailure ? [admissionFailure.error] : []), ...closeErrors], "native create admission and close failed");
+                }
             }
         }
     }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
     }
     finally {
-        const result_1 = __disposeResources(env_1);
+        const result_1 = __disposeResources(env_2);
         if (result_1)
             await result_1;
     }

package/node_modules/@openclaw/fs-safe/dist/native-policy-directory-observation.d.ts

@@ -0,0 +1,11 @@
+import { FsSafeError } from "./errors.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { MutationDirectoryObserver } from "./pinned-mutation-observation.js";
+export declare class NativePolicyDirectoryMismatch extends FsSafeError {
+    constructor(cause?: Error);
+}
+export type NativePolicyDirectoryObserver = MutationDirectoryObserver & {
+    dispose(): void;
+};
+/** Fresh name/metadata/canonical facts from a caller-owned POSIX descriptor. */
+export declare function nativePolicyDirectoryObserver(binding: NativeBinding | undefined, fd: number, pathname: string): NativePolicyDirectoryObserver | undefined;

package/node_modules/@openclaw/fs-safe/dist/native-policy-directory-observation.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+export class NativePolicyDirectoryMismatch extends FsSafeError {
+    constructor(cause) {
+        super("path-mismatch", "staging directory pathname changed", { cause });
+    }
+}
+/** Fresh name/metadata/canonical facts from a caller-owned POSIX descriptor. */
+export function nativePolicyDirectoryObserver(binding, fd, pathname) {
+    if (!binding || process.platform === "win32" || process.versions.bun)
+        return undefined;
+    const observe = binding.observeDirectoryFd;
+    if (typeof observe !== "function")
+        return undefined;
+    const mode = getFsSafeNativeConfig().mode;
+    let disposed = false;
+    const inspect = () => {
+        if (disposed)
+            throw new NativePolicyDirectoryMismatch();
+        if (getFsSafeNativeConfig().mode !== mode)
+            return undefined;
+        let observed;
+        try {
+            observed = observe.call(binding, fd, pathname);
+        }
+        catch (error) {
+            if (error?.code === "OBSERVATION_UNAVAILABLE")
+                return undefined;
+            if (error?.code === "OBSERVATION_REDIRECTED") {
+                // A contained redirect requires ordinary selected-object admission;
+                // it has not yet supplied inconsistent descriptor/name evidence.
+                throw new FsSafeError("path-mismatch", "staging directory pathname redirected");
+            }
+            if (error?.code === "path-mismatch") {
+                throw new NativePolicyDirectoryMismatch(error instanceof Error ? error : undefined);
+            }
+            throw error;
+        }
+        if (getFsSafeNativeConfig().mode !== mode)
+            return undefined;
+        if (!observed || typeof observed.dev !== "bigint" || observed.dev < 0n || observed.dev > 0xffffffffffffffffn ||
+            typeof observed.ino !== "bigint" || observed.ino < 0n || observed.ino > 0xffffffffffffffffn ||
+            typeof observed.mode !== "bigint" || observed.mode < 0n || observed.mode > 0xffffffffn ||
+            typeof observed.nlink !== "bigint" || observed.nlink < 0n || observed.nlink > 0xffffffffffffffffn ||
+            typeof observed.realPath !== "string" || observed.realPath.includes("\0") ||
+            !path.isAbsolute(observed.realPath))
+            return undefined;
+        if ((observed.mode & 61440n) !== 16384n || observed.nlink === 0n ||
+            observed.realPath !== pathname) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        return Object.freeze({
+            canonicalPath: observed.realPath,
+            identity: Object.freeze({
+                dev: observed.dev, ino: observed.ino, mode: observed.mode, nlink: observed.nlink,
+            }),
+        });
+    };
+    return Object.assign(inspect, { dispose() { disposed = true; } });
+}

package/node_modules/@openclaw/fs-safe/dist/native-policy-parent-windows.d.ts

@@ -0,0 +1,13 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type NativeRootAdmission } from "./native-parent-admission.js";
+import type { NativeBinding } from "./native.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+type PolicyParent = {
+    fd: number;
+    guard: AsyncDirectoryGuard<BigIntStats>;
+    observation: MutationDirectoryObservation;
+};
+export declare function capturePolicyAwareWindowsParent(binding: NativeBinding, params: PinnedWriteParams, rootAdmission: NativeRootAdmission): Promise<PolicyParent>;
+export {};