@openclaw/fs-safe 0.13.1 → 0.14.0

package/dist/root-write-lock-binding.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
+const lockObservations = new WeakMap();
+export function canReuseParentWithMutationAssertion(assertion, rootPath, targetPath) {
+    if (assertion === undefined)
+        return true;
+    const binding = lockObservations.get(assertion);
+    return binding?.rootPath === rootPath && binding.targetPath === targetPath;
+}
+function unsupportedSpelling() {
+    return new FsSafeError("path-alias", "Windows compatibility writes require lower-case ASCII destination components");
+}
+// Missing names have no portable case/Unicode lock key. Keep this admission
+// narrower than general Root paths and never change keys after acquisition.
+function effectiveDestination(rootPath, targetPath, rootIdentity) {
+    let effective;
+    let missingHint;
+    try {
+        effective = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        let cursor = targetPath;
+        const missing = [];
+        for (;;) {
+            try {
+                fs.lstatSync(cursor);
+                break;
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error) || cursor === rootPath)
+                    throw error;
+                const parent = path.dirname(cursor);
+                if (parent === cursor)
+                    throw error;
+                missing.unshift(path.basename(cursor));
+                cursor = parent;
+            }
+        }
+        // Existing dangling links must fail resolution, not become missing names.
+        const canonicalParent = realpathSync.native(cursor);
+        effective = path.join(canonicalParent, ...missing);
+        // The hint must describe the selected route exactly. The full resolver can
+        // normalize a missing raw `..` component out of the eventual lock path.
+        if (missing.length > 1 && path.resolve(canonicalParent) === canonicalParent &&
+            missing.every(component => /^[a-z0-9._-]+$/.test(component) &&
+                component !== "." && component !== ".." && !component.endsWith("."))) {
+            missingHint = Object.freeze({ parentPath: canonicalParent, parts: Object.freeze(missing), nextIndex: 0 });
+        }
+    }
+    const admitted = admitPathInsideRoot({ rootPath, candidatePath: effective, rootIdentity });
+    if (!admitted)
+        throw unsupportedSpelling();
+    const relative = admitted.relativePath;
+    if (!relative || !relative.split(path.sep).every(component => /^[a-z0-9._-]+$/.test(component) && !component.endsWith(".")))
+        throw unsupportedSpelling();
+    return {
+        path: admitted.path,
+        // Case-folded or rebased root spellings keep the full resolver and its
+        // existing root-identity admission at every mutation.
+        missing: admitted.admission === "exact" && admitted.path === effective ? missingHint : undefined,
+    };
+}
+// The hint stores only a location. Each call freshly binds the nearest existing
+// prefix and its first absent child; no identity or authorization crosses calls.
+function observeMissingDestination(hint) {
+    // A complete parent needs only the ordinary leaf check, not a prefix fence.
+    if (hint.parts.length - hint.nextIndex < 2)
+        return undefined;
+    try {
+        let parentPath = hint.parentPath;
+        let parent = inspectDirectoryIdentitySync(parentPath);
+        for (let nextIndex = hint.nextIndex; nextIndex < hint.parts.length; nextIndex++) {
+            const childPath = path.join(parentPath, hint.parts[nextIndex]);
+            let child;
+            try {
+                child = fs.lstatSync(childPath, { bigint: true });
+            }
+            catch (error) {
+                if (!hasNodeErrorCode(error, "ENOENT"))
+                    return undefined;
+                if (realpathSync.native(parentPath) !== parentPath)
+                    return undefined;
+                inspectDirectoryIdentitySync(parentPath, parent);
+                try {
+                    fs.lstatSync(childPath);
+                }
+                catch (error) {
+                    if (!hasNodeErrorCode(error, "ENOENT"))
+                        return undefined;
+                    // Absence can follow a renamed ancestor through a new alias while
+                    // preserving the directory's identity. Finish at its current name.
+                    if (realpathSync.native(parentPath) !== parentPath)
+                        return undefined;
+                    return Object.freeze({ parentPath, parts: hint.parts, nextIndex });
+                }
+                return undefined;
+            }
+            // An existing leaf always receives the historical full resolution,
+            // including final links, collisions and unsupported canonical spellings.
+            if (nextIndex === hint.parts.length - 1)
+                return undefined;
+            parent = inspectDirectoryIdentitySync(childPath, undefined, child);
+            parentPath = childPath;
+        }
+    }
+    catch {
+        // Removal, redirection and uncertain observations only discard the hint.
+        // The full resolver below still determines the destination and error.
+    }
+    return undefined;
+}
+export function assertRootFallbackWritePath(expected, actual) {
+    if (expected !== undefined && actual !== expected) {
+        throw new FsSafeError("path-mismatch", "compatibility write destination changed after lock selection");
+    }
+}
+export function createRootWriteLockBinding(params) {
+    const { rootPath } = params;
+    const rootIdentity = params.rootIdentity && Object.freeze({
+        dev: params.rootIdentity.dev, ino: params.rootIdentity.ino,
+    });
+    const selected = effectiveDestination(rootPath, params.targetPath, rootIdentity);
+    const targetPath = selected.path;
+    let missingHint = selected.missing;
+    const relativePath = path.relative(rootPath, targetPath);
+    let active = true;
+    const assertCurrent = () => {
+        if (!active)
+            throw new FsSafeError("path-mismatch", "compatibility lock observation expired");
+        const observed = missingHint && observeMissingDestination(missingHint);
+        if (observed) {
+            missingHint = observed;
+            return;
+        }
+        missingHint = undefined;
+        const current = effectiveDestination(rootPath, targetPath, rootIdentity);
+        assertRootFallbackWritePath(targetPath, current.path);
+        missingHint = current.missing;
+    };
+    // Only this library-owned, observation-only closure permits parent reuse.
+    // Callers cannot obtain that status by setting properties on their callback.
+    lockObservations.set(assertCurrent, Object.freeze({ rootPath, targetPath }));
+    return Object.freeze({
+        targetPath,
+        relativePath,
+        // The existing lock protocol uses slashes; the writer needs native spelling.
+        relativeLockPath: relativePath.split(path.sep).join("/"),
+        assertCurrent,
+        dispose() {
+            active = false;
+            missingHint = undefined;
+            lockObservations.delete(assertCurrent);
+        },
+    });
+}

