@openclaw/signal 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,46 @@
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { isFileObservationFailure, recordFileObservationFailure } from "./file-observation.js";
+export function recordFileOpenFailure(error, filePath) {
+    recordFileObservationFailure(error, `open:${filePath}`);
+    throw error;
+}
+export function recordExclusiveCreateFailure(error, filePath) {
+    recordFileObservationFailure(error, `exclusive-create:${filePath}`);
+    throw error;
+}
+export function openedPathResolutionError(error = new FsSafeError("path-mismatch", "unable to resolve opened file path")) {
+    recordFileObservationFailure(error, "resolution");
+    return error;
+}
+export async function recordPreOpenFileChange(error, handle, filePath, before, opened) {
+    if (!isFileObservationFailure(error, "identity") || !before?.isFile() || !opened?.isFile() ||
+        ![0n, 1n].includes(before.nlink) || ![0n, 1n].includes(opened.nlink))
+        return;
+    try {
+        await inspectFileIdentity(async () => before);
+        const current = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), opened);
+        if (current.isFile() && [0n, 1n].includes(current.nlink) &&
+            (before.dev !== current.dev || before.ino !== current.ino)) {
+            // A stale pathname sample is not proof that its former inode was unlinked.
+            recordFileObservationFailure(error, `changed:${filePath}`);
+        }
+    }
+    catch {
+        // Unknown, changed, or closed descriptor evidence never permits a discard.
+    }
+}
+export async function recordOpenedFileFailure(error, handle, filePath, identity) {
+    if ((!isFileObservationFailure(error, "resolution") && !isFileObservationFailure(error, "identity")) ||
+        !identity.isFile() || identity.nlink > 1n)
+        return;
+    try {
+        const current = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+        if (current.isFile() && current.nlink === 0n)
+            recordFileObservationFailure(error, `unlinked:${filePath}`);
+    }
+    catch {
+        // A closed, changed, or unknown descriptor provides no retry evidence.
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type FileIdentityStat } from "./file-identity.js";
+export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: {
+    dev: bigint;
+    ino: bigint;
+}, ioPath: string): Promise<{
+    realPath: string;
+    stat: BigIntStats;
+}>;
+export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: FileIdentityStat, ioPath: string): Promise<{
+    realPath: string;
+    stat: Stats | BigIntStats;
+}>;

package/node_modules/@openclaw/fs-safe/dist/opened-realpath.js

