@openclaw/openshell-sandbox 2026.9.2 → 2026.9.3

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

@@ -0,0 +1,37 @@
+import { type BigIntStats } from "node:fs";
+import { type AnyAsyncDirectoryGuard, type SyncDirectoryGuard } from "./directory-guard.js";
+export declare function withAsyncDirectoryGuards<T>(guards: readonly AnyAsyncDirectoryGuard[], mutate: () => Promise<T>, options?: {
+    verifyAfter?: boolean;
+    onPostGuardFailure?: (result: T, error: unknown) => Promise<void> | void;
+}): Promise<T>;
+export declare function withSyncDirectoryGuards<T>(guards: readonly SyncDirectoryGuard[], mutate: () => T, options?: {
+    verifyAfter?: boolean;
+}): T;
+export declare function guardedRename(params: {
+    assertBeforeRename?: () => void;
+    onSourceInspected?: (identity: Pick<BigIntStats, "dev" | "ino">) => void;
+    onRenamed?: () => void;
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRenameSync(params: {
+    from: string;
+    to: string;
+    targetRoot?: string;
+    verifyAfter?: boolean;
+}): void;
+export declare function guardedRm(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): Promise<void>;
+export declare function guardedRmSync(params: {
+    target: string;
+    recursive?: boolean;
+    force?: boolean;
+    verifyAfter?: boolean;
+}): void;
+//# sourceMappingURL=guarded-mutation.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/guarded-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAOL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC;IACzE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}

package/node_modules/@openclaw/fs-safe/dist/guarded-mutation.js

@@ -0,0 +1,82 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, createNearestExistingSyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
+export async function withAsyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        await assertAsyncDirectoryGuard(guard);
+    }
+    const result = await mutate();
+    if (options.verifyAfter !== false) {
+        try {
+            for (const guard of guards) {
+                await assertAsyncDirectoryGuard(guard);
+            }
+        }
+        catch (error) {
+            if (options.onPostGuardFailure) {
+                try {
+                    // The mutation may have returned an owned resource before the post-guard
+                    // check detected a swapped directory. Give callers one chance to close
+                    // handles without letting cleanup hide the boundary failure.
+                    await options.onPostGuardFailure(result, error);
+                }
+                catch {
+                    // Preserve the boundary failure. Cleanup is best-effort.
+                }
+            }
+            throw error;
+        }
+    }
+    return result;
+}
+export function withSyncDirectoryGuards(guards, mutate, options = {}) {
+    for (const guard of guards) {
+        assertSyncDirectoryGuard(guard);
+    }
+    const result = mutate();
+    if (options.verifyAfter !== false) {
+        for (const guard of guards) {
+            assertSyncDirectoryGuard(guard);
+        }
+    }
+    return result;
+}
+export async function guardedRename(params) {
+    const sourceGuard = await createAsyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : await createAsyncDirectoryGuard(path.dirname(params.to));
+    await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
+        if (params.onSourceInspected) {
+            params.onSourceInspected(await fs.lstat(params.from, { bigint: true }));
+        }
+        // Authority must survive all awaited guards; do not yield before rename dispatch.
+        params.assertBeforeRename?.();
+        await fs.rename(params.from, params.to);
+        params.onRenamed?.();
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRenameSync(params) {
+    const sourceGuard = createSyncDirectoryGuard(path.dirname(params.from));
+    const targetGuard = params.targetRoot
+        ? createNearestExistingSyncDirectoryGuard(params.targetRoot, path.dirname(params.to))
+        : createSyncDirectoryGuard(path.dirname(params.to));
+    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to), { verifyAfter: params.verifyAfter });
+}
+export async function guardedRm(params) {
+    const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
+    await withAsyncDirectoryGuards([guard], async () => {
+        await fs.rm(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+            ...(params.force !== undefined ? { force: params.force } : {}),
+        });
+    }, { verifyAfter: params.verifyAfter });
+}
+export function guardedRmSync(params) {
+    const guard = createSyncDirectoryGuard(path.dirname(params.target));
+    withSyncDirectoryGuards([guard], () => fsSync.rmSync(params.target, {
+        ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+        ...(params.force !== undefined ? { force: params.force } : {}),
+    }), { verifyAfter: params.verifyAfter });
+}

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