package/dist/staged-directory.d.ts

@@ -1,13 +1,16 @@
 import { type BigIntStats } from "node:fs";
 import type { DirectoryReceipt } from "./directory-durability.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+import type { NativeBinding } from "./native-binding.js";
+import { type MutationDirectoryObservation, type MutationDirectoryObserver } from "./pinned-mutation-observation.js";
 import type { StagedFileReceipt } from "./staged-file-types.js";
 export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
 export type PolicyStagedDirectory = Readonly<{
     directory: StagedDirectorySnapshot;
     observation: MutationDirectoryObservation;
     stat: BigIntStats;
+    observeCurrent?: MutationDirectoryObserver;
+    disposeObservation?(): void;
 }>;
 export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
     dev: bigint;
@@ -15,7 +18,7 @@ export declare function exactIdentityMatches(expected: FileIdentityStat, actual:
 }>): boolean;
 export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
 export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
-export declare function describePolicyStagedDirectory(fd: number, pathname: string): PolicyStagedDirectory;
+export declare function describePolicyStagedDirectory(fd: number, pathname: string, binding?: NativeBinding): PolicyStagedDirectory;
 export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
 export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
 export declare function openStagedDirectory(directory: string | DirectoryReceipt): {

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAwBvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAOb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAU9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CA2CvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAeb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAoB9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}

package/dist/staged-directory.js

