@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,275 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrentSync } from "./root-context.js";
+import { directoryComponentNotDirectoryError, outsideWorkspaceError, } from "./root-errors.js";
+import { sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { assertFileLockSyncRootMutationAllowed, assertFileLockSyncRootResolvedPathCurrent, invokeFileLockSyncRootMutationAuthority, } from "./file-lock-sync-root.js";
+import { assertDirectoryCurrent, assertRegularFile, assertRetainedParentCurrent, exactFileIdentity, fileLockSyncRootReceiptStillCurrent, fileReceiptCurrentAfterParentCheck, observeDirectory, readFileLockSyncRootSnapshot, sameExactIdentity, } from "./file-lock-sync-root-io.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function ensureParent(pathAuthority) {
+    const authority = pathAuthority.authority;
+    const context = authority.context;
+    assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    const targetParent = path.dirname(pathAuthority.path);
+    const admitted = admitPathInsideRoot({
+        rootPath: context.rootReal,
+        candidatePath: targetParent,
+        rootIdentity: context.rootIdentity,
+    });
+    if (!admitted)
+        throw outsideWorkspaceError();
+    const relative = admitted.relativePath;
+    let current = context.rootReal;
+    let currentReceipt = observeDirectory(current);
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        const next = path.join(current, segment);
+        assertRootIdentityCurrentSync(context);
+        assertDirectoryCurrent(currentReceipt);
+        let missing = false;
+        let existing;
+        try {
+            existing = fs.lstatSync(pathForWindowsFilesystem(next), { bigint: true });
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                throw directoryComponentNotDirectoryError();
+            }
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+            missing = true;
+        }
+        if (missing) {
+            assertFileLockSyncRootMutationAllowed(next, authority.denyMutations);
+            const mutationAuthorityInvoked = invokeFileLockSyncRootMutationAuthority(authority);
+            if (mutationAuthorityInvoked) {
+                assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            }
+            assertDirectoryCurrent(currentReceipt);
+            assertRootIdentityCurrentSync(context);
+            // The callback may retarget a deny-policy alias at this particular
+            // intermediate component without changing the admitted final sidecar.
+            // Refresh the actual mkdir target after the callback and immediately
+            // before mutation.
+            if (mutationAuthorityInvoked) {
+                assertFileLockSyncRootMutationAllowed(next, authority.denyMutations);
+            }
+            try {
+                fs.mkdirSync(pathForWindowsFilesystem(next));
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        const nextReceipt = observeDirectory(next, existing);
+        assertDirectoryCurrent(currentReceipt);
+        current = nextReceipt.realPath;
+        currentReceipt = nextReceipt;
+    }
+    assertRootIdentityCurrentSync(context);
+    assertDirectoryCurrent(currentReceipt);
+    return currentReceipt;
+}
+export function createFileLockSyncRootFile(pathAuthority, options) {
+    const parent = ensureParent(pathAuthority);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority)) {
+        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, parent);
+    }
+    const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    let fd;
+    let receipt;
+    try {
+        options.assertBeforeOpen();
+        try {
+            fd = fs.openSync(pathForWindowsFilesystem(pathAuthority.path), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+        }
+        catch (error) {
+            options.onOpenFailure(error);
+            throw error;
+        }
+        const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }));
+        assertRegularFile(opened, pathAuthority.authority.hardlinks);
+        receipt = Object.freeze({ identity: exactFileIdentity(opened), parent });
+        if (!fileReceiptCurrentAfterParentCheck(pathAuthority, receipt)) {
+            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        if (fd === undefined)
+            throw error;
+        const failedFd = fd;
+        fd = undefined;
+        try {
+            fs.closeSync(failedFd);
+            if (receipt && !removeFileLockSyncRootFile(pathAuthority, receipt)) {
+                throw new FsSafeError("path-mismatch", "created sidecar lock changed before cleanup");
+            }
+        }
+        catch (cleanupError) {
+            throw createSuppressedError(error, cleanupError, "file lock create admission and cleanup both failed");
+        }
+        throw error;
+    }
+}
+export function refreshFileLockSyncRootFileReceipt(pathAuthority, receipt) {
+    if (!fileReceiptCurrentAfterParentCheck(pathAuthority, receipt)) {
+        throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+    }
+    return receipt;
+}
+export function removeFileLockSyncRootFile(pathAuthority, receipt, expected, assertBeforeRemove) {
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations);
+    const matches = () => {
+        if (!expected)
+            return fileLockSyncRootReceiptStillCurrent(pathAuthority, receipt);
+        const current = readFileLockSyncRootSnapshot(pathAuthority, {
+            expectedReceipt: receipt,
+        });
+        const matched = !!current &&
+            sameExactIdentity(current.receipt.identity, receipt.identity) &&
+            sidecarLockSnapshotMatches(current.snapshot, expected);
+        return matched;
+    };
+    if (!matches())
+        return false;
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority) && !matches())
+        return false;
+    if (assertBeforeRemove?.() === false)
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations);
+    fs.unlinkSync(pathForWindowsFilesystem(pathAuthority.path));
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    let successorStat;
+    try {
+        successorStat = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            return true;
+        throw error;
+    }
+    assertRegularFile(successorStat, pathAuthority.authority.hardlinks);
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    if (!sameExactIdentity(exactFileIdentity(successorStat), receipt.identity))
+        return true;
+    if (expected) {
+        const successor = readFileLockSyncRootSnapshot(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, receipt.parent);
+        if (successor) {
+            if (!sameExactIdentity(successor.receipt.identity, receipt.identity) ||
+                !sidecarLockSnapshotMatches(successor.snapshot, expected))
+                return true;
+        }
+        else {
+            // A null descriptor-bound snapshot can mean confirmed absence, a distinct
+            // replacement, or unverifiable identity. Re-observe once and accept only
+            // the first two states; ambiguity about the removed generation fails closed.
+            let current;
+            try {
+                current = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }));
+            }
+            catch (error) {
+                if (isNotFoundPathError(error)) {
+                    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+                    return true;
+                }
+                throw error;
+            }
+            assertRegularFile(current, pathAuthority.authority.hardlinks);
+            assertRetainedParentCurrent(pathAuthority, receipt.parent);
+            if (!sameExactIdentity(exactFileIdentity(current), receipt.identity))
+                return true;
+        }
+    }
+    throw new FsSafeError("path-mismatch", "sidecar lock was replaced during removal");
+}
+export function fileLockSyncRootGuardExists(pathAuthority) {
+    // The caller already admitted this path; every guard observation still needs
+    // an operation-local Root identity fence before fresh directory inspection.
+    assertRootIdentityCurrentSync(pathAuthority.authority.context);
+    let stat;
+    try {
+        stat = fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true });
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            assertRootIdentityCurrentSync(pathAuthority.authority.context);
+            return false;
+        }
+        throw error;
+    }
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+        throw directoryComponentNotDirectoryError();
+    }
+    if (stat.isFile())
+        assertRegularFile(stat, pathAuthority.authority.hardlinks);
+    const parent = observeDirectory(path.dirname(pathAuthority.path));
+    if (stat.isFile()) {
+        const current = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }), exactFileIdentity(stat));
+        assertRegularFile(current, pathAuthority.authority.hardlinks);
+    }
+    else {
+        inspectDirectoryIdentitySync(pathAuthority.path, exactFileIdentity(stat));
+    }
+    assertDirectoryCurrent(parent);
+    assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    assertRootIdentityCurrentSync(pathAuthority.authority.context);
+    return true;
+}
+export function createFileLockSyncRootDirectory(pathAuthority) {
+    const parent = ensureParent(pathAuthority);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority)) {
+        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, parent);
+    }
+    try {
+        fs.mkdirSync(pathForWindowsFilesystem(pathAuthority.path));
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return null;
+        throw error;
+    }
+    const stat = inspectDirectoryIdentitySync(pathAuthority.path);
+    const receipt = Object.freeze({ identity: exactFileIdentity(stat), parent });
+    assertRetainedParentCurrent(pathAuthority, parent);
+    inspectDirectoryIdentitySync(pathAuthority.path, receipt.identity);
+    return receipt;
+}
+export function removeFileLockSyncRootDirectory(pathAuthority, receipt) {
+    if (!fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt))
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations, true);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority) &&
+        !fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt))
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations, true);
+    fs.rmdirSync(pathForWindowsFilesystem(pathAuthority.path));
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return true;
+}
+export function fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt) {
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    try {
+        inspectDirectoryIdentitySync(pathAuthority.path, receipt.identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error) ||
+            (error instanceof FsSafeError && error.code === "path-mismatch"))
+            return false;
+        throw error;
+    }
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return true;
+}

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

