@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/path-prefix.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { assertNoNulPathInput, hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { absolutePathWithRawSegments } from "./root-path-existing.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rawRoot(absolutePath) {
+    if (path.sep === "\\" && /^\\\\[?.]\\UNC\\/i.test(absolutePath)) {
+        // Node parses only the namespace prefix as the root of an extended UNC path.
+        const shareRoot = path.parse(`\\\\${absolutePath.slice(8)}`).root;
+        return absolutePath.slice(0, shareRoot.length + 6);
+    }
+    return path.parse(absolutePath).root;
+}
+function resolutionError(code, absolutePath) {
+    const detail = code === "ELOOP" ? "too many symbolic links" : "not a directory";
+    return Object.assign(new Error(`${code}: ${detail}, resolvePathPrefix ${formatErrorDetail(absolutePath)}`), {
+        code, syscall: "resolvePathPrefix", path: absolutePath,
+    });
+}
+// Leave ample room for ordinary shallow paths to retain the legacy small-array
+// path. At 32 components, repeated front removal can reindex at most 496 array
+// positions per constructed queue; longer queues use a forward cursor instead.
+const SHIFT_QUEUE_COMPONENT_LIMIT = 32;
+export function resolvePathPrefixSync(input) {
+    assertNoNulPathInput(input);
+    const absolutePath = absolutePathWithRawSegments(input);
+    let resolved = rawRoot(absolutePath);
+    let remaining = absolutePath.slice(resolved.length).split(path.sep);
+    let shiftQueue = remaining.length <= SHIFT_QUEUE_COMPONENT_LIMIT;
+    let nextSegment = 0;
+    let remainingCount = remaining.length;
+    const visitedStates = new Set();
+    let symlinkHops = 0;
+    while (remainingCount > 0) {
+        const segment = shiftQueue ? remaining.shift() : remaining[nextSegment++];
+        remainingCount--;
+        if (segment === "")
+            continue;
+        if (segment === "." || segment === "..") {
+            const atRoot = resolved === rawRoot(resolved);
+            const lookup = segment === ".." && atRoot ? "." : segment;
+            // lstat(dir) does not test search permission, and realpath may erase dots.
+            const operationBase = pathForWindowsFilesystem(resolved);
+            fs.lstatSync(`${operationBase}${operationBase.endsWith(path.sep) ? "" : path.sep}${lookup}`, { bigint: true });
+            if (segment === ".." && !atRoot)
+                resolved = path.dirname(resolved);
+            continue;
+        }
+        const candidate = path.join(resolved, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(candidate, { bigint: true });
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                throw error;
+            return {
+                absolutePath,
+                existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)),
+                unresolvedSegments: shiftQueue ? [segment, ...remaining] : remaining.slice(nextSegment - 1),
+            };
+        }
+        if (!stat.isSymbolicLink()) {
+            if (!stat.isDirectory() && remainingCount > 0)
+                throw resolutionError("ENOTDIR", absolutePath);
+            resolved = candidate;
+            continue;
+        }
+        const pendingSuffix = shiftQueue ? remaining : remaining.slice(nextSegment);
+        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, pendingSuffix]);
+        if (symlinkHops >= 64 || visitedStates.has(state))
+            throw resolutionError("ELOOP", absolutePath);
+        visitedStates.add(state);
+        symlinkHops++;
+        const target = fs.readlinkSync(candidate);
+        const rawTarget = path.sep === "\\" ? target.replaceAll("/", "\\") : target;
+        let targetSegments;
+        if (path.isAbsolute(rawTarget)) {
+            const targetRoot = rawRoot(rawTarget);
+            // A rooted Windows link target uses the link's drive/share, not cwd's.
+            resolved = path.sep === "\\" && targetRoot === "\\" ? rawRoot(resolved) : targetRoot;
+            targetSegments = rawTarget.slice(targetRoot.length).split(path.sep);
+        }
+        else {
+            // A target's parent traversal applies after resolving its preceding links.
+            targetSegments = rawTarget.split(path.sep);
+        }
+        const expandedCount = targetSegments.length + pendingSuffix.length;
+        if (expandedCount <= SHIFT_QUEUE_COMPONENT_LIMIT) {
+            // The spread is bounded by the same fixed limit as subsequent shifts.
+            remaining = pendingSuffix;
+            remaining.unshift(...targetSegments);
+        }
+        else {
+            remaining = targetSegments.concat(pendingSuffix);
+        }
+        remainingCount = remaining.length;
+        shiftQueue = remainingCount <= SHIFT_QUEUE_COMPONENT_LIMIT;
+        nextSegment = 0;
+    }
+    return { absolutePath, existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)), unresolvedSegments: [] };
+}

