@indigoai-us/hq-cloud 5.41.0 → 5.43.0

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

@@ -0,0 +1,273 @@
+/**
+ * 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 () => {
+    const innerFs = await import("fs");
+    const innerPath = await import("path");
+    const { vi: innerVi } = await import("vitest");
+    return {
+        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}`);
+            return { metadata: {} };
+        }),
+        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, key) => {
+            const hit = REMOTE.current.find((r) => r.key === key);
+            return hit ? { metadata: {}, size: hit.size, etag: hit.etag } : null;
+        }),
+    };
+});
+import { sync } from "./sync.js";
+import { ScopeShrinkBlockedError, ScopeShrinkLargePruneError, } from "../scope-shrink.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() {
+    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 () => "" };
+        }
+        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; 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);
+    });
+    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("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);
+    });
+});
+//# sourceMappingURL=sync-scope.test.js.map

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

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

package/dist/cli/sync.d.ts

@@ -5,6 +5,7 @@
  * Never auto-overwrites local changes — prompts on conflict.
  */
 import type { VaultServiceConfig } from "../types.js";
+import type { SyncMode } from "../vault-client.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 /**
  * Per-file events emitted by `sync()` as it progresses.
@@ -228,6 +229,40 @@ export interface SyncOptions {
      * TS runner and Rust first-push share idempotency state.
      */
     journalSlug?: string;
+    /**
+     * Effective sync mode for this leg (US-005 wiring). Defaults to `"all"`
+     * when absent, preserving the legacy full-bucket pull. The runner resolves
+     * this from the membership's sync-config (`getMembershipSyncConfig`).
+     *
+     * SECURITY NOTE: this is a footprint/UX filter, NOT an authorization
+     * boundary. The security boundary is the server (STS credential scope +
+     * ACL). An owner's STS is wide (role-bypass), so this client-side scope is
+     * what makes selective download durable for owners — but it never grants
+     * access beyond what STS already permits.
+     */
+    syncMode?: SyncMode;
+    /**
+     * Coalesced, COMPANY-RELATIVE prefixes the current pull is scoped to when
+     * `syncMode` is `"shared"` or `"custom"` (same namespace as `RemoteFile.key`
+     * and the per-slug journal keys — e.g. `"knowledge/"`, `"projects/x/"`).
+     * Ignored when `syncMode` is `"all"`. The runner derives this from the
+     * caller's explicit grants (`shared`) or `customPaths` (`custom`) and is
+     * responsible for normalizing into the company-relative namespace.
+     *
+     * A `shared` leg with an empty/undefined `prefixSet` means "nothing is
+     * shared with me" → download nothing. The runner MUST fall back to `"all"`
+     * (not empty `"shared"`) on any grant-resolution error, so a transient
+     * failure can never silently prune the local tree.
+     */
+    prefixSet?: string[];
+    /**
+     * When the effective scope shrinks relative to the last pull and the shrink
+     * would orphan locally-modified ("dirty") files, `sync()` aborts with a
+     * `ScopeShrinkBlockedError` by default. Set `true` to proceed anyway:
+     * dirty files are LEFT ON DISK and only their journal entries are
+     * tombstoned. Mirrors `hq sync narrow --force`.
+     */
+    forceScopeShrink?: boolean;
 }
 export interface SyncResult {
     filesDownloaded: number;
@@ -272,7 +307,36 @@ export interface SyncResult {
      * disappeared from the remote.
      */
     filesTombstoned: number;
+    /**
+     * Count of remote keys NOT downloaded this run because they fall outside
+     * the effective `syncMode` scope (US-005). Always 0 in `all` mode. Distinct
+     * from `filesSkipped` (which measures "unchanged on this run") so consumers
+     * can render a "N outside your sync scope" line. The matching local cleanup
+     * of previously-downloaded-now-out-of-scope files is reported via
+     * `scopeOrphansRemoved`.
+     */
+    filesOutOfScope: number;
+    /**
+     * Clean local orphans deleted this run because a scope shrink moved them
+     * outside the effective scope (US-005). 0 when scope did not shrink.
+     */
+    scopeOrphansRemoved: number;
+    /**
+     * Dirty (locally-modified) orphans that a scope shrink would have pruned.
+     * When `forceScopeShrink` is false these are surfaced via a thrown
+     * `ScopeShrinkBlockedError` and the leg never reaches this result; when
+     * true they are left on disk and tombstoned, and counted here.
+     */
+    scopeOrphansBlocked: number;
 }
+/**
+ * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
+ * scope shrink that would delete more than this many CLEAN local files in one
+ * pull is refused with `ScopeShrinkLargePruneError`. Default 100; `0` (or a
+ * non-positive / unparseable value) disables the cap (unlimited). Override via
+ * `HQ_SYNC_MAX_AUTO_PRUNE`.
+ */
+export declare function resolveAutoPruneCap(): number;
 /**
  * Sync (pull) all allowed files from the entity vault.
  */

package/dist/cli/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"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"}

