@indigoai-us/hq-cloud 6.14.25 → 6.14.27

package/src/cli/sync.ts

@@ -316,8 +316,9 @@ export type SyncProgressEvent =
       /**
        * Emitted at most ONCE per PULL leg when the leg ran under a
        * membership-scoped `syncMode` (`"shared"` or `"custom"` — never `"all"`)
-       * AND one or more remote keys were skipped as out-of-scope
-       * (`filesOutOfScope > 0`). This turns the silent shared-vs-all gap into a
+       * AND one or more remote keys were withheld BY THAT MEMBERSHIP SCOPE
+       * (`skip-out-of-scope` with `reason: "membership-scope"`). This turns the
+       * silent shared-vs-all gap into a
        * VISIBLE, actionable surface. The reporter of feedback_d2082110 lost
        * files across devices precisely because four memberships defaulted to
        * `shared` rather than `all`, so not all vault content materialized on the
@@ -327,11 +328,16 @@ export type SyncProgressEvent =
        * materialization is a deliberate, visible choice rather than a silent
        * omission.
        *
-       * `count` is the number of remote keys skipped as out-of-scope on this
-       * leg; `samplePaths` carries up to 10 company-relative keys for display;
-       * `syncMode` is the active scoped mode. Distinct from the push-side
-       * `scope-excluded` (which reports what a grantee could not PUSH). Not
-       * emitted in `all` mode or when `count === 0` — no gap, no noise.
+       * `count` is the number of remote keys the MEMBERSHIP SCOPE withheld on
+       * this leg; `samplePaths` carries up to 10 company-relative keys for
+       * display; `syncMode` is the active scoped mode. Push-only keys
+       * (`sessions/`, US-006) are deliberately EXCLUDED from both — they are
+       * withheld in every mode including `all`, so the lever this event names
+       * would not materialize them. `count` is therefore ≤
+       * `SyncResult.filesOutOfScope`, which keeps its both-causes meaning.
+       * Distinct from the push-side `scope-excluded` (which reports what a
+       * grantee could not PUSH). Not emitted in `all` mode or when nothing was
+       * withheld by the membership scope — no gap, no noise.
        */
       type: "scope-materialization-gap";
       count: number;
@@ -908,7 +914,7 @@ async function syncWithOperationLockHeld(
   await verifyPlannedJournalTombstones(run, plan);
   executeJournalTombstoneDeletes(run, plan, counters);
 
-  emitScopeMaterializationGap(run, plan, counters);
+  emitScopeMaterializationGap(run, plan);
 
   return finalizePullRun(run, plan, scopeRun, counters);
 }
