@indigoai-us/hq-cloud 6.11.11 → 6.11.12

package/src/watcher.ts

@@ -163,7 +163,9 @@ export class WatchPushDriver {
     }
     this.timer = this.clock.setTimeout(() => {
       this.timer = null;
-      void this.fire();
+      void this.fire().catch((err) => {
+        console.error("WatchPushDriver push failed:", err);
+      });
     }, this.debounceMs);
   }
 
@@ -400,6 +402,36 @@ function supportsRecursiveWatch(): boolean {
   return process.platform === "darwin" || process.platform === "win32";
 }
 
+function startChokidarTreeWatch(
+  hqRoot: string,
+  shouldEmit: WatchPathFilter,
+  onEvent: (absolutePath: string) => void,
+  onError: (err: unknown) => void,
+): WatchBackend {
+  const cw = watch(hqRoot, {
+    // chokidar fallback (Linux): see toChokidarIgnored for why the descent
+    // probe must not prune ancestor dirs of allowlisted leaves.
+    ignored: toChokidarIgnored(shouldEmit, hqRoot),
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100,
+    },
+  });
+  cw.on("add", onEvent)
+    .on("change", onEvent)
+    .on("unlink", onEvent)
+    .on("addDir", onEvent)
+    .on("unlinkDir", onEvent)
+    .on("error", onError);
+  return {
+    close: () => {
+      void cw.close();
+    },
+  };
+}
+
 /**
  * Start watching `hqRoot`, calling `onEvent(absolutePath)` for every change.
  *
@@ -441,8 +473,39 @@ function startTreeWatch(
           onEvent(path.resolve(hqRoot, rel));
         },
       );
-      native.on("error", onError);
-      return { close: () => native.close() };
+      let closed = false;
+      let fallback: WatchBackend | null = null;
+      native.on("error", (err) => {
+        onError(err);
+        if (closed || fallback !== null) return;
+        try {
+          native.close();
+        } catch {
+          /* already closed */
+        }
+        try {
+          fallback = startChokidarTreeWatch(
+            hqRoot,
+            shouldEmit,
+            onEvent,
+            onError,
+          );
+        } catch (fallbackErr) {
+          onError(fallbackErr);
+        }
+      });
+      return {
+        close: () => {
+          closed = true;
+          try {
+            native.close();
+          } catch {
+            /* already closed */
+          }
+          fallback?.close();
+          fallback = null;
+        },
+      };
     } catch (err) {
       // Recursive watch unexpectedly unavailable — fall back to chokidar
       // rather than leaving the daemon with no watcher at all.
@@ -450,28 +513,7 @@ function startTreeWatch(
     }
   }
 
-  const cw = watch(hqRoot, {
-    // chokidar fallback (Linux): see toChokidarIgnored for why the descent
-    // probe must not prune ancestor dirs of allowlisted leaves.
-    ignored: toChokidarIgnored(shouldEmit, hqRoot),
-    persistent: true,
-    ignoreInitial: true,
-    awaitWriteFinish: {
-      stabilityThreshold: 500,
-      pollInterval: 100,
-    },
-  });
-  cw.on("add", onEvent)
-    .on("change", onEvent)
-    .on("unlink", onEvent)
-    .on("addDir", onEvent)
-    .on("unlinkDir", onEvent)
-    .on("error", onError);
-  return {
-    close: () => {
-      void cw.close();
-    },
-  };
+  return startChokidarTreeWatch(hqRoot, shouldEmit, onEvent, onError);
 }
 
 /**
@@ -533,6 +575,25 @@ export function createWatchPathFilter(
   };
 }
 
+export const DEFAULT_TREE_WATCHER_MAX_PENDING_PATHS = 4096;
+export const DEFAULT_TREE_WATCHER_MAX_PENDING_BYTES = 1024 * 1024;
+
+export interface TreeWatcherBacklogOverflow {
+  pendingPaths: number;
+  pendingBytes: number;
+  maxPendingPaths: number;
+  maxPendingBytes: number;
+  droppedPaths: number;
+  droppedBytes: number;
+}
+
+function estimatePendingEntryBytes(
+  absolutePath: string,
+  relativePath: string,
+): number {
+  return Buffer.byteLength(absolutePath) + Buffer.byteLength(relativePath) + 64;
+}
+
 export interface TreeWatcherOptions {
   /** Sync root to watch (== personal-vault root in personalMode). */
   hqRoot: string;
