@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -2,9 +2,8 @@ import { syncFileBestEffort, syncFileBestEffortSync } from "./file-sync.js";
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+import { ownDirectoryMode } from "./directory-mode-node.js";
 export async function syncDirectoryBestEffort(fsModule, dirPath) {
     let handle;
     try {
@@ -15,7 +14,12 @@ export async function syncDirectoryBestEffort(fsModule, dirPath) {
         // Best-effort on platforms/filesystems that do not support directory fsync.
     }
     finally {
-        await handle?.close().catch(() => undefined);
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Best-effort close also covers synchronous adapter throws.
+        }
     }
 }
 export function syncDirectoryBestEffortSync(fsModule, dirPath) {
@@ -48,12 +52,7 @@ function assertDirectory(identity, dirPath) {
     if (identity.isSymbolicLink() || !identity.isDirectory()) {
         throw new FsSafeError("not-file", `Atomic replace parent must be a real directory: ${dirPath}`);
     }
-}
-function assertSameDirectory(expected, opened, dirPath) {
-    assertDirectory(opened, dirPath);
-    if (!sameFileIdentity(expected, opened)) {
-        throw new FsSafeError("path-mismatch", `Atomic replace parent changed before its mode could be applied: ${dirPath}`);
-    }
+    return identity;
 }
 export async function pinDirectoryForMode(params) {
     // Node does not enforce POSIX directory modes on Windows, and its directory
@@ -63,17 +62,21 @@ export async function pinDirectoryForMode(params) {
         return;
     }
     const expected = params.fsModule === fs
-        ? syncFs.lstatSync(params.dirPath) : await params.fsModule.lstat(params.dirPath);
-    assertDirectory(expected, params.dirPath);
+        ? inspectFileIdentitySync(() => assertDirectory(syncFs.lstatSync(params.dirPath, { bigint: true }), params.dirPath))
+        : await inspectFileIdentity(async () => assertDirectory(await params.fsModule.lstat(params.dirPath, { bigint: true }), params.dirPath));
     const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
     try {
         const owner = ownDirectoryMode({
             async inspect() {
-                const opened = params.fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
-                assertOwnedDirectory(expected, opened);
-                return opened.mode & 0o7777;
+                const opened = params.fsModule === fs
+                    ? inspectFileIdentitySync(() => assertDirectory(syncFs.fstatSync(handle.fd, { bigint: true }), params.dirPath), expected)
+                    : await inspectFileIdentity(async () => assertDirectory(await handle.stat({ bigint: true }), params.dirPath), expected);
+                return Number(opened.mode & 4095n);
+            },
+            chmod: (mode) => {
+                params.mutation?.assert();
+                return handle.chmod(mode);
             },
-            chmod: (mode) => handle.chmod(mode),
             close: () => handle.close(),
             ignoreChmodError: params.ignoreChmodError,
         });
@@ -98,12 +101,12 @@ export function applyDirectoryModeSync(params) {
     if (process.platform === "win32") {
         return;
     }
-    const expected = params.fsModule.lstatSync(params.dirPath);
-    assertDirectory(expected, params.dirPath);
+    const expected = inspectFileIdentitySync(() => assertDirectory(params.fsModule.lstatSync(params.dirPath, { bigint: true }), params.dirPath));
     const fd = params.fsModule.openSync(params.dirPath, directoryOpenFlags());
     try {
-        assertSameDirectory(expected, params.fsModule.fstatSync(fd), params.dirPath);
+        inspectFileIdentitySync(() => assertDirectory(params.fsModule.fstatSync(fd, { bigint: true }), params.dirPath), expected);
         // chmod ignores file-type bits; mask so raw stat modes are tolerated.
+        params.mutation?.assert();
         params.fchmodSync?.(fd, params.mode & 0o7777);
     }
     finally {
@@ -111,6 +114,7 @@ export function applyDirectoryModeSync(params) {
     }
 }
 export async function writeTempFile(params) {
+    params.mutation?.assert();
     const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
     try {
         // Custom adapters retain their async-only metadata contract.
@@ -118,6 +122,7 @@ export async function writeTempFile(params) {
             ? syncFs.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
         const identity = await inspectFileIdentity(inspect);
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         await params.fsModule.writeFile(handle, params.content);
         await handle.chmod(params.mode);
         if (params.sync) {
@@ -137,10 +142,12 @@ export async function writeTempFile(params) {
     }
 }
 export function writeTempFileSync(params) {
+    params.mutation?.assert();
     const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
     try {
         const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         params.fsModule.writeFileSync(fd, params.content);
         params.fchmodSync?.(fd, params.mode);
         if (params.sync) {

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

@@ -0,0 +1,21 @@
+import fsSync from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import type { AtomicMutation } from "./replace-file-mutation.js";
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export declare function captureAtomicDestination(fsModule: Pick<typeof fs, "lstat">, handle: FileHandle, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): Promise<{
+    verify: () => Promise<void>;
+    writing: () => void;
+    beforeWrite: () => Promise<void>;
+    beforeRestore: () => Promise<void>;
+    verifyRestore: () => Promise<void>;
+    assertBeforeMutation: () => void;
+    published: () => void;
+}>;
+export declare function captureAtomicDestinationSync(fsModule: Pick<typeof fsSync, "lstatSync" | "fstatSync">, fd: number, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): {
+    verify: () => void;
+    writing: () => void;
+    beforeWrite: () => void;
+    beforeRestore: () => void;
+    verifyRestore: () => void;
+    published: () => void;
+};

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

@@ -0,0 +1,123 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { hasErrorCode } from "./file-cleanup.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+function regular(stat, pathname, rejectHardlinks) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new FsSafeError("path-mismatch", `Atomic replace destination changed: ${pathname}`);
+    }
+    if (rejectHardlinks && stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${pathname}`);
+    }
+    return stat;
+}
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export async function captureAtomicDestination(fsModule, handle, pathname, mutation, rejectHardlinks) {
+    const inspect = () => fsModule === fs
+        ? fsSync.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
+    const identity = await inspectFileIdentity(inspect);
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verifyDescriptor = async () => {
+        await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+    };
+    const verify = async () => {
+        let metadataFailure = false;
+        const observe = async (read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            await inspectFileIdentity(async () => regular(await observe(inspect), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await observe(() => fsModule.lstat(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                // A metadata observation failed, but the already-owned descriptor can
+                // still restore its bytes after fresh exact descriptor verification.
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = async () => {
+        if (!restoreDescriptorOnly)
+            return await verify();
+        try {
+            await verifyDescriptor();
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        beforeRestore: async () => { mutation.assert(); await verifyRestore(); },
+        verifyRestore,
+        assertBeforeMutation: () => mutation.assert(),
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}
+export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, rejectHardlinks) {
+    const identity = inspectFileIdentitySync(() => fsModule.fstatSync(fd, { bigint: true }));
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verify = () => {
+        let metadataFailure = false;
+        const observe = (read) => {
+            try {
+                return read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.fstatSync(fd, { bigint: true })), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.lstatSync(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = () => {
+        if (!restoreDescriptorOnly)
+            return verify();
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        beforeRestore: () => { mutation.assert(); verifyRestore(); },
+        verifyRestore,
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}

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

@@ -1,3 +1,2 @@
 import type { Stats } from "node:fs";
 export declare function inheritedRegularFileMode(stat: Stats): number;
-//# sourceMappingURL=replace-file-mode.d.ts.map

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

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+export type ReplaceFileAtomicDestinationState = Readonly<{
+    state: "removed";
+    path: string;
+}> | Readonly<{
+    state: "writing" | "published";
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export type AtomicMutationOptions = {
+    /** Recheck live authority before new effects; retained descriptor completion may settle. */
+    assertBeforeMutation?: () => void;
+    /** Retain observed destination facts even when later completion fails. */
+    onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
+};
+export declare class AtomicMutation {
+    #private;
+    readonly active: boolean;
+    constructor(options: AtomicMutationOptions);
+    rethrowRefusal(): void;
+    refuse(error: unknown): never;
+    assert(): void;
+    destination(state: "writing" | "published", path: string, identity: BigIntStats): void;
+    removed(path: string): void;
+}

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

@@ -0,0 +1,47 @@
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export class AtomicMutation {
+    active;
+    #assertion;
+    #observer;
+    #refusal;
+    #writingReported = false;
+    constructor(options) {
+        this.#assertion = options.assertBeforeMutation;
+        this.#observer = options.onDestinationState;
+        this.active = Boolean(this.#assertion || this.#observer);
+    }
+    rethrowRefusal() {
+        if (this.#refusal)
+            throw this.#refusal.error;
+    }
+    refuse(error) {
+        this.#refusal ??= { error };
+        throw this.#refusal.error;
+    }
+    #invoke(operation, name) {
+        this.rethrowRefusal();
+        try {
+            const result = operation();
+            assertSynchronousCallbackResult(result, name);
+        }
+        catch (error) {
+            this.refuse(error);
+        }
+    }
+    assert() {
+        this.#invoke(() => this.#assertion?.(), "assertBeforeMutation");
+    }
+    destination(state, path, identity) {
+        if (state === "writing") {
+            if (this.#writingReported)
+                return;
+            this.#writingReported = true;
+        }
+        this.#invoke(() => this.#observer?.(Object.freeze({
+            state, path, dev: identity.dev, ino: identity.ino,
+        })), "onDestinationState");
+    }
+    removed(path) {
+        this.#invoke(() => this.#observer?.(Object.freeze({ state: "removed", path })), "onDestinationState");
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-rename-policy.d.ts

@@ -1,7 +1,5 @@
-import type { RenameIdentityPolicy } from "./pinned-write.js";
-export type { RenameIdentityPolicy };
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
 export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
 export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
 export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;
-//# sourceMappingURL=replace-file-rename-policy.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/replace-file-temp-owner.d.ts

@@ -1,54 +1,49 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import { type TempPathRegistration } from "./temp-cleanup.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export type AtomicTempFailure = Readonly<{
+    error: unknown;
+}>;
 export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
-export declare function cleanupPinnedFilePath(params: {
-    pathname: string;
-    handle: FileHandle;
-    identity?: BigIntStats;
-    parentGuard: AnyAsyncDirectoryGuard;
-}): Promise<void>;
-export declare class AsyncAtomicTempOwner {
-    #private;
+declare class AtomicTempOwner<Resource> {
     readonly pathname: string;
+    protected resource: Resource | undefined;
+    protected recordedIdentity: BigIntStats | undefined;
+    protected exists: boolean;
+    protected unregister: TempPathRegistration;
     constructor(pathname: string);
     start(): void;
     readonly onIdentity: (identity: BigIntStats) => void;
+    get identity(): BigIntStats;
+    markRenamed(): void;
+    protected takeResource(): Resource | undefined;
+}
+export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
     adopt(temp: {
         handle: FileHandle;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
-    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
-    markRenamed(): void;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): Promise<void>;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): Promise<void>;
 }
-export declare class SyncAtomicTempOwner {
-    #private;
-    readonly pathname: string;
-    constructor(pathname: string);
-    start(): void;
-    readonly onIdentity: (identity: BigIntStats) => void;
+export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
     adopt(temp: {
         fd: number;
         identity: BigIntStats;
     }): void;
-    get identity(): BigIntStats;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
-    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
-    markRenamed(): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): void;
 }
 export {};
-//# sourceMappingURL=replace-file-temp-owner.d.ts.map