@openclaw/openshell-sandbox 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/private-producer-handoff-sync.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { ownFileDescriptorSync } from "./create-owned-file.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertInitialSource, FileHandoff, inspectLinkedFile, } from "./private-producer-handoff.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+export function handoffCreatedFileSync(params) {
+    let retained = params.source;
+    const owners = new Set([retained]);
+    const failures = [];
+    const state = new FileHandoff(params, params.identity, true);
+    function close(owner) {
+        // A throwing close may already have released the descriptor for reuse.
+        owners.delete(owner);
+        try {
+            owner.close();
+        }
+        catch (error) {
+            state.closeFailed = true;
+            throw error;
+        }
+    }
+    function verifyCurrent(owner, descriptorPath, links) {
+        state.inspect(owner, links);
+        params.verifyDescriptor?.(owner.fd, descriptorPath, Number(links));
+    }
+    try {
+        assertInitialSource(params.identity);
+        verifyCurrent(retained, params.sourcePath, 1n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(retained, 1n);
+        state.publish();
+        try {
+            params.onPublished?.();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (process.platform === "win32") {
+            verifyCurrent(retained, params.sourcePath, 2n);
+            // Keep the original pin until a verified published-name pin exists, so
+            // Windows can retire the staging name without leaving it delete-pending.
+            const sibling = ownFileDescriptorSync(fs.openSync(params.targetPath, fs.constants.O_RDWR | resolveReadOpenFlags()));
+            owners.add(sibling);
+            verifyCurrent(sibling, params.targetPath, 2n);
+            inspectLinkedFile(() => fs.fstatSync(retained.fd, { bigint: true }), params.identity, 2n, "created file descriptor");
+            close(retained);
+            retained = sibling;
+        }
+        const descriptorPath = process.platform === "win32" ? params.targetPath : params.sourcePath;
+        verifyCurrent(retained, descriptorPath, 2n);
+        assertSynchronousCallbackResult(params.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(retained, 2n);
+        // Link and unlink stay in one JS turn. Only the verified stage is removed;
+        // publication has committed and the destination is never rollback cleanup.
+        state.retireSource();
+        verifyCurrent(retained, params.targetPath, 1n);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length === 0)
+        return retained;
+    for (const owner of owners) {
+        try {
+            close(owner);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    throw state.failure(failures, "created file publication and settlement failed");
+}

package/node_modules/@openclaw/fs-safe/dist/private-producer-handoff.d.ts

@@ -1,16 +1,53 @@
 import { type BigIntStats } from "node:fs";
 import { type FileHandle } from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
 import { type TempPathRegistration } from "./temp-cleanup.js";
 export type PrivateProducerHandoff = {
     handle: FileHandle;
     identity: BigIntStats;
     unregister: TempPathRegistration;
 };
-export declare function handoffPrivateProducerFile(params: {
-    sourcePath: string;
-    targetPath: string;
+type HandoffParents = {
     assertSourceParent: () => void;
     assertTargetParent: () => void;
+};
+type HandoffPaths = HandoffParents & {
+    sourcePath: string;
+    targetPath: string;
+};
+type ProducerHandoffParams = HandoffPaths & {
     readWrite: boolean;
-}): Promise<PrivateProducerHandoff>;
-//# sourceMappingURL=private-producer-handoff.d.ts.map
+};
+export type CreatedHandoffParams<TSource = FileHandle, TVerification = Promise<void>> = HandoffPaths & {
+    source: TSource;
+    identity: BigIntStats;
+    assertBeforeMutation?: () => void;
+    verifyDescriptor?: (fd: number, path: string, links: number) => TVerification;
+    onPublished?: () => void;
+};
+export declare function assertInitialSource(stat: BigIntStats): void;
+export declare function inspectLinkedFile(inspect: () => BigIntStats, expected: BigIntStats, links: bigint, label: string): BigIntStats;
+export declare function assertParents(params: HandoffParents): void;
+export declare function normalizeLinkError(error: unknown): unknown;
+export declare class FileHandoff {
+    private readonly paths;
+    private readonly identity;
+    private readonly createdLabels;
+    siblingOwned: boolean;
+    publication: "not-published" | "published" | "indeterminate";
+    cleanup: "preserved" | "removed" | "failed";
+    closeFailed: boolean;
+    constructor(paths: HandoffPaths, identity: BigIntStats, createdLabels?: boolean);
+    inspect(owner: {
+        readonly fd: number;
+    }, links: bigint): {
+        opened: BigIntStats;
+        named?: BigIntStats;
+    };
+    publish(): void;
+    retireSource(): void;
+    failure(failures: readonly unknown[], aggregateMessage: string): FsSafeError;
+}
+export declare function handoffPrivateProducerFile(params: ProducerHandoffParams): Promise<PrivateProducerHandoff>;
+export declare function handoffCreatedFile(params: CreatedHandoffParams): Promise<FileHandle>;
+export {};

package/node_modules/@openclaw/fs-safe/dist/private-producer-handoff.js

@@ -2,13 +2,14 @@ import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { registerTempPathForExit, } from "./temp-cleanup.js";
 function pathMismatch(message) {
     return new FsSafeError("path-mismatch", message);
 }
-function assertInitialSource(stat) {
+export function assertInitialSource(stat) {
     if (stat.isSymbolicLink()) {
         throw new FsSafeError("path-alias", "isolated producer output must not be a symlink");
     }
@@ -19,7 +20,7 @@ function assertInitialSource(stat) {
         throw new FsSafeError("hardlink", "isolated producer output must have exactly one link");
     }
 }
-function inspectLinkedFile(inspect, expected, links, label) {
+export function inspectLinkedFile(inspect, expected, links, label) {
     return inspectFileIdentitySync(() => {
         const stat = inspect();
         if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== links) {
@@ -28,11 +29,11 @@ function inspectLinkedFile(inspect, expected, links, label) {
         return stat;
     }, expected);
 }
-function assertParents(params) {
+export function assertParents(params) {
     params.assertTargetParent();
     params.assertSourceParent();
 }
-function normalizeLinkError(error) {
+export function normalizeLinkError(error) {
     const code = error?.code;
     if (code === "EEXIST") {
         return new FsSafeError("already-exists", "isolated producer sibling already exists", {
@@ -101,7 +102,7 @@ async function throwAfterClosing(primary, handles) {
     throw combinedFailure(primary, settlement);
 }
 function inspectSourceDescriptor(handle, identity, links = 1n) {
-    inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
+    return inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
 }
 function historicalOpenFlags(readWrite) {
     const access = readWrite ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
@@ -164,109 +165,194 @@ async function openProducerSource(params, identity, links = 1n) {
     }
     return fallback;
 }
-function assertLinkedHandoff(params, handle, identity) {
-    assertParents(params);
-    inspectSourceDescriptor(handle, identity, 2n);
-    inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 2n, "isolated producer path");
-    inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 2n, "isolated producer sibling");
+export class FileHandoff {
+    paths;
+    identity;
+    createdLabels;
+    siblingOwned = false;
+    publication = "not-published";
+    cleanup = "preserved";
+    closeFailed = false;
+    constructor(paths, identity, createdLabels = false) {
+        this.paths = paths;
+        this.identity = identity;
+        this.createdLabels = createdLabels;
+    }
+    inspect(owner, links) {
+        assertParents(this.paths);
+        const opened = inspectLinkedFile(() => fsSync.fstatSync(owner.fd, { bigint: true }), this.identity, links, this.createdLabels ? "created file descriptor" : "isolated producer descriptor");
+        if (this.cleanup !== "removed") {
+            inspectLinkedFile(() => fsSync.lstatSync(this.paths.sourcePath, { bigint: true }), this.identity, links, this.createdLabels ? "created file stage" : "isolated producer path");
+        }
+        const named = this.publication === "published"
+            ? inspectLinkedFile(() => fsSync.lstatSync(this.paths.targetPath, { bigint: true }), this.identity, links, this.createdLabels ? "created file destination" : "isolated producer sibling")
+            : undefined;
+        return { opened, named };
+    }
+    publish() {
+        this.publication = "indeterminate";
+        try {
+            fsSync.linkSync(this.paths.sourcePath, this.paths.targetPath);
+        }
+        catch (error) {
+            const normalized = normalizeLinkError(error);
+            if (normalized instanceof FsSafeError &&
+                (normalized.code === "already-exists" || normalized.code === "helper-unavailable")) {
+                this.publication = "not-published";
+            }
+            throw normalized;
+        }
+        this.publication = "published";
+    }
+    retireSource() {
+        this.cleanup = "failed";
+        fsSync.unlinkSync(this.paths.sourcePath);
+        this.cleanup = "removed";
+    }
+    failure(failures, aggregateMessage) {
+        const primary = failures[0];
+        // Collision-as-no-op callers must still observe a failed settlement.
+        return new FsSafeError(this.closeFailed || failures.length > 1 ? "helper-failed" : primary instanceof FsSafeError ? primary.code : "helper-failed", "created file publication failed", {
+            cause: failures.length === 1 ? primary : new AggregateError(failures, aggregateMessage),
+            details: {
+                publication: { status: this.publication }, cleanup: this.cleanup,
+                resources: this.closeFailed ? "close-failed" : "closed",
+                path: this.paths.targetPath, dev: this.identity.dev, ino: this.identity.ino,
+            },
+        });
+    }
 }
-export async function handoffPrivateProducerFile(params) {
-    assertParents(params);
-    const identity = inspectFileIdentitySync(() => {
+async function handoffFile(params) {
+    const created = "source" in params ? params : undefined;
+    const identity = created?.identity ?? inspectFileIdentitySync(() => {
+        assertParents(params);
         const stat = fsSync.lstatSync(params.sourcePath, { bigint: true });
         assertInitialSource(stat);
         return stat;
     });
-    let handle;
-    let siblingHandle;
+    let handle = created?.source;
+    const owners = new Set(handle ? [handle] : []);
+    const failures = [];
     let unregister;
-    const state = { siblingOwned: false };
+    const state = new FileHandoff(params, identity);
+    async function close(owned) {
+        // Final creation consumes its pin before close can release and recycle it.
+        // Legacy temporary handoff retains its historical FileHandle close retry.
+        if (created)
+            owners.delete(owned);
+        try {
+            await owned.close();
+            owners.delete(owned);
+        }
+        catch (error) {
+            state.closeFailed = true;
+            throw error;
+        }
+    }
     try {
-        handle = await openProducerSource(params, identity);
-        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 1n, "isolated producer path");
-        assertParents(params);
-        unregister = registerTempPathForExit(params.targetPath, {
-            cleanupSync: () => removeSiblingIfOwned({
-                assertTargetParent: params.assertTargetParent,
-                identity,
-                state,
-                targetPath: params.targetPath,
-            }),
-        });
-        assertParents(params);
+        assertInitialSource(identity);
+        if (!handle) {
+            handle = await openProducerSource({ ...params, readWrite: "readWrite" in params && params.readWrite }, identity);
+            owners.add(handle);
+        }
+        state.inspect(handle, 1n);
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, params.sourcePath, 1);
+        if (!created) {
+            unregister = registerTempPathForExit(params.targetPath, {
+                cleanupSync: () => removeSiblingIfOwned({
+                    assertTargetParent: params.assertTargetParent, identity, state, targetPath: params.targetPath,
+                }),
+            });
+        }
+        assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(handle, 1n);
+        state.publish();
+        state.siblingOwned = !created;
         try {
-            fsSync.linkSync(params.sourcePath, params.targetPath);
+            assertSynchronousCallbackResult(created?.onPublished?.(), "onPublished");
         }
         catch (error) {
-            throw normalizeLinkError(error);
+            failures.push(error);
         }
-        state.siblingOwned = true;
-        assertLinkedHandoff(params, handle, identity);
+        state.inspect(handle, 2n);
         if (process.platform === "win32") {
             // Legacy Windows unlink retains a delete-pending name until handles
             // opened through that name close. Transfer the pin before retiring it.
-            siblingHandle = await openProducerSource({ ...params, sourcePath: params.targetPath }, identity, 2n);
-            assertLinkedHandoff(params, siblingHandle, identity);
+            const sibling = created
+                ? await fs.open(params.targetPath, historicalOpenFlags(true))
+                : await openProducerSource({ ...params, sourcePath: params.targetPath,
+                    readWrite: "readWrite" in params && params.readWrite }, identity, 2n);
+            owners.add(sibling);
+            state.inspect(sibling, 2n);
+            if (created?.verifyDescriptor)
+                await created.verifyDescriptor(sibling.fd, params.targetPath, 2);
+            state.inspect(sibling, 2n);
             inspectSourceDescriptor(handle, identity, 2n);
-            await handle.close();
-            handle = siblingHandle;
-            siblingHandle = undefined;
+            await close(handle);
+            handle = sibling;
             // The old handle's close yielded; both names must still be ours.
-            assertLinkedHandoff(params, handle, identity);
+            state.inspect(handle, 2n);
         }
-        assertParents(params);
-        fsSync.unlinkSync(params.sourcePath);
-        assertParents(params);
-        const opened = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
-        const sibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, process.platform === "win32" ? params.targetPath : params.sourcePath, 2);
+        assertSynchronousCallbackResult(created?.assertBeforeMutation?.(), "assertBeforeMutation");
+        state.inspect(handle, 2n);
+        state.retireSource();
+        if (created?.verifyDescriptor)
+            await created.verifyDescriptor(handle.fd, params.targetPath, 1);
+        const { opened, named } = state.inspect(handle, 1n);
         const originalMode = identity.mode & 511n;
-        if (process.platform === "win32" && (originalMode & 128n) === 0n &&
-            ((opened.mode & 511n) !== originalMode || (sibling.mode & 511n) !== originalMode)) {
+        if (!created && process.platform === "win32" && (originalMode & 128n) === 0n &&
+            ((opened.mode & 511n) !== originalMode || (named.mode & 511n) !== originalMode)) {
             // Legacy unlink clears the shared read-only attribute. Repair only the
             // admitted sibling inode, without reopening or chmodding its pathname.
             assertParents(params);
             fsSync.fchmodSync(handle.fd, Number(originalMode));
-            assertParents(params);
-            const restored = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
-            const restoredSibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
-            if ((restored.mode & 511n) !== originalMode || (restoredSibling.mode & 511n) !== originalMode) {
+            const restored = state.inspect(handle, 1n);
+            if ((restored.opened.mode & 511n) !== originalMode || (restored.named.mode & 511n) !== originalMode) {
                 throw pathMismatch("isolated producer read-only mode could not be restored");
             }
         }
-        const registered = unregister;
-        const release = (() => {
-            state.siblingOwned = false;
-            registered();
-        });
-        release.setIdentity = registered.setIdentity;
-        return { handle, identity, unregister: release };
+        if (!created) {
+            const registered = unregister;
+            const release = (() => {
+                state.siblingOwned = false;
+                registered();
+            });
+            release.setIdentity = registered.setIdentity;
+            return { handle, identity, unregister: release };
+        }
     }
     catch (error) {
-        const settlement = [];
-        if (unregister) {
-            try {
-                removeSiblingIfOwned({
-                    assertTargetParent: params.assertTargetParent,
-                    identity,
-                    state,
-                    targetPath: params.targetPath,
-                });
-                unregister();
-            }
-            catch (cleanupError) {
-                settlement.push(cleanupError);
-            }
+        failures.push(error);
+    }
+    if (failures.length === 0)
+        return handle;
+    if (unregister) {
+        try {
+            removeSiblingIfOwned({ assertTargetParent: params.assertTargetParent, identity, state, targetPath: params.targetPath });
+            unregister();
         }
-        for (const retained of new Set([siblingHandle, handle])) {
-            if (!retained)
-                continue;
-            try {
-                await retained.close();
-            }
-            catch (closeError) {
-                settlement.push(closeError);
-            }
+        catch (error) {
+            failures.push(error);
         }
-        throw combinedFailure(error, settlement);
     }
+    for (const owned of [...owners].reverse()) {
+        try {
+            await close(owned);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (!created)
+        throw combinedFailure(failures[0], failures.slice(1));
+    throw state.failure(failures, "isolated producer handoff and settlement failed");
+}
+export function handoffPrivateProducerFile(params) {
+    return handoffFile(params);
+}
+export function handoffCreatedFile(params) {
+    return handoffFile(params);
 }

package/node_modules/@openclaw/fs-safe/dist/private-temp-workspace.d.ts

@@ -5,4 +5,3 @@ export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<Te
 export declare function withTempWorkspace<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspace) => Promise<T>): Promise<T>;
 export declare function tempWorkspaceSync(options: TempWorkspaceOptions): TempWorkspaceSync;
 export declare function withTempWorkspaceSync<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspaceSync) => T): T;
-//# sourceMappingURL=private-temp-workspace.d.ts.map