@@ -547,6 +608,12 @@ export interface TreeWatcherOptions {
    * from {@link createWatchPathFilter}.
    */
   pathFilter?: WatchPathFilter;
+  /** Maximum distinct paths retained in one debounce window. */
+  maxPendingPaths?: number;
+  /** Approximate maximum path-string bytes retained in one debounce window. */
+  maxPendingBytes?: number;
+  /** Backlog overflow signal. Defaults to a console warning. */
+  onBacklogOverflow?: (info: TreeWatcherBacklogOverflow) => void;
 }
 
 /**
@@ -569,6 +636,12 @@ export interface TreeWatcherOptions {
 export interface TreeChangeBatch {
   /** Map of absolutePath → relativePath for every path in the settled burst. */
   paths: Map<string, string>;
+  /** True when path detail was dropped after the watcher backlog cap was hit. */
+  overflowed?: boolean;
+  /** Count of paths dropped from the detailed batch after overflow. */
+  droppedPaths?: number;
+  /** Approximate path-string bytes dropped from the detailed batch. */
+  droppedBytes?: number;
 }
 
 /**
@@ -591,11 +664,19 @@ export class TreeWatcher {
   private readonly debounceMs: number;
   private readonly clock: Clock;
   private readonly shouldEmit: WatchPathFilter;
+  private readonly maxPendingPaths: number;
+  private readonly maxPendingBytes: number;
+  private readonly onBacklogOverflow: (info: TreeWatcherBacklogOverflow) => void;
   private backend: WatchBackend | null = null;
   private timer: unknown = null;
   private listeners = new Set<TreeChangeListener>();
   /** Paths accumulated for the current (in-flight) debounce window. */
   private pending = new Map<string, string>();
