@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/directory-mode-node.js

@@ -0,0 +1,209 @@
+import fsSync, { constants } from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export function nodeDarwinDirectoryMetadataFlags() {
+    if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {
+        throw new FsSafeError("helper-unavailable", "Darwin directory metadata descriptors are unavailable");
+    }
+    // Darwin SDK O_EVTONLY; Node omits this flag from its exported constants.
+    return 0x8000 | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+}
+export function nodeDirectorySearchOnlyFlags() {
+    if (process.arch !== "x64" && process.arch !== "arm64")
+        return undefined;
+    // Darwin SDK O_SEARCH = O_EXEC (0x40000000) | O_DIRECTORY, on x64/arm64.
+    if (process.platform === "darwin")
+        return { flags: 0x40000000, proc: false };
+    // Linux x86-64/aarch64 UAPI O_PATH = 010000000. Not a usable fchmod fd.
+    if (process.platform === "linux")
+        return { flags: 0x200000, proc: true };
+    return undefined;
+}
+/** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
+export async function pinNodeDirectoryForMode(dirPath, options = {}) {
+    const { ownerUid } = options;
+    const assertOwner = (stat) => {
+        if (ownerUid !== undefined && stat.uid !== BigInt(ownerUid)) {
+            throw new FsSafeError("not-owned", "directory mode target must retain its expected owner");
+        }
+    };
+    const expected = await inspectDirectoryIdentity(dirPath, options.expectedIdentity);
+    assertOwner(expected);
+    if (process.platform === "win32") {
+        // POSIX mode enforcement is unsupported; retain strict path identity checks.
+        return ownDirectoryMode({
+            inspect: async () => { assertOwner(await inspectDirectoryIdentity(dirPath, expected)); return 0; },
+            chmod: async () => undefined, close: async () => undefined, ignoreChmodError: true,
+        });
+    }
+    if ([constants.O_DIRECTORY, constants.O_NOFOLLOW, constants.O_NONBLOCK, constants.O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    const flags = constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let proc = false;
+    const handle = await fs.open(dirPath, constants.O_RDONLY | flags).catch(async (error) => {
+        if (error.code !== "EACCES")
+            throw error;
+        const route = nodeDirectorySearchOnlyFlags();
+        if (!route)
+            throw error;
+        proc = route.proc;
+        return await fs.open(dirPath, route.flags | flags);
+    });
+    try {
+        const inspect = async () => {
+            const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+            assertOwnedDirectory(expected, opened);
+            assertOwner(opened);
+            await inspectDirectoryIdentity(dirPath, expected);
+            return Number(opened.mode & 4095n);
+        };
+        const procPath = `/proc/self/fd/${handle.fd}`;
+        const assertProcAuthority = async () => {
+            // Authenticate the fd namespace, not the followed target's filesystem.
+            // This trusts host mount-namespace integrity, not privileged mount replacement.
+            const namespace = await fs.statfs("/proc/self/fd", { bigint: true });
+            if (namespace.type !== 0x9fa0n) {
+                throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
+            }
+            const opened = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), expected);
+            const followed = await inspectFileIdentity(() => fsSync.statSync(procPath, { bigint: true }), expected);
+            assertOwnedDirectory(opened, followed);
+            assertOwner(opened);
+            assertOwner(followed);
+        };
+        const owner = ownDirectoryMode({
+            inspect,
+            prepareChmod: proc ? assertProcAuthority : undefined,
+            verifyChmod: proc ? assertProcAuthority : undefined,
+            async chmod(mode) {
+                if (proc) {
+                    await fs.chmod(procPath, mode);
+                }
+                else {
+                    await handle.chmod(mode);
+                }
+            },
+            close: () => handle.close(),
+        });
+        await owner.verify();
+        return owner;
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
+        throw error;
+    }
+}
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export function pinNodeDirectoryForModeSync(dirPath, options = {}) {
+    const expected = inspectDirectoryIdentitySync(dirPath, options.expectedIdentity);
+    const assertOwner = (stat) => {
+        if (options.ownerUid !== undefined && stat.uid !== BigInt(options.ownerUid)) {
+            throw new FsSafeError("not-owned", "directory mode target must retain its expected owner");
+        }
+    };
+    assertOwner(expected);
+    if (process.platform === "win32") {
+        return {
+            apply: (_mode, check) => {
+                check?.();
+                assertOwner(inspectDirectoryIdentitySync(dirPath, expected));
+                check?.();
+            },
+            close: () => undefined,
+        };
+    }
+    if ([constants.O_DIRECTORY, constants.O_NOFOLLOW, constants.O_NONBLOCK, constants.O_RDONLY]
+        .some((flag) => typeof flag !== "number")) {
+        throw new FsSafeError("helper-unavailable", "no-follow directory mode descriptors are unavailable");
+    }
+    const flags = constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let fd;
+    let proc = false;
+    try {
+        fd = fsSync.openSync(dirPath, constants.O_RDONLY | flags);
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const route = nodeDirectorySearchOnlyFlags();
+        if (!route)
+            throw error;
+        proc = route.proc;
+        fd = fsSync.openSync(dirPath, route.flags | flags);
+    }
+    let closed = false;
+    const inspect = () => {
+        if (closed)
+            throw new FsSafeError("path-mismatch", "directory mode descriptor is closed");
+        const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        assertOwnedDirectory(expected, stat);
+        assertOwner(stat);
+        inspectDirectoryIdentitySync(dirPath, expected);
+        return Number(stat.mode & 4095n);
+    };
+    const procPath = `/proc/self/fd/${fd}`;
+    const assertProcAuthority = () => {
+        if (fsSync.statfsSync("/proc/self/fd", { bigint: true }).type !== 0x9fa0n) {
+            throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
+        }
+        const opened = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+        const followed = inspectFileIdentitySync(() => fsSync.statSync(procPath, { bigint: true }), expected);
+        assertOwnedDirectory(opened, followed);
+        assertOwner(opened);
+        assertOwner(followed);
+    };
+    try {
+        inspect();
+        return {
+            apply: (mode, check) => {
+                mode &= 0o7777;
+                check?.();
+                const currentMode = inspect();
+                check?.();
+                if (currentMode !== mode) {
+                    if (proc)
+                        assertProcAuthority();
+                    check?.();
+                    inspect();
+                    if (proc)
+                        fsSync.chmodSync(procPath, mode);
+                    else
+                        fsSync.fchmodSync(fd, mode);
+                    if (proc)
+                        assertProcAuthority();
+                }
+                const finalMode = inspect();
+                check?.();
+                if (finalMode !== mode) {
+                    throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                fsSync.closeSync(fd);
+            },
+        };
+    }
+    catch (error) {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/directory-mode-owner.d.ts

@@ -0,0 +1,20 @@
+import type { BigIntStats, Stats } from "node:fs";
+export type DirectoryModeChecks = {
+    check?: () => void;
+    beforeChmod?: () => Promise<void>;
+};
+export type DirectoryModeOwner = {
+    verify(check?: () => void): Promise<void>;
+    apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
+    close(): Promise<void>;
+};
+export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actual: Stats | BigIntStats): void;
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export declare function ownDirectoryMode(params: {
+    inspect: () => Promise<number>;
+    chmod: (mode: number) => Promise<void>;
+    prepareChmod?: () => Promise<void>;
+    verifyChmod?: () => Promise<void>;
+    close: () => Promise<void>;
+    ignoreChmodError?: boolean;
+}): DirectoryModeOwner;

package/node_modules/@openclaw/fs-safe/dist/directory-mode-owner.js

@@ -0,0 +1,78 @@
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function assertOwnedDirectory(expected, actual) {
+    if (actual.isSymbolicLink() || !actual.isDirectory()) {
+        throw new FsSafeError("not-file", "directory mode target must be a real directory");
+    }
+    if (!sameFileIdentityForCleanup(expected, actual)) {
+        throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+    }
+}
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export function ownDirectoryMode(params) {
+    let pending = Promise.resolve();
+    let closing;
+    const enqueue = (run) => {
+        if (closing)
+            return Promise.reject(new FsSafeError("path-mismatch", "directory mode owner is closed"));
+        const operation = pending.then(run);
+        pending = operation.catch(() => undefined);
+        return operation;
+    };
+    return {
+        verify: (check) => enqueue(async () => {
+            check?.();
+            await params.inspect();
+            check?.();
+        }),
+        apply: (mode, checks = {}) => enqueue(async () => {
+            // inspect() reports permission bits only; chmod ignores file-type bits,
+            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
+            mode &= 0o7777;
+            checks.check?.();
+            const currentMode = await params.inspect();
+            checks.check?.();
+            if (currentMode === mode && !checks.beforeChmod && !checks.check)
+                return;
+            if (currentMode !== mode) {
+                await params.prepareChmod?.();
+                checks.check?.();
+            }
+            await checks.beforeChmod?.();
+            checks.check?.();
+            // Hooks/ancestor checks can yield; recheck the original named association.
+            await params.inspect();
+            checks.check?.();
+            let dispatchDeadlineFailure;
+            if (currentMode !== mode) {
+                checks.check?.();
+                try {
+                    await params.chmod(mode);
+                }
+                catch (error) {
+                    if (!params.ignoreChmodError)
+                        throw error;
+                }
+                // Expiry cannot release the fd while post-dispatch verification is pending.
+                try {
+                    checks.check?.();
+                }
+                catch (error) {
+                    dispatchDeadlineFailure = { error };
+                }
+                await params.verifyChmod?.();
+            }
+            const finalMode = await params.inspect();
+            if (dispatchDeadlineFailure)
+                throw dispatchDeadlineFailure.error;
+            checks.check?.();
+            if (!params.ignoreChmodError && finalMode !== mode) {
+                throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+            }
+        }),
+        close() {
+            closing ??= pending.then(params.close);
+            return closing;
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+type ExactIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+declare const numericFields: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+declare const timeFields: readonly ["atime", "mtime", "ctime", "birthtime"];
+type DirectoryMetadata = Pick<Stats, typeof numericFields[number] | `${typeof timeFields[number]}Ms`>;
+type DirectoryProvenance = Readonly<{
+    identity: ExactIdentity;
+    metadata: Readonly<DirectoryMetadata>;
+}>;
+type DirectoryAuthority = DirectoryProvenance & Readonly<{
+    path: string;
+    realPath: string;
+}>;
+export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
+export declare function directoryReceiptAuthority(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryAuthority;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryReceipt;
+export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
+export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
+export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
+export {};

package/node_modules/@openclaw/fs-safe/dist/directory-receipt.js

@@ -0,0 +1,123 @@
+import fs, {} from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const numericFields = ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+const timeFields = ["atime", "mtime", "ctime", "birthtime"];
+// Live pins retain private authority. New admissions snapshot the supplied
+// fields and accept exact provenance only while its public identity is intact.
+const authorities = new WeakMap();
+const identities = new WeakMap();
+export function directoryReceiptIdentity(identity) {
+    if (!identity) {
+        throw new FsSafeError("path-mismatch", "directory receipt identity is missing");
+    }
+    const known = identities.get(identity);
+    const dev = identity.dev;
+    const ino = identity.ino;
+    if (known) {
+        const matches = (value, expected) => typeof value === "bigint" ? value === expected : value === Number(expected);
+        if (!matches(dev, known.identity.dev) || !matches(ino, known.identity.ino)) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity changed");
+        }
+        return known.identity;
+    }
+    const exact = (value) => {
+        if ((typeof value !== "bigint" && !Number.isSafeInteger(value)) ||
+            (process.platform === "win32" && (value === 0 || value === 0n))) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity could not be verified");
+        }
+        return BigInt(value);
+    };
+    return Object.freeze({ dev: exact(dev), ino: exact(ino) });
+}
+function snapshotDirectoryReceipt(receipt) {
+    const pathname = receipt?.path;
+    const realPath = receipt?.realPath;
+    const stat = receipt?.identity;
+    if (typeof pathname !== "string" || typeof realPath !== "string" || stat == null) {
+        throw new FsSafeError("path-mismatch", "directory receipt is incomplete");
+    }
+    assertNoWindowsPathAlias(pathname, "filesystem");
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    const identity = directoryReceiptIdentity(stat);
+    const known = authorities.get(receipt);
+    if (known && (pathname !== known.path || realPath !== known.realPath ||
+        identity.dev !== known.identity.dev || identity.ino !== known.identity.ino)) {
+        throw new FsSafeError("path-mismatch", "directory receipt changed before admission");
+    }
+    const metadata = known?.metadata ?? identities.get(stat)?.metadata ?? snapshotDirectoryMetadata(stat, identity);
+    return Object.freeze({ path: pathname, realPath, identity, metadata });
+}
+function snapshotDirectoryMetadata(stat, identity) {
+    const metadata = {};
+    for (const field of numericFields) {
+        metadata[field] = Number(field === "dev" || field === "ino" ? identity[field] : stat[field]);
+    }
+    for (const field of timeFields) {
+        if ("atimeNs" in stat) {
+            const nanoseconds = stat[`${field}Ns`];
+            const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+            metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+        }
+        else {
+            metadata[`${field}Ms`] = stat[`${field}Ms`];
+        }
+    }
+    return Object.freeze(metadata);
+}
+export function directoryReceiptAuthority(receipt) {
+    return authorities.get(receipt) ?? snapshotDirectoryReceipt(receipt);
+}
+function rememberReceipt(receipt, authority) {
+    authorities.set(receipt, authority);
+    identities.set(receipt.identity, authority);
+    return receipt;
+}
+export function ownDirectoryReceipt(receipt) {
+    return receiptFromAuthority(snapshotDirectoryReceipt(receipt));
+}
+export function copyRetainedDirectoryReceipt(receipt) {
+    const authority = directoryReceiptAuthority(receipt);
+    return receiptFromAuthority(authority);
+}
+function receiptFromAuthority(authority) {
+    return rememberReceipt({
+        path: authority.path,
+        realPath: authority.realPath,
+        identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
+    }, authority);
+}
+// The caller already admitted the exact observation and its paths.
+export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {
+    const identity = Object.freeze({ dev: exactStat.dev, ino: exactStat.ino });
+    return receiptFromAuthority(Object.freeze({
+        path: pathname,
+        realPath,
+        identity,
+        // Project metadata from the admitted observation, never a fresh pathname stat.
+        metadata: snapshotDirectoryMetadata(exactStat, identity),
+    }));
+}
+export function createDirectoryReceiptSync(directoryPath, label, canonicalize = realpathSync) {
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const pathname = resolvePathPreservingWindowsRoot(directoryPath);
+    assertNoWindowsPathAlias(pathname, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const exact = inspectDirectoryIdentitySync(pathname);
+    const operationPath = pathForWindowsFilesystem(pathname);
+    const realPath = canonicalize(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    return createDirectoryReceiptFromIdentity(pathname, realPath, exact);
+}
+export function assertDirectoryReceiptCurrentSync(receipt, label, canonicalize = realpathSync) {
+    const authority = directoryReceiptAuthority(receipt);
+    assertNoWindowsPathAlias(authority.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    assertNoWindowsPathAlias(authority.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    inspectDirectoryIdentitySync(authority.path, authority.identity);
+    const realPath = canonicalize(pathForWindowsFilesystem(authority.path));
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    if (realPath !== authority.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${authority.path}`);
+    }
+}

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

@@ -0,0 +1,4 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, } from "./publish-file.js";
+export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
+export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";

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

@@ -0,0 +1,3 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";
+export { isHardlinkFallbackError, publishFileExclusive, } from "./publish-file.js";
+export { sha256File, sha256FileSync, } from "./file-hash.js";

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

@@ -0,0 +1 @@
+export declare function resolveEffectiveUid(): number;

package/node_modules/@openclaw/fs-safe/dist/effective-uid.js

@@ -0,0 +1,25 @@
+function isValidUid(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function unavailable(cause) {
+    return new Error("Effective user identity is unavailable.", {
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+export function resolveEffectiveUid() {
+    const provider = process.geteuid;
+    if (typeof provider !== "function") {
+        throw unavailable();
+    }
+    let uid;
+    try {
+        uid = provider.call(process);
+    }
+    catch (cause) {
+        throw unavailable(cause);
+    }
+    if (!isValidUid(uid)) {
+        throw unavailable();
+    }
+    return uid;
+}

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

@@ -0,0 +1,2 @@
+export declare function formatErrorDetail(value: string): string;
+export declare function shortPath(value: string): string;

package/node_modules/@openclaw/fs-safe/dist/error-detail.js

@@ -0,0 +1,13 @@
+import os from "node:os";
+import path from "node:path";
+const UNSAFE_ERROR_DETAIL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu;
+export function formatErrorDetail(value) {
+    return value.replace(UNSAFE_ERROR_DETAIL_CHARACTERS, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function shortPath(value) {
+    const home = os.homedir();
+    const prefix = home.endsWith(path.sep) ? home : `${home}${path.sep}`;
+    const shortened = value === home ? "~"
+        : value.startsWith(prefix) ? `~${path.sep}${value.slice(prefix.length)}` : value;
+    return formatErrorDetail(shortened);
+}

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

@@ -0,0 +1,13 @@
+export type FsSafeErrorCode = "already-exists" | "denied-path" | "device-path" | "hardlink" | "helper-failed" | "helper-unavailable" | "invalid-path" | "insecure-permissions" | "not-empty" | "not-file" | "not-found" | "not-owned" | "not-removable" | "outside-workspace" | "path-alias" | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists" | "store-reentrant-update" | "symlink" | "timeout" | "too-large" | "unsupported-platform";
+export type FsSafeErrorCategory = "policy" | "operational";
+export type FsSafeErrorDetails = Readonly<Record<string, unknown>>;
+export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;
+export declare class FsSafeError extends Error {
+    readonly code: FsSafeErrorCode;
+    readonly category: FsSafeErrorCategory;
+    readonly details?: FsSafeErrorDetails;
+    constructor(code: FsSafeErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: FsSafeErrorDetails;
+    });
+}

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

@@ -0,0 +1,26 @@
+const OPERATIONAL_CODES = new Set([
+    "helper-failed",
+    "helper-unavailable",
+    "not-empty",
+    "not-found",
+    "not-removable",
+    "permission-unverified",
+    "read-failed",
+    "timeout",
+    "unsupported-platform",
+]);
+export function categorizeFsSafeError(code) {
+    return OPERATIONAL_CODES.has(code) ? "operational" : "policy";
+}
+export class FsSafeError extends Error {
+    code;
+    category;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.name = "FsSafeError";
+        this.code = code;
+        this.category = categorizeFsSafeError(code);
+        this.details = options.details;
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export declare function readErrorCode(error: unknown): unknown;
+export declare function hasErrorCode(error: unknown, expected: string): boolean;
+type OwnedPathCleanupStatus = "removed" | "name-absent" | "preserved";
+export declare function removeOwnedPath(params: {
+    fsModule: Pick<typeof fs, "lstat" | "unlink">;
+    pathname: string;
+    identity?: BigIntStats;
+}): Promise<OwnedPathCleanupStatus>;
+export declare function cleanupPinnedFilePath(params: {
+    pathname: string;
+    handle: Pick<FileHandle, "fd">;
+    identity?: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    throwOnCleanupError?: boolean;
+}): Promise<OwnedPathCleanupStatus>;
+export {};

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

@@ -0,0 +1,81 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function readErrorCode(error) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+        return undefined;
+    }
+    try {
+        return Reflect.get(error, "code");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasErrorCode(error, expected) {
+    return readErrorCode(error) === expected;
+}
+export async function removeOwnedPath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const current = params.fsModule === fs
+            ? syncFs.lstatSync(params.pathname, { bigint: true })
+            : await params.fsModule.lstat(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return "preserved";
+        }
+        await params.fsModule.unlink(params.pathname);
+        return "removed";
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return "name-absent";
+        throw error;
+    }
+}
+// Borrowed handle: the caller retains it until guarded cleanup finishes.
+export async function cleanupPinnedFilePath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const guard = params.parentGuard;
+        if ([guard.stat.dev, guard.stat.ino].some((value) => typeof value === "number" && !Number.isSafeInteger(value)))
+            return "preserved";
+        await assertAsyncDirectoryGuard(guard);
+        const parent = syncFs.lstatSync(guard.dir, { bigint: true });
+        if (parent.isSymbolicLink() || !parent.isDirectory() ||
+            !sameFileIdentityForCleanup(parent, guard.stat))
+            return "preserved";
+        const opened = syncFs.fstatSync(params.handle.fd, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, params.identity))
+            return "preserved";
+    }
+    catch (error) {
+        // Unverifiable authority must preserve the path and the original write failure.
+        if (params.throwOnCleanupError &&
+            !(error instanceof FsSafeError && error.category === "policy") &&
+            !hasErrorCode(error, "ENOENT") && !hasErrorCode(error, "ENOTDIR") &&
+            !hasErrorCode(error, "ELOOP"))
+            throw error;
+        return "preserved";
+    }
+    try {
+        return await removeOwnedPath({
+            fsModule: fs,
+            pathname: params.pathname,
+            identity: params.identity,
+        });
+    }
+    catch (error) {
+        if (params.throwOnCleanupError)
+            throw error;
+        return "preserved";
+    }
+}

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

@@ -0,0 +1,5 @@
+export type SameFileContentsOptions = {
+    maxBytes?: number;
+};
+/** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
+export declare function sameFileContentsSync(leftFd: number, rightFd: number, options?: SameFileContentsOptions): boolean;