package/dist/cli/sync.js

@@ -8,12 +8,29 @@ import * as fs from "fs";
 import * as path from "path";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { downloadFile, listRemoteFiles, headRemoteFile } from "../s3.js";
-import { readJournal, writeJournal, hashFile, hashSymlinkTarget, updateEntry, removeEntry, getEntry, normalizeEtag, } from "../journal.js";
+import { readJournal, writeJournal, hashFile, hashSymlinkTarget, updateEntry, removeEntry, getEntry, normalizeEtag, migrateToV2, gcTombstones, lastPullRecord, appendPullRecord, generatePullId, } from "../journal.js";
+import { buildScopeShrinkPlan, applyScopeShrink, ScopeShrinkBlockedError, ScopeShrinkLargePruneError, } from "../scope-shrink.js";
+import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { isEphemeralPath } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import { buildConflictId, buildConflictPath, readShortMachineId, } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
+/**
+ * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
+ * scope shrink that would delete more than this many CLEAN local files in one
+ * pull is refused with `ScopeShrinkLargePruneError`. Default 100; `0` (or a
+ * non-positive / unparseable value) disables the cap (unlimited). Override via
+ * `HQ_SYNC_MAX_AUTO_PRUNE`.
+ */
+export function resolveAutoPruneCap() {
+    const raw = process.env.HQ_SYNC_MAX_AUTO_PRUNE;
+    if (raw === undefined || raw === "")
+        return 100;
+    const parsed = Number.parseInt(raw, 10);
+    // NaN or negative → treat as "unlimited" (0) rather than silently capping.
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
@@ -41,19 +58,36 @@ export async function sync(options) {
         : path.join(hqRoot, "companies", ctx.slug);
     const shouldSync = createIgnoreFilter(hqRoot);
     const journalSlug = options.journalSlug ?? ctx.slug;
-    const journal = readJournal(journalSlug);
+    const startedAt = new Date().toISOString();
+    // Migrate v1 → v2 in place so the scope-shrink / pull-record machinery has
+    // its fields, and GC any tombstones past the 30-day retention window before
+    // we re-evaluate orphans (so a long-pruned path can re-download cleanly).
+    const journal = migrateToV2(readJournal(journalSlug));
+    gcTombstones(journal, Date.now());
+    // ── Effective download scope (US-005) ─────────────────────────────────────
+    // `all`  → prefixSet `[""]`, which `isCoveredByAny` treats as "covers
+    //          everything" — so the download filter and the scope-shrink
+    //          comparison both become no-ops, preserving legacy full-bucket
+    //          behavior bit-for-bit.
+    // `shared`/`custom` → the coalesced, company-relative prefix set the runner
+    //          resolved. An empty set means "nothing in scope" → download
+    //          nothing (the runner falls back to `all` on resolution errors, so
+    //          empty here is an intentional "nothing shared", never a failure).
+    const syncMode = options.syncMode ?? "all";
+    const currentPrefixSet = syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
     let filesDownloaded = 0;
     let bytesDownloaded = 0;
     let filesSkipped = 0;
     let conflicts = 0;
     let filesTombstoned = 0;
+    let filesOutOfScope = 0;
     const conflictPaths = [];
     // List all remote files (IAM session policy filters at the AWS layer)
     const remoteFiles = await listRemoteFiles(ctx);
     // Stage 1: classify every remote file against the journal + local disk.
     // Hashing happens here (not in the transfer loop) so the plan event below
     // carries an accurate denominator before any progress events fire.
-    const plan = computePullPlan(remoteFiles, journal, companyRoot, shouldSync, options.personalMode === true, options.includeLocalCompanies === true, options.teamSyncedSlugs ?? null);
+    const plan = computePullPlan(remoteFiles, journal, companyRoot, shouldSync, options.personalMode === true, options.includeLocalCompanies === true, options.teamSyncedSlugs ?? null, currentPrefixSet);
     emit({
         type: "plan",
         filesToDownload: plan.filesToDownload,
@@ -65,6 +99,68 @@ export async function sync(options) {
         filesToConflict: plan.filesToConflict,
         filesToDelete: 0,
     });
+    // ── Scope-shrink cleanup (US-005) ─────────────────────────────────────────
+    // If the effective scope narrowed since the last pull, files that were
+    // pulled under the old scope but fall outside the new one are orphans. We
+    // delete only CLEAN orphans (provably unchanged since last sync); dirty
+    // (locally-modified) orphans are sacred. By default a dirty orphan aborts
+    // the leg with a structured error the CLI renders; `forceScopeShrink` keeps
+    // dirty files on disk and only tombstones their journal entries.
+    //
+    // `companyRoot` is passed as the module's `hqRoot` so its `path.join(root,
+    // key)` resolves company-relative journal keys correctly (the scope-shrink
+    // module is namespace-agnostic — root + keys + prefixSet must simply agree).
+    //
+    // Note: this is the durable selective-download fix for OWNERS. An owner's
+    // STS is wide (role-bypass), so the remote LIST returns everything and the
+    // AWS layer never narrows the pull. This client-side shrink is what makes
+    // `hq sync mode shared` actually stick across re-syncs for an owner.
+    const lastRecord = lastPullRecord(journal, ctx.uid);
+    // A missing record, or a v1-migrated record with an empty prefixSet, means
+    // "no recorded scope" → treat the last scope as full-bucket `all` (`[""]`),
+    // per the PullRecord.prefixSet contract in types.ts.
+    const lastPrefixSet = lastRecord && lastRecord.prefixSet.length > 0
+        ? lastRecord.prefixSet
+        : [""];
+    const shrinkPlan = buildScopeShrinkPlan({
+        journal,
+        hqRoot: companyRoot,
+        lastPrefixSet,
+        currentPrefixSet,
+    });
+    if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
+        throw new ScopeShrinkBlockedError(ctx.uid, lastRecord?.syncMode ?? "unknown", syncMode, shrinkPlan.dirty, shrinkPlan.clean);
+    }
+    // Bulk-delete guard: refuse to auto-prune more than the safety cap of CLEAN
+    // files in a single background sync. A deliberate large narrow goes through
+    // `hq sync narrow --apply` (its own confirmation), and `--force-scope-shrink`
+    // (or raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited (opt
+    // out). The engine deletes nothing when it throws here.
+    const autoPruneCap = resolveAutoPruneCap();
+    if (options.forceScopeShrink !== true &&
+        autoPruneCap > 0 &&
+        shrinkPlan.clean.length > autoPruneCap) {
+        throw new ScopeShrinkLargePruneError(ctx.uid, syncMode, shrinkPlan.clean.length, autoPruneCap);
+    }
+    const shrinkResult = applyScopeShrink({
+        journal,
+        plan: shrinkPlan,
+        hqRoot: companyRoot,
+        forceScopeShrink: options.forceScopeShrink === true,
+        reason: "scope_shrink",
+    });
+    // Surface each removed clean orphan as a `deleted` progress event so the
+    // menubar stream renders the prune the same way it renders a cross-machine
+    // tombstone (the Rust parser already handles `deleted: true`).
+    for (const orphan of shrinkPlan.clean) {
+        emit({
+            type: "progress",
+            path: orphan.path,
+            bytes: 0,
+            deleted: true,
+            message: "scope-narrowed (removed local copy outside sync scope)",
+        });
+    }
     // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
     // inline loop; the only structural change is that classification has
     // already happened (so `localHash` is reused instead of re-hashing).
@@ -115,6 +211,13 @@ export async function sync(options) {
             // run", not a catch-all for everything we didn't download.
             continue;
         }
+        if (item.action === "skip-out-of-scope") {
+            // Outside the effective `syncMode` scope (US-005). Counted on its own
+            // axis so `filesSkipped` keeps meaning "unchanged on this run" — these
+            // are "deliberately not downloaded because of your sync scope".
+            filesOutOfScope++;
+            continue;
+        }
         if (item.action === "download") {
             downloadItems.push(item);
             continue;
@@ -195,6 +298,12 @@ export async function sync(options) {
                     // 0 so the field shape stays stable for consumers that
                     // destructure it.
                     filesTombstoned: 0,
+                    // Scope-shrink ran before execution, so its counts are real even on
+                    // a conflict abort. `filesOutOfScope` reflects how far the serial
+                    // pass got before the abort; that's acceptable for an abort result.
+                    filesOutOfScope,
+                    scopeOrphansRemoved: shrinkResult.cleanRemoved,
+                    scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
                 };
                 break;
             }
@@ -485,6 +594,21 @@ export async function sync(options) {
             message: removedSomething ? "tombstone (cross-machine delete)" : "tombstone (already absent locally)",
         });
     }
