@openclaw/feishu 2026.9.6 → 2026.9.7

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

@@ -0,0 +1,11 @@
+export type FileStorePruneOptions = {
+    ttlMs: number;
+    recursive?: boolean;
+    maxDepth?: number;
+    pruneEmptyDirs?: boolean;
+};
+export declare function pruneExpiredStoreEntries(params: {
+    rootDir: string;
+    dirMode: number;
+    options: FileStorePruneOptions;
+}): Promise<void>;

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

@@ -0,0 +1,110 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { literalStoreRootPath } from "./file-store-boundary.js";
+import { isPathInside } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { root } from "./root.js";
+import { nonrecursiveRemovalKind } from "./root-remove.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const REMOVE_EMPTY_DIRECTORY_OPTIONS = Object.freeze({
+    [nonrecursiveRemovalKind]: "directory",
+});
+export async function pruneExpiredStoreEntries(params) {
+    const now = Date.now();
+    const recursive = params.options.recursive ?? false;
+    const maxDepth = params.options.maxDepth;
+    const pruneEmptyDirs = (recursive || maxDepth !== undefined) && (params.options.pruneEmptyDirs ?? false);
+    await fs.mkdir(recursiveMkdirPath(params.rootDir), { recursive: true, mode: params.dirMode });
+    const rootReal = realpathSync.native(params.rootDir);
+    const scopedRoot = await root(rootReal);
+    const rootGuard = {
+        dir: rootReal,
+        realPath: rootReal,
+        stat: fsSync.lstatSync(rootReal, { bigint: true }),
+    };
+    async function assertRootGuard() {
+        const stat = fsSync.lstatSync(rootGuard.dir, { bigint: true });
+        if (stat.isSymbolicLink() ||
+            !stat.isDirectory() ||
+            stat.dev !== rootGuard.stat.dev ||
+            stat.ino !== rootGuard.stat.ino ||
+            realpathSync.native(rootGuard.dir) !== rootGuard.realPath) {
+            throw new FsSafeError("path-mismatch", "store root changed during prune");
+        }
+    }
+    async function readStableDirectory(dir) {
+        const before = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
+        if (!before || before.isSymbolicLink() || !before.isDirectory()) {
+            return null;
+        }
+        const real = observeOrNull(() => realpathSync.native(dir));
+        if (!real || !isPathInside(rootReal, real)) {
+            return null;
+        }
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => null);
+        if (!entries) {
+            return null;
+        }
+        const after = observeOrNull(() => fsSync.lstatSync(dir, { bigint: true }));
+        if (!after || before.dev !== after.dev || before.ino !== after.ino) {
+            return null;
+        }
+        return entries;
+    }
+    async function pruneDir(dir, relativeDir, depth) {
+        const entries = await readStableDirectory(dir);
+        if (!entries) {
+            return false;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const stat = observeOrNull(() => fsSync.lstatSync(fullPath));
+            if (!stat || stat.isSymbolicLink()) {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                const shouldDescend = maxDepth !== undefined ? depth < maxDepth : recursive;
+                if (shouldDescend) {
+                    await getFsSafeTestHooks()?.beforeFileStorePruneDescend?.(fullPath);
+                }
+                if (shouldDescend && (await pruneDir(fullPath, relativePath, depth + 1))) {
+                    await assertRootGuard();
+                    // Keep empty-dir pruning on the same root-bounded remove path as files;
+                    // the Root fallback handles empty directories without recursive delete.
+                    await scopedRoot.remove(literalStoreRootPath(relativePath), REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
+                }
+                continue;
+            }
+            if (stat.isFile() && now - stat.mtimeMs > params.options.ttlMs) {
+                await assertRootGuard();
+                await scopedRoot.remove(literalStoreRootPath(relativePath), {
+                    assertBeforeMutation: () => {
+                        // Removal preparation can outlive the expiry observation above.
+                        const current = fsSync.lstatSync(fullPath);
+                        if (!current.isFile() || !(now - current.mtimeMs > params.options.ttlMs)) {
+                            throw new FsSafeError("path-mismatch", "store entry is no longer an expired file");
+                        }
+                    },
+                }).catch(() => undefined);
+            }
+        }
+        if (!pruneEmptyDirs) {
+            return false;
+        }
+        const remaining = await readStableDirectory(dir);
+        return remaining !== null && remaining.length === 0;
+    }
+    await pruneDir(rootReal, "", 0);
+}
+function observeOrNull(observe) {
+    try {
+        return observe();
+    }
+    catch {
+        return null;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/file-store-sync-directory.d.ts

@@ -0,0 +1,15 @@
+import { type BigIntStats } from "node:fs";
+type StoreMessagePrefix = "private store" | "store";
+export type SyncStoreDirectoryReceipt = Readonly<{
+    dir: string;
+    realPath: string;
+    exactStat: BigIntStats;
+}>;
+export declare function ensureSyncStoreDirectory(params: {
+    rootDir: string;
+    targetDir: string;
+    mode: number;
+    messagePrefix: StoreMessagePrefix;
+}): SyncStoreDirectoryReceipt;
+export declare function assertSyncStoreDirectoryReceipt(receipt: SyncStoreDirectoryReceipt): void;
+export {};

package/node_modules/@openclaw/fs-safe/dist/file-store-sync-directory.js

@@ -0,0 +1,319 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isPathInside, isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function changedStoreDirectory(messagePrefix, cause) {
+    return new FsSafeError("outside-workspace", `${messagePrefix} directory escapes root`, { cause });
+}
+function storeDirectoryRealPath(dir) {
+    const operationPath = pathForWindowsFilesystem(dir);
+    const realPath = process.platform === "win32"
+        ? realpathSync(operationPath) : realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return realPath;
+}
+function inspectStoreDirectory(params) {
+    assertNoWindowsPathAlias(params.dir, "filesystem");
+    return inspectFileIdentitySync(() => {
+        const stat = fs.lstatSync(pathForWindowsFilesystem(params.dir), { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            const subject = params.root ? "root" : "directory component";
+            throw new FsSafeError("not-file", `${params.messagePrefix} ${subject} must be a directory: ${params.dir}`);
+        }
+        return stat;
+    }, params.expected);
+}
+function directoryOpenFlags() {
+    const { O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK, O_RDONLY } = fs.constants;
+    if ([O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK, O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    return O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK;
+}
+function directorySearchFlags() {
+    // Linux O_PATH descriptors cannot be fchmoded, and /proc/self/fd would
+    // reintroduce a pathname mutation. Darwin O_SEARCH remains descriptor-bound.
+    if (process.platform !== "darwin" ||
+        (process.arch !== "x64" && process.arch !== "arm64"))
+        return undefined;
+    const { O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK } = fs.constants;
+    if ([O_DIRECTORY, O_NOFOLLOW, O_NONBLOCK].some((flag) => typeof flag !== "number")) {
+        return undefined;
+    }
+    // Darwin SDK O_SEARCH = O_EXEC (0x40000000) | O_DIRECTORY on supported Node hosts.
+    return 0x40000000 | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK;
+}
+function hasErrorCode(error, code) {
+    if (error && typeof error === "object") {
+        if (error.code === code)
+            return true;
+        const combined = error;
+        return (combined.error !== error && hasErrorCode(combined.error, code)) ||
+            (combined.suppressed !== error && hasErrorCode(combined.suppressed, code));
+    }
+    return false;
+}
+class StoreDirectoryChain {
+    messagePrefix;
+    receipts = [];
+    rootReal;
+    constructor(rootDir, messagePrefix) {
+        this.messagePrefix = messagePrefix;
+        this.observe(rootDir);
+        this.rootReal = storeDirectoryRealPath(rootDir);
+    }
+    observe(dir) {
+        this.receipts.push({
+            dir,
+            stat: inspectStoreDirectory({
+                dir,
+                messagePrefix: this.messagePrefix,
+                root: this.receipts.length === 0,
+            }),
+        });
+    }
+    inspectReceipt(receipt, root = false) {
+        try {
+            const stat = inspectStoreDirectory({
+                dir: receipt.dir,
+                expected: receipt.stat,
+                messagePrefix: this.messagePrefix,
+                root,
+            });
+            if (stat.dev !== receipt.stat.dev || stat.ino !== receipt.stat.ino) {
+                throw changedStoreDirectory(this.messagePrefix);
+            }
+            return stat;
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "outside-workspace")
+                throw error;
+            throw changedStoreDirectory(this.messagePrefix, error);
+        }
+    }
+    assertRoot() {
+        const root = this.receipts[0];
+        const stat = this.inspectReceipt(root, true);
+        try {
+            if (storeDirectoryRealPath(root.dir) !== this.rootReal) {
+                throw changedStoreDirectory(this.messagePrefix);
+            }
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "outside-workspace")
+                throw error;
+            throw changedStoreDirectory(this.messagePrefix, error);
+        }
+        return stat;
+    }
+    assertEdge(canonicalRoot = true) {
+        const targetIndex = this.receipts.length - 1;
+        const rootStat = canonicalRoot
+            ? this.assertRoot() : this.inspectReceipt(this.receipts[0], true);
+        if (targetIndex === 0)
+            return rootStat;
+        const parent = this.receipts[targetIndex - 1];
+        if (targetIndex > 1)
+            this.inspectReceipt(parent);
+        const target = this.receipts[targetIndex];
+        const targetStat = this.inspectReceipt(target);
+        if (path.dirname(target.dir) !== parent.dir) {
+            throw changedStoreDirectory(this.messagePrefix);
+        }
+        return targetStat;
+    }
+    assertModeTarget() {
+        const root = this.receipts[0];
+        const target = this.receipts.at(-1);
+        // The target's canonical observation shares the exact identity fence. Keep
+        // the trailing root canonical check: an ancestor relocation can retain IDs.
+        this.assertEdge(false);
+        let targetReal;
+        try {
+            targetReal = storeDirectoryRealPath(target.dir);
+        }
+        catch (error) {
+            throw changedStoreDirectory(this.messagePrefix, error);
+        }
+        if (target === root ? targetReal !== this.rootReal : !isPathInside(this.rootReal, targetReal)) {
+            throw changedStoreDirectory(this.messagePrefix);
+        }
+        return this.assertEdge();
+    }
+    finish(dir) {
+        const root = this.receipts[0];
+        const target = this.receipts.at(-1);
+        this.assertRoot();
+        let finalStat = root.stat;
+        for (const [index, receipt] of this.receipts.entries()) {
+            if (index === 0)
+                continue;
+            finalStat = this.inspectReceipt(receipt);
+        }
+        let finalReal;
+        try {
+            finalReal = storeDirectoryRealPath(target.dir);
+        }
+        catch (error) {
+            throw changedStoreDirectory(this.messagePrefix, error);
+        }
+        if (!isPathInside(this.rootReal, finalReal))
+            throw changedStoreDirectory(this.messagePrefix);
+        this.assertRoot();
+        if (target !== root)
+            finalStat = this.inspectReceipt(target);
+        return { dir, realPath: finalReal, exactStat: finalStat };
+    }
+    openForMode(receipt) {
+        let openError;
+        try {
+            return fs.openSync(pathForWindowsFilesystem(receipt.dir), directoryOpenFlags());
+        }
+        catch (error) {
+            openError = error;
+        }
+        const searchFlags = hasErrorCode(openError, "EACCES") ? directorySearchFlags() : undefined;
+        if (searchFlags !== undefined) {
+            try {
+                return fs.openSync(pathForWindowsFilesystem(receipt.dir), searchFlags);
+            }
+            catch (searchError) {
+                openError = createSuppressedError(searchError, openError, "ordinary and search-only directory opens both failed");
+            }
+        }
+        try {
+            this.assertModeTarget();
+        }
+        catch (boundaryError) {
+            throw changedStoreDirectory(this.messagePrefix, createSuppressedError(boundaryError, openError, "directory acquisition and boundary revalidation both failed"));
+        }
+        if (hasErrorCode(openError, "EACCES")) {
+            throw new FsSafeError("permission-unverified", `${this.messagePrefix} directory cannot be safely mode-repaired through a Node descriptor`, { cause: openError });
+        }
+        throw openError;
+    }
+    inspectOpened(descriptor, receipt) {
+        try {
+            const stat = inspectFileIdentitySync(() => fs.fstatSync(descriptor, { bigint: true }), receipt.stat);
+            if (!stat.isDirectory() || stat.isSymbolicLink()) {
+                throw changedStoreDirectory(this.messagePrefix);
+            }
+            return stat;
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "outside-workspace")
+                throw error;
+            throw changedStoreDirectory(this.messagePrefix, error);
+        }
+    }
+    finalizeMode(mode) {
+        const receipt = this.receipts.at(-1);
+        const requestedMode = BigInt(mode & 0o7777);
+        if ((receipt.stat.mode & 4095n) === requestedMode || process.platform === "win32") {
+            const current = this.assertEdge();
+            // Identity can remain stable while permissions change after the first receipt.
+            if (process.platform === "win32" || (current.mode & 4095n) === requestedMode) {
+                this.receipts[this.receipts.length - 1] = { ...receipt, stat: current };
+                return;
+            }
+        }
+        // Repair owns the stronger pre/post mode-target fence below, including an
+        // admission check on acquisition failure; no earlier admission is needed.
+        const descriptor = this.openForMode(receipt);
+        let finalStat;
+        let operationFailed = false;
+        let operationError;
+        try {
+            const opened = this.inspectOpened(descriptor, receipt);
+            this.assertModeTarget();
+            if ((opened.mode & 4095n) !== requestedMode) {
+                fs.fchmodSync(descriptor, Number(requestedMode));
+            }
+            const finalized = this.inspectOpened(descriptor, receipt);
+            const pathname = this.assertModeTarget();
+            if ((finalized.mode & 4095n) !== requestedMode ||
+                (pathname.mode & 4095n) !== requestedMode) {
+                throw new FsSafeError("insecure-permissions", `${this.messagePrefix} directory mode could not be finalized`);
+            }
+            finalStat = pathname;
+        }
+        catch (error) {
+            operationFailed = true;
+            operationError = error;
+        }
+        try {
+            fs.closeSync(descriptor);
+        }
+        catch (closeError) {
+            if (operationFailed) {
+                throw createSuppressedError(closeError, operationError, "store directory finalization and close both failed");
+            }
+            throw closeError;
+        }
+        if (operationFailed)
+            throw operationError;
+        if (!finalStat)
+            throw new FsSafeError("helper-failed", "store directory mode receipt is missing");
+        this.receipts[this.receipts.length - 1] = { ...receipt, stat: finalStat };
+    }
+}
+export function ensureSyncStoreDirectory(params) {
+    assertNoWindowsPathAlias(params.rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(params.targetDir, "filesystem", "store path uses a Windows filesystem namespace alias");
+    const rootDir = resolvePathPreservingWindowsRoot(params.rootDir);
+    const dir = resolvePathPreservingWindowsRoot(params.targetDir);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(dir, "filesystem", "store path uses a Windows filesystem namespace alias");
+    const relative = path.relative(rootDir, dir);
+    if (isPathRelativeEscape(relative)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+    fs.mkdirSync(recursiveMkdirPath(pathForWindowsFilesystem(rootDir)), { recursive: true, mode: params.mode });
+    const chain = new StoreDirectoryChain(rootDir, params.messagePrefix);
+    chain.finalizeMode(params.mode);
+    let current = rootDir;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            chain.observe(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            fs.mkdirSync(pathForWindowsFilesystem(current), { mode: params.mode });
+            chain.observe(current);
+        }
+        chain.finalizeMode(params.mode);
+    }
+    return chain.finish(dir);
+}
+export function assertSyncStoreDirectoryReceipt(receipt) {
+    try {
+        assertNoWindowsPathAlias(receipt.realPath, "filesystem");
+        const stat = inspectStoreDirectory({
+            dir: receipt.dir,
+            expected: receipt.exactStat,
+            messagePrefix: "store",
+            root: false,
+        });
+        if (stat.dev !== receipt.exactStat.dev || stat.ino !== receipt.exactStat.ino ||
+            storeDirectoryRealPath(receipt.dir) !== receipt.realPath) {
+            throw new FsSafeError("path-mismatch", "store directory changed during write");
+        }
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch" &&
+            error.message !== "store directory changed during write") {
+            throw new FsSafeError("path-mismatch", "store directory changed during write", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/file-store-sync-write.d.ts

@@ -0,0 +1,9 @@
+export declare function writeFileSyncAtomic(params: {
+    rootDir: string;
+    filePath: string;
+    content: string | Uint8Array;
+    privateMode: boolean;
+    durable: boolean;
+    dirMode: number;
+    mode: number;
+}): string;

package/node_modules/@openclaw/fs-safe/dist/file-store-sync-write.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import path from "node:path";
+import { syncDirectorySync } from "./directory-durability.js";
+import { createDirectoryReceiptFromIdentity } from "./directory-receipt.js";
+import { FsSafeError } from "./errors.js";
+import { ensureParentSync, ensureStoreDirectorySync, } from "./file-store-boundary.js";
+import { assertSyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
+import { isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { errorCauseOptions } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function verifyStoreFile(fd, expected, filePath) {
+    const assertFile = (stat, allowUnknown = false) => {
+        const unknown = allowUnknown && process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n ||
+            (stat.dev !== expected.dev && !(unknown && stat.dev === 0n)) ||
+            (stat.ino !== expected.ino && !(unknown && stat.ino === 0n))) {
+            throw new FsSafeError("path-mismatch", "store file changed during write");
+        }
+        return unknown;
+    };
+    const assertDescriptor = (descriptor) => {
+        assertFile(inspectFileIdentitySync(() => fs.fstatSync(descriptor, { bigint: true }), expected));
+    };
+    assertDescriptor(fd);
+    if (assertFile(fs.lstatSync(filePath, { bigint: true }), true)) {
+        // A Windows pathname can have opaque metadata even while the retained writer is known.
+        // Reopen for identity only; equal content cannot establish that publication kept its file.
+        const reopened = fs.openSync(filePath, resolveReadOpenFlags());
+        try {
+            assertDescriptor(reopened);
+            assertFile(fs.lstatSync(filePath, { bigint: true }), true);
+            assertDescriptor(reopened);
+        }
+        finally {
+            fs.closeSync(reopened);
+        }
+    }
+    assertDescriptor(fd);
+}
+export function writeFileSyncAtomic(params) {
+    const filePath = path.resolve(params.filePath);
+    if (!isPathInside(params.rootDir, filePath)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+    let parentGuard;
+    if (params.privateMode) {
+        parentGuard = ensureStoreDirectorySync({
+            rootDir: params.rootDir,
+            targetDir: path.dirname(filePath),
+            mode: params.dirMode,
+            messagePrefix: "private store",
+        });
+        try {
+            const stat = fs.lstatSync(filePath);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new FsSafeError("not-file", `private store target must be a regular file: ${filePath}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    else {
+        parentGuard = ensureParentSync({
+            rootDir: params.rootDir,
+            filePath,
+            mode: params.dirMode,
+        });
+    }
+    const tempPath = path.join(parentGuard.dir, `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    const owner = new SyncAtomicTempOwner(tempPath);
+    let originalFailure;
+    try {
+        getFsSafeTestHooks()?.beforeFileStoreSyncPrivateWrite?.(filePath);
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        owner.start();
+        const temp = writeTempFileSync({
+            fsModule: fs, tempPath, content: params.content, mode: params.mode, sync: false,
+            onIdentity: owner.onIdentity,
+            fchmodSync: (descriptor, mode) => {
+                try {
+                    fs.fchmodSync(descriptor, mode);
+                }
+                catch {
+                    // Best-effort on platforms that do not enforce POSIX modes.
+                }
+            },
+        });
+        owner.adopt(temp);
+        // Preserve the store's strict fsync errors; the generic temp helper tolerates EPERM.
+        if (params.durable)
+            fs.fsyncSync(temp.fd);
+        verifyStoreFile(temp.fd, owner.identity, tempPath);
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        fs.renameSync(tempPath, filePath);
+        owner.markRenamed();
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        try {
+            verifyStoreFile(temp.fd, owner.identity, filePath);
+        }
+        catch (error) {
+            if (error instanceof FsSafeError) {
+                throw error;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed after write", errorCauseOptions(error));
+        }
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        if (params.durable) {
+            syncDirectorySync(createDirectoryReceiptFromIdentity(parentGuard.dir, parentGuard.realPath, parentGuard.exactStat), { label: "store parent" });
+        }
+        assertSyncStoreDirectoryReceipt(parentGuard);
+        return filePath;
+    }
+    catch (error) {
+        originalFailure = { error };
+        throw error;
+    }
+    finally {
+        owner.finish({ fsModule: fs, originalFailure, throwOnCleanupError: false });
+    }
+}

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

@@ -0,0 +1,62 @@
+import type { Readable } from "node:stream";
+import { type FileStorePruneOptions } from "./file-store-prune.js";
+export type { FileStorePruneOptions } from "./file-store-prune.js";
+import { type JsonFileStoreOptions, type JsonStore } from "./json-document-store.js";
+import { type OpenResult, type ReadResult, type Root, type RootReadOptions } from "./root.js";
+export type FileStoreOptions = {
+    rootDir: string;
+    private?: boolean;
+    /** Default for writes, streams, and copies; true syncs file and parent where supported. */
+    durable?: boolean;
+    dirMode?: number;
+    mode?: number;
+    maxBytes?: number;
+};
+export type FileStoreWriteOptions = Partial<Pick<FileStoreOptions, "dirMode" | "mode" | "maxBytes"> & {
+    /** Override store durability; defaults to the store option, then true. */
+    durable: boolean;
+    tempPrefix: string;
+}>;
+export type FileStoreReadOptions = RootReadOptions & {
+    encoding?: BufferEncoding;
+};
+export type FileStore = {
+    readonly rootDir: string;
+    path(relativePath: string): string;
+    root(): Promise<Root>;
+    write(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): Promise<string>;
+    writeStream(relativePath: string, stream: Readable, options?: FileStoreWriteOptions): Promise<string>;
+    copyIn(relativePath: string, sourcePath: string, options?: FileStoreWriteOptions): Promise<string>;
+    open(relativePath: string, options?: RootReadOptions): Promise<OpenResult>;
+    read(relativePath: string, options?: RootReadOptions): Promise<ReadResult>;
+    readBytes(relativePath: string, options?: RootReadOptions): Promise<Buffer>;
+    readText(relativePath: string, options?: FileStoreReadOptions): Promise<string>;
+    readTextIfExists(relativePath: string, options?: FileStoreReadOptions): Promise<string | null>;
+    readJson<T = unknown>(relativePath: string, options?: FileStoreReadOptions): Promise<T>;
+    readJsonIfExists<T = unknown>(relativePath: string, options?: FileStoreReadOptions): Promise<T | null>;
+    remove(relativePath: string): Promise<void>;
+    exists(relativePath: string): Promise<boolean>;
+    writeText(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): Promise<string>;
+    writeJson(relativePath: string, data: unknown, options?: FileStoreWriteOptions & {
+        trailingNewline?: boolean;
+    }): Promise<string>;
+    json<T = unknown>(relativePath: string, options?: JsonFileStoreOptions): JsonStore<T>;
+    pruneExpired(options: FileStorePruneOptions): Promise<void>;
+};
+export type FileStoreSync = {
+    readonly rootDir: string;
+    path(relativePath: string): string;
+    readTextIfExists(relativePath: string, options?: {
+        maxBytes?: number;
+    }): string | null;
+    readJsonIfExists<T = unknown>(relativePath: string, options?: {
+        maxBytes?: number;
+    }): T | null;
+    write(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): string;
+    writeText(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): string;
+    writeJson(relativePath: string, data: unknown, options?: FileStoreWriteOptions & {
+        trailingNewline?: boolean;
+    }): string;
+};
+export declare function fileStore(options: FileStoreOptions): FileStore;
+export declare function fileStoreSync(options: FileStoreOptions): FileStoreSync;