@rljson/fs-agent 0.0.18 → 0.0.20

package/dist/fs-agent.d.ts

@@ -112,6 +112,14 @@ export interface TimeoutConfig {
      */
     recoveryRetries?: number;
 }
+/**
+ * Longest a disconnect may keep the watcher paused.
+ *
+ * Generous enough for an ordinary reconnect, short enough that a reconnect
+ * which never arrives costs a few seconds of missed notifications rather than
+ * every write from then on.
+ */
+export declare const DISCONNECT_PAUSE_MAX_MS = 30000;
 /** Filename for sync error log written to the sync folder */
 export declare const SYNC_ERROR_FILE = ".sync-errors.log";
 /**
@@ -141,6 +149,16 @@ export declare class FsAgent {
     private _lastAppliedRef?;
     /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
     private _lastSentContentKey?;
+    /**
+     * True while a ref received from a peer is being applied to disk.
+     *
+     * The safety rescan cannot tell a local change the watcher missed (which it
+     * must broadcast) from a remote change not yet applied here (which it must
+     * not). The agent can: while this is set, the disk is mid-way through
+     * someone else's revision, so a rescan-driven push would re-assert our stale
+     * view — and undo a deletion the peer just made.
+     */
+    private _remoteApplyInFlight;
     private _timeouts;
     /** Client-only: resolve DAG-branch conflicts into merge revisions. */
     private _resolveConflicts;
