@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -9,30 +9,29 @@ import { inheritedRegularFileMode } from "./replace-file-mode.js";
 import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
 import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
-function isRetryableRenameError(error) {
-    return error.code === "EBUSY";
-}
-function isPermissionRenameError(error) {
-    const code = error.code;
-    return code === "EPERM" || code === "EEXIST";
-}
+import { hasErrorCode, readErrorCode } from "./file-cleanup.js";
+import { AtomicMutation } from "./replace-file-mutation.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 async function renameWithRetry(params) {
     for (let attempt = 0; attempt <= params.maxRetries; attempt++) {
         if (attempt > 0)
             await params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             await params.fsModule.rename(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            params.mutation.rethrowRefusal();
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 await sleep(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 await copyFallbackReplace({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -42,6 +41,7 @@ async function renameWithRetry(params) {
                     maxRestoreBytes: params.maxRestoreBytes,
                     expectedSourceIdentity: params.sourceIdentity,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -55,15 +55,18 @@ function renameWithRetrySync(params) {
         if (attempt > 0)
             params.assertSourceCurrent();
         try {
+            params.mutation.assert();
             params.fsModule.renameSync(params.src, params.dest);
             return { method: "rename" };
         }
         catch (error) {
-            if (isRetryableRenameError(error) && attempt < params.maxRetries) {
+            params.mutation.rethrowRefusal();
+            const code = readErrorCode(error);
+            if (code === "EBUSY" && attempt < params.maxRetries) {
                 sleepSync(params.baseDelayMs * 2 ** attempt);
                 continue;
             }
-            if (params.copyFallbackOnPermissionError && isPermissionRenameError(error)) {
+            if (params.copyFallbackOnPermissionError && (code === "EPERM" || code === "EEXIST")) {
                 copyFallbackReplaceSync({
                     fsModule: params.fsModule,
                     src: params.src,
@@ -74,6 +77,7 @@ function renameWithRetrySync(params) {
                     expectedSourceIdentity: params.sourceIdentity,
                     fchmodSync: params.fchmodSync,
                     sync: params.syncFallback,
+                    mutation: params.mutation,
                 });
                 return { method: "copy-fallback" };
             }
@@ -114,7 +118,7 @@ async function resolveMode(options, filePath) {
         stat = fsModule === fs ? syncFs.lstatSync(filePath) : await fsModule.lstat(filePath);
     }
     catch (error) {
-        if (error.code === "ENOENT") {
+        if (hasErrorCode(error, "ENOENT")) {
             return defaultMode;
         }
         throw error;
@@ -132,7 +136,7 @@ function resolveModeSync(options, filePath) {
         stat = fsModule.lstatSync(filePath);
     }
     catch (error) {
-        if (error.code !== "ENOENT") {
+        if (!hasErrorCode(error, "ENOENT")) {
             throw error;
         }
     }
@@ -146,24 +150,27 @@ export async function replaceFileAtomic(options) {
 }
 // Internal owner hook: keep directory durability inside publication verification and serialization.
 export async function replaceFileAtomicWithDirectorySync(options, syncParent) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     return await serializePathWrite(path.resolve(filePath), async () => {
         if (renameIdentity !== "verify-content-with-lock") {
-            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent);
+            return await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent);
         }
         const fsModule = options.fileSystem?.promises ?? fs;
         const dir = path.dirname(filePath);
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, {
             recursive: true,
             mode: options.dirMode ?? 0o700,
         });
-        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent));
+        mutation.assert();
+        return await withAtomicRenameIdentityLock(filePath, async () => await replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent));
     });
 }
-async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, syncParent) {
+async function replaceFileAtomicUnserialized(options, filePath, renameIdentity, mutation, syncParent) {
     const fsModule = options.fileSystem?.promises ?? fs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -171,10 +178,11 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
     const expectedHash = atomicExpectedContentHash(renameIdentity, options.content);
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new AsyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
+        mutation.assert();
         await fsModule.mkdir(fsModule === fs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode });
+        await applyDirectoryMode({ fsModule, dirPath: dir, mode: dirMode, mutation });
         tempOwner.start();
         tempOwner.adopt(await writeTempFile({
             fsModule,
@@ -183,6 +191,7 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             mode,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         await tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
@@ -206,10 +215,11 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
             sourceIdentity: tempOwner.identity,
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            await tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            await tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             await tempOwner.assertCurrent(fsModule);
@@ -229,34 +239,37 @@ async function replaceFileAtomicUnserialized(options, filePath, renameIdentity,
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         await tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }
 }
 export function replaceFileAtomicSync(options) {
+    const mutation = new AtomicMutation(options);
     const filePath = validateReplaceFilePath(options.filePath);
     validateRestoreOptions(options);
     const renameIdentity = options.renameIdentity;
     validateRenameIdentity(renameIdentity);
     if (renameIdentity !== "verify-content-with-lock") {
-        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity);
+        return replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation);
     }
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
+    mutation.assert();
     fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, {
         recursive: true,
         mode: options.dirMode ?? 0o700,
     });
-    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity));
+    mutation.assert();
+    return withAtomicRenameIdentityLockSync(filePath, () => replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation));
 }
-function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
+function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity, mutation) {
     const fsModule = options.fileSystem ?? syncFs;
     const dir = path.dirname(filePath);
     const dirMode = options.dirMode ?? 0o700;
@@ -271,10 +284,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
     }
     const tempPath = buildReplaceTempPath(filePath, options.tempPrefix);
     const tempOwner = new SyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
+        mutation.assert();
         fsModule.mkdirSync(fsModule === syncFs ? recursiveMkdirPath(dir) : dir, { recursive: true, mode: dirMode });
-        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync });
+        applyDirectoryModeSync({ fsModule, dirPath: dir, mode: dirMode, fchmodSync, mutation });
         tempOwner.start();
         tempOwner.adopt(writeTempFileSync({
             fsModule,
@@ -284,10 +298,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             fchmodSync,
             sync: options.syncTempFile === true,
             onIdentity: tempOwner.onIdentity,
+            mutation,
         }));
         tempOwner.assertCurrent(fsModule);
         if (options.beforeRename) {
-            options.beforeRename({ filePath, tempPath });
+            assertSynchronousCallbackResult(options.beforeRename({ filePath, tempPath }), "beforeRename");
             tempOwner.assertCurrent(fsModule);
         }
         if (options.destinationHardlinks === "reject") {
@@ -308,10 +323,11 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
             assertSourceCurrent: () => tempOwner.assertCurrent(fsModule),
             fchmodSync,
             syncFallback: options.syncTempFile === true,
+            mutation,
         });
         if (result.method === "rename") {
             tempOwner.markRenamed();
-            tempOwner.assertPublished(fsModule, filePath, expectedHash);
+            tempOwner.assertPublished(fsModule, filePath, expectedHash, identity => mutation.destination("published", filePath, identity));
         }
         else {
             tempOwner.assertCurrent(fsModule);
@@ -327,13 +343,13 @@ function replaceFileAtomicSyncUnserialized(options, filePath, renameIdentity) {
         return result;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
         tempOwner.finish({
             fsModule,
-            originalError,
+            originalFailure,
             throwOnCleanupError: options.throwOnCleanupError === true,
         });
     }

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

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+import type { NativeBinding, NativeOwnedTreeRemovalResult } from "./native-binding.js";
+type RenameBinding = NativeBinding & Required<Pick<NativeBinding, "renameNoReplaceWithIdentity">>;
+export type RetainedReplacementParent = Readonly<{
+    path: string;
+    realPath: string;
+    identity: Pick<BigIntStats, "dev" | "ino">;
+}>;
+export declare function copyOperationalCode(target: Error, source: unknown): void;
+export declare class RetainedDirectoryReplacement {
+    #private;
+    private constructor();
+    static requireBinding(): RenameBinding;
+    static retain(params: {
+        targetParent: RetainedReplacementParent;
+        stagedParent: RetainedReplacementParent;
+        originalTarget?: Readonly<{
+            path: string;
+            identity: Pick<BigIntStats, "dev" | "ino">;
+        }>;
+    }, binding?: RenameBinding): RetainedDirectoryReplacement;
+    renameNoReplace(sourceParent: "staged" | "target", sourceBasename: string, targetBasename: string, expectedSource: Pick<BigIntStats, "dev" | "ino">): void;
+    removeOriginal(backupBasename: string): Promise<NativeOwnedTreeRemovalResult["outcome"]>;
+    close(): void;
+}
+export {};

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

@@ -0,0 +1,193 @@
+import fsSync from "node:fs";
+import { assertDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+function helperUnavailable(message, cause) {
+    return new FsSafeError("helper-unavailable", message, {
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+export function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function primaryWithCloseFailure(error, closeError, message) {
+    const cause = new AggregateError([error, closeError], message);
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, {
+            cause,
+            ...(error.details ? { details: error.details } : {}),
+        });
+    }
+    const wrapped = new Error(message, { cause });
+    copyOperationalCode(wrapped, error);
+    return wrapped;
+}
+function supportsRename(binding) {
+    return typeof binding?.renameNoReplaceWithIdentity === "function";
+}
+function supportsCleanup(binding) {
+    return typeof binding.ownedTreeRemovalAvailable === "function" &&
+        typeof binding.removeOwnedTree === "function";
+}
+function closeDescriptors(descriptors) {
+    const errors = [];
+    const closed = new Set();
+    for (const fd of descriptors) {
+        if (fd === undefined || closed.has(fd))
+            continue;
+        closed.add(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "retained directory replacement descriptors failed to close");
+    }
+}
+const retainedDirectoryOpenFlags = fsSync.constants.O_RDONLY |
+    fsSync.constants.O_DIRECTORY |
+    fsSync.constants.O_NOFOLLOW |
+    fsSync.constants.O_NONBLOCK;
+function openRetainedDirectory(label, expected) {
+    let fd;
+    try {
+        fd = fsSync.openSync(expected.path, retainedDirectoryOpenFlags);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM") {
+            const purpose = label === "original target"
+                ? "original target for bounded cleanup"
+                : label;
+            throw helperUnavailable(`atomic directory replacement cannot retain the ${purpose}`, error);
+        }
+        throw error;
+    }
+    try {
+        const descriptor = fsSync.fstatSync(fd, { bigint: true });
+        if (!descriptor.isDirectory()) {
+            throw new FsSafeError("not-file", `directory replacement ${label} must be a directory`);
+        }
+        if (descriptor.dev !== expected.identity.dev || descriptor.ino !== expected.identity.ino) {
+            throw new FsSafeError("path-mismatch", `directory replacement ${label} changed during admission`);
+        }
+        assertDirectoryIdentitySync(expected.path, {
+            dev: expected.identity.dev,
+            ino: expected.identity.ino,
+            ...(expected.realPath === undefined ? {} : { realPath: expected.realPath }),
+        });
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch (closeError) {
+            throw primaryWithCloseFailure(error, closeError, `directory replacement ${label} admission and close failed`);
+        }
+        throw error;
+    }
+    return fd;
+}
+export class RetainedDirectoryReplacement {
+    #binding;
+    #originalDirectoryFd;
+    #stagedParentFd;
+    #targetParentFd;
+    #cleanupUsed = false;
+    #closed = false;
+    constructor(binding, targetParentFd, stagedParentFd, originalDirectoryFd) {
+        this.#binding = binding;
+        this.#targetParentFd = targetParentFd;
+        this.#stagedParentFd = stagedParentFd;
+        this.#originalDirectoryFd = originalDirectoryFd;
+    }
+    static requireBinding() {
+        const binding = getNativeBinding();
+        if (!supportsRename(binding)) {
+            throw helperUnavailable("atomic directory replacement requires native identity-fenced no-replace rename support");
+        }
+        return binding;
+    }
+    static retain(params, binding = RetainedDirectoryReplacement.requireBinding()) {
+        let targetParentFd;
+        let stagedParentFd;
+        let originalDirectoryFd;
+        try {
+            targetParentFd = openRetainedDirectory("target parent", params.targetParent);
+            stagedParentFd = params.stagedParent.path === params.targetParent.path
+                ? targetParentFd
+                : openRetainedDirectory("staged parent", params.stagedParent);
+            if (params.originalTarget) {
+                if (!supportsCleanup(binding)) {
+                    throw helperUnavailable("replacing an existing directory requires native bounded owned-tree cleanup");
+                }
+                let available = false;
+                try {
+                    available = binding.ownedTreeRemovalAvailable(targetParentFd) === true;
+                }
+                catch (error) {
+                    throw helperUnavailable("native owned-tree cleanup capability probe failed", error);
+                }
+                if (!available) {
+                    throw helperUnavailable("native owned-tree cleanup is unavailable for the target parent");
+                }
+                originalDirectoryFd = openRetainedDirectory("original target", {
+                    path: params.originalTarget.path,
+                    identity: params.originalTarget.identity,
+                });
+            }
+            return new RetainedDirectoryReplacement(binding, targetParentFd, stagedParentFd, originalDirectoryFd);
+        }
+        catch (error) {
+            try {
+                closeDescriptors([originalDirectoryFd, stagedParentFd, targetParentFd]);
+            }
+            catch (closeError) {
+                throw primaryWithCloseFailure(error, closeError, "retained directory replacement admission and descriptor close failed");
+            }
+            throw error;
+        }
+    }
+    renameNoReplace(sourceParent, sourceBasename, targetBasename, expectedSource) {
+        if (this.#closed) {
+            throw new FsSafeError("path-mismatch", "retained directory rename authority is unavailable");
+        }
+        this.#binding.renameNoReplaceWithIdentity(sourceParent === "staged" ? this.#stagedParentFd : this.#targetParentFd, sourceBasename, this.#targetParentFd, targetBasename, expectedSource.dev, expectedSource.ino);
+    }
+    async removeOriginal(backupBasename) {
+        if (this.#closed || this.#cleanupUsed || this.#originalDirectoryFd === undefined ||
+            !supportsCleanup(this.#binding)) {
+            throw new FsSafeError("path-mismatch", "retained owned-tree cleanup authority is unavailable");
+        }
+        this.#cleanupUsed = true;
+        const result = await this.#binding.removeOwnedTree(this.#targetParentFd, backupBasename, this.#originalDirectoryFd);
+        if (result.errorCode) {
+            if (result.errorCode === "path-mismatch") {
+                throw new FsSafeError("path-mismatch", result.errorMessage ?? "native owned-tree cleanup lost retained identity");
+            }
+            throw Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), { code: result.errorCode });
+        }
+        if (result.outcome !== "removed" && result.outcome !== "preserved") {
+            throw helperUnavailable("native owned-tree cleanup returned an invalid result");
+        }
+        return result.outcome;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        closeDescriptors([
+            this.#originalDirectoryFd,
+            this.#stagedParentFd,
+            this.#targetParentFd,
+        ]);
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { StagedFileReceipt } from "./staged-file-types.js";
+/** Exact producer observations: never supply rounded Number identities. */
+export type RetainedFileExpected = Readonly<Pick<StagedFileReceipt["identity"], "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs"> & {
+    /** Lowercase SHA-256 of the producer's expected bytes. */
+    sha256: string;
+}>;
+export type RetainedFileIssue = Readonly<{
+    phase: string;
+    code: string;
+    message: string;
+    cause?: unknown;
+}>;
+/** Descriptive facts, not a deletion capability or a durable transaction receipt. */
+export type RetainedFileResult = Readonly<{
+    status: "unsupported" | "not-attempted" | "preserved-mismatch" | "disposition-accepted" | "name-absent-after-settlement" | "failed" | "indeterminate";
+    phase: string;
+    /** Full native 64-bit volume serial and 128-bit file ID, when observed. */
+    identity?: string;
+    disposition: "not-attempted" | "accepted" | "rejected" | "indeterminate";
+    namespace: "not-observed" | "absent" | "original" | "foreign" | "unknown";
+    resources: "closed" | "close-failed";
+    persistence: "not-proven";
+    errors: readonly RetainedFileIssue[];
+}>;
+export type RetainedFileReceipt = Readonly<{
+    directory: string;
+    parent: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    basename: string;
+    expected: RetainedFileExpected;
+    identity: string;
+}>;
+export interface RetainedFile extends Disposable {
+    readonly receipt: RetainedFileReceipt;
+    /** One-shot, synchronous authority admission; always settles owned resources. */
+    remove(): RetainedFileResult;
+    /** Closes only. Never requests deletion, including after an exception. */
+    dispose(): RetainedFileResult;
+}
+export type RetainedFileAdmission = Readonly<{
+    status: "retained";
+    file: RetainedFile;
+}> | RetainedFileResult;
+export type RetainFileInDirectoryOptions = Readonly<Pick<RetainedFileReceipt, "directory" | "parent" | "basename" | "expected"> & {
+    assertBeforeMutation: () => void;
+    /** Synchronous verification budget, default 16 MiB; maximum 64 MiB. */
+    maxBytes?: number;
+}>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import type { RetainedFileAdmission, RetainFileInDirectoryOptions } from "./retained-file-types.js";
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export declare function retainFileInDirectory(options: RetainFileInDirectoryOptions): RetainedFileAdmission;

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

@@ -0,0 +1,121 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+function freeze(result) {
+    return Object.freeze({ ...result, errors: Object.freeze(result.errors.map((error) => Object.freeze({ ...error }))) });
+}
+function unsupported(cause) {
+    return freeze({ status: "unsupported", phase: "admission", disposition: "not-attempted",
+        namespace: "not-observed", resources: "closed", persistence: "not-proven",
+        errors: [{ phase: "admission", code: "helper-unavailable",
+                message: "existing-file retention requires the maintained Windows native capability", cause }] });
+}
+function exact(value, name, zero = false) {
+    if (typeof value !== "bigint" || value < (zero ? 0n : 1n) || value > 0xffffffffffffffffn) {
+        throw new TypeError(`${name} must be an exact ${zero ? "nonnegative" : "positive"} unsigned 64-bit bigint`);
+    }
+    return value;
+}
+class Owner {
+    receipt;
+    #native;
+    #assert;
+    #result;
+    #running = false;
+    #reentered = false;
+    constructor(native, receipt, assertion) {
+        this.#native = native;
+        this.receipt = receipt;
+        this.#assert = assertion;
+        Object.freeze(this);
+    }
+    #settle(remove) {
+        if (this.#result)
+            return this.#result;
+        if (this.#running) {
+            this.#reentered = true;
+            throw new TypeError("retained-file settlement cannot be reentered");
+        }
+        this.#running = true;
+        let rejection;
+        if (remove) {
+            try {
+                assertSynchronousCallbackResult(this.#assert(), "assertBeforeMutation");
+                if (this.#reentered)
+                    throw new TypeError("retained-file authority reentered settlement");
+            }
+            catch (cause) {
+                rejection = { cause };
+            }
+        }
+        try {
+            const result = this.#native.settle(remove && !rejection);
+            this.#result = freeze(rejection ? { ...result, phase: "authority", errors: [
+                    { phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause },
+                    ...result.errors,
+                ] } : result);
+        }
+        catch (cause) {
+            // An unexpected binding exception cannot establish native effect or close.
+            // Do not retry or release a dependency on an unknown native outcome.
+            this.#result = freeze({ status: "indeterminate", phase: "binding", identity: this.receipt.identity,
+                disposition: remove && !rejection ? "indeterminate" : "not-attempted", namespace: "unknown",
+                resources: "close-failed", persistence: "not-proven", errors: [
+                    ...(rejection ? [{ phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause }] : []),
+                    { phase: "binding", code: "helper-failed", message: "native settlement did not return a result", cause },
+                ] });
+        }
+        return this.#result;
+    }
+    remove() { return this.#settle(true); }
+    dispose() { return this.#settle(false); }
+    [Symbol.dispose]() {
+        const result = this.dispose();
+        if (result.resources !== "closed") {
+            throw new FsSafeError("helper-failed", "retained-file resource settlement is uncertain", { details: { result } });
+        }
+    }
+}
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export function retainFileInDirectory(options) {
+    // Snapshot once before any native resource admission or caller authority runs.
+    const directory = options.directory;
+    const basename = options.basename;
+    const sourceParent = options.parent;
+    const parent = Object.freeze({ dev: exact(sourceParent.dev, "parent.dev"), ino: exact(sourceParent.ino, "parent.ino") });
+    const source = options.expected;
+    const expected = Object.freeze({ dev: exact(source.dev, "expected.dev"), ino: exact(source.ino, "expected.ino"),
+        size: exact(source.size, "expected.size", true), mtimeNs: exact(source.mtimeNs, "expected.mtimeNs", true),
+        ctimeNs: exact(source.ctimeNs, "expected.ctimeNs", true), sha256: source.sha256 });
+    const assertion = options.assertBeforeMutation;
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    if (typeof directory !== "string" || typeof basename !== "string" || typeof assertion !== "function"
+        || typeof expected.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(expected.sha256)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 64 * 1024 * 1024 || expected.size > BigInt(maxBytes)) {
+        throw new TypeError("invalid retained-file directory, authority or bounded expected-byte contract");
+    }
+    if (process.platform !== "win32")
+        return unsupported();
+    let binding;
+    try {
+        binding = getNativeBinding();
+    }
+    catch (cause) {
+        return unsupported(cause);
+    }
+    if (!binding?.retainWindowsFile)
+        return unsupported();
+    let native;
+    try {
+        native = binding.retainWindowsFile(directory, basename, parent.dev, parent.ino, expected.dev, expected.ino, expected.size, expected.mtimeNs, expected.ctimeNs, expected.sha256, maxBytes);
+    }
+    catch (cause) {
+        // Factory errors have no returned owner; never infer absence or deletion.
+        return freeze({ ...unsupported(cause), status: "indeterminate", resources: "close-failed" });
+    }
+    const admission = native.admission;
+    if (admission.status !== "retained")
+        return freeze(admission);
+    const receipt = Object.freeze({ directory, parent, basename, expected, identity: admission.identity });
+    return Object.freeze({ status: "retained", file: new Owner(native, receipt, assertion) });
+}

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

@@ -1,3 +1,4 @@
+export declare function sameNormalizedPathSpelling(left: string, right: string): boolean;
 export type RootBoundaryIdentity = Readonly<{
     dev: number | bigint;
     ino: number | bigint;
@@ -26,4 +27,3 @@ export declare function admitPathInsideRoot(params: {
         ino: bigint;
     }>) => void;
 }): AdmittedRootPath | undefined;
-//# sourceMappingURL=root-boundary.d.ts.map