@openclaw/signal 2026.9.5 → 2026.9.6

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

@@ -0,0 +1,8 @@
+import { type JsonFileStoreOptions, type JsonStore, type JsonStoreLockOptions } from "./json-document-store.js";
+export type JsonStoreOptions<T> = JsonFileStoreOptions & {
+    filePath: string;
+    dirMode?: number;
+    mode?: number;
+};
+export type { JsonFileStoreOptions, JsonStore, JsonStoreLockOptions };
+export declare function jsonStore<T>(options: JsonStoreOptions<T>): JsonStore<T>;

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

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { fileStore } from "./file-store.js";
+import {} from "./json-document-store.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export function jsonStore(options) {
+    const filePathInput = admitStandalonePublicationPath(options.filePath);
+    const filePath = path.resolve(filePathInput);
+    assertNoWindowsPathAlias(filePath);
+    return fileStore({
+        rootDir: path.dirname(filePath),
+        private: true,
+        mode: options.mode,
+        dirMode: options.dirMode,
+    }).json(path.basename(filePath), options);
+}

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

@@ -0,0 +1 @@
+export declare function stringifyJsonDocument(value: unknown, replacer?: Parameters<typeof JSON.stringify>[1], space?: Parameters<typeof JSON.stringify>[2]): string;

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

@@ -0,0 +1,7 @@
+export function stringifyJsonDocument(value, replacer, space) {
+    const text = JSON.stringify(value, replacer, space);
+    if (typeof text !== "string") {
+        throw new TypeError("value is not representable as a JSON document");
+    }
+    return text;
+}

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

@@ -0,0 +1,49 @@
+import fsSync from "node:fs";
+import { type RootFileOpenFailure } from "./root-file.js";
+import { type WriteTextAtomicOptions } from "./text-atomic.js";
+export type ReadJsonOptions = {
+    maxBytes?: number;
+};
+export declare function tryReadJsonSync<T = unknown>(pathname: string, options?: ReadJsonOptions): T | null;
+export declare function writeJsonSync(pathname: string, data: unknown): void;
+export declare class JsonFileReadError extends Error {
+    readonly filePath: string;
+    readonly reason: "read" | "parse";
+    constructor(filePath: string, reason: "read" | "parse", cause: unknown);
+}
+export type RootStructuredFileReadResult<T> = {
+    ok: true;
+    value: T;
+    stat: fsSync.Stats;
+    path: string;
+    rootRealPath: string;
+} | {
+    ok: false;
+    reason: "open";
+    failure: RootFileOpenFailure;
+} | {
+    ok: false;
+    reason: "invalid" | "parse";
+    error: string;
+};
+export type ReadRootStructuredFileSyncOptions<T> = {
+    rootDir: string;
+    rootRealPath?: string;
+    relativePath: string;
+    boundaryLabel: string;
+    rejectHardlinks?: boolean;
+    maxBytes?: number;
+    parse: (raw: string) => unknown;
+    validate?: (value: unknown) => value is T;
+    invalidMessage?: string | ((relativePath: string) => string);
+};
+export type ReadRootJsonSyncOptions = Omit<ReadRootStructuredFileSyncOptions<unknown>, "parse" | "validate" | "invalidMessage">;
+export declare function readRootStructuredFileSync<T>(options: ReadRootStructuredFileSyncOptions<T>): RootStructuredFileReadResult<T>;
+export declare function readRootJsonSync<T = unknown>(options: ReadRootJsonSyncOptions): RootStructuredFileReadResult<T>;
+export declare function readRootJsonObjectSync(options: ReadRootJsonSyncOptions): RootStructuredFileReadResult<Record<string, unknown>>;
+export declare function tryReadJson<T>(filePath: string, options?: ReadJsonOptions): Promise<T | null>;
+export declare function readJson<T>(filePath: string, options?: ReadJsonOptions): Promise<T>;
+export declare function readJsonIfExists<T>(filePath: string, options?: ReadJsonOptions): Promise<T | null>;
+export declare function readJsonSync<T = unknown>(filePath: string, options?: ReadJsonOptions): T;
+export type WriteJsonOptions = Pick<WriteTextAtomicOptions, "dirMode" | "durable" | "mode" | "trailingNewline">;
+export declare function writeJson(filePath: string, value: unknown, options?: WriteJsonOptions): Promise<void>;

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

