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

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

@@ -1,6 +1,6 @@
 import { type BigIntStats, type Stats } from "node:fs";
-import type { DirectoryReceipt } from "./directory-durability.js";
-import type { FileIdentityStat } from "./file-identity.js";
+import type { DirectoryReceipt, ExactDirectoryReceipt } from "./directory-durability.js";
+import { type FileIdentityInput } from "./file-identity.js";
 type ExactIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
 declare const numericFields: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
 declare const timeFields: readonly ["atime", "mtime", "ctime", "birthtime"];
@@ -13,11 +13,11 @@ type DirectoryAuthority = DirectoryProvenance & Readonly<{
     path: string;
     realPath: string;
 }>;
-export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
+export declare function directoryReceiptIdentity(input: FileIdentityInput): ExactIdentity;
 export declare function directoryReceiptAuthority(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryAuthority;
-export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryReceipt;
-export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
-export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
-export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): ExactDirectoryReceipt;
+export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): ExactDirectoryReceipt;
+export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): ExactDirectoryReceipt;
+export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): ExactDirectoryReceipt;
 export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
 export {};

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

@@ -1,6 +1,7 @@
 import fs, {} from "node:fs";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
+import { identityFromReceipt } from "./file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 const numericFields = ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
@@ -9,10 +10,11 @@ const timeFields = ["atime", "mtime", "ctime", "birthtime"];
 // fields and accept exact provenance only while its public identity is intact.
 const authorities = new WeakMap();
 const identities = new WeakMap();