package/node_modules/@openclaw/fs-safe/dist/path-scope-lexical.d.ts

@@ -0,0 +1,13 @@
+export type ResolvePathWithinRootParams = {
+    rootDir: string;
+    requestedPath: string;
+    scopeLabel: string;
+    defaultFileName?: string;
+};
+export declare function resolvePathWithinNormalizedRoot(params: ResolvePathWithinRootParams, root: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};

package/node_modules/@openclaw/fs-safe/dist/path-scope-lexical.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { isPathInside, isPathRelativeEscape } from "./path.js";
+import { hasWindowsPathAlias, resolvePathFromBasePreservingWindowsRoot } from "./windows-path-alias.js";
+function pathStaysWithinRoot(rootDir, candidatePath) {
+    if (process.platform !== "win32") {
+        return candidatePath !== rootDir && isPathInside(rootDir, candidatePath);
+    }
+    const relative = path.relative(rootDir, candidatePath);
+    return Boolean(relative) && !isPathRelativeEscape(relative);
+}
+export function resolvePathWithinNormalizedRoot(params, root) {
+    const requestedPath = params.requestedPath;
+    const defaultFileName = params.defaultFileName;
+    const scopeLabel = params.scopeLabel;
+    if (hasWindowsPathAlias(params.rootDir, "filesystem") ||
+        hasWindowsPathAlias(root, "filesystem") ||
+        hasWindowsPathAlias(requestedPath, "filesystem") ||
+        (defaultFileName !== undefined && hasWindowsPathAlias(defaultFileName, "filesystem"))) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+    }
+    const raw = requestedPath.trim();
+    if (!raw) {
+        if (!defaultFileName) {
+            return { ok: false, error: "path is required" };
+        }
+        const defaultPath = resolvePathFromBasePreservingWindowsRoot(root, defaultFileName);
+        if (hasWindowsPathAlias(defaultPath, "filesystem") || !pathStaysWithinRoot(root, defaultPath)) {
+            return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+        }
+        return { ok: true, path: defaultPath };
+    }
+    const resolved = resolvePathFromBasePreservingWindowsRoot(root, raw);
+    if (hasWindowsPathAlias(resolved, "filesystem") || !pathStaysWithinRoot(root, resolved)) {
+        return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+    }
+    return { ok: true, path: resolved };
+}

package/node_modules/@openclaw/fs-safe/dist/path-segment-route.d.ts

@@ -0,0 +1,6 @@
+export type PathSegmentRoute = Readonly<{
+    joined: string;
+    offsets: readonly number[];
+}>;
+export declare function createPathSegmentRoute(segments: readonly string[]): PathSegmentRoute;
+export declare function joinPathSegmentRoute(base: string, route: PathSegmentRoute, offset: number, tail?: string): string;

package/node_modules/@openclaw/fs-safe/dist/path-segment-route.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+export function createPathSegmentRoute(segments) {
+    const offsets = new Array(segments.length + 1);
+    let cursor = 0;
+    for (let index = 0; index < segments.length; index += 1) {
+        offsets[index] = cursor;
+        cursor += segments[index].length;
+        if (index + 1 < segments.length)
+            cursor += path.sep.length;
+    }
+    offsets[segments.length] = cursor;
+    return Object.freeze({ joined: segments.join(path.sep), offsets: Object.freeze(offsets) });
+}
+// Select the immutable suffix by character offset so callers perform at most
+// one path normalization without copying a shrinking segment array.
+export function joinPathSegmentRoute(base, route, offset, tail) {
+    const start = route.offsets[offset];
+    if (start === undefined)
+        throw new RangeError("path segment offset is outside the route");
+    const suffix = route.joined.slice(start);
+    if (suffix)
+        return tail === undefined ? path.join(base, suffix) : path.join(base, suffix, tail);
+    return tail === undefined ? base : path.join(base, tail);
+}

package/node_modules/@openclaw/fs-safe/dist/path-suffix-aliases.d.ts

