@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,245 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assertSyncDirectoryGuard, createSyncDirectoryGuard } from "./directory-guard.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { hasWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
+const TRASH_DESTINATION_RETRY_LIMIT = 4;
+function getFsErrorCode(error) {
+    if (!error || typeof error !== "object" || !("code" in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isTrashDestinationCollision(error) {
+    const code = getFsErrorCode(error);
+    return Boolean(code && TRASH_DESTINATION_COLLISION_CODES.has(code));
+}
+function isSameOrChildPath(candidate, parent) {
+    return candidate === parent || candidate.startsWith(parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`);
+}
+function assertNoTrashPathAlias(value, label) {
+    if (hasWindowsPathAlias(value, "filesystem")) {
+        throw new Error(`Refusing to trash ${label} using a Windows filesystem namespace alias: ${value}`);
+    }
+}
+function collectAllowedTrashRoots(allowedRoots) {
+    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])];
+    for (const root of roots)
+        assertNoTrashPathAlias(root, "allowed root");
+    return roots;
+}
+function resolveAllowedTrashRoots(allowedRoots) {
+    const roots = allowedRoots.flatMap((root) => {
+        assertNoTrashPathAlias(root, "allowed root");
+        const lexicalRoot = resolvePathPreservingWindowsRoot(root);
+        assertNoTrashPathAlias(lexicalRoot, "allowed root");
+        let realRoot;
+        try {
+            // Keep both spellings: broken symlink targets cannot be realpathed and
+            // may only compare equal to the caller's lexical allowed root.
+            realRoot = realpathSync.native(root);
+        }
+        catch {
+            return [lexicalRoot];
+        }
+        assertNoTrashPathAlias(realRoot, "allowed root");
+        const resolvedRealRoot = resolvePathPreservingWindowsRoot(realRoot);
+        assertNoTrashPathAlias(resolvedRealRoot, "allowed root");
+        return [resolvedRealRoot, lexicalRoot];
+    });
+    return [...new Set(roots)];
+}
+function resolveTrashTargetPath(targetPath) {
+    assertNoTrashPathAlias(targetPath, "target path");
+    let realPath;
+    try {
+        realPath = realpathSync.native(targetPath);
+    }
+    catch {
+        // Broken symlinks are valid trash targets. Fall back to the lexical path,
+        // then rely on lstat identity so the move renames the symlink itself.
+        const lexicalPath = path.resolve(targetPath);
+        assertNoTrashPathAlias(lexicalPath, "target path");
+        return { path: lexicalPath, resolved: false };
+    }
+    const resolvedPath = path.resolve(realPath);
+    assertNoTrashPathAlias(resolvedPath, "target path");
+    return { path: resolvedPath, resolved: true };
+}
+function resolveTrashEntryParent(lexicalTarget, targetPath) {
+    const lexicalParent = path.dirname(lexicalTarget);
+    assertNoTrashPathAlias(lexicalParent, "target path");
+    let realParent;
+    try {
+        // The renamed name lives in this parent. rename follows intermediate
+        // symlinks, so a lexical parent inside an allowed root is not enough.
+        realParent = realpathSync.native(lexicalParent);
+    }
+    catch {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+    const resolvedParent = path.resolve(realParent);
+    assertNoTrashPathAlias(resolvedParent, "target path");
+    return resolvedParent;
+}
+function assertAllowedTrashTarget(targetPath, allowedRoots) {
+    assertNoTrashPathAlias(targetPath, "target path");
+    const lexicalTarget = path.resolve(targetPath);
+    assertNoTrashPathAlias(lexicalTarget, "target path");
+    const stat = fs.lstatSync(lexicalTarget);
+    const resolvedTarget = resolveTrashTargetPath(targetPath);
+    const resolvedTargetPath = resolvedTarget.path;
+    const parent = createSyncDirectoryGuard(path.dirname(lexicalTarget));
+    // Admit the directory entry only when its parent really stays inside an
+    // allowed root. Do not admit it because the symlink target is inside.
+    const resolvedParent = resolveTrashEntryParent(lexicalTarget, targetPath);
+    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => isSameOrChildPath(resolvedParent, root));
+    if (!isAllowed) {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+    // Sync and native realpath can use different Windows short-name spellings.
+    // Recheck the retained guard around native containment instead of comparing them.
+    assertSyncDirectoryGuard(parent);
+    return {
+        parent,
+        path: lexicalTarget,
+        realPath: resolvedTargetPath,
+        realPathResolved: resolvedTarget.resolved,
+        stat,
+    };
+}
+function assertTrashTargetGuard(guard) {
+    assertSyncDirectoryGuard(guard.parent);
+    const stat = fs.lstatSync(guard.path);
+    if (!sameFileIdentity(stat, guard.stat)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    const current = resolveTrashTargetPath(guard.path);
+    if (guard.realPathResolved && (!current.resolved || current.path !== guard.realPath)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    if (!guard.realPathResolved && current.resolved) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+}
+function resolveTrashDir() {
+    const homeDir = os.homedir();
+    assertNoTrashPathAlias(homeDir, "home directory");
+    const trashDir = path.join(homeDir, ".Trash");
+    assertNoTrashPathAlias(trashDir, "trash directory");
+    fs.mkdirSync(recursiveMkdirPath(trashDir), { recursive: true, mode: 0o700 });
+    const trashDirStat = fs.lstatSync(trashDir);
+    if (!trashDirStat.isDirectory() || trashDirStat.isSymbolicLink()) {
+        throw new Error(`Refusing to use non-directory/symlink trash directory: ${trashDir}`);
+    }
+    const realHome = path.resolve(realpathSync.native(homeDir));
+    const resolvedTrashDir = path.resolve(realpathSync.native(trashDir));
+    assertNoTrashPathAlias(realHome, "home directory");
+    assertNoTrashPathAlias(resolvedTrashDir, "trash directory");
+    if (resolvedTrashDir === realHome || !isSameOrChildPath(resolvedTrashDir, realHome)) {
+        throw new Error(`Trash directory escaped home directory: ${trashDir}`);
+    }
+    return resolvedTrashDir;
+}
+function trashBaseName(targetPath) {
+    assertNoTrashPathAlias(targetPath, "target path");
+    const resolvedTargetPath = path.resolve(targetPath);
+    assertNoTrashPathAlias(resolvedTargetPath, "target path");
+    if (resolvedTargetPath === path.parse(resolvedTargetPath).root) {
+        throw new Error(`Refusing to trash root path: ${targetPath}`);
+    }
+    const base = path.basename(resolvedTargetPath).replace(/[\\/]+/g, "");
+    if (!base) {
+        throw new Error(`Unable to derive safe trash basename for: ${targetPath}`);
+    }
+    return base;
+}
+function resolveContainedPath(root, leaf) {
+    assertNoTrashPathAlias(root, "destination root");
+    assertNoTrashPathAlias(leaf, "destination name");
+    const resolvedRoot = path.resolve(root);
+    const resolvedPath = path.resolve(resolvedRoot, leaf);
+    assertNoTrashPathAlias(resolvedRoot, "destination root");
+    assertNoTrashPathAlias(resolvedPath, "destination path");
+    if (!isSameOrChildPath(resolvedPath, resolvedRoot) || resolvedPath === resolvedRoot) {
+        throw new Error(`Trash destination escaped trash directory: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}
+function reserveTrashDestination(trashDir, base, timestamp) {
+    assertNoTrashPathAlias(trashDir, "trash directory");
+    assertNoTrashPathAlias(base, "destination name");
+    const containerPrefix = resolveContainedPath(trashDir, `.fs-safe-trash-${timestamp}-`);
+    const container = fs.mkdtempSync(containerPrefix);
+    const resolvedContainer = path.resolve(container);
+    const resolvedTrashDir = path.resolve(trashDir);
+    assertNoTrashPathAlias(resolvedContainer, "destination container");
+    assertNoTrashPathAlias(resolvedTrashDir, "trash directory");
+    if (resolvedContainer === resolvedTrashDir ||
+        !isSameOrChildPath(resolvedContainer, resolvedTrashDir)) {
+        throw new Error(`Trash destination escaped trash directory: ${container}`);
+    }
+    return resolveContainedPath(container, base);
+}
+function copyTrashTargetSync(target, dest) {
+    if (target.stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(target.path);
+        assertNoTrashPathAlias(linkTarget, "symlink target");
+        assertTrashTargetGuard(target);
+        fs.symlinkSync(linkTarget, dest);
+        return;
+    }
+    fs.cpSync(target.path, dest, { recursive: true, force: false, errorOnExist: true });
+}
+function movePathToDestination(target, dest) {
+    getFsSafeTestHooks()?.beforeTrashMove?.(target.path, dest);
+    assertTrashTargetGuard(target);
+    try {
+        guardedRenameSync({ from: target.path, to: dest });
+        return true;
+    }
+    catch (error) {
+        if (getFsErrorCode(error) !== "EXDEV") {
+            if (isTrashDestinationCollision(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    try {
+        assertTrashTargetGuard(target);
+        copyTrashTargetSync(target, dest);
+        assertTrashTargetGuard(target);
+        guardedRmSync({ target: target.path, recursive: true, force: false, verifyAfter: false });
+        return true;
+    }
+    catch (error) {
+        if (isTrashDestinationCollision(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function movePathToTrash(targetPath, options = {}) {
+    // Avoid resolving external trash helpers through the service PATH during cleanup.
+    assertNoTrashPathAlias(targetPath, "target path");
+    const allowedRoots = collectAllowedTrashRoots(options.allowedRoots);
+    const base = trashBaseName(targetPath);
+    const target = assertAllowedTrashTarget(targetPath, allowedRoots);
+    const trashDir = resolveTrashDir();
+    const timestamp = Date.now();
+    for (let attempt = 0; attempt < TRASH_DESTINATION_RETRY_LIMIT; attempt += 1) {
+        const dest = reserveTrashDestination(trashDir, base, timestamp);
+        if (movePathToDestination(target, dest)) {
+            return dest;
+        }
+    }
+    throw new Error(`Unable to choose a unique trash destination for ${targetPath}`);
+}

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

@@ -0,0 +1,22 @@
+export type FastPathMode = "auto" | "never" | "require";
+export type SafeEncoding = BufferEncoding | null;
+export type PathStat = {
+    dev: number;
+    gid: number;
+    ino: number;
+    isDirectory: boolean;
+    isFile: boolean;
+    isSymbolicLink: boolean;
+    mode: number;
+    mtimeMs: number;
+    nlink: number;
+    size: number;
+    uid: number;
+};
+export type DirEntry = PathStat & {
+    name: string;
+};
+export type BasePathOptions = {
+    rootDir: string;
+    relativePath: string;
+};

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

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

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

@@ -0,0 +1,2 @@
+export declare function lowerCaseNfc(value: string): string;
+export declare function maxNormalizedUtf8Bytes(value: string, includeRaw?: boolean): number;

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

@@ -0,0 +1,16 @@
+const NON_ASCII = /[^\x00-\x7f]/;
+export function lowerCaseNfc(value) {
+    return NON_ASCII.test(value) ? value.normalize("NFC").toLowerCase().normalize("NFC") : value.toLowerCase();
+}
+export function maxNormalizedUtf8Bytes(value, includeRaw = false) {
+    // ASCII has identical raw, NFC and NFD forms, with one UTF-8 byte per unit.
+    if (typeof value === "string" && !NON_ASCII.test(value))
+        return value.length;
+    const nfc = value.normalize("NFC");
+    const bytes = Buffer.byteLength(nfc, "utf8");
+    const maximum = includeRaw && nfc !== value ? Math.max(bytes, Buffer.byteLength(value, "utf8")) : bytes;
+    // ASCII NFC output also has identical NFD and one UTF-8 byte per code unit.
+    if (bytes === nfc.length)
+        return maximum;
+    return Math.max(maximum, Buffer.byteLength(value.normalize("NFD"), "utf8"));
+}

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

@@ -0,0 +1,37 @@
+import fsSync from "node:fs";
+export type WalkEntryKind = "file" | "directory" | "symlink" | "other";
+export type WalkSymlinkPolicy = "skip" | "follow" | "include";
+export type WalkDirectoryEntry = {
+    name: string;
+    path: string;
+    relativePath: string;
+    depth: number;
+    kind: WalkEntryKind;
+    dirent: fsSync.Dirent;
+};
+export type WalkDirectoryOptions = {
+    maxDepth?: number;
+    maxEntries?: number;
+    symlinks?: WalkSymlinkPolicy;
+    include?: (entry: WalkDirectoryEntry) => boolean;
+    descend?: (entry: WalkDirectoryEntry) => boolean;
+};
+export type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+    include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+    descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+};
+export type WalkDirectoryFailure = Pick<WalkDirectoryEntry & {
+    error: unknown;
+}, "path" | "relativePath" | "depth" | "error">;
+export type WalkDirectoryResult = {
+    entries: WalkDirectoryEntry[];
+    scannedEntryCount: number;
+    truncated: boolean;
+    failedDirs?: WalkDirectoryFailure[];
+};
+type WalkDirectoryResultWithFailures = WalkDirectoryResult & {
+    failedDirs: WalkDirectoryFailure[];
+};
+export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResultWithFailures;
+export declare function walkDirectory(rootDir: string, options?: AsyncWalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
+export {};

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

@@ -0,0 +1,207 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { realpathSync } from "./realpath.js";
+import { pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function validateWalkBudget(name, value) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function validateWalkOptions(options) {
+    validateWalkBudget("maxDepth", options.maxDepth);
+    validateWalkBudget("maxEntries", options.maxEntries);
+    if (options.symlinks !== undefined &&
+        !["skip", "follow", "include"].includes(options.symlinks)) {
+        throw new TypeError(`invalid walk symlink policy: ${String(options.symlinks)}`);
+    }
+}
+function isObjectResult(result) {
+    return result !== null &&
+        (typeof result === "object" || typeof result === "function");
+}
+function kindForDirent(dirent) {
+    if (dirent.isDirectory())
+        return "directory";
+    if (dirent.isFile())
+        return "file";
+    if (dirent.isSymbolicLink())
+        return "symlink";
+    return "other";
+}
+function shouldStop(result, options) {
+    return options.maxEntries !== undefined && result.scannedEntryCount >= Math.max(0, options.maxEntries);
+}
+function buildEntry(params) {
+    const fullPath = params.fullPath;
+    return {
+        name: params.dirent.name,
+        path: fullPath,
+        relativePath: params.relativePath,
+        depth: params.depth,
+        kind: params.kind ?? kindForDirent(params.dirent),
+        dirent: params.dirent,
+    };
+}
+function recordFailedDir(result, root, dir, depth, error) {
+    const relativePath = path.relative(root, dir);
+    result.failedDirs.push({
+        path: dir,
+        relativePath,
+        depth: relativePath === "" ? 0 : depth - 1,
+        error,
+    });
+}
+function resolveKind(fullPath, dirent, symlinks) {
+    const kind = kindForDirent(dirent);
+    if (kind !== "symlink")
+        return kind;
+    if (symlinks === "skip")
+        return null;
+    if (symlinks === "include")
+        return "symlink";
+    try {
+        const stat = fsSync.statSync(fullPath);
+        if (stat.isDirectory())
+            return "directory";
+        if (stat.isFile())
+            return "file";
+    }
+    catch {
+        return null;
+    }
+    return "other";
+}
+export function walkDirectorySync(rootDir, options = {}) {
+    validateWalkOptions(options);
+    const root = resolvePathPreservingWindowsRoot(rootDir);
+    const symlinks = options.symlinks ?? "skip";
+    const result = {
+        entries: [],
+        scannedEntryCount: 0,
+        truncated: false,
+        failedDirs: [],
+    };
+    const visitedDirs = new Set();
+    function visit(dir, relativeDir, depth) {
+        if (options.maxDepth !== undefined && depth > options.maxDepth)
+            return;
+        let realDir;
+        const operationPath = pathForWindowsFilesystem(dir);
+        try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
+            realDir = realpathSync(operationPath);
+        }
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
+            return;
+        }
+        if (visitedDirs.has(realDir))
+            return;
+        visitedDirs.add(realDir);
+        let entries;
+        try {
+            entries = fsSync.readdirSync(operationPath, { withFileTypes: true });
+        }
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
+            return;
+        }
+        const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
+        for (const dirent of entries) {
+            if (shouldStop(result, options)) {
+                result.truncated = true;
+                return;
+            }
+            result.scannedEntryCount += 1;
+            const fullPath = childPrefix + dirent.name;
+            const kind = resolveKind(fullPath, dirent, symlinks);
+            if (!kind)
+                continue;
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+            if (options.include?.(entry) ?? true) {
+                result.entries.push(entry);
+            }
+            if (kind === "directory" &&
+                (options.maxDepth === undefined || depth < options.maxDepth) &&
+                (options.descend?.(entry) ?? true)) {
+                visit(fullPath, relativePath, depth + 1);
+                if (result.truncated)
+                    return;
+            }
+        }
+    }
+    visit(root, "", 1);
+    return result;
+}
+export async function walkDirectory(rootDir, options = {}) {
+    validateWalkOptions(options);
+    const root = resolvePathPreservingWindowsRoot(rootDir);
+    const symlinks = options.symlinks ?? "skip";
+    const result = {
+        entries: [],
+        scannedEntryCount: 0,
+        truncated: false,
+        failedDirs: [],
+    };
+    const visitedDirs = new Set();
+    async function visit(dir, relativeDir, depth) {
+        if (options.maxDepth !== undefined && depth > options.maxDepth)
+            return;
+        let realDir;
+        const operationPath = pathForWindowsFilesystem(dir);
+        try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
+            realDir = realpathSync.native(operationPath);
+        }
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
+            return;
+        }
+        if (visitedDirs.has(realDir))
+            return;
+        visitedDirs.add(realDir);
+        let entries;
+        try {
+            entries = await fs.readdir(operationPath, { withFileTypes: true });
+        }
+        catch (error) {
+            recordFailedDir(result, root, dir, depth, error);
+            return;
+        }
+        const childPrefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`;
+        for (const dirent of entries) {
+            if (shouldStop(result, options)) {
+                result.truncated = true;
+                return;
+            }
+            result.scannedEntryCount += 1;
+            const fullPath = childPrefix + dirent.name;
+            const kind = resolveKind(fullPath, dirent, symlinks);
+            if (!kind)
+                continue;
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
+            const include = options.include;
+            const included = include == null ? true : Reflect.apply(include, options, [entry]);
+            if ((isObjectResult(included) ? await included : included) ?? true) {
+                result.entries.push(entry);
+            }
+            if (kind === "directory" &&
+                (options.maxDepth === undefined || depth < options.maxDepth)) {
+                const descend = options.descend;
+                const descended = descend == null ? true : Reflect.apply(descend, options, [entry]);
+                if ((isObjectResult(descended) ? await descended : descended) ?? true) {
+                    await visit(fullPath, relativePath, depth + 1);
+                    if (result.truncated)
+                        return;
+                }
+            }
+        }
+    }
+    await visit(root, "", 1);
+    return result;
+}

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

@@ -0,0 +1,6 @@
+import { type RootContext } from "./root-context.js";
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export declare function admittedNativeChanges(root: RootContext, scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, batch: NativeWatchBatch, signal: AbortSignal, limit: number): Promise<WatchChange[] | undefined>;

package/node_modules/@openclaw/fs-safe/dist/watch-alias.js

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrent, resolvePathInRoot } from "./root-context.js";
+import { createRootDirectoryObservationGuard, assertRootDirectoryObservationGuard } from "./root-directory-list.js";
+import { lookupRootDirectoryEntry } from "./root-directory-entry.js";
+import { excludedWatchPath, nativeChanges, scopedChanges } from "./watch-hints.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export async function admittedNativeChanges(root, scopes, before, after, batch, signal, limit) {
+    if (!nativeChanges(scopes, before, batch, limit, after))
+        return undefined;
+    const result = new Map();
+    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
+    const add = (change) => {
+        if (!result.has(change.path) && result.size >= limit)
+            return false;
+        const prior = result.get(change.path);
+        result.set(change.path, prior?.type === "structural" ? prior : change);
+        return true;
+    };
+    for (const hint of batch.hints) {
+        signal.throwIfAborted();
+        const name = hint.name; // nativeChanges rejected unknown or non-literal names.
+        let parent = hint.directory;
+        const relative = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, relative) || excludedWatchPath(after, relative))
+            continue;
+        let guard;
+        let expected = after.directories.get(parent);
+        if (!expected) {
+            // Native recursion observes one Root handle and may report descendants of
+            // unselected/entry-only directories. Admit a parent alias by exact identity,
+            // not by lowercasing, and do not turn unselected descendants into events.
+            try {
+                const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+                guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+            }
+            catch (error) {
+                await assertRootIdentityCurrent(root);
+                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
+                    continue;
+                throw error;
+            }
+            const admitted = [...after.directories].find(([, identity]) => identity.dev === guard.stat.dev && identity.ino === guard.stat.ino);
+            if (!admitted)
+                continue;
+            [parent, expected] = admitted;
+        }
+        const candidate = parent ? path.join(parent, name) : name;
+        if (excludedWatchPath(before, candidate) || excludedWatchPath(after, candidate))
+            continue;
+        const selected = scopedChanges(scopes, { path: candidate,
+            type: hint.event === "change" && before?.entries.get(candidate)?.startsWith("file:") ? "content" : "structural" });
+        if (selected.length) {
+            for (const change of selected)
+                if (!add(change))
+                    return undefined;
+            continue;
+        }
+        if (!guard) {
+            const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+            guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+        }
+        if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+            throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
+        }
+        const found = await lookupRootDirectoryEntry(root, guard, name);
+        signal.throwIfAborted();
+        // A missing unselected sibling is not evidence of lost selected detail.
+        // Previously observed selected deletions remain visible in the snapshot diff;
+        // an unseen, already-gone name has no identity proving a selected alias.
+        if (!found)
+            continue;
+        for (const [relative, identity] of candidates) {
+            if (!relative || (path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent)
+                continue;
+            if (identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
+                continue;
+            for (const change of scopedChanges(scopes, { path: relative, type: "structural" }))
+                if (!add(change))
+                    return undefined;
+        }
+        await assertRootDirectoryObservationGuard(root, guard);
+    }
+    await assertRootIdentityCurrent(root);
+    signal.throwIfAborted();
+    return [...result.values()];
+}

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

@@ -0,0 +1,9 @@
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+export declare function excludedWatchPath(snapshot: WatchSnapshot | undefined, name: string): boolean;
+export declare function scopedChanges(scopes: readonly WatchScope[], change: WatchChange): WatchChange[];
+export declare function nativeChanges(scopes: readonly WatchScope[], snapshot: WatchSnapshot | undefined, batch: NativeWatchBatch, limit?: number, after?: WatchSnapshot): WatchChange[] | undefined;
+export declare function changedEntries(before: WatchSnapshot | undefined, after: WatchSnapshot, limit: number): WatchChange[] | undefined;
+/** Backend names never establish authority to publish a pathname. */
+export declare function guardedHintChanges(scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, hints: readonly WatchChange[] | undefined, observed: readonly WatchChange[] | undefined, limit: number): WatchChange[] | undefined;