+  private pendingBytes = 0;
+  private overflowed = false;
+  private overflowLogged = false;
+  private droppedPaths = 0;
+  private droppedBytes = 0;
   private disposed = false;
 
   constructor(opts: TreeWatcherOptions) {
@@ -604,6 +685,21 @@ export class TreeWatcher {
     this.clock = opts.clock ?? systemClock;
     this.shouldEmit =
       opts.pathFilter ?? createWatchPathFilter(opts.hqRoot, opts.personalMode ?? false);
+    this.maxPendingPaths = Math.max(
+      1,
+      opts.maxPendingPaths ?? DEFAULT_TREE_WATCHER_MAX_PENDING_PATHS,
+    );
+    this.maxPendingBytes = Math.max(
+      1,
+      opts.maxPendingBytes ?? DEFAULT_TREE_WATCHER_MAX_PENDING_BYTES,
+    );
+    this.onBacklogOverflow =
+      opts.onBacklogOverflow ??
+      ((info) => {
+        console.warn(
+          `TreeWatcher backlog cap exceeded; dropping ${info.droppedPaths} path(s) until the next resync`,
+        );
+      });
   }
 
   /**
@@ -633,10 +729,19 @@ export class TreeWatcher {
       this.hqRoot,
       this.shouldEmit,
       (absolutePath) => this.handleEvent(absolutePath),
-      (err) => console.error("TreeWatcher error:", err),
+      (err) => {
+        console.error("TreeWatcher error:", err);
+        this.signalBackendResync();
+      },
     );
   }
 
+  private signalBackendResync(): void {
+    if (this.disposed) return;
+    this.overflowed = true;
+    this.arm();
+  }
+
   /**
    * Test/seam entry point: feed a raw filesystem path as if the backend
    * reported it. Applies the emit filter then arms the debounce. Real watch
@@ -651,10 +756,42 @@ export class TreeWatcher {
     if (!this.shouldEmit(absolutePath, false)) return;
     const abs = path.resolve(absolutePath);
     const rel = path.relative(this.hqRoot, abs).split(path.sep).join("/");
+    if (!this.pending.has(abs)) {
+      const entryBytes = estimatePendingEntryBytes(abs, rel);
+      if (
+        this.pending.size >= this.maxPendingPaths ||
+        this.pendingBytes + entryBytes > this.maxPendingBytes
+      ) {
+        this.recordBacklogOverflow(entryBytes);
+        this.arm();
+        return;
+      }
+      this.pendingBytes += entryBytes;
+    }
     this.pending.set(abs, rel);
     this.arm();
   }
 
+  private recordBacklogOverflow(entryBytes: number): void {
+    this.overflowed = true;
+    this.droppedPaths += 1;
+    this.droppedBytes += entryBytes;
+    if (this.overflowLogged) return;
+    this.overflowLogged = true;
+    try {
+      this.onBacklogOverflow({
+        pendingPaths: this.pending.size,
+        pendingBytes: this.pendingBytes,
+        maxPendingPaths: this.maxPendingPaths,
+        maxPendingBytes: this.maxPendingBytes,
+        droppedPaths: this.droppedPaths,
+        droppedBytes: this.droppedBytes,
+      });
+    } catch (err) {
+      console.error("TreeWatcher backlog overflow logger error:", err);
+    }
+  }
+
   private arm(): void {
     if (this.timer !== null) {
       this.clock.clearTimeout(this.timer);
@@ -671,7 +808,12 @@ export class TreeWatcher {
     // Snapshot + clear the accumulated paths so the next window starts fresh
     // even if a listener re-enters synchronously.
     const batch: TreeChangeBatch = { paths: new Map(this.pending) };
-    this.pending.clear();
+    if (this.overflowed) {
+      batch.overflowed = true;
+      batch.droppedPaths = this.droppedPaths;
+      batch.droppedBytes = this.droppedBytes;
+    }
+    this.clearPending();
     // First changed relative path of the burst — the US-003 routing argument.
     // undefined when the window settled with no captured path (e.g. a synthetic
     // arm() with no handleEvent).
@@ -685,6 +827,15 @@ export class TreeWatcher {
     }
   }
 
+  private clearPending(): void {
+    this.pending.clear();
+    this.pendingBytes = 0;
+    this.overflowed = false;
+    this.overflowLogged = false;
+    this.droppedPaths = 0;
+    this.droppedBytes = 0;
+  }
+
   /** True while the watch backend is active. */
   isWatching(): boolean {
     return this.backend !== null;
@@ -705,7 +856,7 @@ export class TreeWatcher {
       this.clock.clearTimeout(this.timer);
       this.timer = null;
     }
-    this.pending.clear();
+    this.clearPending();
     if (this.backend) {
       this.backend.close();
       this.backend = null;
@@ -792,6 +943,7 @@ export interface EmitterLogger {
  * running TreeWatcher (returns an unsubscribe fn). Flag-gated + failure-safe.
  */
 export class PushEventEmitter {
+  private static readonly MAX_CONCURRENT_PUBLISHES = 16;
   private readonly originTenantId: string;
   private readonly originDeviceId: string;
   private readonly transport: PushTransport;
@@ -801,6 +953,7 @@ export class PushEventEmitter {
   private readonly logger: EmitterLogger | undefined;
   private internalSeq = 0;
   private readonly nextSeq: () => number;
+  private publishTail: Promise<void> = Promise.resolve();
 
   constructor(opts: PushEventEmitterOptions) {
     this.originTenantId = opts.originTenantId;
@@ -848,12 +1001,35 @@ export class PushEventEmitter {
    */
   async emitForBatch(batch: TreeChangeBatch): Promise<void> {
     if (!this.enabled) return;
-    const entries = [...batch.paths.entries()];
-    await Promise.all(
-      entries.map(([absolutePath, relativePath]) =>
-        this.emitOne(absolutePath, relativePath),
-      ),
+    const entriesByRel = new Map<string, [string, string]>();
+    for (const [absolutePath, relativePath] of batch.paths.entries()) {
+      entriesByRel.set(relativePath, [absolutePath, relativePath]);
+    }
+    const entries = [...entriesByRel.values()];
+    const run = this.publishTail.then(
+      () => this.emitEntries(entries),
+      () => this.emitEntries(entries),
     );
+    this.publishTail = run.catch(() => undefined);
+    await run;
+  }
+
+  private async emitEntries(entries: Array<[string, string]>): Promise<void> {
+    for (
+      let i = 0;
+      i < entries.length;
+      i += PushEventEmitter.MAX_CONCURRENT_PUBLISHES
+    ) {
+      const chunk = entries.slice(
+        i,
+        i + PushEventEmitter.MAX_CONCURRENT_PUBLISHES,
+      );
+      await Promise.all(
+        chunk.map(([absolutePath, relativePath]) =>
+          this.emitOne(absolutePath, relativePath),
+        ),
+      );
+    }
   }
 
   private async emitOne(