+    // Record this pull's boundary (US-005) so the NEXT pull can diff its scope
+    // against ours and detect a shrink. Append before the journal write so it
+    // persists. `prefixSet` is stored in the same company-relative namespace as
+    // the journal keys; `all` mode records `[""]` (covers everything).
+    appendPullRecord(journal, {
+        pullId: generatePullId(),
+        companyUid: ctx.uid,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        syncMode,
+        prefixSet: currentPrefixSet,
+        scopeChangeDetected: shrinkPlan.scopeChangeDetected,
+        orphansRemoved: shrinkResult.cleanRemoved,
+        orphansBlocked: shrinkResult.dirtyTombstoned,
+    });
     // Stamp lastSync on every successful run so the menubar's "Last sync · X ago"
     // ticks even when nothing transferred. updateEntry only fires on actual
     // downloads; without this, a no-op sync leaves lastSync at the time of the
@@ -502,6 +626,9 @@ export async function sync(options) {
         newFilesCount: plan.newFilesCount,
         filesExcludedByPolicy: plan.filesExcludedByPolicy,
         filesTombstoned,
+        filesOutOfScope,
+        scopeOrphansRemoved: shrinkResult.cleanRemoved,
+        scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
     };
 }
 /**
@@ -544,7 +671,11 @@ function hasRemoteChanged(remote, entry) {
  * caller (`sync()`) is responsible for emitting the resulting plan event
  * before iterating `items`.
  */
