@indigoai-us/hq-cloud 6.13.4 → 6.14.0

package/dist/lib/net-errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Transient network-failure classification for the sync runner.
+ *
+ * The auto-sync watcher runs an unattended poll loop. At the top of every pass
+ * it calls `GET /membership/me` to resolve which companies to sync. When the
+ * machine is briefly offline (wifi drop, waking from sleep, a DNS blip, the
+ * vault API momentarily unreachable) that call fails at the transport layer —
+ * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
+ * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
+ *
+ * This is NOT a crash: the next poll (~30s later) succeeds once the network is
+ * back. But the runner used to `return 1` for it, the watch loop propagated
+ * that non-zero exit, the process exited, and the menubar supervisor reported
+ * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
+ * HQ-SYNC-1W cluster. We classify these so the watch loop can stay alive and
+ * retry instead of surfacing a false crash, while a one-shot `hq sync` still
+ * exits non-zero so a human running it by hand sees the failure.
+ */
+/**
+ * Distinct runner exit code for a transient network failure. The watch loop
+ * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
+ * still exits non-zero so the failure is visible to a human/script. Value 75 =
+ * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
+ * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
+ */
+export declare const TRANSIENT_NETWORK_EXIT = 75;
+/**
+ * True when `err` is (or wraps) a transient network-transport failure. Walks the
+ * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
+ * latter), matching either undici's canonical `TypeError: fetch failed` message
+ * or a known transient `.code`. Conservative by design: an arbitrary
+ * `new Error("network down")` with no code and a non-canonical message is NOT
+ * treated as transient, so only real transport-failure shapes qualify.
+ */
+export declare function isTransientNetworkError(err: unknown, depth?: number): boolean;
+//# sourceMappingURL=net-errors.d.ts.map

package/dist/lib/net-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.d.ts","sourceRoot":"","sources":["../../src/lib/net-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AA0BzC;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAsBxE"}

package/dist/lib/net-errors.js

@@ -0,0 +1,81 @@
+/**
+ * Transient network-failure classification for the sync runner.
+ *
+ * The auto-sync watcher runs an unattended poll loop. At the top of every pass
+ * it calls `GET /membership/me` to resolve which companies to sync. When the
+ * machine is briefly offline (wifi drop, waking from sleep, a DNS blip, the
+ * vault API momentarily unreachable) that call fails at the transport layer —
+ * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
+ * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
+ *
+ * This is NOT a crash: the next poll (~30s later) succeeds once the network is
+ * back. But the runner used to `return 1` for it, the watch loop propagated
+ * that non-zero exit, the process exited, and the menubar supervisor reported
+ * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
+ * HQ-SYNC-1W cluster. We classify these so the watch loop can stay alive and
+ * retry instead of surfacing a false crash, while a one-shot `hq sync` still
+ * exits non-zero so a human running it by hand sees the failure.
+ */
+/**
+ * Distinct runner exit code for a transient network failure. The watch loop
+ * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
+ * still exits non-zero so the failure is visible to a human/script. Value 75 =
+ * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
+ * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
+ */
+export const TRANSIENT_NETWORK_EXIT = 75;
+/**
+ * Node/undici error `code`s that mean "the request never completed at the
+ * transport layer" — the machine could not reach the host. All are transient:
+ * a later attempt from the same machine can succeed unchanged.
+ */
+const TRANSIENT_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EHOSTUNREACH",
+    "EHOSTDOWN",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "ECONNABORTED",
+    // undici's own timeout/socket failures
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/**
+ * True when `err` is (or wraps) a transient network-transport failure. Walks the
+ * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
+ * latter), matching either undici's canonical `TypeError: fetch failed` message
+ * or a known transient `.code`. Conservative by design: an arbitrary
+ * `new Error("network down")` with no code and a non-canonical message is NOT
+ * treated as transient, so only real transport-failure shapes qualify.
+ */
+export function isTransientNetworkError(err, depth = 0) {
+    if (depth > 8 || !(err instanceof Error))
+        return false;
+    // undici's transport failure surfaces as exactly this message.
+    if (err.message === "fetch failed")
+        return true;
+    const code = err.code;
+    if (typeof code === "string" && TRANSIENT_CODES.has(code))
+        return true;
+    // AggregateError (e.g. happy-eyeballs) stashes the per-attempt errors here.
+    const aggregated = err.errors;
+    if (Array.isArray(aggregated)) {
+        for (const inner of aggregated) {
+            if (isTransientNetworkError(inner, depth + 1))
+                return true;
+        }
+    }
+    const cause = err.cause;
+    if (cause !== undefined && cause !== err) {
+        return isTransientNetworkError(cause, depth + 1);
+    }
+    return false;
+}
+//# sourceMappingURL=net-errors.js.map

