@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/src/watcher.ts

@@ -8,6 +8,8 @@
  */
 
 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 type { FSWatcher } from "chokidar";
@@ -16,9 +18,188 @@ import { createIgnoreFilter, isWithinSizeLimit } from "./ignore.js";
 import { readJournal, writeJournal, hashFile, updateEntry } from "./journal.js";
 import { uploadFile, deleteRemoteFile } from "./s3.js";
 import type { UploadAuthor } from "./s3.js";
+import { isPersonalVaultExcluded } from "./personal-vault-exclusions.js";
+import { 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";
 
 const DEBOUNCE_MS = 2000;
 
+/**
+ * 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();
+    }, 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;
+  }
+}
+
 interface PendingChange {
   type: "add" | "change" | "unlink";
   absolutePath: string;
@@ -46,10 +227,11 @@ export class SyncWatcher {
     if (this.watcher) return;
 
     this.watcher = watch(this.hqRoot, {
-      // Forward chokidar's stats hint so dir-only gitignore patterns
-      // (`foo/`) match directory entries during the descent decision.
-      ignored: (filePath: string, stats?: fs.Stats) =>
-        !this.shouldSync(filePath, stats?.isDirectory()),
+      // See toChokidarIgnored: chokidar's pre-stat descent probe has no stats
+      // hint, so a naive file-verdict prunes intermediate allowlist dirs
+      // before descending to their in-scope leaves. Keep a statless probe
+      // when EITHER the file or directory reading would survive the filter.
+      ignored: toChokidarIgnored(this.shouldSync, this.hqRoot),
       persistent: true,
       ignoreInitial: true,
       awaitWriteFinish: {
@@ -146,3 +328,489 @@ export class SyncWatcher {
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// US-002 — debounced, ignore-aware, exclusion-aware tree watcher.
+//
+// Unlike SyncWatcher (which does S3 work inline), 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;
+
+/**
+ * Translate an emit-filter into chokidar's `ignored` predicate (true = SKIP).
+ *
+ * The subtlety this encodes: chokidar probes a candidate path for the descent
+ * decision BEFORE it has stat()ed it, so `stats` is `undefined` on that first
+ * call — and if we say "ignore" there, chokidar prunes the subtree and never
+ * descends. In allowlist mode (`.hqinclude`) the in-scope leaves
+ * (`companies/*\/knowledge/`) live UNDER intermediate dirs (`companies/`,
+ * `companies/<slug>/`) that only survive the filter when queried as a
+ * directory (the ancestor matcher fires for `isDir=true` only). With no stats
+ * hint we don't know if the candidate is that ancestor dir or an in-scope
+ * file, so we must NOT prune when EITHER reading would keep it. The real
+ * isDir-accurate verdict is reapplied at event time (TreeWatcher.handleEvent
+ * re-checks with the known kind), so this only widens descent, never emit.
+ */
+function toChokidarIgnored(
+  shouldEmit: WatchPathFilter,
+  hqRoot: string,
+): (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 false;
+    const isDir = stats?.isDirectory();
+    if (isDir === undefined) {
+      // Pre-stat descent probe: keep the path if it could be an in-scope file
+      // OR an ancestor directory of one.
+      return !(shouldEmit(filePath, false) || shouldEmit(filePath, true));
+    }
+    return !shouldEmit(filePath, isDir);
+  };
+}
+
+/**
+ * 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;
+
+    if (personalMode) {
+      // 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 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * 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 watcher: FSWatcher | 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 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);
+  }
+
+  /**
+   * 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 chokidar instance, no leaked fds).
+   */
+  start(): void {
+    if (this.disposed || this.watcher) return;
+
+    this.watcher = watch(this.hqRoot, {
+      // `ignored` returns true to SKIP. chokidar probes a candidate for the
+      // descent decision BEFORE stat()ing it (stats undefined on that call),
+      // so a naive `!shouldEmit(path, stats?.isDirectory())` treats the
+      // statless probe as a file and prunes intermediate dirs (`companies/`)
+      // that only survive the allowlist filter as directories — starving the
+      // in-scope leaves below them. toChokidarIgnored keeps a statless probe
+      // when EITHER the file or the directory reading would; the accurate
+      // isDir verdict is reapplied at event time in handleEvent.
+      ignored: toChokidarIgnored(this.shouldEmit, this.hqRoot),
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 500,
+        pollInterval: 100,
+      },
+    });
+
+    const onEvent = (absolutePath: string) => this.handleEvent(absolutePath);
+    this.watcher
+      .on("add", onEvent)
+      .on("change", onEvent)
+      .on("unlink", onEvent)
+      .on("addDir", onEvent)
+      .on("unlinkDir", onEvent)
+      .on("error", (err) => console.error("TreeWatcher error:", err));
+  }
+
+  /**
+   * Test/seam entry point: feed a raw filesystem path as if chokidar reported
+   * it. Applies the emit filter then arms the debounce. Real chokidar events
+   * route through here too.
+   */
+  handleEvent(absolutePath: string): void {
+    if (this.disposed) return;
+    // Defensive: chokidar's `ignored` already filtered, but a path that slips
+    // through (or a synthetic test event) is re-checked here.
+    if (!this.shouldEmit(absolutePath, false)) return;
+    const abs = path.resolve(absolutePath);
+    const rel = path.relative(this.hqRoot, abs).split(path.sep).join("/");
+    this.pending.set(abs, rel);
+    this.arm();
+  }
+
+  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) };
+    this.pending.clear();
+    // 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);
+      }
+    }
+  }
+
+  /** True while the chokidar watcher is active. */
+  isWatching(): boolean {
+    return this.watcher !== null;
+  }
+
+  /** Number of pending debounce timers — a leak check for tests. */
+  pendingTimerCount(): number {
+    return this.timer === null ? 0 : 1;
+  }
+
+  /**
+   * Stop watching: close the chokidar watcher (releasing fds) 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.pending.clear();
+    if (this.watcher) {
+      void this.watcher.close();
+      this.watcher = 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;
+}
+
+/**
+ * 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 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 internalSeq = 0;
+  private readonly nextSeq: () => number;
+
+  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.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 entries = [...batch.paths.entries()];
+    await Promise.all(
+      entries.map(([absolutePath, relativePath]) =>
+        this.emitOne(absolutePath, relativePath),
+      ),
+    );
+  }
+
+  private async emitOne(
+    absolutePath: string,
+    relativePath: string,
+  ): Promise<void> {
+    let event: PushEvent | undefined;
+    try {
+      const [contentHash, st] = await Promise.all([
+        computeContentHash(absolutePath),
+        stat(absolutePath),
+      ]);
+      event = {
+        relativePath,
+        contentHash,
+        mtime: st.mtime.toISOString(),
+        originDeviceId: this.originDeviceId,
+        originTenantId: this.originTenantId,
+        sequenceNumber: this.nextSeq(),
+        eventTimestamp: this.now().toISOString(),
+      };
+    } catch (err) {
+      // File deleted between debounce fire and hash read (legal race), or stat
+      // failed. Surface, don't crash.
+      this.onError(err instanceof Error ? err : new Error(String(err)), {
+        relativePath,
+      });
+      return;
+    }
+
+    // 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",
+        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,
+      });
+    }
+  }
+}