@@ -0,0 +1,19 @@
+import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
+import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
+type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<{
+    compromiseCheckIntervalMs?: number;
+    lockPath?: string;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    optionsReceiver: FileLockSyncAcquireOptions<TPayload>;
+    parsePayload?: (raw: string) => unknown;
+    payload: () => TPayload;
+    reentrantOwner?: string;
+    retry: Readonly<SidecarLockRetryOptions>;
+    shouldReclaim?: FileLockSyncAcquireOptions<TPayload>["shouldReclaim"];
+    shouldRemoveStaleLock?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
+    staleMs: number;
+    staleRecovery?: SidecarLockStaleRecovery;
+    timeoutMs?: number;
+}>;
+export declare function captureRootSyncAcquireOptions<TPayload extends Record<string, unknown>>(options: FileLockSyncAcquireOptions<TPayload>): CapturedRootSyncAcquireOptions<TPayload>;
+export {};

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

@@ -0,0 +1,58 @@
+import { getFsSafeLockConfig } from "./lock-config.js";
+import { validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockStaleMs, validateSidecarLockTimeoutMs } from "./sidecar-lock-policy.js";
+export function captureRootSyncAcquireOptions(options) {
+    // Root authority is already validated and snapshotted before entering this
+    // helper. Snapshot every remaining caller-owned property before validating
+    // options; nested retry accessors must not be revisited by backoff or a
+    // callback that mutates the original options object.
+    const lockPath = options.lockPath;
+    const staleMsInput = options.staleMs;
+    const timeoutMsInput = options.timeoutMs;
+    const retryInput = options.retry;
+    const staleRecoveryInput = options.staleRecovery;
+    const reentrantOwner = options.reentrantOwner;
+    const payload = options.payload;
+    const shouldReclaim = options.shouldReclaim;
+    const shouldRemoveStaleLock = options.shouldRemoveStaleLock;
+    const parsePayload = options.parsePayload;
+    const onCompromised = options.onCompromised;
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    const retrySnapshot = retryInput === undefined ? undefined : Object.freeze({
+        retries: retryInput.retries,
+        factor: retryInput.factor,
+        minTimeout: retryInput.minTimeout,
+        maxTimeout: retryInput.maxTimeout,
+        randomize: retryInput.randomize,
+    });
+    const defaults = getFsSafeLockConfig();
+    const defaultRetry = defaults.retry;
+    const retry = retrySnapshot ?? Object.freeze({
+        retries: defaultRetry?.retries,
+        factor: defaultRetry?.factor,
+        minTimeout: defaultRetry?.minTimeout,
+        maxTimeout: defaultRetry?.maxTimeout,
+        randomize: defaultRetry?.randomize,
+    });
+    const timeoutMs = timeoutMsInput ?? defaults.timeoutMs;
+    const staleMs = staleMsInput ?? defaults.staleMs ?? 30_000;
+    const staleRecovery = staleRecoveryInput ?? defaults.staleRecovery;
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(timeoutMs);
+    validateSidecarLockStaleMs(staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    return Object.freeze({
+        compromiseCheckIntervalMs,
+        lockPath,
+        onCompromised,
+        optionsReceiver: options,
+        parsePayload,
+        payload,
+        reentrantOwner,
+        retry,
+        shouldReclaim,
+        shouldRemoveStaleLock,
+        staleMs,
+        staleRecovery,
+        timeoutMs,
+    });
+}

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

@@ -0,0 +1 @@
+export declare function ensureFileLockSyncRootExitCleanupRegistered(cleanupHandler: () => void): void;

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

@@ -0,0 +1,90 @@
+import { FsSafeError } from "./errors.js";
+import { createSuppressedError } from "./suppressed-error.js";
+const ROOT_SYNC_CLEANUP_REGISTERING_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistering.v1");
+const ROOT_SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistered.v1");
+const ROOT_SYNC_CLEANUP_FAILED_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistrationFailed.v1");
+const ROOT_SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupHandler.v1");
+function unavailable(message) {
+    return new FsSafeError("helper-unavailable", message);
+}
+function exactListenerCount(listener) {
+    return process.listeners("exit").filter((candidate) => candidate === listener).length;
+}
+export function ensureFileLockSyncRootExitCleanupRegistered(cleanupHandler) {
+    const state = globalThis;
+    if (state[ROOT_SYNC_CLEANUP_REGISTERED_KEY]) {
+        if (typeof state[ROOT_SYNC_CLEANUP_HANDLER_KEY] === "function")
+            return;
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+        throw unavailable("Root sidecar exit cleanup registration state is inconsistent");
+    }
+    if (state[ROOT_SYNC_CLEANUP_FAILED_KEY]) {
+        throw unavailable("Root sidecar exit cleanup registration previously failed");
+    }
+    if (state[ROOT_SYNC_CLEANUP_REGISTERING_KEY]) {
+        throw unavailable("Root sidecar exit cleanup registration is already in progress");
+    }
+    if (state[ROOT_SYNC_CLEANUP_HANDLER_KEY] !== undefined) {
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+        throw unavailable("Root sidecar exit cleanup handler exists without registration");
+    }
+    state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = true;
+    let baselineCount;
+    let registrationAttempted = false;
+    let registrationStateAmbiguous = false;
+    try {
+        baselineCount = exactListenerCount(cleanupHandler);
+        if (baselineCount !== 0) {
+            registrationStateAmbiguous = true;
+            throw unavailable("Root sidecar exit cleanup listener exists without registration");
+        }
+        registrationAttempted = true;
+        process.on("exit", cleanupHandler);
+        if (exactListenerCount(cleanupHandler) !== baselineCount + 1) {
+            throw unavailable("Root sidecar exit cleanup listener was not registered exactly once");
+        }
+        // Do not expose a callable handler or report success until process.on has
+        // returned and the exact listener registration has been observed.
+        state[ROOT_SYNC_CLEANUP_HANDLER_KEY] = cleanupHandler;
+        state[ROOT_SYNC_CLEANUP_REGISTERED_KEY] = true;
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = false;
+        state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = false;
+    }
+    catch (registrationError) {
+        let rollbackFailed = false;
+        let rollbackError;
+        if (registrationAttempted && baselineCount !== undefined) {
+            try {
+                let currentCount = exactListenerCount(cleanupHandler);
+                while (currentCount > baselineCount) {
+                    process.removeListener("exit", cleanupHandler);
+                    const nextCount = exactListenerCount(cleanupHandler);
+                    if (nextCount >= currentCount) {
+                        throw unavailable("Root sidecar exit cleanup listener rollback made no progress");
+                    }
+                    currentCount = nextCount;
+                }
+                if (currentCount !== baselineCount) {
+                    throw unavailable("Root sidecar exit cleanup listener rollback was ambiguous");
+                }
+            }
+            catch (error) {
+                rollbackFailed = true;
+                rollbackError = error;
+            }
+        }
+        state[ROOT_SYNC_CLEANUP_HANDLER_KEY] = undefined;
+        state[ROOT_SYNC_CLEANUP_REGISTERED_KEY] = false;
+        state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = false;
+        if (registrationStateAmbiguous) {
+            state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+            throw registrationError;
+        }
+        if (rollbackFailed) {
+            state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+            throw createSuppressedError(registrationError, rollbackError, "Root sidecar exit cleanup registration and rollback both failed");
+        }
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = false;
+        throw registrationError;
+    }
+}

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

@@ -0,0 +1,36 @@
+import { type RootContext } from "./root-context.js";
+import type { Root } from "./root-impl.js";
+import type { RootDefaults } from "./root-options.js";
+/** @internal Registers only instances constructed by RootHandle itself. */
+export declare function registerFileLockSyncRootAdapter(handle: object, context: RootContext, defaults: RootDefaults): void;
+export type FileLockSyncRootAuthority = Readonly<{
+    adapter: object;
+    context: RootContext;
+    assertBeforeMutation?: () => void;
+    denyMutations?: Readonly<{
+        paths?: readonly string[];
+        prefixes?: readonly string[];
+    }>;
+    hardlinks?: RootDefaults["hardlinks"];
+    mutationPolicy: RootPathResolutionPolicy;
+    readPolicy: RootPathResolutionPolicy;
+    policiesMatch: boolean;
+}>;
+export type FileLockSyncRootPath = Readonly<{
+    authority: FileLockSyncRootAuthority;
+    path: string;
+    relativePath: string;
+}>;
+export declare function captureFileLockSyncRootAuthority(lockRoot: Root): FileLockSyncRootAuthority;
+export declare function invokeFileLockSyncRootMutationAuthority(authority: FileLockSyncRootAuthority): boolean;
+export declare function assertFileLockSyncRootMutationAllowed(pathname: string, policy: FileLockSyncRootAuthority["denyMutations"], protectAncestors?: boolean): void;
+type RootPathResolutionPolicy = Readonly<{
+    rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    rejectUnresolvedSymlinks: true;
+}>;
+export declare function admitFileLockSyncRootPath(authority: FileLockSyncRootAuthority, requestedPath: string): FileLockSyncRootPath;
+export declare function assertFileLockSyncRootResolvedPathCurrent(pathAuthority: FileLockSyncRootPath): void;
+export declare function assertFileLockSyncRootPathsCurrent(paths: readonly FileLockSyncRootPath[]): void;
+export declare function normalizeFileLockSyncTargetWithRoot(authority: FileLockSyncRootAuthority, resolvedTargetPath: string): string;
+export {};