@@ -406,6 +424,25 @@ export declare class FsAgent {
      * @param map - Content map (relativePath → blobId)
      */
     private _contentKeyFromMap;
+    /**
+     * Records `treeRef` as the ref describing this folder's current state, and
+     * retires the one it supersedes from the connector's dedup sets.
+     *
+     * A tree ref is a pure content hash, so a folder that returns to an earlier
+     * state re-derives that state's exact ref. The connector drops an incoming
+     * ref it has already received, which assumes a state is reached once and
+     * never returned to — false for content-addressed state, and false in the
+     * most ordinary way possible: create a file, then delete it again.
+     *
+     * Retiring the SUPERSEDED ref is what keeps the return trip deliverable.
+     * The ref just adopted stays deduped, so a peer re-advertising the state
+     * this folder is actually in is still suppressed as the echo it is. That
+     * only works if every adopted state passes through here — a state adopted
+     * silently is never retired and blocks its own return for good.
+     * @param connector - Connector whose dedup sets to retire from.
+     * @param treeRef - The ref that now describes this folder.
+     */
+    private _adoptAppliedRef;
     /**
      * Derives a deterministic content key from an FsTree.
      * @param tree - Tree structure to derive content key from

package/dist/fs-agent.js

@@ -413,6 +413,9 @@ class FsDbAdapter {
     return this.db;
   }
 }
+const _envRescan = Number(process.env["RLJSON_FS_RESCAN_MS"]);
+const SAFETY_RESCAN_INTERVAL_MS = Number.isFinite(_envRescan) && _envRescan > 0 ? _envRescan : 5e3;
+const STUCK_PAUSE_MS = 15e3;
 class FsScanner {
   _rootPath;
   _tree = null;
@@ -424,6 +427,10 @@ class FsScanner {
   _missedChangesDuringPause = false;
   /** Periodic full-rescan timer that catches events the native watcher drops. */
   _safetyTimer = null;
+  /** When the current pause began, or null when not paused. */
+  _pausedAt = null;
+  /** Releases a pause whose resume never arrived (see {@link pauseWatch}). */
+  _autoResumeTimer = null;
   /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
   _stopRequested = false;
   /** Path→content cache backing {@link FsScanOptions.scanCachePath} (unused when unset). */
@@ -434,6 +441,8 @@ class FsScanner {
   _nextBlobCache = /* @__PURE__ */ new Map();
   /** Ensures the persisted cache is read from disk only once. */
   _cacheLoaded = false;
+  /** Entries that vanished mid-scan, counted per {@link scan} for one summary. */
+  _vanishedDuringScan = 0;
   constructor(rootPath, options = {}) {
     this._rootPath = rootPath;
     this._options = {
@@ -478,6 +487,7 @@ class FsScanner {
       this._nextBlobCache = /* @__PURE__ */ new Map();
     }
     const trees = /* @__PURE__ */ new Map();
+    this._vanishedDuringScan = 0;
     let rootTree;
     try {
       rootTree = await this._scanDirectory(this._rootPath, ".", 0, trees);
@@ -493,6 +503,11 @@ class FsScanner {
         "Failed to generate hash for root tree. Tree structure may be invalid."
       );
     }
+    if (this._vanishedDuringScan > 0) {
+      console.warn(
+        `[fs-scanner] ${this._vanishedDuringScan} entr${this._vanishedDuringScan === 1 ? "y" : "ies"} vanished during the scan of ${this._rootPath} — skipped; the next scan picks up the settled state`
+      );
+    }
     trees.set(rootHashStr, rootTree);
     this._tree = {
       rootHash: rootHashStr,
@@ -506,6 +521,7 @@ class FsScanner {
   }
   async _scanDirectory(absolutePath, relativePath, depth, trees) {
     const entries = await readdir(absolutePath, { withFileTypes: true });
+    const childTrees = [];
     const childRefs = [];
     for (const entry of entries) {
       if (this._shouldIgnore(entry.name)) {
@@ -519,78 +535,87 @@ class FsScanner {
       if (this._options.maxDepth !== void 0 && depth >= this._options.maxDepth) {
         continue;
       }
-      const childStats = await stat(childPath);
-      if (entry.isDirectory()) {
-        const childTree = await this._scanDirectory(
-          childPath,
-          childRelPath,
-          depth + 1,
-          trees
-        );
-        hip(childTree);
-        const childHashStr = childTree._hash;
-        trees.set(childHashStr, childTree);
-        childRefs.push(childHashStr);
-      } else if (entry.isFile()) {
-        const mtimeMs = childStats.mtime.getTime();
-        const cached = this._scanCachePath ? this._blobCache.get(childRelPath) : void 0;
-        let blobId;
-        if (cached && cached.mtime === mtimeMs && cached.size === childStats.size) {
-          blobId = cached.blobId;
-        } else {
-          let fileContent;
-          try {
-            fileContent = await readFile(childPath);
-          } catch (error) {
-            throw new Error(
-              `Failed to read file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
-            );
-          }
-          let blobProps;
-          try {
-            blobProps = await this._bs.setBlob(fileContent);
-          } catch (error) {
-            throw new Error(
-              `Failed to store blob for file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
-            );
+      try {
+        const childStats = await stat(childPath);
+        if (entry.isDirectory()) {
+          const childTree = await this._scanDirectory(
+            childPath,
+            childRelPath,
+            depth + 1,
+            trees
+          );
+          childTrees.push(childTree);
+          hip(childTree);
+          const childHashStr = childTree._hash;
+          trees.set(childHashStr, childTree);
+          childRefs.push(childHashStr);
+        } else if (entry.isFile()) {
+          const mtimeMs = childStats.mtime.getTime();
+          const cached = this._scanCachePath ? this._blobCache.get(childRelPath) : void 0;
+          let blobId;
+          if (cached && cached.mtime === mtimeMs && cached.size === childStats.size) {
+            blobId = cached.blobId;
+          } else {
+            let fileContent;
+            try {
+              fileContent = await readFile(childPath);
+            } catch (error) {
+              if (FsScanner._isVanished(error)) throw error;
+              throw new Error(
+                `Failed to read file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
+            let blobProps;
+            try {
+              blobProps = await this._bs.setBlob(fileContent);
+            } catch (error) {
+              throw new Error(
+                `Failed to store blob for file "${childRelPath}": ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
+            if (!blobProps || !blobProps.blobId) {
+              throw new Error(
+                `Blob storage returned invalid blobId for file "${childRelPath}"`
+              );
+            }
+            blobId = blobProps.blobId;
           }
-          if (!blobProps || !blobProps.blobId) {
-            throw new Error(
-              `Blob storage returned invalid blobId for file "${childRelPath}"`
-            );
+          if (this._scanCachePath) {
+            this._nextBlobCache.set(childRelPath, {
+              mtime: mtimeMs,
+              size: childStats.size,
+              blobId
+            });
           }
-          blobId = blobProps.blobId;
-        }
-        if (this._scanCachePath) {
-          this._nextBlobCache.set(childRelPath, {
-            mtime: mtimeMs,
+          const fileMeta = {
+            name: entry.name,
+            type: "file",
+            relativePath: childRelPath,
             size: childStats.size,
+            // mtime is kept for files (restore preserves it, so it round-trips to
+            // the same ref on every client) but NOT for directories (a folder's
+            // mtime is per-machine and does not round-trip). The absolute `path`
+            // is excluded everywhere — it is folder-specific.
+            mtime: mtimeMs,
             blobId
-          });
+            // Link to content in Bs
+          };
+          const fileTree = {
+            id: entry.name,
+            isParent: false,
+            meta: fileMeta,
+            children: null
+          };
+          childTrees.push(fileTree);
+          hip(fileTree);
+          const fileTreeHashStr = fileTree._hash;
+          trees.set(fileTreeHashStr, fileTree);
+          childRefs.push(fileTreeHashStr);
         }
-        const fileMeta = {
-          name: entry.name,
-          type: "file",
-          relativePath: childRelPath,
-          size: childStats.size,
-          // mtime is kept for files (restore preserves it, so it round-trips to
-          // the same ref on every client) but NOT for directories (a folder's
-          // mtime is per-machine and does not round-trip). The absolute `path`
-          // is excluded everywhere — it is folder-specific.
-          mtime: mtimeMs,
-          blobId
-          // Link to content in Bs
-        };
-        const fileTree = {
-          id: entry.name,
-          isParent: false,
-          meta: fileMeta,
-          children: null
-        };
-        hip(fileTree);
-        const fileTreeHashStr = fileTree._hash;
-        trees.set(fileTreeHashStr, fileTree);
-        childRefs.push(fileTreeHashStr);
+      } catch (error) {
+        if (!FsScanner._isVanished(error)) throw error;
+        this._vanishedDuringScan++;
+        continue;
       }
     }
     const dirName = relativePath === "." ? "." : (
@@ -697,7 +722,7 @@ class FsScanner {
     if (!this._safetyTimer) {
       this._safetyTimer = setInterval(() => {
         void this._runSafetyRescan();
-      }, 3e4);
+      }, SAFETY_RESCAN_INTERVAL_MS);
       this._safetyTimer.unref?.();
     }
   }
@@ -708,7 +733,10 @@ class FsScanner {
    * scan failures are no-ops.
    */
   async _runSafetyRescan() {
-    if (this._paused || this._stopRequested) return;
+    if (this._stopRequested) return;
+    if (this._paused && !this._pauseLooksStuck({ type: "safety-rescan", path: "." })) {
+      return;
+    }
     const prevKey = this._tree ? this._safetyContentKey(this._tree) : null;
     try {
       await this.scan();
@@ -718,7 +746,7 @@ class FsScanner {
       );
       return;
     }
-    if (this._paused || this._stopRequested) return;
+    if (this._stopRequested) return;
     const nextKey = this._tree ? this._safetyContentKey(this._tree) : null;
     if (prevKey !== nextKey) {
       console.warn(
@@ -756,6 +784,20 @@ class FsScanner {
   static _errMessage(err) {
     return err instanceof Error ? err.message : String(err);
   }
+  /**
+   * Whether a caught value is a "no longer there" filesystem error.
+   *
+   * A scan walks a directory that is still being written to. `readdir` returns
+   * a name, and by the time the entry is `stat`ed, read, or descended into it
+   * can be gone — a save-and-rename editor, a build tool, a peer applying a
+   * deletion. That is ordinary, not exceptional.
+   * @param err - The caught value.
+   * @returns `true` for ENOENT / ENOTDIR.
+   */
+  static _isVanished(err) {
+    const code = err?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+  }
   /** Whether the host is Windows — gates Windows-specific watcher hardening. */
   static get _isWindows() {
     return process.platform === "win32";
@@ -819,8 +861,24 @@ class FsScanner {
     }
     return void 0;
   }
+  /**
+   * Whether this notification should escape the pause.
+   *
+   * Only the safety rescan may, and only once the pause has outlasted any
+   * plausible restore. Letting it through a SHORT pause reintroduces exactly
+   * the echo the pause prevents — a rescan firing mid-restore notifies, the
+   * agent stores a tree built from half-restored files, and delete propagation
+   * breaks (caught by the client-server suite, not by unit tests).
+   * @param change - The pending notification.
+   * @returns `true` when the pause has lasted long enough to look stuck.
+   */
+  _pauseLooksStuck(change) {
+    if (change.type !== "safety-rescan") return false;
+    if (this._pausedAt === null) return false;
+    return Date.now() - this._pausedAt >= STUCK_PAUSE_MS;
+  }
   async _notifyChange(change) {
-    if (this._paused) {
+    if (this._paused && !this._pauseLooksStuck(change)) {
       return;
     }
     for (const callback of this._changeCallbacks) {
@@ -837,6 +895,10 @@ class FsScanner {
   }
   stopWatch() {
     this._stopRequested = true;
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
     if (this._safetyTimer) {
       clearInterval(this._safetyTimer);
       this._safetyTimer = null;
@@ -847,12 +909,37 @@ class FsScanner {
     }
   }
   /**
-   * Temporarily pause file change notifications
-   * Used to prevent loops when updating filesystem from external source
+   * Temporarily pause file change notifications, so an external restore does
+   * not loop back as a local change.
+   *
+   * `autoResumeMs` bounds the pause. A pause taken on socket disconnect is
+   * released by the matching reconnect — and when that reconnect never fires,
+   * an unbounded pause silences the node permanently. A bounded one degrades
+   * to a little duplicate work instead, which is the right way round: the
+   * loop-suppression this exists for is an optimisation, staying alive is not.
+   * @param autoResumeMs - Release the pause after this many milliseconds.
+   *   Omit to pause until an explicit `resumeWatch()`.
    */
-  pauseWatch() {
+  pauseWatch(autoResumeMs) {
+    if (!this._paused) this._pausedAt = Date.now();
     this._paused = true;
     this._missedChangesDuringPause = false;
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
+    if (autoResumeMs !== void 0) {
+      this._autoResumeTimer = setTimeout(() => {
+        this._autoResumeTimer = null;
+        if (this._paused) {
+          console.warn(
+            `[fs-scanner] pause exceeded ${autoResumeMs}ms without a resume — releasing it so ${this._rootPath} keeps syncing`
+          );
+          this.resumeWatch();
+        }
+      }, autoResumeMs);
+      this._autoResumeTimer.unref?.();
+    }
   }
   /**
    * Resume file change notifications.
@@ -860,8 +947,13 @@ class FsScanner {
    * an asynchronous rescan so that syncToDb can detect and push the changes.
    */
   resumeWatch() {
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
     const missedChanges = this._missedChangesDuringPause;
     this._paused = false;
+    this._pausedAt = null;
     this._missedChangesDuringPause = false;
     if (missedChanges) {
       void this._rescanAfterPause();
@@ -921,6 +1013,7 @@ const DEFAULT_TIMEOUTS = {
   processRefRetryDelayMs: 5e3,
   recoveryRetries: 10
 };
+const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 class FsAgent {
@@ -941,6 +1034,16 @@ class FsAgent {
   _lastAppliedRef;
   /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
   _lastSentContentKey;
+  /**
+   * True while a ref received from a peer is being applied to disk.
+   *
+   * The safety rescan cannot tell a local change the watcher missed (which it
+   * must broadcast) from a remote change not yet applied here (which it must
+   * not). The agent can: while this is set, the disk is mid-way through
+   * someone else's revision, so a rescan-driven push would re-assert our stale
+   * view — and undo a deletion the peer just made.
+   */
+  _remoteApplyInFlight = false;
   _timeouts;
   /** Client-only: resolve DAG-branch conflicts into merge revisions. */
   _resolveConflicts;
@@ -1537,7 +1640,10 @@ ${err.stack}` : String(err);
       );
     }
     let debounceTimer = null;
-    const debouncedSync = () => {
+    const debouncedSync = (change) => {
+      if (change?.type === "safety-rescan" && this._remoteApplyInFlight) {
+        return;
+      }
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(async () => {
         debounceTimer = null;
@@ -1726,6 +1832,30 @@ ${err.stack}` : String(err);
     );
     return sorted.map(([p, b]) => `${p}:${b}`).join("\n");
   }
+  /**
+   * Records `treeRef` as the ref describing this folder's current state, and
+   * retires the one it supersedes from the connector's dedup sets.
+   *
+   * A tree ref is a pure content hash, so a folder that returns to an earlier
+   * state re-derives that state's exact ref. The connector drops an incoming
+   * ref it has already received, which assumes a state is reached once and
+   * never returned to — false for content-addressed state, and false in the
+   * most ordinary way possible: create a file, then delete it again.
+   *
+   * Retiring the SUPERSEDED ref is what keeps the return trip deliverable.
+   * The ref just adopted stays deduped, so a peer re-advertising the state
+   * this folder is actually in is still suppressed as the echo it is. That
+   * only works if every adopted state passes through here — a state adopted
+   * silently is never retired and blocks its own return for good.
+   * @param connector - Connector whose dedup sets to retire from.
+   * @param treeRef - The ref that now describes this folder.
+   */
+  _adoptAppliedRef(connector, treeRef) {
+    if (this._lastAppliedRef && this._lastAppliedRef !== treeRef) {
+      connector.invalidateSent?.(this._lastAppliedRef);
+    }
+    this._lastAppliedRef = treeRef;
+  }
   /**
    * Derives a deterministic content key from an FsTree.
    * @param tree - Tree structure to derive content key from
@@ -1816,6 +1946,7 @@ ${err.stack}` : String(err);
       const maxAttempts = this._timeouts.processRefRetries + 1;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         this._scanner.pauseWatch();
+        this._remoteApplyInFlight = true;
         try {
           const incomingTree = await FsAgent._withTimeout(
             this._fetchTreeFromDb(db, treeKey, treeRef),
@@ -1837,6 +1968,7 @@ ${err.stack}` : String(err);
             console.log(
               `[FsAgent] syncFromDb: equivalent content, skipping restore (incoming=${incomingFiles.size} entries, current=${currentFiles.size} entries, ref=${treeRef.slice(0, 8)}…)`
             );
+            this._adoptAppliedRef(connector, treeRef);
             return;
           }
           if (this._resolveConflicts && this._currentRef && predecessorRefs && predecessorRefs.length > 0) {
@@ -1877,10 +2009,7 @@ ${err.stack}` : String(err);
             skipNotification: true,
             previous
           });
-          if (this._lastAppliedRef && this._lastAppliedRef !== treeRef) {
-            connector.invalidateSent?.(this._lastAppliedRef);
-          }
-          this._lastAppliedRef = treeRef;
+          this._adoptAppliedRef(connector, treeRef);
           this._lastSentRef = postRestoreRef;
           this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
           this._currentRef = postRestoreRef;
@@ -1914,6 +2043,7 @@ ${err.stack}` : String(err);
             );
           }
         } finally {
+          this._remoteApplyInFlight = false;
           this._scanner.resumeWatch();
         }
         await new Promise(
@@ -1922,6 +2052,9 @@ ${err.stack}` : String(err);
       }
     };
     const scheduleProcess = (ref, delayMs, recoveryAttempt, predecessorRefs) => {
+      if (pendingRef && pendingRef !== ref) {
+        connector.invalidateReceived(pendingRef);
+      }
       pendingRef = ref;
       pendingRecoveryAttempt = recoveryAttempt;
       pendingPredecessorRefs = predecessorRefs;
@@ -2002,7 +2135,7 @@ ${err.stack}` : String(err);
     };
     if (typeof client.onDisconnect === "function") {
       client.onDisconnect(() => {
-        agent.scanner.pauseWatch();
+        agent.scanner.pauseWatch(DISCONNECT_PAUSE_MAX_MS);
       });
     }
     if (typeof client.onReconnect === "function") {

package/dist/fs-scanner.d.ts

@@ -1,6 +1,16 @@
 import { Bs } from '@rljson/bs';
 import { Json } from '@rljson/json';
 import { Tree, TreeRef } from '@rljson/rljson';
+export declare const SAFETY_RESCAN_INTERVAL_MS: number;
+/**
+ * How long a pause must last before the safety rescan treats it as stuck and
+ * reports through it.
+ *
+ * Longer than any restore takes, so ordinary loop-suppression is untouched;
+ * short enough that a pause whose resume never arrives costs seconds, not
+ * every write from then on.
+ */
+export declare const STUCK_PAUSE_MS = 15000;
 /**
  * Metadata stored in Tree.meta for file system nodes
  */
@@ -93,6 +103,10 @@ export declare class FsScanner {
     private _missedChangesDuringPause;
     /** Periodic full-rescan timer that catches events the native watcher drops. */
     private _safetyTimer;
+    /** When the current pause began, or null when not paused. */
+    private _pausedAt;
+    /** Releases a pause whose resume never arrived (see {@link pauseWatch}). */
+    private _autoResumeTimer;
     /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
     private _stopRequested;
     /** Path→content cache backing {@link FsScanOptions.scanCachePath} (unused when unset). */
@@ -103,6 +117,8 @@ export declare class FsScanner {
     private _nextBlobCache;
     /** Ensures the persisted cache is read from disk only once. */
     private _cacheLoaded;
+    /** Entries that vanished mid-scan, counted per {@link scan} for one summary. */
+    private _vanishedDuringScan;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
     get rootPath(): string;
@@ -142,19 +158,50 @@ export declare class FsScanner {
      * @returns A message string
      */
     private static _errMessage;
+    /**
+     * Whether a caught value is a "no longer there" filesystem error.
+     *
+     * A scan walks a directory that is still being written to. `readdir` returns
+     * a name, and by the time the entry is `stat`ed, read, or descended into it
+     * can be gone — a save-and-rename editor, a build tool, a peer applying a
+     * deletion. That is ordinary, not exceptional.
+     * @param err - The caught value.
+     * @returns `true` for ENOENT / ENOTDIR.
+     */
+    private static _isVanished;
     /** Whether the host is Windows — gates Windows-specific watcher hardening. */
     private static get _isWindows();
     private _handleFileChange;
     private _findTreeByPath;
+    /**
+     * Whether this notification should escape the pause.
+     *
+     * Only the safety rescan may, and only once the pause has outlasted any
+     * plausible restore. Letting it through a SHORT pause reintroduces exactly
+     * the echo the pause prevents — a rescan firing mid-restore notifies, the
+     * agent stores a tree built from half-restored files, and delete propagation
+     * breaks (caught by the client-server suite, not by unit tests).
+     * @param change - The pending notification.
+     * @returns `true` when the pause has lasted long enough to look stuck.
+     */
+    private _pauseLooksStuck;
     private _notifyChange;
     onChange(callback: FsChangeCallback): void;
     offChange(callback: FsChangeCallback): void;
     stopWatch(): void;
     /**
-     * Temporarily pause file change notifications
-     * Used to prevent loops when updating filesystem from external source
+     * Temporarily pause file change notifications, so an external restore does
+     * not loop back as a local change.
+     *
+     * `autoResumeMs` bounds the pause. A pause taken on socket disconnect is
+     * released by the matching reconnect — and when that reconnect never fires,
+     * an unbounded pause silences the node permanently. A bounded one degrades
+     * to a little duplicate work instead, which is the right way round: the
+     * loop-suppression this exists for is an optimisation, staying alive is not.
+     * @param autoResumeMs - Release the pause after this many milliseconds.
+     *   Omit to pause until an explicit `resumeWatch()`.
      */
-    pauseWatch(): void;
+    pauseWatch(autoResumeMs?: number): void;
     /**
      * Resume file change notifications.
      * If any filesystem events were missed during the pause, triggers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@rljson/bs": "^0.0.21",
-    "@rljson/db": "^0.0.30",
+    "@rljson/db": "^0.0.31",
     "@rljson/hash": "^0.0.18",
     "@rljson/io": "^0.0.66",
     "@rljson/json": "^0.0.23",