@openclaw/fs-safe 0.21.0 → 0.21.1

package/dist/root-directory-list.d.ts

@@ -37,6 +37,8 @@ export type RootDirectoryListingOptions = {
     metadataBatchSize?: number;
     /** Internal exact metadata lane, supported by streaming filesystem order. */
     exactIdentity?: boolean;
+    /** Advisory scans may omit vanished leaves after revalidating their parent. */
+    skipVanished?: boolean;
     /** Internal owner receives cleanup failures, including acquisition rollback. */
     onCleanupFailure?: (error: unknown) => void;
     admitEntry(): boolean;

package/dist/root-directory-list.js

@@ -1,3 +1,4 @@
+import { isUtf8 } from "node:buffer";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -14,6 +15,22 @@ import { realpathSync } from "./realpath.js";
 import { inspectStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
+function directoryEntryName(bytes) {
+    if (!isUtf8(bytes)) {
+        throw new FsSafeError("invalid-path", "directory entry name is not valid UTF-8");
+    }
+    return bytes.toString("utf8");
+}
+async function readDirectoryEntryName(handle) {
+    const entry = await handle.read();
+    // Bun returns the raw Buffer directly; Node returns a Dirent whose name is a Buffer.
+    // Node's Dir types still declare only string names.
+    return entry === null ? undefined
+        : directoryEntryName(Buffer.isBuffer(entry) ? entry : entry.name);
+}
+function openDirectoryNames(directory) {
+    return fs.opendir(directory, { bufferSize: 1, encoding: "buffer" });
+}
 export function pathStatFromStats(stat) {
     const mtimeMs = typeof stat.mtimeMs === "bigint"
         ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
@@ -202,7 +219,7 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
         if (beforeObservation)
             await beforeObservation(guard.realPath, withFileTypes);
-        const names = (await fs.readdir(guard.realPath)).sort();
+        const names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName).sort();
         entries = withFileTypes
             ? names.map(name => ({
                 name,
@@ -275,17 +292,17 @@ export async function openRootDirectoryListing(root, directory, options, receipt
         await assertCurrent();
         if (options.order === "filesystem") {
             // A one-entry buffer keeps the truncation lookahead independent of width.
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
         }
         else if (options.snapshot) {
             snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
-            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            handle = await openDirectoryNames(guard.realPath);
             while (true) {
                 await assertCurrent();
-                const name = (await handle.read())?.name;
+                const name = await readDirectoryEntryName(handle);
                 await assertCurrent();
                 if (name === undefined)
                     break;
@@ -297,7 +314,7 @@ export async function openRootDirectoryListing(root, directory, options, receipt
             await close();
         }
         else {
-            names = await fs.readdir(guard.realPath);
+            names = (await fs.readdir(guard.realPath, { encoding: "buffer" })).map(directoryEntryName);
         }
         await assertCurrent();
         names?.sort();
@@ -382,21 +399,30 @@ export async function openRootDirectoryListing(root, directory, options, receipt
                         return { kind: "limit", name: pendingLimit };
                     return;
                 }
-                await assertCurrent();
-                const name = (await handle.read())?.name;
-                await assertCurrent();
-                if (name === undefined)
-                    return;
-                if (!options.admitEntry())
-                    return { kind: "limit", name };
-                // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const pathname = path.join(guard.realPath, name);
-                const observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
-                    ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : undefined;
-                const stat = observed?.stat ?? fsSync.lstatSync(pathname);
-                await assertCurrent();
-                const entry = { name, ...pathStatFromStats(stat) };
-                return observed ? { kind: "entry", entry, identity: observed.identity } : { kind: "entry", entry };
+                for (;;) {
+                    await assertCurrent();
+                    const name = await readDirectoryEntryName(handle);
+                    await assertCurrent();
+                    if (name === undefined)
+                        return;
+                    if (!options.admitEntry())
+                        return { kind: "limit", name };
+                    // The stream's post-read fence is also the pre-stat fence in this owned operation.
+                    const pathname = path.join(guard.realPath, name);
+                    let observed;
+                    try {
+                        observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                            ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : { stat: fsSync.lstatSync(pathname) };
+                    }
+                    catch (error) {
+                        await assertCurrent();
+                        if (options.skipVanished && isNotFoundPathError(error))
+                            continue;
+                        throw error;
+                    }
+                    await assertCurrent();
+                    return { kind: "entry", entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+                }
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

package/dist/root-move-noreplace.js

@@ -4,7 +4,7 @@ import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard } from "./directory
 import { FsSafeError } from "./errors.js";
 import { assertMutationNotDenied } from "./deny-mutations.js";
 import { openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
-import { getNativeBinding } from "./native.js";
+import { requireNativeBinding } from "./native.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
@@ -78,8 +78,8 @@ export async function movePathNoReplaceNative(root, params, paths) {
             throw error;
         // Advisory fast rejection only. renameNoReplace owns the collision decision.
     }
-    const binding = getNativeBinding();
-    if (!binding || typeof binding.renameNoReplace !== "function") {
+    const binding = requireNativeBinding();
+    if (typeof binding.renameNoReplace !== "function") {
         throw new FsSafeError("helper-unavailable", "native no-replace move is unavailable");
     }
     const rootAdmission = await openNativeRootAdmission(binding, {

package/dist/sidecar-lock-acquire.js

@@ -290,9 +290,9 @@ export async function acquireSidecarLock(options, context) {
                     }
                     await handle.writeFile(raw, "utf8");
                 }
-                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd), ownershipToken };
+                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd, { bigint: true }), ownershipToken };
                 createdSnapshot = snapshot;
-                if (snapshot.stat.nlink === 0) {
+                if (snapshot.stat.nlink === 0n) {
                     await handle.close();
                     handle = null;
                     await waitForRetry();
@@ -361,7 +361,7 @@ export async function acquireSidecarLock(options, context) {
                     if (handle) {
                         failedSnapshot ??= { payload: null };
                         try {
-                            failedSnapshot.stat = fsSync.fstatSync(handle.fd);
+                            failedSnapshot.stat = fsSync.fstatSync(handle.fd, { bigint: true });
                         }
                         catch {
                             // Best-effort cleanup of a failed exclusive create.

package/dist/sidecar-lock-reclaim.d.ts

@@ -1,4 +1,4 @@
-import { type Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { Root } from "./root-impl.js";
 export type SidecarLockStaleSnapshot = {
     lockPath: string;
@@ -9,7 +9,7 @@ export type SidecarLockStaleSnapshot = {
 export type SidecarLockSnapshot = {
     raw?: string;
     payload: unknown;
-    stat?: Stats;
+    stat?: Stats | BigIntStats;
     ownershipToken?: string;
 };
 type SidecarLockRawSnapshot = Omit<SidecarLockSnapshot, "payload"> & {

package/dist/sidecar-lock-reclaim.js

@@ -90,7 +90,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
                     raw,
-                    stat: opened.stat,
+                    stat: fsSync.fstatSync(opened.handle.fd, { bigint: true }),
                 };
             }
             finally {
@@ -99,7 +99,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         }
         let before;
         try {
-            before = fsSync.lstatSync(lockPath);
+            before = fsSync.lstatSync(lockPath, { bigint: true });
         }
         catch (error) {
             before = missingSnapshotPath(error);
@@ -132,7 +132,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = fsSync.fstatSync(handle.fd);
+        const opened = fsSync.fstatSync(handle.fd, { bigint: true });
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -144,7 +144,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
         let after;
         try {
-            after = fsSync.lstatSync(lockPath);
+            after = fsSync.lstatSync(lockPath, { bigint: true });
         }
         catch (error) {
             after = missingSnapshotPath(error);
@@ -159,7 +159,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
 }
 function lstatSidecarLockSync(lockPath) {
     try {
-        return fsSync.lstatSync(lockPath);
+        return fsSync.lstatSync(lockPath, { bigint: true });
     }
     catch (error) {
         return missingSnapshotPath(error);
@@ -189,7 +189,7 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = fsSync.fstatSync(fd);
+        const opened = fsSync.fstatSync(fd, { bigint: true });
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);

package/dist/sidecar-lock.js

@@ -50,7 +50,7 @@ function resolveManagerState(key) {
 function snapshotMatchesSync(lockPath, observed) {
     let fd;
     try {
-        const beforeStat = fsSync.lstatSync(lockPath);
+        const beforeStat = fsSync.lstatSync(lockPath, { bigint: true });
         if (!beforeStat.isFile()) {
             return false;
         }
@@ -60,17 +60,17 @@ function snapshotMatchesSync(lockPath, observed) {
                 : 0) |
             (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
         fd = fsSync.openSync(lockPath, openFlags);
-        const openedStat = fsSync.fstatSync(fd);
+        const openedStat = fsSync.fstatSync(fd, { bigint: true });
         // Token-owned files can have different descriptor/path identities on VirtioFS.
         // Require a known descriptor identity without rejecting that supported drift.
         if (!openedStat.isFile() || !sameFileIdentityForCleanup(openedStat, openedStat)) {
             return false;
         }
-        if (observed.raw !== undefined && openedStat.size !== Buffer.byteLength(observed.raw)) {
+        if (observed.raw !== undefined && openedStat.size !== BigInt(Buffer.byteLength(observed.raw))) {
             return false;
         }
         const raw = fsSync.readFileSync(fd, "utf8");
-        const afterStat = fsSync.lstatSync(lockPath);
+        const afterStat = fsSync.lstatSync(lockPath, { bigint: true });
         if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
             return false;
         }

package/dist/staged-symlink-types.d.ts

@@ -1,20 +1,13 @@
-import type { StagedFileReceipt } from "./staged-file-types.js";
+import type { PublishedFileReceipt, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
 /** Caller-captured admission evidence, never a same-target ownership heuristic. */
-export type StagedSymlinkExpected = Readonly<{
-    dev: bigint;
-    ino: bigint;
-    uid: number;
-    gid: number;
-    ctimeNs: bigint;
+export type StagedSymlinkExpected = Readonly<Pick<StagedFileReceipt["identity"], "dev" | "ino" | "uid" | "gid" | "ctimeNs"> & {
     target: string;
 }>;
 export type StagedSymlinkReceipt = StagedFileReceipt & Readonly<{
     target: string;
 }>;
-export type PublishedSymlinkReceipt = Readonly<{
-    status: "published";
+export type PublishedSymlinkReceipt = Readonly<Pick<PublishedFileReceipt, "status" | "basename"> & {
     staged: StagedSymlinkReceipt;
-    basename: string;
     overwrite: false;
 }>;
 export type StagedSymlinkPublication = Readonly<{
@@ -25,11 +18,8 @@ export type StagedSymlinkPublication = Readonly<{
     overwrite: false;
 }>;
 export type StagedSymlinkRemoval = "removed" | "name-absent" | "preserved";
-export type StagedSymlinkCleanupReceipt = Readonly<{
-    temporaryBasename: string;
+export type StagedSymlinkCleanupReceipt = Readonly<Pick<StagedFileCleanupReceipt, "temporaryBasename" | "status" | "resources"> & {
     publication: StagedSymlinkPublication;
-    status: StagedSymlinkRemoval | "failed" | "not-needed";
-    resources: "closed" | "close-failed";
 }>;
 export type StagedSymlinkFailureDetails = Readonly<{
     phase: "prepare" | "publish" | "remove-published" | "cleanup";

package/dist/test-hooks.d.ts

@@ -3,6 +3,7 @@ import type { FileIdentityStat } from "./file-identity.js";
 export type FsSafeTestHooks = {
     beforeWatchRegistration?: (path: string) => void | Promise<void>;
     afterWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchBackendOverflow?: (root: string, phase: "received" | "reconciled") => void;
     afterWatchBackendCreated?: (root: string, emit: (batch: import("./watch-native.js").NativeWatchBatch) => void, nativeEvent?: (path: string, flags: number) => void) => void;
     afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
     beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;

package/dist/watch-alias.js

@@ -4,10 +4,10 @@ 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 { nativeChanges, scopedChanges } from "./watch-hints.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))
+    if (!nativeChanges(scopes, before, batch, limit, after))
         return undefined;
     const result = new Map();
     const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
@@ -22,6 +22,9 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
         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) {
@@ -44,6 +47,8 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
             [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) {
@@ -61,8 +66,11 @@ export async function admittedNativeChanges(root, scopes, before, after, batch,
         }
         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)
-            return undefined; // Could be a deleted short-name/case alias.
+            continue;
         for (const [relative, identity] of candidates) {
             if (!relative || (path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent)
                 continue;

package/dist/watch-hints.d.ts

@@ -1,8 +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): WatchChange[] | undefined;
+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;

package/dist/watch-hints.js

@@ -5,6 +5,18 @@ function below(parent, child) {
 function distance(parent, child) {
     return (parent === "" ? child : child.slice(parent.length + 1)).split(path.sep).length;
 }
+export function excludedWatchPath(snapshot, name) {
+    const exclusions = snapshot?.excluded;
+    if (exclusions?.has(name))
+        return true;
+    while (name) {
+        const parent = path.dirname(name);
+        name = parent === "." ? "" : parent;
+        if (exclusions?.get(name) === "directory")
+            return true;
+    }
+    return false;
+}
 export function scopedChanges(scopes, change) {
     const result = new Map();
     for (const scope of scopes) {
@@ -18,7 +30,7 @@ export function scopedChanges(scopes, change) {
     }
     return [...result.values()];
 }
-export function nativeChanges(scopes, snapshot, batch, limit = 256) {
+export function nativeChanges(scopes, snapshot, batch, limit = 256, after) {
     if (batch.overflow)
         return undefined;
     const result = new Map();
@@ -28,6 +40,8 @@ export function nativeChanges(scopes, snapshot, batch, limit = 256) {
         if (typeof name !== "string" || !name || name === "." || name === ".." || name.includes("\0") || name.includes("/") || (process.platform === "win32" && /[\\:]/.test(name)))
             return undefined;
         const relative = hint.directory ? path.join(hint.directory, name) : name;
+        if (excludedWatchPath(snapshot, relative) || excludedWatchPath(after, relative))
+            continue;
         for (const change of scopedChanges(scopes, {
             path: relative,
             type: hint.event === "change" && snapshot?.entries.get(relative)?.startsWith("file:") ? "content" : "structural",
@@ -68,6 +82,8 @@ export function guardedHintChanges(scopes, before, after, hints, observed, limit
         // A stale/misdirected inode watch may report outside names: erase its detail.
         if (!before?.entries.has(hint.path) && !after.entries.has(hint.path) && !scopes.some(scope => scope.path === hint.path))
             return undefined;
+        // Equal snapshots cannot exclude an intermediate change and restoration (ABA).
+        // Preserve admitted hints, including setup activity delivered after ready.
         if (!result.has(hint.path) && result.size >= limit)
             return undefined;
         const prior = result.get(hint.path);

package/dist/watch-native.d.ts

@@ -1,6 +1,7 @@
 import { type NativeBinding } from "./native.js";
 import type { RootContext } from "./root-context.js";
 import type { DirectoryIdentity } from "./watch-scan.js";
+import type { WatchStreamPaths } from "./watch-stream.js";
 export type NativeWatchHint = {
     directory: string;
     name: string;
@@ -16,6 +17,7 @@ export type NativeWatchWireBatch = {
         directory: string;
         name: string;
         structural: boolean;
+        flags?: number;
     }[];
     overflow: boolean;
     error?: string;
@@ -25,8 +27,10 @@ export declare class NativeWatchBackend {
     private binding;
     private root;
     private id;
+    private streamPaths;
     constructor(binding: NativeBinding, root: RootContext, callback: (batch: NativeWatchBatch) => void, limit: number, persistent: boolean);
     add(name: string, identity: DirectoryIdentity): void;
     testEvent(path: string, flags: number): void;
+    configure(paths: WatchStreamPaths): boolean;
     close(): void;
 }

package/dist/watch-native.js

@@ -6,7 +6,7 @@ export function watchBinding(mode) {
         return;
     const binding = getNativeBinding(); // Preserves require + missing-addon failure.
     // Bun TSFN teardown remains unqualified; guarded native scans remain usable.
-    if (binding?.watchRegister && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
+    if (binding?.watchRegister && (process.platform !== "darwin" || binding.watchConfigure) && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
         return binding;
     if (mode === "events" || getFsSafeNativeConfig().mode === "require") {
         throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { details: { operation: "watch" } });
@@ -16,9 +16,11 @@ export class NativeWatchBackend {
     binding;
     root;
     id;
+    streamPaths;
     constructor(binding, root, callback, limit, persistent) {
         this.binding = binding;
         this.root = root;
+        this.streamPaths = JSON.stringify({ anchors: [root.rootReal], exclusions: [] });
         try {
             this.id = binding.watchRegister(root.rootReal, limit, batch => {
                 if (this.id !== undefined)
@@ -41,6 +43,21 @@ export class NativeWatchBackend {
         }
     }
     testEvent(path, flags) { this.binding.watchTestEvent(this.id, path, flags); }
+    configure(paths) {
+        if (process.platform !== "darwin")
+            return false;
+        const key = JSON.stringify(paths);
+        if (this.streamPaths === key)
+            return false;
+        try {
+            this.binding.watchConfigure(this.id, paths.anchors, paths.exclusions);
+        }
+        catch (cause) {
+            throw watchError(cause);
+        }
+        this.streamPaths = key;
+        return true;
+    }
     close() {
         const id = this.id;
         this.id = undefined; // Fence queued TSFN callbacks before synchronous native join.

package/dist/watch-scan.d.ts

@@ -1,12 +1,15 @@
 import { type RootContext } from "./root-context.js";
 import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
-import type { WatchOptions, WatchScope } from "./watch-types.js";
+import type { WatchEntry, WatchOptions, WatchScope } from "./watch-types.js";
 export type DirectoryIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
 export type WatchSnapshot = {
     entries: Map<string, string>;
+    excluded?: Map<string, WatchEntry["kind"]>;
+    excludedDirectories?: Map<string, string>;
+    directoryPaths?: Map<string, string>;
     directories: Map<string, DirectoryIdentity>;
     targets: Map<string, DirectoryIdentity>;
     scanned: number;
@@ -21,4 +24,5 @@ export declare function scanWatch(root: RootContext, scopes: readonly WatchScope
     maxDirectories: number;
     maxPendingPaths: number;
     admitting: boolean;
+    previous?: WatchSnapshot;
 }, signal: AbortSignal, register: (name: string, identity: DirectoryIdentity, guard: RootDirectoryObservationGuard) => Promise<void>, onCleanupFailure?: (error: unknown) => void): Promise<WatchSnapshot>;

package/dist/watch-scan.js

@@ -55,7 +55,9 @@ export function isWatchPathError(error) {
     return ["ENOTDIR", "EACCES", "EPERM", "EBUSY", "ESTALE", "EIO", "ELOOP"].includes(error?.code ?? "");
 }
 export async function scanWatch(root, scopes, options, signal, register, onCleanupFailure) {
-    const result = { entries: new Map(), directories: new Map(), targets: new Map(), scanned: 0 };
+    const exclusions = new Map();
+    const excludedDirectories = new Map(), directoryPaths = new Map();
+    const result = { entries: new Map(), excluded: exclusions, excludedDirectories, directoryPaths, directories: new Map(), targets: new Map(), scanned: 0 };
     const attempts = new Map();
     const guards = new Map();
     const walked = new Map();
@@ -68,7 +70,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
             result.overflow = true;
         // Discard partially observed names when their enclosing directory lost admission.
         const below = (name) => name === relative || !relative || name.startsWith(relative + path.sep);
-        for (const map of [result.entries, result.targets, result.directories, guards, walked]) {
+        for (const map of [result.entries, exclusions, excludedDirectories, directoryPaths, result.targets, result.directories, guards, walked]) {
             for (const name of map.keys())
                 if (below(name))
                     map.delete(name);
@@ -86,7 +88,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
         if (++result.scanned > options.maxEntries)
             throw new FsSafeError("too-large", "watch entry budget exceeded", { details: { operation: "scan" } });
     };
-    const excluded = (name, entry) => {
+    const excluded = async (name, entry) => {
         let value;
         try {
             value = options.exclude?.({ path: name, kind: kind(entry) });
@@ -96,6 +98,23 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
             throw new FsSafeError("helper-failed", "watch exclusion callback failed", { cause, details: { operation: "callback" } });
         }
         signal.throwIfAborted();
+        if (value) {
+            exclusions.set(name, kind(entry));
+            if (process.platform === "darwin" && entry.isDirectory && !entry.isSymbolicLink) {
+                try {
+                    const resolved = await resolvePathInRoot(root, "./" + name, { rejectSymlinks: true });
+                    const guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+                    await assertRootDirectoryObservationGuard(root, guard);
+                    excludedDirectories.set(name, guard.realPath);
+                }
+                catch (error) {
+                    signal.throwIfAborted();
+                    await assertRootIdentityCurrent(root);
+                    if (!isWatchPathError(error))
+                        throw error;
+                }
+            }
+        }
         return value;
     };
     const directory = async (relative) => {
@@ -121,6 +140,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 const guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
                 const identity = { dev: guard.stat.dev, ino: guard.stat.ino };
                 result.directories.set(relative, identity);
+                directoryPaths.set(relative, guard.realPath);
                 await register(relative, identity, guard);
                 signal.throwIfAborted();
                 await assertRootDirectoryObservationGuard(root, guard);
@@ -148,7 +168,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
             try {
                 guard = await directory(relative);
                 listing = await openRootDirectoryListing(root, guard.realPath, {
-                    order: "filesystem", snapshot: false, signal, exactIdentity: true, onCleanupFailure, admitEntry: () => { examined(); return true; },
+                    order: "filesystem", snapshot: false, signal, exactIdentity: true, skipVanished: true, onCleanupFailure, admitEntry: () => { examined(); return true; },
                 });
                 // The listing has its own guard. Both identities must agree before reading names.
                 await assertRootDirectoryObservationGuard(root, guard);
@@ -176,7 +196,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                     throw new FsSafeError("path-mismatch", "watch listing lacks exact identity");
                 const entry = next.entry;
                 const name = relative ? path.join(relative, entry.name) : entry.name;
-                if (excluded(name, entry))
+                if (await excluded(name, entry))
                     continue;
                 result.entries.set(name, fingerprint(entry, next.identity));
                 if (entry.isDirectory && !entry.isSymbolicLink && depth > 1)
@@ -229,7 +249,7 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
                 if (!found)
                     break;
                 const name = relative ? path.join(relative, segments[i]) : segments[i];
-                if (excluded(name, found.entry))
+                if (await excluded(name, found.entry))
                     break;
                 if (i === segments.length - 1) {
                     result.entries.set(name, fingerprint(found.entry, found.identity));
@@ -265,5 +285,16 @@ export async function scanWatch(root, scopes, options, signal, register, onClean
     }
     await assertRootIdentityCurrent(root);
     signal.throwIfAborted();
+    // Native deletion hints can arrive after a later scan. Keep bounded tombstones
+    // until the name is admitted again; they never grant authority to publish it.
+    for (const [name, kind] of options.previous?.excluded ?? []) {
+        if (exclusions.size >= options.maxEntries)
+            break;
+        if (!result.entries.has(name) && !result.directories.has(name) && !exclusions.has(name))
+            exclusions.set(name, kind);
+        const priorPath = options.previous?.excludedDirectories?.get(name);
+        if (kind === "directory" && exclusions.get(name) === "directory" && priorPath && !excludedDirectories.has(name))
+            excludedDirectories.set(name, priorPath);
+    }
     return result;
 }

package/dist/watch-stream.d.ts

@@ -0,0 +1,8 @@
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchScope } from "./watch-types.js";
+export type WatchStreamPaths = {
+    anchors: string[];
+    exclusions: string[];
+};
+/** Canonical names come only from guarded directory observations, never backend hints. */
+export declare function watchStreamPaths(snapshot: WatchSnapshot, scopes: readonly WatchScope[]): WatchStreamPaths;