@@ -2,6 +2,7 @@ import fs, {} from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
 import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
 import { realpathSync } from "./realpath.js";
 import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
@@ -38,12 +39,31 @@ function sameDirectoryMetadata(left, right) {
 }
 // The policy hot path is Node/POSIX-only. It deliberately uses native
 // canonicalization so a successful capture contains no JS realpath work.
-export function describePolicyStagedDirectory(fd, pathname) {
+export function describePolicyStagedDirectory(fd, pathname, binding) {
     const resolved = path.resolve(pathname);
     const descriptor = fs.fstatSync(fd, { bigint: true });
     if (!descriptor.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a directory");
     }
+    const observeCurrent = nativePolicyDirectoryObserver(binding, fd, resolved);
+    const observed = observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(descriptor, observed.identity)) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        const directory = Object.freeze({
+            path: resolved,
+            realPath: observed.canonicalPath,
+            identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+        });
+        return Object.freeze({
+            directory,
+            observation: checkedMutationDirectory(resolved, observed.canonicalPath, observed.identity, observeCurrent),
+            stat: descriptor,
+            observeCurrent,
+            disposeObservation: observeCurrent.dispose,
+        });
+    }
     const before = inspectDirectoryIdentitySync(resolved);
     const canonicalPath = path.resolve(realpathSync.native(resolved));
     const after = inspectDirectoryIdentitySync(resolved, descriptor);