@@ -1917,27 +1923,31 @@ function finalizePullRun(
  * remote keys as out-of-scope, emit a single summary event so the operator
  * SEES that not all vault content materialized on this device and knows the
  * lever — raise the membership's access level to `all`. Silent in `all` mode
- * (nothing is scoped away) and when nothing fell out of scope: no gap, no
- * noise. Deliberately AFTER the transfer executors, so `filesOutOfScope` is
- * final; sample keys are read off the plan's `skip-out-of-scope` items (pure,
- * no I/O). This is the visible complement to the previously-silent
- * `SyncResult.filesOutOfScope` count.
+ * (nothing is scoped away) and when the membership scope withheld nothing: no
+ * gap, no noise. Pure — count and samples are both read off the plan's
+ * `skip-out-of-scope` items, no I/O.
+ *
+ * Counts ONLY `reason: "membership-scope"` items. `push-only` keys
+ * (`sessions/`, US-006) are also classified `skip-out-of-scope` and also land
+ * on the `filesOutOfScope` axis, but they are withheld in EVERY mode — `all`
+ * included — so raising the access level does NOT materialize them. Counting
+ * them here would inflate the gap, could fill `samplePaths` entirely with
+ * session keys, and could fire the event (and its "set this membership to
+ * `all`" advice) when the membership scope withheld nothing at all — sending
+ * the operator back into exactly the flip-everything-to-`all`-and-still-miss
+ * -files loop this event exists to end. `SyncResult.filesOutOfScope` keeps its
+ * original both-causes meaning; only this advisory is narrowed.
  */
-function emitScopeMaterializationGap(
-  run: PullRunContext,
-  plan: PullPlan,
-  counters: PullCounters,
-): void {
+function emitScopeMaterializationGap(run: PullRunContext, plan: PullPlan): void {
   if (run.syncMode === "all") return;
-  if (counters.filesOutOfScope <= 0) return;
-  const samplePaths = plan.items
-    .filter((item) => item.action === "skip-out-of-scope")
-    .slice(0, 10)
-    .map((item) => item.remoteFile.key);
+  const withheldByMembership = plan.items.filter(
+    (item) => item.action === "skip-out-of-scope" && item.reason === "membership-scope",
+  );
+  if (withheldByMembership.length === 0) return;
   run.emit({
     type: "scope-materialization-gap",
-    count: counters.filesOutOfScope,
-    samplePaths,
+    count: withheldByMembership.length,
+    samplePaths: withheldByMembership.slice(0, 10).map((item) => item.remoteFile.key),
     syncMode: run.syncMode,
   });
 }
@@ -2111,6 +2121,14 @@ type LocalSnapshot =
   | { kind: "absent" | "directory" | "other" }
   | { kind: "file" | "symlink"; hash: string };
 
+/**
+ * Why a remote key was classified `skip-out-of-scope`. The two causes look
+ * identical in the count but have OPPOSITE remedies, so they must never be
+ * reported as one: `membership-scope` is fixed by raising the membership's
+ * access level to `all`; `push-only` is not fixed by that at all.
+ */
+type OutOfScopeReason = "membership-scope" | "push-only";
+
 type PullPlanItem =
   | {
       action: "download";
@@ -2145,10 +2163,25 @@ type PullPlanItem =
   // refused to upload these since 5.33.0; the pull walker now refuses to
   // download them so legacy litter in cloud staging drains naturally.
   | { action: "skip-excluded-policy"; remoteFile: RemoteFile; localPath: string }
-  // Remote keys outside the effective `syncMode` scope (US-005). Present in
-  // the remote LIST (and accessible per STS) but deliberately not downloaded
-  // because the membership's sync scope doesn't cover them.
-  | { action: "skip-out-of-scope"; remoteFile: RemoteFile; localPath: string }
+  // Remote keys present in the remote LIST (and accessible per STS) but
+  // deliberately not downloaded. Two DIFFERENT causes share this action and
+  // the `filesOutOfScope` count, so `reason` discriminates them:
+  //
+  //   `membership-scope` — outside the effective `syncMode` prefix set
+  //     (US-005). RAISING the membership's access level to `all` WOULD
+  //     materialize these keys.
+  //   `push-only`        — under a push-only exclude prefix (`sessions/`,
+  //     US-006). These are withheld in EVERY mode, `all` included; raising
+  //     the access level does NOT materialize them (`hq files get` does).
+  //
+  // Only `membership-scope` items may be attributed to the shared-vs-all gap
+  // — see `emitScopeMaterializationGap`. feedback_d2082110.
+  | {
+      action: "skip-out-of-scope";
+      remoteFile: RemoteFile;
+      localPath: string;
+      reason: OutOfScopeReason;
+    }
   | {
       // Mixed-version amplifier guard — see the `skip-junk-key-spelling`
       // event doc. Carries the journaled spelling for the warning surface.
@@ -2447,8 +2480,20 @@ function computePullPlan(
     // `all` and preserves the legacy full-bucket pull bit-for-bit. The
     // previously-downloaded counterparts of these keys (if scope just shrank)
     // are pruned separately by the scope-shrink pass in `sync()`.
+    // A key can fail the inclusion check AND sit under a push-only exclude
+    // prefix. Attribute it to `push-only` in that case: widening the
+    // membership to `all` would move it into `prefixSet` but the exclusion
+    // below would still withhold it, so it is NOT part of the shared-vs-all
+    // gap and must not be advertised as fixable by raising the access level.
     if (!isCoveredByAny(remoteFile.key, prefixSet)) {
-      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      items.push({
+        action: "skip-out-of-scope",
+        remoteFile,
+        localPath,
+        reason: isCoveredByAny(remoteFile.key, excludePrefixes)
+          ? "push-only"
+          : "membership-scope",
+      });
       continue;
     }
 
@@ -2462,7 +2507,12 @@ function computePullPlan(
     // previously pulled, authored locally, or pinned+materialized) is NOT pruned
     // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
     if (isCoveredByAny(remoteFile.key, excludePrefixes)) {
-      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      items.push({
+        action: "skip-out-of-scope",
+        remoteFile,
+        localPath,
+        reason: "push-only",
+      });
       continue;
     }
 

package/src/watcher.test.ts

@@ -2,11 +2,14 @@ import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { watch } from "chokidar";
 import {
   FakeClock,
   WatchPushDriver,
   TreeWatcher,
+  ChokidarWatchBudget,
   createWatchPathFilter,
+  toChokidarIgnored,
   PushEventEmitter,
 } from "./watcher.js";
 import { StaticFlagProvider } from "./sync/feature-flags.js";
@@ -465,6 +468,87 @@ describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
   });
 });
 
+describe("US-002: chokidar descent scope", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-scope-")));
+    // This is the real HQ allowlist shape. The synthetic heavy directories
+    // deliberately sit both under an in-scope company and under the two
+    // never-synced top-level buckets from #156.
+    fs.writeFileSync(path.join(dir, ".hqinclude"), "companies/*/knowledge/\n");
+    fs.mkdirSync(
+      path.join(dir, "companies", "acme", "knowledge", "node_modules", "heavy"),
+      { recursive: true },
+    );
+    fs.writeFileSync(
+      path.join(dir, "companies", "acme", "knowledge", "node_modules", "heavy", "index.js"),
+      "module.exports = 1;\n",
+    );
+    fs.mkdirSync(path.join(dir, "repos", "checkout", "heavy"), { recursive: true });
+    fs.mkdirSync(
+      path.join(dir, "workspace", "worktrees", "repo", "node_modules", "heavy"),
+      { recursive: true },
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("uses the directory verdict, not a file-shaped false positive, for the pre-stat probe", () => {
+    const filter = createWatchPathFilter(dir, false);
+    const nodeModules = path.join(
+      dir,
+      "companies",
+      "acme",
+      "knowledge",
+      "node_modules",
+    );
+    // `node_modules/` is directory-only. Asking the generic emit filter as
+    // though it were a file returns true, which is exactly what the old
+    // `file || directory` probe used to mistake for permission to descend.
+    expect(filter(nodeModules, false)).toBe(true);
+    expect(filter(nodeModules, true)).toBe(false);
+    const ignored = toChokidarIgnored(filter, dir);
+    expect(ignored(nodeModules)).toBe(true);
+    // The allowlist's exact ancestor matcher remains the only carve-out: the
+    // watcher can still reach companies/<slug>/knowledge without opening every
+    // otherwise-file-shaped ignored directory below it.
+    expect(ignored(path.join(dir, "companies"))).toBe(false);
+    expect(ignored(path.join(dir, "companies", "acme"))).toBe(false);
+  });
+
+  it("prunes ignored directories during chokidar's pre-stat descent probe", async () => {
+    const filter = createWatchPathFilter(dir, false);
+    const chokidarWatcher = watch(dir, {
+      ignored: toChokidarIgnored(filter, dir),
+      ignoreInitial: true,
+      persistent: false,
+    });
+    try {
+      await new Promise<void>((resolve, reject) => {
+        chokidarWatcher.once("ready", resolve);
+        chokidarWatcher.once("error", reject);
+      });
+      const descended = Object.keys(chokidarWatcher.getWatched())
+        .map((watchedPath) => path.resolve(watchedPath))
+        .sort();
+
+      expect(descended).toContain(
+        path.join(dir, "companies", "acme", "knowledge"),
+      );
+      expect(descended).not.toContain(
+        path.join(dir, "companies", "acme", "knowledge", "node_modules"),
+      );
+      expect(descended).not.toContain(path.join(dir, "repos"));
+      expect(descended).not.toContain(path.join(dir, "workspace", "worktrees"));
+    } finally {
+      await chokidarWatcher.close();
+    }
+  });
+});
+
 describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
   function makeWatcher(opts?: { debounceMs?: number; personalMode?: boolean }) {
     const clock = new FakeClock();
@@ -555,6 +639,170 @@ describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
     expect(source).not.toContain("startPollingTreeWatch");
     expect(source).not.toContain("snapshotWatchTree");
   });
+
+  it("stops descending at the hard watch budget, reports, and degrades to polling", () => {
+    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "watch-cap-")));
+    fs.mkdirSync(path.join(dir, "personal", "a", "deep"), { recursive: true });
+    fs.mkdirSync(path.join(dir, "personal", "b", "deep"), { recursive: true });
+    const clock = new FakeClock();
+    const degraded = vi.fn();
+    const changed = vi.fn();
+    const descended: string[] = [];
+    let backendClosed = false;
+    try {
+      const watcher = new TreeWatcher({
+        hqRoot: dir,
+        clock,
+        debounceMs: DEBOUNCE,
+        maxWatchedPaths: 3,
+        onDegraded: degraded,
+        // This faked backend drives chokidar's real ignored predicate through
+        // its pre-stat and post-stat calls, without needing an inotify slot on
+        // a host already exhausted by another process.
+        backendFactory: ({
+          hqRoot,
+          shouldEmit,
+          maxWatchedPaths,
+          onWatchBudgetExceeded,
+        }) => {
+          const budget = new ChokidarWatchBudget(
+            maxWatchedPaths,
+            onWatchBudgetExceeded,
+          );
+          const ignored = toChokidarIgnored(shouldEmit, hqRoot, budget);
+          const visit = (candidate: string): void => {
+            if (ignored(candidate)) return;
+            const stats = fs.lstatSync(candidate);
+            if (ignored(candidate, stats)) return;
+            if (!stats.isDirectory()) return;
+            descended.push(path.resolve(candidate));
+            for (const entry of fs.readdirSync(candidate)) {
+              visit(path.join(candidate, entry));
+            }
+          };
+          visit(hqRoot);
+          return {
+            close: () => {
+              backendClosed = true;
+            },
+            needsKnownKinds: false,
+            watchedPathCount: () => descended.length,
+          };
+        },
+      });
+      watcher.onChange(changed);
+      watcher.start();
+
+      expect(descended).toHaveLength(3);
+      expect(descended).not.toContain(path.join(dir, "personal", "a", "deep"));
+      expect(degraded).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reason: "watch_budget_exhausted",
+          maxWatchedPaths: 3,
+          watchedPaths: 3,
+          offendingPath: expect.stringContaining(path.join("personal", "a", "deep")),
+        }),
+      );
+      expect(backendClosed).toBe(true);
+      expect(watcher.isWatching()).toBe(false);
+
+      clock.advance(DEBOUNCE);
+      expect(changed).toHaveBeenCalledWith(
+        undefined,
+        expect.objectContaining({ overflowed: true }),
+      );
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("degrades instead of dying when chokidar emits runtime ENOSPC", () => {
+    const clock = new FakeClock();
+    const degraded = vi.fn();
+    const changed = vi.fn();
+    const telemetry: TelemetryEventsBatch[] = [];
+    const telemetryClient = {
+      postTelemetryEvents: vi.fn(async (batch: TelemetryEventsBatch) => {
+        telemetry.push(batch);
+        return { ok: true, written: batch.events.length, skipped: [] };
+      }),
+    };
+    let closeCalls = 0;
+    const watcher = new TreeWatcher({
+      hqRoot: ROOT,
+      clock,
+      debounceMs: DEBOUNCE,
+      onDegraded: degraded,
+      telemetryClient,
+      backendFactory: ({ onError }) => {
+        const backend = {
+          close: () => {
+            closeCalls += 1;
+          },
+          needsKnownKinds: false,
+          watchedPathCount: () => 0,
+        };
+        queueMicrotask(() =>
+          onError(
+            Object.assign(new Error("inotify limit"), {
+              code: "ENOSPC",
+              path: path.join(ROOT, "companies", "acme", "knowledge"),
+            }),
+          ),
+        );
+        return backend;
+      },
+    });
+    watcher.onChange(changed);
+    watcher.start();
+
+    return new Promise<void>((resolve) => queueMicrotask(resolve)).then(() => {
+      expect(closeCalls).toBe(1);
+      expect(watcher.isWatching()).toBe(false);
+      expect(degraded).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reason: "inotify_enospc",
+          errorCode: "ENOSPC",
+          offendingPath: path.join(ROOT, "companies", "acme", "knowledge"),
+        }),
+      );
+      expect(telemetry).toEqual([
+        expect.objectContaining({
+          events: [
+            expect.objectContaining({
+              eventName: "watcher_degraded",
+              source: "watcher",
+              properties: expect.objectContaining({
+                reason: "inotify_enospc",
+                offendingTopLevel: "companies",
+              }),
+            }),
+          ],
+        }),
+      ]);
+      clock.advance(DEBOUNCE);
+      expect(changed).toHaveBeenCalledWith(
+        undefined,
+        expect.objectContaining({ overflowed: true }),
+      );
+    });
+  });
+
+  it("does not retain one rename-kind entry for every changed file", () => {
+    const clock = new FakeClock();
+    const watcher = new TreeWatcher({
+      hqRoot: ROOT,
+      clock,
+      pathFilter: () => true,
+      maxPendingPaths: 20_000,
+      maxPendingBytes: 20_000_000,
+    });
+    for (let i = 0; i < 10_000; i++) {
+      watcher.handleEvent(path.join(ROOT, "personal", `file-${i}.md`));
+    }
+    expect(watcher.knownDirectoryCount()).toBe(0);
+    watcher.stop();
+  });
 });
 
 describe("US-002: TreeWatcher — lifecycle (real chokidar over a temp dir)", () => {