@@ -0,0 +1,323 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import path from "node:path";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { FsSafeError } from "./errors.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
+import { readRegularFile, readRegularFileSync, statRegularFile } from "./regular-file.js";
+import { openRootFileSync } from "./root-file.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { writeTextAtomic } from "./text-atomic.js";
+import { sleep } from "./timing.js";
+const READ_RETRY_MAX_ATTEMPTS = 5;
+const READ_RETRY_BASE_DELAY_MS = 50;
+function isRetryableReadError(err) {
+    if (err instanceof FsSafeError && err.code === "path-mismatch") {
+        return true;
+    }
+    const code = getErrorCode(err);
+    return code === "ENOENT" || code === "EPERM";
+}
+async function readRegularFileWithRetry(filePath, maxBytes) {
+    let lastErr;
+    for (let attempt = 0; attempt < READ_RETRY_MAX_ATTEMPTS; attempt++) {
+        try {
+            return (await readRegularFile({ filePath, maxBytes })).buffer;
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryableReadError(err) || attempt === READ_RETRY_MAX_ATTEMPTS - 1) {
+                throw err;
+            }
+            await sleep(READ_RETRY_BASE_DELAY_MS * Math.pow(2, attempt));
+        }
+    }
+    throw lastErr;
+}
+async function readRegularFileIfExistsWithRetry(filePath, options = {}) {
+    const initial = await statRegularFile(filePath);
+    if (initial.missing) {
+        return null;
+    }
+    return await readRegularFileWithRetry(filePath, options.maxBytes);
+}
+const JSON_FILE_MODE = 0o600;
+const JSON_DIR_MODE = 0o700;
+function getErrorCode(err) {
+    return err instanceof Error ? err.code : undefined;
+}
+function trySetSecureMode(fd) {
+    try {
+        fsSync.fchmodSync(fd, JSON_FILE_MODE);
+    }
+    catch {
+        // Best-effort mode application stays on the retained staging descriptor.
+    }
+}
+function trySyncDirectory(pathname) {
+    let fd;
+    try {
+        fd = fsSync.openSync(path.dirname(pathname), "r");
+        fsSync.fsyncSync(fd);
+    }
+    catch {
+        // best-effort; some platforms/filesystems do not support syncing directories.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function renameJsonFileWithFallback(owner, pathname) {
+    owner.assertCurrent(fsSync);
+    try {
+        fsSync.renameSync(owner.pathname, pathname);
+        return;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EPERM" || code === "EEXIST") {
+            owner.assertCurrent(fsSync);
+            fsSync.rmSync(pathname, { force: true });
+            owner.assertCurrent(fsSync);
+            fsSync.renameSync(owner.pathname, pathname);
+            return;
+        }
+        throw error;
+    }
+}
+export function tryReadJsonSync(pathname, options = {}) {
+    try {
+        const raw = readRegularFileSync({
+            filePath: pathname,
+            maxBytes: options.maxBytes,
+        }).buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJsonSync(pathname, data) {
+    const filePath = admitStandalonePublicationPath(pathname);
+    // Keep literal parent segments so staging follows the same symlinks as the target.
+    const tmpPath = path.format({ ...path.parse(filePath), base: `.fs-safe-${randomUUID()}.tmp` });
+    const payload = `${stringifyJsonDocument(data, null, 2)}\n`;
+    fsSync.mkdirSync(recursiveMkdirPath(path.dirname(filePath)), { recursive: true, mode: JSON_DIR_MODE });
+    const owner = new SyncAtomicTempOwner(tmpPath);
+    let originalFailure;
+    try {
+        owner.start();
+        const temp = writeTempFileSync({
+            fsModule: fsSync, tempPath: tmpPath, content: payload, mode: JSON_FILE_MODE,
+            sync: false, onIdentity: owner.onIdentity,
+        });
+        owner.adopt(temp);
+        owner.assertCurrent(fsSync);
+        trySetSecureMode(temp.fd);
+        fsSync.fsyncSync(temp.fd);
+        renameJsonFileWithFallback(owner, filePath);
+        owner.markRenamed();
+        owner.assertPublished(fsSync, filePath);
+        trySetSecureMode(temp.fd);
+        trySyncDirectory(filePath);
+        owner.assertPublished(fsSync, filePath);
+    }
+    catch (error) {
+        originalFailure = { error };
+        throw error;
+    }
+    finally {
+        owner.finish({ fsModule: fsSync, originalFailure, throwOnCleanupError: false });
+    }
+}
+export class JsonFileReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, cause) {
+        super(`Failed to ${reason} JSON file: ${filePath}`, { cause });
+        this.name = "JsonFileReadError";
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveInvalidMessage(invalidMessage, relativePath) {
+    if (typeof invalidMessage === "function") {
+        return invalidMessage(relativePath);
+    }
+    return invalidMessage ?? `${relativePath} has an unexpected shape`;
+}
+export function readRootStructuredFileSync(options) {
+    return readRootStructuredFileSyncInternal(options, options);
+}
+function readRootStructuredFileSyncInternal(options, parser) {
+    let absolutePath;
+    let relativePath;
+    let rootDir;
+    let rootRealPath;
+    try {
+        rootDir = options.rootDir;
+        relativePath = options.relativePath;
+        rootRealPath = options.rootRealPath;
+        assertNoWindowsPathAlias(rootDir);
+        assertNoWindowsPathAlias(relativePath, "relative");
+        if (rootRealPath !== undefined) {
+            assertNoWindowsPathAlias(rootRealPath);
+        }
+        absolutePath = path.resolve(rootDir, relativePath);
+        assertNoWindowsPathAlias(absolutePath);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "open",
+            failure: { ok: false, reason: "validation", error },
+        };
+    }
+    const boundaryLabel = options.boundaryLabel;
+    const rejectHardlinks = options.rejectHardlinks;
+    const maxBytes = options.maxBytes;
+    const opened = openRootFileSync({
+        absolutePath,
+        rootPath: rootDir,
+        rootRealPath,
+        boundaryLabel,
+        rejectHardlinks,
+        maxBytes,
+        allowedType: "file",
+    });
+    if (!opened.ok) {
+        return { ok: false, reason: "open", failure: opened };
+    }
+    try {
+        const raw = maxBytes === undefined
+            ? fsSync.readFileSync(opened.fd, "utf8")
+            : readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
+        const parse = parser.parse;
+        const parsed = Reflect.apply(parse, parser, [raw]);
+        const validate = parser.validate;
+        if (validate && !Reflect.apply(validate, parser, [parsed])) {
+            return {
+                ok: false,
+                reason: "invalid",
+                error: resolveInvalidMessage(parser.invalidMessage, relativePath),
+            };
+        }
+        return {
+            ok: true,
+            value: parsed,
+            stat: opened.stat,
+            path: opened.path,
+            rootRealPath: opened.rootRealPath,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "parse",
+            error: `failed to parse ${relativePath}: ${String(error)}`,
+        };
+    }
+    finally {
+        fsSync.closeSync(opened.fd);
+    }
+}
+export function readRootJsonSync(options) {
+    return readRootStructuredFileSyncInternal(options, {
+        parse: (raw) => JSON.parse(raw),
+    });
+}
+export function readRootJsonObjectSync(options) {
+    return readRootStructuredFileSyncInternal(options, {
+        parse: (raw) => JSON.parse(raw),
+        validate: isRecord,
+        invalidMessage: (relativePath) => `${relativePath} must contain a JSON object`,
+    });
+}
+export async function tryReadJson(filePath, options = {}) {
+    try {
+        const buffer = await readRegularFileIfExistsWithRetry(filePath, options);
+        if (buffer === null) {
+            return null;
+        }
+        const raw = buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readJson(filePath, options = {}) {
+    let raw;
+    try {
+        raw = (await readRegularFileWithRetry(filePath, options.maxBytes)).toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function readJsonIfExists(filePath, options = {}) {
+    let raw;
+    try {
+        const buffer = await readRegularFileIfExistsWithRetry(filePath, options);
+        if (buffer === null) {
+            return null;
+        }
+        raw = buffer.toString("utf8");
+    }
+    catch (err) {
+        if (getErrorCode(err) === "ENOENT") {
+            return null;
+        }
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export function readJsonSync(filePath, options = {}) {
+    let raw;
+    try {
+        raw = readRegularFileSync({ filePath, maxBytes: options.maxBytes }).buffer.toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function writeJson(filePath, value, options) {
+    const admittedPath = admitStandalonePublicationPath(filePath);
+    const text = stringifyJsonDocument(value, null, 2);
+    await writeTextAtomic(admittedPath, text, {
+        mode: options?.mode,
+        dirMode: options?.dirMode,
+        trailingNewline: options?.trailingNewline,
+        durable: options?.durable,
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/local-file-access.d.ts

@@ -0,0 +1,8 @@
+export declare function isFileUrl(input: string): boolean;
+export declare function hasEncodedFileUrlSeparator(pathname: string): boolean;
+export declare function isWindowsNetworkPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function isWindowsDriveLetterPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function assertNoWindowsNetworkPath(filePath: string, label?: string): void;
+export declare function safeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string;
+export declare function trySafeFileURLToPath(fileUrl: string, platform?: NodeJS.Platform): string | undefined;
+export declare function basenameFromMediaSource(source?: string): string | undefined;

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

@@ -0,0 +1,84 @@
+import path from "node:path";
+import { fileURLToPath, URL } from "node:url";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+import { hasWindowsPathAlias } from "./windows-path-alias.js";
+import { isWindowsSeparator, rootedWindowsDriveColonIndex, windowsNamespaceMarker, } from "./windows-path-syntax.js";
+const ENCODED_FILE_URL_SEPARATOR_RE = /%(?:2f|5c)/i;
+const FILE_URL_PREFIX_RE = /^file:\/\//i;
+export function isFileUrl(input) {
+    return FILE_URL_PREFIX_RE.test(input);
+}
+function isLocalFileUrlHost(hostname) {
+    const normalized = normalizeLowercaseStringOrEmpty(hostname);
+    return normalized === "" || normalized === "localhost";
+}
+export function hasEncodedFileUrlSeparator(pathname) {
+    return ENCODED_FILE_URL_SEPARATOR_RE.test(pathname);
+}
+export function isWindowsNetworkPath(filePath, platform = process.platform) {
+    if (platform !== "win32") {
+        return false;
+    }
+    return isWindowsSeparator(filePath, 0) && isWindowsSeparator(filePath, 1) &&
+        !(windowsNamespaceMarker(filePath) === "?" && rootedWindowsDriveColonIndex(filePath) === 5);
+}
+export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
+    return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);
+}
+export function assertNoWindowsNetworkPath(filePath, label = "Path") {
+    if (isWindowsNetworkPath(filePath)) {
+        throw new Error(`${label} cannot use Windows network paths: ${filePath}`);
+    }
+}
+export function safeFileURLToPath(fileUrl, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = new URL(fileUrl);
+    }
+    catch {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (parsed.protocol !== "file:") {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (!isLocalFileUrlHost(parsed.hostname)) {
+        throw new Error(`file:// URLs with remote hosts are not allowed: ${fileUrl}`);
+    }
+    if (hasEncodedFileUrlSeparator(parsed.pathname)) {
+        throw new Error(`file:// URLs cannot encode path separators: ${fileUrl}`);
+    }
+    const filePath = fileURLToPath(parsed, { windows: platform === "win32" });
+    if (hasWindowsPathAlias(filePath, "filesystem", platform)) {
+        throw new Error(`Local file URL cannot use Windows filesystem namespace aliases: ${filePath}`);
+    }
+    if (isWindowsNetworkPath(filePath, platform)) {
+        throw new Error(`Local file URL cannot use Windows network paths: ${filePath}`);
+    }
+    return filePath;
+}
+export function trySafeFileURLToPath(fileUrl, platform = process.platform) {
+    try {
+        return safeFileURLToPath(fileUrl, platform);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function basenameFromMediaSource(source) {
+    if (!source) {
+        return undefined;
+    }
+    if (isFileUrl(source)) {
+        const filePath = trySafeFileURLToPath(source);
+        return filePath ? path.basename(filePath) || undefined : undefined;
+    }
+    if (/^https?:\/\//i.test(source)) {
+        try {
+            return path.basename(new URL(source).pathname) || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.basename(source) || undefined;
+}

package/node_modules/@openclaw/fs-safe/dist/local-file-descriptor.d.ts

@@ -0,0 +1,16 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { HardlinkPolicy } from "./root-options.js";
+import type { SymlinkPolicy } from "./root-symlink-policy.js";
+type OwnedLocalFile = {
+    handle: FileHandle;
+    stat: Stats;
+    identity: BigIntStats;
+    preOpenStat: BigIntStats | undefined;
+};
+export declare function openLocalFileDescriptor(filePath: string, options?: {
+    hardlinks?: HardlinkPolicy;
+    symlinks?: SymlinkPolicy;
+    readWrite?: true;
+}): Promise<OwnedLocalFile>;
+export {};

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

@@ -0,0 +1,84 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { recordFileOpenFailure, recordPreOpenFileChange } from "./opened-file-failure.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const OPEN_READ_FLAGS = resolveReadOpenFlags();
+const OPEN_READ_FOLLOW_FLAGS = resolveReadOpenFlags({ followSymlinks: true });
+// Ownership transfers only after descriptor verification. Each admission caller
+// must close on rejection and construct an OpenResult only after admission.
+export async function openLocalFileDescriptor(filePath, options) {
+    assertNoUnsafeDeviceReadPath(filePath);
+    const fsSafeTestHooks = getFsSafeTestHooks();
+    let preOpenStat;
+    let observedBeforeOpen = false;
+    // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
+    // results that get sent to messaging channels). See openclaw/openclaw#31186.
+    try {
+        preOpenStat = await inspectFileIdentity(() => {
+            const stat = fsSync.lstatSync(filePath, { bigint: true });
+            observedBeforeOpen = true;
+            if (stat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
+                throw new FsSafeError("symlink", "symlink not allowed");
+            }
+            if (!stat.isFile() && !stat.isSymbolicLink()) {
+                throw new FsSafeError("not-file", "not a file");
+            }
+            return stat;
+        });
+    }
+    catch (err) {
+        if (err instanceof FsSafeError || observedBeforeOpen) {
+            throw err;
+        }
+        // Only an initial lookup failure falls through; a failed re-inspection aborts.
+    }
+    if (preOpenStat) {
+        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
+    }
+    const openFlags = (options?.symlinks === "follow-within-root"
+        ? OPEN_READ_FOLLOW_FLAGS
+        : OPEN_READ_FLAGS) | (options?.readWrite ? fsSync.constants.O_RDWR : 0);
+    await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
+    let handle;
+    try {
+        handle = await fs.open(filePath, openFlags).catch((error) => recordFileOpenFailure(isNotFoundPathError(error) ? fileNotFoundError() : error, filePath));
+    }
+    catch (err) {
+        if (isSymlinkOpenError(err)) {
+            throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
+        }
+        // Defensive: if open still throws EISDIR (e.g. race), sanitize so it never leaks.
+        if (hasNodeErrorCode(err, "EISDIR")) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        throw err;
+    }
+    try {
+        await fsSafeTestHooks?.afterOpen?.(filePath, handle);
+        const stat = fsSync.fstatSync(handle.fd);
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        // Keep numeric Stats for the public receipt, never for identity verification.
+        let openedIdentity;
+        const identity = await inspectFileIdentity(() => (openedIdentity = fsSync.fstatSync(handle.fd, { bigint: true })), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined).catch(async (error) => {
+            if ([0, 1].includes(stat.nlink)) {
+                await recordPreOpenFileChange(error, handle, filePath, preOpenStat, openedIdentity);
+            }
+            throw error;
+        });
+        if (options?.hardlinks === "reject" && stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+        return { handle, stat, identity, preOpenStat };
+    }
+    catch (err) {
+        await handle.close().catch(() => { });
+        throw err;
+    }
+}

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

@@ -0,0 +1,25 @@
+import { type HardlinkPolicy, type ReadResult, type SymlinkPolicy } from "./root.js";
+export type LocalRootsPathResult = {
+    path: string;
+    root: string;
+};
+export type LocalRootsReadResult = ReadResult & {
+    root: string;
+};
+export type LocalRootsInputOptions = {
+    filePath: string;
+    roots: readonly string[];
+    label?: string;
+};
+export type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+    allowMissing?: boolean;
+    requireFile?: boolean;
+};
+export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+    hardlinks?: HardlinkPolicy;
+    maxBytes?: number;
+    nonBlockingRead?: boolean;
+    symlinks?: SymlinkPolicy;
+};
+export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
+export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;