@openclaw/signal 2026.9.4 → 2026.9.6

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

@@ -0,0 +1,286 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureAbsoluteDirectory } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
+import { assertDirectoryReceiptCurrentSync, copyRetainedDirectoryReceipt, createDirectoryReceiptSync, directoryReceiptAuthority, directoryReceiptIdentity, ownDirectoryReceipt, } from "./directory-receipt.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+function directoryOpenFlags() {
+    if (process.platform === "win32") {
+        return "r";
+    }
+    return (fsSync.constants.O_RDONLY |
+        fsSync.constants.O_DIRECTORY |
+        fsSync.constants.O_NOFOLLOW |
+        fsSync.constants.O_NONBLOCK);
+}
+function isWindowsDirectorySyncUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return (code === "EACCES" ||
+        code === "EINVAL" ||
+        code === "EISDIR" ||
+        code === "ENOSYS" ||
+        code === "ENOTSUP" ||
+        code === "EPERM");
+}
+function isWindowsDirectoryOpenUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return code === "EINVAL" || code === "EISDIR" || code === "ENOSYS" || code === "ENOTSUP";
+}
+function unsupportedOutcome(error) {
+    const code = error.code;
+    return code ? { status: "unsupported", code } : { status: "unsupported" };
+}
+async function createDirectoryReceipt(directoryPath, label) {
+    return createDirectoryReceiptSync(directoryPath, label, realpathSync.native);
+}
+async function assertDirectoryReceiptCurrent(receipt, label) {
+    assertDirectoryReceiptCurrentSync(receipt, label, realpathSync.native);
+}
+function assertOpenDirectoryIdentity(descriptor, receipt, label) {
+    inspectFileIdentitySync(() => {
+        const opened = fsSync.fstatSync(descriptor, { bigint: true });
+        if (!opened.isDirectory()) {
+            throw new FsSafeError("not-file", `${label} must be a real directory: ${receipt.path}`);
+        }
+        return opened;
+    }, directoryReceiptAuthority(receipt).identity);
+}
+async function assertOpenDirectoryCurrent(handle, receipt, label) {
+    assertOpenDirectoryIdentity(handle.fd, receipt, label);
+    await assertDirectoryReceiptCurrent(receipt, label);
+}
+class PinnedDirectoryImpl {
+    receipt;
+    #authority;
+    #handle;
+    #label;
+    #closed = false;
+    constructor(handle, receipt, label) {
+        this.#handle = handle;
+        this.#authority = receipt;
+        this.receipt = copyRetainedDirectoryReceipt(receipt);
+        this.#label = label;
+    }
+    async assertCurrent() {
+        if (this.#closed) {
+            throw new FsSafeError("helper-failed", `${this.#label} pin is already closed`);
+        }
+        await assertOpenDirectoryCurrent(this.#handle, this.#authority, this.#label);
+    }
+    async sync() {
+        await this.assertCurrent();
+        try {
+            await this.#handle.sync();
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            await this.assertCurrent();
+            return unsupportedOutcome(error);
+        }
+        await this.assertCurrent();
+        return { status: "synced" };
+    }
+    async close() {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        await this.#handle.close();
+    }
+}
+export async function pinDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string"
+        ? await createDirectoryReceipt(directory, label)
+        : ownDirectoryReceipt(directory);
+    await assertDirectoryReceiptCurrent(receipt, label);
+    const handle = await fs.open(pathForWindowsFilesystem(receipt.path), directoryOpenFlags());
+    try {
+        await assertOpenDirectoryCurrent(handle, receipt, label);
+        return new PinnedDirectoryImpl(handle, receipt, label);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+export async function syncDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string"
+        ? await createDirectoryReceipt(directory, label)
+        : ownDirectoryReceipt(directory);
+    let pinned;
+    try {
+        pinned = await pinDirectory(receipt, { label });
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        await assertDirectoryReceiptCurrent(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        return await pinned.sync();
+    }
+    finally {
+        await pinned.close();
+    }
+}
+export function syncDirectorySync(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string"
+        ? createDirectoryReceiptSync(directory, label)
+        : ownDirectoryReceipt(directory);
+    assertDirectoryReceiptCurrentSync(receipt, label);
+    let descriptor;
+    try {
+        descriptor = fsSync.openSync(pathForWindowsFilesystem(receipt.path), directoryOpenFlags());
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        assertOpenDirectoryIdentity(descriptor, receipt, label);
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        try {
+            fsSync.fsyncSync(descriptor);
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            assertDirectoryReceiptCurrentSync(receipt, label);
+            return unsupportedOutcome(error);
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return { status: "synced" };
+    }
+    finally {
+        fsSync.closeSync(descriptor);
+    }
+}
+export async function syncDirectoryBestEffort(directoryPath) {
+    await syncDirectory(directoryPath).catch(() => undefined);
+}
+export function syncDirectoryBestEffortSync(directoryPath) {
+    try {
+        syncDirectorySync(directoryPath);
+    }
+    catch {
+        // Compatibility helper for operations whose primary write may remain usable.
+    }
+}
+async function findExistingAncestorReceipt(targetPath, label) {
+    assertNoWindowsPathAlias(targetPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    let currentPath = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(currentPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    while (true) {
+        try {
+            return await createDirectoryReceipt(currentPath, label);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            throw new FsSafeError("not-found", `${label} has no existing directory ancestor`);
+        }
+        currentPath = parentPath;
+    }
+}
+export async function ensureDurableDirectory(options) {
+    const label = options.label ?? "directory";
+    const requestedDirectoryPath = options.directoryPath;
+    assertNoWindowsPathAlias(requestedDirectoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const directoryPath = resolvePathPreservingWindowsRoot(requestedDirectoryPath);
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const expectedInput = options.expectedExistingIdentity;
+    const expectedIdentity = expectedInput && directoryReceiptIdentity(expectedInput);
+    const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
+    const targetExists = ancestorReceipt.path === directoryPath;
+    if (expectedIdentity && !targetExists) {
+        throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
+    }
+    if (expectedIdentity) {
+        inspectFileIdentitySync(() => directoryReceiptAuthority(ancestorReceipt).identity, expectedIdentity);
+    }
+    const ancestor = await pinDirectory(ancestorReceipt, { label });
+    const pinnedDirectories = [ancestor];
+    try {
+        await ancestor.assertCurrent();
+        if (!targetExists) {
+            const create = options.create;
+            if (create) {
+                await Reflect.apply(create, options, [directoryPath]);
+            }
+            else {
+                const created = await ensureAbsoluteDirectory(directoryPath, {
+                    mode: options.mode,
+                    scopeLabel: label,
+                });
+                if (!created.ok) {
+                    throw created.error;
+                }
+            }
+        }
+        await ancestor.assertCurrent();
+        let currentPath = ancestor.receipt.path;
+        for (const segment of path
+            .relative(ancestor.receipt.path, directoryPath)
+            .split(path.sep)
+            .filter(Boolean)) {
+            currentPath = path.join(currentPath, segment);
+            pinnedDirectories.push(await pinDirectory(currentPath, { label }));
+        }
+        let parentSync = { status: "not-needed" };
+        for (let index = pinnedDirectories.length - 1; index > 0; index -= 1) {
+            const parent = pinnedDirectories[index - 1];
+            const child = pinnedDirectories[index];
+            if (!parent || !child) {
+                throw new FsSafeError("helper-failed", `${label} directory pin chain is incomplete`);
+            }
+            await child.assertCurrent();
+            try {
+                const outcome = await parent.sync();
+                if (outcome.status === "unsupported") {
+                    parentSync = outcome;
+                }
+                else if (parentSync.status === "not-needed") {
+                    parentSync = outcome;
+                }
+            }
+            catch (error) {
+                throw new FsSafeError("helper-failed", `${label} could not sync created directory edge ${child.receipt.path} through ${parent.receipt.path}`, { cause: error });
+            }
+            await child.assertCurrent();
+        }
+        const finalReceipt = pinnedDirectories.at(-1)?.receipt;
+        if (!finalReceipt) {
+            throw new FsSafeError("helper-failed", `${label} directory receipt is missing`);
+        }
+        await ancestor.assertCurrent();
+        await assertDirectoryReceiptCurrent(finalReceipt, label);
+        return Object.assign(copyRetainedDirectoryReceipt(finalReceipt), { parentSync });
+    }
+    finally {
+        await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));
+    }
+}

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

@@ -0,0 +1,2 @@
+/** Strip only trailing separators: lstat must inspect the entry, not follow a leaf link. */
+export declare function directoryEntryPath(dir: string, platform?: NodeJS.Platform): string;

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

@@ -0,0 +1,21 @@
+import path from "node:path";
+/** Strip only trailing separators: lstat must inspect the entry, not follow a leaf link. */
+export function directoryEntryPath(dir, platform = process.platform) {
+    const windows = platform === "win32";
+    if (typeof dir === "string") {
+        const last = dir[dir.length - 1];
+        if (last !== "/" && (!windows || last !== "\\"))
+            return dir;
+    }
+    let rootLength = (windows ? path.win32 : path.posix).parse(dir).root.length;
+    if (windows && /^[\\/]{2}[?.][\\/]UNC[\\/]/i.test(dir)) {
+        // Node parses the namespace prefix as the root; retain the complete UNC share.
+        const uncRoot = path.win32.parse(`\\\\${dir.slice(8)}`).root;
+        if (uncRoot.length > 1)
+            rootLength = Math.max(rootLength, uncRoot.length + 6);
+    }
+    let end = dir.length;
+    while (end > rootLength && (dir[end - 1] === "/" || (windows && dir[end - 1] === "\\")))
+        end--;
+    return end === rootLength || end === dir.length ? dir : dir.slice(0, end);
+}

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

@@ -0,0 +1,55 @@
+import type { BigIntStats, Stats } from "node:fs";
+import { type ExactStatIdentity, type StatObservationReceipt } from "./stat-observation.js";
+export type AsyncDirectoryGuard<T extends Stats | BigIntStats = Stats> = {
+    dir: string;
+    realPath: string;
+    stat: T;
+};
+export type AnyAsyncDirectoryGuard = AsyncDirectoryGuard<Stats | BigIntStats>;
+export type SyncDirectoryGuard = AsyncDirectoryGuard;
+export type DirectoryIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    realPath: string;
+}>;
+export declare function readDirectoryIdentity(dir: string): Promise<DirectoryIdentity>;
+export declare function assertDirectoryIdentitySync(observedPath: string, expected: Pick<DirectoryIdentity, "dev" | "ino"> & {
+    realPath?: string;
+}): void;
+export declare function createAsyncDirectoryGuard(dir: string, options: {
+    bigint: true;
+    initial?: BigIntStats;
+}): Promise<AsyncDirectoryGuard<BigIntStats>>;
+export declare function createAsyncDirectoryGuard(dir: string, options?: {
+    bigint?: false;
+}): Promise<AsyncDirectoryGuard>;
+export declare function createAsyncDirectoryGuard(dir: string, options: {
+    bigint: boolean;
+}): Promise<AnyAsyncDirectoryGuard>;
+export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
+export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
+export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard | AnyAsyncDirectoryGuard): void;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
+    bigint: true;
+}): Promise<AsyncDirectoryGuard<BigIntStats>>;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
+    bigint: boolean;
+}): Promise<AnyAsyncDirectoryGuard>;
+export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
+export declare function inspectDirectoryIdentity(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): Promise<BigIntStats>;
+export declare function observeDirectoryIdentitySync(dir: string, options: {
+    bigint: true;
+}): BigIntStats;
+export declare function observeDirectoryIdentitySync(dir: string, options?: {
+    bigint?: false;
+}): Stats;
+export declare function inspectDirectoryIdentitySync(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">, initial?: BigIntStats, platform?: NodeJS.Platform): BigIntStats;
+export type DirectoryObservationGuard = StatObservationReceipt & {
+    dir: string;
+    realPath: string;
+};
+export declare function extendDirectoryObservationGuard(observation: StatObservationReceipt, dir: string, realPath: string): DirectoryObservationGuard;
+export declare function inspectDirectoryObservationSync(dir: string, expected?: ExactStatIdentity): StatObservationReceipt;
+export declare function assertDirectoryObservationSync(dir: string, expected: ExactStatIdentity): Stats | BigIntStats;
+export declare function assertDirectoryObservationGuardSync(guard: DirectoryObservationGuard): void;

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

@@ -0,0 +1,179 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
+import { directoryEntryPath } from "./directory-entry-path.js";
+import { assertStatObservationSync, inspectStatObservationSync, } from "./stat-observation.js";
+export async function readDirectoryIdentity(dir) {
+    const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+    return Object.freeze({ dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
+}
+export function assertDirectoryIdentitySync(observedPath, expected) {
+    const operationPath = directoryOperationPath(observedPath);
+    const expectedDev = expected.dev;
+    const expectedIno = expected.ino;
+    const expectedRealPath = expected.realPath;
+    if (expectedRealPath !== undefined)
+        assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedDev, ino: expectedIno });
+    if (expectedRealPath === undefined)
+        return;
+    const realPath = realpathSync.native(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+export async function createAsyncDirectoryGuard(dir, options) {
+    return captureDirectoryGuard(dir, "native", options);
+}
+export function createSyncDirectoryGuard(dir) {
+    return captureDirectoryGuard(dir, "normalized");
+}
+function captureDirectoryGuard(dir, mode, options) {
+    const operationPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
+        : fsSync.lstatSync(operationPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw directoryComponentNotDirectoryError();
+    }
+    const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    return { dir, realPath, stat };
+}
+export async function assertAsyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "native");
+}
+export function assertSyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "normalized");
+}
+function assertDirectoryGuard(guard, mode) {
+    const dir = guard.dir;
+    const operationPath = directoryOperationPath(dir);
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    const expectedStat = guard.stat;
+    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
+    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
+        ? inspectDirectoryIdentityAtPathSync(operationPath, {
+            dev: expectedIdentity.dev,
+            ino: expectedIdentity.ino,
+        })
+        : fsSync.lstatSync(operationPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw directoryComponentNotDirectoryError();
+    }
+    // Native guards check identity first; normalized numeric guards preserve
+    // canonicalization errors before their final identity comparison.
+    if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
+        ? realpathSync.native(operationPath) : realpathSync(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
+export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
+}
+export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
+}
+function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
+    assertNoWindowsPathAlias(rootReal, "filesystem");
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    const root = resolvePathPreservingWindowsRoot(rootReal);
+    while (current !== root) {
+        try {
+            return captureDirectoryGuard(current, mode, options);
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error)) {
+                throw error;
+            }
+            current = path.dirname(current);
+        }
+    }
+    return captureDirectoryGuard(root, mode, options);
+}
+// Recovery receipts must retain every identity bit, including on Windows.
+export async function inspectDirectoryIdentity(dir, expected) {
+    return inspectDirectoryIdentitySync(dir, expected);
+}
+function directoryOperationPath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    return pathForWindowsFilesystem(directoryEntryPath(dir));
+}
+export function observeDirectoryIdentitySync(dir, options) {
+    const entryPath = directoryOperationPath(dir);
+    const stat = options?.bigint
+        ? fsSync.lstatSync(entryPath, { bigint: true })
+        : fsSync.lstatSync(entryPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw directoryComponentNotDirectoryError();
+    return stat;
+}
+export function inspectDirectoryIdentitySync(dir, expected, initial, platform = process.platform) {
+    const operationPath = directoryOperationPath(dir);
+    const expectedIdentity = expected === undefined
+        ? undefined
+        : { dev: expected.dev, ino: expected.ino };
+    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity, initial, platform);
+}
+function inspectDirectoryIdentityAtPathSync(operationPath, expected, initial, platform = process.platform) {
+    return inspectFileIdentitySync(() => {
+        // Traversal can supply the first exact observation. A bounded retry still
+        // uses the admitted operation path and retains every known identity bit.
+        const stat = initial ?? fsSync.lstatSync(operationPath, { bigint: true });
+        initial = undefined;
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected, platform);
+}
+export function extendDirectoryObservationGuard(observation, dir, realPath) {
+    const guard = observation;
+    guard.dir = dir;
+    guard.realPath = realPath;
+    return guard;
+}
+// Only stat/list receipts use this metadata fast path. Recovery and publication
+// callers retain the BigIntStats contract of inspectDirectoryIdentitySync.
+export function inspectDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return inspectStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationSync(dir, expected) {
+    const entryPath = directoryOperationPath(dir);
+    return assertStatObservationSync(bigint => {
+        const stat = bigint ? fsSync.lstatSync(entryPath, { bigint: true }) : fsSync.lstatSync(entryPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            throw directoryComponentNotDirectoryError();
+        return stat;
+    }, expected);
+}
+export function assertDirectoryObservationGuardSync(guard) {
+    const dir = guard.dir;
+    const expectedRealPath = guard.realPath;
+    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
+    assertDirectoryObservationSync(dir, guard.identity);
+    const realPath = realpathSync.native(directoryOperationPath(dir));
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    if (realPath !== expectedRealPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}

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

@@ -0,0 +1,21 @@
+import { type BigIntStats } from "node:fs";
+import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export declare function nodeDarwinDirectoryMetadataFlags(): number;
+export declare function nodeDirectorySearchOnlyFlags(): {
+    flags: number;
+    proc: boolean;
+} | undefined;
+/** Real Node only: injected filesystem adapters must retain descriptor-chmod semantics. */
+export declare function pinNodeDirectoryForMode(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): Promise<DirectoryModeOwner>;
+/** Synchronous counterpart with the same no-follow, identity, and owner checks. */
+export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
+    expectedIdentity?: BigIntStats;
+    ownerUid?: number;
+}): {
+    apply(mode: number, check?: () => void): void;
+    close(): void;
+};