@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/bin/sync-runner-watch-loop.ts

@@ -1,1235 +0,0 @@
-import * as os from "os";
-import * as path from "path";
-import * as fs from "fs";
-import { performance } from "node:perf_hooks";
-import { inventoryManagedSnapshots } from "../backup-prune.js";
-import { VaultClient } from "../index.js";
-import { pickCanonicalPersonEntity } from "../vault-client.js";
-import {
-  acquireOperationLock,
-  withOperationLock,
-  OperationLockedError,
-  OPERATION_LOCKED_EXIT,
-} from "../operation-lock.js";
-import { describeError } from "../lib/describe-error.js";
-import { TRANSIENT_NETWORK_EXIT } from "../lib/net-errors.js";
-import { PARTIAL_SYNC_EXIT } from "../lib/exit-codes.js";
-import { getOrCreateMachineId } from "../lib/machine-id.js";
-import { localPathForVaultKey } from "../local-path-codec.js";
-import {
-  TreeWatcher,
-  systemClock,
-  type LocalDeleteSnapshot,
-  type TreeChange,
-  type TreeChangeBatch,
-} from "../watcher.js";
-import {
-  clearLocalDeleteIntent,
-  markLocalDeleteIntent,
-  PERSONAL_VAULT_JOURNAL_SLUG,
-  readJournal,
-  writeJournal,
-} from "../journal.js";
-import {
-  NoopPushReceiver,
-  type PushReceiver,
-  type SyncEngineFn,
-} from "../sync/push-receiver.js";
-import {
-  resolveEventSync,
-  startEventSync as defaultStartEventSync,
-  type EventSyncHandles,
-} from "../sync/event-sync.js";
-import type { TelemetryClaims } from "../telemetry-events.js";
-import {
-  buildScopedDrainPullArgv,
-  buildScopedPushArgv,
-  buildTargetedPullArgv,
-  isWatchRouteSelected,
-  routeChangeToTarget,
-  routeKey,
-  type WatchRoute,
-} from "./sync-runner-watch-routes.js";
-import { resolveSkipCompanies } from "./sync-runner-planning.js";
-import type {
-  Direction,
-  RunnerLoopDeps,
-  RunnerPassOutcome,
-  WatcherSurface,
-} from "./sync-runner.js";
-
-const FULL_RECONCILE_EVERY_TICKS = 10;
-
-/**
- * Adaptive remote-poll backoff bounds (whole-box CPU aware). When
- * `--poll-remote-ms` is NOT passed, the watch loop scales its poll cadence to
- * the host's overall load instead of using a fixed interval: ~60s when the box
- * is idle, stretching toward ~10min under sustained full load, so the periodic
- * pull yields CPU/I-O to whatever else is running (e.g. the user's live agent
- * session). The poll is only a correctness backstop — event-push handles
- * real-time — so a stale interval under load is safe. An explicit
- * `--poll-remote-ms <n>` overrides this entirely and pins a fixed interval.
- */
-const ADAPTIVE_POLL_FLOOR_MS = 60_000;
-const ADAPTIVE_POLL_CEIL_MS = 600_000;
-
-/**
- * Map whole-box load to a poll interval in the [floor, ceil] range.
- *
- * `load1` is the 1-minute load average ({@link os.loadavg}[0]); dividing by the
- * CPU count yields per-core saturation. ratio 0 (idle) → floor; ratio ≥ 1
- * (fully saturated) → ceil; linear in between. Pure + injectable so the loop
- * can be unit-tested without a real host or a 10-minute wait.
- */
-export function adaptivePollMs(
-  load1: number,
-  cpuCount: number,
-  floorMs: number = ADAPTIVE_POLL_FLOOR_MS,
-  ceilMs: number = ADAPTIVE_POLL_CEIL_MS,
-): number {
-  const cores = cpuCount > 0 ? cpuCount : 1;
-  const saturation = load1 > 0 ? load1 / cores : 0;
-  const ratio = Math.max(0, Math.min(1, saturation));
-  return Math.round(floorMs + ratio * (ceilMs - floorMs));
-}
-
-/**
- * Advance the cadence from its previous monotonic deadline, rather than from
- * the end of a pass. A slow pass is allowed one immediate catch-up pass; the
- * returned deadline is always the first future slot, so missed slots cannot
- * turn into an unbounded burst.
- */
-export function advanceMonotonicDeadline(
-  previousDueAt: number,
-  now: number,
-  intervalMs: number,
-): { nextDueAt: number; delayMs: number } {
-  let nextDueAt = previousDueAt + intervalMs;
-  if (nextDueAt > now) {
-    return { nextDueAt, delayMs: nextDueAt - now };
-  }
-
-  // The pass crossed at least one deadline. Run exactly one catch-up now,
-  // then retain only the first future cadence slot.
-  do {
-    nextDueAt += intervalMs;
-  } while (nextDueAt <= now);
-  return { nextDueAt, delayMs: 0 };
-}
-
-export interface ParsedLoopArgs {
-  hqRoot: string;
-  lockTimeoutSec?: number;
-  /** Resolved parser flag; environment policy is applied by resolveSkipPersonal. */
-  skipPersonal?: boolean;
-  /**
-   * The run's resolved sync direction, straight from `parseArgs` (the single
-   * source of truth — same default as the parser). The drain reads this to
-   * decide whether scoped pushes and/or the pull leg run; it must NOT re-parse
-   * `--direction` from argv, which mis-defaults an omitted flag and disagrees
-   * with the parser on duplicate flags.
-   */
-  direction?: Direction;
-}
-
-export interface WatchLoopRuntime {
-  runPassWithOperationLockAlreadyHeld: (
-    passArgv: string[],
-  ) => Promise<number | RunnerPassOutcome>;
-  authRequiredPassExit: number;
-  defaultGetIdTokenClaims: () => ({ email?: string } & TelemetryClaims) | null;
-  defaultGetAccessToken: () => Promise<string>;
-  apiUrl: string;
-  region: string;
-}
-
-type JournalFiles = ReturnType<typeof readJournal>["files"];
-
-/**
- * Select journal entries covered by one watcher delete. Exact file unlinks
- * deliberately avoid enumeration; only directory unlinks expand descendants.
- */
-export function journalEntriesForWatcherDelete(
-  files: JournalFiles,
-  key: string,
-  kind: "unlink" | "unlinkDir",
-): Array<[string, JournalFiles[string]]> {
-  if (kind === "unlink") {
-    const entry = files[key];
-    return entry ? [[key, entry]] : [];
-  }
-  return Object.entries(files).filter(
-    ([candidate]) =>
-      key === "" || candidate === key || candidate.startsWith(`${key}/`),
-  );
-}
-
-/**
- * Bulk-intent quarantine thresholds. Deliberately the same shape and values as
- * the engine's `BULK_ASYMMETRY_*` constants (`src/cli/share.ts`) so operators
- * learn one rule and one knob: a disappearance covering >= 10 journal entries
- * AND >= 10% of the shard is treated as suspect rather than deliberate.
- */
-const WATCHER_BULK_INTENT_MIN_ABS = 10;
-const WATCHER_BULK_INTENT_RATIO = 0.1;
-
-/**
- * Should a single `unlinkDir` expansion be quarantined instead of stamping a
- * version-bound delete intent on every descendant journal entry?
- *
- * One filesystem event can cover an arbitrary subtree, so the producer is
- * capable of minting thousands of individually-valid intents from a checkout
- * swap, an unmount, a partial restore or an `rm -rf` — the 2026-07-30 mass
- * deletion did exactly that. Quarantined entries are simply left intent-less,
- * which the engine already refuses (`missing-delete-intent`); nothing is
- * deleted locally or remotely and the next pull restores the tree.
- *
- * Pure so the threshold is unit-testable without a watcher or a journal.
- */
-export function shouldQuarantineWatcherDeleteIntents(
-  expandedEntries: number,
-  journalEntries: number,
-): boolean {
-  if (expandedEntries < WATCHER_BULK_INTENT_MIN_ABS) return false;
-  if (journalEntries <= 0) return false;
-  return expandedEntries / journalEntries >= WATCHER_BULK_INTENT_RATIO;
-}
-
-/**
- * Same operator escape hatch as the engine breaker — one knob for both layers.
- * Set when a genuinely intentional large folder removal must propagate.
- */
-function isBulkIntentOverride(): boolean {
-  const v = (process.env.HQ_SYNC_DELETE_BULK_OVERRIDE ?? "").toLowerCase();
-  return v === "1" || v === "true" || v === "yes";
-}
-
-function passExitCode(outcome: number | RunnerPassOutcome): number {
-  return typeof outcome === "number" ? outcome : outcome.exitCode;
-}
-
-function companyPassFailures(
-  outcome: number | RunnerPassOutcome,
-): Array<{ company: string; message: string }> {
-  return typeof outcome === "number"
-    ? []
-    : outcome.result?.companyFailures ?? [];
-}
-
-export async function runOneShotWithOperationLock(
-  argv: string[],
-  parsed: ParsedLoopArgs,
-  deps: RunnerLoopDeps,
-  runtime: WatchLoopRuntime,
-): Promise<number> {
-  const runOnce =
-    deps.runPass ?? runtime.runPassWithOperationLockAlreadyHeld;
-  try {
-    return passExitCode(
-      await withOperationLock(parsed.hqRoot, "sync", () => runOnce(argv), {
-        timeoutSec: parsed.lockTimeoutSec,
-      }),
-    );
-  } catch (err) {
-    if (err instanceof OperationLockedError) {
-      process.stderr.write(err.message + "\n");
-      return OPERATION_LOCKED_EXIT;
-    }
-    throw err;
-  }
-}
-
-export async function runWatchLoop(
-  argv: string[],
-  parsed: ParsedLoopArgs,
-  deps: RunnerLoopDeps,
-  runtime: WatchLoopRuntime,
-): Promise<number> {
-  const sleep =
-    deps.sleep ??
-    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
-  const monotonicNow = deps.monotonicNow ?? (() => performance.now());
-  const runPass =
-    deps.runPass ?? runtime.runPassWithOperationLockAlreadyHeld;
-  const pollIdx = argv.indexOf("--poll-remote-ms");
-  // An explicit --poll-remote-ms pins a fixed interval (menubar/CLI still set
-  // one). When it is omitted, the interval is resolved fresh each cycle from
-  // whole-box load via adaptivePollMs() — see the sleep at the loop's tail.
-  const explicitPollMs =
-    pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : undefined;
-  const sampleLoadAvg = deps.sampleLoadAvg ?? (() => os.loadavg()[0]);
-  const cpuCount = os.cpus().length;
-  const eventPush = argv.includes("--event-push");
-  const companiesMode = argv.includes("--companies");
-  const companyMode = argv.includes("--company");
-  const personalMode = argv.includes("--personal");
-  // Keep this at the watcher ingress rather than importing the runner's
-  // resolver: sync-runner imports this loop, and a reverse value import would
-  // create a runtime cycle. These are the parser's documented truthy values.
-  const skipPersonalEnv = (process.env.HQ_SYNC_SKIP_PERSONAL ?? "").toLowerCase();
-  const watchRouteSelection = {
-    companies: companiesMode,
-    company: companyMode,
-    personal: personalMode,
-    skipPersonal:
-      parsed.skipPersonal === true ||
-      skipPersonalEnv === "1" ||
-      skipPersonalEnv === "true" ||
-      skipPersonalEnv === "yes",
-  };
-  const hqRoot = parsed.hqRoot;
-  // Delayed and daily: this must never be attached to the 15s poll cadence.
-  // Stage 0 remains dry-run only; the standalone hq-backup-prune command is
-  // the explicitly-gated apply surface.
-  let nextBackupPruneAt = Date.now() + 60_000;
-  const runBackupPrune = deps.runBackupPrune ?? (async (root: string) => {
-    const backupRoot = path.join(process.env.HOME ?? "", ".hq", "backups");
-    const plan = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
-    process.stderr.write(`hq-sync-runner: backup retention dry-run — ${plan.candidates.length} candidate(s), ${plan.protected.length} protected\n`);
-  });
-
-  const passArgv = argv.filter((a, i) => {
-    if (a === "--watch") return false;
-    if (a === "--poll-remote-ms") return false;
-    if (a === "--event-push") return false;
-    if (a === "--scope-path") return false;
-    if (a === "--delete-scope-path") return false;
-    if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
-    if (i > 0 && argv[i - 1] === "--scope-path") return false;
-    if (i > 0 && argv[i - 1] === "--delete-scope-path") return false;
-    return true;
-  });
-  // Authoritative direction from parseArgs — never re-derive from argv (that
-  // mis-defaults an omitted --direction to "both" and picks the wrong
-  // occurrence on duplicates). Fall back to the parser's own default ("pull").
-  const originalDirection: Direction = parsed.direction ?? "pull";
-  const drainRunsPush =
-    originalDirection === "both" || originalDirection === "push";
-  const drainRunsPull =
-    originalDirection === "both" || originalDirection === "pull";
-
-  if (parsed.lockTimeoutSec === 0) {
-    try {
-      const handle = acquireOperationLock(hqRoot, "sync", {
-        timeoutSec: 0,
-        onWaitStart: () => undefined,
-      });
-      handle.release();
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-      throw err;
-    }
-  }
-
-  type PassPreparation = () => void;
-  const runPassWithLock = async (
-    passArgvForRun: string[],
-    prepare?: PassPreparation,
-  ): Promise<number | RunnerPassOutcome> => {
-    try {
-      const handle = acquireOperationLock(hqRoot, "sync", {
-        timeoutSec: 0,
-        onWaitStart: () => undefined,
-      });
-      try {
-        prepare?.();
-        return await runPass(passArgvForRun);
-      } finally {
-        handle.release();
-      }
-    } catch (err) {
-      if (!(err instanceof OperationLockedError)) throw err;
-      if (parsed.lockTimeoutSec === 0) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-    }
-
-    try {
-      return await withOperationLock(
-        hqRoot,
-        "sync",
-        () => {
-          prepare?.();
-          return runPass(passArgvForRun);
-        },
-        { timeoutSec: parsed.lockTimeoutSec },
-      );
-    } catch (err) {
-      if (err instanceof OperationLockedError) {
-        process.stderr.write(err.message + "\n");
-        return OPERATION_LOCKED_EXIT;
-      }
-      throw err;
-    }
-  };
-
-  let stopped = false;
-  let resolveStopped: (() => void) | null = null;
-  const stoppedSignal = new Promise<void>((resolve) => {
-    resolveStopped = resolve;
-  });
-  // A signal can arrive while a guarded pass is running, before the next wait
-  // has registered. Keep a monotonic generation so that event is retained and
-  // consumed by the next scheduler wait instead of being lost.
-  let interruptGeneration = 0;
-  let observedInterruptGeneration = 0;
-  let resolveInterruptWait: (() => void) | null = null;
-  const interruptWait = (): void => {
-    if (stopped) return;
-    interruptGeneration += 1;
-    const resolve = resolveInterruptWait;
-    resolveInterruptWait = null;
-    resolve?.();
-  };
-  const waitForNextPass = async (delayMs: number): Promise<void> => {
-    if (interruptGeneration !== observedInterruptGeneration) {
-      observedInterruptGeneration = interruptGeneration;
-      return;
-    }
-
-    await Promise.race([
-      sleep(delayMs),
-      new Promise<void>((resolve) => {
-        resolveInterruptWait = resolve;
-        // Do not lose an event that arrived between the first generation
-        // check and registration of this wait.
-        if (interruptGeneration !== observedInterruptGeneration) {
-          resolveInterruptWait = null;
-          resolve();
-        }
-      }),
-      stoppedSignal,
-    ]);
-    resolveInterruptWait = null;
-    observedInterruptGeneration = interruptGeneration;
-  };
-  let activePass: Promise<number | RunnerPassOutcome> | null = null;
-  type QueuedPass = {
-    argv: string[];
-    prepare?: PassPreparation;
-    resolve: (outcome: number | RunnerPassOutcome) => void;
-    reject: (err: unknown) => void;
-  };
-  const pendingPasses: QueuedPass[] = [];
-  const resolveStoppedQueue = (): void => {
-    while (pendingPasses.length > 0) {
-      pendingPasses.shift()?.resolve(0);
-    }
-  };
-  const drainQueuedPasses = (): void => {
-    if (activePass !== null) return;
-    if (stopped) {
-      resolveStoppedQueue();
-      return;
-    }
-    const next = pendingPasses.shift();
-    if (!next) return;
-    const current = startGuardedPass(next.argv, next.prepare);
-    void current.then(next.resolve, next.reject);
-  };
-  const startGuardedPass = (
-    passArgvForRun: string[],
-    prepare?: PassPreparation,
-  ): Promise<number | RunnerPassOutcome> => {
-    const current = stopped
-      ? Promise.resolve(0)
-      : runPassWithLock(passArgvForRun, prepare);
-    activePass = current;
-    void current
-      .finally(() => {
-        if (activePass === current) {
-          activePass = null;
-          drainQueuedPasses();
-        }
-      })
-      .catch(() => undefined);
-    return current;
-  };
-  const runGuarded = (
-    passArgvForRun: string[],
-    prepare?: PassPreparation,
-  ): Promise<number | RunnerPassOutcome> => {
-    if (activePass === null && pendingPasses.length === 0) {
-      return startGuardedPass(passArgvForRun, prepare);
-    }
-
-    return new Promise<number | RunnerPassOutcome>((resolve, reject) => {
-      pendingPasses.push({ argv: passArgvForRun, prepare, resolve, reject });
-      drainQueuedPasses();
-    });
-  };
-
-  let watcher: WatcherSurface | null = null;
-  let detachSignal: (() => void) | null = null;
-  const pendingWatcherPaths = new Map<string, string>();
-  const pendingWatcherChanges = new Map<string, TreeChange>();
-  let pendingWatcherOriginalBatch: TreeChangeBatch | null = null;
-  // Every coalesced watcher batch gets one durable in-process generation.
-  // A wake can cause the scheduler to revisit a drained batch, but an event
-  // announcement is an external side effect and must occur at most once for
-  // that batch after its targeted push succeeds.
-  let nextWatcherBatchGeneration = 0;
-  let pendingWatcherBatchGeneration: number | null = null;
-  const lastPublishedWatcherBatchGenerationByRoute = new Map<string, number>();
-  let pendingWatcherBareChange = false;
-  let pendingWatcherOverflowed = false;
-  let pendingWatcherDroppedPaths = 0;
-  let pendingWatcherDroppedBytes = 0;
-  const addPendingWatcherChange = (
-    changedRelPath?: string,
-    batch?: TreeChangeBatch,
-  ): boolean => {
-    if (batch) {
-      const paths = new Map<string, string>();
-      const changes = new Map<string, TreeChange>();
-      for (const [absolutePath, relativePath] of batch.paths.entries()) {
-        const route = routeChangeToTarget(relativePath);
-        if (!route || !isWatchRouteSelected(route, watchRouteSelection)) continue;
-        paths.set(absolutePath, relativePath);
-        const change = batch.changes?.get(absolutePath);
-        if (change) changes.set(absolutePath, change);
-      }
-      if (paths.size === 0) return false;
-      batch = {
-        ...batch,
-        paths,
-        changes,
-      };
-    } else if (changedRelPath) {
-      const route = routeChangeToTarget(changedRelPath);
-      if (!route || !isWatchRouteSelected(route, watchRouteSelection)) {
-        return false;
-      }
-    }
-    pendingWatcherBatchGeneration ??= ++nextWatcherBatchGeneration;
-    if (batch) {
-      pendingWatcherOriginalBatch =
-        pendingWatcherPaths.size === 0 &&
-        !pendingWatcherBareChange &&
-        !pendingWatcherOverflowed &&
-        !batch.overflowed
-          ? batch
-          : null;
-      for (const [absolutePath, relativePath] of batch.paths.entries()) {
-        pendingWatcherPaths.set(absolutePath, relativePath);
-        const change = batch.changes?.get(absolutePath);
-        if (change) pendingWatcherChanges.set(absolutePath, change);
-      }
-      if (batch.overflowed) {
-        pendingWatcherOverflowed = true;
-        pendingWatcherDroppedPaths += batch.droppedPaths ?? 0;
-        pendingWatcherDroppedBytes += batch.droppedBytes ?? 0;
-      }
-      return true;
-    }
-    if (changedRelPath) {
-      pendingWatcherOriginalBatch = null;
-      // Codec boundary: `changedRelPath` is a canonical vault key (the
-      // TreeWatcher decodes win32 farm names before emitting), so its local
-      // counterpart must be re-derived through the codec — a raw join would
-      // point at the impossible colon path on Windows.
-      const absolutePath = localPathForVaultKey(hqRoot, changedRelPath);
-      pendingWatcherPaths.set(absolutePath, changedRelPath);
-      // A bare path signal carries no delete intent; drop any change record
-      // a prior batch left for this path so the stale intent cannot leak
-      // into the coalesced batch (#227).
-      pendingWatcherChanges.delete(absolutePath);
-      return true;
-    }
-    pendingWatcherOriginalBatch = null;
-    pendingWatcherBareChange = true;
-    return true;
-  };
-  const takePendingWatcherChange = (): {
-    batch: TreeChangeBatch | null;
-    bare: boolean;
-    generation: number | null;
-  } => {
-    const batch =
-      pendingWatcherOriginalBatch !== null && !pendingWatcherOverflowed
-        ? pendingWatcherOriginalBatch
-        : pendingWatcherPaths.size > 0 || pendingWatcherOverflowed
-          ? {
-              paths: new Map(pendingWatcherPaths),
-              ...(pendingWatcherChanges.size > 0
-                ? { changes: new Map(pendingWatcherChanges) }
-                : {}),
-              ...(pendingWatcherOverflowed
-                ? {
-                    overflowed: true,
-                    droppedPaths: pendingWatcherDroppedPaths,
-                    droppedBytes: pendingWatcherDroppedBytes,
-                  }
-                : {}),
-            }
-          : null;
-    const bare = pendingWatcherBareChange;
-    const generation = pendingWatcherBatchGeneration;
-    pendingWatcherPaths.clear();
-    pendingWatcherChanges.clear();
-    pendingWatcherOriginalBatch = null;
-    pendingWatcherBareChange = false;
-    pendingWatcherOverflowed = false;
-    pendingWatcherDroppedPaths = 0;
-    pendingWatcherDroppedBytes = 0;
-    pendingWatcherBatchGeneration = null;
-    return { batch, bare, generation };
-  };
-  const restorePendingWatcherPaths = (
-    paths: Map<string, string>,
-    generation: number | null,
-  ): void => {
-    pendingWatcherBatchGeneration ??=
-      generation ?? ++nextWatcherBatchGeneration;
-    pendingWatcherOriginalBatch = null;
-    for (const [absolutePath, relativePath] of paths.entries()) {
-      pendingWatcherPaths.set(absolutePath, relativePath);
-    }
-  };
-
-  /**
-   * Journal roots the bulk-intent quarantine has refused for the current
-   * delete episode, keyed `slug\0journalKey`.
-   *
-   * Chokidar (the Linux backend) reports every removed child through `unlink`
-   * BEFORE the parent `unlinkDir`, so by the time the directory expansion is
-   * refused each descendant has already persisted its own version-bound intent
-   * and handed a snapshot to the pending batch. Declining the expansion alone
-   * leaves those intents standing and `prepareWatcherChanges` re-stamps them
-   * from the snapshots, so a large `rm -rf` still propagates in full under
-   * `HQ_SYNC_DELETE_POLICY=all` — the path this producer-side layer exists to
-   * cover, because it bypasses the engine breaker entirely. The trip therefore
-   * revokes the descendants' intents as well, and this set keeps the refusal
-   * in force for the rest of the episode (the native macOS/Windows backends
-   * make no child-before-parent guarantee, so descendants can also arrive
-   * after the directory event).
-   */
-  const quarantinedDeleteRoots = new Set<string>();
-  const QUARANTINE_KEY_SEPARATOR = "\u0000";
-  const quarantineRootKey = (slug: string, journalKey: string): string =>
-    `${slug}${QUARANTINE_KEY_SEPARATOR}${journalKey}`;
-  const quarantineRootFor = (
-    slug: string,
-    journalKey: string,
-  ): string | null => {
-    for (const root of quarantinedDeleteRoots) {
-      const separator = root.indexOf(QUARANTINE_KEY_SEPARATOR);
-      if (root.slice(0, separator) !== slug) continue;
-      const rootKey = root.slice(separator + 1);
-      if (
-        rootKey === "" ||
-        journalKey === rootKey ||
-        journalKey.startsWith(`${rootKey}/`)
-      ) {
-        return root;
-      }
-    }
-    return null;
-  };
-
-  const journalCoordinates = (
-    relativePath: string,
-  ): { slug: string; key: string } | null => {
-    const route = routeChangeToTarget(relativePath);
-    if (!route || !isWatchRouteSelected(route, watchRouteSelection)) return null;
-    if (route.kind === "personal") {
-      return { slug: PERSONAL_VAULT_JOURNAL_SLUG, key: relativePath };
-    }
-    const prefix = `companies/${route.slug}`;
-    return {
-      slug: route.slug,
-      key:
-        relativePath === prefix
-          ? ""
-          : relativePath.slice(prefix.length + 1),
-    };
-  };
-
-  const captureLocalDeleteSnapshots = (
-    relativePath: string,
-    kind: "unlink" | "unlinkDir",
-  ): LocalDeleteSnapshot[] => {
-    const coordinates = journalCoordinates(relativePath);
-    const route = routeChangeToTarget(relativePath);
-    if (!coordinates || !route) return [];
-    const journal = readJournal(coordinates.slug);
-    const snapshots: LocalDeleteSnapshot[] = [];
-    const captureEntry = (
-      key: string,
-      entry: (typeof journal.files)[string] | undefined,
-    ): void => {
-      if (!entry?.remoteEtag || !entry.kind || entry.removedAt !== undefined) {
-        return;
-      }
-      const snapshot: LocalDeleteSnapshot = {
-        journalSlug: coordinates.slug,
-        journalPath: key,
-        deleteScopeRoot: coordinates.key,
-        absolutePath:
-          route.kind === "company"
-            ? path.join(hqRoot, "companies", route.slug, key)
-            : path.join(hqRoot, key),
-        remoteEtag: entry.remoteEtag,
-        localHash: entry.hash,
-        localKind: entry.kind,
-      };
-      if (
-        markLocalDeleteIntent(
-          journal,
-          key,
-          snapshot.localHash,
-          snapshot.localKind,
-          snapshot.remoteEtag,
-        )
-      ) {
-        snapshots.push(snapshot);
-      }
-    };
-
-    // Chokidar emits one unlink per file during rm -rf. Avoid walking the
-    // whole shard for every exact-key event; directory unlinks alone need
-    // descendant expansion.
-    const covered = journalEntriesForWatcherDelete(
-      journal.files,
-      coordinates.key,
-      kind,
-    );
-
-    /**
-     * Revoke every delete intent under this event, including ones a descendant
-     * `unlink` already persisted before the parent `unlinkDir` arrived. An
-     * intent-less disappearance is the safe state: the engine refuses it
-     * (`missing-delete-intent`) under every delete policy, nothing is deleted
-     * locally or remotely, and the next pull restores the subtree.
-     */
-    const revokeCoveredDeleteIntents = (): number => {
-      let revoked = 0;
-      for (const [key] of covered) {
-        if (clearLocalDeleteIntent(journal, key)) revoked += 1;
-      }
-      if (revoked > 0) writeJournal(coordinates.slug, journal);
-      return revoked;
-    };
-
-    // A refused directory removal covers its descendants for the rest of the
-    // episode, whichever order the backend reports them in.
-    if (quarantineRootFor(coordinates.slug, coordinates.key)) {
-      revokeCoveredDeleteIntents();
-      return [];
-    }
-
-    // Bulk-intent quarantine: one directory event must not be able to mint
-    // intents across a large fraction of the shard. Leaving them intent-less
-    // is the safe state — the engine refuses intent-less disappearances and
-    // the next pull restores the subtree.
-    const stampable = covered.filter(
-      ([, entry]) =>
-        entry?.remoteEtag && entry.kind && entry.removedAt === undefined,
-    );
-    if (
-      kind === "unlinkDir" &&
-      !isBulkIntentOverride() &&
-      shouldQuarantineWatcherDeleteIntents(
-        stampable.length,
-        Object.keys(journal.files).length,
-      )
-    ) {
-      quarantinedDeleteRoots.add(
-        quarantineRootKey(coordinates.slug, coordinates.key),
-      );
-      const revoked = revokeCoveredDeleteIntents();
-      process.stderr.write(
-        `hq-sync-runner: refusing to record delete intent for ${stampable.length} ` +
-          `of ${Object.keys(journal.files).length} journal entries under ` +
-          `"${coordinates.key || "<root>"}" — a single directory removal that large ` +
-          `is treated as a possible mirror loss. Nothing was deleted. ` +
-          `Revoked ${revoked} intent(s) already recorded by descendant unlink ` +
-          `events. Set HQ_SYNC_DELETE_BULK_OVERRIDE=1 to propagate it ` +
-          `deliberately.\n`,
-      );
-      return [];
-    }
-
-    for (const [key, entry] of stampable) {
-      captureEntry(key, entry);
-    }
-
-    // Persist at observation time, before the debounced batch can queue
-    // behind an in-flight pull. The pull planner treats this current,
-    // version-bound intent as authoritative and will not resurrect the path.
-    if (snapshots.length > 0) {
-      writeJournal(coordinates.slug, journal);
-    }
-    return snapshots;
-  };
-
-  const prepareWatcherChanges = (changes: Map<string, TreeChange>): void => {
-    const journals = new Map<string, ReturnType<typeof readJournal>>();
-    const dirty = new Set<string>();
-    const journalFor = (slug: string) => {
-      const loaded = journals.get(slug);
-      if (loaded) return loaded;
-      const journal = readJournal(slug);
-      journals.set(slug, journal);
-      return journal;
-    };
-
-    for (const [absolutePath, change] of changes.entries()) {
-      if (change.kind === "unlink" || change.kind === "unlinkDir") {
-        for (const snapshot of change.deleteSnapshots ?? []) {
-          // Snapshots captured by descendant unlinks before the directory
-          // expansion was refused are part of the same quarantined episode.
-          // Re-stamping them here would hand the engine exactly the bulk
-          // delete the quarantine declined.
-          if (quarantineRootFor(snapshot.journalSlug, snapshot.journalPath)) {
-            if (
-              clearLocalDeleteIntent(
-                journalFor(snapshot.journalSlug),
-                snapshot.journalPath,
-              )
-            ) {
-              dirty.add(snapshot.journalSlug);
-            }
-            continue;
-          }
-          let absent = false;
-          try {
-            fs.lstatSync(snapshot.absolutePath);
-          } catch (err: unknown) {
-            const code =
-              err && typeof err === "object" && "code" in err
-                ? (err as { code?: string }).code
-                : undefined;
-            if (code !== "ENOENT") continue;
-            absent = true;
-          }
-          if (!absent) {
-            if (
-              clearLocalDeleteIntent(
-                journalFor(snapshot.journalSlug),
-                snapshot.journalPath,
-              )
-            ) {
-              dirty.add(snapshot.journalSlug);
-            }
-            continue;
-          }
-          if (
-            markLocalDeleteIntent(
-              journalFor(snapshot.journalSlug),
-              snapshot.journalPath,
-              snapshot.localHash,
-              snapshot.localKind,
-              snapshot.remoteEtag,
-            )
-          ) {
-            dirty.add(snapshot.journalSlug);
-          }
-        }
-        continue;
-      }
-
-      const relativePath = path
-        .relative(hqRoot, absolutePath)
-        .split(path.sep)
-        .join("/");
-      const coordinates = journalCoordinates(relativePath);
-      if (
-        coordinates &&
-        clearLocalDeleteIntent(
-          journalFor(coordinates.slug),
-          coordinates.key,
-        )
-      ) {
-        dirty.add(coordinates.slug);
-      }
-    }
-
-    for (const slug of dirty) {
-      writeJournal(slug, journals.get(slug)!);
-    }
-  };
-
-  const groupBatchByRoute = (
-    batch: TreeChangeBatch,
-  ): Map<
-    string,
-    {
-      route: WatchRoute;
-      paths: Map<string, string>;
-      changes: Map<string, TreeChange>;
-      relPaths: string[];
-      deleteScopeRoots: string[];
-    }
-  > => {
-    const grouped = new Map<
-      string,
-      {
-        route: WatchRoute;
-        paths: Map<string, string>;
-        changes: Map<string, TreeChange>;
-        relPaths: string[];
-        deleteScopeRoots: string[];
-      }
-    >();
-    for (const [absolutePath, relativePath] of batch.paths.entries()) {
-      const route = routeChangeToTarget(relativePath);
-      if (!route) continue;
-      const key = routeKey(route);
-      const existing =
-        grouped.get(key) ??
-        {
-          route,
-          paths: new Map<string, string>(),
-          changes: new Map<string, TreeChange>(),
-          relPaths: [],
-          deleteScopeRoots: [],
-        };
-      existing.paths.set(absolutePath, relativePath);
-      const change = batch.changes?.get(absolutePath);
-      if (change) existing.changes.set(absolutePath, change);
-      existing.relPaths = [...new Set([...existing.paths.values()])];
-      existing.deleteScopeRoots = [
-        ...new Set(
-          [...existing.changes.values()].flatMap((item) =>
-            (item.deleteSnapshots ?? []).flatMap((snapshot) =>
-              snapshot.deleteScopeRoot === undefined
-                ? []
-                : [snapshot.deleteScopeRoot],
-            ),
-          ),
-        ),
-      ];
-      grouped.set(key, existing);
-    }
-    return grouped;
-  };
-
-  const publishBatchIfAvailable = (paths: Map<string, string>): boolean => {
-    if (!stopped && eventSync && paths.size > 0) {
-      eventSync.publishBatch({ paths: new Map(paths) });
-      return true;
-    }
-    return false;
-  };
-
-  const runScopedDrain = async (
-    batch: TreeChangeBatch | null,
-    watcherBatchGeneration: number | null,
-  ): Promise<number> => {
-    if (drainRunsPush && batch && batch.paths.size > 0) {
-      const skipCompanies = resolveSkipCompanies();
-      const grouped = groupBatchByRoute(batch);
-      for (const group of grouped.values()) {
-        // Paused workspaces: drop the scoped push without uploading or
-        // publishing event-sync metadata (path/hash must not leak while Off).
-        if (
-          group.route.kind === "company" &&
-          skipCompanies.has(group.route.slug.toLowerCase())
-        ) {
-          continue;
-        }
-        const scopedArgv = buildScopedPushArgv(
-          group.route,
-          group.relPaths,
-          passArgv,
-          group.deleteScopeRoots,
-        );
-        try {
-          const result = await runGuarded(
-            scopedArgv,
-            group.changes.size > 0
-              ? () => prepareWatcherChanges(group.changes)
-              : undefined,
-          );
-          if (passExitCode(result) === 0) {
-            const refusedPaths = new Set(
-              typeof result === "number"
-                ? []
-                : (result.result?.pushPathResults ?? [])
-                    .filter((pathResult) => pathResult.status === "refused")
-                    .map((pathResult) => pathResult.relativePath),
-            );
-            const route = routeKey(group.route);
-            const generation = watcherBatchGeneration ?? 0;
-            if (
-              lastPublishedWatcherBatchGenerationByRoute.get(route) !== generation
-            ) {
-              const published = publishBatchIfAvailable(
-                new Map(
-                  [...group.paths.entries()].filter(
-                    ([absolutePath, relativePath]) => {
-                      if (refusedPaths.has(relativePath)) return false;
-                      if (group.changes.get(absolutePath)?.kind !== "unlinkDir") {
-                        return true;
-                      }
-                      return ![...refusedPaths].some((refusedPath) =>
-                        refusedPath.startsWith(`${relativePath}/`),
-                      );
-                    },
-                  ),
-                ),
-              );
-              if (published) {
-                lastPublishedWatcherBatchGenerationByRoute.set(route, generation);
-              }
-            }
-          } else {
-            restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
-          }
-        } catch (err) {
-          restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
-          process.stderr.write(
-            `watch scoped push failed, will retry next tick: ${describeError(err)}\n`,
-          );
-        }
-      }
-    }
-
-    if (!drainRunsPull) return 0;
-    return passExitCode(
-      await runGuarded(buildScopedDrainPullArgv(passArgv)),
-    );
-  };
-
-  let receiver: PushReceiver | null = null;
-  let eventSync: EventSyncHandles | null = null;
-
-  if (eventPush) {
-    const clock = deps.clock ?? systemClock;
-    const debounceMs = 2000;
-    // The watcher owns the structured degradation event; give it the normal
-    // runner telemetry client so a budget/ENOSPC fallback is observable even
-    // when event-sync itself is not enrolled.
-    const getClaims =
-      deps.getIdTokenClaims ?? runtime.defaultGetIdTokenClaims;
-    const claims = getClaims();
-    const getAccessToken =
-      deps.getAccessToken ?? runtime.defaultGetAccessToken;
-    const watcherTelemetryClient = new VaultClient({
-      apiUrl: runtime.apiUrl,
-      authToken: getAccessToken,
-      region: runtime.region,
-    });
-    const createWatcher =
-      deps.createWatcher ??
-      ((opts) =>
-        new TreeWatcher({
-          hqRoot: opts.hqRoot,
-          debounceMs: opts.debounceMs,
-          clock: opts.clock,
-          personalMode: !companiesMode,
-          captureLocalDeleteSnapshots: opts.captureLocalDeleteSnapshots,
-          telemetryClient: watcherTelemetryClient,
-          telemetryClaims: claims,
-        }));
-    watcher = createWatcher({
-      hqRoot,
-      debounceMs,
-      clock,
-      captureLocalDeleteSnapshots,
-    });
-
-    watcher.onChange((changedRelPath, batch) => {
-      if (stopped) return;
-      if (addPendingWatcherChange(changedRelPath, batch)) interruptWait();
-    });
-    watcher.start();
-
-    const receiverSyncFn: SyncEngineFn = async (ctx) => {
-      if (stopped) return;
-      // A received wake/high-water signal means there is bounded work now.
-      // It wakes the scheduler but is still funneled through runGuarded below,
-      // so it cannot overlap the pass that may currently own the operation
-      // lock.
-      interruptWait();
-      const route = routeChangeToTarget(ctx.event.relativePath);
-      if (!route) return;
-      const targetedArgv = buildTargetedPullArgv(route, passArgv);
-      const result = await runGuarded(targetedArgv);
-      if (passExitCode(result) !== 0) {
-        throw new Error(
-          `targeted pull failed with exit code ${passExitCode(result)}`,
-        );
-      }
-    };
-    const createReceiver = deps.createReceiver ?? (() => new NoopPushReceiver());
-    receiver = createReceiver({ syncFn: receiverSyncFn, hqRoot });
-    void Promise.resolve(receiver.start()).catch(() => undefined);
-
-    if (resolveEventSync(process.env.HQ_SYNC_EVENT_SYNC)) {
-      const startES = deps.startEventSync ?? defaultStartEventSync;
-      void (async () => {
-        const eventSyncClient = new VaultClient({
-          apiUrl: runtime.apiUrl,
-          authToken: getAccessToken,
-          region: runtime.region,
-        });
-        const handles = await startES({
-          hqRoot,
-          apiUrl: runtime.apiUrl,
-          authToken: getAccessToken,
-          deviceId: getOrCreateMachineId(hqRoot),
-          resolveTenantId: async () => {
-            const persons = await eventSyncClient.entity.listByType("person");
-            const pick = pickCanonicalPersonEntity(persons);
-            if (!pick?.uid) {
-              throw new Error("no canonical person entity for this account");
-            }
-            return pick.uid;
-          },
-          syncFn: receiverSyncFn,
-          log: (m) => process.stderr.write(`${m}\n`),
-          telemetryClient: eventSyncClient,
-          telemetryClaims: claims,
-        });
-        if (!handles) return;
-        if (stopped) {
-          void handles.dispose();
-          return;
-        }
-        eventSync = handles;
-      })().catch((err) => {
-        process.stderr.write(
-          `event-sync: wiring failed, continuing poll-only: ${describeError(err)}\n`,
-        );
-      });
-    }
-  }
-
-  const shutdown = (): void => {
-    if (stopped) return;
-    stopped = true;
-    resolveStoppedQueue();
-    try {
-      void receiver?.dispose();
-    } catch {
-      /* ignore */
-    }
-    try {
-      void eventSync?.dispose();
-    } catch {
-      /* ignore */
-    }
-    eventSync = null;
-    try {
-      watcher?.dispose();
-    } catch {
-      /* ignore */
-    }
-    resolveStopped?.();
-  };
-  const onShutdownSignal =
-    deps.onShutdownSignal ??
-    ((handler: () => void) => {
-      const wrapped = () => handler();
-      process.on("SIGTERM", wrapped);
-      process.on("SIGINT", wrapped);
-      return () => {
-        process.off("SIGTERM", wrapped);
-        process.off("SIGINT", wrapped);
-      };
-    });
-  detachSignal = onShutdownSignal(shutdown);
-
-  // The initial reconcile is due immediately. Later passes advance from this
-  // deadline, not from pass completion, so cadence stays monotonic.
-  let nextDueAt = monotonicNow();
-  let pollTick = 0;
-  try {
-    while (!stopped) {
-      pollTick++;
-      const pending = takePendingWatcherChange();
-      // The quarantine is scoped to the delete episode it refused, and only
-      // the roots already refused when this batch was taken belong to it.
-      // Snapshot them here rather than clearing the whole set after the pass:
-      // the pass is awaited, so a bulk removal observed while it runs adds its
-      // root afterwards and its snapshots ride the NEXT batch. Clearing
-      // unconditionally would drop that root before `prepareWatcherChanges`
-      // ever sees the batch, re-stamping the revoked descendant intents and
-      // handing the engine exactly the bulk delete the quarantine refused.
-      const drainedQuarantineRoots = new Set(quarantinedDeleteRoots);
-      const shouldRunFull =
-        pollTick === 1 ||
-        pending.bare ||
-        pending.batch?.overflowed === true ||
-        pollTick % FULL_RECONCILE_EVERY_TICKS === 0;
-      const result = shouldRunFull
-        ? await runGuarded(passArgv)
-        : await runScopedDrain(pending.batch, pending.generation);
-      // This batch's episode has now been prepared and pushed, so a later
-      // removal under the same path is judged fresh — a root that never
-      // expired would silently refuse ordinary deletes from here on.
-      for (const root of drainedQuarantineRoots) {
-        quarantinedDeleteRoots.delete(root);
-      }
-      const exitCode = passExitCode(result);
-      if (exitCode === runtime.authRequiredPassExit) {
-        // The pass already emitted auth-error. Stop the unattended loop but
-        // keep the process exit successful so desktop/manual consumers treat
-        // this as a reauth state, not a crash.
-        return 0;
-      } else if (exitCode === TRANSIENT_NETWORK_EXIT) {
-        // The machine was briefly offline (the discovery fetch failed after
-        // retries). That is NOT a crash — stay alive and retry on the next
-        // poll. Returning it here would exit the watcher and the menubar would
-        // report "watcher exited unexpectedly" for every network blip
-        // (HQ-SYNC-1W). Log to stderr so it still shows up as a breadcrumb.
-        process.stderr.write(
-          "hq-sync-runner: watch pass skipped — transient network failure; retrying next poll\n",
-        );
-      } else if (exitCode === PARTIAL_SYNC_EXIT) {
-        // The pass completed but some per-file transfers threw. Also NOT a
-        // crash: the per-file errors were already emitted as ndjson `error`
-        // events (menubar breadcrumbs + journal), and exiting here just gets
-        // the watcher hot-respawned and Sentry-captured on every failing pass
-        // (the July 2026 code=Some(2) alert flood — see exit-codes.ts). Stay
-        // alive; everything else keeps syncing and the failing paths re-attempt
-        // on the next tick. A one-shot `hq sync` still exits 2.
-        const failures = companyPassFailures(result);
-        const failedCompanies = Array.from(
-          new Set(failures.map((failure) => failure.company)),
-        );
-        for (const failure of failures) {
-          process.stderr.write(
-            `hq-sync-runner: COMPANY PASS FAILED company=${failure.company} message=${failure.message} (downloads for this company did not run)\n`,
-          );
-        }
-        process.stderr.write(
-          "hq-sync-runner: watch pass completed with per-file errors" +
-            (failedCompanies.length > 0
-              ? `; failed-companies=${failedCompanies.join(",")}`
-              : "") +
-            "; staying alive, retrying next poll\n",
-        );
-      } else if (exitCode !== 0) {
-        return exitCode;
-      }
-      if (Date.now() >= nextBackupPruneAt) {
-        // Advance before invoking: a failed/unavailable backstop cannot become
-        // an every-tick retry loop. It is diagnostic only and never restarts
-        // the sync daemon.
-        nextBackupPruneAt = Date.now() + 24 * 60 * 60 * 1000;
-        try { await runBackupPrune(hqRoot); }
-        catch (error) { process.stderr.write(`hq-sync-runner: backup retention dry-run failed — ${error instanceof Error ? error.message : String(error)}\n`); }
-      }
-      const nextPollMs =
-        explicitPollMs ?? adaptivePollMs(sampleLoadAvg(), cpuCount);
-      const schedule = advanceMonotonicDeadline(
-        nextDueAt,
-        monotonicNow(),
-        nextPollMs,
-      );
-      nextDueAt = schedule.nextDueAt;
-      await waitForNextPass(schedule.delayMs);
-    }
-    return 0;
-  } finally {
-    shutdown();
-    detachSignal?.();
-  }
-}