@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/watcher.ts

@@ -1,1741 +0,0 @@
-/**
- * File watcher — monitors HQ directory for changes
- * Uses chokidar with debounced batching
- *
- * Active watcher path: TreeWatcher detects local changes, WatchPushDriver
- * schedules pushes, and PushEventEmitter publishes typed push events.
- */
-
-import * as fs from "fs";
-import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
-import * as path from "path";
-import { watch } from "chokidar";
-import { createIgnoreFilter } from "./ignore.js";
-import {
-  isCoveredByRecursiveRoot,
-  planWatchRoots,
-  type WatchRootPlan,
-} from "./watch-roots.js";
-import { vaultKeyForLocalPath } from "./local-path-codec.js";
-import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
-import {
-  AGENCY_SYNC_REL,
-  CONTINUITY_POINTER_REL,
-  SESSION_LOGS_SYNC_REL,
-  PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
-} from "./personal-vault.js";
-import type { PushEvent } from "./sync/push-event.js";
-import type { PushTransport } from "./sync/push-transport.js";
-import type { EventDrivenPushFlagProvider } from "./sync/feature-flags.js";
-import {
-  emitCloudTelemetry,
-  type CloudTelemetryClient,
-  type TelemetryClaims,
-} from "./telemetry-events.js";
-
-const DEBOUNCE_MS = 2000;
-
-/**
- * A single Linux chokidar watcher must leave room for editors, dev servers,
- * and other HQ runners on the same uid. This is deliberately far below the
- * common 250k kernel maximum. The cap is on distinct directories admitted over
- * this watcher's lifetime, which also prevents a high-churn tree from slowly
- * accumulating an unbounded set of kernel watches.
- */
-export const DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS = 20_000;
-export const TREE_WATCHER_MAX_WATCHED_PATHS_ENV = "HQ_SYNC_MAX_WATCHED_PATHS";
-
-function resolveMaxWatchedPaths(override: number | undefined): number {
-  const configured = override ?? Number(process.env[TREE_WATCHER_MAX_WATCHED_PATHS_ENV]);
-  if (override === undefined && process.env[TREE_WATCHER_MAX_WATCHED_PATHS_ENV] === undefined) {
-    return DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS;
-  }
-  if (Number.isFinite(configured) && configured > 0) return Math.trunc(configured);
-  console.warn(
-    `TreeWatcher ignoring invalid ${TREE_WATCHER_MAX_WATCHED_PATHS_ENV}; using ${DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS}`,
-  );
-  return DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS;
-}
-
-/**
- * Injectable clock seam (US-001).
- *
- * Production code uses the host timers; tests inject a {@link FakeClock} so the
- * debounce window can be advanced deterministically without real wall-clock
- * sleeps. US-002 (real chokidar watcher) and US-003 (runner wiring) build on
- * this same seam — keep the surface minimal and stable.
- */
-export interface Clock {
-  /** Schedule `fn` to run after `ms`. Returns an opaque handle. */
-  setTimeout(fn: () => void, ms: number): unknown;
-  /** Cancel a previously scheduled timeout. Safe to call with a stale handle. */
-  clearTimeout(handle: unknown): void;
-  /** Current epoch milliseconds. */
-  now(): number;
-}
-
-/** Real clock backed by host timers + Date.now. The production default. */
-export const systemClock: Clock = {
-  setTimeout: (fn, ms) => setTimeout(fn, ms),
-  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
-  now: () => Date.now(),
-};
-
-interface FakeTimer {
-  id: number;
-  fireAt: number;
-  fn: () => void;
-}
-
-/**
- * Deterministic clock for tests. Advance virtual time with {@link advance};
- * any timers whose deadline has passed fire in scheduled order. No real timers
- * are ever created, so a test using only this clock leaks nothing.
- */
-export class FakeClock implements Clock {
-  private current = 0;
-  private nextId = 1;
-  private timers = new Map<number, FakeTimer>();
-
-  now(): number {
-    return this.current;
-  }
-
-  setTimeout(fn: () => void, ms: number): unknown {
-    const id = this.nextId++;
-    this.timers.set(id, { id, fireAt: this.current + Math.max(0, ms), fn });
-    return id;
-  }
-
-  clearTimeout(handle: unknown): void {
-    if (typeof handle === "number") this.timers.delete(handle);
-  }
-
-  /**
-   * Advance virtual time by `ms`, firing every timer whose deadline falls in
-   * the interval (in deadline order). Timers scheduled by a firing callback are
-   * honored within the same advance if their new deadline is still within the
-   * advanced window.
-   */
-  advance(ms: number): void {
-    const target = this.current + ms;
-    while (true) {
-      const due = [...this.timers.values()]
-        .filter((t) => t.fireAt <= target)
-        .sort((a, b) => a.fireAt - b.fireAt || a.id - b.id);
-      if (due.length === 0) break;
-      const next = due[0];
-      this.timers.delete(next.id);
-      this.current = Math.max(this.current, next.fireAt);
-      next.fn();
-    }
-    this.current = target;
-  }
-
-  /** Number of timers still pending — a leak check for tests. */
-  pendingTimerCount(): number {
-    return this.timers.size;
-  }
-}
-
-/** A push pass to run when a debounced change settles. May be async. */
-export type PushFn = () => void | Promise<void>;
-
-export interface WatchPushDriverOptions {
-  /** Quiet window (ms) before a settled change triggers a push. */
-  debounceMs?: number;
-  /** Clock seam — defaults to {@link systemClock}; tests inject {@link FakeClock}. */
-  clock?: Clock;
-  /** Push pass to invoke when the window settles. */
-  push: PushFn;
-}
-
-/**
- * The reusable debounce + coalesce + concurrency-guard core of event-driven
- * push (US-001 seam).
- *
- * It is intentionally decoupled from chokidar and from S3: callers feed it
- * synthetic or real change notifications via {@link notifyChange}, and it
- * invokes the injected `push` fn at most once per quiet window. A push that is
- * still in flight is never overlapped — a change arriving mid-push is collapsed
- * and re-triggers a single follow-up pass after the next quiet window.
- *
- * US-002 wires a real chokidar watcher's events into {@link notifyChange};
- * US-003 supplies the targeted-push `push` fn. Tests drive it directly with a
- * {@link FakeClock} and a spy `push` fn (no real S3, no 10-minute sleep).
- */
-export class WatchPushDriver {
-  private readonly debounceMs: number;
-  private readonly clock: Clock;
-  private readonly push: PushFn;
-  private timer: unknown = null;
-  private pushing = false;
-  private pendingWhilePushing = false;
-  private disposed = false;
-
-  constructor(opts: WatchPushDriverOptions) {
-    this.debounceMs = opts.debounceMs ?? DEBOUNCE_MS;
-    this.clock = opts.clock ?? systemClock;
-    this.push = opts.push;
-  }
-
-  /**
-   * Register a change. Resets the quiet window; the push fires `debounceMs`
-   * after the LAST change in a burst, coalescing the burst to one push.
-   */
-  notifyChange(): void {
-    if (this.disposed) return;
-    if (this.timer !== null) {
-      this.clock.clearTimeout(this.timer);
-      this.timer = null;
-    }
-    this.timer = this.clock.setTimeout(() => {
-      this.timer = null;
-      void this.fire().catch((err) => {
-        console.error("WatchPushDriver push failed:", err);
-      });
-    }, this.debounceMs);
-  }
-
-  private async fire(): Promise<void> {
-    if (this.disposed) return;
-    if (this.pushing) {
-      // A pass is in flight — collapse this trigger; re-arm after it settles.
-      this.pendingWhilePushing = true;
-      return;
-    }
-    this.pushing = true;
-    try {
-      await this.push();
-    } finally {
-      this.pushing = false;
-      if (this.pendingWhilePushing && !this.disposed) {
-        this.pendingWhilePushing = false;
-        // Re-arm a fresh quiet window for the change(s) seen mid-push.
-        this.notifyChange();
-      }
-    }
-  }
-
-  /** True while a push pass is executing. */
-  isPushing(): boolean {
-    return this.pushing;
-  }
-
-  /** Cancel any pending debounce timer; idempotent. Leaves no timers behind. */
-  dispose(): void {
-    this.disposed = true;
-    if (this.timer !== null) {
-      this.clock.clearTimeout(this.timer);
-      this.timer = null;
-    }
-    this.pendingWhilePushing = false;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// US-002 — debounced, ignore-aware, exclusion-aware tree watcher.
-//
-// TreeWatcher is a pure change detector: it emits a single debounced `changed`
-// callback after a quiet window and never touches S3 itself. US-003 wires that
-// callback to a targeted push.
-//
-// The emit decision composes the SAME filter stack the push walk uses, so a
-// path that the push would skip never wakes the watcher:
-//   1. createIgnoreFilter  — .hqignore/.gitignore/DEFAULT_IGNORES
-//   2. PERSONAL_VAULT_DEFAULT_EXCLUSIONS (personalMode) — .env/output/.beads/…
-//   3. PERSONAL_VAULT_EXCLUDED_TOP_LEVEL (personalMode) — .git/companies/repos/workspace
-// ---------------------------------------------------------------------------
-
-/** Decision for a single path: emit a change for it, or ignore it. */
-export type WatchPathFilter = (absolutePath: string, isDir?: boolean) => boolean;
-
-export interface TreeWatcherWatchBudgetExceeded {
-  maxWatchedPaths: number;
-  watchedPaths: number;
-  /** Absolute directory whose admission would exceed the cap. */
-  offendingPath: string;
-}
-
-/**
- * Tracks directories admitted to chokidar. Chokidar asks its ignored callback
- * twice: before stat (the descent gate) and after stat (where we can safely
- * account only for directories). This class is intentionally lifetime-bounded:
- * a directory that is deleted and recreated cannot turn one long-running
- * runner into an unbounded consumer.
- */
-export class ChokidarWatchBudget {
-  private readonly admitted = new Set<string>();
-  private exhausted = false;
-
-  constructor(
-    private readonly maxWatchedPaths: number,
-    private readonly onExceeded: (info: TreeWatcherWatchBudgetExceeded) => void,
-  ) {}
-
-  admit(absolutePath: string): boolean {
-    const resolved = path.resolve(absolutePath);
-    if (this.admitted.has(resolved)) return true;
-    if (this.exhausted || this.admitted.size >= this.maxWatchedPaths) {
-      if (!this.exhausted) {
-        this.exhausted = true;
-        this.onExceeded({
-          maxWatchedPaths: this.maxWatchedPaths,
-          watchedPaths: this.admitted.size,
-          offendingPath: resolved,
-        });
-      }
-      return false;
-    }
-    this.admitted.add(resolved);
-    return true;
-  }
-
-  count(): number {
-    return this.admitted.size;
-  }
-}
-
-/**
- * Translate the emit filter into chokidar's descent predicate.
- *
- * Chokidar first calls this with no stats, before it has chosen whether to
- * recurse. That call is a DIRECTORY question, not an event-emission question:
- * consulting `shouldEmit(path, false)` here lets directory-only ignores such
- * as `node_modules/` masquerade as files and opens their whole subtree. The
- * directory branch of createIgnoreFilter already contains the exact
- * `.hqinclude` ancestor matcher, so it is both safe and sufficient to consult
- * `shouldEmit(path, true)` at this gate.
- */
-export function toChokidarIgnored(
-  shouldEmit: WatchPathFilter,
-  hqRoot: string,
-  budget?: ChokidarWatchBudget,
-): (filePath: string, stats?: fs.Stats) => boolean {
-  const root = path.resolve(hqRoot);
-  return (filePath: string, stats?: fs.Stats): boolean => {
-    // The watched root itself must NEVER be ignored, or chokidar tears down
-    // the whole watch. (shouldEmit returns false for it — it's not a valid
-    // emit target — so we special-case it here.)
-    if (path.resolve(filePath) === root) {
-      return stats?.isDirectory() && budget !== undefined
-        ? !budget.admit(filePath)
-        : false;
-    }
-    const isDir = stats?.isDirectory();
-    if (isDir === undefined) {
-      // This is chokidar's descent decision. The `isDir=true` branch includes
-      // only precise .hqinclude ancestors, rather than widening descent for
-      // every path that could happen to be an allowed file.
-      return !shouldEmit(filePath, true);
-    }
-    if (isDir) {
-      return (
-        !shouldEmit(filePath, true) ||
-        (budget !== undefined && !budget.admit(filePath))
-      );
-    }
-    return !shouldEmit(filePath, isDir);
-  };
-}
-
-/** A started watch backend. `close()` releases its OS handle(s); idempotent. */
-export interface WatchBackend {
-  close(): void;
-  /** Native recursive watches need rename-kind state; chokidar does not. */
-  needsKnownKinds: boolean;
-  /**
-   * True when the backend already populated those known kinds through
-   * `onDirectorySeen` while planning its watch roots, so {@link TreeWatcher}
-   * must NOT walk the tree a second time to seed them.
-   */
-  seededKnownKinds?: boolean;
-  /** Directories/OS handles admitted by this backend so degradation is auditable. */
-  watchedPathCount(): number;
-}
-
-export interface TreeWatcherDegradation {
-  reason: "watch_budget_exhausted" | "inotify_enospc";
-  maxWatchedPaths: number;
-  watchedPaths: number;
-  /** Full local path is deliberately log-only; telemetry receives its top level. */
-  offendingPath?: string;
-  offendingTopLevel?: string;
-  errorCode?: string;
-}
-
-export interface TreeWatchBackendOptions {
-  hqRoot: string;
-  shouldEmit: WatchPathFilter;
-  onEvent: (absolutePath: string, kind: BackendChangeKind) => void;
-  onError: (err: unknown) => void;
-  maxWatchedPaths: number;
-  onWatchBudgetExceeded: (info: TreeWatcherWatchBudgetExceeded) => void;
-  /**
-   * Reports every in-scope directory a backend encounters while planning its
-   * watch roots, so the known-kinds index can be built in that same pass.
-   */
-  onDirectorySeen?: (absolutePath: string) => void;
-}
-
-export type TreeWatchBackendFactory = (
-  opts: TreeWatchBackendOptions,
-) => WatchBackend;
-
-function isInotifyLimitError(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    "code" in err &&
-    (err as { code?: unknown }).code === "ENOSPC"
-  );
-}
-
-function errorPath(err: unknown): string | undefined {
-  if (
-    typeof err === "object" &&
-    err !== null &&
-    "path" in err &&
-    typeof (err as { path?: unknown }).path === "string"
-  ) {
-    return (err as { path: string }).path;
-  }
-  return undefined;
-}
-
-export type TreeChangeKind =
-  | "add"
-  | "change"
-  | "unlink"
-  | "addDir"
-  | "unlinkDir";
-
-/** Exact journal revision observed when a live watcher reports a deletion. */
-export interface LocalDeleteSnapshot {
-  journalSlug: string;
-  journalPath: string;
-  /** Exact vault-relative root authorized by the originating watcher event. */
-  deleteScopeRoot?: string;
-  absolutePath: string;
-  remoteEtag: string;
-  localHash: string;
-  localKind: "file" | "symlink";
-}
-
-export interface TreeChange {
-  kind: TreeChangeKind;
-  deleteSnapshots?: LocalDeleteSnapshot[];
-}
-
-type BackendChangeKind = TreeChangeKind | "rename";
-
-/**
- * Platforms where Node's `fs.watch(dir, { recursive: true })` is natively
- * supported by a SINGLE OS handle: macOS (FSEvents) and Windows
- * (ReadDirectoryChangesW). On Linux, recursive `fs.watch` is NOT implemented
- * (it throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`), so we fall back to
- * chokidar there.
- */
-function supportsRecursiveWatch(): boolean {
-  return process.platform === "darwin" || process.platform === "win32";
-}
-
-function startChokidarTreeWatch(
-  hqRoot: string,
-  shouldEmit: WatchPathFilter,
-  onEvent: (absolutePath: string, kind: BackendChangeKind) => void,
-  onError: (err: unknown) => void,
-  maxWatchedPaths: number,
-  onWatchBudgetExceeded: (info: TreeWatcherWatchBudgetExceeded) => void,
-): WatchBackend {
-  const budget = new ChokidarWatchBudget(
-    maxWatchedPaths,
-    onWatchBudgetExceeded,
-  );
-  let cw: ReturnType<typeof watch>;
-  try {
-    cw = watch(hqRoot, {
-      // On Linux chokidar adds one fs.watch/inotify watch per descended dir.
-      // The predicate therefore enforces both scope and the hard per-runner cap.
-      ignored: toChokidarIgnored(shouldEmit, hqRoot, budget),
-      persistent: true,
-      ignoreInitial: true,
-      awaitWriteFinish: {
-        stabilityThreshold: 500,
-        pollInterval: 100,
-      },
-    });
-  } catch (err) {
-    // Some chokidar/fs.watch versions surface ENOSPC synchronously. Route it
-    // through the same degradation path as an asynchronous backend error.
-    onError(err);
-    return {
-      close: () => {},
-      needsKnownKinds: false,
-      watchedPathCount: () => budget.count(),
-    };
-  }
-  cw.on("add", (p) => onEvent(p, "add"))
-    .on("change", (p) => onEvent(p, "change"))
-    .on("unlink", (p) => onEvent(p, "unlink"))
-    .on("addDir", (p) => onEvent(p, "addDir"))
-    .on("unlinkDir", (p) => onEvent(p, "unlinkDir"))
-    .on("error", onError);
-  return {
-    close: () => {
-      void cw.close();
-    },
-    needsKnownKinds: false,
-    watchedPathCount: () => budget.count(),
-  };
-}
-
-/**
- * macOS/Windows backend: recursive `fs.watch` handles placed over the in-scope
- * tree ONLY, as planned by {@link planWatchRoots}.
- *
- * The previous shape was a single recursive watch on hqRoot. That is one handle
- * regardless of tree size — but the OS then reports the WHOLE tree, including
- * the buckets sync never uploads. On a real HQ root that is `repos/` (~26k
- * directories) and `workspace/worktrees/` (~62k), where agent builds, installs,
- * and git checkouts churn constantly. Each of those events woke the runner and
- * was dropped only after the emit filter ran, which was enough allocation churn
- * to pin the process above 100% CPU in GC.
- *
- * So instead: plan the minimum cover of the uploadable tree and watch that.
- * A directory whose entire subtree is in scope takes one recursive watch; a
- * directory containing an excluded child is watched non-recursively and its
- * in-scope children are planned separately. Excluded subtrees get no watch at
- * all, so the OS never reports them.
- *
- * Handle count stays small (tens, not thousands — well clear of the kqueue fd
- * exhaustion that made chokidar 4 unusable here), and the emit filter still
- * runs on every delivered event, so a depth-bounded plan admitting some residue
- * is a performance concern, never a correctness one.
- */
-/**
- * How long the temporary whole-tree bootstrap watch is held open after the
- * scoped plan goes live, so events the OS observed during the planning walk
- * still drain instead of being dropped with the handle.
- */
-const BOOTSTRAP_DRAIN_MS = 2000;
-
-export interface ScopedWatchBackend extends WatchBackend {
-  /**
-   * Planned watches that could not be attached during the initial plan. Any
-   * failure here means the scoped plan has a permanent hole, so the caller
-   * discards it and falls back to chokidar rather than running with partial
-   * coverage.
-   */
-  attachFailures: number;
-}
-
-export function startScopedRecursiveWatch(
-  hqRoot: string,
-  shouldEmit: WatchPathFilter,
-  onEvent: (absolutePath: string, kind: BackendChangeKind) => void,
-  onError: (err: unknown) => void,
-  onDirectorySeen?: (absolutePath: string) => void,
-): ScopedWatchBackend {
-  const root = path.resolve(hqRoot);
-  const watchers = new Map<string, fs.FSWatcher>();
-  const recursiveRoots = new Set<string>();
-  const recursiveFlag = new Map<string, boolean>();
-  let closed = false;
-  let attachFailures = 0;
-  /** Retires the bootstrap watch — replaced once that watch exists. */
-  let closeBootstrap: () => void = () => {};
-
-  /** lstat that answers "is this a directory right now", never throwing. */
-  function isDirectoryNow(absolutePath: string): boolean {
-    try {
-      return fs.lstatSync(absolutePath).isDirectory();
-    } catch {
-      return false;
-    }
-  }
-
-  function exists(absolutePath: string): boolean {
-    try {
-      fs.lstatSync(absolutePath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Release the watch on `dir` AND on everything beneath it.
-   *
-   * When a directory is removed the OS reports that directory, not each of its
-   * descendants — so dropping only the exact path leaks every watch underneath
-   * it. Those handles stay open forever, and a leaked recursive root keeps
-   * marking its (now absent) subtree as covered, so a later recreation is never
-   * re-attached. These runners live for many hours, so the leak accumulates
-   * across every directory the tree churns through.
-   */
-  function dropWatch(dir: string): void {
-    const prefix = dir + path.sep;
-    for (const watched of [...watchers.keys()]) {
-      if (watched !== dir && !watched.startsWith(prefix)) continue;
-      const handle = watchers.get(watched);
-      if (handle) {
-        try {
-          handle.close();
-        } catch {
-          /* already closed */
-        }
-      }
-      watchers.delete(watched);
-      recursiveRoots.delete(watched);
-      recursiveFlag.delete(watched);
-    }
-  }
-
-  function addWatch(dir: string, recursive: boolean): void {
-    if (closed || watchers.has(dir)) return;
-    let handle: fs.FSWatcher;
-    try {
-      handle = fs.watch(
-        dir,
-        { recursive, persistent: true },
-        (eventType, filename) => {
-          // `filename` is relative to THIS watch's directory (or null/empty if
-          // the platform couldn't provide it — nothing actionable then).
-          // `String()` coerces both the string and (older @types/node) Buffer
-          // shapes.
-          if (filename == null) return;
-          const rel = String(filename);
-          if (rel === "") return;
-          const abs = path.resolve(dir, rel);
-          const kind: BackendChangeKind =
-            eventType === "change" ? "change" : "rename";
-          if (kind === "rename") reconcileCoverage(abs);
-          onEvent(abs, kind);
-        },
-      );
-    } catch (err) {
-      // A planned watch we could not attach. Report it and record the hole so
-      // the caller can reject the whole plan instead of running half-blind.
-      attachFailures += 1;
-      onError(err);
-      return;
-    }
-    handle.on("error", (err) => {
-      onError(err);
-      if (closed) return;
-      // Rebuild this root rather than leaving it permanently unwatched. The
-      // onError above has already asked TreeWatcher for a reconcile, so a gap
-      // between the drop and the re-attach cannot lose data.
-      const wasRecursive = recursiveFlag.get(dir) ?? recursive;
-      dropWatch(dir);
-      if (exists(dir) && shouldEmit(dir, true)) addWatch(dir, wasRecursive);
-    });
-    watchers.set(dir, handle);
-    recursiveFlag.set(dir, recursive);
-    if (recursive) recursiveRoots.add(dir);
-  }
-
-  function applyPlan(plan: WatchRootPlan): void {
-    for (const dir of plan.recursive) addWatch(dir, true);
-    for (const dir of plan.shallow) addWatch(dir, false);
-  }
-
-  function planAndAttach(dir: string): void {
-    applyPlan(planWatchRoots(dir, shouldEmit, { onDirectory: onDirectorySeen }));
-  }
-
-  /**
-   * Keep the live watch set honest about a path that just appeared, moved, or
-   * vanished. Three cases, all of which silently break coverage if ignored:
-   *
-   *  1. A watched directory was deleted (or deleted and recreated, which gives
-   *     the replacement a new inode). Its stale handle would otherwise make the
-   *     path look covered forever, so drop it and let the recreate re-plan.
-   *  2. An EXCLUDED directory was created under a recursive root — e.g.
-   *     `workspace/worktrees/` or a fresh `node_modules/` that did not exist at
-   *     plan time. The root now covers a bucket we must never watch, which is
-   *     exactly the firehose this backend exists to prevent, so re-plan it.
-   *  3. An in-scope directory was created under a SHALLOW watch, so nothing
-   *     covers its subtree yet. Attach before the event is handed on.
-   */
-  function reconcileCoverage(absolutePath: string): void {
-    if (closed) return;
-
-    // (1) stale handle for a path that no longer exists.
-    if (watchers.has(absolutePath) && !exists(absolutePath)) {
-      dropWatch(absolutePath);
-      return;
-    }
-
-    const inScope = shouldEmit(absolutePath, true);
-    const covered = isCoveredByRecursiveRoot(absolutePath, recursiveRoots);
-
-    // (2) newly-created exclusion swallowed by an existing recursive root. The
-    // lstat is paid only for excluded paths under a recursive root — rare, and
-    // strictly cheaper than the unconditional stat this backend replaced.
-    if (!inScope) {
-      if (covered && isDirectoryNow(absolutePath)) {
-        for (const rootDir of [...recursiveRoots]) {
-          if (
-            absolutePath === rootDir ||
-            absolutePath.startsWith(rootDir + path.sep)
-          ) {
-            dropWatch(rootDir);
-            planAndAttach(rootDir);
-          }
-        }
-      }
-      return;
-    }
-
-    // (3) in-scope directory with no coverage yet.
-    if (covered || watchers.has(absolutePath)) return;
-    if (!isDirectoryNow(absolutePath)) return;
-    onDirectorySeen?.(absolutePath);
-    planAndAttach(absolutePath);
-  }
-
-  // Cover the whole tree BEFORE planning. The plan walk below is synchronous
-  // and takes seconds on a real HQ root; without this, every change during that
-  // window would be invisible to event-driven push and would wait for the next
-  // cadence poll. This temporary watch is exactly the old backend's shape, so
-  // the bootstrap window is no worse than the previous behavior — and it is
-  // dropped the moment the scoped plan is live.
-  let bootstrap: fs.FSWatcher | null = null;
-  try {
-    bootstrap = fs.watch(
-      root,
-      { recursive: true, persistent: true },
-      (eventType, filename) => {
-        if (filename == null) return;
-        const rel = String(filename);
-        if (rel === "") return;
-        onEvent(
-          path.resolve(root, rel),
-          eventType === "change" ? "change" : "rename",
-        );
-      },
-    );
-    bootstrap.on("error", onError);
-  } catch (err) {
-    // Recursive watch is unavailable at all — the plan below cannot work
-    // either, so record the hole and let the caller fall back.
-    attachFailures += 1;
-    onError(err);
-  }
-
-  // Unbounded on purpose: this walk replaces TreeWatcher's separate known-kinds
-  // seed walk (same tree, same filter, ~3.6s on a real HQ root), so planning
-  // the tree exhaustively costs nothing over the status quo and leaves no
-  // excluded subtree covered by a recursive root.
-  planAndAttach(root);
-
-  // The scoped plan is live, so narrow from whole-tree to in-scope-only — but
-  // NOT synchronously. Events observed during the planning walk can still be
-  // sitting in the OS queue undelivered, and closing the handle here drops
-  // them, reopening the very gap the bootstrap watch exists to close. Hold it
-  // open for one drain window instead; the overlap only costs duplicate events
-  // for excluded paths, which the emit filter drops and the debounce coalesces.
-  if (bootstrap) {
-    const handle = bootstrap;
-    bootstrap = null;
-    const timer = setTimeout(() => {
-      try {
-        handle.close();
-      } catch {
-        /* already closed */
-      }
-      closeBootstrap = () => {};
-    }, BOOTSTRAP_DRAIN_MS);
-    // Never hold the process open just to retire a temporary watch.
-    (timer as { unref?: () => void }).unref?.();
-    closeBootstrap = () => {
-      clearTimeout(timer);
-      try {
-        handle.close();
-      } catch {
-        /* already closed */
-      }
-      closeBootstrap = () => {};
-    };
-  }
-
-  return {
-    close: () => {
-      closed = true;
-      closeBootstrap();
-      for (const handle of watchers.values()) {
-        try {
-          handle.close();
-        } catch {
-          /* already closed */
-        }
-      }
-      watchers.clear();
-      recursiveRoots.clear();
-      recursiveFlag.clear();
-    },
-    needsKnownKinds: true,
-    seededKnownKinds: onDirectorySeen !== undefined,
-    watchedPathCount: () => watchers.size,
-    attachFailures,
-  };
-}
-
-/**
- * Start watching `hqRoot`, calling `onEvent(absolutePath)` for every change.
- *
- * Backend selection (the whole point of this helper):
- *   - macOS / Windows → scoped recursive `fs.watch` handles over the in-scope
- *     tree only ({@link startScopedRecursiveWatch}). chokidar 4 dropped its
- *     `fsevents` backend, so on macOS it watches via kqueue, which costs ~1
- *     open fd PER watched path — ~11k fds over a real HQ tree, which EMFILEs
- *     under the default soft `ulimit -n` (256) and silently kills the watcher
- *     (instant sync then falls back to the poll).
- *   - Linux / other → chokidar (recursive `fs.watch` is unsupported there).
- *
- * The recursive backend does no descent-time filtering WITHIN a watched
- * subtree, so changes there are funneled to `onEvent`, which re-applies the
- * emit filter via {@link TreeWatcher.handleEvent}. That filter remains the
- * authoritative gate; the watch plan is a performance optimization on top of
- * it. This is also why the recursive backend is immune to the `.hqinclude`
- * ancestor-descent pruning that the chokidar backend needs
- * {@link toChokidarIgnored} to avoid.
- */
-function startTreeWatch(
-  hqRoot: string,
-  shouldEmit: WatchPathFilter,
-  onEvent: (absolutePath: string, kind: BackendChangeKind) => void,
-  onError: (err: unknown) => void,
-  maxWatchedPaths: number,
-  onWatchBudgetExceeded: (info: TreeWatcherWatchBudgetExceeded) => void,
-  onDirectorySeen?: (absolutePath: string) => void,
-): WatchBackend {
-  if (supportsRecursiveWatch()) {
-    try {
-      const scoped = startScopedRecursiveWatch(
-        hqRoot,
-        shouldEmit,
-        onEvent,
-        onError,
-        onDirectorySeen,
-      );
-      // Partial coverage is worse than a different backend: a planned root we
-      // could not attach is silently unwatched forever, and the operator only
-      // sees it as "instant sync stopped working for that subtree". Accept the
-      // scoped plan only when EVERY planned watch attached.
-      if (scoped.attachFailures === 0 && scoped.watchedPathCount() > 0) {
-        return scoped;
-      }
-      scoped.close();
-    } catch (err) {
-      // Recursive watch unexpectedly unavailable — fall back to chokidar
-      // rather than leaving the daemon with no watcher at all.
-      onError(err);
-    }
-  }
-
-  return startChokidarTreeWatch(
-    hqRoot,
-    shouldEmit,
-    onEvent,
-    onError,
-    maxWatchedPaths,
-    onWatchBudgetExceeded,
-  );
-}
-
-/**
- * Build the composite emit-decision predicate. Returns true when a change to
- * `absolutePath` SHOULD wake the watcher (i.e. it survives every exclusion
- * layer). Pure and chokidar-free so the matching logic is unit-testable
- * directly.
- *
- * @param hqRoot       sync root (== personal-vault root in personalMode).
- * @param personalMode when true, also applies the personal-vault default
- *                     exclusions and the excluded-top-level buckets.
- */
-export function createWatchPathFilter(
-  hqRoot: string,
-  personalMode = false,
-): WatchPathFilter {
-  const ignoreFilter = createIgnoreFilter(hqRoot);
-  const excludedTopLevel = new Set(PERSONAL_VAULT_EXCLUDED_TOP_LEVEL);
-
-  return (absolutePath: string, isDir = false): boolean => {
-    const rel = path.relative(hqRoot, absolutePath).split(path.sep).join("/");
-    // The root itself, or anything outside it, is never an emit target.
-    if (rel === "" || rel.startsWith("..")) return false;
-
-    // Layer 1: shared ignore stack (.hqignore/.gitignore/DEFAULT_IGNORES).
-    // createIgnoreFilter returns true = "sync this"; false = "ignored".
-    if (!ignoreFilter(absolutePath, isDir)) return false;
-
-    // Never-synced heavy buckets — pruned in BOTH modes. The local git worktrees
-    // (`workspace/worktrees/`, where `/worktree` and agent coding runs check out
-    // repos — often 100k+ transient source/build files) and the on-box `repos/`
-    // checkout are never vault-synced in any mode. In personalMode the
-    // excluded-top-level layer below already drops them; in `--companies` mode
-    // that layer is skipped, so without this the watcher descends into every
-    // worktree source tree — tens of thousands of wasted inotify watches (the
-    // outpost sat at ~78% of the OS limit) plus CPU spent processing build churn
-    // it immediately discards, and enough backlog to trip the
-    // overflow → full-reconcile fallback. Returning false for the dir probe too
-    // prunes the whole subtree at descent instead of per-file. `companies/` and
-    // the synced `workspace/agency/` + continuity-pointer paths are untouched.
-    const topSegments = rel.split("/");
-    if (topSegments[0] === "repos") return false;
-    if (topSegments[0] === "workspace" && topSegments[1] === "worktrees") {
-      return false;
-    }
-
-    if (personalMode) {
-      // Continuity-pointer carve-out: the session pointer lives under the
-      // otherwise-excluded `workspace/`, so it must re-include BEFORE the
-      // top-level bucket rejection below. Two cases:
-      //   (a) the pointer FILE itself → emit. Waking on the pointer is
-      //       sufficient: `/handoff` rewrites handoff.json AFTER its
-      //       (immutable) thread file, and the resulting personal push
-      //       re-enumerates via computePersonalVaultPaths, which sweeps the
-      //       pointer + its active thread file together.
-      //   (b) an ANCESTOR DIR of the pointer (`workspace`, `workspace/threads`)
-      //       queried as a directory → allow descent. The Linux chokidar
-      //       backend prunes a subtree the instant its dir probe says "ignore",
-      //       so without this it would prune `workspace/` before ever reaching
-      //       the leaf (the same ancestor-descent subtlety `.hqinclude` handles
-      //       via its ancestor matcher). The native recursive backend ignores
-      //       descent decisions and re-checks each path at event time, so this
-      //       only matters for chokidar but is harmless everywhere.
-      // See computeContinuityPointerPaths for the matching push-side carve-out.
-      if (rel === CONTINUITY_POINTER_REL && !isDir) return true;
-      if (isDir && CONTINUITY_POINTER_REL.startsWith(rel + "/")) return true;
-
-      // Agency-workspace carve-out: `workspace/agency/` (the whole subtree) IS
-      // synced via computeAgencySyncPaths (mirrored on the push side), so it must
-      // re-include BEFORE the top-level `workspace/` rejection below — same
-      // reason as the continuity pointer above, but for an entire subtree rather
-      // than one file. Without this, a `--personal --watch` runner never emits
-      // agency changes and they wait for the 60s poll. Paths at/under agency
-      // emit (handleEvent always probes isDir=false); agency itself and its
-      // ancestor dir (`workspace`) return true for the dir probe so chokidar
-      // descends to reach them instead of pruning `workspace/`.
-      if (rel === AGENCY_SYNC_REL || rel.startsWith(AGENCY_SYNC_REL + "/")) {
-        return true;
-      }
-      if (isDir && AGENCY_SYNC_REL.startsWith(rel + "/")) return true;
-
-      // Session-logs carve-out: `workspace/.session-logs/` (the whole subtree)
-      // IS synced via computeSessionLogsSyncPaths (mirrored on the push side),
-      // so it must re-include BEFORE the top-level `workspace/` rejection below
-      // — identical shape to the agency carve-out just above. Without this, a
-      // `--personal --watch` runner never emits reindex-captured session-log
-      // changes and they wait for the 60s poll. Paths at/under it emit; the
-      // subtree root and its ancestor dir (`workspace`) return true for the dir
-      // probe so chokidar descends to reach them instead of pruning `workspace/`.
-      if (
-        rel === SESSION_LOGS_SYNC_REL ||
-        rel.startsWith(SESSION_LOGS_SYNC_REL + "/")
-      ) {
-        return true;
-      }
-      if (isDir && SESSION_LOGS_SYNC_REL.startsWith(rel + "/")) return true;
-
-      // Layer 3: excluded top-level buckets (.git/companies/repos/workspace).
-      const topLevel = rel.split("/")[0];
-      if (excludedTopLevel.has(topLevel)) return false;
-
-      // Layer 2: personal-vault default exclusions (.env/output/.beads/…).
-      if (isPersonalVaultExcluded(rel, isDir)) return false;
-    }
-
-    return true;
-  };
-}
-
-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;
-  /** Quiet window (ms) before a settled burst emits one `changed` call. */
-  debounceMs?: number;
-  /** Apply personal-vault default + top-level exclusions. */
-  personalMode?: boolean;
-  /** Clock seam — defaults to {@link systemClock}; tests inject {@link FakeClock}. */
-  clock?: Clock;
-  /**
-   * Pre-built path filter override (test seam). When omitted, one is built
-   * 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;
-  /**
-   * Hard cap on distinct directories admitted to the chokidar backend for the
-   * lifetime of this instance. Linux uses one inotify watch per such directory.
-   * Overrides `HQ_SYNC_MAX_WATCHED_PATHS` for callers that construct a watcher.
-   */
-  maxWatchedPaths?: number;
-  /** Backlog overflow signal. Defaults to a console warning. */
-  onBacklogOverflow?: (info: TreeWatcherBacklogOverflow) => void;
-  /**
-   * Structured degradation/metric seam. It fires exactly once when the watch
-   * cap or the kernel's inotify limit disables event watching; cadence polling
-   * remains the correctness path.
-   */
-  onDegraded?: (info: TreeWatcherDegradation) => void;
-  /** Optional cloud telemetry sink for the same degradation signal. */
-  telemetryClient?: CloudTelemetryClient | null;
-  telemetryClaims?: TelemetryClaims | null;
-  /** Test seam for a watch backend; production uses native/chokidar selection. */
-  backendFactory?: TreeWatchBackendFactory;
-  captureLocalDeleteSnapshots?: (
-    relativePath: string,
-    kind: "unlink" | "unlinkDir",
-  ) => LocalDeleteSnapshot[];
-}
-
-/**
- * Chokidar-backed file watcher that emits a single debounced `changed` signal
- * after a {@link debounceMs} quiet window, coalescing bursts. It honors the
- * full exclusion stack via {@link createWatchPathFilter}, so excluded paths
- * (`.env`, `output/`, `.git/`, `companies/` in personalMode, …) never emit.
- *
- * Lifecycle: {@link start} (idempotent), {@link stop}, {@link dispose}. Stop
- * closes the chokidar watcher (releasing fds) and cancels any pending debounce
- * timer. dispose() is stop() + permanent shutdown.
- */
-/**
- * One settled change-burst, handed to {@link TreeWatcher} listeners. Carries
- * the set of relative paths that changed during the quiet window so a listener
- * (e.g. {@link PushEventEmitter}) can build one PushEvent per path. `paths` is
- * absolute-path → relative-path; both are needed (relative for the wire shape,
- * absolute for hashing/statting the file on disk).
- */
-export interface TreeChangeBatch {
-  /** Map of absolutePath → relativePath for every path in the settled burst. */
-  paths: Map<string, string>;
-  /** Per-path watcher event and the captured pre-delete journal revision. */
-  changes?: Map<string, TreeChange>;
-  /** 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;
-}
-
-/**
- * Listener invoked once per settled debounce window.
- *
- * Backwards compatible with the US-003 `WatcherSurface` contract: the first
- * argument is the OPTIONAL changed relative path the loop routes its targeted
- * push to (the first path of the burst; undefined when the window settled with
- * no captured path). US-008's {@link PushEventEmitter} consumes the SECOND
- * argument — the full {@link TreeChangeBatch} of every path in the burst — to
- * build one PushEvent per path. Listeners are free to ignore either argument.
- */
-export type TreeChangeListener = (
-  changedRelPath?: string,
-  batch?: TreeChangeBatch,
-) => void;
-
-export class TreeWatcher {
-  private readonly hqRoot: string;
-  private readonly debounceMs: number;
-  private readonly clock: Clock;
-  private readonly shouldEmit: WatchPathFilter;
-  private readonly maxPendingPaths: number;
-  private readonly maxPendingBytes: number;
-  private readonly maxWatchedPaths: number;
-  private readonly onBacklogOverflow: (info: TreeWatcherBacklogOverflow) => void;
-  private readonly onDegraded: (info: TreeWatcherDegradation) => void;
-  private readonly telemetryClient: CloudTelemetryClient | null | undefined;
-  private readonly telemetryClaims: TelemetryClaims | null | undefined;
-  private readonly backendFactory?: TreeWatchBackendFactory;
-  private readonly captureLocalDeleteSnapshots?: TreeWatcherOptions["captureLocalDeleteSnapshots"];
-  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 pendingChanges = new Map<string, TreeChange>();
-  private knownKinds = new Map<string, "file" | "directory">();
-  private pendingBytes = 0;
-  private overflowed = false;
-  private overflowLogged = false;
-  private droppedPaths = 0;
-  private droppedBytes = 0;
-  private degraded = false;
-  private disposed = false;
-
-  constructor(opts: TreeWatcherOptions) {
-    this.hqRoot = opts.hqRoot;
-    this.debounceMs = opts.debounceMs ?? DEBOUNCE_MS;
-    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.maxWatchedPaths = resolveMaxWatchedPaths(opts.maxWatchedPaths);
-    this.onBacklogOverflow =
-      opts.onBacklogOverflow ??
-      ((info) => {
-        console.warn(
-          `TreeWatcher backlog cap exceeded; dropping ${info.droppedPaths} path(s) until the next resync`,
-        );
-      });
-    this.onDegraded =
-      opts.onDegraded ??
-      ((info) => {
-        console.error(
-          JSON.stringify({ event: "watcher.degraded", ...info }),
-        );
-      });
-    this.telemetryClient = opts.telemetryClient;
-    this.telemetryClaims = opts.telemetryClaims;
-    this.backendFactory = opts.backendFactory;
-    this.captureLocalDeleteSnapshots = opts.captureLocalDeleteSnapshots;
-  }
-
-  /**
-   * Register a debounced-`changed` listener. Returns an unsubscribe fn.
-   *
-   * Listeners receive a {@link TreeChangeBatch} of the paths that changed in
-   * the settled window. Existing US-003 callers that only need the "something
-   * changed" signal can ignore the argument — the contract is backwards
-   * compatible (a zero-arg callback still type-checks).
-   */
-  onChange(listener: TreeChangeListener): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-
-  /**
-   * Begin watching. Idempotent — a second call while already running is a
-   * no-op (no second watch backend, no leaked handles).
-   *
-   * Uses a SINGLE recursive `fs.watch` on macOS/Windows (1 OS handle for the
-   * whole tree) and falls back to chokidar on Linux. See {@link startTreeWatch}
-   * for why per-path watching is avoided (kqueue fd exhaustion → EMFILE).
-   */
-  start(): void {
-    if (this.disposed || this.degraded || this.backend) return;
-    const backendOpts: TreeWatchBackendOptions = {
-      hqRoot: this.hqRoot,
-      shouldEmit: this.shouldEmit,
-      onEvent: (absolutePath, kind) => this.handleEvent(absolutePath, kind),
-      onError: (err) => this.handleBackendError(err),
-      maxWatchedPaths: this.maxWatchedPaths,
-      onWatchBudgetExceeded: (info) => this.degrade({
-        reason: "watch_budget_exhausted",
-        maxWatchedPaths: info.maxWatchedPaths,
-        watchedPaths: info.watchedPaths,
-        offendingPath: info.offendingPath,
-        offendingTopLevel: this.topLevelForTelemetry(info.offendingPath),
-      }),
-      onDirectorySeen: (absolutePath) =>
-        this.knownKinds.set(path.resolve(absolutePath), "directory"),
-    };
-    const backend = this.backendFactory
-      ? this.backendFactory(backendOpts)
-      : startTreeWatch(
-          backendOpts.hqRoot,
-          backendOpts.shouldEmit,
-          backendOpts.onEvent,
-          backendOpts.onError,
-          backendOpts.maxWatchedPaths,
-          backendOpts.onWatchBudgetExceeded,
-          backendOpts.onDirectorySeen,
-        );
-    // A test backend (or a future eager backend) can discover exhaustion while
-    // it is being constructed. Never retain that just-created handle after the
-    // degradation path has deliberately disabled event watching.
-    if (this.degraded) {
-      backend.close();
-      return;
-    }
-    this.backend = backend;
-    // The scoped backend already indexed every in-scope directory while
-    // planning its watch roots — walking the tree again here would double a
-    // multi-second startup cost for an identical result.
-    if (backend.needsKnownKinds && !backend.seededKnownKinds) {
-      this.seedKnownKinds();
-    }
-  }
-
-  private handleBackendError(err: unknown): void {
-    if (isInotifyLimitError(err)) {
-      const offendingPath = errorPath(err);
-      this.degrade({
-        reason: "inotify_enospc",
-        maxWatchedPaths: this.maxWatchedPaths,
-        watchedPaths: this.backend?.watchedPathCount() ?? 0,
-        offendingPath,
-        offendingTopLevel: offendingPath
-          ? this.topLevelForTelemetry(offendingPath)
-          : undefined,
-        errorCode: "ENOSPC",
-      });
-      return;
-    }
-    console.error("TreeWatcher error:", err);
-    this.signalBackendResync();
-  }
-
-  private topLevelForTelemetry(absolutePath: string): string | undefined {
-    const rel = path.relative(this.hqRoot, absolutePath).split(path.sep);
-    const topLevel = rel[0];
-    return topLevel && topLevel !== ".." ? topLevel : undefined;
-  }
-
-  private degrade(info: TreeWatcherDegradation): void {
-    if (this.disposed || this.degraded) return;
-    this.degraded = true;
-    // Closing synchronously prevents further directory admissions while
-    // chokidar's initial walk is still in flight.
-    this.backend?.close();
-    this.backend = null;
-    try {
-      this.onDegraded(info);
-    } catch (err) {
-      console.error("TreeWatcher degradation reporter error:", err);
-    }
-    void emitCloudTelemetry(
-      this.telemetryClient,
-      {
-        eventName: "watcher_degraded",
-        source: "watcher",
-        properties: {
-          reason: info.reason,
-          maxWatchedPaths: info.maxWatchedPaths,
-          watchedPaths: info.watchedPaths,
-          ...(info.offendingTopLevel
-            ? { offendingTopLevel: info.offendingTopLevel }
-            : {}),
-        },
-      },
-      { claims: this.telemetryClaims },
-    );
-    // The existing overflow/resync batch causes the runner to use its scoped
-    // drain while the cadence poll continues covering everything else.
-    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
-   * events route through here too — and for the recursive backend this is the
-   * ONLY place filtering happens, so out-of-scope paths are dropped here.
-   */
-  handleEvent(
-    absolutePath: string,
-    backendKind: BackendChangeKind = "change",
-  ): void {
-    if (this.disposed) return;
-    const abs = path.resolve(absolutePath);
-    // Cheap pre-gate. When a path is out of scope BOTH as a file and as a
-    // directory, no stat can change the answer — so drop it before paying the
-    // syscall below. Scoped watch roots (see planWatchRoots) keep most excluded
-    // traffic from being delivered at all; this covers the residue a
-    // depth-bounded plan still admits, at the cost of two string matches
-    // instead of one synchronous lstat.
-    if (!this.shouldEmit(abs, false) && !this.shouldEmit(abs, true)) return;
-    let kind: TreeChangeKind;
-    if (backendKind === "rename") {
-      try {
-        kind = fs.lstatSync(abs).isDirectory() ? "addDir" : "add";
-      } catch (err: unknown) {
-        const code =
-          err && typeof err === "object" && "code" in err
-            ? (err as { code?: string }).code
-            : undefined;
-        if (code !== "ENOENT") return;
-        kind = this.knownKinds.get(abs) === "directory" ? "unlinkDir" : "unlink";
-      }
-    } else {
-      kind = backendKind;
-    }
-    const isDir = kind === "addDir" || kind === "unlinkDir";
-    // The recursive backend does no descent-time filtering, so this is the
-    // authoritative emit gate; the chokidar backend's `ignored` pre-filters
-    // but a slipped-through (or synthetic test) path is re-checked here too.
-    if (!this.shouldEmit(abs, isDir)) return;
-    // Codec boundary: the batch's relative path is a WIRE identifier — it
-    // becomes `PushEvent.relativePath` and the targeted-push route key — so
-    // a win32 local farm name (`indigo%3Ax`) must decode back to its
-    // canonical vault-key spelling (`indigo:x`) here. Emitting the encoded
-    // local name verbatim would mint a fresh junk key family on the wire
-    // (the mixed-version amplifier). The emit filter above still sees the
-    // raw local path: its exclusion patterns live in local-name space and
-    // none of them contain codec-reserved characters.
-    const rel = vaultKeyForLocalPath(this.hqRoot, abs);
-    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);
-    if (kind === "unlink" || kind === "unlinkDir") {
-      // A SECOND delete event for the same path in one window must never
-      // downgrade a directory delete to a file delete. The first `unlinkDir`
-      // clears this path's known-kind hint, so a duplicate event — the OS can
-      // report one path through two overlapping watches — would re-classify it
-      // as `unlink` and, with it, narrow the deletion scope the vault applies
-      // and drop the captured descendant snapshots.
-      if (kind === "unlink" && this.pendingChanges.get(abs)?.kind === "unlinkDir") {
-        this.pending.set(abs, rel);
-        this.arm();
-        return;
-      }
-      const deleteSnapshots =
-        this.captureLocalDeleteSnapshots?.(rel, kind) ?? [];
-      this.pendingChanges.set(abs, {
-        kind,
-        ...(deleteSnapshots.length > 0 ? { deleteSnapshots } : {}),
-      });
-      this.knownKinds.delete(abs);
-    } else {
-      this.pendingChanges.set(abs, { kind });
-      // Only directories are needed to disambiguate a native recursive
-      // rename-after-delete. Unknown paths already correctly default to an
-      // unlink file, so retaining every file ever touched made this map grow
-      // without bound in a long-lived runner.
-      if (isDir) this.knownKinds.set(abs, "directory");
-      else this.knownKinds.delete(abs);
-    }
-    this.arm();
-  }
-
-  private seedKnownKinds(): void {
-    const visit = (dir: string): void => {
-      let entries: fs.Dirent[];
-      try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      for (const entry of entries) {
-        const absolutePath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          if (!this.shouldEmit(absolutePath, true)) continue;
-          this.knownKinds.set(path.resolve(absolutePath), "directory");
-          visit(absolutePath);
-        }
-      }
-    };
-    visit(this.hqRoot);
-  }
-
-  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);
-      this.timer = null;
-    }
-    this.timer = this.clock.setTimeout(() => {
-      this.timer = null;
-      this.emit();
-    }, this.debounceMs);
-  }
-
-  private emit(): void {
-    if (this.disposed) return;
-    // 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),
-      changes: new Map(this.pendingChanges),
-    };
-    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).
-    const firstRel = [...batch.paths.values()][0];
-    for (const l of this.listeners) {
-      try {
-        l(firstRel, batch);
-      } catch (err) {
-        console.error("TreeWatcher listener error:", err);
-      }
-    }
-  }
-
-  private clearPending(): void {
-    this.pending.clear();
-    this.pendingChanges.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;
-  }
-
-  /** Number of pending debounce timers — a leak check for tests. */
-  pendingTimerCount(): number {
-    return this.timer === null ? 0 : 1;
-  }
-
-  /** Number of native-rename directory hints retained for deletion handling. */
-  knownDirectoryCount(): number {
-    return this.knownKinds.size;
-  }
-
-  /**
-   * Stop watching: close the watch backend (releasing its OS handle) and
-   * cancel any pending debounce timer. Idempotent. The instance can be
-   * restarted with {@link start} unless {@link dispose} was called.
-   */
-  stop(): void {
-    if (this.timer !== null) {
-      this.clock.clearTimeout(this.timer);
-      this.timer = null;
-    }
-    this.clearPending();
-    if (this.backend) {
-      this.backend.close();
-      this.backend = null;
-    }
-  }
-
-  /** Permanent shutdown: stop() + drop listeners; further events are no-ops. */
-  dispose(): void {
-    this.stop();
-    this.disposed = true;
-    this.listeners.clear();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// US-008 — PushEventEmitter: bridge the TreeWatcher to the Phase 2 transport.
-//
-// On each settled debounce window, build one PushEvent per changed path
-// (sha-256 contentHash, monotonic per-device sequenceNumber, originTenantId)
-// and hand it to the injected PushTransport. Feature-flag gated: when the
-// originTenantId is NOT enabled the emitter is DORMANT — it subscribes to
-// nothing and ships nothing, so the Phase 1 poll-only behavior is unchanged.
-//
-// Failure posture: a transport publish that throws (network/non-2xx/timeout)
-// MUST NOT crash the daemon. The emitter catches per-event publish errors and
-// routes them to `onError` (default: console.error); the existing cadence
-// poll remains the safety net that eventually ships the change.
-// ---------------------------------------------------------------------------
-
-/** Computes the canonical contentHash for a file: `sha256:<64-hex>`. */
-async function computeContentHash(absolutePath: string): Promise<string> {
-  const bytes = await readFile(absolutePath);
-  const hex = createHash("sha256").update(bytes).digest("hex");
-  return `sha256:${hex}`;
-}
-
-export interface PushEventEmitterOptions {
-  /** Tenant identifier stamped onto every PushEvent + checked against the flag. */
-  originTenantId: string;
-  /** Device identifier stamped onto every PushEvent. */
-  originDeviceId: string;
-  /** Transport that ships each PushEvent (US-007 NoopPushTransport / HttpPushTransport). */
-  transport: PushTransport;
-  /**
-   * Feature-flag seam. When `isEnabled(originTenantId)` is false the emitter is
-   * dormant: {@link attach} subscribes nothing and {@link emitForBatch} is a
-   * no-op. Defaults are NOT supplied here — the caller injects an
-   * EventDrivenPushFlagProvider so dormancy is explicit.
-   */
-  flagProvider: EventDrivenPushFlagProvider;
-  /**
-   * Returns the next monotonic sequence number for this device. Default: an
-   * internal counter starting at 0. Inject to persist across daemon restarts.
-   */
-  getSequenceNumber?: () => number;
-  /** Clock for eventTimestamp. Default `() => new Date()`. */
-  now?: () => Date;
-  /**
-   * Where publish failures + hash/stat errors go. Default `console.error`.
-   * Receives the offending PushEvent (when known) so callers can correlate.
-   */
-  onError?: (err: Error, ctx: { relativePath?: string }) => void;
-  /**
-   * Optional structured logger for the US-011 3-log diagnostic chain. When
-   * supplied, the emitter logs `event=watcher.emit` (the 1st correlated link)
-   * carrying the PushEvent's `sequenceNumber` — the same join key stamped by
-   * the server `push.receive` log and the client `fanout.receive` log. Default:
-   * no log (the daemon stays quiet unless wired with a logger).
-   */
-  logger?: EmitterLogger;
-  /** Optional hq-pro ACTION telemetry sink. Best-effort; never affects publish. */
-  telemetryClient?: CloudTelemetryClient | null;
-  telemetryClaims?: TelemetryClaims | null;
-}
-
-/**
- * Minimal structured logger surface for {@link PushEventEmitter}. A pino
- * `Logger` (from `./sync/logger.ts`) satisfies this; tests inject a fake.
- */
-export interface EmitterLogger {
-  info(obj: Record<string, unknown>, msg?: string): void;
-}
-
-/**
- * Bridges {@link TreeWatcher} change batches to a {@link PushTransport} as
- * typed PushEvents. Construct once per daemon, then {@link attach} to a
- * 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;
-  private readonly flagProvider: EventDrivenPushFlagProvider;
-  private readonly now: () => Date;
-  private readonly onError: (err: Error, ctx: { relativePath?: string }) => void;
-  private readonly logger: EmitterLogger | undefined;
-  private readonly telemetryClient: CloudTelemetryClient | null | undefined;
-  private readonly telemetryClaims: TelemetryClaims | null | undefined;
-  private internalSeq = 0;
-  private readonly nextSeq: () => number;
-  private publishTail: Promise<void> = Promise.resolve();
-
-  constructor(opts: PushEventEmitterOptions) {
-    this.originTenantId = opts.originTenantId;
-    this.originDeviceId = opts.originDeviceId;
-    this.transport = opts.transport;
-    this.flagProvider = opts.flagProvider;
-    this.now = opts.now ?? (() => new Date());
-    this.logger = opts.logger;
-    this.telemetryClient = opts.telemetryClient;
-    this.telemetryClaims = opts.telemetryClaims;
-    this.onError =
-      opts.onError ??
-      ((err, ctx) =>
-        console.error("PushEventEmitter error:", ctx.relativePath ?? "", err));
-    this.nextSeq =
-      opts.getSequenceNumber ??
-      (() => {
-        const n = this.internalSeq;
-        this.internalSeq += 1;
-        return n;
-      });
-  }
-
-  /** True iff event-driven push is enabled for this emitter's tenant. */
-  get enabled(): boolean {
-    return this.flagProvider.isEnabled(this.originTenantId);
-  }
-
-  /**
-   * Subscribe to a TreeWatcher's change batches. Dormant (no subscription)
-   * when the flag is OFF for this tenant. Returns an unsubscribe fn (a no-op
-   * when dormant).
-   */
-  attach(watcher: TreeWatcher): () => void {
-    if (!this.enabled) return () => {};
-    return watcher.onChange((_changedRelPath, batch) => {
-      if (batch) void this.emitForBatch(batch);
-    });
-  }
-
-  /**
-   * Build + ship one PushEvent per changed path in the batch. No-op when the
-   * flag is OFF. Each path is independent: a hash/stat failure or a transport
-   * publish rejection for one path is caught + surfaced via `onError` and does
-   * NOT abort the others or propagate (the daemon must not crash; the cadence
-   * poll covers any miss).
-   */
-  async emitForBatch(batch: TreeChangeBatch): Promise<void> {
-    if (!this.enabled) return;
-    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(
-    absolutePath: string,
-    relativePath: string,
-  ): Promise<void> {
-    let event: PushEvent | undefined;
-    try {
-      const st = await stat(absolutePath);
-      if (st.isDirectory()) return;
-
-      const contentHash = await computeContentHash(absolutePath);
-      event = {
-        kind: "upsert",
-        relativePath,
-        contentHash,
-        mtime: st.mtime.toISOString(),
-        originDeviceId: this.originDeviceId,
-        originTenantId: this.originTenantId,
-        sequenceNumber: this.nextSeq(),
-        eventTimestamp: this.now().toISOString(),
-      };
-    } catch (err) {
-      const code =
-        err && typeof err === "object" && "code" in err
-          ? (err as { code?: string }).code
-          : undefined;
-      if (code !== "ENOENT") {
-        // Genuine stat/read failure. Surface, don't crash.
-        this.onError(err instanceof Error ? err : new Error(String(err)), {
-          relativePath,
-        });
-        this.emitPublishFailureTelemetry("unknown", "capture");
-        return;
-      }
-
-      // Deleted before/during capture: publish a tombstone so peers run a
-      // targeted pull and let the vault-confirmed tombstone path remove it.
-      event = {
-        kind: "delete",
-        relativePath,
-        originDeviceId: this.originDeviceId,
-        originTenantId: this.originTenantId,
-        sequenceNumber: this.nextSeq(),
-        eventTimestamp: this.now().toISOString(),
-      };
-    }
-
-    // US-011: 1st link of the 3-log diagnostic chain. Stamps the same
-    // `sequenceNumber` the server `push.receive` log and the client
-    // `fanout.receive` log carry, so an operator can walk one event
-    // end-to-end. Logged after the event is built, before the publish.
-    this.logger?.info(
-      {
-        event: "watcher.emit",
-        kind: event.kind,
-        originTenantId: event.originTenantId,
-        originDeviceId: event.originDeviceId,
-        relativePath: event.relativePath,
-        contentHash: event.contentHash,
-        sequenceNumber: event.sequenceNumber,
-        eventTimestamp: event.eventTimestamp,
-      },
-      "watcher emitted push event",
-    );
-
-    try {
-      await this.transport.publish(event);
-    } catch (err) {
-      // Push failure (network / non-2xx / timeout). The cadence poll is the
-      // safety net — log + continue, never throw.
-      this.onError(err instanceof Error ? err : new Error(String(err)), {
-        relativePath,
-      });
-      this.emitPublishFailureTelemetry(event.kind, "publish");
-    }
-  }
-
-  private emitPublishFailureTelemetry(
-    kind: string,
-    stage: "capture" | "publish",
-  ): void {
-    void emitCloudTelemetry(
-      this.telemetryClient,
-      {
-        eventName: "push_event_failed",
-        source: "watcher",
-        properties: {
-          kind,
-          count: 1,
-          status: "failure",
-          stage,
-        },
-      },
-      { claims: this.telemetryClaims },
-    );
-  }
-}