@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/filename.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
 import { maxNormalizedUtf8Bytes } from "./unicode-path.js";
 const INVALID_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
+const HAS_INVALID_FILE_NAME_CHARACTER = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/;
+const HAS_RETAINED_FILE_NAME_CHARACTER = /[^\u0000-\u001f\u007f-\u009f<>:"/\\|?*\s]/;
 function canStartWindowsDeviceName(character) {
     const folded = character | 0x20;
     return folded === 0x61 || folded === 0x63 || folded === 0x6c ||
@@ -33,18 +35,44 @@ export function suffixWindowsReservedDeviceName(fileName) {
     return `${fileName.slice(0, baseNameEnd)}_${fileName.slice(baseNameEnd)}`;
 }
 const PORTABLE_FILE_NAME_BYTES = 255;
-const UNTRUSTED_FILE_NAME_CODE_UNITS = 200;
-function truncateWithoutSplittingSurrogatePair(value, maxLength) {
-    let truncated = value.slice(0, maxLength);
+const SANITIZED_FILE_NAME_CODE_UNITS = 200;
+const SAFE_FALLBACK_FILE_NAME = "file";
+/**
+ * Uses native string and regexp operations to recognize the full sanitizer's
+ * bounded fixed points. The separate non-global regexp keeps this predicate
+ * stateless, and the authoritative device-name transform remains the final
+ * admission check.
+ */
+function isBoundedSanitizedFileName(fileName, trimmedFileName) {
+    return typeof fileName === "string" &&
+        fileName.length > 0 &&
+        fileName.length <= SANITIZED_FILE_NAME_CODE_UNITS &&
+        fileName !== "." &&
+        fileName !== ".." &&
+        trimmedFileName === fileName &&
+        !HAS_INVALID_FILE_NAME_CHARACTER.test(fileName) &&
+        suffixWindowsReservedDeviceName(fileName) === fileName;
+}
+function hasWindowsDrivePrefix(value) {
+    if (value.length < 2 || value.charCodeAt(1) !== 0x3a)
+        return false;
+    const firstCodeUnit = value.charCodeAt(0);
+    return (firstCodeUnit >= 0x41 && firstCodeUnit <= 0x5a) ||
+        (firstCodeUnit >= 0x61 && firstCodeUnit <= 0x7a);
+}
+function normalizedFileNameBytes(value) {
+    return maxNormalizedUtf8Bytes(value, true);
+}
+function truncateCodeUnitsWithoutSplittingSurrogate(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let truncated = value.slice(0, limit);
     const trailingCodeUnit = truncated.charCodeAt(truncated.length - 1);
     if (trailingCodeUnit >= 0xd800 && trailingCodeUnit <= 0xdbff) {
         truncated = truncated.slice(0, -1);
     }
     return truncated;
 }
-function normalizedFileNameBytes(value) {
-    return maxNormalizedUtf8Bytes(value, true);
-}
 /** Keeps short names exact and trims only the filename tail of a composite temp name. */
 export function fitFileNameToPortableComponent(params) {
     const complete = `${params.prefix}${params.fileName}${params.suffix}`;
@@ -77,23 +105,40 @@ export function fitFileNameToPortableComponent(params) {
     }
     return `${codePoints.slice(0, low).join("")}${tailSuffix}`;
 }
-export function sanitizeUntrustedFileName(fileName, fallbackName) {
-    const trimmed = typeof fileName === "string" ? fileName.trim() : "";
-    if (!trimmed) {
-        return fallbackName;
+function sanitizeFileNameCandidate(fileName) {
+    if (typeof fileName !== "string")
+        return undefined;
+    const trimmed = fileName.trim();
+    if (!trimmed)
+        return undefined;
+    if (isBoundedSanitizedFileName(fileName, trimmed))
+        return fileName;
+    // Basename selection cannot manufacture a character, and the complete
+    // sanitizer removes this same invalid set before its final trim.
+    if (!HAS_RETAINED_FILE_NAME_CHARACTER.test(trimmed))
+        return undefined;
+    let base = trimmed;
+    if (base.includes("/"))
+        base = path.posix.basename(base);
+    if (base.includes("\\") || hasWindowsDrivePrefix(base)) {
+        base = path.win32.basename(base);
     }
-    let base = path.posix.basename(trimmed);
-    base = path.win32.basename(base);
     base = base.replace(INVALID_FILE_NAME_CHARACTERS, "").trim();
     if (!base || base === "." || base === "..") {
-        return fallbackName;
+        return undefined;
     }
-    base = suffixWindowsReservedDeviceName(base);
-    if (base.length > UNTRUSTED_FILE_NAME_CODE_UNITS) {
-        base = truncateWithoutSplittingSurrogatePair(base, UNTRUSTED_FILE_NAME_CODE_UNITS);
-        if (suffixWindowsReservedDeviceName(base) !== base) {
-            base = suffixWindowsReservedDeviceName(truncateWithoutSplittingSurrogatePair(base, UNTRUSTED_FILE_NAME_CODE_UNITS - 1));
-        }
+    base = truncateCodeUnitsWithoutSplittingSurrogate(base, SANITIZED_FILE_NAME_CODE_UNITS);
+    let safeBase = suffixWindowsReservedDeviceName(base);
+    if (safeBase.length > SANITIZED_FILE_NAME_CODE_UNITS) {
+        // The safety suffix is the final invariant. Shorten the unsuffixed tail so
+        // truncation cannot turn a padded reserved stem back into a device name.
+        base = truncateCodeUnitsWithoutSplittingSurrogate(base, SANITIZED_FILE_NAME_CODE_UNITS - 1);
+        safeBase = suffixWindowsReservedDeviceName(base);
     }
-    return base;
+    return safeBase;
+}
+export function sanitizeUntrustedFileName(fileName, fallbackName) {
+    return (sanitizeFileNameCandidate(fileName) ??
+        sanitizeFileNameCandidate(fallbackName) ??
+        SAFE_FALLBACK_FILE_NAME);
 }

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOxD"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOxD"}

package/dist/fs.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
 /**
  * Returns true when `fs.stat()` can stat the path.
  *
@@ -7,7 +8,7 @@ import fs from "node:fs";
  */
 export async function pathExists(filePath) {
     try {
-        fs.statSync(filePath);
+        fs.statSync(pathForWindowsFilesystem(filePath));
         return true;
     }
     catch {
@@ -20,7 +21,7 @@ export async function pathExists(filePath) {
  */
 export function pathExistsSync(filePath) {
     try {
-        fs.statSync(filePath);
+        fs.statSync(pathForWindowsFilesystem(filePath));
         return true;
     }
     catch {

package/dist/guarded-mkdir.d.ts

@@ -1,4 +1,6 @@
 import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write.js";
 /**
  * Creates each missing path component from `rootReal` down to `targetPath`,
  * guarding every step. Returns the real (symlink-resolved) path of the final
@@ -9,9 +11,15 @@ export declare function mkdirPathComponentsWithGuards(params: {
     rootReal: string;
     targetPath: string;
     beforeComponent?: (componentPath: string) => Promise<void> | void;
+    beforeCreateComponent?: (componentPath: string, prospectiveTargetPath: string, retainedTargetPath: string | undefined, parent: MutationDirectoryObservation) => Promise<PinnedMutationAdmissionReceipt | undefined> | PinnedMutationAdmissionReceipt | undefined;
+    beforeUseComponent?: (componentPath: string, prospectiveTargetPath: string, retainedTargetPath: string | undefined) => Promise<void> | void;
+    afterCreateComponent?: (receipt: PinnedCreatedDirectoryReceipt) => PinnedMutationAuthorizationToken | undefined;
     assertBeforeMutation?: () => void;
     mode?: number;
     rejectSymlinks?: boolean;
+    revalidateParentAfterBeforeComponent?: boolean;
+    synchronousAuthorizationIncludesFence?: boolean;
+    retainedTargetPath?: string;
     rootIdentity?: RootBoundaryIdentity;
 }): Promise<string>;
 //# sourceMappingURL=guarded-mkdir.d.ts.map

package/dist/guarded-mkdir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAYA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAgCpF;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClE,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAqFlB"}
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAA4B,KAAK,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAC/G,OAAO,KAAK,EACV,6BAA6B,EAC7B,8BAA8B,EAC9B,gCAAgC,EACjC,MAAM,mBAAmB,CAAC;AAuG3B;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClE,qBAAqB,CAAC,EAAE,CACtB,aAAa,EAAE,MAAM,EACrB,qBAAqB,EAAE,MAAM,EAC7B,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,MAAM,EAAE,4BAA4B,KACjC,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC,GAAG,8BAA8B,GAAG,SAAS,CAAC;IACtG,kBAAkB,CAAC,EAAE,CACnB,aAAa,EAAE,MAAM,EACrB,qBAAqB,EAAE,MAAM,EAC7B,kBAAkB,EAAE,MAAM,GAAG,SAAS,KACnC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,oBAAoB,CAAC,EAAE,CACrB,OAAO,EAAE,6BAA6B,KACnC,gCAAgC,GAAG,SAAS,CAAC;IAClD,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oCAAoC,CAAC,EAAE,OAAO,CAAC;IAC/C,qCAAqC,CAAC,EAAE,OAAO,CAAC;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAyMlB"}

package/dist/guarded-mkdir.js

@@ -1,12 +1,58 @@
-import fsSync from "node:fs";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 import { directoryComponentNotDirectoryError, rootPathChangedError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { checkedMutationDirectory } from "./pinned-mutation-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute, } from "./path-segment-route.js";
+function sameDirectoryFacts(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+function inspectGuardCurrent(parent) {
+    const stat = inspectDirectoryIdentitySync(parent.dir, parent.stat);
+    if (realpathSync.native(parent.dir) !== parent.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    return stat;
+}
+function observedGuard(parent) {
+    return checkedMutationDirectory(parent.dir, parent.realPath, parent.stat);
+}
+function createdDirectoryEvidence(admission, parent, childPath) {
+    try {
+        const parentAfter = inspectGuardCurrent(parent);
+        const childBefore = inspectDirectoryIdentitySync(childPath);
+        const realPath = realpathSync.native(childPath);
+        if (realPath !== childPath)
+            return undefined;
+        const childAfter = inspectDirectoryIdentitySync(childPath, childBefore);
+        if (!sameDirectoryFacts(childBefore, childAfter))
+            return undefined;
+        const child = checkedMutationDirectory(childPath, realPath, childAfter);
+        const receipt = Object.freeze({
+            admission,
+            parent: checkedMutationDirectory(parent.dir, parent.realPath, parentAfter),
+            child,
+        });
+        return Object.freeze({
+            receipt,
+            guard: Object.freeze({ dir: childPath, realPath, stat: childAfter }),
+        });
+    }
+    catch {
+        // Failed optional evidence leaves the existing ordered admission in charge.
+        return undefined;
+    }
+}
+function sameAbsolutePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
 function suppliedExactRootIdentity(identity) {
     return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint"
         ? { dev: identity.dev, ino: identity.ino }
@@ -17,9 +63,14 @@ function assertGuardMatchesRootIdentity(guard, expected) {
         throw rootPathChangedError();
     }
 }
+function isPromiseLike(value) {
+    return typeof value?.then === "function";
+}
 async function realpathOrThrowNotFile(target) {
     try {
-        return path.resolve(realpathSync.native(target));
+        const canonical = realpathSync.native(pathForWindowsFilesystem(target));
+        assertNoWindowsPathAlias(canonical, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        return resolvePathPreservingWindowsRoot(canonical);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -37,20 +88,25 @@ async function realpathOrThrowNotFile(target) {
  * re-deriving it from the original, possibly-symlinked, lexical path.
  */
 export async function mkdirPathComponentsWithGuards(params) {
-    const root = path.resolve(params.rootReal);
-    const configuredRootGuard = await createAsyncDirectoryGuard(root, { bigint: true });
+    const rawRootReal = params.rootReal;
+    assertNoWindowsPathAlias(rawRootReal, "filesystem", "root directory uses a Windows filesystem namespace alias");
+    const rawTargetPath = params.targetPath;
+    assertNoWindowsPathAlias(rawTargetPath, "filesystem", "target directory uses a Windows filesystem namespace alias");
+    const root = resolvePathPreservingWindowsRoot(rawRootReal);
+    const target = resolvePathPreservingWindowsRoot(rawTargetPath);
     const suppliedIdentity = suppliedExactRootIdentity(params.rootIdentity);
+    const configuredRootGuard = await createAsyncDirectoryGuard(root, { bigint: true });
     const checkedRootIdentity = suppliedIdentity ?? {
         dev: configuredRootGuard.stat.dev,
         ino: configuredRootGuard.stat.ino,
     };
     assertGuardMatchesRootIdentity(configuredRootGuard, checkedRootIdentity);
-    const rootCanonical = path.resolve(configuredRootGuard.realPath);
+    assertNoWindowsPathAlias(configuredRootGuard.realPath);
+    const rootCanonical = resolvePathPreservingWindowsRoot(configuredRootGuard.realPath);
     const rootGuard = rootCanonical === root
         ? configuredRootGuard
         : await createAsyncDirectoryGuard(rootCanonical, { bigint: true });
     assertGuardMatchesRootIdentity(rootGuard, checkedRootIdentity);
-    const target = path.resolve(params.targetPath);
     const admissionParams = {
         candidatePath: target,
         rootIdentity: checkedRootIdentity,
@@ -67,37 +123,119 @@ export async function mkdirPathComponentsWithGuards(params) {
     }
     let current = rootCanonical;
     let currentGuard = rootGuard;
-    for (const part of admittedTarget.relativePath.split(path.sep).filter(Boolean)) {
+    const parts = admittedTarget.relativePath.split(path.sep).filter(Boolean);
+    let partRoute;
+    let retainedTargetPath = params.retainedTargetPath &&
+        sameAbsolutePath(path.dirname(params.retainedTargetPath), target)
+        ? params.retainedTargetPath
+        : undefined;
+    let retainedParentPath = retainedTargetPath ? path.dirname(retainedTargetPath) : undefined;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
         const next = path.join(current, part);
         const parentGuard = currentGuard;
-        await assertAsyncDirectoryGuard(parentGuard);
+        assertNoWindowsPathAlias(parentGuard.realPath, "filesystem", "canonical parent directory uses a Windows filesystem namespace alias");
+        let created = false;
+        let createReceipt;
+        if (!params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
         await params.beforeComponent?.(next);
-        params.assertBeforeMutation?.();
-        try {
-            await fs.mkdir(next, { mode: params.mode });
+        if (params.revalidateParentAfterBeforeComponent) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        if (params.beforeCreateComponent) {
+            let missing = false;
+            try {
+                fsSync.lstatSync(next);
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                missing = true;
+            }
+            if (missing) {
+                let prospectiveParent = retainedParentPath;
+                if (!prospectiveParent) {
+                    partRoute ??= createPathSegmentRoute(parts);
+                    prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
+                }
+                const authorization = params.beforeCreateComponent(next, prospectiveParent, retainedTargetPath, observedGuard(parentGuard));
+                if (isPromiseLike(authorization)) {
+                    createReceipt = await authorization;
+                    await assertAsyncDirectoryGuard(parentGuard);
+                }
+                else {
+                    createReceipt = authorization;
+                    // A synchronous authorization must still end at a live pathname
+                    // fence immediately before the authority callback and mkdir.
+                    if (!params.synchronousAuthorizationIncludesFence)
+                        inspectGuardCurrent(parentGuard);
+                }
+                params.assertBeforeMutation?.();
+                // Authority callbacks are an explicit freshness boundary. Recheck the
+                // exact parent synchronously so no callback-observed authority is
+                // carried into a pathname mkdir after the parent was swapped.
+                inspectGuardCurrent(parentGuard);
+                try {
+                    await fs.mkdir(next, { mode: params.mode });
+                    created = true;
+                }
+                catch (error) {
+                    if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                        throw error;
+                    }
+                }
+            }
+        }
+        else {
+            params.assertBeforeMutation?.();
+            try {
+                await fs.mkdir(next, { mode: params.mode });
+            }
+            catch (error) {
+                if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                    throw error;
+                }
+            }
+        }
+        let createdAuthorization;
+        let createdEvidence;
+        if (created && createReceipt && params.afterCreateComponent) {
+            createdEvidence = createdDirectoryEvidence(createReceipt, parentGuard, next);
+            if (createdEvidence) {
+                createdAuthorization = params.afterCreateComponent(createdEvidence.receipt);
+            }
         }
-        catch (error) {
-            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
-                throw error;
+        if (params.beforeUseComponent && !createdAuthorization) {
+            let prospectiveParent = retainedParentPath;
+            if (!prospectiveParent) {
+                partRoute ??= createPathSegmentRoute(parts);
+                prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
             }
+            await params.beforeUseComponent(next, prospectiveParent, retainedTargetPath);
+            await assertAsyncDirectoryGuard(parentGuard);
         }
-        const stat = fsSync.lstatSync(next);
-        if ((params.rejectSymlinks && stat.isSymbolicLink()) || (!stat.isSymbolicLink() && !stat.isDirectory())) {
+        const stat = createdAuthorization ? undefined : fsSync.lstatSync(next);
+        if (stat && ((params.rejectSymlinks && stat.isSymbolicLink()) ||
+            (!stat.isSymbolicLink() && !stat.isDirectory()))) {
             throw directoryComponentNotDirectoryError();
         }
         // Node's recursive mkdir follows symlinks in missing components. Build one
         // segment at a time and realpath-check each segment before descending.
-        const observedNextReal = await realpathOrThrowNotFile(next);
+        const nextReal = createdAuthorization && createdEvidence
+            ? createdEvidence.receipt.child.canonicalPath
+            : await realpathOrThrowNotFile(next);
         const admittedNextReal = admitPathInsideRoot({
             rootPath: rootCanonical,
-            candidatePath: observedNextReal,
+            candidatePath: nextReal,
             rootIdentity: checkedRootIdentity,
         });
         if (!admittedNextReal) {
             throw new FsSafeError("outside-workspace", "directory escaped workspace root");
         }
-        const nextReal = admittedNextReal.path;
-        if (stat.isSymbolicLink()) {
+        const admittedNextPath = admittedNextReal.path;
+        if (stat?.isSymbolicLink()) {
             // An existing path component may legitimately be a symlink to a real
             // directory inside the root (e.g. a skill-bank layout). We already
             // verified above that it resolves inside the root, so treat the
@@ -107,18 +245,29 @@ export async function mkdirPathComponentsWithGuards(params) {
             // every subsequent segment. Callers that need the final directory
             // (e.g. to guard it themselves after this function returns) must use
             // the returned resolved path, not their own lexical parent path.
-            const targetStat = fsSync.statSync(nextReal);
+            const targetStat = fsSync.statSync(admittedNextPath);
             if (!targetStat.isDirectory()) {
                 throw directoryComponentNotDirectoryError();
             }
-            currentGuard = await createAsyncDirectoryGuard(nextReal);
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+            assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
             await assertAsyncDirectoryGuard(parentGuard);
-            current = nextReal;
+            retainedTargetPath = undefined;
+            retainedParentPath = undefined;
+            current = admittedNextPath;
             continue;
         }
-        currentGuard = await createAsyncDirectoryGuard(next);
-        await assertAsyncDirectoryGuard(parentGuard);
-        current = next;
+        if (createdAuthorization && createdEvidence) {
+            currentGuard = createdEvidence.guard;
+        }
+        else {
+            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+        }
+        assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
+        if (!createdAuthorization || !createdEvidence) {
+            await assertAsyncDirectoryGuard(parentGuard);
+        }
+        current = admittedNextPath;
     }
     return current;
 }

package/dist/guest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QA2ZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QA8ZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}

package/dist/guest.js

@@ -57,7 +57,10 @@ export const GUEST_FILESYSTEM_PYTHON = [
     "            except FileNotFoundError:",
     "                if not mkdir_enabled:",
     "                    raise",
-    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                try:",
+    "                    os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                except FileExistsError:",
+    "                    pass  # The competing entry must still pass the no-follow directory open.",
     "                next_fd = open_dir(segment, dir_fd=current_fd)",
     "            os.close(current_fd)",
     "            current_fd = next_fd",

package/dist/home-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAoBA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAwCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAaR"}
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAsCA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAOpB;AAwCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAIR;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AA4DD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAoBR"}

package/dist/home-dir.js

@@ -1,6 +1,17 @@
 import os from "node:os";
 import path from "node:path";
+import process from "node:process";
 import { normalizeOptionalString } from "./string-coerce.js";
+import { assertNoWindowsPathAlias, assertNoWindowsPathAliasForPlatform, repairResolvedWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const PATH_ALIAS_MESSAGE = "path uses a Windows filesystem namespace alias";
+function isOrdinaryRootedWindowsDrivePath(input) {
+    const drive = input.charCodeAt(0);
+    return input.length >= 3 &&
+        ((drive >= 0x41 && drive <= 0x5a) || (drive >= 0x61 && drive <= 0x7a)) &&
+        input.charCodeAt(1) === 0x3a &&
+        (input.charCodeAt(2) === 0x5c || input.charCodeAt(2) === 0x2f) &&
+        input.indexOf(":", 2) === -1;
+}
 function hasHomePrefix(input) {
     return input === "~" || input.startsWith("~/") ||
         (path.sep === "\\" && input.startsWith("~\\"));
@@ -17,7 +28,12 @@ function normalize(value) {
 }
 export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
     const raw = resolveRawHomeDir(env, homedir);
-    return raw ? path.resolve(raw) : undefined;
+    if (!raw)
+        return undefined;
+    assertNoWindowsPathAlias(raw, "filesystem", "home path uses a Windows filesystem namespace alias");
+    const resolved = resolvePathPreservingWindowsRoot(raw);
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
 }
 function resolveRawHomeDir(env, homedir) {
     const explicitHome = normalize(env.OPENCLAW_HOME);
@@ -56,7 +72,9 @@ function normalizeSafe(homedir) {
     }
 }
 export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
-    return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+    const resolved = resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+    assertNoWindowsPathAlias(resolved, "filesystem", "home path uses a Windows filesystem namespace alias");
+    return resolved;
 }
 export function expandHomePrefix(input, opts) {
     if (!hasHomePrefix(input)) {
@@ -70,17 +88,62 @@ export function expandHomePrefix(input, opts) {
     // Expand before normalizing so a following .. traverses the actual home.
     return path.join(home, input.slice(2));
 }
-export function resolveHomeRelativePath(input, opts) {
-    if (!input) {
-        return input;
-    }
-    if (!hasHomePrefix(input)) {
-        return path.resolve(input);
-    }
+function resolveExpandedHomePath(input, opts) {
     const expanded = expandHomePrefix(input, {
         home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
         env: opts?.env,
         homedir: opts?.homedir,
     });
-    return path.resolve(expanded);
+    const resolved = resolvePathPreservingWindowsRoot(expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", PATH_ALIAS_MESSAGE);
+    return resolved;
+}
+function admitFinalHomePath(resolved, platform) {
+    assertNoWindowsPathAliasForPlatform(resolved, "filesystem", PATH_ALIAS_MESSAGE, platform);
+    return resolved;
+}
+function finishOrdinaryHomePath(input, resolved) {
+    const resolvedPlatform = process.platform;
+    if (resolved === input && resolvedPlatform !== undefined)
+        return resolved;
+    return admitFinalHomePath(resolved, resolvedPlatform);
+}
+function repairAndFinishOrdinaryHomePath(input, resolved) {
+    return finishOrdinaryHomePath(input, repairResolvedWindowsRoot(input, resolved));
+}
+function resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted) {
+    if (ordinaryRawAdmitted) {
+        return finishOrdinaryHomePath(input, resolvePathPreservingWindowsRoot(input));
+    }
+    assertNoWindowsPathAliasForPlatform(input, "filesystem", PATH_ALIAS_MESSAGE, rawPlatform);
+    if (!hasHomePrefix(input)) {
+        const resolved = resolvePathPreservingWindowsRoot(input);
+        // This cold branch was not admitted as an ordinary rooted drive. Recheck
+        // even an unchanged result because the live platform can change between
+        // raw admission and resolved-path admission. Passing undefined preserves
+        // the classifier's default process.platform read.
+        return admitFinalHomePath(resolved, process.platform);
+    }
+    return resolveExpandedHomePath(input, opts);
+}
+export function resolveHomeRelativePath(input, opts) {
+    if (!input) {
+        return input;
+    }
+    const rawPlatform = process.platform;
+    // Primitive ordinary drive paths have exactly one structural colon. Record
+    // that admission so an unchanged resolved string does not need rescanning.
+    const ordinaryRawAdmitted = rawPlatform === "win32" &&
+        typeof input === "string" &&
+        isOrdinaryRootedWindowsDrivePath(input);
+    // Keep the overwhelmingly common rooted-drive path close to path.resolve
+    // itself. Seven-byte inputs retain the general helper's observable
+    // namespace-root preflight; a rare six-byte result retains its repair.
+    if (!ordinaryRawAdmitted || input.length === 7) {
+        return resolveHomePathCold(input, opts, rawPlatform, ordinaryRawAdmitted);
+    }
+    const resolved = path.resolve(input);
+    return resolved.length === 6
+        ? repairAndFinishOrdinaryHomePath(input, resolved)
+        : finishOrdinaryHomePath(input, resolved);
 }

package/dist/install-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAWA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA+B5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB"}