@@ -0,0 +1,102 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { openedPathResolutionError } from "./opened-file-failure.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
+    const fd = handle.fd;
+    const identity = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
+    const resolved = await resolveOpenedFileRealPathForFd(fd, identity, ioPath);
+    let first = resolved.stat;
+    inspectFileIdentitySync(() => {
+        const current = first ?? fsSync.statSync(resolved.realPath, { bigint: true });
+        first = undefined;
+        return current;
+    }, identity);
+    return resolved.realPath;
+}
+export async function resolveOpenedFileRealPathForFd(fd, handleStat, ioPath) {
+    const statOptions = typeof handleStat.dev === "bigint" || typeof handleStat.ino === "bigint"
+        ? { bigint: true } : undefined;
+    const fdCandidates = process.platform === "linux"
+        ? [`/proc/self/fd/${fd}`, `/dev/fd/${fd}`]
+        : [];
+    for (const fdPath of fdCandidates) {
+        try {
+            const fdRealPath = realpathSync.native(fdPath);
+            const fdRealStat = statOptions ? fsSync.statSync(fdRealPath, statOptions) : fsSync.statSync(fdRealPath);
+            if (sameFileIdentity(handleStat, fdRealStat)) {
+                return { realPath: fdRealPath, stat: fdRealStat };
+            }
+        }
+        catch {
+            // try next fd path
+        }
+    }
+    try {
+        const ioRealPath = realpathSync.native(ioPath);
+        const ioRealStat = statOptions ? fsSync.statSync(ioRealPath, statOptions) : fsSync.statSync(ioRealPath);
+        if (sameFileIdentity(handleStat, ioRealStat)) {
+            return { realPath: ioRealPath, stat: ioRealStat };
+        }
+    }
+    catch (err) {
+        if (!isNotFoundPathError(err)) {
+            // Windows can fail here on a deleted-but-open file. Brand only this
+            // resolver operation; the caller must still prove unlink on the same fd.
+            if (process.platform === "win32" && err instanceof Error &&
+                ["EPERM", "EBADF"].includes(err.code ?? "")) {
+                throw openedPathResolutionError(err);
+            }
+            throw err;
+        }
+    }
+    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions);
+    if (parentResolved) {
+        return parentResolved;
+    }
+    throw openedPathResolutionError();
+}
+async function resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions) {
+    let parentReal;
+    try {
+        parentReal = realpathSync.native(path.dirname(ioPath));
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return null;
+        }
+        throw err;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(parentReal);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return null;
+        }
+        throw err;
+    }
+    for (const entry of entries.toSorted()) {
+        const candidatePath = path.join(parentReal, entry);
+        try {
+            const candidateStat = statOptions ? fsSync.lstatSync(candidatePath, statOptions) : fsSync.lstatSync(candidatePath);
+            if (candidateStat.isFile() && sameFileIdentity(handleStat, candidateStat)) {
+                const realPath = realpathSync.native(candidatePath);
+                const stat = statOptions ? fsSync.statSync(realPath, statOptions) : fsSync.statSync(realPath);
+                if (sameFileIdentity(handleStat, stat))
+                    return { realPath, stat };
+            }
+        }
+        catch (err) {
+            if (!isNotFoundPathError(err)) {
+                throw err;
+            }
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,16 @@
+export type ExternalFileWriteOptions<T = void> = {
+    rootDir: string;
+    path: string;
+    write: (filePath: string) => Promise<T>;
+    maxBytes?: number;
+    mode?: number;
+    staging?: "workspace" | "sibling";
+    /** Isolate sibling producers; workspace staging is already private. */
+    producerIsolation?: "private-directory";
+    fallbackFileName?: string;
+};
+export type ExternalFileWriteResult<T = void> = {
+    path: string;
+    result: T;
+};
+export declare function writeExternalFileWithinRoot<T = void>(options: ExternalFileWriteOptions<T>): Promise<ExternalFileWriteResult<T>>;

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

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
+function tempFileNameForTarget(targetPath, fallbackFileName) {
+    const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
+    return sanitizeUntrustedFileName(path.basename(targetPath), fallback);
+}
+function sanitizedTargetPath(targetPath, fallbackFileName) {
+    const basename = path.basename(targetPath);
+    if (!NON_PORTABLE_FILE_NAME_CHARACTERS.test(basename)) {
+        return targetPath;
+    }
+    const sanitized = tempFileNameForTarget(targetPath, fallbackFileName);
+    return sanitized === basename ? targetPath : path.join(path.dirname(targetPath), sanitized);
+}
+function ensureTrailingSep(value) {
+    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+}
+function toRootPathInput(params) {
+    if (!path.isAbsolute(params.targetPath)) {
+        return params.targetPath;
+    }
+    const absoluteTarget = path.resolve(params.targetPath);
+    const rootDir = path.resolve(params.rootDir);
+    if (isPathInside(ensureTrailingSep(rootDir), absoluteTarget)) {
+        return path.relative(rootDir, absoluteTarget);
+    }
+    if (isPathInside(ensureTrailingSep(params.rootReal), absoluteTarget)) {
+        return path.relative(params.rootReal, absoluteTarget);
+    }
+    return params.targetPath;
+}
+function assertFileTargetPath(targetPath) {
+    const basename = path.basename(targetPath);
+    if (!targetPath ||
+        targetPath === "." ||
+        targetPath.endsWith("/") ||
+        targetPath.endsWith("\\") ||
+        !basename ||
+        basename === "." ||
+        basename === "..") {
+        throw new FsSafeError("invalid-path", "target path must name a file");
+    }
+}
+export async function writeExternalFileWithinRoot(options) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "output root uses a Windows filesystem namespace alias");
+    const requestedTargetPath = options.path;
+    assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const write = options.write;
+    const mode = options.mode;
+    const staging = options.staging;
+    const fallbackFileName = options.fallbackFileName;
+    const targetRoot = await root(rootDir);
+    if (requestedTargetPath.length === 0) {
+        throw new FsSafeError("invalid-path", "target path is required");
+    }
+    assertFileTargetPath(requestedTargetPath);
+    const rawTargetPath = toRootPathInput({
+        rootDir: targetRoot.rootDir,
+        rootReal: targetRoot.rootReal,
+        targetPath: requestedTargetPath,
+    });
+    assertFileTargetPath(rawTargetPath);
+    const targetPath = sanitizedTargetPath(rawTargetPath, fallbackFileName);
+    assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const finalPath = await targetRoot.resolve(targetPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    if (staging === "sibling") {
+        const parentPath = path.dirname(targetPath);
+        if (parentPath !== ".") {
+            await targetRoot.mkdir(parentPath);
+        }
+        const siblingFinalPath = await targetRoot.resolve(targetPath);
+        const result = await writeExternalFileViaSibling({
+            finalPath: siblingFinalPath,
+            write,
+            producerIsolation,
+            fallbackFileName,
+            maxBytes,
+            mode,
+        });
+        return { path: siblingFinalPath, result };
+    }
+    const staged = await tempFile({
+        prefix: "fs-safe-output",
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
+    });
+    try {
+        const result = await Function.prototype.call.call(write, options, staged.path);
+        await targetRoot.copyIn(targetPath, staged.path, {
+            maxBytes,
+            mode,
+            mkdir: true,
+            sourceHardlinks: "reject",
+        });
+        return { path: finalPath, result };
+    }
+    finally {
+        await staged.cleanup();
+    }
+}
+function buildSiblingTempName(targetPath, fallbackFileName) {
+    const prefix = `.fs-safe-output-${process.pid}-${randomUUID()}-`;
+    const suffix = ".part";
+    const safeTail = fitFileNameToPortableComponent({
+        prefix,
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
+        suffix,
+    });
+    return `${prefix}${safeTail}${suffix}`;
+}
+async function writeExternalFileViaSibling(params) {
+    assertNoWindowsPathAlias(params.finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const finalPath = path.resolve(params.finalPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const { result } = await writeCallbackSibling({
+        tempDir: path.dirname(finalPath),
+        tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
+        write: params.write,
+        producerIsolation: params.producerIsolation,
+        resolveFinalPath: () => finalPath,
+        mode: params.mode,
+        maxBytes: params.maxBytes,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+    return result;
+}

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

@@ -0,0 +1,7 @@
+import type { FileHandle } from "node:fs/promises";
+export type OverwriteFileHandleOptions = {
+    /** Admit the whole write once, after rollback preparation and before any mutation. */
+    beforeWrite?: () => void;
+};
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export declare function overwriteFileHandle(handle: FileHandle, data: Uint8Array, options?: OverwriteFileHandleOptions): Promise<void>;

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

@@ -0,0 +1,46 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { readFileWindowFully } from "./positional-read.js";
+import { writeAllToFile } from "./write-file-handle.js";
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export async function overwriteFileHandle(handle, data, options = {}) {
+    // Snapshot caller-owned admission before the first await. Preserve the
+    // former method-call receiver while preventing a later getter mutation from
+    // replacing authority after rollback preparation.
+    const beforeWrite = options.beforeWrite;
+    const payload = data.subarray(0, data.byteLength);
+    const payloadBytes = payload.byteLength;
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "overwrite handle must be a regular file");
+    }
+    const originalSize = stat.size;
+    if (!Number.isSafeInteger(originalSize) || originalSize < 0) {
+        throw new RangeError("file size must be a non-negative safe integer");
+    }
+    const prefixBytes = Math.min(payloadBytes, originalSize);
+    const originalPrefix = Buffer.allocUnsafe(prefixBytes);
+    if (await readFileWindowFully(handle, originalPrefix, 0) !== prefixBytes) {
+        throw new FsSafeError("read-failed", "file ended before overwrite rollback preparation completed");
+    }
+    assertSynchronousCallbackResult(beforeWrite === undefined ? undefined : Reflect.apply(beforeWrite, options, []), "beforeWrite");
+    let prefixStarted = false;
+    try {
+        // Leave existing bytes intact until any additional storage has been written.
+        if (payloadBytes > originalSize) {
+            await writeAllToFile(handle, payload.subarray(originalSize), { position: originalSize });
+        }
+        prefixStarted = true;
+        await writeAllToFile(handle, payload.subarray(0, prefixBytes), { position: 0 });
+        if (payloadBytes < originalSize) {
+            await handle.truncate(payloadBytes);
+        }
+    }
+    catch (error) {
+        if (prefixStarted) {
+            await writeAllToFile(handle, originalPrefix, { position: 0 }).catch(() => undefined);
+        }
+        await handle.truncate(originalSize).catch(() => undefined);
+        throw error;
+    }
+}

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

@@ -0,0 +1,30 @@
+export type WindowsAceFlags = {
+    raw: number;
+    objectInherit: boolean;
+    containerInherit: boolean;
+    noPropagateInherit: boolean;
+    inheritOnly: boolean;
+    inherited: boolean;
+    successfulAccess: boolean;
+    failedAccess: boolean;
+};
+export type WindowsAccessControlEntry = {
+    sid: string;
+    mask: number;
+    aceType: "allow" | "deny";
+    flags: WindowsAceFlags;
+};
+export type OwnerAndDaclResult = {
+    status: "supported";
+    ownerSid: string;
+    currentUserSid: string;
+    daclPresent: boolean;
+    isLocal: boolean;
+    complete: boolean;
+    unsupportedAceTypes: number[];
+    aces: WindowsAccessControlEntry[];
+} | {
+    status: "unsupported-platform";
+    platform: NodeJS.Platform;
+};
+export declare function readOwnerAndDacl(targetPath: string): OwnerAndDaclResult;

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

@@ -0,0 +1,36 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { readWindowsSecurityFactsCommand } from "./windows-security-command.js";
+export function readOwnerAndDacl(targetPath) {
+    if (process.platform !== "win32") {
+        return { status: "unsupported-platform", platform: process.platform };
+    }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+    const native = getNativeBinding();
+    const inspect = native?.readOwnerAndDacl;
+    if (typeof inspect !== "function") {
+        if (getFsSafeNativeConfig().mode === "require") {
+            throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
+        }
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+    }
+    const facts = typeof inspect === "function" ? inspect.call(native, targetPath) : readWindowsSecurityFactsCommand(targetPath);
+    return {
+        status: "supported",
+        ownerSid: facts.ownerSid,
+        currentUserSid: facts.currentUserSid,
+        daclPresent: facts.daclPresent,
+        isLocal: facts.isLocal,
+        complete: facts.aceListComplete,
+        unsupportedAceTypes: [...facts.unsupportedAceTypes],
+        aces: facts.aces.map((entry) => ({
+            sid: entry.sid,
+            mask: entry.mask,
+            aceType: entry.aceType,
+            flags: { ...entry.flags },
+        })),
+    };
+}

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

@@ -0,0 +1,6 @@
+export type ProbePathCaseOptions = {
+    /** Allow an exclusively created empty probe when existing entries provide no answer. Defaults to true. */
+    allowTemporaryProbe?: boolean;
+};
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export declare function probePathCaseInsensitiveSync(targetPath: string, options?: ProbePathCaseOptions): boolean | undefined;

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

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function swapAsciiCase(value) {
+    return value.replace(/[A-Za-z]/g, character => {
+        const lower = character.toLowerCase();
+        return character === lower ? character.toUpperCase() : lower;
+    });
+}
+function probeEntry(directory, name, names) {
+    const alternate = swapAsciiCase(name);
+    if (alternate === name)
+        return undefined;
+    const bothListed = names.has(name) && names.has(alternate);
+    const originalPath = path.join(directory, name);
+    let original;
+    let observed;
+    try {
+        original = inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }));
+        try {
+            const other = inspectFileIdentitySync(() => fs.lstatSync(path.join(directory, alternate), { bigint: true }));
+            const sameIdentity = sameFileIdentityForCleanup(original, other);
+            if (sameIdentity || bothListed) {
+                // Matching inodes can belong to newly linked case-distinct names.
+                const currentNames = new Set(fs.readdirSync(directory));
+                const bothCurrent = currentNames.has(name) && currentNames.has(alternate);
+                if (bothListed && !bothCurrent)
+                    return undefined;
+                observed = sameIdentity && !bothCurrent;
+            }
+            else {
+                observed = false;
+            }
+        }
+        catch (error) {
+            if (bothListed || !isNotFoundPathError(error))
+                return undefined;
+            observed = false;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    // Disappearance during lookup is not evidence that case variants are distinct.
+    inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }), original);
+    return observed;
+}
+function probeTemporaryEntry(directory) {
+    const name = `.fs-safe-case-probe-${randomUUID()}`;
+    const owner = new SyncAtomicTempOwner(path.join(directory, name));
+    try {
+        owner.start();
+        owner.adopt(writeTempFileSync({
+            fsModule: fs,
+            tempPath: owner.pathname,
+            content: "",
+            mode: 0o600,
+            sync: false,
+            onIdentity: owner.onIdentity,
+        }));
+        owner.assertCurrent(fs);
+        const observed = probeEntry(directory, name, new Set(fs.readdirSync(directory)));
+        owner.assertCurrent(fs);
+        return observed;
+    }
+    finally {
+        // Failed cleanup invalidates the observation; the existing owner retains its exit retry.
+        owner.finish({ fsModule: fs, throwOnCleanupError: true });
+    }
+}
+function probeDirectory(directory, allowTemporaryProbe, preferredName) {
+    const canonical = realpathSync.native(directory);
+    const identity = inspectDirectoryIdentitySync(canonical);
+    const names = new Set(fs.readdirSync(canonical));
+    let observed = preferredName === undefined ? undefined : probeEntry(canonical, preferredName, names);
+    for (const name of names) {
+        if (observed !== undefined)
+            break;
+        observed = probeEntry(canonical, name, names);
+    }
+    if (observed === undefined && allowTemporaryProbe)
+        observed = probeTemporaryEntry(canonical);
+    assertDirectoryIdentitySync(canonical, identity);
+    return realpathSync.native(directory) === canonical ? observed : undefined;
+}
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export function probePathCaseInsensitiveSync(targetPath, options = {}) {
+    const resolved = path.resolve(targetPath);
+    const allowTemporaryProbe = options.allowTemporaryProbe !== false;
+    let targetExists = true;
+    try {
+        fs.lstatSync(resolved);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            return undefined;
+        targetExists = false;
+    }
+    if (targetExists) {
+        try {
+            return probeDirectory(path.dirname(resolved), allowTemporaryProbe, path.basename(resolved));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let directory = path.dirname(resolved);
+    for (;;) {
+        let exists = false;
+        try {
+            exists = fs.statSync(directory).isDirectory();
+        }
+        catch {
+            // A missing or unreadable component can still have a readable existing ancestor.
+        }
+        if (exists) {
+            try {
+                return probeDirectory(directory, allowTemporaryProbe);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}

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

@@ -0,0 +1,24 @@
+import { type RootPathAliasPolicy } from "./root-path.js";
+export type PathAliasPolicy = RootPathAliasPolicy;
+export declare const PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+export declare function assertNoPathAliasEscape(params: {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    policy?: PathAliasPolicy;
+}): Promise<void>;
+export declare function assertNoHardlinkedFinalPath(params: {
+    filePath: string;
+    root: string;
+    boundaryLabel: string;
+    allowFinalHardlinkForUnlink?: boolean;
+}): Promise<void>;

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

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
+import { isNotFoundPathError } from "./path.js";
+import { shortPath } from "./error-detail.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
+export async function assertNoPathAliasEscape(params) {
+    const resolved = await resolveRootPath({
+        absolutePath: params.absolutePath,
+        rootPath: params.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        policy: params.policy,
+    });
+    const allowFinalSymlink = params.policy?.allowFinalSymlinkForUnlink === true;
+    if (allowFinalSymlink && resolved.kind === "symlink") {
+        return;
+    }
+    await assertNoHardlinkedFinalPath({
+        filePath: resolved.canonicalPath,
+        root: resolved.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        allowFinalHardlinkForUnlink: params.policy?.allowFinalHardlinkForUnlink,
+    });
+}
+export async function assertNoHardlinkedFinalPath(params) {
+    if (params.allowFinalHardlinkForUnlink) {
+        return;
+    }
+    const filePath = params.filePath;
+    const root = params.root;
+    const boundaryLabel = params.boundaryLabel;
+    assertNoWindowsPathAlias(filePath);
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    if (!stat.isFile()) {
+        return;
+    }
+    if (stat.nlink > 1) {
+        throw new Error(`Hardlinked path is not allowed under ${boundaryLabel} (${shortPath(root)}): ${shortPath(filePath)}`);
+    }
+}

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

@@ -0,0 +1,6 @@
+export type ResolvedPathPrefix = {
+    readonly absolutePath: string;
+    readonly existingPath: string;
+    readonly unresolvedSegments: readonly string[];
+};
+export declare function resolvePathPrefixSync(input: string): ResolvedPathPrefix;