@indigoai-us/hq-cloud 5.22.0 → 5.23.0

package/dist/scope-shrink.js

@@ -0,0 +1,196 @@
+/**
+ * Scope-shrink detection + classification + clean removal (US-005).
+ *
+ * Implements the "hybrid scope-change contract" decided in US-000 Task 3
+ * (see companies/indigo/projects/hq-sync-browse-vs-sync/references.md):
+ *
+ *   - Compare the current pull's `prefixSet` against the last `PullRecord`'s
+ *     `prefixSet` for the same company. Files in the journal covered by the
+ *     previous scope but NOT covered by the new scope are **orphans**.
+ *   - Classify each orphan **clean** (safe to silently delete) or **dirty**
+ *     (locally modified — sacred, never silently delete).
+ *   - The remote-pull caller drives:
+ *       * default mode: abort the leg if any dirty orphan exists;
+ *       * `--force-scope-shrink`: continue, leave dirty files on disk,
+ *         tombstone their journal entries.
+ *
+ * The pure-detection layer here intentionally does NOT touch disk for the
+ * tombstone write — that lives in `journal.ts`. It DOES touch disk for the
+ * orphan classification (hash + stat) because cleanliness is a function of
+ * the file's current on-disk state vs the journal.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { hashFile, tombstoneEntry } from "./journal.js";
+import { isCoveredByAny } from "./prefix-coalesce.js";
+/**
+ * Build a scope-shrink plan: find orphans, classify each clean/dirty.
+ * Pure given the journal + filesystem state — no network, no journal
+ * mutation.
+ *
+ * **Tombstone-aware:** journal entries that already carry a `removedAt`
+ * marker are skipped — they represent a prior scope-shrink prune and must
+ * not be re-flagged as orphans on each subsequent pull (that's the whole
+ * point of the tombstone retention window).
+ *
+ * **Direction-aware:** only `direction: "down"` entries (and pre-ETag
+ * legacy entries without an explicit direction marker) participate in
+ * shrink detection. Push-only files (`direction: "up"`) represent local
+ * authorship — they aren't in scope-as-pulled, so a scope change doesn't
+ * orphan them.
+ */
+export function buildScopeShrinkPlan(input) {
+    const { journal, hqRoot, lastPrefixSet, currentPrefixSet } = input;
+    const orphans = [];
+    for (const [relPath, entry] of Object.entries(journal.files)) {
+        if (entry.removedAt)
+            continue; // tombstone — already pruned
+        if (entry.direction !== "down")
+            continue;
+        if (!isCoveredByAny(relPath, lastPrefixSet))
+            continue;
+        if (isCoveredByAny(relPath, currentPrefixSet))
+            continue;
+        orphans.push(classifyOrphan(relPath, entry, hqRoot));
+    }
+    const clean = orphans.filter((o) => o.clean);
+    const dirty = orphans.filter((o) => !o.clean);
+    return {
+        orphans,
+        clean,
+        dirty,
+        scopeChangeDetected: orphans.length > 0,
+    };
+}
+/**
+ * Classify a single orphan:
+ *
+ *   - **Clean** when:
+ *       * the local file is missing (already removed by the user — harmless), OR
+ *       * `sha256(localFile) === entry.hash` AND `stat.mtime ≤ entry.syncedAt`.
+ *   - **Dirty** otherwise.
+ *
+ * Symlinks: we don't re-hash with the symlink-target convention here —
+ * the safer default is to treat any symlink whose lstat exists but whose
+ * target hash doesn't match `entry.hash` (via `hashFile` reading the
+ * target) as dirty. In practice symlinks materialize through the same
+ * code path as files; a stale-target symlink is correctly flagged dirty
+ * and the operator-facing message points at the path either way.
+ */
+function classifyOrphan(relPath, entry, hqRoot) {
+    const absPath = path.join(hqRoot, relPath);
+    let stat;
+    try {
+        stat = fs.lstatSync(absPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return { path: relPath, entry, clean: true };
+        }
+        return {
+            path: relPath,
+            entry,
+            clean: false,
+            dirtyReason: "stat-error",
+        };
+    }
+    // mtime guard: a local edit moves mtime past syncedAt. We use ≤ because
+    // a download stamps syncedAt at the close of the write; mtime is set by
+    // the OS before that, so an unmodified pulled file has mtime ≤ syncedAt.
+    const mtimeMs = stat.mtimeMs;
+    const syncedAtMs = Date.parse(entry.syncedAt);
+    if (!Number.isNaN(syncedAtMs) && mtimeMs > syncedAtMs + 1000) {
+        // 1s grace for filesystem clock jitter.
+        return {
+            path: relPath,
+            entry,
+            clean: false,
+            dirtyReason: "modified-after-sync",
+        };
+    }
+    // Hash check — final word. If the content matches the journaled hash,
+    // the file is provably what the last pull left there.
+    let actualHash;
+    try {
+        actualHash = hashFile(absPath);
+    }
+    catch {
+        return {
+            path: relPath,
+            entry,
+            clean: false,
+            dirtyReason: "stat-error",
+        };
+    }
+    if (actualHash !== entry.hash) {
+        return {
+            path: relPath,
+            entry,
+            clean: false,
+            dirtyReason: "hash-mismatch",
+        };
+    }
+    return { path: relPath, entry, clean: true };
+}
+/**
+ * Structured error thrown when the engine refuses to proceed because a scope
+ * shrink would orphan dirty files. The CLI catches this and renders the
+ * operator-facing message; the engine never prints directly.
+ */
+export class ScopeShrinkBlockedError extends Error {
+    companyUid;
+    fromMode;
+    toMode;
+    dirty;
+    clean;
+    code = "SCOPE_SHRINK_BLOCKED";
+    constructor(companyUid, fromMode, toMode, dirty, clean) {
+        super(`Sync scope shrank for ${companyUid} (${fromMode} → ${toMode}); ` +
+            `${dirty.length} dirty file(s) outside the new scope would be ` +
+            `pruned from the journal. Resolve or pass --force-scope-shrink.`);
+        this.companyUid = companyUid;
+        this.fromMode = fromMode;
+        this.toMode = toMode;
+        this.dirty = dirty;
+        this.clean = clean;
+        this.name = "ScopeShrinkBlockedError";
+    }
+}
+/**
+ * Apply a scope-shrink plan: delete clean orphans on disk + tombstone their
+ * journal entries. With `forceScopeShrink: true`, dirty orphans are
+ * preserved on disk but their journal entries are also tombstoned.
+ *
+ * Returns counts for the audit log row (`scope_shrink_blocked` /
+ * `scope_shrink_forced`).
+ */
+export function applyScopeShrink(input) {
+    const { journal, plan, hqRoot, forceScopeShrink } = input;
+    const reason = input.reason ?? "scope_shrink";
+    let cleanRemoved = 0;
+    let dirtyTombstoned = 0;
+    for (const orphan of plan.clean) {
+        const absPath = path.join(hqRoot, orphan.path);
+        try {
+            fs.unlinkSync(absPath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err; // missing-on-disk is fine; anything else escalates
+        }
+        tombstoneEntry(journal, orphan.path, reason);
+        cleanRemoved++;
+    }
+    if (forceScopeShrink) {
+        for (const orphan of plan.dirty) {
+            // Do NOT delete the file — that's the entire point of the `--force`
+            // contract: keep dirty content on disk, prune only the journal entry.
+            tombstoneEntry(journal, orphan.path, reason);
+            dirtyTombstoned++;
+        }
+    }
+    return { cleanRemoved, dirtyTombstoned };
+}
+//# sourceMappingURL=scope-shrink.js.map

package/dist/scope-shrink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-shrink.js","sourceRoot":"","sources":["../src/scope-shrink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoCtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IACnE,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7D,IAAI,KAAK,CAAC,SAAS;YAAE,SAAS,CAAC,6BAA6B;QAC5D,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM;YAAE,SAAS;QACzC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC;YAAE,SAAS;QACtD,IAAI,cAAc,CAAC,OAAO,EAAE,gBAAgB,CAAC;YAAE,SAAS;QACxD,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO;QACL,OAAO;QACP,KAAK;QACL,KAAK;QACL,mBAAmB,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,cAAc,CACrB,OAAe,EACf,KAAmB,EACnB,MAAc;IAEd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,IAAc,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,YAAY;SAC1B,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,OAAO,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC;QAC7D,wCAAwC;QACxC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,qBAAqB;SACnC,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,sDAAsD;IACtD,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,YAAY;SAC1B,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,eAAe;SAC7B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAG9B;IACA;IACA;IACA;IACA;IANT,IAAI,GAAG,sBAAsB,CAAC;IACvC,YACkB,UAAkB,EAClB,QAA4C,EAC5C,MAA8B,EAC9B,KAA6B,EAC7B,KAA6B;QAE7C,KAAK,CACH,yBAAyB,UAAU,KAAK,QAAQ,MAAM,MAAM,KAAK;YAC/D,GAAG,KAAK,CAAC,MAAM,gDAAgD;YAC/D,gEAAgE,CACnE,CAAC;QAVc,eAAU,GAAV,UAAU,CAAQ;QAClB,aAAQ,GAAR,QAAQ,CAAoC;QAC5C,WAAM,GAAN,MAAM,CAAwB;QAC9B,UAAK,GAAL,KAAK,CAAwB;QAC7B,UAAK,GAAL,KAAK,CAAwB;QAO7C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAsBD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA4B;IAE5B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,cAAc,CAAC;IAC9C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC,CAAC,mDAAmD;QACvF,CAAC;QACD,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,YAAY,EAAE,CAAC;IACjB,CAAC;IAED,IAAI,gBAAgB,EAAE,CAAC;QACrB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,oEAAoE;YACpE,sEAAsE;YACtE,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7C,eAAe,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;AAC3C,CAAC"}

package/dist/scope-shrink.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Scope-shrink detection + classification + clean removal (US-005).
+ *
+ * Pins the hybrid-contract semantics decided in US-000 Task 3:
+ *   - orphans = (covered by last scope) ∧ ¬(covered by current scope)
+ *   - tombstones are NOT re-flagged on subsequent pulls
+ *   - clean orphan: local missing OR hash matches + mtime ≤ syncedAt
+ *   - dirty orphan: anything else
+ *   - applyScopeShrink deletes clean orphans, leaves dirty files alone
+ *     when `forceScopeShrink: true` but tombstones the journal entry
+ */
+export {};
+//# sourceMappingURL=scope-shrink.test.d.ts.map

package/dist/scope-shrink.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-shrink.test.d.ts","sourceRoot":"","sources":["../src/scope-shrink.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/scope-shrink.test.js

@@ -0,0 +1,342 @@
+/**
+ * Scope-shrink detection + classification + clean removal (US-005).
+ *
+ * Pins the hybrid-contract semantics decided in US-000 Task 3:
+ *   - orphans = (covered by last scope) ∧ ¬(covered by current scope)
+ *   - tombstones are NOT re-flagged on subsequent pulls
+ *   - clean orphan: local missing OR hash matches + mtime ≤ syncedAt
+ *   - dirty orphan: anything else
+ *   - applyScopeShrink deletes clean orphans, leaves dirty files alone
+ *     when `forceScopeShrink: true` but tombstones the journal entry
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as crypto from "crypto";
+import { buildScopeShrinkPlan, applyScopeShrink, ScopeShrinkBlockedError, } from "./scope-shrink.js";
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function emptyJournal() {
+    return { version: "2", lastSync: "", files: {}, pulls: [] };
+}
+describe("buildScopeShrinkPlan", () => {
+    let hqRoot;
+    beforeEach(() => {
+        hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-scope-shrink-"));
+    });
+    afterEach(() => {
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("returns empty plan when no orphans exist", () => {
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/meetings/a.md": {
+                    hash: "h",
+                    size: 1,
+                    syncedAt: "2026-05-01T00:00:00.000Z",
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/"],
+        });
+        expect(plan.orphans).toEqual([]);
+        expect(plan.scopeChangeDetected).toBe(false);
+    });
+    it("flags files covered by lastPrefixSet but not currentPrefixSet as orphans", () => {
+        const meetingsAbs = path.join(hqRoot, "companies/indigo/meetings/a.md");
+        const scratchAbs = path.join(hqRoot, "companies/indigo/scratch/jacob/draft.md");
+        fs.mkdirSync(path.dirname(meetingsAbs), { recursive: true });
+        fs.mkdirSync(path.dirname(scratchAbs), { recursive: true });
+        fs.writeFileSync(meetingsAbs, "meetings");
+        fs.writeFileSync(scratchAbs, "draft");
+        const now = new Date().toISOString();
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/meetings/a.md": {
+                    hash: sha256("meetings"),
+                    size: 8,
+                    syncedAt: now,
+                    direction: "down",
+                },
+                "companies/indigo/scratch/jacob/draft.md": {
+                    hash: sha256("draft"),
+                    size: 5,
+                    syncedAt: now,
+                    direction: "down",
+                },
+            },
+        };
+        // Backdate the scratch file so mtime ≤ syncedAt.
+        const past = Date.now() - 60_000;
+        fs.utimesSync(scratchAbs, past / 1000, past / 1000);
+        fs.utimesSync(meetingsAbs, past / 1000, past / 1000);
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.orphans.map((o) => o.path)).toEqual([
+            "companies/indigo/scratch/jacob/draft.md",
+        ]);
+        expect(plan.clean).toHaveLength(1);
+        expect(plan.dirty).toHaveLength(0);
+        expect(plan.scopeChangeDetected).toBe(true);
+    });
+    it("classifies a locally modified orphan as dirty (hash mismatch)", () => {
+        const abs = path.join(hqRoot, "companies/indigo/scratch/notes.md");
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, "ORIGINAL");
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/notes.md": {
+                    hash: sha256("DIFFERENT"), // doesn't match what's on disk
+                    size: 8,
+                    syncedAt: new Date().toISOString(),
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.dirty).toHaveLength(1);
+        expect(plan.dirty[0]?.dirtyReason).toBe("hash-mismatch");
+    });
+    it("classifies a recently mtime-touched file as dirty", () => {
+        const abs = path.join(hqRoot, "companies/indigo/scratch/notes.md");
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, "ORIGINAL");
+        const syncedAt = new Date(Date.now() - 60_000).toISOString();
+        // Touch mtime forward, well past syncedAt + 1s grace.
+        const future = Date.now() + 10_000;
+        fs.utimesSync(abs, future / 1000, future / 1000);
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/notes.md": {
+                    hash: sha256("ORIGINAL"), // hash matches, but mtime is forward
+                    size: 8,
+                    syncedAt,
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.dirty).toHaveLength(1);
+        expect(plan.dirty[0]?.dirtyReason).toBe("modified-after-sync");
+    });
+    it("treats a locally-missing orphan as clean (already removed by user)", () => {
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/gone.md": {
+                    hash: sha256("gone"),
+                    size: 4,
+                    syncedAt: new Date().toISOString(),
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.clean).toHaveLength(1);
+        expect(plan.clean[0]?.path).toBe("companies/indigo/scratch/gone.md");
+    });
+    it("skips tombstoned entries (do not re-flag on subsequent pulls)", () => {
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/already.md": {
+                    hash: "h",
+                    size: 1,
+                    syncedAt: "2026-05-01T00:00:00.000Z",
+                    direction: "down",
+                    removedAt: "2026-05-02T00:00:00.000Z",
+                    removedReason: "scope_shrink",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.orphans).toEqual([]);
+    });
+    it("skips push-only entries (direction: 'up')", () => {
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/local-only.md": {
+                    hash: "h",
+                    size: 1,
+                    syncedAt: "2026-05-01T00:00:00.000Z",
+                    direction: "up",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        expect(plan.orphans).toEqual([]);
+    });
+});
+describe("applyScopeShrink", () => {
+    let hqRoot;
+    beforeEach(() => {
+        hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-scope-shrink-apply-"));
+    });
+    afterEach(() => {
+        fs.rmSync(hqRoot, { recursive: true, force: true });
+    });
+    it("deletes clean orphans on disk + tombstones their journal entries", () => {
+        const abs = path.join(hqRoot, "companies/indigo/scratch/clean.md");
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, "clean");
+        const syncedAt = new Date().toISOString();
+        const past = Date.now() - 60_000;
+        fs.utimesSync(abs, past / 1000, past / 1000);
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/clean.md": {
+                    hash: sha256("clean"),
+                    size: 5,
+                    syncedAt,
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        const result = applyScopeShrink({
+            journal,
+            plan,
+            hqRoot,
+            forceScopeShrink: false,
+        });
+        expect(result.cleanRemoved).toBe(1);
+        expect(result.dirtyTombstoned).toBe(0);
+        expect(fs.existsSync(abs)).toBe(false);
+        expect(journal.files["companies/indigo/scratch/clean.md"]?.removedAt).toBeTruthy();
+        expect(journal.files["companies/indigo/scratch/clean.md"]?.removedReason).toBe("scope_shrink");
+    });
+    it("leaves dirty files on disk when forceScopeShrink: true, but tombstones the entry", () => {
+        const abs = path.join(hqRoot, "companies/indigo/scratch/dirty.md");
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, "MODIFIED");
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/dirty.md": {
+                    hash: sha256("ORIGINAL"), // mismatch — dirty
+                    size: 8,
+                    syncedAt: new Date().toISOString(),
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        const result = applyScopeShrink({
+            journal,
+            plan,
+            hqRoot,
+            forceScopeShrink: true,
+        });
+        expect(result.dirtyTombstoned).toBe(1);
+        expect(fs.existsSync(abs)).toBe(true); // PRESERVED
+        expect(fs.readFileSync(abs, "utf-8")).toBe("MODIFIED");
+        expect(journal.files["companies/indigo/scratch/dirty.md"]?.removedAt).toBeTruthy();
+    });
+    it("accepts a custom reason for the tombstone (e.g. narrow_apply)", () => {
+        const abs = path.join(hqRoot, "companies/indigo/scratch/clean.md");
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, "x");
+        const past = Date.now() - 60_000;
+        fs.utimesSync(abs, past / 1000, past / 1000);
+        const journal = {
+            ...emptyJournal(),
+            files: {
+                "companies/indigo/scratch/clean.md": {
+                    hash: sha256("x"),
+                    size: 1,
+                    syncedAt: new Date().toISOString(),
+                    direction: "down",
+                },
+            },
+        };
+        const plan = buildScopeShrinkPlan({
+            journal,
+            hqRoot,
+            lastPrefixSet: ["companies/indigo/"],
+            currentPrefixSet: ["companies/indigo/meetings/"],
+        });
+        applyScopeShrink({
+            journal,
+            plan,
+            hqRoot,
+            forceScopeShrink: false,
+            reason: "narrow_apply",
+        });
+        expect(journal.files["companies/indigo/scratch/clean.md"]?.removedReason).toBe("narrow_apply");
+    });
+});
+describe("ScopeShrinkBlockedError", () => {
+    it("carries from/to syncMode + dirty/clean orphan lists for the CLI", () => {
+        const err = new ScopeShrinkBlockedError("cmp_indigo", "all", "shared", [
+            {
+                path: "companies/indigo/scratch/notes.md",
+                entry: {
+                    hash: "h",
+                    size: 1,
+                    syncedAt: "",
+                    direction: "down",
+                },
+                clean: false,
+                dirtyReason: "hash-mismatch",
+            },
+        ], []);
+        expect(err.code).toBe("SCOPE_SHRINK_BLOCKED");
+        expect(err.fromMode).toBe("all");
+        expect(err.toMode).toBe("shared");
+        expect(err.dirty).toHaveLength(1);
+        expect(err.name).toBe("ScopeShrinkBlockedError");
+    });
+});
+//# sourceMappingURL=scope-shrink.test.js.map

package/dist/scope-shrink.test.js.map

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

package/dist/types.d.ts

@@ -31,11 +31,58 @@ export interface JournalEntry {
      * against `syncedAt`.
      */
     remoteEtag?: string;
+    /**
+     * Tombstone marker (Journal v2, US-005). When set, this entry represents
+     * a file that was pruned by a scope shrink — either implicitly (next pull
+     * after the membership's effective scope narrowed) or explicitly (via
+     * `hq sync narrow --apply`). Tombstones are kept for `TOMBSTONE_TTL_MS`
+     * (30d) so subsequent pulls under the same shrunk scope don't re-flag
+     * the same paths as orphans, then garbage-collected.
+     */
+    removedAt?: string;
+    removedReason?: "scope_shrink" | "narrow_apply" | "manual";
+}
+/**
+ * Per-pull boundary record (Journal v2, US-005).
+ *
+ * Recorded at the end of every per-company sync leg so the next pull can
+ * detect "scope changed" against `prefixSet` and compute orphans
+ * deterministically. `pulls[]` is append-only; old records are not pruned
+ * (cheap, useful for incident forensics — one row per pull per company).
+ */
+export interface PullRecord {
+    /** ULID-shaped id (crockford base32, lexically sortable). */
+    pullId: string;
+    companyUid: string;
+    startedAt: string;
+    completedAt: string;
+    /** Effective sync-mode at pull start. */
+    syncMode: "all" | "shared" | "custom";
+    /**
+     * Coalesced prefixes used to drive ListObjectsV2 for this pull. Empty for
+     * v1-migrated records (no recorded scope; treated as full-bucket "all").
+     */
+    prefixSet: string[];
+    scopeChangeDetected: boolean;
+    orphansRemoved: number;
+    orphansBlocked: number;
 }
 export interface SyncJournal {
-    version: "1";
+    /**
+     * Schema version. `"1"` is the pre-US-005 shape (no `pulls`, no
+     * tombstone fields on entries). `"2"` adds per-pull records and
+     * tombstone markers; readers MUST tolerate either and migrate v1 → v2
+     * in place on the first v2 write.
+     */
+    version: "1" | "2";
     lastSync: string;
     files: Record<string, JournalEntry>;
+    /**
+     * Per-pull boundary records (v2 only). Always present on v2 journals.
+     * v1 journals do not carry this field — readers should treat absence as
+     * "no recorded history; treat last scope as 'all'/empty".
+     */
+    pulls?: PullRecord[];
 }
 export interface SyncStatus {
     running: boolean;

package/dist/types.d.ts.map

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