-export function directoryReceiptIdentity(identity) {
-    if (!identity) {
+export function directoryReceiptIdentity(input) {
+    if (!input) {
         throw new FsSafeError("path-mismatch", "directory receipt identity is missing");
     }
+    const identity = identityFromReceipt(input);
     const known = identities.get(identity);
     const dev = identity.dev;
     const ino = identity.ino;
@@ -41,9 +43,11 @@ function snapshotDirectoryReceipt(receipt) {
     }
     assertNoWindowsPathAlias(pathname, "filesystem");
     assertNoWindowsPathAlias(realPath, "filesystem");
-    const identity = directoryReceiptIdentity(stat);
+    const identity = directoryReceiptIdentity(receipt.exactIdentity ?? stat);
     const known = authorities.get(receipt);
-    if (known && (pathname !== known.path || realPath !== known.realPath ||
+    const matches = (value, expected) => typeof value === "bigint" ? value === expected : value === Number(expected);
+    if (known && (!matches(stat.dev, known.identity.dev) || !matches(stat.ino, known.identity.ino) ||
+        pathname !== known.path || realPath !== known.realPath ||
         identity.dev !== known.identity.dev || identity.ino !== known.identity.ino)) {
         throw new FsSafeError("path-mismatch", "directory receipt changed before admission");
     }
@@ -79,6 +83,7 @@ export function copyRetainedDirectoryReceipt(receipt) {
 }
 function receiptFromAuthority(authority) {
     const receipt = {
+        exactIdentity: authority.identity,
         path: authority.path,
         realPath: authority.realPath,
         identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),

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

@@ -1,4 +1,5 @@
-export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type ExactDirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
 export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, } from "./publish-file.js";
 export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
 export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";
+export type { ExactFileIdentity, ExactIdentityReceipt } from "./exact-identity.js";

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

@@ -18,7 +18,7 @@ function basename(name) {
 }
 function identity(value) {
     const { dev, ino } = value;
-    if (typeof dev !== "bigint" || typeof ino !== "bigint" || dev < 0n || ino <= 0n ||
+    if (typeof dev !== "bigint" || typeof ino !== "bigint" || dev < -(1n << 63n) || ino < -(1n << 63n) || ino === 0n ||
         dev > 0xffffffffffffffffn || ino > 0xffffffffffffffffn) {
         throw new FsSafeError("path-mismatch", "publication requires an exact known identity");
     }
@@ -230,7 +230,7 @@ export function retainEntryForPublication(options) {
         inspectEntry(sourcePath, source.expected);
         const sourceFd = kind === "symlink"
             ? binding.openStagedSymlink(sourceParent.fd, source.basename)
-            : binding.openBeneath(sourceParent.fd, source.basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK |
+            : native.openBeneath(sourceParent.fd, source.basename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK |
                 (kind === "directory" ? fs.constants.O_DIRECTORY : 0))?.fd;
         if (!Number.isInteger(sourceFd) || sourceFd < 0) {
             throw new FsSafeError("helper-unavailable", "publication source descriptor is unavailable");

package/node_modules/@openclaw/fs-safe/dist/exact-identity.d.ts

@@ -0,0 +1,17 @@
+import { type BigIntStats, type Stats } from "node:fs";
+export type ExactFileIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type ExactIdentityReceipt = {
+    readonly exactIdentity: ExactFileIdentity;
+};
+/** Copy scalars from one observation; never try to recover rounded identity bits. */
+export declare function exactFileIdentity(stat: {
+    dev: number | bigint;
+    ino: number | bigint;
+}): ExactFileIdentity;
+/** Node stores unsigned libuv fields in a signed BigInt64Array. */
+export declare function numberStatScalar(value: number | bigint): number;
+/** Legacy metadata view of the very same bigint observation. */
+export declare function numberStats(stat: BigIntStats): Stats;

package/node_modules/@openclaw/fs-safe/dist/exact-identity.js

@@ -0,0 +1,29 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+/** Copy scalars from one observation; never try to recover rounded identity bits. */
+export function exactFileIdentity(stat) {
+    const { dev, ino } = stat;
+    if ((typeof dev !== "bigint" && !Number.isSafeInteger(dev)) ||
+        (typeof ino !== "bigint" && !Number.isSafeInteger(ino))) {
+        throw new FsSafeError("path-mismatch", "file identity is not exact");
+    }
+    return Object.freeze({ dev: BigInt(dev), ino: BigInt(ino) });
+}
+/** Node stores unsigned libuv fields in a signed BigInt64Array. */
+export function numberStatScalar(value) {
+    return typeof value === "bigint" ? Number(BigInt.asUintN(64, value)) : Number(value);
+}
+/** Legacy metadata view of the very same bigint observation. */
+export function numberStats(stat) {
+    const result = Object.create(fs.Stats.prototype);
+    for (const field of ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"]) {
+        result[field] = numberStatScalar(stat[field]);
+    }
+    for (const field of ["atime", "mtime", "ctime", "birthtime"]) {
+        const ns = stat[`${field}Ns`];
+        const remainder = ((ns % 1000000000n) + 1000000000n) % 1000000000n;
+        result[`${field}Ms`] = Number((ns - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+        // Stats.prototype supplies Node's lazy, correctly rounded Date getters.
+    }
+    return result;
+}

package/node_modules/@openclaw/fs-safe/dist/file-handle-transfer.js

@@ -113,7 +113,8 @@ export async function copyFileHandle(source, target, options = {}) {
     const assertBeforeMutation = composeMutationAssertions(undefined, options.assertBeforeMutation);
     const sourceStat = await inspectFileIdentity(() => {
         signal?.throwIfAborted();
-        return source.stat({ bigint: true });
+        const fd = source.fd;
+        return fd < 0 ? source.stat({ bigint: true }) : fs.fstatSync(fd, { bigint: true });
     });
     signal?.throwIfAborted();
     if (!sourceStat.isFile())
@@ -123,7 +124,8 @@ export async function copyFileHandle(source, target, options = {}) {
     }
     const targetStat = await inspectFileIdentity(() => {
         signal?.throwIfAborted();
-        return target.stat({ bigint: true });
+        const fd = target.fd;
+        return fd < 0 ? target.stat({ bigint: true }) : fs.fstatSync(fd, { bigint: true });
     });
     signal?.throwIfAborted();
     if (!targetStat.isFile())

package/node_modules/@openclaw/fs-safe/dist/file-hash.d.ts

@@ -10,7 +10,7 @@ export type Sha256FileResult = {
     bytes: number;
     digest: string;
 };
-export declare function hashFileHandle(handle: FileHandle, native?: NativeBinding | undefined, { maxBytes, signal }?: Sha256FileOptions): Promise<Sha256FileResult>;
+export declare function hashFileHandle(handle: FileHandle, native?: NativeBinding | undefined, { maxBytes, signal }?: Sha256FileOptions, ownsPosition?: boolean): Promise<Sha256FileResult>;
 export declare function sha256File(input: Sha256FileInput, options?: Sha256FileOptions): Promise<Sha256FileResult>;
 /** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */
 export declare function sha256FileSync(input: Sha256FileSyncInput, options?: Sha256FileOptions): Sha256FileResult;

package/node_modules/@openclaw/fs-safe/dist/file-hash.js

@@ -55,9 +55,9 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
+import { getNativeBinding, selectNativeBinding } from "./native.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 // Idle storage is bounded independently of caller concurrency. A pending read
 // retains its exclusive borrow until the async hasher settles.
@@ -89,7 +89,7 @@ class HashScratch {
             hashScratchBuffers.shift();
     }
 }
-export async function hashFileHandle(handle, native = getNativeBinding(), { maxBytes = Infinity, signal } = {}) {
+export async function hashFileHandle(handle, native = getNativeBinding(), { maxBytes = Infinity, signal } = {}, ownsPosition = false) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
         signal?.throwIfAborted();
@@ -100,11 +100,12 @@ export async function hashFileHandle(handle, native = getNativeBinding(), { maxB
         if (stat.size > maxBytes) {
             throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
         }
-        if (native) {
+        const hasher = selectNativeBinding(native, "sha256File");
+        if (hasher) {
             // A completed N-API task can mask later aborts on the same signal.
             const nativeSignal = signal ? AbortSignal.any([signal]) : undefined;
             try {
-                const result = await native.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
+                const result = await hasher.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal, ownsPosition);
                 signal?.throwIfAborted();
                 return result;
             }
@@ -183,7 +184,7 @@ function rethrowHashOpenError(error) {
 }
 async function hashPath(filePath, options) {
     assertNoWindowsPathAlias(filePath, "filesystem", "SHA-256 path uses a Windows filesystem namespace alias");
-    const before = await inspectFileIdentity(() => hashPathIdentity(filePath));
+    const before = inspectFileIdentitySync(() => hashPathIdentity(filePath));
     let handle;
     try {
         options.signal?.throwIfAborted();
@@ -195,9 +196,10 @@ async function hashPath(filePath, options) {
     let completed = false;
     try {
         options.signal?.throwIfAborted();
-        const opened = await inspectFileIdentity(() => hashDescriptorIdentity(handle.fd), before);
-        await inspectFileIdentity(() => hashPathIdentity(filePath, true), opened);
-        const result = await hashFileHandle(handle, getNativeBinding(), options);
+        const opened = inspectFileIdentitySync(() => hashDescriptorIdentity(handle.fd), before);
+        inspectFileIdentitySync(() => hashPathIdentity(filePath, true), opened);
+        // Only this overload owns the handle and its otherwise unobservable cursor.
+        const result = await hashFileHandle(handle, getNativeBinding(), options, true);
         completed = true;
         return result;
     }

package/node_modules/@openclaw/fs-safe/dist/file-identity.d.ts

@@ -1,7 +1,13 @@
+import type { ExactIdentityReceipt } from "./exact-identity.js";
+export type { ExactFileIdentity, ExactIdentityReceipt } from "./exact-identity.js";
 export type FileIdentityStat = {
     dev: number | bigint;
     ino: number | bigint;
 };
+export type FileIdentityInput = FileIdentityStat | ExactIdentityReceipt;
+/** Only the explicit companion is unambiguous; nested source/target receipts are not inferred. */
+export declare function identityFromReceipt(value: FileIdentityInput): FileIdentityStat;
+export declare function hasSafeFileIdentity(identity: FileIdentityStat): boolean;
 export declare function sha256Hex(data: string | Buffer, encoding?: BufferEncoding): string;
-export declare function sameFileIdentity(left: FileIdentityStat, right: FileIdentityStat, platform?: NodeJS.Platform): boolean;
+export declare function sameFileIdentity(left: FileIdentityInput, right: FileIdentityInput, platform?: NodeJS.Platform): boolean;
 export declare function sameFileIdentityForCleanup(left: FileIdentityStat, right: FileIdentityStat, platform?: NodeJS.Platform): boolean;

package/node_modules/@openclaw/fs-safe/dist/file-identity.js

@@ -1,4 +1,20 @@
 import { createHash } from "node:crypto";
+/** Only the explicit companion is unambiguous; nested source/target receipts are not inferred. */
+export function identityFromReceipt(value) {
+    if ("exactIdentity" in value) {
+        const exact = value.exactIdentity;
+        const dev = exact?.dev, ino = exact?.ino;
+        // A malformed explicit companion cannot fall back to a lossy legacy view.
+        return typeof dev === "bigint" && typeof ino === "bigint" ? { dev, ino } : { dev: NaN, ino: NaN };
+    }
+    return value;
+}
+export function hasSafeFileIdentity(identity) {
+    return isExactStatValue(identity.dev) && isExactStatValue(identity.ino);
+}
+function isExactStatValue(value) {
+    return typeof value === "bigint" || Number.isSafeInteger(value);
+}
 function isZero(value) {
     return value === 0 || value === 0n;
 }
@@ -16,17 +32,23 @@ export function sha256Hex(data, encoding) {
     return createHash("sha256").update(buffer).digest("hex");
 }
 export function sameFileIdentity(left, right, platform = process.platform) {
+    left = identityFromReceipt(left);
+    right = identityFromReceipt(right);
+    const leftDev = left.dev;
+    const leftIno = left.ino;
+    const rightDev = right.dev;
+    const rightIno = right.ino;
     // When Windows cannot open a path for stat, libuv's FindFirstFile fallback reports dev=0 and
     // ino=0. Treating either unknown value as a mismatch caused nondeterministic path-mismatch
     // failures on legitimate reads under antivirus or indexer contention.
-    return (!isStatValueProvablyDifferent(left.dev, right.dev, platform) &&
-        !isStatValueProvablyDifferent(left.ino, right.ino, platform));
+    return (isExactStatValue(leftDev) && isExactStatValue(leftIno) &&
+        isExactStatValue(rightDev) && isExactStatValue(rightIno) &&
+        !isStatValueProvablyDifferent(leftDev, rightDev, platform) &&
+        !isStatValueProvablyDifferent(leftIno, rightIno, platform));
 }
 function sameCleanupStatValue(left, right) {
     // Converting an unsafe number to bigint cannot recover an already rounded ID.
-    if (typeof left === "number" && !Number.isSafeInteger(left))
-        return false;
-    if (typeof right === "number" && !Number.isSafeInteger(right))
+    if (!isExactStatValue(left) || !isExactStatValue(right))
         return false;
     return sameStatValue(left, right);
 }

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-admission.js

@@ -38,8 +38,7 @@ export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
 }
 export function syncReclaimGuardExists(reclaimGuardPath) {
     try {
-        fs.lstatSync(reclaimGuardPath);
-        return true;
+        return fs.lstatSync(reclaimGuardPath, { throwIfNoEntry: false }) !== undefined;
     }
     catch (error) {
         if (error.code === "ENOENT")

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

@@ -91,7 +91,14 @@ function canonicalLockParentSync(parent) {
 function normalizeTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
     assertNoWindowsPathAlias(resolved);
-    fs.mkdirSync(recursiveMkdirPath(path.dirname(resolved)), { recursive: true });
+    const directory = path.dirname(resolved);
+    let parentExists = false;
+    try {
+        parentExists = fs.statSync(directory).isDirectory();
+    }
+    catch { /* Preserve mkdir errors below. */ }
+    if (!parentExists)
+        fs.mkdirSync(recursiveMkdirPath(directory), { recursive: true });
     let parent;
     try {
         parent = canonicalLockParentSync(path.dirname(resolved));

package/node_modules/@openclaw/fs-safe/dist/file-lock.d.ts

@@ -1,4 +1,5 @@
 import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions, type SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export { tryAcquireWriteLease, type FileWriteLease } from "./file-write-lease.js";
 export { acquireFileLockSync, withFileLockSync, type FileLockSyncAcquireOptions, type FileLockSyncHandle, } from "./file-lock-sync.js";
 export type FileLockRetryOptions = SidecarLockRetryOptions;
 export type FileLockStaleRecovery = SidecarLockStaleRecovery;

package/node_modules/@openclaw/fs-safe/dist/file-lock.js

@@ -1,5 +1,6 @@
 import { createSidecarLockManager, } from "./sidecar-lock.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
+export { tryAcquireWriteLease } from "./file-write-lease.js";
 export { acquireFileLockSync, withFileLockSync, } from "./file-lock-sync.js";
 function resolveFileLockManagerKey(targetPath, managerKey) {
     return managerKey ?? `fs-safe.file-lock:${targetPath}`;

package/node_modules/@openclaw/fs-safe/dist/file-write-lease.d.ts

@@ -0,0 +1,9 @@
+export type FileWriteLease = {
+    readonly fd: number;
+    /** False after release or when the kernel breaks or downgrades the lease. */
+    isHeld(): boolean;
+    release(): void;
+    [Symbol.dispose](): void;
+};
+/** Linux kernel write lease. The caller retains the open fd and SIGIO handling. */
+export declare function tryAcquireWriteLease(fd: number): FileWriteLease | null;

package/node_modules/@openclaw/fs-safe/dist/file-write-lease.js

@@ -0,0 +1,42 @@
+import { FsSafeError } from "./errors.js";
+import { requireNativeBinding } from "./native.js";
+/** Linux kernel write lease. The caller retains the open fd and SIGIO handling. */
+export function tryAcquireWriteLease(fd) {
+    if (process.platform !== "linux") {
+        throw new FsSafeError("unsupported-platform", "File write leases require Linux");
+    }
+    if (!Number.isInteger(fd) || fd < 0 || fd > 0x7fffffff) {
+        throw new FsSafeError("invalid-path", "Expected an open file descriptor");
+    }
+    const native = requireNativeBinding();
+    const acquire = native.tryAcquireWriteLease?.bind(native);
+    const held = native.isFileWriteLeaseHeld?.bind(native);
+    const unlock = native.releaseFileWriteLease?.bind(native);
+    if (!acquire || !held || !unlock) {
+        throw new FsSafeError("helper-unavailable", "Native file write leases are unavailable");
+    }
+    const call = (operation) => {
+        try {
+            return operation();
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "Native file write lease operation failed", { cause });
+        }
+    };
+    if (!call(() => acquire(fd)))
+        return null;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        // Never retry an ambiguous settlement against a potentially recycled fd.
+        released = true;
+        call(() => unlock(fd));
+    };
+    return Object.freeze({
+        fd,
+        isHeld: () => !released && call(() => held(fd)),
+        release,
+        [Symbol.dispose]: release,
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.d.ts

@@ -14,6 +14,7 @@ export declare function mkdirPathComponentsWithGuards(params: {
     afterCreateComponent?: (receipt: PinnedCreatedDirectoryReceipt) => PinnedMutationAuthorizationToken | undefined;
     assertBeforeMutation?: () => void;
     createMissing?: boolean;
+    synchronousMkdir?: boolean;
     mode?: number;
     private?: boolean;
     rejectSymlinks?: boolean;

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.js

@@ -2,7 +2,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createDirectoryWithAdmission } from "./create.js";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { assertDirectoryGuard, captureDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 import { directoryComponentNotDirectoryError, rootPathChangedError } from "./root-errors.js";
@@ -55,6 +55,9 @@ function createdDirectoryEvidence(admission, parent, childPath) {
         return undefined;
     }
 }
+function captureExactDirectoryGuard(dir) {
+    return captureDirectoryGuard(dir, "native", { bigint: true });
+}
 function suppliedExactRootIdentity(identity) {
     return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint"
         ? { dev: identity.dev, ino: identity.ino }
@@ -68,7 +71,7 @@ function assertGuardMatchesRootIdentity(guard, expected) {
 function isPromiseLike(value) {
     return typeof value?.then === "function";
 }
-async function realpathOrThrowNotFile(target) {
+function realpathOrThrowNotFile(target) {
     try {
         const canonical = realpathSync.native(pathForWindowsFilesystem(target));
         assertNoWindowsPathAlias(canonical, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
@@ -95,7 +98,7 @@ export async function mkdirPathComponentsWithGuards(params) {
     const root = resolvePathPreservingWindowsRoot(rawRootReal);
     const target = resolvePathPreservingWindowsRoot(rawTargetPath);
     const suppliedIdentity = suppliedExactRootIdentity(params.rootIdentity);
-    const configuredRootGuard = await createAsyncDirectoryGuard(root, { bigint: true });
+    const configuredRootGuard = captureExactDirectoryGuard(root);
     const checkedRootIdentity = suppliedIdentity ?? {
         dev: configuredRootGuard.stat.dev,
         ino: configuredRootGuard.stat.ino,
@@ -105,7 +108,7 @@ export async function mkdirPathComponentsWithGuards(params) {
     const rootCanonical = resolvePathPreservingWindowsRoot(configuredRootGuard.realPath);
     const rootGuard = rootCanonical === root
         ? configuredRootGuard
-        : await createAsyncDirectoryGuard(rootCanonical, { bigint: true });
+        : captureExactDirectoryGuard(rootCanonical);
     assertGuardMatchesRootIdentity(rootGuard, checkedRootIdentity);
     const admissionParams = {
         candidatePath: target,
@@ -138,11 +141,12 @@ export async function mkdirPathComponentsWithGuards(params) {
         let created = false;
         let createReceipt;
         if (!params.revalidateParentAfterBeforeComponent) {
-            await assertAsyncDirectoryGuard(parentGuard);
+            assertDirectoryGuard(parentGuard, "native");
         }
-        await params.beforeComponent?.(next);
+        if (params.beforeComponent)
+            await params.beforeComponent(next);
         if (params.revalidateParentAfterBeforeComponent) {
-            await assertAsyncDirectoryGuard(parentGuard);
+            assertDirectoryGuard(parentGuard, "native");
         }
         let shouldCreate = true;
         if (params.beforeCreateComponent) {
@@ -165,7 +169,7 @@ export async function mkdirPathComponentsWithGuards(params) {
                 const authorization = params.beforeCreateComponent(next, prospectiveParent, retainedTargetPath, observedGuard(parentGuard));
                 if (isPromiseLike(authorization)) {
                     createReceipt = await authorization;
-                    await assertAsyncDirectoryGuard(parentGuard);
+                    assertDirectoryGuard(parentGuard, "native");
                 }
                 else {
                     createReceipt = authorization;
@@ -193,7 +197,10 @@ export async function mkdirPathComponentsWithGuards(params) {
                     });
                 }
                 else {
-                    await fs.mkdir(next, { mode: params.mode });
+                    if (params.synchronousMkdir)
+                        fsSync.mkdirSync(next, { mode: params.mode });
+                    else
+                        await fs.mkdir(next, { mode: params.mode });
                 }
                 created = true;
             }
@@ -217,7 +224,7 @@ export async function mkdirPathComponentsWithGuards(params) {
                 prospectiveParent = joinPathSegmentRoute(next, partRoute, index + 1);
             }
             await params.beforeUseComponent(next, prospectiveParent, retainedTargetPath);
-            await assertAsyncDirectoryGuard(parentGuard);
+            assertDirectoryGuard(parentGuard, "native");
         }
         const stat = createdAuthorization ? undefined : fsSync.lstatSync(next);
         if (stat && ((params.rejectSymlinks && stat.isSymbolicLink()) ||
@@ -228,7 +235,7 @@ export async function mkdirPathComponentsWithGuards(params) {
         // segment at a time and realpath-check each segment before descending.
         const nextReal = createdAuthorization && createdEvidence
             ? createdEvidence.receipt.child.canonicalPath
-            : await realpathOrThrowNotFile(next);
+            : realpathOrThrowNotFile(next);
         const admittedNextReal = admitPathInsideRoot({
             rootPath: rootCanonical,
             candidatePath: nextReal,
@@ -245,9 +252,9 @@ export async function mkdirPathComponentsWithGuards(params) {
             if (!targetStat.isDirectory()) {
                 throw directoryComponentNotDirectoryError();
             }
-            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+            currentGuard = captureExactDirectoryGuard(admittedNextPath);
             assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
-            await assertAsyncDirectoryGuard(parentGuard);
+            assertDirectoryGuard(parentGuard, "native");
             retainedTargetPath = undefined;
             retainedParentPath = undefined;
             current = admittedNextPath;
@@ -257,11 +264,11 @@ export async function mkdirPathComponentsWithGuards(params) {
             currentGuard = createdEvidence.guard;
         }
         else {
-            currentGuard = await createAsyncDirectoryGuard(admittedNextPath, { bigint: true });
+            currentGuard = captureExactDirectoryGuard(admittedNextPath);
         }
         assertNoWindowsPathAlias(currentGuard.realPath, "filesystem", "canonical directory uses a Windows filesystem namespace alias");
         if (!createdAuthorization || !createdEvidence) {
-            await assertAsyncDirectoryGuard(parentGuard);
+            assertDirectoryGuard(parentGuard, "native");
         }
         current = admittedNextPath;
     }

package/node_modules/@openclaw/fs-safe/dist/guest-native-python.js

@@ -92,6 +92,9 @@ export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
     "        try:",
     "            os.rename(src_basename + '/', dst_basename, src_dir_fd=src_parent_fd, dst_dir_fd=dst_parent_fd)",
     "        except OSError as error:",
+    "            # ENOTDIR can describe the slash-checked source, not just the target.",
+    "            if error.errno == errno.ENOTDIR:",
+    "                verify(src_parent_fd, src_basename, 1)",
     "            if error.errno in (errno.ENOTEMPTY, errno.ENOTDIR, errno.EEXIST):",
     "                raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), dst_basename) from error",
     "            raise",

package/node_modules/@openclaw/fs-safe/dist/hardlink-fallback.d.ts

@@ -0,0 +1 @@
+export declare function isHardlinkFallbackError(error: unknown): boolean;

package/node_modules/@openclaw/fs-safe/dist/hardlink-fallback.js

@@ -0,0 +1,5 @@
+// These refusals leave the destination uncreated. EEXIST is deliberately excluded.
+const HARDLINK_FALLBACK_CODES = new Set(["EACCES", "EPERM", "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+export function isHardlinkFallbackError(error) {
+    return HARDLINK_FALLBACK_CODES.has(error?.code ?? "");
+}

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

@@ -3,6 +3,7 @@ export type * from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, type Root, } from "./root.js";
 export type * from "./root-public-types.js";
 export { configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export { getFsSafeNativeStatus } from "./config.js";
 export type * from "./config.js";
 export { writeExternalFileWithinRoot, } from "./output.js";
 export type * from "./output.js";

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

@@ -1,5 +1,6 @@
 export { FsSafeError, categorizeFsSafeError, isNoReplaceUnsupported, } from "./errors.js";
 export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
 export { configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export { getFsSafeNativeStatus } from "./config.js";
 export { writeExternalFileWithinRoot, } from "./output.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { isHardlinkFallbackError } from "./hardlink-fallback.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
@@ -61,6 +62,18 @@ async function withQueueEntryLock(paths, run) {
     assertNoWindowsPathAlias(resolvedJsonPath);
     return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(resolvedJsonPath, run));
 }
+async function linkQueueGeneration(sourcePath, targetPath) {
+    try {
+        await fs.link(sourcePath, targetPath);
+    }
+    catch (error) {
+        // Shared inode identity is recovery evidence; a copy cannot replace it.
+        if (isHardlinkFallbackError(error)) {
+            throw new FsSafeError("helper-unavailable", "durable queue ownership requires hardlink support", { cause: error });
+        }
+        throw error;
+    }
+}
 async function claimDurableQueueEntryUnlocked(paths, options = {}) {
     const processingPath = paths.processingPath;
     await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
@@ -92,7 +105,7 @@ async function claimDurableQueueEntryUnlocked(paths, options = {}) {
         throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
     }
     try {
-        await fs.link(paths.jsonPath, processingPath);
+        await linkQueueGeneration(paths.jsonPath, processingPath);
     }
     catch (error) {
         if (getErrorCode(error) === "EEXIST") {
@@ -227,7 +240,7 @@ export async function moveDurableQueueEntryToFailed(params) {
             throw new FsSafeError("already-exists", "failed queue destination already exists");
         }
         if (!failed)
-            await fs.link(sourcePath, failedPath);
+            await linkQueueGeneration(sourcePath, failedPath);
         await syncDirectory(path.dirname(failedPath));
         await fs.unlink(sourcePath);
         await syncDirectory(path.dirname(sourcePath));
@@ -305,7 +318,7 @@ async function recoverDurableQueueRetirement(params) {
     if (!sameFileIdentityForCleanup(entry, processing)) {
         const pending = regularQueueFileIdentity(params.jsonPath, "retirement");
         if (!pending) {
-            await fs.link(entryPath, params.jsonPath);
+            await linkQueueGeneration(entryPath, params.jsonPath);
             await syncDirectory(path.dirname(params.jsonPath));
         }
         else if (sameFileIdentityForCleanup(pending, entry)) {