@@ -0,0 +1,12 @@
+export declare function resolveEffectiveHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string | undefined;
+export declare function resolveRequiredHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+export declare function expandHomePrefix(input: string, opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+}): string;
+export declare function resolveHomeRelativePath(input: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+}): string;
+//# sourceMappingURL=home-dir.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/home-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-dir.d.ts","sourceRoot":"","sources":["../src/home-dir.ts"],"names":[],"mappings":"AAeA,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,GAAG,SAAS,CAGpB;AAyCD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAM,MAAmB,GACjC,MAAM,CAER;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB,GACA,MAAM,CAcR"}

package/node_modules/@openclaw/fs-safe/dist/home-dir.js

@@ -0,0 +1,84 @@
+import os from "node:os";
+import path from "node:path";
+import { normalizeOptionalString } from "./string-coerce.js";
+function normalize(value) {
+    const trimmed = normalizeOptionalString(value);
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed === "undefined" || trimmed === "null") {
+        return undefined;
+    }
+    return trimmed;
+}
+export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
+    const raw = resolveRawHomeDir(env, homedir);
+    return raw ? path.resolve(raw) : undefined;
+}
+function resolveRawHomeDir(env, homedir) {
+    const explicitHome = normalize(env.OPENCLAW_HOME);
+    if (!explicitHome) {
+        return resolveRawOsHomeDir(env, homedir);
+    }
+    const segments = path.normalize(explicitHome).split(path.sep);
+    if (segments[0] !== "~") {
+        return explicitHome;
+    }
+    // OPENCLAW_HOME starts with "~"; expand against the os home dir. Fall
+    // back to undefined when there is no os home to expand against rather
+    // than returning a raw "~"-prefixed path the caller cannot use.
+    const fallbackHome = resolveRawOsHomeDir(env, homedir);
+    if (!fallbackHome) {
+        return undefined;
+    }
+    return expandHomePrefix(explicitHome, { home: fallbackHome });
+}
+function resolveRawOsHomeDir(env, homedir) {
+    const envHome = normalize(env.HOME);
+    if (envHome) {
+        return envHome;
+    }
+    const userProfile = normalize(env.USERPROFILE);
+    if (userProfile) {
+        return userProfile;
+    }
+    return normalizeSafe(homedir);
+}
+function normalizeSafe(homedir) {
+    try {
+        return normalize(homedir());
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
+    return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+}
+export function expandHomePrefix(input, opts) {
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return input;
+    }
+    const home = normalize(opts?.home) ??
+        resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+    if (!home) {
+        return input;
+    }
+    return path.join(home, ...segments.slice(1));
+}
+export function resolveHomeRelativePath(input, opts) {
+    if (!input) {
+        return input;
+    }
+    const segments = path.normalize(input).split(path.sep);
+    if (segments[0] !== "~") {
+        return path.resolve(input);
+    }
+    const expanded = expandHomePrefix(input, {
+        home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+        env: opts?.env,
+        homedir: opts?.homedir,
+    });
+    return path.resolve(expanded);
+}

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

@@ -0,0 +1,7 @@
+export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
+export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

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

@@ -0,0 +1,5 @@
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

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