@@ -64,6 +84,14 @@ export function describePolicyStagedDirectory(fd, pathname) {
     });
 }
 export function assertPolicyStagedDirectoryCurrent(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(captured.stat, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return captured.stat;
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     if (!sameDirectoryMetadata(captured.stat, current) ||
         path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
@@ -72,6 +100,14 @@ export function assertPolicyStagedDirectoryCurrent(captured) {
     return current;
 }
 export function refreshPolicyStagedDirectoryObservation(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!exactIdentityMatches(captured.directory.identity, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return checkedMutationDirectory(captured.directory.path, observed.canonicalPath, observed.identity, captured.observeCurrent);
+    }
     const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
     const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
     if (canonicalPath !== captured.directory.realPath) {

package/dist/temp-workspace-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AA0UF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}
+{"version":3,"file":"temp-workspace-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-admission.ts"],"names":[],"mappings":"AA6BA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAiB5D,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,IAAI,CAAC;IACtB,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,CAAC;AAsWF,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAM1F;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyBjG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAsBtF"}

package/dist/temp-workspace-admission.js

@@ -116,6 +116,30 @@ function assertSnapshot(entry, uid) {
     assertTrustedTempWorkspaceDirectory(stat, uid);
     assertCanonicalRoot(entry);
 }
+function snapshotMissingRootComponent(parent, dir, ownerUid) {
+    if (parent.dir !== parent.realPath) {
+        assertSnapshot(parent, ownerUid);
+        return snapshot(dir, ownerUid);
+    }
+    const current = inspectSnapshotIdentity(parent);
+    assertTrustedTempWorkspaceDirectory(current, ownerUid);
+    let realPath;
+    try {
+        realPath = canonicalTempWorkspacePath(dir);
+    }
+    catch (error) {
+        // Keep parent resolution failures ahead of a missing or unreadable child.
+        assertCanonicalRoot(parent);
+        throw error;
+    }
+    if (path.dirname(realPath) !== parent.realPath) {
+        assertCanonicalRoot(parent);
+        return snapshot(dir, ownerUid);
+    }
+    // The child's canonical parent confirms the same parent name at this phase.
+    // Its exact non-symlink/owner observation still precedes mode initialization.
+    return snapshot(dir, ownerUid, realPath);
+}
 function assertChain(chain, uid) {
     for (const entry of chain) {
         const current = inspectSnapshotIdentity(entry);
@@ -321,6 +345,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
         return admission;
     const guardedChain = chain;
     for (const segment of missing) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
         assertNoWindowsPathAlias(dir, "filesystem");
@@ -334,8 +359,7 @@ export async function admitTempWorkspaceRoot(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        parent.assertCurrent();
-        const observed = snapshot(dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
         if (created) {
             const modeInitialization = admitTempWorkspaceChild(dir, observed.stat, parent, 0o700);
             if (modeInitialization)
@@ -351,6 +375,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
         return admission;
     const guardedChain = chain;
     for (const segment of missing) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
         const parent = rootAdmission(guardedChain, ownerUid);
         const dir = path.join(parent.dir, segment);
         assertNoWindowsPathAlias(dir, "filesystem");
@@ -364,8 +389,7 @@ export function admitTempWorkspaceRootSync(rootDir) {
             if (error.code !== "EEXIST")
                 throw error;
         }
-        parent.assertCurrent();
-        const observed = snapshot(dir, ownerUid);
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid);
         if (created)
             admitTempWorkspaceChildSync(dir, observed.stat, parent, 0o700);
         guardedChain.push(observed.entry);

package/docs/guest.md

@@ -80,7 +80,7 @@ disables. Do not omit required fields.
 | Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
 | Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
 | Make directories | `mkdirp root directory` | Creates missing relative directory components. |
-| List directory | `readdir root directory` | JSON array of `{ name, isDirectory }`; no sorting guarantee. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory, isFile }`; both kind fields are false for symlinks and special entries; no sorting guarantee. |
 
 The complete program rejects empty, `.`, `..`, slash-containing, and NUL
 basenames before opening roots or creating parents. Both leaf operands of copy

package/docs/native.md

@@ -206,6 +206,14 @@ that fallback does not apply to POSIX no-read modes.
 
 ## JavaScript fallback guarantees and delta
 
+Policy-bound parent creation can refresh exact directory facts through the
+retained POSIX descriptor. The optional native observer compares descriptor and
+no-follow pathname metadata and verifies the descriptor's canonical path before
+and after the observation. Ordinary paths can share that observation within one
+synchronous admission phase; callbacks, mutations, and later phases require fresh
+evidence. Unsupported helpers retain the guarded pathname checks. Policy and
+denied-path decisions remain in TypeScript.
+
 Public policy does not change with the selected mechanism: traversal and link
 rejection, archive filters/limits/modes, exclusive target creation, source and
 target identity fencing, publication cleanup receipts, and secret/lock policy

package/docs/writing.md

@@ -537,6 +537,12 @@ Windows `Root.write()` and `Root.writeJson()` honor this policy both as a Root d
 
 The Windows buffered compatibility path resolves permitted in-root aliases before choosing its lock and binds publication to that effective destination. With the existing lock protocol, effective path components beneath the Root must contain only lower-case ASCII letters, digits, `.`, `_`, or `-`, with no trailing `.`. Unsupported spellings, including missing upper-case or non-ASCII names, fail with `path-alias` before mutation; no filesystem case-sensitivity or Unicode-folding behavior is guessed. This restriction does not apply to strict writes. Opaque Windows pathname identities still use strict verification against the retained original descriptor: they never, by themselves, authorize content-based acceptance of a replacement.
 
+The library's own lock-destination check permits the writer to reuse parent
+admission within that operation. The lock key and destination checks remain
+unchanged, and evidence is revoked when the locked operation finishes. Supplying
+an `assertBeforeMutation` callback retains full parent admission because caller
+code can change the filesystem before dispatch.
+
 Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -167,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.13.1",
-    "@openclaw/fs-safe-darwin-x64": "0.13.1",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.13.1",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.13.1",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.13.1",
-    "@openclaw/fs-safe-linux-x64-musl": "0.13.1",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.13.1",
+    "@openclaw/fs-safe-darwin-arm64": "0.14.0",
+    "@openclaw/fs-safe-darwin-x64": "0.14.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.14.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.14.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.14.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.14.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.14.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {