@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,530 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { rootHandleContext } from "./root-handle-context.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { admittedNativeChanges } from "./watch-alias.js";
+import { watchStreamPaths } from "./watch-stream.js";
+import { changedEntries, excludedWatchPath, guardedHintChanges, scopedChanges } from "./watch-hints.js";
+import path from "node:path";
+import { watchBinding, NativeWatchBackend } from "./watch-native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { isWatchPathError, scanWatch, watchScopes } from "./watch-scan.js";
+function deferred() {
+    let settled = false;
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    // Ownership exists even when a consumer closes without awaiting startup.
+    void promise.catch(() => { });
+    return { promise, get settled() { return settled; },
+        resolve() { settled = true; resolve(); },
+        reject(error) { settled = true; reject(error); },
+    };
+}
+function budget(value, fallback, name, max = 1_000_000) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > max)
+        throw new RangeError("invalid watch " + name);
+    return result;
+}
+const retired = () => new DOMException("Watch generation retired", "AbortError");
+const coalesceMs = 25;
+/** Advisory observation only. Hints never grant filesystem authority. */
+export function watch(root, input) {
+    const context = rootHandleContext(root);
+    const options = { ...input };
+    const persistent = options.persistent !== false;
+    if (!["auto", "events", "poll"].includes(options.mode))
+        throw new TypeError("invalid watch mode");
+    let binding;
+    let selectionFailure;
+    try {
+        binding = watchBinding(options.mode);
+    }
+    catch (error) {
+        selectionFailure = error;
+    }
+    let mode = binding || options.mode === "events" ? "events" : "poll";
+    let intervalMs = budget(options.intervalMs, mode === "events" ? 30_000 : 1000, "intervalMs", 2_147_483_647);
+    if (intervalMs < 20)
+        throw new RangeError("watch intervalMs must be at least 20");
+    const pollIntervalMs = budget(options.pollIntervalMs, options.intervalMs ?? 1000, "pollIntervalMs", 2_147_483_647);
+    if (pollIntervalMs < 20)
+        throw new RangeError("watch pollIntervalMs must be at least 20");
+    if (mode === "poll")
+        intervalMs = pollIntervalMs;
+    const maxDirectories = budget(options.maxDirectories, 4096, "maxDirectories");
+    const maxEntries = budget(options.maxEntries, 100_000, "maxEntries");
+    const maxPendingPaths = budget(options.maxPendingPaths, 256, "maxPendingPaths", 4096);
+    if (typeof options.onInvalidate !== "function")
+        throw new TypeError("watch requires onInvalidate");
+    const makeGeneration = (scopes) => ({
+        scopes: watchScopes(scopes), abort: new AbortController(), waiter: deferred(),
+    });
+    let current = makeGeneration(options.scopes);
+    const ready = current.waiter.promise;
+    let state = "starting";
+    let terminal = false;
+    let failure;
+    let failureInfo;
+    let retirementFailure;
+    const retirementErrors = new Set();
+    let closing;
+    let active;
+    let backend;
+    const registered = new Map();
+    let observedDirectories = 0;
+    let snapshot;
+    let resetRequested = false;
+    let refreshBackend = false;
+    let pending = false;
+    let pendingWaiter;
+    let runningWaiter;
+    let pendingHint = false;
+    let pendingBackendOverflow = false;
+    let pendingChanges = new Map();
+    let timer;
+    let hintTimer;
+    const combinedFailure = () => {
+        if (!retirementFailure)
+            return failure;
+        const error = retirementFailure.error;
+        if (failure === undefined || error === failure || error?.suppressed === failure)
+            return error;
+        return createSuppressedError(error, failure, "watch observation and retirement failed");
+    };
+    const retainRetirement = (error) => {
+        if (retirementErrors.has(error))
+            return;
+        retirementErrors.add(error);
+        retirementFailure = { error: retirementFailure
+                ? createSuppressedError(error, retirementFailure.error, "watch retirement failed more than once") : error };
+    };
+    const health = () => Object.freeze({
+        state, mode, directories: observedDirectories,
+        ...(failure === undefined && !retirementFailure ? {} : {
+            failure: retirementFailure ? Object.freeze({ operation: "close", error: combinedFailure() }) : failureInfo,
+        }),
+    });
+    const check = (g) => {
+        g.abort.signal.throwIfAborted();
+        if (terminal || current !== g)
+            throw retired();
+        if (failure !== undefined)
+            throw failure;
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const clearTimers = () => {
+        clearTimeout(timer);
+        clearTimeout(hintTimer);
+        timer = undefined;
+        hintTimer = undefined;
+        pending = false;
+        pendingHint = false;
+        pendingChanges = new Map();
+        pendingBackendOverflow = false;
+    };
+    const notifyHealth = () => {
+        try {
+            const result = options.onHealth?.(health());
+            assertSynchronousCallbackResult(result, "watch onHealth");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch health callback failed", { cause, details: { operation: "callback" } });
+        }
+    };
+    const dirty = (g, reason, changes) => {
+        check(g);
+        try {
+            const result = options.onInvalidate(Object.freeze({ reason, changes: changes && Object.freeze(changes) }));
+            assertSynchronousCallbackResult(result, "watch onInvalidate");
+        }
+        catch (cause) {
+            throw new FsSafeError("helper-failed", "watch dirty callback failed", { cause, details: { operation: "callback" } });
+        }
+        check(g);
+    };
+    const retain = (error) => {
+        if (failure === undefined) {
+            failure = error;
+            failureInfo = Object.freeze({ operation: "close", error });
+        }
+        else if (error !== failure)
+            failure = createSuppressedError(error, failure, "watch and retirement both failed");
+    };
+    const retireBackend = async () => {
+        const old = backend;
+        try {
+            await old?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        if (backend === old) {
+            backend = undefined;
+            registered.clear();
+            observedDirectories = 0;
+        }
+        if (retirementFailure)
+            throw retirementFailure.error;
+    };
+    const lose = (error, operation = "scan") => {
+        if (terminal || failure !== undefined)
+            return;
+        if (error === undefined)
+            error = new FsSafeError("helper-failed", "watch operation failed without an error value", { details: { operation } });
+        retain(error);
+        const details = error instanceof FsSafeError ? error.details : undefined;
+        const code = details?.code ?? error?.code;
+        failureInfo = Object.freeze({ error, operation: details?.operation === "watch" ? "watch" : details?.operation === "callback" ? "callback" : details?.operation === "close" ? "close" : operation, ...(typeof code === "string" ? { code } : {}) });
+        current.abort.abort(error);
+        current.waiter.reject(error);
+        pendingWaiter?.reject(error);
+        runningWaiter?.reject(error);
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        state = "unavailable";
+        // Stop backend admission before notifying. Its join remains owned by active/close.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        try {
+            notifyHealth();
+        }
+        catch (callbackError) {
+            retain(callbackError);
+        }
+    };
+    const scheduleInterval = () => {
+        if (terminal || failure !== undefined)
+            return;
+        timer = setTimeout(() => { timer = undefined; void request().catch(() => { }); }, intervalMs);
+        if (!persistent)
+            timer.unref();
+    };
+    const onHint = (g, batch) => {
+        if (terminal || current !== g || g.abort.signal.aborted || failure !== undefined)
+            return;
+        if (batch.overflow) {
+            pendingBackendOverflow = true;
+            try {
+                assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "received"), "afterWatchBackendOverflow");
+            }
+            catch (error) {
+                lose(error, "callback");
+                return;
+            }
+        }
+        if (batch.error === "ESTALE")
+            refreshBackend = true;
+        else if (batch.error) {
+            lose(new FsSafeError("helper-failed", "native watch failed", { details: { operation: "watch", code: batch.error } }));
+            return;
+        }
+        if (batch.overflow)
+            pendingChanges = undefined;
+        else if (pendingChanges)
+            for (const hint of batch.hints) {
+                if (typeof hint.name === "string" && excludedWatchPath(snapshot, hint.directory ? path.join(hint.directory, hint.name) : hint.name))
+                    continue;
+                const key = JSON.stringify([hint.directory, hint.name]);
+                if (!pendingChanges.has(key) && pendingChanges.size >= maxPendingPaths) {
+                    pendingChanges = undefined;
+                    break;
+                }
+                const previous = pendingChanges.get(key);
+                pendingChanges.set(key, previous?.event === "rename" ? previous : hint);
+            }
+        pendingHint = true;
+        pending = true;
+        if (hintTimer)
+            return;
+        hintTimer = setTimeout(() => {
+            hintTimer = undefined;
+            if (terminal || current !== g || failure !== undefined)
+                return;
+            // Raw backend filenames stay private. Reconcile before publishing detail.
+            void request().catch(() => { });
+        }, coalesceMs);
+        if (!persistent)
+            hintTimer.unref();
+    };
+    const fallBack = (error) => {
+        if (options.mode !== "auto" || getFsSafeNativeConfig().mode === "require" ||
+            !(error instanceof FsSafeError) || error.code !== "helper-unavailable")
+            return false;
+        mode = "poll";
+        binding = undefined;
+        intervalMs = pollIntervalMs;
+        return true;
+    };
+    const observe = async (g) => {
+        check(g);
+        if (selectionFailure !== undefined)
+            throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { cause: selectionFailure, details: { operation: "watch" } });
+        if (refreshBackend) {
+            await retireBackend();
+            check(g);
+            refreshBackend = false;
+        }
+        if (resetRequested) {
+            await retireBackend();
+            check(g);
+            snapshot = undefined;
+            resetRequested = false;
+        }
+        state = snapshot ? "reconciling" : "starting";
+        notifyHealth();
+        check(g);
+        const hadHints = pendingHint;
+        const hadBackendOverflow = pendingBackendOverflow;
+        const hints = pendingChanges;
+        pendingHint = false;
+        pendingChanges = new Map();
+        pendingBackendOverflow = false;
+        clearTimeout(hintTimer);
+        hintTimer = undefined;
+        if (mode === "events" && !backend && g.scopes.length) {
+            try {
+                const candidate = new NativeWatchBackend(binding, context, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, maxPendingPaths, persistent);
+                backend = candidate;
+                if (snapshot)
+                    candidate.configure(watchStreamPaths(snapshot, g.scopes));
+                const hookResult = getFsSafeTestHooks()?.afterWatchBackendCreated?.(context.rootReal, batch => {
+                    if (backend === candidate)
+                        onHint(g, batch);
+                }, (path, flags) => candidate.testEvent(path, flags));
+                assertSynchronousCallbackResult(hookResult, "afterWatchBackendCreated");
+            }
+            catch (error) {
+                if (!fallBack(error))
+                    throw error;
+            }
+            check(g);
+        }
+        const next = await scanWatch(context, g.scopes, { exclude: options.exclude, maxDirectories, maxEntries, maxPendingPaths, admitting: !snapshot, previous: snapshot }, g.abort.signal, async (name, identity, guard) => {
+            check(g);
+            const existing = registered.get(name);
+            const acquire = !existing || existing.dev !== identity.dev || existing.ino !== identity.ino;
+            await getFsSafeTestHooks()?.beforeWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire) {
+                try {
+                    backend?.add(name, identity);
+                }
+                catch (error) {
+                    if (snapshot || !fallBack(error))
+                        throw error;
+                    await retireBackend();
+                    check(g);
+                }
+            }
+            await getFsSafeTestHooks()?.afterWatchRegistration?.(guard.realPath);
+            check(g);
+            if (acquire)
+                registered.set(name, identity);
+        }, retainRetirement);
+        check(g);
+        if (backend?.configure(watchStreamPaths(next, g.scopes))) {
+            // The replacement stream is live before the next guarded pass covers the handover.
+            pending = true;
+        }
+        // Retire stale inventory before the next pass; that crawl installs fresh anchors first.
+        if ([...registered.keys()].some(name => !next.directories.has(name))) {
+            refreshBackend = true;
+        }
+        observedDirectories = next.directories.size;
+        const initial = !snapshot;
+        let observed = next.overflow ? undefined : changedEntries(snapshot, next, maxPendingPaths);
+        if (observed) {
+            const changes = new Map(observed.map(change => [change.path, change]));
+            for (const name of next.structural ?? [])
+                for (const change of scopedChanges(g.scopes, { path: name, type: "structural" }))
+                    changes.set(change.path, change);
+            observed = changes.size > maxPendingPaths ? undefined : [...changes.values()];
+        }
+        let admittedHints = [];
+        try {
+            if (hadHints)
+                admittedHints = await admittedNativeChanges(context, g.scopes, snapshot, next, {
+                    hints: hints ? [...hints.values()] : [], overflow: !hints,
+                }, g.abort.signal, maxPendingPaths);
+        }
+        catch (error) {
+            check(g);
+            await assertRootIdentityCurrent(context);
+            if (!isWatchPathError(error))
+                throw error;
+            admittedHints = undefined;
+        }
+        check(g);
+        await assertRootIdentityCurrent(context);
+        check(g);
+        let details = hadHints
+            ? guardedHintChanges(g.scopes, snapshot, next, admittedHints, observed, maxPendingPaths)
+            : observed;
+        snapshot = next;
+        if (!initial && !details && hadBackendOverflow) {
+            assertSynchronousCallbackResult(getFsSafeTestHooks()?.afterWatchBackendOverflow?.(context.rootReal, "reconciled"), "afterWatchBackendOverflow");
+        }
+        // Publish before readiness; callbacks may synchronously retire this generation.
+        if (initial || !details || details.length)
+            dirty(g, initial ? "reconcile" : !details ? "overflow" : hadHints ? "event" : "reconcile", initial ? undefined : details);
+        check(g);
+        state = "ready";
+        notifyHealth();
+        check(g);
+    };
+    const pump = () => {
+        if (active || terminal || failure !== undefined)
+            return;
+        // Enroll before any callback. There is one active pass and one coalesced request.
+        active = Promise.resolve().then(async () => {
+            do {
+                const g = current;
+                pending = false;
+                if (pendingWaiter) {
+                    // A scope replacement keeps reconcile requests alive until its baseline completes.
+                    const previous = runningWaiter;
+                    runningWaiter = pendingWaiter;
+                    pendingWaiter = undefined;
+                    if (previous)
+                        void runningWaiter.promise.then(() => previous.resolve(), error => previous.reject(error));
+                }
+                try {
+                    await observe(g);
+                    check(g);
+                    g.waiter.resolve();
+                    runningWaiter?.resolve();
+                    runningWaiter = undefined;
+                }
+                catch (error) {
+                    g.waiter.reject(error);
+                    if (!g.abort.signal.aborted && current === g && !terminal)
+                        lose(error);
+                    try {
+                        await retireBackend();
+                    }
+                    catch (closeError) {
+                        retainRetirement(closeError);
+                    }
+                }
+                if (current !== g) {
+                    await retireBackend();
+                    snapshot = undefined;
+                    pending = true;
+                }
+            } while (pending && !terminal && failure === undefined);
+        }).catch(lose).finally(() => {
+            active = undefined;
+            if (!terminal && failure === undefined) {
+                if (pending || !current.waiter.settled)
+                    pump();
+                else
+                    scheduleInterval();
+            }
+        });
+    };
+    const request = () => {
+        if (terminal)
+            return Promise.reject(retired());
+        if (failure !== undefined)
+            return Promise.reject(failure);
+        clearTimeout(timer);
+        timer = undefined;
+        pending = true;
+        pendingWaiter ??= deferred();
+        const result = pendingWaiter.promise;
+        pump();
+        return result;
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        terminal = true;
+        current.abort.abort(retired());
+        current.waiter.reject(retired());
+        pendingWaiter?.reject(retired());
+        runningWaiter?.reject(retired());
+        pendingWaiter = undefined;
+        runningWaiter = undefined;
+        clearTimers();
+        options.signal?.removeEventListener("abort", abort);
+        // Start physical stop immediately, without waiting behind an in-flight scan.
+        try {
+            backend?.close();
+        }
+        catch (error) {
+            retainRetirement(error);
+        }
+        closing = Promise.resolve().then(async () => {
+            await active;
+            try {
+                await retireBackend();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            state = "closed";
+            if (retirementFailure)
+                throw combinedFailure();
+        });
+        void closing.catch(() => { });
+        return closing;
+    };
+    const abort = () => { void close(); };
+    const subscription = {
+        ready, health, close, [Symbol.asyncDispose]: close,
+        reconcile: request,
+        setScopes(scopes) {
+            if (terminal)
+                return Promise.reject(retired());
+            if (failure !== undefined)
+                return Promise.reject(failure);
+            const previous = current;
+            const next = makeGeneration(scopes);
+            // Scope accessors may synchronously close this owner during validation.
+            if (terminal || failure !== undefined || current !== previous) {
+                next.waiter.reject(failure ?? retired());
+                return next.waiter.promise;
+            }
+            current.abort.abort(retired());
+            current.waiter.reject(retired());
+            current = next;
+            resetRequested = true;
+            try {
+                backend?.close();
+            }
+            catch (error) {
+                retainRetirement(error);
+            }
+            clearTimers();
+            state = "starting";
+            // If idle, retire the old backend before the next scan can admit anything.
+            if (!active) {
+                active = retireBackend().catch(error => lose(error, "close")).finally(() => {
+                    active = undefined;
+                    snapshot = undefined;
+                    pump();
+                });
+            }
+            return next.waiter.promise;
+        },
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    else
+        pump();
+    return subscription;
+}

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

@@ -1,2 +1 @@
 export declare function resolveWindowsSystemCommand(command: string, env?: NodeJS.ProcessEnv): string;
-//# sourceMappingURL=windows-command.d.ts.map

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

@@ -1,20 +1,16 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
 }>;
-export type WindowsOwnerSummary = {
+export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     sid?: string;
     currentUserSid?: string;
     daclPresent?: boolean;
     aces?: WindowsOwnerAce[];
     aclError?: string;
-    remote?: boolean;
     trusted?: boolean;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsOwnerAce = {
     sid: string;
     mask: number;
@@ -26,4 +22,3 @@ export declare function inspectWindowsOwner(params: {
     env?: NodeJS.ProcessEnv;
     exec: WindowsOwnerExec;
 }): Promise<WindowsOwnerSummary>;
-//# sourceMappingURL=windows-owner.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/windows-owner.js

@@ -1,4 +1,4 @@
-import { formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
+import { formatCaughtPermissionFailure, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
@@ -14,6 +14,7 @@ function windowsOwnerQueryCommand(targetPath) {
     const encodedPath = Buffer.from(targetPath, "utf8").toString("base64");
     return [
         "$ErrorActionPreference='Stop'",
+        "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
         `$p=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
         "$sections=[System.Security.AccessControl.AccessControlSections]::Access -bor [System.Security.AccessControl.AccessControlSections]::Owner",
         "$acl=if([IO.Directory]::Exists($p)){[IO.Directory]::GetAccessControl($p,$sections)}else{[IO.File]::GetAccessControl($p,$sections)}",
@@ -29,7 +30,7 @@ function windowsOwnerQueryCommand(targetPath) {
         "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
         "$dacl=$raw.DiscretionaryAcl;$complete=$true",
         "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|Microsoft.PowerShell.Utility\\ConvertTo-Json -Depth 4 -Compress",
     ].join(";");
 }
 function parseWindowsAclFacts(parsed) {
@@ -78,18 +79,20 @@ export async function inspectWindowsOwner(params) {
         if (!ownerSid || !currentUserSid) {
             return { error: "Windows owner query returned invalid SID data" };
         }
-        const remote = parsed.remote === true;
+        const remote = parsed.remote;
+        if (typeof remote !== "boolean") {
+            return { error: "Windows owner query returned invalid locality data" };
+        }
         return {
             sid: ownerSid,
             currentUserSid,
             ...parseWindowsAclFacts(parsed),
-            remote,
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };
     }
     catch (err) {
         return {
-            error: formatPermissionErrorDetail(String(err)),
+            error: formatCaughtPermissionFailure(err),
             errorDetail: getPermissionCommandFailure(err, command, performance.now() - startedAt),
             errorCause: err,
         };

package/node_modules/@openclaw/fs-safe/dist/windows-path-alias.d.ts

@@ -36,4 +36,4 @@ export declare function hasWindowsPathAlias(value: string, kind: WindowsPathAlia
 export declare function assertNoWindowsPathAliasForPlatform(value: string, kind: WindowsPathAliasKind, message: string, platform: NodeJS.Platform | string | undefined): void;
 export declare function assertNoWindowsPathAlias(value: string, kind?: WindowsPathAliasKind, message?: string, platform?: NodeJS.Platform | string): void;
 export declare function isWindowsPathAliasError(error: unknown): error is FsSafeError;
-//# sourceMappingURL=windows-path-alias.d.ts.map
+export declare function admitStandalonePublicationPath(value: string, message?: string): string;