-function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personalMode, includeLocalCompanies, teamSyncedSlugs) {
+function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personalMode, includeLocalCompanies, teamSyncedSlugs, 
+// Coalesced, company-relative prefixes the pull is scoped to (US-005).
+// `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
+// the scope filter below becomes a no-op and legacy behavior is preserved.
+prefixSet) {
     const items = [];
     for (const remoteFile of remoteFiles) {
         const localPath = path.join(companyRoot, remoteFile.key);
@@ -583,6 +714,16 @@ function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personal
                 continue;
             }
         }
+        // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
+        // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
+        // `isCoveredByAny` treats as covering everything — so this is a no-op for
+        // `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()`.
+        if (!isCoveredByAny(remoteFile.key, prefixSet)) {
+            items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+            continue;
+        }
         // LIST gives us no kind signal for the remote object — we don't
         // know whether this key is a regular file or a symlink record
         // until we either HEAD it (expensive — N extra calls per pull) or
@@ -729,6 +870,7 @@ function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personal
     let filesToSkip = 0;
     let filesToConflict = 0;
     let filesExcludedByPolicy = 0;
+    let filesOutOfScope = 0;
     const newFiles = [];
     for (const item of items) {
         if (item.action === "download") {
@@ -748,6 +890,11 @@ function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personal
             // can render a "N refused by policy" line independently of the
             // generic "N unchanged" tally.
         }
+        else if (item.action === "skip-out-of-scope") {
+            // Out-of-scope items get their own axis too, mirroring excluded-policy:
+            // they're "deliberately not downloaded (sync scope)", not "unchanged".
+            filesOutOfScope++;
+        }
         else {
             filesToSkip++;
         }
@@ -856,6 +1003,7 @@ function computePullPlan(remoteFiles, journal, companyRoot, shouldSync, personal
         newFiles,
         newFilesCount: newFiles.length,
         filesExcludedByPolicy,
+        filesOutOfScope,
         tombstones,
     };
 }