@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cli/sync-scope.test.ts

@@ -1,652 +0,0 @@
-/**
- * Unit tests for scope-aware download (US-005 wiring into `sync()`).
- *
- * Covers the contract added when `syncMode` / `prefixSet` were threaded
- * through `computePullPlan` + the scope-shrink pass:
- *
- *   - `all`    → no filtering (regression guard lives in sync.test.ts).
- *   - `shared` → only keys covered by `prefixSet` download; the rest are
- *                classified `skip-out-of-scope` (NOT downloaded).
- *   - `custom` → same mechanism, driven by the explicit path list.
- *   - Idempotency → a second `shared` pull downloads nothing and removes
- *                   nothing (the PullRecord makes scope-change a no-op).
- *   - Scope shrink → narrowing `all → shared` prunes the now-out-of-scope
- *                    CLEAN local orphan; a DIRTY orphan aborts with
- *                    `ScopeShrinkBlockedError` unless `forceScopeShrink`.
- *
- * The security contract (this filter is footprint-only, never an authz
- * boundary) is asserted indirectly: out-of-scope keys are still LISTED and
- * accessible — the engine simply chooses not to materialize them.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { clearContextCache } from "../context.js";
-import type { VaultServiceConfig } from "../types.js";
-
-// Mutable remote-file list so each test controls what the vault returns.
-const REMOTE: { current: Array<{ key: string; size: number; lastModified: Date; etag: string }> } = {
-  current: [
-    { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
-    { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
-  ],
-};
-
-vi.mock("../s3.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../s3.js")>();
-  const innerFs = await import("fs");
-  const innerPath = await import("path");
-  const { vi: innerVi } = await import("vitest");
-  return {
-    ...actual,
-    toPosixKey: (key: string) => key.split("\\").join("/"),
-    uploadFile: innerVi.fn().mockResolvedValue(undefined),
-    downloadFile: innerVi
-      .fn()
-      .mockImplementation(async (_ctx: unknown, key: string, localPath: string) => {
-        const dir = innerPath.dirname(localPath);
-        if (!innerFs.existsSync(dir)) innerFs.mkdirSync(dir, { recursive: true });
-        // Deterministic per-key body so re-downloads produce a stable hash.
-        innerFs.writeFileSync(localPath, `mock:${key}`);
-        // Real GETs carry author metadata; surface a fixed uploader sub so
-        // journal entries are stamped with a KNOWN author. With no `callerSub`
-        // passed (the default for these tests), that author is "foreign", so
-        // the scope-shrink prune/block paths behave exactly as pre-guard —
-        // only the new own-author retention test passes a matching callerSub.
-        return { metadata: { "created-by-sub": "uploader-sub" } };
-      }),
-    listRemoteFiles: innerVi.fn().mockImplementation(async () => REMOTE.current),
-    deleteRemoteFile: innerVi.fn().mockResolvedValue(undefined),
-    // HEAD returns metadata (object exists) for any key still in REMOTE,
-    // null otherwise — mirrors the real bucket so the tombstone HEAD-verify
-    // pass behaves correctly for out-of-scope (still-present) keys.
-    headRemoteFile: innerVi.fn().mockImplementation(async (_ctx: unknown, key: string) => {
-      const hit = REMOTE.current.find((r) => r.key === key);
-      return hit ? { metadata: {}, size: hit.size, etag: hit.etag } : null;
-    }),
-    primeObjectTransport: innerVi.fn().mockResolvedValue(undefined),
-  };
-});
-
-import { sync } from "./sync.js";
-import {
-  ScopeShrinkBlockedError,
-  ScopeShrinkLargePruneError,
-} from "../scope-shrink.js";
-
-const mockConfig: VaultServiceConfig = {
-  apiUrl: "https://vault-api.test",
-  authToken: "test-jwt-token",
-  region: "us-east-1",
-};
-
-const mockEntity = {
-  uid: "cmp_01ABCDEF",
-  slug: "acme",
-  bucketName: "hq-vault-acme-123",
-  status: "active",
-};
-
-const mockVendResponse = {
-  credentials: {
-    accessKeyId: "ASIA_TEST_KEY",
-    secretAccessKey: "test-secret",
-    sessionToken: "test-session-token",
-    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
-  },
-  expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
-};
-
-function setupFetchMock() {
-  const fetchMock = vi.fn().mockImplementation(async (url: string) => {
-    const urlStr = String(url);
-    if (urlStr.includes("/entity/check-slug/me")) {
-      return {
-        ok: true,
-        status: 200,
-        json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
-        text: async () => "",
-      };
-    }
-    if (urlStr.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(urlStr)) {
-      return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
-    }
-    if (urlStr.includes("/sts/vend")) {
-      return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
-    }
-    return { ok: false, status: 404, text: async () => "Not found" };
-  });
-  vi.stubGlobal("fetch", fetchMock);
-  return fetchMock;
-}
-
-describe("sync — scope-aware download (US-005)", () => {
-  let tmpDir: string;
-  let stateDir: string;
-  const companyRel = (p: string) => path.join(tmpDir, "companies", "acme", p);
-
-  beforeEach(() => {
-    clearContextCache();
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-scope-"));
-    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-scope-"));
-    process.env.HQ_STATE_DIR = stateDir;
-    // Reset the remote list every test (a prior test may have mutated it).
-    REMOTE.current = [
-      { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
-      { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
-    ];
-    setupFetchMock();
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    vi.clearAllMocks();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-    fs.rmSync(stateDir, { recursive: true, force: true });
-    delete process.env.HQ_STATE_DIR;
-  });
-
-  it("shared mode downloads only keys covered by prefixSet; rest are skip-out-of-scope", async () => {
-    const result = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["knowledge/"],
-    });
-
-    expect(result.filesDownloaded).toBe(1);
-    expect(result.filesOutOfScope).toBe(1);
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-    // docs/handoff.md is out of scope — never materialized.
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
-  });
-
-  it("custom mode behaves like shared, driven by the explicit prefix list", async () => {
-    const result = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "custom",
-      prefixSet: ["docs/"],
-    });
-
-    expect(result.filesDownloaded).toBe(1);
-    expect(result.filesOutOfScope).toBe(1);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
-  });
-
-  it("shared mode with empty prefixSet downloads nothing", async () => {
-    const result = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: [],
-    });
-
-    expect(result.filesDownloaded).toBe(0);
-    expect(result.filesOutOfScope).toBe(2);
-  });
-
-  // FILE_TOMBSTONE fetch is COMPANY-scoped (GET /v1/files/tombstones?company=…).
-  // For the personal vault the target uid is a personUid (prs_…), which the
-  // server correctly 403s ("No active membership for caller in company prs_…"),
-  // spamming hq-pro's Sentry with a per-user no-membership cluster. The pull
-  // must SKIP the fetch for the personal target (delete-resync was never a
-  // committed personal-vault feature). Differential: company-mode fetches,
-  // personal-mode does not.
-  const hitTombstones = (m: ReturnType<typeof setupFetchMock>) =>
-    m.mock.calls.some((c: unknown[]) =>
-      String(c[0]).includes("/v1/files/tombstones"),
-    );
-
-  it("company-mode pull fetches FILE_TOMBSTONEs (baseline for the personal guard)", async () => {
-    const fetchMock = setupFetchMock();
-    await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "all",
-      prefixSet: [],
-    });
-    expect(hitTombstones(fetchMock)).toBe(true);
-  });
-
-  it("personal-vault pull SKIPS the company-scoped tombstone fetch (no 403 → no Sentry no-membership spam)", async () => {
-    const fetchMock = setupFetchMock();
-    await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "all",
-      prefixSet: [],
-      personalMode: true,
-    });
-    expect(hitTombstones(fetchMock)).toBe(false);
-  });
-
-  it("is idempotent: a second shared pull downloads and removes nothing", async () => {
-    const opts = {
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared" as const,
-      prefixSet: ["knowledge/"],
-    };
-    const first = await sync(opts);
-    expect(first.filesDownloaded).toBe(1);
-
-    const second = await sync(opts);
-    expect(second.filesDownloaded).toBe(0);
-    expect(second.scopeOrphansRemoved).toBe(0);
-    expect(second.scopeOrphansBlocked).toBe(0);
-    // knowledge file still present; nothing churned.
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-  });
-
-  it("scope shrink (all → shared) prunes the clean out-of-scope orphan", async () => {
-    // First pull EVERYTHING under all-mode.
-    const all = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "all",
-    });
-    expect(all.filesDownloaded).toBe(2);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-
-    // Narrow to shared/knowledge → docs/handoff.md is now a clean orphan.
-    const shared = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["knowledge/"],
-    });
-    expect(shared.scopeOrphansRemoved).toBe(1);
-    expect(shared.scopeOrphansBlocked).toBe(0);
-    // The clean orphan was pruned; the in-scope file stays.
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-  });
-
-  it("scope shrink (all → shared) RETAINS the owner's own out-of-scope file", async () => {
-    // Corey's exact scenario: the caller authored everything (the mock stamps
-    // `created-by-sub: "uploader-sub"`), so passing the matching `callerSub`
-    // means narrowing to `shared` must NOT prune their own work — mode only
-    // governs mirroring OTHER people's files.
-    const all = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "all",
-      callerSub: "uploader-sub",
-    });
-    expect(all.filesDownloaded).toBe(2);
-
-    const shared = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["knowledge/"],
-      callerSub: "uploader-sub",
-    });
-    // Out of scope, but authored by the caller → retained, not pruned.
-    expect(shared.scopeOrphansRemoved).toBe(0);
-    expect(shared.scopeOrphansBlocked).toBe(0);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-  });
-
-  it("refuses a bulk auto-prune over the safety cap, then proceeds when forced", async () => {
-    // Pull both files under all-mode, then narrow to a scope covering neither
-    // → 2 clean orphans. With the cap set to 1, the auto-prune is refused.
-    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
-
-    // Narrow to a scope covering neither file → 2 clean orphans; cap at 1.
-    process.env.HQ_SYNC_MAX_AUTO_PRUNE = "1";
-    try {
-      await expect(
-        sync({
-          company: "acme",
-          vaultConfig: mockConfig,
-          hqRoot: tmpDir,
-          syncMode: "shared",
-          prefixSet: ["nonexistent/"],
-        }),
-      ).rejects.toBeInstanceOf(ScopeShrinkLargePruneError);
-      // Nothing deleted on the refused run.
-      expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-
-      // Forced: the prune proceeds despite the cap.
-      const forced = await sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "shared",
-        prefixSet: ["nonexistent/"],
-        forceScopeShrink: true,
-      });
-      expect(forced.scopeOrphansRemoved).toBe(2);
-      expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
-      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
-    } finally {
-      delete process.env.HQ_SYNC_MAX_AUTO_PRUNE;
-    }
-  });
-
-  it("scope shrink aborts on a DIRTY orphan unless forceScopeShrink is set", async () => {
-    await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "all",
-    });
-    // Locally modify the soon-to-be-orphan so it's dirty (hash mismatch).
-    fs.writeFileSync(companyRel("docs/handoff.md"), "LOCAL EDIT — do not delete");
-
-    // Default: abort with the structured error; the dirty file is untouched.
-    await expect(
-      sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "shared",
-        prefixSet: ["knowledge/"],
-      }),
-    ).rejects.toBeInstanceOf(ScopeShrinkBlockedError);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-    expect(fs.readFileSync(companyRel("docs/handoff.md"), "utf-8")).toBe(
-      "LOCAL EDIT — do not delete",
-    );
-
-    // With force: the leg proceeds, the dirty file is LEFT ON DISK, only its
-    // journal entry is tombstoned.
-    const forced = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["knowledge/"],
-      forceScopeShrink: true,
-    });
-    expect(forced.scopeOrphansBlocked).toBe(1);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-  });
-
-  // DEV-1768 fix #3: a scope shrink must QUARANTINE clean orphans (recoverable),
-  // never silently delete them. The file leaves its working-tree path but is
-  // recoverable under `.hq/scope-quarantine/<slug>/`.
-  it("scope shrink QUARANTINES a clean orphan (recoverable), never silent-deletes", async () => {
-    const quarantined = path.join(
-      tmpDir,
-      ".hq",
-      "scope-quarantine",
-      "acme",
-      "docs",
-      "handoff.md",
-    );
-    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
-    const original = companyRel("docs/handoff.md");
-    const bodyBefore = fs.readFileSync(original, "utf-8");
-
-    const shared = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["knowledge/"],
-    });
-
-    expect(shared.scopeOrphansRemoved).toBe(1);
-    // Gone from the working tree...
-    expect(fs.existsSync(original)).toBe(false);
-    // ...but recoverable in quarantine, byte-for-byte.
-    expect(fs.existsSync(quarantined)).toBe(true);
-    expect(fs.readFileSync(quarantined, "utf-8")).toBe(bodyBefore);
-  });
-
-  // DEV-1768 fix #1 (recovery) + #2: the background runner path
-  // (`scopeShrinkPolicy: "auto-recover"`) must NEVER throw on a scope shrink —
-  // it self-heals. This reproduces the EXACT wedge: a buggy `all`-mode pull
-  // seeds the journal (all-mode PullRecord + both files), one out-of-scope file
-  // is edited locally (dirty), then the real `shared` pull arrives. Under the
-  // old code this threw ScopeShrinkBlockedError(all→shared) → exit 2 forever.
-  it("auto-recover policy clears an all→shared wedge: dirty kept on disk, clean quarantined, no throw", async () => {
-    // 1. Buggy all-mode CLI seed: journals everything + stamps an all-mode record.
-    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
-    // 2. User edits an out-of-scope file → it becomes a DIRTY orphan.
-    fs.writeFileSync(companyRel("docs/handoff.md"), "LOCAL EDIT — keep me");
-    const quarantinedClean = path.join(
-      tmpDir, ".hq", "scope-quarantine", "acme", "knowledge", "readme.md",
-    );
-
-    // 3. The menubar runner's real shared pull. prefixSet covers NEITHER file
-    //    (docs is dirty-orphan, knowledge becomes a clean orphan) so we exercise
-    //    both dispositions. Must resolve without throwing.
-    const recovered = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["projects/"],
-      scopeShrinkPolicy: "auto-recover",
-    });
-    expect(recovered.aborted).toBe(false);
-    // Dirty file: KEPT on disk (un-tracked), counted as blocked-but-kept.
-    expect(recovered.scopeOrphansBlocked).toBe(1);
-    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-    expect(fs.readFileSync(companyRel("docs/handoff.md"), "utf-8")).toBe(
-      "LOCAL EDIT — keep me",
-    );
-    // Clean file: quarantined (recoverable), removed from the working tree.
-    expect(recovered.scopeOrphansRemoved).toBe(1);
-    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
-    expect(fs.existsSync(quarantinedClean)).toBe(true);
-
-    // 4. Idempotent: the next auto-recover sync re-flags NOTHING (the orphans
-    //    were tombstoned, so the wedge does not recur).
-    const second = await sync({
-      company: "acme",
-      vaultConfig: mockConfig,
-      hqRoot: tmpDir,
-      syncMode: "shared",
-      prefixSet: ["projects/"],
-      scopeShrinkPolicy: "auto-recover",
-    });
-    expect(second.scopeOrphansRemoved).toBe(0);
-    expect(second.scopeOrphansBlocked).toBe(0);
-  });
-
-  // ── US-006: sessions prefix push-only pull-scope exclusion ─────────────────
-  // The sessions prefix is PUSH-ONLY: pushed into the vault but never
-  // auto-pulled onto grantee laptops in ANY mode (including `all`, which
-  // otherwise pulls the whole bucket). The engine expresses this as
-  // `excludePrefixes`, applied to the DOWNLOAD filter only — never to
-  // scope-shrink, so an authored/pinned session is never orphaned.
-  describe("sessions push-only exclusion (US-006)", () => {
-    const withSession = () => {
-      REMOTE.current = [
-        { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
-        { key: "sessions/prs_1/2026-07-11T10-00-00.json", size: 50, lastModified: new Date(), etag: '"sess1"' },
-      ];
-    };
-    const sessionPath = "sessions/prs_1/2026-07-11T10-00-00.json";
-
-    it("AC4: `all` mode subtracts excludePrefixes — a sessions key is skip-out-of-scope; non-session downloads", async () => {
-      withSession();
-      const result = await sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "all",
-        excludePrefixes: ["sessions/"],
-      });
-      // `all` normally pulls everything; the exclusion carves sessions out.
-      expect(result.filesDownloaded).toBe(1);
-      expect(result.filesOutOfScope).toBe(1);
-      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-      expect(fs.existsSync(companyRel(sessionPath))).toBe(false);
-    });
-
-    it("AC4: excludePrefixes is NOT fed to scope-shrink — a previously-pulled session file is never orphaned", async () => {
-      withSession();
-      // 1. Full pull WITHOUT the exclusion: the session materializes and journals
-      //    as a pulled (direction:"down") entry under an `all`-mode PullRecord.
-      const first = await sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "all",
-      });
-      expect(first.filesDownloaded).toBe(2);
-      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
-
-      // 2. Full pull WITH the sessions exclusion. The session is now
-      //    skip-out-of-scope (not re-pulled) but MUST NOT be pruned: the exclude
-      //    set never reaches scope-shrink, whose currentPrefixSet stays `[""]`
-      //    (covers everything). If it WERE fed in, the file would be orphaned.
-      const second = await sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "all",
-        excludePrefixes: ["sessions/"],
-      });
-      expect(second.filesOutOfScope).toBe(1);
-      expect(second.scopeOrphansRemoved).toBe(0);
-      expect(second.scopeOrphansBlocked).toBe(0);
-      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
-    });
-
-    it("AC6: a pinned/in-scope session survives scope-shrink even though excludePrefixes skips its re-pull", async () => {
-      withSession();
-      // Materialize both under all-mode (knowledge sync + an on-demand session get).
-      await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
-      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
-
-      // A scoped shared pull whose inclusion prefixSet includes the pinned
-      // session key (as resolvePullScope would after `hq files get` pins it),
-      // plus the push-only sessions exclusion. The session is NOT re-pulled
-      // (exclusion), but the pin keeps it in scope-shrink's currentPrefixSet, so
-      // it is retained rather than orphaned.
-      const scoped = await sync({
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        syncMode: "shared",
-        prefixSet: ["knowledge/", sessionPath],
-        excludePrefixes: ["sessions/"],
-      });
-      expect(scoped.scopeOrphansRemoved).toBe(0);
-      expect(scoped.scopeOrphansBlocked).toBe(0);
-      // Session is not re-downloaded (excluded) but survives on disk...
-      expect(scoped.filesOutOfScope).toBe(1);
-      expect(fs.existsSync(companyRel(sessionPath))).toBe(true);
-      // ...and the in-scope knowledge file is retained too.
-      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-    });
-
-    // ── feedback_d2082110 follow-up ────────────────────────────────────────
-    // `skip-out-of-scope` carries TWO causes with OPPOSITE remedies:
-    // membership scope (fixed by raising the access level to `all`) and the
-    // push-only sessions exclusion (NOT fixed by that — sessions are withheld
-    // in every mode, `all` included, and materialize only via `hq files get`).
-    // The `scope-materialization-gap` advisory names the shared→all lever, so
-    // it must count and sample ONLY membership-withheld keys. Counting session
-    // keys inflates the gap, can fill the sample list with keys the lever will
-    // never deliver, and can fire the whole advisory when the membership scope
-    // withheld nothing — sending the reporter back into exactly the
-    // flip-everything-to-`all`-and-still-miss-files loop the event exists to end.
-    describe("materialization gap excludes push-only keys (feedback_d2082110)", () => {
-      const collectEvents = () => {
-        const events: Array<Record<string, unknown>> = [];
-        return {
-          events,
-          onEvent: (e: unknown) => events.push(e as Record<string, unknown>),
-        };
-      };
-      const gapOf = (events: Array<Record<string, unknown>>) =>
-        events.find((e) => e.type === "scope-materialization-gap");
-
-      it("a leg withholding ONLY push-only session keys emits no gap — the shared→all lever would not materialize them", async () => {
-        withSession();
-        const { events, onEvent } = collectEvents();
-        const result = await sync({
-          company: "acme",
-          vaultConfig: mockConfig,
-          hqRoot: tmpDir,
-          syncMode: "shared",
-          prefixSet: ["knowledge/"],
-          excludePrefixes: ["sessions/"],
-          onEvent,
-        });
-
-        // The session key is still withheld and still counted on the
-        // both-causes `filesOutOfScope` axis — that contract is unchanged.
-        expect(result.filesDownloaded).toBe(1);
-        expect(result.filesOutOfScope).toBe(1);
-        expect(fs.existsSync(companyRel(sessionPath))).toBe(false);
-        // But the membership scope withheld nothing, so there is no
-        // shared-vs-all gap to report and no `all` lever to advertise.
-        expect(gapOf(events)).toBeUndefined();
-      });
-
-      it("counts and samples only membership-withheld keys when both causes fire on one leg", async () => {
-        REMOTE.current = [
-          { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
-          { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
-          { key: sessionPath, size: 50, lastModified: new Date(), etag: '"sess1"' },
-        ];
-        const { events, onEvent } = collectEvents();
-        const result = await sync({
-          company: "acme",
-          vaultConfig: mockConfig,
-          hqRoot: tmpDir,
-          syncMode: "shared",
-          prefixSet: ["knowledge/"],
-          excludePrefixes: ["sessions/"],
-          onEvent,
-        });
-
-        // Two keys withheld overall: one by the membership scope, one push-only.
-        expect(result.filesDownloaded).toBe(1);
-        expect(result.filesOutOfScope).toBe(2);
-
-        // The advisory reports ONLY the one the `all` lever would deliver.
-        const gap = gapOf(events);
-        expect(gap).toBeDefined();
-        expect(gap!.count).toBe(1);
-        expect(gap!.syncMode).toBe("shared");
-        expect(gap!.samplePaths).toEqual(["docs/handoff.md"]);
-      });
-
-      it("a pinned session key withheld on the push-only axis alone is not a membership gap", async () => {
-        // Exercises the OTHER classification branch: the key PASSES the
-        // inclusion check (it is pinned into prefixSet, as resolvePullScope
-        // does after `hq files get`) and is withheld by the exclusion filter.
-        withSession();
-        const { events, onEvent } = collectEvents();
-        const result = await sync({
-          company: "acme",
-          vaultConfig: mockConfig,
-          hqRoot: tmpDir,
-          syncMode: "shared",
-          prefixSet: ["knowledge/", sessionPath],
-          excludePrefixes: ["sessions/"],
-          onEvent,
-        });
-
-        expect(result.filesDownloaded).toBe(1);
-        expect(result.filesOutOfScope).toBe(1);
-        expect(gapOf(events)).toBeUndefined();
-      });
-    });
-  });
-});