@indigoai-us/hq-cloud 6.18.44-alpha.9 → 6.18.44

package/dist/cli/sync-scope.test.js

@@ -1,903 +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";
-// Mutable remote-file list so each test controls what the vault returns.
-const REMOTE = {
-    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();
-    const innerFs = await import("fs");
-    const innerPath = await import("path");
-    const { vi: innerVi } = await import("vitest");
-    async function* streamRemoteFiles(_ctx, prefix) {
-        for (const remoteFile of prefix === undefined
-            ? REMOTE.current
-            : REMOTE.current.filter((file) => file.key.startsWith(prefix))) {
-            yield remoteFile;
-        }
-    }
-    return {
-        ...actual,
-        toPosixKey: (key) => key.split("\\").join("/"),
-        uploadFile: innerVi.fn().mockResolvedValue(undefined),
-        downloadFile: innerVi
-            .fn()
-            .mockImplementation(async (_ctx, key, localPath) => {
-            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" } };
-        }),
-        // Honor the scoped-listing prefix like the real ListObjectsV2 call does:
-        // `sync()` now lists per in-scope prefix (`listRemoteFilesForScope`), so
-        // the mock must return only the keys under the requested prefix for the
-        // scoped-listing assertions below to mean anything.
-        listRemoteFiles: innerVi
-            .fn()
-            .mockImplementation(async (_ctx, prefix) => prefix === undefined
-            ? REMOTE.current
-            : REMOTE.current.filter((f) => f.key.startsWith(prefix))),
-        streamRemoteFiles,
-        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, key) => {
-            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";
-import { PERSONAL_VAULT_JOURNAL_SLUG, readJournal, writeJournal, } from "../journal.js";
-import { SESSION_LOGS_PUSH_ONLY_PREFIX } from "../sync/pull-scope.js";
-const mockConfig = {
-    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(options = {}) {
-    const fetchMock = vi.fn().mockImplementation(async (url) => {
-        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 () => "" };
-        }
-        if (urlStr.includes("/v1/files/tombstones")) {
-            return {
-                ok: true,
-                status: 200,
-                json: async () => ({ tombstones: options.tombstones ?? [] }),
-                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;
-    let stateDir;
-    const companyRel = (p) => 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; the rest are never even LISTED", async () => {
-        const s3 = await import("../s3.js");
-        const result = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "shared",
-            prefixSet: ["knowledge/"],
-        });
-        expect(result.filesDownloaded).toBe(1);
-        // Scoped listing: out-of-scope keys are excluded at LIST time (one
-        // ListObjectsV2 per in-scope prefix) rather than listed-then-skipped, so
-        // they no longer appear in the plan at all — filesOutOfScope is 0 and the
-        // full remote listing is never materialized in memory.
-        expect(result.filesOutOfScope).toBe(0);
-        const listPrefixes = vi
-            .mocked(s3.listRemoteFiles)
-            .mock.calls.map((c) => c[1]);
-        expect(listPrefixes).toEqual(["knowledge/"]);
-        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(0);
-        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 and issues zero LIST calls", async () => {
-        const s3 = await import("../s3.js");
-        const result = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "shared",
-            prefixSet: [],
-        });
-        expect(result.filesDownloaded).toBe(0);
-        expect(result.filesOutOfScope).toBe(0);
-        expect(s3.listRemoteFiles).not.toHaveBeenCalled();
-    });
-    it("a scoped LIST never marks out-of-scope journaled files as remote-deleted", async () => {
-        // Regression for the scoped-listing deletion sweep: seed BOTH files via an
-        // all-mode pull (journaling both), then run a shared pull scoped to
-        // knowledge/ with auto-recover. docs/handoff.md is absent from the scoped
-        // LIST because it was never asked about — the journal-vs-LIST sweep must
-        // NOT treat that as a remote delete. (Scope-shrink may quarantine it as an
-        // out-of-scope orphan — that is its own, recoverable, contract — so pin
-        // the sweep axis: filesTombstoned stays 0.)
-        const all = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "all",
-        });
-        expect(all.filesDownloaded).toBe(2);
-        const scoped = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "shared",
-            prefixSet: ["knowledge/"],
-            scopeShrinkPolicy: "auto-recover",
-        });
-        expect(scoped.filesTombstoned).toBe(0);
-        expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-    });
-    describe("targeted pull narrowing (pullPrefixes)", () => {
-        it("lists and plans only the requested prefixes, without touching the rest of the tree", async () => {
-            const s3 = await import("../s3.js");
-            // Seed everything so the targeted run has out-of-target local state.
-            const all = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-            });
-            expect(all.filesDownloaded).toBe(2);
-            vi.mocked(s3.listRemoteFiles).mockClear();
-            // Remote update lands under knowledge/ while docs/ is also updated —
-            // the targeted pull must fetch only the knowledge/ change.
-            REMOTE.current = [
-                { key: "docs/handoff.md", size: 43, lastModified: new Date(), etag: '"abc124"' },
-                { key: "knowledge/readme.md", size: 101, lastModified: new Date(), etag: '"def457"' },
-            ];
-            const targeted = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-                pullPrefixes: ["knowledge/"],
-            });
-            expect(targeted.filesDownloaded).toBe(1);
-            const listPrefixes = vi
-                .mocked(s3.listRemoteFiles)
-                .mock.calls.map((c) => c[1]);
-            expect(listPrefixes).toEqual(["knowledge/"]);
-            // The out-of-target journaled file was neither re-pulled nor —
-            // critically — mistaken for a remote delete (it was never listed).
-            expect(targeted.filesTombstoned).toBe(0);
-            expect(targeted.scopeOrphansRemoved).toBe(0);
-            expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-            expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
-        });
-        it("rejects an unservable targeted path instead of silently consuming it", async () => {
-            const s3 = await import("../s3.js");
-            await expect(sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "shared",
-                prefixSet: ["knowledge/"],
-                pullPrefixes: ["docs/"],
-            })).rejects.toThrow("targeted pull paths are outside the durable scope: docs/");
-            expect(s3.listRemoteFiles).not.toHaveBeenCalled();
-            expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
-        });
-        it("a targeted pull still propagates a genuine remote delete INSIDE the target", async () => {
-            const all = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-            });
-            expect(all.filesDownloaded).toBe(2);
-            // Peer deleted the knowledge file remotely; docs/ untouched.
-            REMOTE.current = [
-                { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
-            ];
-            const targeted = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-                pullPrefixes: ["knowledge/"],
-            });
-            expect(targeted.filesTombstoned).toBe(1);
-            expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
-            expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
-        });
-    });
-    const tombstoneCalls = (m) => m.mock.calls.filter((c) => String(c[0]).includes("/v1/files/tombstones"));
-    it("company-mode pull requests FILE_TOMBSTONEs with the company selector", async () => {
-        const fetchMock = setupFetchMock();
-        await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "all",
-            prefixSet: [],
-        });
-        expect(tombstoneCalls(fetchMock)).toHaveLength(1);
-        expect(String(tombstoneCalls(fetchMock)[0][0])).toContain(`company=${mockEntity.uid}`);
-    });
-    it("personal-vault pull requests FILE_TOMBSTONEs with personal=1, never a person UID as company", async () => {
-        const fetchMock = setupFetchMock();
-        await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "all",
-            prefixSet: [],
-            personalMode: true,
-        });
-        expect(tombstoneCalls(fetchMock)).toHaveLength(1);
-        const url = String(tombstoneCalls(fetchMock)[0][0]);
-        expect(url).toContain("personal=1");
-        expect(url).not.toContain("company=");
-    });
-    it("personal deletion removes a clean local copy, stays suppressed, then accepts a newer recreate", async () => {
-        const s3 = await import("../s3.js");
-        const deletedPath = path.join(tmpDir, "docs", "handoff.md");
-        const now = Date.now();
-        REMOTE.current = [
-            {
-                key: "docs/handoff.md",
-                size: 42,
-                lastModified: new Date(now - 60_000),
-                etag: '"abc123"',
-            },
-        ];
-        // Establish the clean local baseline held by a machine that has not yet
-        // observed the personal-vault deletion.
-        await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            personalMode: true,
-            journalSlug: "personal",
-        });
-        expect(fs.readFileSync(deletedPath, "utf8")).toBe("mock:docs/handoff.md");
-        setupFetchMock({
-            tombstones: [
-                { key: "docs/handoff.md", deletedAt: new Date(now).toISOString() },
-            ],
-        });
-        vi.mocked(s3.downloadFile).mockClear();
-        const deleted = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            personalMode: true,
-            journalSlug: "personal",
-        });
-        expect(deleted.filesTombstoned).toBe(1);
-        expect(fs.existsSync(deletedPath)).toBe(false);
-        expect(s3.downloadFile).not.toHaveBeenCalled();
-        // A later pass seeing the same stale object must not materialize an empty
-        // placeholder or restore the old bytes after the journal row converges.
-        await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            personalMode: true,
-            journalSlug: "personal",
-        });
-        expect(fs.existsSync(deletedPath)).toBe(false);
-        expect(s3.downloadFile).not.toHaveBeenCalled();
-        // Tombstones are precedence markers, not permanent path bans. A real
-        // object written after the deletion downloads normally.
-        REMOTE.current = [
-            {
-                key: "docs/handoff.md",
-                size: 43,
-                lastModified: new Date(now + 60_000),
-                etag: '"abc124"',
-            },
-        ];
-        const recreated = await sync({
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            personalMode: true,
-            journalSlug: "personal",
-        });
-        expect(recreated.filesDownloaded).toBe(1);
-        expect(fs.readFileSync(deletedPath, "utf8")).toBe("mock:docs/handoff.md");
-    });
-    it("is idempotent: a second shared pull downloads and removes nothing", async () => {
-        const opts = {
-            company: "acme",
-            vaultConfig: mockConfig,
-            hqRoot: tmpDir,
-            syncMode: "shared",
-            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 = [];
-                return {
-                    events,
-                    onEvent: (e) => events.push(e),
-                };
-            };
-            const gapOf = (events) => 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 — under scoped listing it never
-                // even enters the plan (sessions/ is outside the inclusion scope), so
-                // it is not counted on the filesOutOfScope axis either.
-                expect(result.filesDownloaded).toBe(1);
-                expect(result.filesOutOfScope).toBe(0);
-                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("scoped listing withholds membership-out-of-scope keys at LIST time — no gap event, no materialization", async () => {
-                // BEHAVIOR CHANGE (targeted-sync scoped listing): a shared leg no
-                // longer materializes the full remote listing, so keys outside the
-                // membership scope never reach the plan and the
-                // `scope-materialization-gap` advisory has nothing to count. The
-                // withheld-key telemetry was traded for not holding the whole vault
-                // listing in memory on every scoped pull; the classification logic
-                // (membership-scope vs push-only) still guards any full listing that
-                // reaches the plan (see the all-mode AC4 test and the pinned-session
-                // test below).
-                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,
-                });
-                // Only the in-scope key was listed and pulled; the membership-withheld
-                // and push-only keys were never listed, so neither materializes and no
-                // gap advisory fires.
-                expect(result.filesDownloaded).toBe(1);
-                expect(result.filesOutOfScope).toBe(0);
-                expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
-                expect(fs.existsSync(companyRel(sessionPath))).toBe(false);
-                expect(gapOf(events)).toBeUndefined();
-            });
-            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();
-            });
-        });
-    });
-    // Personal-vault captured transcripts (`workspace/.session-logs/`) are
-    // push-only: the capturing machine uploads them, but no personal pull —
-    // including `all` mode and a foreground `hq sync --personal` — auto-downloads
-    // the prefix. Local retention depends on this: without the exclusion, prune
-    // would be undone by the next pull. The engine unions the prefix into the
-    // exclude set when `personalMode === true`; tests below do not pass
-    // `excludePrefixes` so a missing union would fail.
-    describe("personal session-log push-only exclusion", () => {
-        const sessionLogKey = `${SESSION_LOGS_PUSH_ONLY_PREFIX}codex/2026/08/rollout.jsonl`;
-        const sessionLogPath = () => path.join(tmpDir, ...sessionLogKey.split("/"));
-        const withSessionLog = () => {
-            REMOTE.current = [
-                { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
-                { key: sessionLogKey, size: 50, lastModified: new Date(), etag: '"sess-log-1"' },
-            ];
-        };
-        it("personal `all` mode never downloads workspace/.session-logs/", async () => {
-            withSessionLog();
-            const result = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-                personalMode: true,
-                journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-                skipReindex: true,
-            });
-            expect(result.filesDownloaded).toBe(1);
-            expect(result.filesOutOfScope).toBe(1);
-            expect(fs.existsSync(path.join(tmpDir, "knowledge", "readme.md"))).toBe(true);
-            expect(fs.existsSync(sessionLogPath())).toBe(false);
-        });
-        it("a DEEP_ARCHIVE session-log key is not downloaded and does not tombstone the journal", async () => {
-            writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, {
-                version: "2",
-                lastSync: "",
-                pulls: [],
-                files: {
-                    [sessionLogKey]: {
-                        hash: "a".repeat(64),
-                        size: 50,
-                        syncedAt: "2026-08-31T00:00:00.000Z",
-                        direction: "up",
-                        remoteEtag: "deep-archive-etag",
-                        kind: "file",
-                    },
-                },
-            });
-            REMOTE.current = [
-                {
-                    key: sessionLogKey,
-                    size: 50,
-                    lastModified: new Date(),
-                    etag: "deep-archive-etag",
-                    storageClass: "DEEP_ARCHIVE",
-                },
-            ];
-            const result = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-                personalMode: true,
-                journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-                skipReindex: true,
-            });
-            expect(result.filesDownloaded).toBe(0);
-            expect(result.filesTombstoned).toBe(0);
-            const s3 = await import("../s3.js");
-            expect(s3.downloadFile).not.toHaveBeenCalled();
-            expect(fs.existsSync(sessionLogPath())).toBe(false);
-            expect(readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files[sessionLogKey]).toMatchObject({
-                remoteEtag: "deep-archive-etag",
-            });
-        });
-        it("scope-shrink does not prune a local workspace/.session-logs/ file after the exclusion", async () => {
-            withSessionLog();
-            const localPath = sessionLogPath();
-            fs.mkdirSync(path.dirname(localPath), { recursive: true });
-            fs.writeFileSync(localPath, "captured locally\n");
-            writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, {
-                version: "2",
-                lastSync: new Date().toISOString(),
-                pulls: [],
-                files: {
-                    [sessionLogKey]: {
-                        hash: "local-hash",
-                        size: 18,
-                        syncedAt: new Date().toISOString(),
-                        direction: "up",
-                        remoteEtag: "sess-log-1",
-                        kind: "file",
-                        createdBySub: "uploader-sub",
-                    },
-                },
-            });
-            const result = await sync({
-                company: "acme",
-                vaultConfig: mockConfig,
-                hqRoot: tmpDir,
-                syncMode: "all",
-                personalMode: true,
-                journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
-                skipReindex: true,
-            });
-            expect(result.filesOutOfScope).toBe(1);
-            expect(result.scopeOrphansRemoved).toBe(0);
-            expect(result.scopeOrphansBlocked).toBe(0);
-            expect(fs.existsSync(localPath)).toBe(true);
-            expect(fs.readFileSync(localPath, "utf8")).toBe("captured locally\n");
-            expect(readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files[sessionLogKey]).toBeDefined();
-        });
-    });
-});
-//# sourceMappingURL=sync-scope.test.js.map