@openclaw/matrix 2026.9.6 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-owner.js

@@ -0,0 +1,398 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+import { openTempWorkspaceCleanupParent, TempWorkspaceRetainedChild, } from "./temp-workspace-descriptor.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function isNativeCleanupBinding(binding) {
+    return typeof binding?.renameNoReplace === "function" &&
+        typeof binding.removeOwnedTree === "function" &&
+        typeof binding.removeOwnedTreeSync === "function" &&
+        typeof binding.ownedTreeRemovalAvailable === "function";
+}
+export class TempWorkspaceCleanupCapability {
+    binding;
+    parent;
+    #admission;
+    #safety;
+    #ownedTreeRemovalAvailable;
+    #phase = "new";
+    constructor(root, safety, admission, dirMode) {
+        assertNoWindowsPathAlias(root, "filesystem");
+        const admittedRoot = admission.dir;
+        assertNoWindowsPathAlias(admittedRoot, "filesystem");
+        const resolvedRoot = resolvePathPreservingWindowsRoot(root);
+        assertNoWindowsPathAlias(resolvedRoot, "filesystem");
+        if (resolvedRoot !== resolvePathPreservingWindowsRoot(admittedRoot)) {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent differs from admitted root");
+        }
+        this.#admission = admission;
+        this.#safety = safety;
+        // POSIX enumeration reopens fd-relative ".", so retaining O_RDONLY before
+        // chmod cannot supply read/search authority that the final mode removes.
+        const childModeAllowsRemoval = process.platform === "win32" || (dirMode & 0o500) === 0o500;
+        if (safety === "require-bounded" && !childModeAllowsRemoval) {
+            throw new FsSafeError("helper-unavailable", "temp workspace owned-tree cleanup requires owner read and search in dirMode");
+        }
+        let binding;
+        try {
+            binding = getNativeBinding();
+        }
+        catch (error) {
+            if (safety === "require-bounded")
+                throw error;
+        }
+        this.binding = binding;
+        let parent;
+        try {
+            parent = openTempWorkspaceCleanupParent(root, admission);
+        }
+        catch (error) {
+            // Failed descriptor closure must retain the original admission failure too.
+            if (error instanceof AggregateError)
+                throw error;
+        }
+        let available = false;
+        if (childModeAllowsRemoval && parent?.access === "read" && isNativeCleanupBinding(binding)) {
+            let probeReady = false;
+            try {
+                admission.prepareCleanupProbe(parent.fd);
+                probeReady = true;
+            }
+            catch (error) {
+                // A descriptor that cannot be associated even provisionally must not
+                // reach native code or remain available to compatible cleanup.
+                try {
+                    fsSync.closeSync(parent.fd);
+                }
+                catch (closeError) {
+                    throw new AggregateError([error, closeError], "temp workspace cleanup parent probe admission and close failed");
+                }
+                parent = undefined;
+            }
+            try {
+                if (probeReady && parent) {
+                    available = binding.ownedTreeRemovalAvailable(parent.fd) === true;
+                }
+            }
+            catch {
+                // Runtime denial must select fallback or reject before child creation.
+            }
+        }
+        this.parent = parent;
+        this.#ownedTreeRemovalAvailable = available;
+        if (safety === "require-bounded" && !this.#ownedTreeRemovalAvailable) {
+            this.close();
+            throw new FsSafeError("helper-unavailable", "temp workspace owned-tree cleanup is unavailable");
+        }
+    }
+    get canRemoveOwnedTree() {
+        return (this.#phase === "ready" || this.#phase === "sealed") &&
+            this.#ownedTreeRemovalAvailable;
+    }
+    prepareChildCreation() {
+        const replay = this.#phase === "ready";
+        if (this.#phase !== "new" && !replay) {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent is unavailable");
+        }
+        // A failed initial admission or receipt replay is terminal: no earlier
+        // authority may survive a partial revalidation.
+        this.#phase = "failed";
+        if (replay) {
+            if (this.parent)
+                this.#admission.associateAncestry(this.parent.fd);
+            else
+                this.#admission.assertAncestry();
+        }
+        else {
+            this.#admission.prepareChildCreation(this.parent?.fd);
+        }
+        // The retained descriptor cannot authorize cleanup until the complete
+        // ancestry and its exact descriptor association succeeded together.
+        this.#phase = "ready";
+    }
+    #assertCurrent(ancestry) {
+        if ((this.#phase !== "ready" && this.#phase !== "sealed") || !this.parent) {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent is unavailable");
+        }
+        if (ancestry)
+            this.#admission.associateAncestry(this.parent.fd);
+        else
+            this.#admission.associateCurrent(this.parent.fd);
+    }
+    admitChildDescriptor(canEnumerate) {
+        if (this.#phase !== "ready") {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent is unavailable");
+        }
+        // From this point the capability belongs to this successfully created
+        // child. Collision retries and further preparation must remain impossible.
+        this.#phase = "sealed";
+        const bounded = this.canRemoveOwnedTree && canEnumerate;
+        if (this.#safety === "require-bounded" && !bounded) {
+            throw new FsSafeError("helper-unavailable", "temp workspace owned-tree cleanup requires a readable child descriptor");
+        }
+        return bounded;
+    }
+    assertCurrent() {
+        this.#assertCurrent(false);
+    }
+    assertAncestryCurrent() {
+        this.#assertCurrent(true);
+    }
+    close() {
+        if (this.#phase === "closed")
+            return;
+        this.#phase = "closed";
+        if (this.parent)
+            fsSync.closeSync(this.parent.fd);
+    }
+}
+export function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner, label = "temp workspace") {
+    try {
+        if (owner)
+            owner.cleanupSync();
+        else {
+            const closeErrors = [];
+            try {
+                retainedChild?.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            try {
+                capability.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            if (closeErrors.length === 1)
+                throw closeErrors[0];
+            if (closeErrors.length > 1) {
+                throw new AggregateError(closeErrors, `${label} admission descriptor close failed`);
+            }
+        }
+    }
+    catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], `${label} creation and cleanup both failed`);
+    }
+    throw error;
+}
+export class TempWorkspaceCleanupOwner {
+    #dir;
+    #identity;
+    #capability;
+    #directory;
+    #closed = false;
+    #running = false;
+    #exitInterrupted = false;
+    #result;
+    #pending;
+    constructor(retained, capability, retainDescriptor) {
+        const child = retained.transfer(retainDescriptor);
+        this.#dir = child.dir;
+        this.#identity = child.identity;
+        this.#capability = capability;
+        this.#directory = child.directory;
+    }
+    #repeat() {
+        return this.#result === "removed" ? "missing" : this.#result;
+    }
+    #close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const errors = [];
+        if (this.#directory) {
+            try {
+                fsSync.closeSync(this.#directory.fd);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        try {
+            this.#capability.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "temp workspace cleanup descriptor close failed");
+    }
+    #finish(result) {
+        this.#result ??= this.#exitInterrupted ? "indeterminate" : result;
+        try {
+            this.#close();
+        }
+        catch (error) {
+            this.#result = "indeterminate";
+            throw error;
+        }
+        return this.#result;
+    }
+    #fallbackResult() {
+        try {
+            const current = fsSync.lstatSync(this.#dir, { bigint: true });
+            return current.isDirectory() && !current.isSymbolicLink() &&
+                sameFileIdentityForCleanup(current, this.#identity)
+                ? "indeterminate"
+                : "identity-mismatch";
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? "missing" : "indeterminate";
+        }
+    }
+    #prepare() {
+        const parent = this.#capability.parent;
+        if (!parent)
+            return this.#fallbackResult();
+        try {
+            this.#capability.assertCurrent();
+            let current;
+            try {
+                current = fsSync.lstatSync(this.#dir, { bigint: true });
+            }
+            catch (error) {
+                this.#capability.assertCurrent();
+                return error.code === "ENOENT" ? "missing" : "indeterminate";
+            }
+            this.#capability.assertCurrent();
+            if (!current.isDirectory() || current.isSymbolicLink() ||
+                !sameFileIdentityForCleanup(current, this.#identity)) {
+                return "identity-mismatch";
+            }
+            const name = `.fs-safe-workspace-cleanup-${randomUUID()}`;
+            const quarantinePath = path.join(parent.receipt.path, name);
+            const nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
+            if (nativeRemoval) {
+                this.#capability.binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+            }
+            else {
+                // The admitted receipt is exact and descriptor-associated. Reuse it as
+                // the pre/post parent fence instead of layering a numeric guard over it.
+                this.#capability.assertCurrent();
+                fsSync.renameSync(this.#dir, quarantinePath);
+            }
+            this.#capability.assertCurrent();
+            const quarantined = fsSync.lstatSync(quarantinePath, { bigint: true });
+            this.#capability.assertCurrent();
+            if (!quarantined.isDirectory() || quarantined.isSymbolicLink() ||
+                !sameFileIdentityForCleanup(quarantined, this.#identity)) {
+                return "indeterminate";
+            }
+            return { name, path: quarantinePath, nativeRemoval };
+        }
+        catch {
+            // A failed rename can still have committed on a remote filesystem.
+            return "indeterminate";
+        }
+    }
+    #assertQuarantine(quarantine) {
+        const current = fsSync.lstatSync(quarantine.path, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink() ||
+            !sameFileIdentityForCleanup(current, this.#identity)) {
+            throw new FsSafeError("path-mismatch", "temp workspace quarantine changed");
+        }
+        this.#capability.assertCurrent();
+    }
+    #mapRemoval(result) {
+        if (result.errorCode) {
+            const error = Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
+                code: result.errorCode,
+            });
+            if (error.code === "path-mismatch")
+                return "indeterminate";
+            throw error;
+        }
+        return result.outcome === "removed" ? "removed" : "indeterminate";
+    }
+    async #remove(quarantine) {
+        if (quarantine.nativeRemoval) {
+            const beforeNativeRemoval = getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemoval;
+            if (beforeNativeRemoval)
+                await beforeNativeRemoval(quarantine.path);
+            return this.#mapRemoval(await this.#capability.binding.removeOwnedTree(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
+        }
+        try {
+            this.#assertQuarantine(quarantine);
+        }
+        catch {
+            return "indeterminate";
+        }
+        // Removal failures propagate unchanged; only authority uncertainty becomes a receipt.
+        await fs.rm(quarantine.path, { recursive: true, force: true });
+        try {
+            this.#capability.assertCurrent();
+            return "removed";
+        }
+        catch {
+            return "indeterminate";
+        }
+    }
+    #removeSync(quarantine) {
+        if (quarantine.nativeRemoval) {
+            getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemovalSync?.(quarantine.path);
+            return this.#mapRemoval(this.#capability.binding.removeOwnedTreeSync(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
+        }
+        try {
+            this.#assertQuarantine(quarantine);
+        }
+        catch {
+            return "indeterminate";
+        }
+        fsSync.rmSync(quarantine.path, { recursive: true, force: true });
+        try {
+            this.#capability.assertCurrent();
+            return "removed";
+        }
+        catch {
+            return "indeterminate";
+        }
+    }
+    async #run() {
+        let result = "indeterminate";
+        try {
+            const prepared = this.#prepare();
+            result = typeof prepared === "string" ? prepared : await this.#remove(prepared);
+            return this.#finish(result);
+        }
+        finally {
+            if (!this.#closed)
+                this.#finish(result);
+        }
+    }
+    cleanup() {
+        if (this.#result)
+            return Promise.resolve(this.#repeat());
+        if (this.#pending)
+            return this.#pending.then(() => this.#repeat());
+        this.#running = true;
+        this.#pending = this.#run();
+        return this.#pending;
+    }
+    cleanupSync() {
+        if (this.#result)
+            return this.#repeat();
+        if (this.#running) {
+            this.#exitInterrupted = true;
+            return "indeterminate";
+        }
+        this.#running = true;
+        let result = "indeterminate";
+        try {
+            const prepared = this.#prepare();
+            result = typeof prepared === "string" ? prepared : this.#removeSync(prepared);
+            return this.#finish(result);
+        }
+        finally {
+            if (!this.#closed)
+                this.#finish(result);
+        }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-ownership.d.ts

@@ -0,0 +1,8 @@
+type DirectoryOwner = {
+    uid: number | bigint;
+    gid: number | bigint;
+};
+export type TempWorkspaceOwnership = "user" | "root" | "unmapped" | "foreign";
+export declare function classifyTempWorkspaceOwner(stat: DirectoryOwner, uid: number): TempWorkspaceOwnership;
+export declare function warnUnmappedTempWorkspaceAncestor(): void;
+export {};

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-ownership.js

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+let warned = false;
+function overflowId(kind) {
+    try {
+        const value = Number(fs.readFileSync(`/proc/sys/kernel/overflow${kind}`, "utf8").trim());
+        if (Number.isSafeInteger(value) && value >= 0 && value < 0xffffffff)
+            return value;
+    }
+    catch {
+        // Linux defaults when the sysctl files are unavailable in the service mount.
+    }
+    return 65534;
+}
+function unmappedId(kind) {
+    const mappings = fs.readFileSync(`/proc/self/${kind}_map`, "utf8").trim()
+        .split("\n").map((line) => line.trim().split(/\s+/).map(Number));
+    if (!mappings.every((row) => row.length === 3 && row.every((id) => Number.isSafeInteger(id) && id >= 0 && id <= 0xffffffff) && row[2] > 0))
+        return null;
+    if (mappings.length === 1 && mappings[0][0] === 0 &&
+        mappings[0][1] === 0 && mappings[0][2] === 0xffffffff)
+        return null;
+    const id = overflowId(kind);
+    // Recheck every admission: an explicitly mapped overflow-number ID is real ownership.
+    return mappings.some(([start, , count]) => id >= start && id < start + count) ? null : id;
+}
+export function classifyTempWorkspaceOwner(stat, uid) {
+    if (stat.uid === uid || stat.uid === BigInt(uid))
+        return "user";
+    if (stat.uid === 0 || stat.uid === 0n)
+        return "root";
+    if (process.platform !== "linux")
+        return "foreign";
+    try {
+        const overflowUid = unmappedId("uid");
+        const overflowGid = unmappedId("gid");
+        return overflowUid !== null && overflowGid !== null &&
+            (stat.uid === overflowUid || stat.uid === BigInt(overflowUid)) &&
+            (stat.gid === overflowGid || stat.gid === BigInt(overflowGid))
+            ? "unmapped"
+            : "foreign";
+    }
+    catch {
+        // Unavailable mapping evidence cannot authorize the namespace exception.
+        return "foreign";
+    }
+}
+export function warnUnmappedTempWorkspaceAncestor() {
+    if (warned)
+        return;
+    warned = true;
+    process.emitWarning("Temp workspace ancestor ownership is unverifiable in this user namespace; trusting the host directory hierarchy while enforcing ancestor modes and a process-owned private root.", { code: "FS_SAFE_UNMAPPED_TEMP_ANCESTOR", type: "FsSafeWarning" });
+}

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-types.d.ts

@@ -0,0 +1,39 @@
+import type { FileStore, FileStoreSync } from "./file-store.js";
+import type { TempPathIdentityReceipt } from "./temp-cleanup.js";
+import type { TempWorkspaceCleanupResult, TempWorkspaceCleanupSafety } from "./temp-workspace-owner.js";
+export type TempWorkspaceOptions = {
+    rootDir: string;
+    prefix: string;
+    dirMode?: number;
+    mode?: number;
+    cleanupSafety?: TempWorkspaceCleanupSafety;
+};
+export type TempWorkspace = {
+    dir: string;
+    identity: TempPathIdentityReceipt;
+    store: FileStore;
+    path(fileName: string): string;
+    write(fileName: string, data: string | Uint8Array): Promise<string>;
+    writeText(fileName: string, data: string): Promise<string>;
+    writeJson(fileName: string, data: unknown, options?: {
+        trailingNewline?: boolean;
+    }): Promise<string>;
+    copyIn(fileName: string, sourcePath: string): Promise<string>;
+    read(fileName: string): Promise<Buffer>;
+    cleanup(): Promise<TempWorkspaceCleanupResult>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type TempWorkspaceSync = {
+    dir: string;
+    identity: TempPathIdentityReceipt;
+    store: FileStoreSync;
+    path(fileName: string): string;
+    write(fileName: string, data: string | Uint8Array): string;
+    writeText(fileName: string, data: string): string;
+    writeJson(fileName: string, data: unknown, options?: {
+        trailingNewline?: boolean;
+    }): string;
+    read(fileName: string): Buffer;
+    cleanup(): TempWorkspaceCleanupResult;
+    [Symbol.dispose](): void;
+};

package/node_modules/@openclaw/fs-safe/dist/temp-workspace-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, type TempWorkspaceCleanupResult, type TempWorkspaceCleanupSafety, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export type { TempPathIdentityReceipt } from "./temp-cleanup.js";
+export { resolveSecureTempRoot, type ResolveSecureTempRootOptions, type SecureTempRootDescriptorAdapter, } from "./secure-temp-dir.js";

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

@@ -0,0 +1,2 @@
+export { tempWorkspace, tempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export { resolveSecureTempRoot, } from "./secure-temp-dir.js";

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

@@ -0,0 +1,35 @@
+import type { FileHandle } from "node:fs/promises";
+import type { FileIdentityStat } from "./file-identity.js";
+export type FsSafeTestHooks = {
+    beforeWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchBackendOverflow?: (root: string, phase: "received" | "reconciled") => void;
+    afterWatchBackendCreated?: (root: string, emit: (batch: import("./watch-native.js").NativeWatchBatch) => void, nativeEvent?: (path: string, flags: number) => void) => void;
+    afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+    beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+    afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
+    beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
+    beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
+    beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
+    beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
+    beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+    beforePinnedWriteParentAdmission?: (targetPath: string) => Promise<void> | void;
+    beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
+    beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
+    beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
+    afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
+    beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+    beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
+    beforeRegularFileAppendOpen?: (filePath: string) => Promise<void> | void;
+    beforeRegularFileAppendOpenSync?: (filePath: string) => void;
+    beforeTempWorkspaceNativeRemoval?: (quarantinePath: string) => Promise<void> | void;
+    beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
+    beforeTrashMove?: (targetPath: string, destPath: string) => void;
+    afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: NonNullable<FsSafeTestHooks["afterPublishTargetCreated"]>;
+};
+export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
+export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;

package/node_modules/@openclaw/fs-safe/dist/test-hooks.js

@@ -0,0 +1,13 @@
+let fsSafeTestHooks;
+function allowFsSafeTestHooks() {
+    return process.env.NODE_ENV === "test" || process.env.VITEST === "true";
+}
+export function getFsSafeTestHooks() {
+    return fsSafeTestHooks;
+}
+export function __setFsSafeTestHooksForTest(hooks) {
+    if (hooks && !allowFsSafeTestHooks()) {
+        throw new Error("__setFsSafeTestHooksForTest is only available in tests");
+    }
+    fsSafeTestHooks = hooks;
+}

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

@@ -0,0 +1,14 @@
+import { type ReplaceFileAtomicOptions } from "./replace-file.js";
+export type WriteTextAtomicOptions = Pick<ReplaceFileAtomicOptions, "beforeRename" | "tempPrefix"> & {
+    mode?: number;
+    dirMode?: number;
+    trailingNewline?: boolean;
+    /**
+     * When false, skip the temp-file and parent-directory fsync calls while
+     * preserving the temp-file replace/rename behavior.
+     *
+     * Defaults to true.
+     */
+    durable?: boolean;
+};
+export declare function writeTextAtomic(filePath: string, content: string, options?: WriteTextAtomicOptions): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/text-atomic.js

@@ -0,0 +1,18 @@
+import { replaceFileAtomic } from "./replace-file.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
+export async function writeTextAtomic(filePath, content, options) {
+    const admittedPath = admitStandalonePublicationPath(filePath);
+    const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
+    const durable = options?.durable ?? true;
+    await replaceFileAtomic({
+        filePath: admittedPath,
+        content: payload,
+        mode: options?.mode ?? 0o600,
+        dirMode: options?.dirMode ?? (0o777 & ~process.umask()),
+        copyFallbackOnPermissionError: true,
+        syncTempFile: durable,
+        syncParentDir: durable,
+        beforeRename: options?.beforeRename,
+        tempPrefix: options?.tempPrefix,
+    });
+}

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

@@ -0,0 +1,8 @@
+export declare function scheduleTimeout(callback: () => void, ms: number): () => void;
+export declare function sleep(ms: number): Promise<void>;
+export declare function sleepSync(ms: number): void;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, labelOrOptions?: string | {
+    label?: string;
+    message?: string;
+    createError?: () => Error;
+}): Promise<T>;

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

@@ -0,0 +1,59 @@
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+export function scheduleTimeout(callback, ms) {
+    let timer;
+    if (Number.isFinite(ms) && ms > MAX_TIMER_DELAY_MS) {
+        const startedAt = performance.now();
+        const tick = () => {
+            const remaining = ms - (performance.now() - startedAt);
+            if (remaining <= 0)
+                callback();
+            else
+                timer = setTimeout(tick, Math.min(remaining, MAX_TIMER_DELAY_MS));
+        };
+        // Node clamps overflowing delays to 1 ms. Rearm bounded timers against a
+        // monotonic clock so clock changes and event-loop stalls cannot shorten them.
+        timer = setTimeout(tick, MAX_TIMER_DELAY_MS);
+    }
+    else {
+        timer = setTimeout(callback, ms);
+    }
+    return () => clearTimeout(timer);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => { scheduleTimeout(resolve, ms); });
+}
+export function sleepSync(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export async function withTimeout(promise, timeoutMs, labelOrOptions = {
+    message: "timeout",
+}) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return await promise;
+    }
+    const options = typeof labelOrOptions === "string" ? { label: labelOrOptions } : labelOrOptions;
+    const createError = options.createError ??
+        (() => new Error(options.message ?? `${options.label ?? "operation"} timed out after ${timeoutMs}ms`));
+    let cancelTimeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                cancelTimeout = scheduleTimeout(() => {
+                    try {
+                        reject(createError());
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        cancelTimeout?.();
+    }
+}

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

@@ -0,0 +1,4 @@
+export type MovePathToTrashOptions = {
+    allowedRoots?: Iterable<string>;
+};
+export declare function movePathToTrash(targetPath: string, options?: MovePathToTrashOptions): Promise<string>;