@@ -0,0 +1,20 @@
+export declare function safeDirName(input: string): string;
+export declare function safePathSegmentHashed(input: string): string;
+export declare function resolveSafeInstallDir(params: {
+    baseDir: string;
+    id: string;
+    invalidNameMessage: string;
+    nameEncoder?: (id: string) => string;
+}): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertCanonicalPathWithinBase(params: {
+    baseDir: string;
+    candidatePath: string;
+    boundaryLabel: string;
+}): Promise<void>;
+//# sourceMappingURL=install-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAsB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

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

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInside } from "./path.js";
+export function safeDirName(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
+}
+export function safePathSegmentHashed(input) {
+    const trimmed = input.trim();
+    const base = trimmed
+        .replaceAll(/[\\/]/g, "-")
+        .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-+/g, "")
+        .replaceAll(/-+$/g, "");
+    const normalized = base.length > 0 ? base : "skill";
+    const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
+    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
+    if (safe !== trimmed) {
+        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
+        return `${prefix}-${hash}`;
+    }
+    if (safe.length > 60) {
+        return `${safe.slice(0, 50)}-${hash}`;
+    }
+    return safe;
+}
+export function resolveSafeInstallDir(params) {
+    const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
+    const targetDir = path.join(params.baseDir, encodedName);
+    const resolvedBase = path.resolve(params.baseDir);
+    const resolvedTarget = path.resolve(targetDir);
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    return { ok: true, path: resolvedTarget };
+}
+export async function assertCanonicalPathWithinBase(params) {
+    const baseDir = path.resolve(params.baseDir);
+    const candidatePath = path.resolve(params.candidatePath);
+    if (!isPathInside(baseDir, candidatePath)) {
+        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+    }
+    const baseLstat = await fs.lstat(baseDir);
+    if (baseLstat.isSymbolicLink()) {
+        const baseStat = await fs.stat(baseDir);
+        if (!baseStat.isDirectory()) {
+            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+        }
+    }
+    else if (!baseLstat.isDirectory()) {
+        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+    }
+    const baseRealPath = await fs.realpath(baseDir);
+    const validateDirectory = async (dirPath) => {
+        const resolvedDirPath = path.resolve(dirPath);
+        const dirLstat = await fs.lstat(dirPath);
+        if (dirLstat.isSymbolicLink()) {
+            if (resolvedDirPath !== baseDir) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+            const dirStat = await fs.stat(dirPath);
+            if (!dirStat.isDirectory()) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+        }
+        else if (!dirLstat.isDirectory()) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+        const dirRealPath = await fs.realpath(dirPath);
+        if (!isPathInside(baseRealPath, dirRealPath)) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+    };
+    try {
+        await validateDirectory(candidatePath);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            throw err;
+        }
+    }
+    await validateDirectory(path.dirname(candidatePath));
+}

package/node_modules/@openclaw/fs-safe/dist/json-document-store.d.ts

@@ -0,0 +1,35 @@
+import type { FileLockRetryOptions } from "./file-lock.js";
+import type { Root } from "./root.js";
+import type { SidecarLockStaleRecovery } from "./sidecar-lock.js";
+export type JsonStoreLockOptions = {
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: FileLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
+    managerKey?: string;
+};
+export type JsonFileStoreOptions = {
+    trailingNewline?: boolean;
+    lock?: boolean | JsonStoreLockOptions;
+};
+export type JsonStore<T> = {
+    readonly filePath: string;
+    read(): Promise<T | undefined>;
+    readOr(fallback: T): Promise<T>;
+    readRequired(): Promise<T>;
+    write(value: T): Promise<void>;
+    update(run: (current: T | undefined) => T | Promise<T>): Promise<T>;
+    updateOr(fallback: T, run: (current: T) => T | Promise<T>): Promise<T>;
+};
+export type JsonStoreAdapter<T> = {
+    filePath: string;
+    /** Internal admission before lock I/O, within the serialized mutation. */
+    prepareLock?: () => Promise<Root>;
+    readIfExists(): Promise<T | undefined>;
+    readRequired(): Promise<T>;
+    write(value: T, options?: {
+        trailingNewline?: boolean;
+    }): Promise<void>;
+};
+export declare function createJsonStore<T>(adapter: JsonStoreAdapter<T>, options?: JsonFileStoreOptions): JsonStore<T>;
+//# sourceMappingURL=json-document-store.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-document-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AASlE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CAmFd"}

package/node_modules/@openclaw/fs-safe/dist/json-document-store.js