package/dist/lib/net-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.js","sourceRoot":"","sources":["../../src/lib/net-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;GAIG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS;IACtC,cAAc;IACd,YAAY;IACZ,WAAW;IACX,WAAW;IACX,WAAW;IACX,OAAO;IACP,cAAc;IACd,WAAW;IACX,aAAa;IACb,UAAU;IACV,cAAc;IACd,uCAAuC;IACvC,yBAAyB;IACzB,yBAAyB;IACzB,sBAAsB;IACtB,gBAAgB;CACjB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY,EAAE,KAAK,GAAG,CAAC;IAC7D,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEvD,+DAA+D;IAC/D,IAAI,GAAG,CAAC,OAAO,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,4EAA4E;IAC5E,MAAM,UAAU,GAAI,GAA4B,CAAC,MAAM,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,IAAI,uBAAuB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAI,GAA2B,CAAC,KAAK,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACzC,OAAO,uBAAuB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/net-errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=net-errors.test.d.ts.map

package/dist/lib/net-errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.test.d.ts","sourceRoot":"","sources":["../../src/lib/net-errors.test.ts"],"names":[],"mappings":""}

package/dist/lib/net-errors.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { isTransientNetworkError, TRANSIENT_NETWORK_EXIT } from "./net-errors.js";
+describe("isTransientNetworkError", () => {
+    it("treats undici's canonical `fetch failed` TypeError as transient", () => {
+        // This is the exact shape the runner's discovery step sees in production
+        // (HQ-SYNC-1W): `{"type":"error","message":"fetch failed","path":"(discovery)"}`.
+        expect(isTransientNetworkError(new TypeError("fetch failed"))).toBe(true);
+    });
+    it("treats known transport `.code`s as transient", () => {
+        for (const code of ["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT"]) {
+            const err = Object.assign(new Error("boom"), { code });
+            expect(isTransientNetworkError(err)).toBe(true);
+        }
+    });
+    it("walks the .cause chain (fetch failed wrapping a DNS error)", () => {
+        const cause = Object.assign(new Error("getaddrinfo ENOTFOUND api"), {
+            code: "ENOTFOUND",
+        });
+        const err = Object.assign(new TypeError("fetch failed"), { cause });
+        expect(isTransientNetworkError(err)).toBe(true);
+    });
+    it("walks AggregateError.errors (happy-eyeballs)", () => {
+        const agg = Object.assign(new AggregateError([
+            Object.assign(new Error("v4"), { code: "ECONNREFUSED" }),
+            Object.assign(new Error("v6"), { code: "EHOSTUNREACH" }),
+        ], "all attempts failed"), {});
+        expect(isTransientNetworkError(agg)).toBe(true);
+    });
+    it("is conservative: an arbitrary error is NOT transient", () => {
+        // A bare message like "network down" (no code, not the canonical undici
+        // message) must not be misclassified — only real transport shapes qualify.
+        expect(isTransientNetworkError(new Error("network down"))).toBe(false);
+        expect(isTransientNetworkError(new Error("boom"))).toBe(false);
+        expect(isTransientNetworkError("fetch failed")).toBe(false);
+        expect(isTransientNetworkError(undefined)).toBe(false);
+    });
+    it("does not infinite-loop on a self-referential cause", () => {
+        const err = new Error("weird");
+        err.cause = err;
+        expect(isTransientNetworkError(err)).toBe(false);
+    });
+    it("exposes a distinct exit code off the runner's other codes", () => {
+        expect(TRANSIENT_NETWORK_EXIT).toBe(75);
+        expect([0, 1, 2, 17]).not.toContain(TRANSIENT_NETWORK_EXIT);
+    });
+});
+//# sourceMappingURL=net-errors.test.js.map

package/dist/lib/net-errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.test.js","sourceRoot":"","sources":["../../src/lib/net-errors.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.13.4",
+  "version": "6.14.0",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner-company.ts

@@ -6,6 +6,13 @@ import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import type { VaultServiceConfig } from "../index.js";
 import { resolvePullScope, type PullScope } from "../sync/pull-scope.js";
