@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/local-roots.js

@@ -0,0 +1,160 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { expandHomePrefix, resolveRequiredHomeDir } from "./home-dir.js";
+import { isFileUrl, safeFileURLToPath } from "./local-file-access.js";
+import { realpathSync } from "./realpath.js";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPathSync } from "./root-path.js";
+import { root } from "./root.js";
+import { assertNoWindowsPathAlias, isWindowsPathAliasError, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function resolveLocalPathInput(input, label) {
+    if (isFileUrl(input)) {
+        try {
+            return safeFileURLToPath(input);
+        }
+        catch {
+            const location = label === "file path" ? "" : ` in ${label}`;
+            throw new Error(`Invalid file:// URL${location}: ${input}`);
+        }
+    }
+    if (input.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} must not contain NUL bytes`);
+    }
+    assertNoWindowsPathAlias(input, "filesystem", `${label} uses a Windows filesystem namespace alias`);
+    const homePrefix = input === "~" || input.startsWith("~/") ||
+        (path.sep === "\\" && input.startsWith("~\\"));
+    const expanded = homePrefix ? `${resolveRequiredHomeDir()}${path.sep}${input.slice(2)}` : input;
+    assertNoWindowsPathAlias(expanded, "filesystem", `${label} uses a Windows filesystem namespace alias`);
+    if (path.isAbsolute(expanded))
+        return expanded;
+    const drive = path.parse(expanded).root;
+    const base = drive ? path.resolve(drive) : process.cwd();
+    const resolved = `${base}${path.sep}${expanded.slice(drive.length)}`;
+    assertNoWindowsPathAlias(resolved, "filesystem", `${label} uses a Windows filesystem namespace alias`);
+    return resolved;
+}
+function resolveLocalRootInput(input, label) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new FsSafeError("invalid-path", `${label} entry is required`);
+    }
+    const resolved = isFileUrl(trimmed)
+        ? resolveLocalPathInput(trimmed, label)
+        : expandHomePrefix(trimmed);
+    if (resolved.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} entry must not contain NUL bytes`);
+    }
+    assertNoWindowsPathAlias(resolved, "filesystem", `${label} entry uses a Windows filesystem namespace alias`);
+    if (!path.isAbsolute(resolved)) {
+        throw new FsSafeError("invalid-path", `${label} entries must be absolute paths: ${input}`);
+    }
+    const absolute = resolvePathPreservingWindowsRoot(resolved);
+    assertNoWindowsPathAlias(absolute, "filesystem", `${label} entry uses a Windows filesystem namespace alias`);
+    return absolute;
+}
+function resolveRootRealSync(rootDir) {
+    let realPath;
+    try {
+        // Configured roots may themselves be symlinks. Follow only this trusted
+        // root entry, then use its canonical directory for containment checks.
+        const operationPath = pathForWindowsFilesystem(rootDir);
+        const stat = fsSync.statSync(operationPath);
+        if (!stat.isDirectory()) {
+            return null;
+        }
+        realPath = realpathSync(operationPath);
+    }
+    catch {
+        return null;
+    }
+    assertNoWindowsPathAlias(realPath, "filesystem", "local root uses a Windows filesystem namespace alias");
+    return realPath;
+}
+function prepareLocalRootsInput(options) {
+    const label = options.label ?? "local roots";
+    const rootDirs = options.roots.map((rootEntry) => resolveLocalRootInput(rootEntry, label));
+    let requestedPath;
+    try {
+        requestedPath = resolveLocalPathInput(options.filePath, "file path");
+    }
+    catch (error) {
+        if (isWindowsPathAliasError(error))
+            return null;
+        throw error;
+    }
+    return { label, rootDirs, requestedPath };
+}
+export function resolveLocalPathFromRootsSync(options) {
+    const input = prepareLocalRootsInput(options);
+    if (!input)
+        return null;
+    const { label, rootDirs, requestedPath } = input;
+    for (const rootDir of rootDirs) {
+        const rootReal = resolveRootRealSync(rootDir);
+        if (!rootReal) {
+            continue;
+        }
+        let candidate;
+        try {
+            candidate = resolveRootPathSync({
+                absolutePath: requestedPath,
+                rootPath: rootDir,
+                rootCanonicalPath: rootReal,
+                boundaryLabel: label,
+                rejectUnresolvedSymlinks: true,
+                policy: options.requireFile ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            });
+        }
+        catch {
+            continue;
+        }
+        if (!candidate.exists && options.allowMissing !== true) {
+            continue;
+        }
+        if (candidate.exists && options.requireFile === true && candidate.kind !== "file")
+            continue;
+        if (candidate.exists && options.requireFile === true) {
+            try {
+                if (!fsSync.lstatSync(pathForWindowsFilesystem(requestedPath)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        return { path: candidate.canonicalPath, root: rootReal };
+    }
+    return null;
+}
+export async function readLocalFileFromRoots(options) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const input = prepareLocalRootsInput(options);
+    if (!input || input.rootDirs.length === 0)
+        return null;
+    const { rootDirs, requestedPath } = input;
+    const readOptions = {
+        hardlinks: options.hardlinks,
+        symlinks: options.symlinks,
+    };
+    // Omission keeps Root's default cap; one policy snapshot serves every root.
+    if (maxBytes !== undefined)
+        readOptions.maxBytes = maxBytes;
+    for (const rootDir of rootDirs) {
+        let scopedRoot;
+        try {
+            scopedRoot = await root(rootDir);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const result = await scopedRoot.readAbsolute(requestedPath, readOptions);
+            return { ...result, root: scopedRoot.rootReal };
+        }
+        catch {
+            // Root handles both trusted spellings; try the next configured root.
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,9 @@
+import type { SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export type FsSafeLockConfig = {
+    staleRecovery: SidecarLockStaleRecovery;
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+};
+export declare function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+export declare function getFsSafeLockConfig(): FsSafeLockConfig;

package/node_modules/@openclaw/fs-safe/dist/lock-config.js

@@ -0,0 +1,12 @@
+const DEFAULT_LOCK_CONFIG = {
+    staleRecovery: "fail-closed",
+};
+let lockConfig = { ...DEFAULT_LOCK_CONFIG };
+export function configureFsSafeLocks(config) {
+    // Process defaults only fill lock options after a caller explicitly enables
+    // locking for a resource; this must never turn sidecar locks on globally.
+    lockConfig = { ...lockConfig, ...config };
+}
+export function getFsSafeLockConfig() {
+    return { ...lockConfig, retry: lockConfig.retry ? { ...lockConfig.retry } : undefined };
+}

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

@@ -0,0 +1,30 @@
+import fsSync from "node:fs";
+export type EntryIdentity = Readonly<Pick<fsSync.BigIntStats, "ctimeNs" | "dev" | "ino" | "mode" | "mtimeNs" | "nlink" | "size">>;
+export type CopiedEntryManifest = (EntryIdentity & {
+    children: Array<{
+        name: string;
+        manifest: CopiedEntryManifest;
+    }>;
+    directoryIdentity: Readonly<Pick<fsSync.BigIntStats, "dev" | "ino">>;
+    kind: "directory";
+}) | (EntryIdentity & {
+    kind: "leaf";
+});
+type CleanupCopiedEntryResult = "removed" | "stale";
+type CleanupAliasGroup = {
+    expected: EntryIdentity;
+    remainingPaths: Set<string>;
+    stale: boolean;
+};
+export type CleanupCopiedEntryState = {
+    aliasGroups: Map<string, CleanupAliasGroup>;
+};
+export declare function entryIdentity(stat: EntryIdentity): EntryIdentity;
+export declare function sameIdentity(a: EntryIdentity, b: EntryIdentity): boolean;
+export declare function sourceChangedError(sourcePath: string): Error;
+export declare function inspectSourceEntry(sourcePath: string, observe: () => fsSync.BigIntStats): fsSync.BigIntStats;
+export declare function inspectSourceDirectory(sourcePath: string, expected?: Pick<fsSync.BigIntStats, "dev" | "ino">): fsSync.BigIntStats;
+export declare function assertSourceStillMatches(sourcePath: string, identity: EntryIdentity): Promise<void>;
+export declare function createCleanupCopiedEntryState(sourcePath: string, manifest: CopiedEntryManifest): CleanupCopiedEntryState;
+export declare function cleanupCopiedEntry(sourcePath: string, manifest: CopiedEntryManifest, state: CleanupCopiedEntryState, assertBeforeMutation: (() => void) | undefined): Promise<CleanupCopiedEntryResult>;
+export {};

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

@@ -0,0 +1,224 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export function entryIdentity(stat) {
+    return {
+        ctimeNs: stat.ctimeNs,
+        dev: stat.dev,
+        ino: stat.ino,
+        mode: stat.mode,
+        mtimeNs: stat.mtimeNs,
+        nlink: stat.nlink,
+        size: stat.size,
+    };
+}
+export function sameIdentity(a, b) {
+    return (a.dev === b.dev &&
+        a.ino === b.ino &&
+        a.mode === b.mode &&
+        a.nlink === b.nlink &&
+        a.size === b.size &&
+        a.mtimeNs === b.mtimeNs &&
+        a.ctimeNs === b.ctimeNs);
+}
+export function sourceChangedError(sourcePath) {
+    return Object.assign(new Error(`Source changed during move fallback: ${sourcePath}`), {
+        code: "ESTALE",
+    });
+}
+export function inspectSourceEntry(sourcePath, observe) {
+    return inspectFileIdentitySync(observe, undefined, process.platform, () => sourceChangedError(sourcePath));
+}
+export function inspectSourceDirectory(sourcePath, expected) {
+    try {
+        return inspectDirectoryIdentitySync(sourcePath, expected);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR" ||
+            (error instanceof FsSafeError && (error.code === "path-mismatch" || error.code === "not-file"))) {
+            throw sourceChangedError(sourcePath);
+        }
+        throw error;
+    }
+}
+export async function assertSourceStillMatches(sourcePath, identity) {
+    if (!sameIdentity(identity, inspectSourceEntry(sourcePath, () => fsSync.lstatSync(sourcePath, { bigint: true })))) {
+        throw sourceChangedError(sourcePath);
+    }
+}
+function identityKey(identity) {
+    return `${identity.dev}:${identity.ino}`;
+}
+function collectAliasCandidates(sourcePath, manifest, candidates) {
+    if (manifest.kind === "directory") {
+        for (const child of manifest.children) {
+            collectAliasCandidates(path.join(sourcePath, child.name), child.manifest, candidates);
+        }
+        return;
+    }
+    if (manifest.nlink <= 1n) {
+        return;
+    }
+    const key = identityKey(manifest);
+    const entries = candidates.get(key) ?? [];
+    entries.push({ manifest, path: sourcePath });
+    candidates.set(key, entries);
+}
+export function createCleanupCopiedEntryState(sourcePath, manifest) {
+    const candidates = new Map();
+    collectAliasCandidates(sourcePath, manifest, candidates);
+    const aliasGroups = new Map();
+    for (const [key, entries] of candidates) {
+        if (entries.length < 2) {
+            continue;
+        }
+        const first = entries[0];
+        if (!first || entries.some((entry) => !sameIdentity(first.manifest, entry.manifest))) {
+            throw sourceChangedError(sourcePath);
+        }
+        aliasGroups.set(key, {
+            expected: first.manifest,
+            remainingPaths: new Set(entries.map((entry) => entry.path)),
+            stale: false,
+        });
+    }
+    return { aliasGroups };
+}
+function sameOwnedUnlinkTransition(before, after) {
+    return (before.dev === after.dev &&
+        before.ino === after.ino &&
+        before.mode === after.mode &&
+        before.size === after.size &&
+        before.mtimeNs === after.mtimeNs &&
+        before.nlink > 0n &&
+        after.nlink === before.nlink - 1n &&
+        after.ctimeNs >= before.ctimeNs);
+}
+function poisonAliasGroup(group) {
+    group.stale = true;
+    return "stale";
+}
+function inspectCleanupLeaf(sourcePath, expected) {
+    let mismatch;
+    try {
+        return inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), expected, process.platform, () => mismatch = sourceChangedError(sourcePath));
+    }
+    catch (error) {
+        if (mismatch !== undefined && error === mismatch)
+            return undefined;
+        throw error;
+    }
+}
+async function observeOwnedAliasUnlink(sourcePath, group) {
+    group.remainingPaths.delete(sourcePath);
+    const remainingPath = group.remainingPaths.values().next().value;
+    if (!remainingPath) {
+        return "removed";
+    }
+    let observed;
+    try {
+        observed = inspectCleanupLeaf(remainingPath, group.expected);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            return poisonAliasGroup(group);
+        }
+        throw error;
+    }
+    if (!observed || !sameOwnedUnlinkTransition(group.expected, observed)) {
+        return poisonAliasGroup(group);
+    }
+    group.expected = entryIdentity(observed);
+    return "removed";
+}
+function mergeCleanupResults(a, b) {
+    return a === "stale" || b === "stale" ? "stale" : "removed";
+}
+export async function cleanupCopiedEntry(sourcePath, manifest, state, assertBeforeMutation) {
+    if (manifest.kind === "directory") {
+        let currentStat;
+        try {
+            currentStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), manifest.directoryIdentity);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return "removed";
+            if (error instanceof FsSafeError && error.code === "path-mismatch")
+                return "stale";
+            throw error;
+        }
+        if (!currentStat.isDirectory()) {
+            return "stale";
+        }
+        // A same-inode directory can gain unrelated children after commit. Still
+        // clean manifest children so the fallback does not duplicate copied files.
+        let result = "removed";
+        const assertBeforeChildMutation = assertBeforeMutation ? () => {
+            assertBeforeMutation();
+            inspectSourceDirectory(sourcePath, manifest.directoryIdentity);
+        } : undefined;
+        for (const child of manifest.children) {
+            result = mergeCleanupResults(result, await cleanupCopiedEntry(path.join(sourcePath, child.name), child.manifest, state, assertBeforeChildMutation));
+        }
+        // Child cleanup and the caller's authority check can replace the directory.
+        // Keep the final exact observation after both, immediately before removal.
+        assertBeforeMutation?.();
+        try {
+            currentStat = inspectFileIdentitySync(() => fsSync.lstatSync(sourcePath, { bigint: true }), manifest.directoryIdentity);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                return "stale";
+            }
+            if (error instanceof FsSafeError && error.code === "path-mismatch")
+                return "stale";
+            throw error;
+        }
+        if (!currentStat.isDirectory()) {
+            return "stale";
+        }
+        try {
+            await fs.rmdir(sourcePath);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOTEMPTY" || code === "EEXIST") {
+                return "stale";
+            }
+            throw error;
+        }
+        return result;
+    }
+    const aliasGroup = state.aliasGroups.get(identityKey(manifest));
+    if (aliasGroup?.stale) {
+        return "stale";
+    }
+    const expected = aliasGroup?.expected ?? manifest;
+    let currentStat;
+    try {
+        currentStat = inspectCleanupLeaf(sourcePath, expected);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            return aliasGroup ? poisonAliasGroup(aliasGroup) : "removed";
+        }
+        throw error;
+    }
+    for (let observation = 0;; observation++) {
+        if (!currentStat || !sameIdentity(expected, currentStat)) {
+            return aliasGroup ? poisonAliasGroup(aliasGroup) : "stale";
+        }
+        if (observation || !assertBeforeMutation)
+            break;
+        assertBeforeMutation();
+        currentStat = inspectCleanupLeaf(sourcePath, expected);
+    }
+    await fs.unlink(sourcePath);
+    return aliasGroup
+        ? await observeOwnedAliasUnlink(sourcePath, aliasGroup)
+        : "removed";
+}

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