@@ -0,0 +1,97 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
+import { getFsSafeLockConfig } from "./lock-config.js";
+import { createSidecarLockManager } from "./sidecar-lock.js";
+import { serializePathWrite } from "./write-queue.js";
+const activeStoreMutations = new AsyncLocalStorage();
+function cloneFallback(value) {
+    if (value && typeof value === "object") {
+        return structuredClone(value);
+    }
+    return value;
+}
+function resolveLockOptions(filePath, options) {
+    if (!options.lock) {
+        return null;
+    }
+    const lockOptions = options.lock === true ? {} : options.lock;
+    const defaults = getFsSafeLockConfig();
+    return {
+        managerKey: lockOptions.managerKey ?? `fs-safe.json-store:${filePath}`,
+        retry: lockOptions.retry ?? defaults.retry ?? {},
+        staleMs: lockOptions.staleMs ?? defaults.staleMs ?? 30_000,
+        staleRecovery: lockOptions.staleRecovery ?? defaults.staleRecovery,
+        timeoutMs: lockOptions.timeoutMs ?? defaults.timeoutMs ?? 30_000,
+    };
+}
+export function createJsonStore(adapter, options = {}) {
+    const lockOptions = resolveLockOptions(adapter.filePath, options);
+    const locks = lockOptions ? createSidecarLockManager(lockOptions.managerKey) : null;
+    async function read() {
+        return await adapter.readIfExists();
+    }
+    async function readOr(fallback) {
+        const current = await read();
+        return current === undefined ? cloneFallback(fallback) : current;
+    }
+    async function write(value) {
+        await adapter.write(value, {
+            trailingNewline: options.trailingNewline ?? true,
+        });
+    }
+    async function withSerializedMutation(run) {
+        const canonicalPath = await canonicalPathFromExistingAncestor(adapter.filePath);
+        const activePaths = activeStoreMutations.getStore();
+        if (activePaths?.get(canonicalPath)?.active) {
+            throw new FsSafeError("store-reentrant-update", `jsonStore cannot write or update ${canonicalPath} from inside its active update callback; return the complete next value from the outer update instead`);
+        }
+        return await serializePathWrite(`json-store:${canonicalPath}`, async () => {
+            const mutationPaths = new Map([...(activePaths ?? [])].filter(([, token]) => token.active));
+            const token = { active: true };
+            mutationPaths.set(canonicalPath, token);
+            return await activeStoreMutations.run(mutationPaths, async () => {
+                try {
+                    if (!locks || !lockOptions) {
+                        return await run();
+                    }
+                    const lockRoot = adapter.prepareLock ? await adapter.prepareLock() : undefined;
+                    return await locks.withLock({
+                        ...(lockRoot ? { lockRoot } : {}),
+                        targetPath: adapter.filePath,
+                        staleMs: lockOptions.staleMs,
+                        timeoutMs: lockOptions.timeoutMs,
+                        retry: lockOptions.retry,
+                        staleRecovery: lockOptions.staleRecovery,
+                        payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+                    }, run);
+                }
+                finally {
+                    token.active = false;
+                }
+            });
+        });
+    }
+    return {
+        filePath: adapter.filePath,
+        read,
+        readOr,
+        readRequired: adapter.readRequired,
+        write: async (value) => {
+            await withSerializedMutation(async () => {
+                await write(value);
+            });
+        },
+        update: async (run) => await withSerializedMutation(async () => {
+            const next = await run(await read());
+            await write(next);
+            return next;
+        }),
+        updateOr: async (fallback, run) => await withSerializedMutation(async () => {
+            const current = await read();
+            const next = await run(current === undefined ? cloneFallback(fallback) : current);
+            await write(next);
+            return next;
+        }),
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-directory.d.ts

@@ -0,0 +1,2 @@
+export declare function syncQueueDirectoryCreation(dir: string, validationBase: string): Promise<void>;
+//# sourceMappingURL=json-durable-queue-directory.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-directory.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-directory.ts"],"names":[],"mappings":"AAKA,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-directory.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { isPathRelativeEscape } from "./path.js";
+export async function syncQueueDirectoryCreation(dir, validationBase) {
+    const baseReal = await fs.realpath(validationBase);
+    const targetReal = await fs.realpath(dir);
+    const relative = path.relative(baseReal, targetReal);
+    if (isPathRelativeEscape(relative)) {
+        throw new Error(`durable queue directory escapes validation base: ${dir}`);
+    }
+    const directories = [baseReal];
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        directories.push(path.join(directories.at(-1), segment));
+    }
+    await syncDirectory(targetReal, { label: "durable queue directory" });
+    for (const parent of directories.slice(0, -1).toReversed()) {
+        await syncDirectory(parent, { label: "durable queue parent" });
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.d.ts

@@ -0,0 +1,17 @@
+export type DurableQueueEntryPathsLike = {
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath?: string;
+};
+export declare function durableQueueProcessingPath(paths: DurableQueueEntryPathsLike): string;
+export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike, options?: {
+    skipUnowned?: boolean;
+}): Promise<string | null>;
+export declare function completeDeliveredQueueEntry(paths: DurableQueueEntryPathsLike): Promise<boolean>;
+export declare function acknowledgeDurableQueueEntry(paths: DurableQueueEntryPathsLike): Promise<void>;
+export declare function moveDurableQueueEntryToFailed(params: {
+    paths: DurableQueueEntryPathsLike;
+    failedPath: string;
+}): Promise<void>;
+export declare function getErrorCode(error: unknown): string | null;
+//# sourceMappingURL=json-durable-queue-ownership.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAKpF;AA+DD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAalB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}