+import {
+  coalescePrefixes,
+  pathToScopePrefix,
+  toScopePrefixEntries,
+  type ScopePrefixEntry,
+  type ScopePrefixInput,
+} from "../prefix-coalesce.js";
 import { describeError } from "../lib/describe-error.js";
 import type {
   DeletePropagationPolicy,
@@ -42,6 +49,7 @@ export async function executeCompanyFanout(options: {
   shareFn: (options: ShareOptions) => Promise<ShareResult>;
   resolveDeletePolicy: () => DeletePropagationPolicy;
   emit: (event: RunnerEvent) => void;
+  scopePaths?: string[];
 }): Promise<CompanyFanoutResult> {
   const doPush =
     options.direction === "push" || options.direction === "both";
@@ -196,6 +204,10 @@ export async function executeCompanyFanout(options: {
 
       if (doPush) {
         activePhase = "push";
+        const pushPrefixSet = effectivePushPrefixSet(
+          scope.prefixSet,
+          options.scopePaths ?? [],
+        );
         const pushPaths =
           target.personalMode === true
             ? computePersonalVaultPaths(options.hqRoot, { teamSyncedSlugs })
@@ -224,8 +236,8 @@ export async function executeCompanyFanout(options: {
           ...(decommissionPrefixes && decommissionPrefixes.length > 0
             ? { decommissionPrefixes }
             : {}),
-          ...(scope.prefixSet !== undefined
-            ? { prefixSet: scope.prefixSet }
+          ...(pushPrefixSet !== undefined
+            ? { prefixSet: pushPrefixSet }
             : {}),
         });
       }
@@ -364,6 +376,53 @@ export async function executeCompanyFanout(options: {
   return { stateByCompany, errors, allConflicts };
 }
 
+function effectivePushPrefixSet(
+  aclPrefixSet: readonly ScopePrefixInput[] | undefined,
+  scopePaths: readonly string[],
+): string[] | undefined {
+  if (scopePaths.length === 0) {
+    return aclPrefixSet === undefined
+      ? undefined
+      : coalescePrefixes(aclPrefixSet);
+  }
+
+  const requested = scopePaths.flatMap((p) => [
+    pathToScopePrefix(p),
+    pathToScopePrefix(p.endsWith("/") ? p : p + "/"),
+  ]);
+  if (aclPrefixSet === undefined) {
+    return coalescePrefixes(requested);
+  }
+
+  const aclEntries = toScopePrefixEntries(aclPrefixSet);
+  const requestedEntries = toScopePrefixEntries(requested);
+  const intersection: ScopePrefixEntry[] = [];
+  for (const requestedEntry of requestedEntries) {
+    for (const aclEntry of aclEntries) {
+      if (entryCoversEntry(aclEntry, requestedEntry)) {
+        intersection.push(requestedEntry);
+      } else if (entryCoversEntry(requestedEntry, aclEntry)) {
+        intersection.push(aclEntry);
+      }
+    }
+  }
+  return coalescePrefixes(intersection);
+}
+
+function entryCoversEntry(
+  entry: ScopePrefixEntry,
+  candidate: ScopePrefixEntry,
+): boolean {
+  if (entry.prefix === "") return true;
+  if (entry.match === "prefix") {
+    return (
+      candidate.prefix === entry.prefix ||
+      candidate.prefix.startsWith(entry.prefix)
+    );
+  }
+  return candidate.match === "exact" && candidate.prefix === entry.prefix;
+}
+
 function normalizePullChangedPaths(
   target: RunnerTarget,
   changedPaths: string[] | undefined,

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

@@ -8,10 +8,10 @@ import {
   OPERATION_LOCKED_EXIT,
 } from "../operation-lock.js";
 import { describeError } from "../lib/describe-error.js";
+import { TRANSIENT_NETWORK_EXIT } from "../lib/net-errors.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
   TreeWatcher,
-  WatchPushDriver,
   systemClock,
   type TreeChangeBatch,
 } from "../watcher.js";
@@ -26,18 +26,28 @@ import {
   type EventSyncHandles,
 } from "../sync/event-sync.js";
 import {
-  buildFullFanoutPushArgv,
+  buildScopedDrainPullArgv,
+  buildScopedPushArgv,
   buildTargetedPullArgv,
-  buildTargetedPushArgv,
   routeChangeToTarget,
-  routesForBatch,
+  routeKey,
   type WatchRoute,
 } from "./sync-runner-watch-routes.js";
-import type { RunnerLoopDeps, WatcherSurface } from "./sync-runner.js";
+import type { Direction, RunnerLoopDeps, WatcherSurface } from "./sync-runner.js";
+
+const FULL_RECONCILE_EVERY_TICKS = 10;
 
 export interface ParsedLoopArgs {
   hqRoot: string;
   lockTimeoutSec?: number;
+  /**
+   * 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 {
@@ -91,9 +101,19 @@ export async function runWatchLoop(
     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 (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
+    if (i > 0 && argv[i - 1] === "--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 {
@@ -197,7 +217,6 @@ export async function runWatchLoop(
   };
 
   let watcher: WatcherSurface | null = null;
-  let driver: WatchPushDriver | null = null;
   let detachSignal: (() => void) | null = null;
   const pendingWatcherPaths = new Map<string, string>();
   let pendingWatcherOriginalBatch: TreeChangeBatch | null = null;
@@ -236,8 +255,8 @@ export async function runWatchLoop(
     pendingWatcherBareChange = true;
   };
   const takePendingWatcherChange = (): {
-    rel: string | null;
     batch: TreeChangeBatch | null;
+    bare: boolean;
   } => {
     const batch =
       pendingWatcherOriginalBatch !== null && !pendingWatcherOverflowed
@@ -254,15 +273,81 @@ export async function runWatchLoop(
                 : {}),
             }
           : null;
-    const rel = [...pendingWatcherPaths.values()][0] ?? null;
-    const fallbackRel = rel ?? (pendingWatcherBareChange ? null : null);
+    const bare = pendingWatcherBareChange;
     pendingWatcherPaths.clear();
     pendingWatcherOriginalBatch = null;
     pendingWatcherBareChange = false;
     pendingWatcherOverflowed = false;
     pendingWatcherDroppedPaths = 0;
     pendingWatcherDroppedBytes = 0;
-    return { rel: fallbackRel, batch };
+    return { batch, bare };
+  };
+  const restorePendingWatcherPaths = (paths: Map<string, string>): void => {
+    pendingWatcherOriginalBatch = null;
+    for (const [absolutePath, relativePath] of paths.entries()) {
+      pendingWatcherPaths.set(absolutePath, relativePath);
+    }
+  };
+
+  const groupBatchByRoute = (
+    batch: TreeChangeBatch,
+  ): Map<
+    string,
+    { route: WatchRoute; paths: Map<string, string>; relPaths: string[] }
+  > => {
+    const grouped = new Map<
+      string,
+      { route: WatchRoute; paths: Map<string, string>; relPaths: 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>(), relPaths: [] };
+      existing.paths.set(absolutePath, relativePath);
+      existing.relPaths = [...new Set([...existing.paths.values()])];
+      grouped.set(key, existing);
+    }
+    return grouped;
+  };
+
+  const publishBatchIfAvailable = (paths: Map<string, string>): void => {
+    if (!stopped && eventSync && paths.size > 0) {
+      eventSync.publishBatch({ paths: new Map(paths) });
+    }
+  };
+
+  const runScopedDrain = async (
+    batch: TreeChangeBatch | null,
+  ): Promise<number> => {
+    if (drainRunsPush && batch && batch.paths.size > 0) {
+      const grouped = groupBatchByRoute(batch);
+      for (const group of grouped.values()) {
+        const scopedArgv = buildScopedPushArgv(
+          group.route,
+          group.relPaths,
+          passArgv,
+        );
+        try {
+          const result = await runGuarded(scopedArgv);
+          if (result === 0) {
+            publishBatchIfAvailable(group.paths);
+          } else {
+            restorePendingWatcherPaths(group.paths);
+          }
+        } catch (err) {
+          restorePendingWatcherPaths(group.paths);
+          process.stderr.write(
+            `watch scoped push failed, will retry next tick: ${describeError(err)}\n`,
+          );
+        }
+      }
+    }
+
+    if (!drainRunsPull) return 0;
+    return runGuarded(buildScopedDrainPullArgv(passArgv));
   };
 
   let receiver: PushReceiver | null = null;
@@ -282,47 +367,9 @@ export async function runWatchLoop(
         }));
     watcher = createWatcher({ hqRoot, debounceMs, clock });
 
-    driver = new WatchPushDriver({
-      debounceMs: 0,
-      clock,
-      push: async () => {
-        if (stopped) return;
-        const { rel, batch: batchForPublish } = takePendingWatcherChange();
-        const batchRoutes = batchForPublish
-          ? routesForBatch(batchForPublish)
-          : new Map<string, WatchRoute>();
-        let targetedArgv: string[];
-        if (batchForPublish?.overflowed || batchRoutes.size > 1) {
-          targetedArgv = buildFullFanoutPushArgv(passArgv);
-        } else {
-          const route =
-            batchRoutes.size === 1
-              ? [...batchRoutes.values()][0]
-              : rel
-                ? routeChangeToTarget(rel)
-                : { kind: "personal" as const };
-          if (!route) return;
-          targetedArgv = buildTargetedPushArgv(route, passArgv);
-        }
-        const result = await runGuarded(targetedArgv);
-        if (
-          result === 0 &&
-          !stopped &&
-          eventSync &&
-          !batchForPublish?.overflowed
-        ) {
-          const batch: TreeChangeBatch | null =
-            batchForPublish ??
-            (rel ? { paths: new Map([[path.join(hqRoot, rel), rel]]) } : null);
-          if (batch) eventSync.publishBatch(batch);
-        }
-      },
-    });
-
     watcher.onChange((changedRelPath, batch) => {
       if (stopped) return;
       addPendingWatcherChange(changedRelPath, batch);
-      driver?.notifyChange();
     });
     watcher.start();
 
@@ -402,11 +449,6 @@ export async function runWatchLoop(
       /* ignore */
     }
     eventSync = null;
-    try {
-      driver?.dispose();
-    } catch {
-      /* ignore */
-    }
     try {
       watcher?.dispose();
     } catch {
@@ -427,10 +469,29 @@ export async function runWatchLoop(
     });
   detachSignal = onShutdownSignal(shutdown);
 
+  let pollTick = 0;
   try {
     while (!stopped) {
-      const result = await runGuarded(passArgv);
-      if (result !== 0) {
+      pollTick++;
+      const pending = takePendingWatcherChange();
+      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);
+      if (result === 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 (result !== 0) {
         return result;
       }
       await Promise.race([sleep(pollMs), stoppedSignal]);

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

@@ -37,10 +37,48 @@ export function buildTargetedPushArgv(
   return ["--companies", "--direction", "push", ...carried];
 }
 
+export function buildScopedPushArgv(
+  route: WatchRoute,
+  relPaths: readonly string[],
+  baseArgv: string[],
+): string[] {
+  const scopeArgs = scopedPathArgs(route, relPaths);
+  const carried = carriedFlags(baseArgv);
+  if (route.kind === "company") {
+    return [
+      "--company",
+      route.slug,
+      "--direction",
+      "push",
+      ...scopeArgs,
+      ...carried,
+    ];
+  }
+  return ["--personal", "--direction", "push", ...scopeArgs, ...carried];
+}
+
 export function buildFullFanoutPushArgv(baseArgv: string[]): string[] {
   return ["--companies", "--direction", "push", ...carriedFlags(baseArgv)];
 }
 
+export function buildScopedDrainPullArgv(baseArgv: string[]): string[] {
+  const carried = carriedFlags(baseArgv);
+  if (baseArgv.includes("--personal")) {
+    return ["--personal", "--direction", "pull", ...carried];
+  }
+  const companyIdx = baseArgv.indexOf("--company");
+  if (companyIdx >= 0 && baseArgv[companyIdx + 1] !== undefined) {
+    return [
+      "--company",
+      baseArgv[companyIdx + 1],
+      "--direction",
+      "pull",
+      ...carried,
+    ];
+  }
+  return ["--companies", "--direction", "pull", ...carried];
+}
+
 /**
  * Build the argv for a targeted pull pass from a routed change.
  */
@@ -55,7 +93,7 @@ export function buildTargetedPullArgv(
   return ["--companies", "--direction", "pull", ...carried];
 }
 
-function routeKey(route: WatchRoute): string {
+export function routeKey(route: WatchRoute): string {
   return route.kind === "company" ? `company:${route.slug}` : "personal";
 }
 
@@ -69,6 +107,24 @@ export function routesForBatch(batch: TreeChangeBatch): Map<string, WatchRoute>
   return routes;
 }
 
+function scopedPathArgs(route: WatchRoute, relPaths: readonly string[]): string[] {
+  const args: string[] = [];
+  for (const relPath of relPaths) {
+    const scopePath = scopePathForRoute(route, relPath);
+    if (scopePath === null) continue;
+    args.push("--scope-path", scopePath);
+  }
+  return args;
+}
+
+function scopePathForRoute(route: WatchRoute, relPath: string): string | null {
+  const norm = relPath.split(path.sep).join("/").replace(/^\.\//, "");
+  if (route.kind === "personal") return norm;
+  const prefix = `companies/${route.slug}/`;
+  if (norm.startsWith(prefix)) return norm.slice(prefix.length);
+  return null;
+}
+
 /**
  * Extract the `--hq-root` / `--on-conflict` pair-flags from a base argv so a
  * re-targeted pass inherits the same root and conflict policy.