@@ -0,0 +1,7 @@
+import { type BigIntStats } from "node:fs";
+export declare function createMoveStageOwner(staged: string): Promise<{
+    record(created: BigIntStats): void;
+    assertCurrent: () => void;
+    published(): void;
+    cleanup(): Promise<void>;
+}>;

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

@@ -0,0 +1,56 @@
+import fsSync, {} from "node:fs";
+import path from "node:path";
+import { createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { guardedRm, guardedRmSync } from "./guarded-mutation.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { realpathSync } from "./realpath.js";
+export async function createMoveStageOwner(staged) {
+    const parent = await createAsyncDirectoryGuard(path.dirname(staged), { bigint: true });
+    let identity;
+    let unregister;
+    const changed = () => new FsSafeError("path-mismatch", "move staging path changed before publication");
+    const assertParent = () => {
+        const current = fsSync.lstatSync(parent.dir, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink() ||
+            !sameFileIdentityForCleanup(current, parent.stat) ||
+            realpathSync.native(parent.dir) !== parent.realPath)
+            throw changed();
+    };
+    const assertCurrent = () => {
+        assertParent();
+        if (!identity || !sameFileIdentityForCleanup(fsSync.lstatSync(staged, { bigint: true }), identity)) {
+            throw changed();
+        }
+    };
+    return {
+        record(created) {
+            if (!sameFileIdentityForCleanup(created, created))
+                throw changed();
+            identity = created;
+            unregister = registerTempPathForExit(staged, {
+                identity,
+                cleanupSync: () => {
+                    guardedRmSync({ target: staged, recursive: created.isDirectory(), assertBeforeMutation: assertCurrent });
+                },
+            });
+        },
+        assertCurrent,
+        published() { unregister?.(); },
+        async cleanup() {
+            if (!identity)
+                return;
+            try {
+                await guardedRm({ target: staged, recursive: identity.isDirectory(), assertBeforeMutation: assertCurrent });
+                unregister?.();
+            }
+            catch (error) {
+                if (error.code === "ENOENT" || error instanceof FsSafeError) {
+                    unregister?.();
+                }
+                // Retry only the original receipt after transient cleanup I/O failures.
+            }
+        },
+    };
+}

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

@@ -0,0 +1,20 @@
+export type MovePathPublicationReceipt = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export type MovePathWithCopyFallbackOptions = {
+    /** Rechecks authority before each rename and copied-source unlink/rmdir dispatch. */
+    assertBeforeMutation?: () => void;
+    /** Rechecks caller authority synchronously immediately before each rename dispatch. */
+    assertBeforeRename?: () => void;
+    /** Reports the committed destination before post-rename checks or source cleanup. */
+    onDestinationPublished?: (receipt: MovePathPublicationReceipt) => void;
+    from: string;
+    sourceHardlinks?: "allow" | "reject";
+    to: string;
+};
+type MoveCopyFallbackReason = "cross-device" | "windows-rename-denied";
+export declare function moveCopyFallbackReasonForRenameError(error: unknown, platform?: NodeJS.Platform): MoveCopyFallbackReason | undefined;
+export declare function movePathWithCopyFallback(options: MovePathWithCopyFallbackOptions): Promise<void>;
+export {};