@@ -0,0 +1,11 @@
+export type ProbePathSuffixAliasesOptions = {
+    directory: string;
+    left: string;
+    right: string;
+    /** Maximum relative component count; defaults to 32. */
+    maxDepth?: number;
+    /** Synchronous caller policy for differing NFC pairs not equivalent under ASCII case folding. */
+    shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+/** Observe bounded missing suffix aliases; the caller owns caching and ambiguity policy. */
+export declare function probePathSuffixAliasesSync(options: ProbePathSuffixAliasesOptions): boolean | undefined;

package/node_modules/@openclaw/fs-safe/dist/path-suffix-aliases.js

@@ -0,0 +1,394 @@
+import { randomInt } from "node:crypto";
+import fs, {} from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const MAX_SUFFIX_LENGTH = 8_192;
+const MAX_PATH_LENGTH = 32_768;
+const MAX_SUFFIX_DEPTH = 32;
+const MAX_MKDIR_ATTEMPTS = 128;
+const MAX_CREATED_DIRECTORIES = 64;
+const MAX_FORWARD_OBSERVATIONS = 4_096;
+const MAX_SCALED_FORWARD_OBSERVATIONS = 32_768;
+const PROBE_NAME_LENGTH = 6;
+const PROBE_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+const PROBE_FIRST_ALPHABET = "bdefghijkmoqrstuvwxyz";
+function unavailable() {
+    throw new Error("path suffix probe resources or cleanup authority are unavailable");
+}
+function assertMutationPath(value) {
+    if (value.length > MAX_PATH_LENGTH)
+        unavailable();
+}
+function suffixSegments(value, maxDepth) {
+    if (typeof value !== "string")
+        throw new TypeError("suffix must be a string");
+    if (value.length > MAX_SUFFIX_LENGTH)
+        throw new RangeError("suffix exceeds 8192 code units");
+    if (value.includes("\0") || path.isAbsolute(value)) {
+        throw new TypeError("suffix must be a relative path without NUL bytes");
+    }
+    const windows = process.platform === "win32";
+    const segments = (windows ? value.replaceAll("/", "\\") : value).split(path.sep);
+    if (segments.length > maxDepth)
+        throw new RangeError(`suffix exceeds ${maxDepth} components`);
+    if (segments.some(segment => !segment || segment === "." || segment === ".." ||
+        (windows && (segment.includes(":") || /^[ .]+$/u.test(segment) ||
+            isWindowsReservedDeviceName(segment))))) {
+        throw new TypeError("suffix must contain ordinary relative path components");
+    }
+    return segments;
+}
+function areAsciiCaseVariants(left, right) {
+    const fold = (value) => value.replace(/[A-Z]/gu, letter => String.fromCharCode(letter.charCodeAt(0) + 0x20));
+    return fold(left) === fold(right);
+}
+function forbiddenNames(leftNfc, rightNfc) {
+    const lower = new Set([leftNfc.toLowerCase(), rightNfc.toLowerCase()]);
+    const upper = new Set([leftNfc.toUpperCase(), rightNfc.toUpperCase()]);
+    // These conservative exclusions never classify filesystem aliases.
+    return candidate => {
+        const normalized = candidate.normalize("NFC");
+        return lower.has(normalized.toLowerCase()) || upper.has(normalized.toUpperCase());
+    };
+}
+function* normalizationProbePairs(left, right, forbidden, availableNameLength) {
+    const seen = new Set();
+    const replaceAscii = (value, replacements) => value.replace(/[A-Za-z]/gu, character => {
+        const lower = character.toLowerCase();
+        const replacement = replacements.get(lower);
+        return replacement ? character === lower ? replacement : replacement.toUpperCase() : character;
+    });
+    const presentAscii = [...new Set(`${left}${right}`.toLowerCase().match(/[a-z]/gu) ?? [])];
+    const mutableAscii = presentAscii.filter(source => {
+        const replacements = new Map([[source, source === "z" ? "y" : "z"]]);
+        return areAsciiCaseVariants(replaceAscii(left, replacements).normalize("NFC"), replaceAscii(right, replacements).normalize("NFC"));
+    });
+    for (let attempt = 0; attempt < 24 && mutableAscii.length > 0; attempt++) {
+        const replacements = new Map(mutableAscii.map(source => [
+            source, String.fromCharCode("a".charCodeAt(0) + randomInt(26)),
+        ]));
+        const first = replaceAscii(left, replacements);
+        const second = replaceAscii(right, replacements);
+        if (first.length > availableNameLength || second.length > availableNameLength ||
+            !areAsciiCaseVariants(first.normalize("NFC"), second.normalize("NFC")) ||
+            isWindowsReservedDeviceName(first) || isWindowsReservedDeviceName(second) ||
+            forbidden(first) || forbidden(second))
+            continue;
+        const key = `${first}\0${second}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            yield [first, second];
+        }
+    }
+}
+function createPrivateProbeName(nameLength) {
+    let name = "";
+    for (let index = 0; index < nameLength; index++) {
+        const alphabet = index === 0 ? PROBE_FIRST_ALPHABET : PROBE_ALPHABET;
+        name += alphabet[randomInt(alphabet.length)];
+    }
+    return name;
+}
+function* asciiCaseProbePairs(nameLength, forbidden) {
+    for (const first of privateProbeNames(nameLength, forbidden)) {
+        yield [first, `${first[0].toUpperCase()}${first.slice(1)}`];
+    }
+}
+function* privateProbeNames(nameLength, forbidden) {
+    let count = 0;
+    for (let attempt = 0; attempt < 96 && count < 24; attempt++) {
+        const name = createPrivateProbeName(nameLength);
+        if (!forbidden(name)) {
+            count++;
+            yield name;
+        }
+    }
+}
+function* prependPair(first, remaining) {
+    yield first;
+    yield* remaining;
+}
+class ProbeDirectories {
+    requestedDirectory;
+    root;
+    created = [];
+    cleanupComplete = true;
+    observations = 0;
+    mkdirAttempts = 0;
+    creations = 0;
+    maxObservations;
+    maxMkdirAttempts;
+    maxCreations;
+    constructor(requestedDirectory, depth) {
+        this.requestedDirectory = requestedDirectory;
+        // The suffix-length limit bounds actual depth, so these products remain safe integers.
+        const scale = Math.max(1, depth / MAX_SUFFIX_DEPTH);
+        this.maxObservations = Math.min(MAX_SCALED_FORWARD_OBSERVATIONS, MAX_FORWARD_OBSERVATIONS * scale * scale);
+        this.maxMkdirAttempts = MAX_MKDIR_ATTEMPTS * scale;
+        this.maxCreations = MAX_CREATED_DIRECTORIES * scale;
+        this.observe(1);
+        const canonical = realpathSync.native(pathForWindowsFilesystem(requestedDirectory));
+        assertMutationPath(canonical);
+        this.observe(2);
+        this.root = { path: canonical, identity: inspectDirectoryIdentitySync(canonical) };
+        this.assert(this.root);
+    }
+    reserveObservations(units) {
+        if (units > this.maxObservations - this.observations)
+            unavailable();
+    }
+    observe(units, cleanup = false) {
+        if (cleanup)
+            return;
+        this.reserveObservations(units);
+        this.observations += units;
+    }
+    assert(directory, cleanup = false) {
+        this.observe(1, cleanup);
+        if (realpathSync.native(pathForWindowsFilesystem(this.requestedDirectory)) !== this.root.path) {
+            throw new FsSafeError("path-mismatch", "probe directory changed");
+        }
+        for (let current = directory; current; current = current.parent) {
+            // Each strict identity helper can perform two observations on Windows.
+            this.observe(2, cleanup);
+            assertDirectoryIdentitySync(current.path, current.identity);
+        }
+    }
+    create(parent, name) {
+        if (this.mkdirAttempts >= this.maxMkdirAttempts || this.creations >= this.maxCreations)
+            unavailable();
+        const probePath = path.join(parent.path, name);
+        assertMutationPath(probePath);
+        this.assert(parent);
+        // Exhaustion must not itself create an entry whose first identity cannot be read.
+        this.reserveObservations(2);
+        this.mkdirAttempts++;
+        try {
+            fs.mkdirSync(probePath);
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "EEXIST"))
+                return undefined;
+            throw error;
+        }
+        this.creations++;
+        this.observe(2);
+        // A failed initial observation can still leave an entry: mkdir returns no descriptor.
+        const created = { path: probePath, identity: inspectDirectoryIdentitySync(probePath), parent };
+        this.created.push(created);
+        this.assert(created);
+        return created;
+    }
+    remove(created, cleanup = false) {
+        try {
+            this.assert(created, cleanup);
+            assertMutationPath(created.path);
+            // Never recurse: unexpected children and replacements must remain.
+            fs.rmdirSync(created.path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    probe(parent, pairs) {
+        for (const [first, alternate] of pairs) {
+            const alternatePath = path.join(parent.path, alternate);
+            assertMutationPath(alternatePath);
+            const created = this.create(parent, first);
+            if (!created)
+                continue;
+            let alias;
+            this.observe(2);
+            try {
+                alias = inspectFileIdentitySync(() => fs.lstatSync(alternatePath, { bigint: true }));
+            }
+            catch (error) {
+                if (!hasNodeErrorCode(error, "ENOENT"))
+                    throw error;
+            }
+            this.assert(created);
+            if (!alias)
+                return { aliases: false, directory: created };
+            if (alias.isDirectory() && !alias.isSymbolicLink() && sameFileIdentityForCleanup(created.identity, alias)) {
+                return { aliases: true, directory: created };
+            }
+            // A different alternate entry is a collision. Lost cleanup authority ends probing.
+            if (!this.remove(created)) {
+                this.cleanupComplete = false;
+                unavailable();
+            }
+            this.created.splice(this.created.indexOf(created), 1);
+        }
+        return undefined;
+    }
+    neutral(parent, nameLength, forbidden) {
+        for (const name of privateProbeNames(nameLength, forbidden)) {
+            const created = this.create(parent, name);
+            if (created)
+                return created;
+        }
+        return undefined;
+    }
+    cleanup() {
+        // Cleanup bypasses the forward budget; creation and depth caps bound its work.
+        for (let index = this.created.length - 1; index >= 0; index--) {
+            if (!this.remove(this.created[index], true))
+                this.cleanupComplete = false;
+        }
+        try {
+            this.assert(this.root, true);
+        }
+        catch {
+            this.cleanupComplete = false;
+        }
+        return this.cleanupComplete;
+    }
+}
+function observeSuffixes(getOwner, leftSegments, rightSegments, shouldProbeCaseVariants) {
+    let maxProbePathLength;
+    let probeParent;
+    for (let index = 0; index < leftSegments.length; index++) {
+        const left = leftSegments[index];
+        const right = rightSegments[index];
+        const normalizedLeft = left.normalize("NFC");
+        const normalizedRight = right.normalize("NFC");
+        const asciiCaseVariants = areAsciiCaseVariants(normalizedLeft, normalizedRight);
+        if (normalizedLeft !== normalizedRight && !asciiCaseVariants &&
+            !shouldProbeCaseVariants(normalizedLeft, normalizedRight))
+            return false;
+        const needsNormalization = left !== normalizedLeft || right !== normalizedRight;
+        if (normalizedLeft === normalizedRight && !needsNormalization && index === leftSegments.length - 1)
+            continue;
+        const owner = getOwner();
+        probeParent ??= owner.root;
+        maxProbePathLength ??= Math.max(path.join(owner.root.path, leftSegments.join(path.sep)).length, path.join(owner.root.path, rightSegments.join(path.sep)).length);
+        const availableNameLength = maxProbePathLength - probeParent.path.length -
+            (probeParent.path.endsWith(path.sep) ? 0 : 1);
+        const nameLength = Math.max(1, Math.min(PROBE_NAME_LENGTH, left.length, right.length));
+        const forbidden = forbiddenNames(normalizedLeft, normalizedRight);
+        let next;
+        if (normalizedLeft !== normalizedRight) {
+            let caseParent = probeParent;
+            let pairs;
+            if (asciiCaseVariants) {
+                pairs = asciiCaseProbePairs(nameLength, forbidden);
+            }
+            else {
+                const neutral = owner.neutral(probeParent, nameLength, forbidden);
+                if (!neutral)
+                    return undefined;
+                caseParent = neutral;
+                pairs = [[left, right]];
+            }
+            const observed = owner.probe(caseParent, pairs);
+            if (!observed)
+                return undefined;
+            if (!observed.aliases)
+                return false;
+            next = observed.directory;
+        }
+        if (needsNormalization) {
+            const generated = normalizationProbePairs(left, right, forbidden, availableNameLength);
+            const first = generated.next();
+            let pairs;
+            let normalizationParent = probeParent;
+            // Fallback only when no generated pair exists, not when generated names collide.
+            if (first.done) {
+                const neutral = owner.neutral(probeParent, nameLength, forbidden);
+                if (!neutral)
+                    return undefined;
+                normalizationParent = neutral;
+                pairs = [[left, right]];
+            }
+            else {
+                pairs = prependPair(first.value, generated);
+            }
+            const observed = owner.probe(normalizationParent, pairs);
+            if (!observed)
+                return undefined;
+            if (!observed.aliases)
+                return false;
+            next ??= observed.directory;
+        }
+        if (index < leftSegments.length - 1) {
+            next ??= owner.neutral(probeParent, nameLength, forbidden);
+            if (!next)
+                return undefined;
+            probeParent = next;
+        }
+    }
+    return true;
+}
+/** Observe bounded missing suffix aliases; the caller owns caching and ambiguity policy. */
+export function probePathSuffixAliasesSync(options) {
+    const requestedDirectory = options.directory;
+    if (typeof requestedDirectory !== "string")
+        throw new TypeError("directory must be a string");
+    if (requestedDirectory.length > MAX_PATH_LENGTH)
+        throw new RangeError("directory exceeds 32768 code units");
+    if (requestedDirectory.includes("\0"))
+        throw new TypeError("directory must be a path without NUL bytes");
+    // Preserve one-argument Windows drive-relative resolution before reentrant option getters.
+    const directory = resolvePathPreservingWindowsRoot(requestedDirectory);
+    if (directory.length > MAX_PATH_LENGTH)
+        throw new RangeError("resolved directory exceeds 32768 code units");
+    const requestedMaxDepth = options.maxDepth;
+    const maxDepth = requestedMaxDepth === undefined ? MAX_SUFFIX_DEPTH : requestedMaxDepth;
+    if (!Number.isSafeInteger(maxDepth) || maxDepth < 0) {
+        throw new RangeError("maxDepth must be a non-negative safe integer");
+    }
+    const leftInput = options.left;
+    const rightInput = options.right;
+    const predicate = options.shouldProbeCaseVariants;
+    const left = suffixSegments(leftInput, maxDepth);
+    const right = suffixSegments(rightInput, maxDepth);
+    if (left.length !== right.length)
+        throw new TypeError("suffixes must have the same component count");
+    if (predicate !== undefined && typeof predicate !== "function") {
+        throw new TypeError("shouldProbeCaseVariants must be a function");
+    }
+    if (leftInput === rightInput)
+        return true;
+    let callbackFailure;
+    const shouldProbe = (first, second) => {
+        if (!predicate)
+            return true;
+        try {
+            const result = predicate(first, second);
+            if (typeof result !== "boolean") {
+                void Promise.resolve(result).catch(() => undefined);
+                throw new TypeError("shouldProbeCaseVariants must return a boolean synchronously");
+            }
+            return result;
+        }
+        catch (error) {
+            callbackFailure = { error };
+            throw error;
+        }
+    };
+    let owner;
+    let observed;
+    let cleaned = true;
+    try {
+        observed = observeSuffixes(() => owner ??= new ProbeDirectories(directory, left.length), left, right, shouldProbe);
+        owner?.assert(owner.root);
+    }
+    catch {
+        observed = undefined;
+        if (callbackFailure)
+            throw callbackFailure.error;
+    }
+    finally {
+        if (owner)
+            cleaned = owner.cleanup();
+    }
+    return cleaned ? observed : undefined;
+}

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

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
+export declare function normalizeWindowsPathForComparison(input: string): string;
+export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
+export declare function hasNodeErrorCode(value: unknown, code: string): boolean;
+export declare function assertNoNulPathInput(filePath: string, message?: string): void;
+export declare function isNotFoundPathError(value: unknown): boolean;
+export declare function isSymlinkOpenError(value: unknown): boolean;
+export declare function isPathInside(root: string, target: string): boolean;
+export declare function isPathRelativeEscape(relativePath: string): boolean;
+export declare function resolveSafeBaseDir(rootDir: string): string;
+export declare function isWithinDir(rootDir: string, targetPath: string): boolean;
+export declare function safeRealpathSync(targetPath: string, cache?: Map<string, string>): string | null;
+export declare function isPathInsideWithRealpath(basePath: string, candidatePath: string, opts?: {
+    requireRealpath?: boolean;
+    cache?: Map<string, string>;
+}): boolean;
+export declare function safeStatSync(targetPath: string): fs.Stats | null;
+export declare function splitSafeRelativePath(relativePath: string): string[];
+export declare function resolveSafeRelativePath(rootDir: string, relativePath: string): string;